**feat(examples, core, docs): add flushStatistics example, implementation, and documentation**

- **Examples**: Added a new `flush-statistics-example.js` script to demonstrate the usage of the `flushStatistics` method for ensuring updated statistics after data insertion.
- **Core**:
  - Implemented `flushStatistics` in the `BrainyData` class to allow immediate flushing of statistics to storage.
  - Updated `BaseStorageAdapter` with `flushStatisticsToStorage` to support flushing cached statistics.
  - Modified the `shutDown` method to ensure statistics are flushed before database shutdown.
- **Documentation**: Added `statistics-flush-solution.md` to explain the batch update mechanism, the issue with delayed statistics updates, and how to manually flush statistics in storage.

**Purpose**: Provide users with the ability to manually flush statistics for real-time accuracy, particularly useful for systems relying on immediate updates. Improved documentation and examples to guide developers in implementing and using this functionality effectively.

src/brainyData.ts

@@ -1880,6 +1880,22 @@ export class BrainyData<T = any> implements BrainyDataInterface<T> {
         return nounCount
     }
 
+    /**
+     * Force an immediate flush of statistics to storage
+     * This ensures that any pending statistics updates are written to persistent storage
+     * @returns Promise that resolves when the statistics have been flushed
+     */
+    public async flushStatistics(): Promise<void> {
+        await this.ensureInitialized()
+
+        if (!this.storage) {
+            throw new Error('Storage not initialized')
+        }
+
+        // Call the flushStatisticsToStorage method on the storage adapter
+        await this.storage.flushStatisticsToStorage()
+    }
+
     /**
      * Get statistics about the current state of the database
      * @param options Additional options for retrieving statistics
@@ -2649,6 +2665,16 @@ export class BrainyData<T = any> implements BrainyDataInterface<T> {
      */
     public async shutDown(): Promise<void> {
         try {
+            // Flush statistics to ensure they're saved before shutting down
+            if (this.storage && this.isInitialized) {
+                try {
+                    await this.flushStatistics()
+                } catch (statsError) {
+                    console.warn('Failed to flush statistics during shutdown:', statsError)
+                    // Continue with shutdown even if statistics flush fails
+                }
+            }
+
             // Disconnect from remote server if connected
             if (this.isConnectedToRemoteServer()) {
                 await this.disconnectFromRemoteServer()

src/coreTypes.ts

@@ -229,4 +229,10 @@ export interface StorageAdapter {
    * @param size The new size of the HNSW index
    */
   updateHnswIndexSize(size: number): Promise<void>
+
+  /**
+   * Force an immediate flush of statistics to storage
+   * This ensures that any pending statistics updates are written to persistent storage
+   */
+  flushStatisticsToStorage(): Promise<void>
 }

src/storage/adapters/baseStorageAdapter.ts

@@ -290,6 +290,20 @@ export abstract class BaseStorageAdapter implements StorageAdapter {
     this.scheduleBatchUpdate()
   }
 
+  /**
+   * Force an immediate flush of statistics to storage
+   * This ensures that any pending statistics updates are written to persistent storage
+   */
+  async flushStatisticsToStorage(): Promise<void> {
+    // If there are no statistics in cache or they haven't been modified, nothing to flush
+    if (!this.statisticsCache || !this.statisticsModified) {
+      return
+    }
+
+    // Call the protected flushStatistics method to immediately write to storage
+    await this.flushStatistics()
+  }
+
   /**
    * Create default statistics data
    * @returns Default statistics data