@soulcraft/brainy 4.1.2 → 4.1.3

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [4.1.3](https://github.com/soulcraftlabs/brainy/compare/v4.1.2...v4.1.3) (2025-10-21)
+
+- perf: make getRelations() pagination consistent and efficient (54d819c)
+- fix: resolve getRelations() empty array bug and add string ID shorthand (8d217f3)
+
+
+### [4.1.3](https://github.com/soulcraftlabs/brainy/compare/v4.1.2...v4.1.3) (2025-10-21)
+
+
+### 🐛 Bug Fixes
+
+* **api**: fix getRelations() returning empty array when called without parameters
+  - Fixed critical bug where `brain.getRelations()` returned `[]` instead of all relationships
+  - Added support for retrieving all relationships with pagination (default limit: 100)
+  - Added string ID shorthand syntax: `brain.getRelations(entityId)` as alias for `brain.getRelations({ from: entityId })`
+  - **Performance**: Made pagination consistent - now ALL query patterns paginate at storage layer
+  - **Efficiency**: `getRelations({ from: id, limit: 10 })` now fetches only 10 instead of fetching ALL then slicing
+  - Fixed storage.getVerbs() offset handling - now properly converts offset to cursor for adapters
+  - Production safety: Warns when fetching >10k relationships without filters
+  - Fixed broken method calls in improvedNeuralAPI.ts (replaced non-existent `getVerbsForNoun` with `getRelations`)
+  - Fixed property access bugs: `verb.target` → `verb.to`, `verb.verb` → `verb.type`
+  - Added comprehensive integration tests (14 tests covering all query patterns)
+  - Updated JSDoc documentation with usage examples
+  - **Impact**: Resolves Workshop team bug where 524 imported relationships were inaccessible
+  - **Breaking**: None - fully backward compatible
+
 ### [4.1.2](https://github.com/soulcraftlabs/brainy/compare/v4.1.1...v4.1.2) (2025-10-21)
 
 

package/dist/brainy.d.ts

@@ -314,9 +314,38 @@ export declare class Brainy<T = any> implements BrainyInterface<T> {
      */
     unrelate(id: string): Promise<void>;
     /**
-     * Get relationships
+     * Get relationships between entities
+     *
+     * Supports multiple query patterns:
+     * - No parameters: Returns all relationships (paginated, default limit: 100)
+     * - String ID: Returns relationships from that entity (shorthand for { from: id })
+     * - Parameters object: Fine-grained filtering and pagination
+     *
+     * @param paramsOrId - Optional string ID or parameters object
+     * @returns Promise resolving to array of relationships
+     *
+     * @example
+     * ```typescript
+     * // Get all relationships (first 100)
+     * const all = await brain.getRelations()
+     *
+     * // Get relationships from specific entity (shorthand syntax)
+     * const fromEntity = await brain.getRelations(entityId)
+     *
+     * // Get relationships with filters
+     * const filtered = await brain.getRelations({
+     *   type: VerbType.FriendOf,
+     *   limit: 50
+     * })
+     *
+     * // Pagination
+     * const page2 = await brain.getRelations({ offset: 100, limit: 100 })
+     * ```
+     *
+     * @since v4.1.3 - Fixed bug where calling without parameters returned empty array
+     * @since v4.1.3 - Added string ID shorthand syntax: getRelations(id)
      */
-    getRelations(params?: GetRelationsParams): Promise<Relation<T>[]>;
+    getRelations(paramsOrId?: string | GetRelationsParams): Promise<Relation<T>[]>;
     /**
      * Unified find method - supports natural language and structured queries
      * Implements Triple Intelligence with parallel search optimization

package/dist/brainy.js

@@ -719,33 +719,75 @@ export class Brainy {
         });
     }
     /**
-     * Get relationships
+     * Get relationships between entities
+     *
+     * Supports multiple query patterns:
+     * - No parameters: Returns all relationships (paginated, default limit: 100)
+     * - String ID: Returns relationships from that entity (shorthand for { from: id })
+     * - Parameters object: Fine-grained filtering and pagination
+     *
+     * @param paramsOrId - Optional string ID or parameters object
+     * @returns Promise resolving to array of relationships
+     *
+     * @example
+     * ```typescript
+     * // Get all relationships (first 100)
+     * const all = await brain.getRelations()
+     *
+     * // Get relationships from specific entity (shorthand syntax)
+     * const fromEntity = await brain.getRelations(entityId)
+     *
+     * // Get relationships with filters
+     * const filtered = await brain.getRelations({
+     *   type: VerbType.FriendOf,
+     *   limit: 50
+     * })
+     *
+     * // Pagination
+     * const page2 = await brain.getRelations({ offset: 100, limit: 100 })
+     * ```
+     *
+     * @since v4.1.3 - Fixed bug where calling without parameters returned empty array
+     * @since v4.1.3 - Added string ID shorthand syntax: getRelations(id)
      */
-    async getRelations(params = {}) {
+    async getRelations(paramsOrId) {
         await this.ensureInitialized();
-        const relations = [];
+        // Handle string ID shorthand: getRelations(id) -> getRelations({ from: id })
+        const params = typeof paramsOrId === 'string'
+            ? { from: paramsOrId }
+            : (paramsOrId || {});
+        const limit = params.limit || 100;
+        const offset = params.offset || 0;
+        // Production safety: warn for large unfiltered queries
+        if (!params.from && !params.to && !params.type && limit > 10000) {
+            console.warn(`[Brainy] getRelations(): Fetching ${limit} relationships without filters. ` +
+                `Consider adding 'from', 'to', or 'type' filter for better performance.`);
+        }
+        // Build filter for storage query
+        const filter = {};
         if (params.from) {
-            const verbs = await this.storage.getVerbsBySource(params.from);
-            relations.push(...this.verbsToRelations(verbs));
+            filter.sourceId = params.from;
         }
         if (params.to) {
-            const verbs = await this.storage.getVerbsByTarget(params.to);
-            relations.push(...this.verbsToRelations(verbs));
+            filter.targetId = params.to;
         }
-        // Filter by type
-        let filtered = relations;
         if (params.type) {
-            const types = Array.isArray(params.type) ? params.type : [params.type];
-            filtered = relations.filter((r) => types.includes(r.type));
+            filter.verbType = Array.isArray(params.type) ? params.type : [params.type];
         }
-        // Filter by service
         if (params.service) {
-            filtered = filtered.filter((r) => r.service === params.service);
-        }
-        // Apply pagination
-        const limit = params.limit || 100;
-        const offset = params.offset || 0;
-        return filtered.slice(offset, offset + limit);
+            filter.service = params.service;
+        }
+        // Fetch from storage with pagination at storage layer (efficient!)
+        const result = await this.storage.getVerbs({
+            pagination: {
+                limit,
+                offset,
+                cursor: params.cursor
+            },
+            filter: Object.keys(filter).length > 0 ? filter : undefined
+        });
+        // Convert to Relation format
+        return this.verbsToRelations(result.items);
     }
     // ============= SEARCH & DISCOVERY =============
     /**

package/dist/neural/improvedNeuralAPI.js

@@ -1310,14 +1310,14 @@ export class ImprovedNeuralAPI {
         for (const sourceId of itemIds) {
             const sourceVerbs = await this.brain.getRelations(sourceId);
             for (const verb of sourceVerbs) {
-                const targetId = verb.target;
+                const targetId = verb.to;
                 if (nodes.has(targetId) && sourceId !== targetId) {
                     // Initialize edge map if needed
                     if (!edges.has(sourceId)) {
                         edges.set(sourceId, new Map());
                     }
                     // Calculate edge weight from verb type and metadata
-                    const verbType = verb.verb;
+                    const verbType = verb.type;
                     const baseWeight = relationshipWeights[verbType] || 0.5;
                     const confidenceWeight = verb.confidence || 1.0;
                     const weight = baseWeight * confidenceWeight;
@@ -2743,7 +2743,7 @@ export class ImprovedNeuralAPI {
         const sampleSize = Math.min(50, itemIds.length);
         for (let i = 0; i < sampleSize; i++) {
             try {
-                const verbs = await this.brain.getVerbsForNoun(itemIds[i]);
+                const verbs = await this.brain.getRelations({ from: itemIds[i] });
                 connectionCount += verbs.length;
             }
             catch (error) {
@@ -2797,9 +2797,9 @@ export class ImprovedNeuralAPI {
                 if (fromType !== toType) {
                     for (const fromItem of fromItems.slice(0, 10)) { // Sample to avoid N^2
                         try {
-                            const verbs = await this.brain.getVerbsForNoun(fromItem.id);
+                            const verbs = await this.brain.getRelations({ from: fromItem.id });
                             for (const verb of verbs) {
-                                const toItem = toItems.find(item => item.id === verb.target);
+                                const toItem = toItems.find(item => item.id === verb.to);
                                 if (toItem) {
                                     connections.push({
                                         from: fromItem.id,

package/dist/storage/baseStorage.js

@@ -600,13 +600,15 @@ export class BaseStorage extends BaseStorageAdapter {
             // Check if the adapter has a paginated method for getting verbs
             if (typeof this.getVerbsWithPagination === 'function') {
                 // Use the adapter's paginated method
+                // Convert offset to cursor if no cursor provided (adapters use cursor for offset)
+                const effectiveCursor = cursor || (offset > 0 ? offset.toString() : undefined);
                 const result = await this.getVerbsWithPagination({
                     limit,
-                    cursor,
+                    cursor: effectiveCursor,
                     filter: options?.filter
                 });
-                // Apply offset if needed (some adapters might not support offset)
-                const items = result.items.slice(offset);
+                // Items are already offset by the adapter via cursor, no need to slice
+                const items = result.items;
                 // CRITICAL SAFETY CHECK: Prevent infinite loops
                 // If we have no items but hasMore is true, force hasMore to false
                 // This prevents pagination bugs from causing infinite loops

package/dist/types/brainy.types.d.ts

@@ -172,14 +172,83 @@ export interface SimilarParams<T = any> {
 }
 /**
  * Parameters for getting relationships
+ *
+ * All parameters are optional. When called without parameters, returns all relationships
+ * with pagination (default limit: 100).
+ *
+ * @example
+ * ```typescript
+ * // Get all relationships (default limit: 100)
+ * const all = await brain.getRelations()
+ *
+ * // Get relationships from a specific entity (string shorthand)
+ * const fromEntity = await brain.getRelations(entityId)
+ *
+ * // Equivalent to:
+ * const fromEntity2 = await brain.getRelations({ from: entityId })
+ *
+ * // Get relationships to a specific entity
+ * const toEntity = await brain.getRelations({ to: entityId })
+ *
+ * // Filter by relationship type
+ * const friends = await brain.getRelations({ type: VerbType.FriendOf })
+ *
+ * // Pagination
+ * const page2 = await brain.getRelations({ offset: 100, limit: 50 })
+ *
+ * // Combined filters
+ * const filtered = await brain.getRelations({
+ *   from: entityId,
+ *   type: VerbType.WorksWith,
+ *   limit: 20
+ * })
+ * ```
+ *
+ * @since v4.1.3 - Fixed bug where calling without parameters returned empty array
+ * @since v4.1.3 - Added string ID shorthand syntax
  */
 export interface GetRelationsParams {
+    /**
+     * Filter by source entity ID
+     *
+     * Returns all relationships originating from this entity.
+     */
     from?: string;
+    /**
+     * Filter by target entity ID
+     *
+     * Returns all relationships pointing to this entity.
+     */
     to?: string;
+    /**
+     * Filter by relationship type(s)
+     *
+     * Can be a single VerbType or array of VerbTypes.
+     */
     type?: VerbType | VerbType[];
+    /**
+     * Maximum number of results to return
+     *
+     * @default 100
+     */
     limit?: number;
+    /**
+     * Number of results to skip (offset-based pagination)
+     *
+     * @default 0
+     */
     offset?: number;
+    /**
+     * Cursor for cursor-based pagination
+     *
+     * More efficient than offset for large result sets.
+     */
     cursor?: string;
+    /**
+     * Filter by service (multi-tenancy)
+     *
+     * Only return relationships belonging to this service.
+     */
     service?: string;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "4.1.2",
+  "version": "4.1.3",
   "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",