ai-database 2.0.2 → 2.1.3

package/dist/ai-promise-db.js

@@ -20,6 +20,43 @@
  *
  * @packageDocumentation
  */
+import { Semaphore } from './memory-provider.js';
+import { isEntityArray, extractEntityId, extractMarkerType, isPlainObject, hasRelationElements, asCallback, asPredicate, asComparator, getSymbolProperty, asItem, } from './type-guards.js';
+// Provider resolver - will be set by schema.ts
+let providerResolver = null;
+/**
+ * Set the provider resolver function (called from schema.ts)
+ */
+export function setProviderResolver(resolver) {
+    providerResolver = resolver;
+}
+/**
+ * Get the provider for batch operations
+ */
+async function getProvider() {
+    if (providerResolver) {
+        return providerResolver();
+    }
+    return null;
+}
+// Schema info for batch loading - stores relation field info for entity types
+// Maps entityType -> fieldName -> relatedType
+let schemaRelationInfo = null;
+/**
+ * Set schema relation info for batch loading nested relations
+ * Called from schema.ts when DB() is initialized
+ */
+export function setSchemaRelationInfo(info) {
+    schemaRelationInfo = info;
+}
+/**
+ * Get the related type for a field on an entity type
+ */
+function getRelatedType(entityType, fieldName) {
+    if (!schemaRelationInfo)
+        return undefined;
+    return schemaRelationInfo.get(entityType)?.get(fieldName);
+}
 // =============================================================================
 // Types
 // =============================================================================
@@ -84,7 +121,13 @@ export class DBPromise {
         }
         // Execute the query
         const result = await this._options.executor();
-        this._resolvedValue = result;
+        // If result is an array, wrap it with batch-loading map
+        if (Array.isArray(result)) {
+            this._resolvedValue = createBatchLoadingArray(result);
+        }
+        else {
+            this._resolvedValue = result;
+        }
         this._isResolved = true;
         return this._resolvedValue;
     }
@@ -113,8 +156,7 @@ export class DBPromise {
                 }
                 // Create recording context
                 const recordings = [];
-                // Record what the callback accesses for each item
-                const recordedResults = [];
+                // Phase 1: Record what the callback accesses for each item (using placeholder proxies)
                 for (let i = 0; i < items.length; i++) {
                     const item = items[i];
                     const recording = {
@@ -123,17 +165,32 @@ export class DBPromise {
                     };
                     // Create a recording proxy for this item
                     const recordingProxy = createRecordingProxy(item, recording);
-                    // Execute callback with recording proxy
-                    const result = callback(recordingProxy, i);
-                    recordedResults.push(result);
+                    // Execute callback with recording proxy to discover accesses
+                    // Use asCallback to convert the callback to accept unknown items
+                    try {
+                        asCallback(callback)(recordingProxy, i);
+                    }
+                    catch {
+                        // Ignore errors during recording phase - they'll surface in Phase 3
+                    }
                     recordings.push(recording);
                 }
-                // Analyze recordings to find batch-loadable relations
+                // Phase 2: Analyze recordings and batch-load relations
                 const batchLoads = analyzeBatchLoads(recordings, items);
-                // Execute batch loads
-                const loadedRelations = await executeBatchLoads(batchLoads);
-                // Apply loaded relations to results
-                return applyBatchResults(recordedResults, loadedRelations, 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
+                // 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(typedCallback(enrichedItems[i], i));
+                }
+                return results;
             },
         });
     }
@@ -149,7 +206,8 @@ export class DBPromise {
                 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));
             },
         });
     }
@@ -165,7 +223,8 @@ export class DBPromise {
                 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));
             },
         });
     }
@@ -247,7 +306,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
@@ -324,10 +383,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;
         };
@@ -346,24 +405,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;
                 }
