ai-database 2.1.1 → 2.3.0

package/dist/ai-promise-db.js

@@ -21,6 +21,8 @@
  * @packageDocumentation
  */
 import { Semaphore } from './memory-provider.js';
+import { isEntityArray, extractEntityId, extractMarkerType, isPlainObject, hasRelationElements, asCallback, asPredicate, asComparator, getSymbolProperty, asItem, } from './type-guards.js';
+import { EntityNotFoundError } from './errors.js';
 // Provider resolver - will be set by schema.ts
 let providerResolver = null;
 /**
@@ -146,7 +148,7 @@ export class DBPromise {
     map(callback) {
         const parentPromise = this;
         return new DBPromise({
-            type: this._options.type,
+            ...(this._options.type !== undefined && { type: this._options.type }),
             executor: async () => {
                 // Resolve the parent array
                 const items = await parentPromise.resolve();
@@ -165,8 +167,9 @@ export class DBPromise {
                     // Create a recording proxy for this item
                     const recordingProxy = createRecordingProxy(item, recording);
                     // Execute callback with recording proxy to discover accesses
+                    // Use asCallback to convert the callback to accept unknown items
                     try {
-                        callback(recordingProxy, i);
+                        asCallback(callback)(recordingProxy, i);
                     }
                     catch {
                         // Ignore errors during recording phase - they'll surface in Phase 3
@@ -182,9 +185,11 @@ export class DBPromise {
                     enrichedItems.push(enrichItemWithLoadedRelations(items[i], loadedRelations));
                 }
                 // Execute callback again with enriched data
+                // Use asCallback to convert the callback to accept unknown items
                 const results = [];
+                const typedCallback = asCallback(callback);
                 for (let i = 0; i < enrichedItems.length; i++) {
-                    results.push(callback(enrichedItems[i], i));
+                    results.push(typedCallback(enrichedItems[i], i));
                 }
                 return results;
             },
@@ -196,13 +201,14 @@ export class DBPromise {
     filter(predicate) {
         const parentPromise = this;
         return new DBPromise({
-            type: this._options.type,
+            ...(this._options.type !== undefined && { type: this._options.type }),
             executor: async () => {
                 const items = await parentPromise.resolve();
                 if (!Array.isArray(items)) {
                     return items;
                 }
-                return items.filter(predicate);
+                // Use asPredicate to convert the predicate to accept unknown items
+                return items.filter(asPredicate(predicate));
             },
         });
     }
@@ -212,13 +218,14 @@ export class DBPromise {
     sort(compareFn) {
         const parentPromise = this;
         return new DBPromise({
-            type: this._options.type,
+            ...(this._options.type !== undefined && { type: this._options.type }),
             executor: async () => {
                 const items = await parentPromise.resolve();
                 if (!Array.isArray(items)) {
                     return items;
                 }
-                return [...items].sort(compareFn);
+                // Use asComparator to convert the compareFn to accept unknown items
+                return [...items].sort(asComparator(compareFn));
             },
         });
     }
@@ -228,7 +235,7 @@ export class DBPromise {
     limit(n) {
         const parentPromise = this;
         return new DBPromise({
-            type: this._options.type,
+            ...(this._options.type !== undefined && { type: this._options.type }),
             executor: async () => {
                 const items = await parentPromise.resolve();
                 if (!Array.isArray(items)) {
@@ -244,7 +251,7 @@ export class DBPromise {
     first() {
         const parentPromise = this;
         return new DBPromise({
-            type: this._options.type,
+            ...(this._options.type !== undefined && { type: this._options.type }),
             executor: async () => {
                 const items = await parentPromise.resolve();
                 if (Array.isArray(items)) {
@@ -300,7 +307,7 @@ export class DBPromise {
         // Persistence state
         let processedIds = new Set();
         let persistCounter = 0;
-        const getItemId = (item) => item?.$id ?? item?.id ?? String(item);
+        const getItemId = (item) => extractEntityId(item) ?? String(item);
         // Get actions API from options (injected by wrapEntityOperations)
         const actionsAPI = this._options.actionsAPI;
         // Initialize persistence if enabled
@@ -319,7 +326,7 @@ export class DBPromise {
                     await actionsAPI.update(actionId, { status: 'active' });
                 }
                 else {
-                    throw new Error(`Action ${resume} not found`);
+                    throw new EntityNotFoundError('Action', resume, 'resume');
                 }
             }
             else {
@@ -355,7 +362,7 @@ export class DBPromise {
                 skipped,
                 current,
                 elapsed,
-                remaining,
+                ...(remaining !== undefined && { remaining }),
                 rate,
             };
         };
@@ -377,10 +384,10 @@ export class DBPromise {
         const getRetryDelay = (attempt) => {
             return typeof retryDelay === 'function' ? retryDelay(attempt) : retryDelay;
         };
-        // Helper to handle error
+        // Helper to handle error - use asItem for type conversion
         const handleError = async (error, item, attempt) => {
             if (typeof onError === 'function') {
-                return onError(error, item, attempt);
+                return onError(error, asItem(item), attempt);
             }
             return onError;
         };
@@ -399,24 +406,25 @@ export class DBPromise {
             let attempt = 0;
             while (true) {
                 try {
-                    // Create timeout wrapper if needed
+                    // Create timeout wrapper if needed - use asCallback for type conversion
                     let result;
+                    const typedCallback = asCallback(callback);
                     if (timeout) {
                         const timeoutPromise = new Promise((_, reject) => {
                             setTimeout(() => reject(new Error(`Timeout after ${timeout}ms`)), timeout);
                         });
                         result = await Promise.race([
-                            Promise.resolve(callback(item, index)),
+                            Promise.resolve(typedCallback(item, index)),
                             timeoutPromise,
                         ]);
                     }
                     else {
-                        result = await callback(item, index);
+                        result = await typedCallback(item, index);
                     }
                     // Success
                     completed++;
                     await persistProgress(itemId);
-                    await onComplete?.(item, result, index);
+                    await onComplete?.(asItem(item), result, index);
                     onProgress?.(getProgress(index, item));
                     return;
                 }
@@ -504,13 +512,21 @@ export class DBPromise {
                     cancelled,
                     actionId,
                 };
-                await actionsAPI.update(actionId, {
+                const updatePayload = {
                     status: cancelled ? 'failed' : 'completed',
                     progress: completed + failed + skipped,
                     data: { processedIds: Array.from(processedIds) },
                     result: finalResult,
-                    error: cancelled ? 'Cancelled' : errors.length > 0 ? `${errors.length} items failed` : undefined,
-                });
+                };
+                const errorMessage = cancelled
+                    ? 'Cancelled'
+                    : errors.length > 0
+                        ? `${errors.length} items failed`
+                        : undefined;
+                if (errorMessage !== undefined) {
+                    updatePayload.error = errorMessage;
+                }
+                await actionsAPI.update(actionId, updatePayload);
             }
         }
         return {
@@ -521,11 +537,14 @@ export class DBPromise {
             elapsed: Date.now() - startTime,
             errors,
             cancelled,
-            actionId,
+            ...(actionId !== undefined && { actionId }),
         };
     }
     /**
      * Async iteration
+     *
+     * The yield casts use a local type alias because TypeScript cannot narrow
+     * the conditional type `T extends (infer I)[] ? I : T` at runtime.
      */
     async *[Symbol.asyncIterator]() {
         const items = await this.resolve();
@@ -579,9 +598,50 @@ export class DBPromise {
 // =============================================================================
 // Proxy Handlers
 // =============================================================================
+/**
+ * Known DBPromise methods that need proxy handling.
+ */
+const DBPROMISE_METHODS = new Set([
+    'map',
+    'filter',
+    'sort',
+    'limit',
+    'first',
+    'forEach',
+    'resolve',
+    'then',
+    'catch',
+    'finally',
+]);
+/**
+ * Known internal properties that need proxy handling.
+ */
+const INTERNAL_PROPS = new Set(['accessedProps', 'path', 'isResolved']);
+/**
+ * Access a property on DBPromise by name, with type safety.
+ */
+function getDBPromiseProperty(target, prop) {
+    return target[prop];
+}
+/**
+ * Get and bind a method from DBPromise by name.
+ */
+function bindDBPromiseMethod(target, prop) {
+    const method = getDBPromiseProperty(target, prop);
+    if (typeof method === 'function') {
+        return method.bind(target);
+    }
+    throw new Error(`${prop} is not a method on DBPromise`);
+}
+/**
+ * Proxy handlers for DBPromise property access tracking.
+ *
+ * Uses type-safe helper functions to access class methods and properties
+ * from within the ProxyHandler where the target type is DBPromise<unknown>.
+ */
 const DB_PROXY_HANDLERS = {
-    get(target, prop, receiver) {
-        // Handle symbols
+    get(target, prop) {
+        // Handle symbols - access internal symbol-keyed properties
         if (typeof prop === 'symbol') {
             if (prop === DB_PROMISE_SYMBOL)
                 return true;
@@ -589,25 +649,24 @@ const DB_PROXY_HANDLERS = {
                 return target;
             if (prop === Symbol.asyncIterator)
                 return target[Symbol.asyncIterator].bind(target);
-            return target[prop];
+            // Use getSymbolProperty for type-safe symbol access
+            return getSymbolProperty(target, prop);
         }
-        // Handle promise methods
-        if (prop === 'then' || prop === 'catch' || prop === 'finally') {
-            return target[prop].bind(target);
+        // Handle promise and DBPromise methods
+        if (DBPROMISE_METHODS.has(prop)) {
+            return bindDBPromiseMethod(target, prop);
         }
-        // Handle DBPromise methods
-        if (['map', 'filter', 'sort', 'limit', 'first', 'forEach', 'resolve'].includes(prop)) {
-            return target[prop].bind(target);
-        }
-        // Handle internal properties
-        if (prop.startsWith('_') || ['accessedProps', 'path', 'isResolved'].includes(prop)) {
-            return target[prop];
+        // Handle internal properties - private properties and getters
+        if (prop.startsWith('_') || INTERNAL_PROPS.has(prop)) {
+            return getDBPromiseProperty(target, prop);
         }
         // Track property access
         target.accessedProps.add(prop);
         // Return a new DBPromise for the property path
+        const internals = target;
+        const typeValue = internals._options?.type;
         return new DBPromise({
-            type: target['_options']?.type,
+            ...(typeValue !== undefined && { type: typeValue }),
             parent: target,
             propertyPath: [...target.path, prop],
             executor: async () => {
@@ -651,9 +710,11 @@ function getNestedValue(obj, path) {
 function createBatchLoadingArray(items) {
     // Create a new array with all the original items
     const batchArray = [...items];
-    // Override the map method to do batch loading
+    // Override the map method to do batch loading only when needed
+    // Returns synchronously when no relations are accessed (preserving native Array behavior)
+    // Returns a Promise when relations need to be batch-loaded
     Object.defineProperty(batchArray, 'map', {
-        value: async function (callback) {
+        value: function (callback) {
             const items = this;
             // Phase 1: Record what the callback accesses using placeholder proxies
             const recordings = [];
@@ -674,20 +735,33 @@ function createBatchLoadingArray(items) {
                 }
                 recordings.push(recording);
             }
-            // Phase 2: Analyze recordings and batch-load relations
-            const batchLoads = analyzeBatchLoads(recordings, items);
-            const loadedRelations = await executeBatchLoads(batchLoads, recordings);
-            // Phase 3: Re-run callback with enriched items that have loaded relations
-            const enrichedItems = [];
-            for (let i = 0; i < items.length; i++) {
-                enrichedItems.push(enrichItemWithLoadedRelations(items[i], loadedRelations));
-            }
-            // Execute callback again with enriched data
-            const results = [];
-            for (let i = 0; i < enrichedItems.length; i++) {
-                results.push(callback(enrichedItems[i], i));
+            // Check if any relations were accessed
+            const hasRelations = recordings.some((r) => r.relations.size > 0);
+            // If no relations were accessed, run synchronously like native Array.map
+            if (!hasRelations) {
+                try {
+                    return Array.prototype.map.call(items, (item, i) => callback(item, i));
+                }
+                catch (error) {
+                    return Promise.reject(error);
+                }
             }
-            return results;
+            // Phase 2 & 3: Async batch loading path (returns a Promise)
+            return (async () => {
+                const batchLoads = analyzeBatchLoads(recordings, items);
+                const loadedRelations = await executeBatchLoads(batchLoads, recordings);
+                // Re-run callback with enriched items that have loaded relations
+                const enrichedItems = [];
+                for (let i = 0; i < items.length; i++) {
+                    enrichedItems.push(enrichItemWithLoadedRelations(items[i], loadedRelations));
+                }
+                // Execute callback again with enriched data
+                const results = [];
+                for (let i = 0; i < enrichedItems.length; i++) {
+                    results.push(callback(enrichedItems[i], i));
+                }
+                return results;
+            })();
         },
         writable: true,
         configurable: true,
@@ -779,14 +853,15 @@ function createRecordingProxy(item, recording) {
     return new Proxy(item, {
         get(target, prop) {
             if (typeof prop === 'symbol') {
-                return target[prop];
+                // Use getSymbolProperty for type-safe symbol access
+                return getSymbolProperty(target, prop);
             }
             recording.paths.add(prop);
             const value = target[prop];
             // If accessing a relation (identified by $type marker from hydration)
             // Note: proxies may not expose $type in 'has' trap, so check via property access
-            const maybeType = value && typeof value === 'object' ? value.$type : undefined;
-            if (maybeType && typeof maybeType === 'string') {
+            const maybeType = extractMarkerType(value);
+            if (maybeType) {
                 const relationType = maybeType;
                 // Get or create the relation recording
                 let relationRecording = recording.relations.get(prop);
@@ -805,16 +880,17 @@ function createRecordingProxy(item, recording) {
             // Handle arrays with potential relation elements (like members: ['->User'])
             if (Array.isArray(value)) {
                 // Check if the array itself is a relation array (has $type marker from thenableArray)
-                const arrayType = value.$type;
-                const isArrayRelation = arrayType !== undefined || value.$isArrayRelation;
+                const arrayMarker = isEntityArray(value) ? value : null;
+                const arrayType = arrayMarker?.$type;
+                const isArrayRelationFlag = arrayMarker !== null;
                 // Also check if array contains relation proxies (for backwards compatibility)
-                const hasRelationElements = !isArrayRelation && value.some(v => v && typeof v === 'object' && v.$type !== undefined);
-                if (isArrayRelation || hasRelationElements) {
+                const hasRelationElementsFlag = !isArrayRelationFlag && hasRelationElements(value);
+                if (isArrayRelationFlag || hasRelationElementsFlag) {
                     // Get the type from the array $type or first element
                     let relationType = arrayType;
                     if (!relationType) {
-                        const firstRelation = value.find(v => v && typeof v === 'object' && v.$type !== undefined);
-                        relationType = firstRelation ? firstRelation.$type : 'unknown';
+                        const firstRelation = value.find((v) => extractMarkerType(v) !== undefined);
+                        relationType = firstRelation ? extractMarkerType(firstRelation) ?? 'unknown' : 'unknown';
                     }
                     let relationRecording = recording.relations.get(prop);
                     if (!relationRecording) {
@@ -852,7 +928,7 @@ function createRecordingProxy(item, recording) {
                                 return createRelationRecordingProxy(relationRecording);
                             }
                             return Reflect.get(arrayTarget, arrayProp);
-                        }
+                        },
                     });
                 }
                 // Regular array - wrap for recording
@@ -889,36 +965,17 @@ function analyzeBatchLoads(recordings, items) {
                 // Handle array relations (e.g., members: ['id1', 'id2'])
                 if (Array.isArray(relationValue)) {
                     for (const element of relationValue) {
-                        if (typeof element === 'string') {
-                            ids.push(element);
-                        }
-                        else if (element && typeof element === 'object') {
-                            // Try valueOf() for thenable proxies
-                            if (typeof element.valueOf === 'function') {
-                                const val = element.valueOf();
-                                if (typeof val === 'string') {
-                                    ids.push(val);
-                                }
-                            }
-                            else if (element.$id) {
-                                ids.push(element.$id);
-                            }
+                        const elementId = extractEntityId(element);
+                        if (elementId) {
+                            ids.push(elementId);
                         }
                     }
                 }
-                else if (typeof relationValue === 'string') {
-                    ids.push(relationValue);
-                }
-                else if (relationValue && typeof relationValue === 'object') {
-                    // Try valueOf() for thenable proxies (single relation)
-                    if (typeof relationValue.valueOf === 'function') {
-                        const val = relationValue.valueOf();
-                        if (typeof val === 'string') {
-                            ids.push(val);
-                        }
-                    }
-                    else if (relationValue.$id) {
-                        ids.push(relationValue.$id);
+                else {
+                    // Handle single relations - string ID or proxy object
+                    const relationId = extractEntityId(relationValue);
+                    if (relationId) {
+                        ids.push(relationId);
                     }
                 }
             }
@@ -983,12 +1040,12 @@ async function executeBatchLoads(batchLoads, recordings) {
         // Deduplicate IDs
         const uniqueIds = [...new Set(ids)];
         // Fetch all entities in parallel
-        const entities = await Promise.all(uniqueIds.map(id => provider.get(type, id)));
+        const entities = await Promise.all(uniqueIds.map((id) => provider.get(type, id)));
         // Map results by ID
         for (let i = 0; i < uniqueIds.length; i++) {
             const entity = entities[i];
             if (entity) {
-                const entityId = (entity.$id || entity.id);
+                const entityId = (entity['$id'] || entity['id']);
                 relationResults.set(entityId, entity);
             }
         }
@@ -1004,7 +1061,7 @@ async function executeBatchLoads(batchLoads, recordings) {
                 let nestedType;
                 for (const entity of relationResults.values()) {
                     const entityObj = entity;
-                    const entityType = entityObj.$type;
+                    const entityType = entityObj['$type'];
                     const nestedValue = entityObj[nestedPath];
                     if (typeof nestedValue === 'string') {
                         // It's a string - could be an ID
@@ -1022,17 +1079,15 @@ async function executeBatchLoads(batchLoads, recordings) {
                             }
                         }
                     }
-                    else if (nestedValue && typeof nestedValue === 'object') {
+                    else if (isPlainObject(nestedValue)) {
                         // Check if it has a $type marker (for already-hydrated proxies)
-                        const valueType = nestedValue.$type;
-                        if (valueType && typeof valueType === 'string') {
+                        const valueType = extractMarkerType(nestedValue);
+                        if (valueType) {
                             nestedType = valueType;
-                            // Try to get the ID
-                            if (typeof nestedValue.valueOf === 'function') {
-                                const val = nestedValue.valueOf();
-                                if (typeof val === 'string') {
-                                    nestedIds.push(val);
-                                }
+                            // Try to get the ID via valueOf or $id
+                            const nestedId = extractEntityId(nestedValue);
+                            if (nestedId) {
+                                nestedIds.push(nestedId);
                             }
                         }
                     }
@@ -1044,11 +1099,13 @@ async function executeBatchLoads(batchLoads, recordings) {
             // Recursively load nested relations
             if (nestedBatchLoads.size > 0) {
                 // Create nested recordings for the next level if available
+                // The key must be the field name (not the type) so that nestedRelationInfo
+                // lookups in the recursive call match by relation field name
                 const nestedRecordings = [];
-                for (const nestedRecording of nestedInfo.nestedRelations.values()) {
+                for (const [nestedFieldName, nestedRecording] of nestedInfo.nestedRelations) {
                     nestedRecordings.push({
                         paths: new Set(),
-                        relations: new Map([[nestedRecording.type, nestedRecording]]),
+                        relations: new Map([[nestedFieldName, nestedRecording]]),
                     });
                 }
                 const nestedResults = await executeBatchLoads(nestedBatchLoads, nestedRecordings.length > 0 ? nestedRecordings : undefined);
@@ -1076,22 +1133,7 @@ function enrichItemWithLoadedRelations(item, loadedRelations) {
         if (Array.isArray(relationValue)) {
             const loadedArray = [];
             for (const element of relationValue) {
-                let idStr;
-                if (typeof element === 'string') {
-                    idStr = element;
-                }
-                else if (element && typeof element === 'object') {
-                    // Try valueOf for thenable proxies
-                    if (typeof element.valueOf === 'function') {
-                        const val = element.valueOf();
-                        if (typeof val === 'string') {
-                            idStr = val;
-                        }
-                    }
-                    if (!idStr && element.$id) {
-                        idStr = element.$id;
-                    }
-                }
+                const idStr = extractEntityId(element);
                 if (idStr) {
                     const loaded = relationData.get(idStr);
                     if (loaded) {
@@ -1103,23 +1145,7 @@ function enrichItemWithLoadedRelations(item, loadedRelations) {
         }
         else {
             // Handle single relations - get the ID from the thenable proxy or direct value
-            let relationId;
-            if (typeof relationValue === 'string') {
-                relationId = relationValue;
-            }
-            else if (relationValue && typeof relationValue === 'object') {
-                // Try to get ID from proxy's valueOf or toString
-                if ('valueOf' in relationValue && typeof relationValue.valueOf === 'function') {
-                    const val = relationValue.valueOf();
-                    if (typeof val === 'string') {
-                        relationId = val;
-                    }
-                }
-                // Also check for $id
-                if (!relationId && '$id' in relationValue) {
-                    relationId = relationValue.$id;
-                }
-            }
+            const relationId = extractEntityId(relationValue);
             if (relationId) {
                 const loaded = relationData.get(relationId);
                 if (loaded) {
@@ -1130,13 +1156,6 @@ function enrichItemWithLoadedRelations(item, loadedRelations) {
     }
     return enriched;
 }
-/**
- * Apply batch-loaded results to the mapped results (deprecated, kept for compatibility)
- */
-function applyBatchResults(results, loadedRelations, originalItems) {
-    // No longer used - enrichment happens before callback re-run
-    return results;
-}
 // =============================================================================
 // Check Functions
 // =============================================================================
@@ -1154,7 +1173,9 @@ export function isDBPromise(value) {
  */
 export function getRawDBPromise(value) {
     if (RAW_DB_PROMISE_SYMBOL in value) {
-        return value[RAW_DB_PROMISE_SYMBOL];
+        // We know the symbol exists from the check above, so this cast is safe
+        const raw = value[RAW_DB_PROMISE_SYMBOL];
+        return raw;
     }
     return value;
 }
@@ -1179,9 +1200,6 @@ export function createEntityPromise(type, executor) {
 export function createSearchPromise(type, executor) {
     return new DBPromise({ type, executor });
 }
-// =============================================================================
-// Entity Operations Wrapper
-// =============================================================================
 /**
  * Wrap EntityOperations to return DBPromise
  */
@@ -1191,28 +1209,28 @@ export function wrapEntityOperations(typeName, operations, actionsAPI) {
             return new DBPromise({
                 type: typeName,
                 executor: () => operations.get(id),
-                actionsAPI,
+                ...(actionsAPI !== undefined && { actionsAPI }),
             });
         },
         list(options) {
             return new DBPromise({
                 type: typeName,
                 executor: () => operations.list(options),
-                actionsAPI,
+                ...(actionsAPI !== undefined && { actionsAPI }),
             });
         },
         find(where) {
             return new DBPromise({
                 type: typeName,
                 executor: () => operations.find(where),
-                actionsAPI,
+                ...(actionsAPI !== undefined && { actionsAPI }),
             });
         },
         search(query, options) {
             return new DBPromise({
                 type: typeName,
                 executor: () => operations.search(query, options),
-                actionsAPI,
+                ...(actionsAPI !== undefined && { actionsAPI }),
             });
         },
         first() {
@@ -1222,7 +1240,7 @@ export function wrapEntityOperations(typeName, operations, actionsAPI) {
                     const items = await operations.list({ limit: 1 });
                     return items[0] ?? null;
                 },
-                actionsAPI,
+                ...(actionsAPI !== undefined && { actionsAPI }),
             });
         },
         /**
@@ -1243,7 +1261,9 @@ export function wrapEntityOperations(typeName, operations, actionsAPI) {
          */
         async forEach(callbackOrOptions, callbackOrOpts) {
             // Detect which calling style is being used
-            const isOptionsFirst = typeof callbackOrOptions === 'object' && callbackOrOptions !== null && !('call' in callbackOrOptions);
+            const isOptionsFirst = typeof callbackOrOptions === 'object' &&
+                callbackOrOptions !== null &&
+                !('call' in callbackOrOptions);
             const callback = isOptionsFirst
                 ? callbackOrOpts
                 : callbackOrOptions;
@@ -1255,26 +1275,27 @@ export function wrapEntityOperations(typeName, operations, actionsAPI) {
             const listPromise = new DBPromise({
                 type: typeName,
                 executor: () => operations.list(listOptions),
-                actionsAPI,
+                ...(actionsAPI !== undefined && { actionsAPI }),
             });
-            return listPromise.forEach(callback, options);
+            return listPromise.forEach(asCallback(callback), options);
         },
-        // Semantic search methods
+        // Semantic search methods - delegate to underlying operations
+        // Return empty array if not available for graceful degradation
         semanticSearch(query, options) {
-            if (operations.semanticSearch) {
-                return operations.semanticSearch(query, options);
+            if (!operations.semanticSearch) {
+                // Return empty array for graceful degradation when semantic search not available
+                return Promise.resolve([]);
             }
-            // Fallback: return empty array if not supported
-            return Promise.resolve([]);
+            return operations.semanticSearch(query, options);
         },
         hybridSearch(query, options) {
-            if (operations.hybridSearch) {
-                return operations.hybridSearch(query, options);
+            if (!operations.hybridSearch) {
+                // Return empty array for graceful degradation when hybrid search not available
+                return Promise.resolve([]);
             }
-            // Fallback: return empty array if not supported
-            return Promise.resolve([]);
+            return operations.hybridSearch(query, options);
         },
-        // Mutations don't need wrapping
+        // Mutations - pass through create which supports both (data, options?) and (id, data, options?)
         create: operations.create,
         update: operations.update,
         upsert: operations.upsert,