feat(core, tests): add standalone getStatistics function and improve storage configuration

- **Core**: Introduced a new `getStatistics` utility function in `statistics.ts` for fetching database statistics at the root level of the library. Enhanced `BrainyData` methods to ensure metadata includes `id` field and refined statistics calculations, excluding verbs from the noun count.
- **Tests**: Added comprehensive test coverage in `statistics.test.ts` for the new utility function, validating proper error handling, statistics accuracy, and consistent results between instance methods and standalone function.
- **Storage Config**: Enabled dynamic support for AWS S3, Cloudflare R2, and Google Cloud Storage in web service configuration, utilizing environment variables for adapter setup. Addressed a race condition in `FileSystemStorage` initialization by deferring path module imports.

**Purpose**: Enhance database analytics by introducing a reusable `getStatistics` function, improve flexibility in storage configuration, and ensure robust testing for reliability and accuracy.
This commit is contained in:
David Snelling 2025-07-23 16:26:59 -07:00
parent b8f10ba39a
commit 2322b53a0c
13 changed files with 346 additions and 61 deletions

View file

@ -488,6 +488,32 @@ const backupData = await db.backup()
const restoreResult = await db.restore(backupData, {clearExisting: true})
```
### Database Statistics
Brainy provides a way to get statistics about the current state of the database:
```typescript
import { BrainyData, getStatistics } from '@soulcraft/brainy'
// Create and initialize the database
const db = new BrainyData()
await db.init()
// Get statistics using the standalone function
const stats = await getStatistics(db)
console.log(stats)
// Output: { nounCount: 0, verbCount: 0, metadataCount: 0, hnswIndexSize: 0 }
// Or using the instance method
const instanceStats = await db.getStatistics()
```
The statistics include:
- `nounCount`: Number of nouns (entities) in the database
- `verbCount`: Number of verbs (relationships) in the database
- `metadataCount`: Number of metadata entries
- `hnswIndexSize`: Size of the HNSW index
### Working with Nouns (Entities)
```typescript