ai-database 2.1.3 → 2.3.0

package/dist/rdb-provider-adapter.js

@@ -0,0 +1,291 @@
+/**
+ * RDB Provider Adapter
+ *
+ * Adapts RDB's DBProvider interface to ai-database's DBProvider interface.
+ *
+ * The key interface mismatch addressed:
+ * - ai-database search(): (type: string, query: string, options?: SearchOptions) => Promise<Record[]>
+ * - RDB search(): (type: string, filter: Filter, options?: SearchOptions) => Promise<Entity[]>
+ *
+ * This adapter:
+ * 1. Converts ai-database's string query to RDB's Filter object (using $regex for text search)
+ * 2. Normalizes RDB entities (id/type) to ai-database format ($id/$type)
+ * 3. Maintains full compatibility with ai-database's DBProvider interface
+ *
+ * @example
+ * ```ts
+ * import { RDB } from '@dotdo/rdb'
+ * import { RDBProviderAdapter } from 'ai-database'
+ * import { DB, setProvider } from 'ai-database'
+ *
+ * // Create RDB instance (Cloudflare D1/DO SQLite)
+ * const rdb = new RDB(sqlStorage)
+ *
+ * // Wrap with adapter for ai-database compatibility
+ * const adapter = new RDBProviderAdapter(rdb)
+ * setProvider(adapter)
+ *
+ * // Now use ai-database's schema-first API
+ * const { db } = DB({
+ *   User: { name: 'string', email: 'string' },
+ *   Post: { title: 'string', author: '->User' }
+ * })
+ *
+ * // search() works with string queries (adapter converts to Filter)
+ * const results = await db.Post.search('TypeScript')
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Normalizes an RDB entity to ai-database format
+ *
+ * RDB uses: { id: 'xxx', type: 'User', name: 'John' }
+ * ai-database uses: { $id: 'xxx', $type: 'User', name: 'John' }
+ */
+function normalizeEntity(entity) {
+    const { id, type, ...rest } = entity;
+    return {
+        $id: id,
+        $type: type,
+        ...rest,
+    };
+}
+/**
+ * Default fields to search when no specific fields are provided.
+ * These are common text fields found in most entity types.
+ */
+const DEFAULT_SEARCH_FIELDS = ['title', 'name', 'content', 'description', 'body', 'text'];
+/**
+ * Converts a string search query to an RDB Filter object
+ *
+ * By default, creates a $regex filter that searches across all string fields.
+ * If fields option is provided, restricts search to those fields.
+ *
+ * @param query - The search string
+ * @param field - The specific field to search
+ * @returns Filter object for RDB search()
+ */
+function stringQueryToFilter(query, field) {
+    // Escape regex special characters in the query
+    const escapedQuery = query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return {
+        [field]: { $regex: escapedQuery },
+    };
+}
+/**
+ * Get the list of fields to search
+ *
+ * @param options - Search options that may include specific fields
+ * @returns Array of field names to search
+ */
+function getSearchFields(options) {
+    if (options?.fields && options.fields.length > 0) {
+        return options.fields;
+    }
+    return DEFAULT_SEARCH_FIELDS;
+}
+/**
+ * RDB Provider Adapter
+ *
+ * Wraps an RDB DBProvider to make it compatible with ai-database's DBProvider interface.
+ * The primary adaptation is converting string search queries to RDB Filter objects.
+ */
+export class RDBProviderAdapter {
+    rdb;
+    /**
+     * Create a new RDBProviderAdapter
+     *
+     * @param rdb - An RDB DBProvider instance (from RDB class or D1Provider/DOProvider)
+     */
+    constructor(rdb) {
+        this.rdb = rdb;
+    }
+    /**
+     * Get an entity by type and ID
+     */
+    async get(type, id) {
+        const entity = await this.rdb.get(type, id);
+        return entity ? normalizeEntity(entity) : null;
+    }
+    /**
+     * List entities of a type
+     *
+     * If a `where` filter is provided, we apply it client-side after fetching
+     * since RDB's list() method doesn't support where filters natively.
+     */
+    async list(type, options) {
+        const listOptions = {};
+        // If we have where filters, we need to fetch all and filter client-side
+        // We apply pagination after filtering
+        const hasWhereFilter = options?.where && Object.keys(options.where).length > 0;
+        if (!hasWhereFilter) {
+            if (options?.limit !== undefined) {
+                listOptions.limit = options.limit;
+            }
+            if (options?.offset !== undefined) {
+                listOptions.offset = options.offset;
+            }
+        }
+        if (options?.orderBy !== undefined) {
+            listOptions.orderBy = options.orderBy;
+        }
+        if (options?.order !== undefined) {
+            listOptions.order = options.order;
+        }
+        let entities = await this.rdb.list(type, listOptions);
+        // Apply where filter client-side
+        if (hasWhereFilter && options?.where) {
+            const whereFilter = options.where;
+            entities = entities.filter((entity) => {
+                for (const [key, value] of Object.entries(whereFilter)) {
+                    if (entity[key] !== value) {
+                        return false;
+                    }
+                }
+                return true;
+            });
+        }
+        let results = entities.map(normalizeEntity);
+        // Apply pagination after client-side filtering
+        if (hasWhereFilter) {
+            if (options?.offset) {
+                results = results.slice(options.offset);
+            }
+            if (options?.limit) {
+                results = results.slice(0, options.limit);
+            }
+        }
+        return results;
+    }
+    /**
+     * Search entities using a string query
+     *
+     * This is the key adaptation point:
+     * - ai-database expects: search(type, query: string)
+     * - RDB expects: search(type, filter: Filter)
+     *
+     * The adapter converts the string query to $regex Filters for text search.
+     * Since RDB doesn't support $or at the top level, we search each field
+     * separately and deduplicate results.
+     */
+    async search(type, query, options) {
+        const fields = getSearchFields(options);
+        const seenIds = new Set();
+        const results = [];
+        // Search each field and collect unique results
+        // This is necessary because RDB doesn't support $or at the top level
+        for (const field of fields) {
+            const filter = stringQueryToFilter(query, field);
+            try {
+                const entities = await this.rdb.search(type, filter, {
+                // Don't apply limit/offset per-field, we'll apply after deduplication
+                });
+                for (const entity of entities) {
+                    if (!seenIds.has(entity.id)) {
+                        seenIds.add(entity.id);
+                        results.push(normalizeEntity(entity));
+                    }
+                }
+            }
+            catch {
+                // Field might not exist on this entity type, continue to next field
+            }
+        }
+        // Apply where filter client-side
+        let finalResults = results;
+        if (options?.where && Object.keys(options.where).length > 0) {
+            const whereFilter = options.where;
+            finalResults = finalResults.filter((entity) => {
+                for (const [key, value] of Object.entries(whereFilter)) {
+                    if (entity[key] !== value) {
+                        return false;
+                    }
+                }
+                return true;
+            });
+        }
+        // Apply limit and offset after collecting and filtering all results
+        if (options?.offset) {
+            finalResults = finalResults.slice(options.offset);
+        }
+        if (options?.limit) {
+            finalResults = finalResults.slice(0, options.limit);
+        }
+        return finalResults;
+    }
+    /**
+     * Create a new entity
+     */
+    async create(type, id, data) {
+        const entity = await this.rdb.create(type, data, id);
+        return normalizeEntity(entity);
+    }
+    /**
+     * Update an existing entity
+     */
+    async update(type, id, data) {
+        const entity = await this.rdb.update(type, id, data);
+        return normalizeEntity(entity);
+    }
+    /**
+     * Delete an entity
+     *
+     * @returns true if deleted, false if entity didn't exist
+     */
+    async delete(type, id) {
+        try {
+            // Check if entity exists first
+            const existing = await this.rdb.get(type, id);
+            if (!existing) {
+                return false;
+            }
+            await this.rdb.delete(type, id);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get related entities
+     */
+    async related(type, id, relation) {
+        const entities = await this.rdb.related(type, id, relation, {
+            direction: 'outgoing',
+        });
+        return entities.map(normalizeEntity);
+    }
+    /**
+     * Create a relationship between entities
+     */
+    async relate(fromType, fromId, relation, toType, toId, metadata) {
+        await this.rdb.relate(fromType, fromId, relation, toType, toId, metadata);
+    }
+    /**
+     * Remove a relationship between entities
+     */
+    async unrelate(fromType, fromId, relation, toType, toId) {
+        await this.rdb.unrelate(fromType, fromId, relation, toType, toId);
+    }
+}
+/**
+ * Create an RDBProviderAdapter from an RDB instance
+ *
+ * @param rdb - An RDB DBProvider instance
+ * @returns Adapted provider compatible with ai-database
+ *
+ * @example
+ * ```ts
+ * import { RDB } from '@dotdo/rdb'
+ * import { createRDBAdapter, setProvider } from 'ai-database'
+ *
+ * const rdb = new RDB(sqlStorage)
+ * const adapter = createRDBAdapter(rdb)
+ * setProvider(adapter)
+ * ```
+ */
+export function createRDBAdapter(rdb) {
+    return new RDBProviderAdapter(rdb);
+}
+//# sourceMappingURL=rdb-provider-adapter.js.map

package/dist/rdb-provider-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rdb-provider-adapter.js","sourceRoot":"","sources":["../src/rdb-provider-adapter.ts"],"names":[],"mappings":"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"}

package/dist/schema/cascade.d.ts

@@ -8,24 +8,52 @@
  */
 import type { ParsedEntity, ParsedSchema } from '../types.js';
 import type { DBProvider } from './provider.js';
+import type { AIGenerationConfig } from './types.js';
+import type { ValueGenerator } from './value-generators/types.js';
+export type { AIGenerationConfig, GenerationDetails } from './types.js';
+/**
+ * Hard safety limit for cascade/entity generation recursion depth.
+ * Applied even when maxDepth is not explicitly configured to prevent
+ * infinite recursion with circular schemas.
+ */
+export declare const DEFAULT_MAX_DEPTH = 10;
+/**
+ * Configure the value generator to use for field generation
+ *
+ * @param generator - The value generator instance to use
+ */
+export declare function setValueGenerator(generator: ValueGenerator): void;
+/**
+ * Get the current value generator
+ *
+ * @returns The current value generator instance
+ */
+export declare function getValueGenerator(): ValueGenerator;
+/**
+ * Configure AI generation settings
+ *
+ * @param config - Partial configuration to merge with defaults
+ */
+export declare function configureAIGeneration(config: Partial<AIGenerationConfig>): void;
+/**
+ * Get current AI generation configuration
+ */
+export declare function getAIGenerationConfig(): AIGenerationConfig;
 /**
  * Generate a context-aware value for a field
  *
- * Uses hint, instructions, schema context, and parent data to generate
- * contextually appropriate values. This is a minimal deterministic implementation
- * for testing - real AI generation would integrate with LLMs.
+ * **DELEGATED TO VALUE-GENERATORS MODULE**
  *
- * The function uses keyword matching on the context and hint to produce
- * contextually relevant values for common field names like 'name', 'description',
- * 'headline', 'background', etc.
+ * This function now delegates to PlaceholderValueGenerator for backward
+ * compatibility. The actual generation logic has been extracted to:
+ * `./value-generators/placeholder.ts`
  *
- * **PLACEHOLDER IMPLEMENTATION**: This function contains hardcoded test values
- * and keyword-based generation rules. In a production system, this would be
- * replaced with actual AI/LLM integration to generate contextually appropriate
- * content. The current implementation is designed to:
- * - Provide deterministic, predictable outputs for testing
- * - Demonstrate the expected behavior and API contract
- * - Allow tests to make specific assertions about generated content
+ * For new code, prefer using the ValueGenerator interface directly:
+ * ```ts
+ * import { getValueGenerator } from './value-generators/index.js'
+ * const generator = getValueGenerator()
+ * const result = await generator.generate({ fieldName, type, fullContext, hint, parentData })
+ * ```
  *
  * @param fieldName - The name of the field being generated
  * @param type - The entity type name
@@ -55,25 +83,28 @@ export declare function generateContextAwareValue(fieldName: string, type: strin
  * @param entityDef - The parsed entity definition
  * @param schema - The parsed schema
  * @param provider - The database provider
+ * @param injectedConfig - Optional AI config to use instead of module-level config (for DI)
  * @returns The data with AI-generated fields populated
  */
-export declare function generateAIFields(data: Record<string, unknown>, typeName: string, entityDef: ParsedEntity, schema: ParsedSchema, provider: DBProvider): Promise<Record<string, unknown>>;
+export declare function generateAIFields(data: Record<string, unknown>, typeName: string, entityDef: ParsedEntity, schema: ParsedSchema, provider: DBProvider, injectedConfig?: AIGenerationConfig): Promise<Record<string, unknown>>;
 /**
  * Generate an entity based on its type and context
  *
- * For testing, generates deterministic content based on the prompt and type.
- * In production, this would integrate with AI generation.
+ * Uses AI generation via generateObject from ai-functions when available,
+ * falling back to deterministic placeholder values for testing or when AI fails.
  *
  * @param type - The type of entity to generate
  * @param prompt - Optional prompt for generation context
  * @param context - Parent context information (parent type name, parentData, and optional parentId)
  * @param schema - The parsed schema
+ * @param _depth - Current recursion depth (internal)
+ * @param injectedConfig - Optional AI config to use instead of module-level config (for DI)
  */
 export declare function generateEntity(type: string, prompt: string | undefined, context: {
     parent: string;
     parentData: Record<string, unknown>;
     parentId?: string;
-}, schema: ParsedSchema): Promise<Record<string, unknown>>;
+}, schema: ParsedSchema, _depth?: number, injectedConfig?: AIGenerationConfig): Promise<Record<string, unknown>>;
 /**
  * Resolve forward exact (->) fields by auto-generating related entities
  *

package/dist/schema/cascade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cascade.d.ts","sourceRoot":"","sources":["../../src/schema/cascade.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACb,MAAM,aAAa,CAAA;AAEpB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAQ/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACvC,MAAM,CAyJR;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,YAAY,EACvB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,UAAU,GACnB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAuElC;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,EACnF,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA8DlC;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,gBAAgB,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAwGlI;AAMD;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,MAAM,CA4DR"}
+{"version":3,"file":"cascade.d.ts","sourceRoot":"","sources":["../../src/schema/cascade.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAG7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,KAAK,EAAE,kBAAkB,EAAqB,MAAM,YAAY,CAAA;AASvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAGjE,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEvE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAA;AAenC;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,CAEjE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAElD;AAYD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAE/E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,kBAAkB,CAE1D;AAmKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACvC,MAAM,CA0BR;AAmGD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,YAAY,EACvB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,UAAU,EACpB,cAAc,CAAC,EAAE,kBAAkB,GAClC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAuIlC;AAkED;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,EACnF,MAAM,EAAE,YAAY,EACpB,MAAM,GAAE,MAAU,EAClB,cAAc,CAAC,EAAE,kBAAkB,GAClC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAwFlC;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,gBAAgB,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACrF,CAAC,CAwHD;AAMD;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,MAAM,CAkER"}