@soulcraft/brainy 2.14.0 → 2.14.2

package/dist/storage/adapters/baseStorageAdapter.d.ts

@@ -75,6 +75,48 @@ export declare abstract class BaseStorageAdapter implements StorageAdapter {
         hasMore: boolean;
         nextCursor?: string;
     }>;
+    /**
+     * Get nouns with pagination (internal implementation)
+     * This method should be implemented by storage adapters to support efficient pagination
+     * @param options Pagination options
+     * @returns Promise that resolves to a paginated result of nouns
+     */
+    getNounsWithPagination?(options: {
+        limit?: number;
+        cursor?: string;
+        filter?: {
+            nounType?: string | string[];
+            service?: string | string[];
+            metadata?: Record<string, any>;
+        };
+    }): Promise<{
+        items: any[];
+        totalCount?: number;
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
+    /**
+     * Get verbs with pagination (internal implementation)
+     * This method should be implemented by storage adapters to support efficient pagination
+     * @param options Pagination options
+     * @returns Promise that resolves to a paginated result of verbs
+     */
+    getVerbsWithPagination?(options: {
+        limit?: number;
+        cursor?: string;
+        filter?: {
+            verbType?: string | string[];
+            sourceId?: string | string[];
+            targetId?: string | string[];
+            service?: string | string[];
+            metadata?: Record<string, any>;
+        };
+    }): Promise<{
+        items: any[];
+        totalCount?: number;
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
     protected statisticsCache: StatisticsData | null;
     protected statisticsBatchUpdateTimerId: NodeJS.Timeout | null;
     protected statisticsModified: boolean;

package/dist/storage/adapters/fileSystemStorage.d.ts

@@ -189,6 +189,26 @@ export declare class FileSystemStorage extends BaseStorage {
      * Get verbs by type
      */
     protected getVerbsByType_internal(type: string): Promise<GraphVerb[]>;
+    /**
+     * Get verbs with pagination
+     * This method reads verb files from the filesystem and returns them with pagination
+     */
+    getVerbsWithPagination(options?: {
+        limit?: number;
+        cursor?: string;
+        filter?: {
+            verbType?: string | string[];
+            sourceId?: string | string[];
+            targetId?: string | string[];
+            service?: string | string[];
+            metadata?: Record<string, any>;
+        };
+    }): Promise<{
+        items: GraphVerb[];
+        totalCount?: number;
+        hasMore: boolean;
+        nextCursor?: string;
+    }>;
     /**
      * Delete a verb from storage
      */

package/dist/storage/adapters/fileSystemStorage.js

@@ -793,6 +793,103 @@ export class FileSystemStorage extends BaseStorage {
         console.warn('getVerbsByType_internal is deprecated and not efficiently supported in new storage pattern');
         return [];
     }
+    /**
+     * Get verbs with pagination
+     * This method reads verb files from the filesystem and returns them with pagination
+     */
+    async getVerbsWithPagination(options = {}) {
+        await this.ensureInitialized();
+        const limit = options.limit || 100;
+        const startIndex = options.cursor ? parseInt(options.cursor, 10) : 0;
+        try {
+            // List all verb files in the verbs directory
+            // Note: For very large directories (millions of files), this could be memory-intensive
+            // Future optimization: Use fs.opendir() for streaming directory reads
+            const files = await fs.promises.readdir(this.verbsDir);
+            const verbFiles = files.filter((f) => f.endsWith('.json'));
+            // Sort files for consistent ordering
+            verbFiles.sort();
+            // Calculate pagination
+            const totalCount = verbFiles.length;
+            const endIndex = Math.min(startIndex + limit, totalCount);
+            const hasMore = endIndex < totalCount;
+            // Safety check for large datasets
+            if (totalCount > 100000) {
+                console.warn(`Large verb dataset detected (${totalCount} verbs). Consider using a database for better performance.`);
+            }
+            // Load the requested page of verbs
+            const verbs = [];
+            for (let i = startIndex; i < endIndex; i++) {
+                const file = verbFiles[i];
+                const id = file.replace('.json', '');
+                try {
+                    // Read the verb data
+                    const filePath = path.join(this.verbsDir, file);
+                    const data = await fs.promises.readFile(filePath, 'utf-8');
+                    const edge = JSON.parse(data);
+                    // Also try to get metadata if it exists
+                    const metadata = await this.getVerbMetadata(id);
+                    // Convert to GraphVerb format
+                    const verb = {
+                        id: edge.id,
+                        source: metadata?.source || '',
+                        target: metadata?.target || '',
+                        type: metadata?.type || 'relationship',
+                        ...(metadata || {})
+                    };
+                    // Apply filters if provided
+                    if (options.filter) {
+                        const filter = options.filter;
+                        // Check verbType filter
+                        if (filter.verbType) {
+                            const types = Array.isArray(filter.verbType) ? filter.verbType : [filter.verbType];
+                            if (!types.includes(verb.type || ''))
+                                continue;
+                        }
+                        // Check sourceId filter
+                        if (filter.sourceId) {
+                            const sources = Array.isArray(filter.sourceId) ? filter.sourceId : [filter.sourceId];
+                            if (!sources.includes(verb.source || ''))
+                                continue;
+                        }
+                        // Check targetId filter
+                        if (filter.targetId) {
+                            const targets = Array.isArray(filter.targetId) ? filter.targetId : [filter.targetId];
+                            if (!targets.includes(verb.target || ''))
+                                continue;
+                        }
+                        // Check service filter
+                        if (filter.service && metadata?.service) {
+                            const services = Array.isArray(filter.service) ? filter.service : [filter.service];
+                            if (!services.includes(metadata.service))
+                                continue;
+                        }
+                    }
+                    verbs.push(verb);
+                }
+                catch (error) {
+                    console.warn(`Failed to read verb ${id}:`, error);
+                }
+            }
+            return {
+                items: verbs,
+                totalCount,
+                hasMore,
+                nextCursor: hasMore ? String(endIndex) : undefined
+            };
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // Verbs directory doesn't exist yet
+                return {
+                    items: [],
+                    totalCount: 0,
+                    hasMore: false
+                };
+            }
+            throw error;
+        }
+    }
     /**
      * Delete a verb from storage
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "2.14.0",
+  "version": "2.14.2",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",