ai-database 2.1.3 → 2.3.0

package/dist/schema/migration.js

@@ -0,0 +1,327 @@
+/**
+ * Schema Migration Executor
+ *
+ * Provides utilities for defining and executing schema migrations.
+ * Supports forward (up) and backward (down) migrations with operations
+ * for adding, removing, renaming fields, and transforming data.
+ *
+ * @packageDocumentation
+ */
+import { getSchemaVersion, setSchemaVersion } from './version.js';
+// =============================================================================
+// Migration Definition Helper
+// =============================================================================
+/**
+ * Define a migration with type safety
+ *
+ * This helper function ensures the migration object has the correct shape
+ * and provides type inference for the operations.
+ *
+ * @param migration - The migration definition
+ * @returns The same migration definition (for chaining)
+ *
+ * @example
+ * ```ts
+ * const migration = defineMigration({
+ *   version: 2,
+ *   description: 'Add email field to User',
+ *   up: [
+ *     { type: 'addField', entityName: 'User', fieldName: 'email', fieldType: 'string' }
+ *   ],
+ *   down: [
+ *     { type: 'removeField', entityName: 'User', fieldName: 'email' }
+ *   ]
+ * })
+ * ```
+ */
+export function defineMigration(migration) {
+    // Validate migration structure
+    if (typeof migration.version !== 'number' || migration.version < 1) {
+        throw new Error(`Migration version must be a positive number, got: ${migration.version}`);
+    }
+    if (!migration.description || typeof migration.description !== 'string') {
+        throw new Error(`Migration version ${migration.version} must have a description`);
+    }
+    if (!Array.isArray(migration.up)) {
+        throw new Error(`Migration version ${migration.version} must have an 'up' operations array`);
+    }
+    if (!Array.isArray(migration.down)) {
+        throw new Error(`Migration version ${migration.version} must have a 'down' operations array`);
+    }
+    return migration;
+}
+// =============================================================================
+// Operation Execution
+// =============================================================================
+/**
+ * Execute a single migration operation
+ *
+ * @param provider - The database provider
+ * @param operation - The operation to execute
+ */
+async function executeOperation(provider, operation) {
+    switch (operation.type) {
+        case 'addEntity': {
+            // No action needed - the entity will be created when data is added
+            // This operation is primarily for documentation and down migration purposes
+            break;
+        }
+        case 'removeEntity': {
+            if (operation.deleteData) {
+                // Delete all entities of this type
+                const entities = await provider.list(operation.entityName);
+                for (const entity of entities) {
+                    const id = entity['$id'] || entity['id'];
+                    if (id) {
+                        await provider.delete(operation.entityName, id);
+                    }
+                }
+            }
+            break;
+        }
+        case 'addField': {
+            // Update existing entities with the default value
+            if (operation.defaultValue !== undefined) {
+                const entities = await provider.list(operation.entityName);
+                for (const entity of entities) {
+                    const id = entity['$id'] || entity['id'];
+                    if (id && entity[operation.fieldName] === undefined) {
+                        await provider.update(operation.entityName, id, {
+                            [operation.fieldName]: operation.defaultValue,
+                        });
+                    }
+                }
+            }
+            break;
+        }
+        case 'removeField': {
+            // Remove field from all entities
+            const entities = await provider.list(operation.entityName);
+            for (const entity of entities) {
+                const id = entity['$id'] || entity['id'];
+                if (id && entity[operation.fieldName] !== undefined) {
+                    // Create update object without the removed field
+                    const { [operation.fieldName]: _, ...rest } = entity;
+                    await provider.update(operation.entityName, id, {
+                        [operation.fieldName]: null, // Set to null to "remove"
+                    });
+                }
+            }
+            break;
+        }
+        case 'renameField': {
+            const entities = await provider.list(operation.entityName);
+            for (const entity of entities) {
+                const id = entity['$id'] || entity['id'];
+                if (id && entity[operation.oldFieldName] !== undefined) {
+                    await provider.update(operation.entityName, id, {
+                        [operation.newFieldName]: entity[operation.oldFieldName],
+                        [operation.oldFieldName]: null, // Remove old field
+                    });
+                }
+            }
+            break;
+        }
+        case 'changeType': {
+            const entities = await provider.list(operation.entityName);
+            for (const entity of entities) {
+                const id = entity['$id'] || entity['id'];
+                if (id && entity[operation.fieldName] !== undefined) {
+                    const oldValue = entity[operation.fieldName];
+                    const newValue = operation.transform ? operation.transform(oldValue) : oldValue;
+                    await provider.update(operation.entityName, id, {
+                        [operation.fieldName]: newValue,
+                    });
+                }
+            }
+            break;
+        }
+        case 'transformData': {
+            const entities = await provider.list(operation.entityName);
+            for (const entity of entities) {
+                // Apply filter if provided
+                if (operation.filter && !operation.filter(entity)) {
+                    continue;
+                }
+                const id = entity['$id'] || entity['id'];
+                if (id) {
+                    const transformed = operation.transform(entity);
+                    // Extract only the changed fields for update
+                    const updates = {};
+                    for (const [key, value] of Object.entries(transformed)) {
+                        if (key !== '$id' && key !== '$type' && value !== entity[key]) {
+                            updates[key] = value;
+                        }
+                    }
+                    if (Object.keys(updates).length > 0) {
+                        await provider.update(operation.entityName, id, updates);
+                    }
+                }
+            }
+            break;
+        }
+        default: {
+            // TypeScript exhaustiveness check
+            const _exhaustive = operation;
+            throw new Error(`Unknown operation type: ${_exhaustive.type}`);
+        }
+    }
+}
+// =============================================================================
+// Migration Execution
+// =============================================================================
+/**
+ * Run pending migrations on the database
+ *
+ * This function:
+ * 1. Gets the current schema version from the database
+ * 2. Finds all migrations with version > current version
+ * 3. Applies them in order
+ * 4. Updates the schema version after each successful migration
+ *
+ * @param provider - The database provider
+ * @param migrations - Array of migration definitions
+ * @param targetVersion - Optional: specific version to migrate to
+ * @returns Result of the migration run
+ *
+ * @example
+ * ```ts
+ * const migrations = [
+ *   defineMigration({
+ *     version: 1,
+ *     description: 'Initial schema',
+ *     up: [],
+ *     down: []
+ *   }),
+ *   defineMigration({
+ *     version: 2,
+ *     description: 'Add email to User',
+ *     up: [
+ *       { type: 'addField', entityName: 'User', fieldName: 'email', fieldType: 'string' }
+ *     ],
+ *     down: [
+ *       { type: 'removeField', entityName: 'User', fieldName: 'email' }
+ *     ]
+ *   })
+ * ]
+ *
+ * const result = await runMigrations(provider, migrations)
+ * console.log(`Migrated from v${result.fromVersion} to v${result.toVersion}`)
+ * ```
+ */
+export async function runMigrations(provider, migrations, targetVersion) {
+    // Sort migrations by version
+    const sortedMigrations = [...migrations].sort((a, b) => a.version - b.version);
+    // Validate version sequence
+    for (let i = 0; i < sortedMigrations.length; i++) {
+        if (sortedMigrations[i].version !== i + 1) {
+            throw new Error(`Migration versions must be sequential starting from 1. ` +
+                `Expected version ${i + 1}, got ${sortedMigrations[i].version}`);
+        }
+    }
+    // Get current version
+    const versionInfo = await getSchemaVersion(provider);
+    const currentVersion = versionInfo?.version ?? 0;
+    const finalTargetVersion = targetVersion ?? sortedMigrations[sortedMigrations.length - 1]?.version ?? 0;
+    const result = {
+        migrationsRun: false,
+        fromVersion: currentVersion === 0 ? null : currentVersion,
+        toVersion: currentVersion,
+        appliedMigrations: [],
+        errors: [],
+    };
+    // Determine direction
+    if (finalTargetVersion > currentVersion) {
+        // Forward migration
+        for (const migration of sortedMigrations) {
+            if (migration.version <= currentVersion)
+                continue;
+            if (migration.version > finalTargetVersion)
+                break;
+            try {
+                // Execute all up operations
+                for (const operation of migration.up) {
+                    await executeOperation(provider, operation);
+                }
+                // Update version after successful migration
+                await setSchemaVersion(provider, migration.version, `v${migration.version}`, migration.description);
+                result.appliedMigrations.push(migration.version);
+                result.toVersion = migration.version;
+                result.migrationsRun = true;
+            }
+            catch (error) {
+                result.errors.push({
+                    version: migration.version,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+                // Stop on first error
+                break;
+            }
+        }
+    }
+    else if (finalTargetVersion < currentVersion) {
+        // Backward migration (rollback)
+        const reversedMigrations = [...sortedMigrations].reverse();
+        for (const migration of reversedMigrations) {
+            if (migration.version > currentVersion)
+                continue;
+            if (migration.version <= finalTargetVersion)
+                break;
+            try {
+                // Execute all down operations
+                for (const operation of migration.down) {
+                    await executeOperation(provider, operation);
+                }
+                // Update version after successful rollback
+                const newVersion = migration.version - 1;
+                await setSchemaVersion(provider, newVersion, `v${newVersion}`, `Rolled back from v${migration.version}`);
+                result.appliedMigrations.push(migration.version);
+                result.toVersion = newVersion;
+                result.migrationsRun = true;
+            }
+            catch (error) {
+                result.errors.push({
+                    version: migration.version,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+                // Stop on first error
+                break;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Get pending migrations that need to be run
+ *
+ * @param provider - The database provider
+ * @param migrations - Array of migration definitions
+ * @returns Array of migrations that haven't been applied yet
+ */
+export async function getPendingMigrations(provider, migrations) {
+    const versionInfo = await getSchemaVersion(provider);
+    const currentVersion = versionInfo?.version ?? 0;
+    return migrations.filter((m) => m.version > currentVersion).sort((a, b) => a.version - b.version);
+}
+/**
+ * Rollback the last applied migration
+ *
+ * @param provider - The database provider
+ * @param migrations - Array of migration definitions
+ * @returns Result of the rollback
+ */
+export async function rollbackLastMigration(provider, migrations) {
+    const versionInfo = await getSchemaVersion(provider);
+    const currentVersion = versionInfo?.version ?? 0;
+    if (currentVersion === 0) {
+        return {
+            migrationsRun: false,
+            fromVersion: null,
+            toVersion: 0,
+            appliedMigrations: [],
+            errors: [],
+        };
+    }
+    return runMigrations(provider, migrations, currentVersion - 1);
+}
+//# sourceMappingURL=migration.js.map

package/dist/schema/migration.js.map

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

package/dist/schema/nl-query-generator.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Default Natural Language Query Generator
+ *
+ * Uses generateObject from ai-functions to convert natural language
+ * queries into structured query plans that can be executed against the database.
+ *
+ * @packageDocumentation
+ */
+import type { NLQueryGenerator } from './types.js';
+/**
+ * Create a default NL query generator that uses generateObject from ai-functions
+ *
+ * This generator converts natural language queries into structured query plans
+ * using the LLM configured via configureAIGeneration().
+ *
+ * @returns An NLQueryGenerator function
+ *
+ * @example
+ * ```ts
+ * import { setNLQueryGenerator } from 'ai-database'
+ * import { createDefaultNLQueryGenerator } from 'ai-database/schema/nl-query-generator'
+ *
+ * // Configure the default generator
+ * const generator = createDefaultNLQueryGenerator()
+ * setNLQueryGenerator(generator)
+ *
+ * // Now NL queries will use the LLM
+ * const results = await db.Lead`find high scoring leads`
+ * ```
+ */
+export declare function createDefaultNLQueryGenerator(): NLQueryGenerator;
+/**
+ * Check if a value matches a MongoDB-style filter condition
+ *
+ * Supports the following operators:
+ * - `$eq` - Equal to
+ * - `$ne` - Not equal to
+ * - `$gt` - Greater than (works with numbers and dates)
+ * - `$gte` - Greater than or equal to
+ * - `$lt` - Less than
+ * - `$lte` - Less than or equal to
+ * - `$in` - Value is in array
+ * - `$nin` - Value is not in array
+ * - `$exists` - Field exists (or doesn't exist if false)
+ * - `$regex` - Regular expression match (string values only)
+ *
+ * @param value - The value to check
+ * @param condition - The filter condition (can be a value or operator object)
+ * @returns Whether the value matches the condition
+ *
+ * @example
+ * ```ts
+ * matchesFilter(75, { $gt: 70 }) // true
+ * matchesFilter('active', 'active') // true
+ * matchesFilter(new Date('2024-01-15'), { $gt: new Date('2024-01-01') }) // true
+ * matchesFilter('enterprise', { $regex: 'enter' }) // true
+ * ```
+ */
+export declare function matchesFilter(value: unknown, condition: unknown): boolean;
+/**
+ * Apply filters to a list of entities
+ *
+ * @param entities - The entities to filter
+ * @param filters - The filter conditions to apply
+ * @returns The filtered entities
+ */
+export declare function applyFilters<T extends Record<string, unknown>>(entities: T[], filters: Record<string, unknown> | undefined): T[];
+//# sourceMappingURL=nl-query-generator.d.ts.map

package/dist/schema/nl-query-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nl-query-generator.d.ts","sourceRoot":"","sources":["../../src/schema/nl-query-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAA+B,gBAAgB,EAAE,MAAM,YAAY,CAAA;AA8D/E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,6BAA6B,IAAI,gBAAgB,CA4HhE;AA+BD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,GAAG,OAAO,CAmFzE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,QAAQ,EAAE,CAAC,EAAE,EACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC3C,CAAC,EAAE,CAcL"}