@@ -473,6 +533,9 @@ export class DBPromise {
     }
     /**
      * 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();
@@ -526,9 +589,42 @@ 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;
@@ -536,25 +632,23 @@ const DB_PROXY_HANDLERS = {
                 return target;
             if (prop === Symbol.asyncIterator)
                 return target[Symbol.asyncIterator].bind(target);
-            return target[prop];
-        }
-        // Handle promise methods
-        if (prop === 'then' || prop === 'catch' || prop === 'finally') {
-            return target[prop].bind(target);
+            // Use getSymbolProperty for type-safe symbol access
+            return getSymbolProperty(target, prop);
         }
-        // Handle DBPromise methods
-        if (['map', 'filter', 'sort', 'limit', 'first', 'forEach', 'resolve'].includes(prop)) {
-            return target[prop].bind(target);
+        // Handle promise and DBPromise methods
+        if (DBPROMISE_METHODS.has(prop)) {
+            return bindDBPromiseMethod(target, prop);
         }
-        // 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;
         return new DBPromise({
-            type: target['_options']?.type,
+            type: internals._options?.type,
             parent: target,
             propertyPath: [...target.path, prop],
             executor: async () => {
@@ -579,35 +673,6 @@ const DB_PROXY_HANDLERS = {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-/**
- * Simple semaphore for concurrency control
- */
-class Semaphore {
-    permits;
-    queue = [];
-    constructor(permits) {
-        this.permits = permits;
-    }
-    async acquire() {
-        if (this.permits > 0) {
-            this.permits--;
-            return () => this.release();
-        }
-        return new Promise((resolve) => {
-            this.queue.push(() => {
-                this.permits--;
-                resolve(() => this.release());
-            });
-        });
-    }
-    release() {
-        this.permits++;
-        const next = this.queue.shift();
-        if (next) {
-            next();
-        }
-    }
-}
 /**
  * Get nested value from object
  */
@@ -620,6 +685,131 @@ function getNestedValue(obj, path) {
     }
     return current;
 }
+/**
+ * Create an array that has a batch-loading map method
+ * When .map() is called on the resolved array, it performs batch loading of relations
+ */
+function createBatchLoadingArray(items) {
+    // Create a new array with all the original items
+    const batchArray = [...items];
+    // Override the map method to do batch loading
+    Object.defineProperty(batchArray, 'map', {
+        value: async function (callback) {
+            const items = this;
+            // Phase 1: Record what the callback accesses using placeholder proxies
+            const recordings = [];
+            for (let i = 0; i < items.length; i++) {
+                const item = items[i];
+                const recording = {
+                    paths: new Set(),
+                    relations: new Map(),
+                };
+                // Create a recording proxy for this item
+                const recordingProxy = createRecordingProxy(item, recording);
+                // Execute callback with recording proxy to discover accesses
+                try {
+                    callback(recordingProxy, i);
+                }
+                catch {
+                    // Ignore errors during recording phase - they'll surface in Phase 3
+                }
+                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));
+            }
+            return results;
+        },
+        writable: true,
+        configurable: true,
+        enumerable: false,
+    });
+    return batchArray;
+}
+/**
+ * Create a proxy that records nested property accesses for relations
+ * This returns placeholder values to allow the callback to complete
+ *
+ * When accessing customer.address.city:
+ * - At depth 0 (path=[]), accessing 'address' records it in nestedPaths
+ * - Accessing 'city' on 'address' creates a nestedRelation for 'address' and records 'city' in its nestedPaths
+ */
+function createRelationRecordingProxy(relationRecording, path = [], currentNestedRecording) {
+    // Return a proxy that records all nested accesses
+    return new Proxy({}, {
+        get(target, prop) {
+            if (typeof prop === 'symbol') {
+                return undefined;
+            }
+            // For common array methods that don't need recording
+            if (prop === 'map' || prop === 'filter' || prop === 'forEach' || prop === 'length') {
+                if (relationRecording.isArray) {
+                    // Return array-like behavior
+                    if (prop === 'length')
+                        return 0;
+                    if (prop === 'map')
+                        return (fn) => [];
+                    if (prop === 'filter')
+                        return (fn) => [];
+                    if (prop === 'forEach')
+                        return (fn) => { };
+                }
+                return undefined;
+            }
+            if (path.length === 0) {
+                // First level: recording access to properties of the relation itself (e.g., customer.address)
+                // This is a direct property access on the relation - record it
+                relationRecording.nestedPaths.add(prop);
+                // Create a nested recording for potential deeper access
+                // We don't know if 'prop' is a relation yet, but if there's further access we'll need it
+                let nestedRec = relationRecording.nestedRelations.get(prop);
+                if (!nestedRec) {
+                    nestedRec = {
+                        type: 'unknown', // Type will be inferred when loading
+                        isArray: false,
+                        nestedPaths: new Set(),
+                        nestedRelations: new Map(),
+                    };
+                    relationRecording.nestedRelations.set(prop, nestedRec);
+                }
+                // Return a proxy that will record further accesses into the nested recording
+                return createRelationRecordingProxy(relationRecording, [prop], nestedRec);
+            }
+            else {
+                // Deeper level: recording access to properties of a nested relation (e.g., customer.address.city)
+                // Record this property in the current nested recording
+                if (currentNestedRecording) {
+                    currentNestedRecording.nestedPaths.add(prop);
+                    // Create another nested recording for even deeper access
+                    let deeperRec = currentNestedRecording.nestedRelations.get(prop);
+                    if (!deeperRec) {
+                        deeperRec = {
+                            type: 'unknown',
+                            isArray: false,
+                            nestedPaths: new Set(),
+                            nestedRelations: new Map(),
+                        };
+                        currentNestedRecording.nestedRelations.set(prop, deeperRec);
+                    }
+                    return createRelationRecordingProxy(relationRecording, [...path, prop], deeperRec);
+                }
+                // Fallback - just record in nestedPaths of root
+                relationRecording.nestedPaths.add(prop);
+                return createRelationRecordingProxy(relationRecording, [...path, prop]);
+            }
+        },
+    });
+}
 /**
  * Create a proxy that records property accesses
  */
@@ -630,19 +820,88 @@ 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 $id or Promise), record it
-            if (value && typeof value === 'object' && '$type' in value) {
-                recording.relations.set(prop, {
-                    type: value.$type,
-                    isArray: Array.isArray(value),
-                    nestedPaths: new Set(),
-                });
+            // 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 = extractMarkerType(value);
+            if (maybeType) {
+                const relationType = maybeType;
+                // Get or create the relation recording
+                let relationRecording = recording.relations.get(prop);
+                if (!relationRecording) {
+                    relationRecording = {
+                        type: relationType,
+                        isArray: Array.isArray(value),
+                        nestedPaths: new Set(),
+                        nestedRelations: new Map(),
+                    };
+                    recording.relations.set(prop, relationRecording);
+                }
+                // Return a proxy that records nested accesses but uses placeholder values
+                return createRelationRecordingProxy(relationRecording);
+            }
+            // 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 arrayMarker = isEntityArray(value) ? value : null;
+                const arrayType = arrayMarker?.$type;
+                const isArrayRelationFlag = arrayMarker !== null;
+                // Also check if array contains relation proxies (for backwards compatibility)
+                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 => extractMarkerType(v) !== undefined);
+                        relationType = firstRelation ? extractMarkerType(firstRelation) ?? 'unknown' : 'unknown';
+                    }
+                    let relationRecording = recording.relations.get(prop);
+                    if (!relationRecording) {
+                        relationRecording = {
+                            type: relationType,
+                            isArray: true,
+                            nestedPaths: new Set(),
+                            nestedRelations: new Map(),
+                        };
+                        recording.relations.set(prop, relationRecording);
+                    }
+                    // Return a proxy array that records element accesses
+                    return new Proxy(value, {
+                        get(arrayTarget, arrayProp) {
+                            if (arrayProp === 'map') {
+                                return (fn) => {
+                                    // Record what the map callback accesses
+                                    const elementProxy = createRelationRecordingProxy(relationRecording);
+                                    // Execute callback to record accesses, but we can't return real results
+                                    try {
+                                        fn(elementProxy, 0);
+                                    }
+                                    catch { }
+                                    return [];
+                                };
+                            }
+                            if (arrayProp === 'length')
+                                return value.length;
+                            if (arrayProp === 'filter')
+                                return (fn) => [];
+                            if (arrayProp === 'forEach')
+                                return (fn) => { };
+                            // Numeric index access
+                            if (!isNaN(Number(arrayProp))) {
+                                return createRelationRecordingProxy(relationRecording);
+                            }
+                            return Reflect.get(arrayTarget, arrayProp);
+                        }
+                    });
+                }
+                // Regular array - wrap for recording
+                return createRecordingProxy(value, recording);
             }
-            // Return a nested recording proxy for objects
+            // Return a nested recording proxy for regular objects
             if (value && typeof value === 'object') {
                 return createRecordingProxy(value, recording);
             }
@@ -658,27 +917,43 @@ function analyzeBatchLoads(recordings, items) {
     // Find common relations across all recordings
     const relationCounts = new Map();
     for (const recording of recordings) {
-        for (const [relationName, relation] of recording.relations) {
+        for (const [relationName] of recording.relations) {
             relationCounts.set(relationName, (relationCounts.get(relationName) || 0) + 1);
         }
     }
-    // Only batch-load relations accessed in all (or most) items
+    // Batch-load any relation that was accessed at least once
     for (const [relationName, count] of relationCounts) {
-        if (count >= recordings.length * 0.5) {
-            // At least 50% of items access this relation
+        if (count > 0) {
+            // At least one item accesses this relation
             const ids = [];
             for (let i = 0; i < items.length; i++) {
                 const item = items[i];
-                const relationId = item[relationName];
-                if (typeof relationId === 'string') {
-                    ids.push(relationId);
+                const relationValue = item[relationName];
+                // Handle array relations (e.g., members: ['id1', 'id2'])
+                if (Array.isArray(relationValue)) {
+                    for (const element of relationValue) {
+                        const elementId = extractEntityId(element);
+                        if (elementId) {
+                            ids.push(elementId);
+                        }
+                    }
                 }
-                else if (relationId && typeof relationId === 'object' && '$id' in relationId) {
-                    ids.push(relationId.$id);
+                else {
+                    // Handle single relations - string ID or proxy object
+                    const relationId = extractEntityId(relationValue);
+                    if (relationId) {
+                        ids.push(relationId);
+                    }
                 }
             }
             if (ids.length > 0) {
-                const relation = recordings[0]?.relations.get(relationName);
+                // Find the relation info from any recording that has it
+                let relation;
+                for (const recording of recordings) {
+                    relation = recording.relations.get(relationName);
+                    if (relation)
+                        break;
+                }
                 if (relation) {
                     batchLoads.set(relationName, { type: relation.type, ids });
                 }
@@ -688,23 +963,169 @@ function analyzeBatchLoads(recordings, items) {
     return batchLoads;
 }
 /**
- * Execute batch loads for relations
+ * Execute batch loads for relations, including nested relations recursively
  */
-async function executeBatchLoads(batchLoads) {
+async function executeBatchLoads(batchLoads, recordings) {
     const results = new Map();
-    // For now, return empty - actual implementation would batch query
-    // This is a placeholder that will be filled in by the actual DB integration
+    const provider = await getProvider();
+    if (!provider) {
+        // No provider available, return empty results
+        for (const [relationName] of batchLoads) {
+            results.set(relationName, new Map());
+        }
+        return results;
+    }
+    // Collect nested relation info from recordings
+    const nestedRelationInfo = new Map();
+    if (recordings) {
+        for (const recording of recordings) {
+            for (const [relationName, relationRecording] of recording.relations) {
+                if (!nestedRelationInfo.has(relationName)) {
+                    nestedRelationInfo.set(relationName, {
+                        nestedPaths: new Set(relationRecording.nestedPaths),
+                        nestedRelations: new Map(relationRecording.nestedRelations),
+                    });
+                }
+                else {
+                    // Merge nested paths
+                    const existing = nestedRelationInfo.get(relationName);
+                    for (const path of relationRecording.nestedPaths) {
+                        existing.nestedPaths.add(path);
+                    }
+                    for (const [nestedName, nestedRec] of relationRecording.nestedRelations) {
+                        if (!existing.nestedRelations.has(nestedName)) {
+                            existing.nestedRelations.set(nestedName, nestedRec);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Batch load each relation type
     for (const [relationName, { type, ids }] of batchLoads) {
-        results.set(relationName, new Map());
+        const relationResults = new Map();
+        // Deduplicate IDs
+        const uniqueIds = [...new Set(ids)];
+        // Fetch all entities in parallel
+        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);
+                relationResults.set(entityId, entity);
+            }
+        }
+        results.set(relationName, relationResults);
+        // Check for nested relations that need to be loaded
+        const nestedInfo = nestedRelationInfo.get(relationName);
+        if (nestedInfo && nestedInfo.nestedPaths.size > 0) {
+            // For each nested path, check if it's actually a relation (string ID) on loaded entities
+            const nestedBatchLoads = new Map();
+            for (const nestedPath of nestedInfo.nestedPaths) {
+                // Collect IDs from all loaded entities for this nested path
+                const nestedIds = [];
+                let nestedType;
+                for (const entity of relationResults.values()) {
+                    const entityObj = entity;
+                    const entityType = entityObj.$type;
+                    const nestedValue = entityObj[nestedPath];
+                    if (typeof nestedValue === 'string') {
+                        // It's a string - could be an ID
+                        nestedIds.push(nestedValue);
+                        // Try to determine the type from various sources
+                        if (!nestedType) {
+                            // First, check the nested relation recording
+                            const nestedRecording = nestedInfo.nestedRelations.get(nestedPath);
+                            if (nestedRecording && nestedRecording.type !== 'unknown') {
+                                nestedType = nestedRecording.type;
+                            }
+                            // Then, try to get from schema info using the entity's $type
+                            if (!nestedType && entityType) {
+                                nestedType = getRelatedType(entityType, nestedPath);
+                            }
+                        }
+                    }
+                    else if (isPlainObject(nestedValue)) {
+                        // Check if it has a $type marker (for already-hydrated proxies)
+                        const valueType = extractMarkerType(nestedValue);
+                        if (valueType) {
+                            nestedType = valueType;
+                            // Try to get the ID via valueOf or $id
+                            const nestedId = extractEntityId(nestedValue);
+                            if (nestedId) {
+                                nestedIds.push(nestedId);
+                            }
+                        }
+                    }
+                }
+                if (nestedIds.length > 0 && nestedType) {
+                    nestedBatchLoads.set(nestedPath, { type: nestedType, ids: nestedIds });
+                }
+            }
+            // Recursively load nested relations
+            if (nestedBatchLoads.size > 0) {
+                // Create nested recordings for the next level if available
+                const nestedRecordings = [];
+                for (const nestedRecording of nestedInfo.nestedRelations.values()) {
+                    nestedRecordings.push({
+                        paths: new Set(),
+                        relations: new Map([[nestedRecording.type, nestedRecording]]),
+                    });
+                }
+                const nestedResults = await executeBatchLoads(nestedBatchLoads, nestedRecordings.length > 0 ? nestedRecordings : undefined);
+                // Enrich the already-loaded entities with their nested relations
+                for (const [entityId, entity] of relationResults) {
+                    const enrichedEntity = enrichItemWithLoadedRelations(entity, nestedResults);
+                    relationResults.set(entityId, enrichedEntity);
+                }
+            }
+        }
     }
     return results;
 }
 /**
- * Apply batch-loaded results to the mapped results
+ * Enrich an item with loaded relations, replacing thenable proxies with actual data
+ */
+function enrichItemWithLoadedRelations(item, loadedRelations) {
+    const enriched = { ...item };
+    for (const [relationName, relationData] of loadedRelations) {
+        const relationValue = item[relationName];
+        if (relationValue === undefined || relationValue === null) {
+            continue;
+        }
+        // Handle array relations
+        if (Array.isArray(relationValue)) {
+            const loadedArray = [];
+            for (const element of relationValue) {
+                const idStr = extractEntityId(element);
+                if (idStr) {
+                    const loaded = relationData.get(idStr);
+                    if (loaded) {
+                        loadedArray.push(loaded);
+                    }
+                }
+            }
+            enriched[relationName] = loadedArray;
+        }
+        else {
+            // Handle single relations - get the ID from the thenable proxy or direct value
+            const relationId = extractEntityId(relationValue);
+            if (relationId) {
+                const loaded = relationData.get(relationId);
+                if (loaded) {
+                    enriched[relationName] = loaded;
+                }
+            }
+        }
+    }
+    return enriched;
+}
+/**
+ * Apply batch-loaded results to the mapped results (deprecated, kept for compatibility)
  */
 function applyBatchResults(results, loadedRelations, originalItems) {
-    // For now, return results as-is
-    // Actual implementation would inject loaded relations
+    // No longer used - enrichment happens before callback re-run
     return results;
 }
 // =============================================================================
@@ -724,7 +1145,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;
 }
@@ -827,7 +1250,22 @@ export function wrapEntityOperations(typeName, operations, actionsAPI) {
                 executor: () => operations.list(listOptions),
                 actionsAPI,
             });
-            return listPromise.forEach(callback, options);
+            return listPromise.forEach(asCallback(callback), options);
+        },
+        // Semantic search methods
+        semanticSearch(query, options) {
+            if (operations.semanticSearch) {
+                return operations.semanticSearch(query, options);
+            }
+            // Fallback: return empty array if not supported
+            return Promise.resolve([]);
+        },
+        hybridSearch(query, options) {
+            if (operations.hybridSearch) {
+                return operations.hybridSearch(query, options);
+            }
+            // Fallback: return empty array if not supported
+            return Promise.resolve([]);
         },
         // Mutations don't need wrapping
         create: operations.create,