ai-database 2.1.1 → 2.3.0

package/dist/schema/verb-derivation.js

@@ -0,0 +1,281 @@
+/**
+ * Verb Derivation for Backward Cascade Resolution
+ *
+ * Derives reverse verbs for backward relationships:
+ * - manages -> managedBy
+ * - owns -> ownedBy
+ * - creates -> createdBy
+ * - parent_of <-> child_of (bidirectional)
+ *
+ * Used by the cascade resolver to determine the reverse relationship
+ * when traversing relationships in the opposite direction.
+ *
+ * @example
+ * ```ts
+ * import { deriveReverseVerb, fieldNameToVerb, isPassiveVerb } from './verb-derivation.js'
+ *
+ * deriveReverseVerb('manages')     // 'managedBy'
+ * deriveReverseVerb('parent_of')   // 'child_of'
+ * deriveReverseVerb('managedBy')   // 'manages'
+ *
+ * fieldNameToVerb('manager')       // 'manages'
+ * fieldNameToVerb('owner')         // 'owns'
+ *
+ * isPassiveVerb('managedBy')       // true
+ * isPassiveVerb('manages')         // false
+ * ```
+ *
+ * @packageDocumentation
+ */
+// =============================================================================
+// Forward to Reverse Verb Mapping
+// =============================================================================
+/**
+ * Mutable copy for runtime registration of custom verb pairs.
+ * Initialized from INITIAL_FORWARD_TO_REVERSE.
+ */
+const _forwardToReverse = {
+    manages: 'managedBy',
+    owns: 'ownedBy',
+    creates: 'createdBy',
+    reviews: 'reviewedBy',
+    employs: 'employedBy',
+    contains: 'containedBy',
+    assigns: 'assignedBy',
+};
+/**
+ * Mutable copy for runtime registration of reverse to forward mappings.
+ */
+const _reverseToForward = {
+    managedBy: 'manages',
+    ownedBy: 'owns',
+    createdBy: 'creates',
+    reviewedBy: 'reviews',
+    employedBy: 'employs',
+    containedBy: 'contains',
+    assignedBy: 'assigns',
+};
+/**
+ * Forward verbs to their reverse forms.
+ * Common active verbs mapped to their passive counterparts.
+ *
+ * @example
+ * ```ts
+ * FORWARD_TO_REVERSE.manages   // 'managedBy'
+ * FORWARD_TO_REVERSE.owns      // 'ownedBy'
+ * FORWARD_TO_REVERSE.creates   // 'createdBy'
+ * ```
+ */
+export const FORWARD_TO_REVERSE = _forwardToReverse;
+// =============================================================================
+// Bidirectional Pairs
+// =============================================================================
+/**
+ * Mutable copy for runtime registration of bidirectional pairs.
+ */
+const _bidirectionalPairs = {
+    parent_of: 'child_of',
+    child_of: 'parent_of',
+};
+/**
+ * Known verb pairs for bidirectional relationships.
+ * These are symmetric - each maps to the other.
+ *
+ * @example
+ * ```ts
+ * BIDIRECTIONAL_PAIRS.parent_of  // 'child_of'
+ * BIDIRECTIONAL_PAIRS.child_of   // 'parent_of'
+ * ```
+ */
+export const BIDIRECTIONAL_PAIRS = _bidirectionalPairs;
+// =============================================================================
+// Field Name to Verb Mapping
+// =============================================================================
+/**
+ * Mutable copy for runtime registration of field to verb mappings.
+ */
+const _fieldToVerb = {
+    manager: 'manages',
+    owner: 'owns',
+    creator: 'creates',
+    reviewer: 'reviews',
+    employer: 'employs',
+    parent: 'parent_of',
+    child: 'child_of',
+    assignee: 'assigns',
+};
+// =============================================================================
+// Core Functions
+// =============================================================================
+/**
+ * Derives the reverse verb for a given forward verb.
+ *
+ * Resolution order:
+ * 1. Check bidirectional pairs first (parent_of <-> child_of)
+ * 2. Check known forward verbs (manages -> managedBy)
+ * 3. Check if already a reversed verb (managedBy -> manages)
+ * 4. Apply standard transformation for verbs ending in 's'
+ * 5. Add 'By' suffix for unknown verbs
+ *
+ * @param verb - The verb to derive the reverse of
+ * @returns The reverse verb
+ *
+ * @example
+ * ```ts
+ * deriveReverseVerb('manages')        // 'managedBy'
+ * deriveReverseVerb('owns')           // 'ownedBy'
+ * deriveReverseVerb('parent_of')      // 'child_of'
+ * deriveReverseVerb('managedBy')      // 'manages' (already reversed)
+ * deriveReverseVerb('customAction')   // 'customActionBy' (unknown verb)
+ * ```
+ */
+export function deriveReverseVerb(verb) {
+    // Check bidirectional pairs first
+    if (verb in _bidirectionalPairs) {
+        return _bidirectionalPairs[verb];
+    }
+    // Check known forward verbs
+    if (verb in _forwardToReverse) {
+        return _forwardToReverse[verb];
+    }
+    // Check if this is already a reversed verb (ends with 'By')
+    if (verb in _reverseToForward) {
+        return _reverseToForward[verb];
+    }
+    // Check if verb ends with 'By' - try to find its forward form
+    if (verb.endsWith('By')) {
+        // Check if there's a known forward form
+        const forwardVerb = _reverseToForward[verb];
+        if (forwardVerb) {
+            return forwardVerb;
+        }
+        // Otherwise just return the base (customActionBy -> customAction)
+        return verb.slice(0, -2);
+    }
+    // Apply standard verb transformation for third person singular verbs
+    // (verbs ending in 's' like manages, owns, creates, reviews, employs, contains)
+    if (verb.endsWith('s') && verb.length > 2) {
+        // Remove trailing 's' to get base form, then add 'edBy'
+        // manages -> manage -> managedBy
+        // owns -> own -> ownedBy
+        // creates -> create -> createdBy
+        const base = verb.slice(0, -1);
+        return base + 'dBy';
+    }
+    // For other verbs, just add 'By' suffix
+    return verb + 'By';
+}
+/**
+ * Derives a verb from a field name.
+ *
+ * Common field names like "manager", "owner", "creator" are mapped
+ * to their corresponding verbs. Unknown field names are returned as-is.
+ *
+ * @param fieldName - The field name to derive a verb from
+ * @returns The derived verb or the field name if no mapping exists
+ *
+ * @example
+ * ```ts
+ * fieldNameToVerb('manager')     // 'manages'
+ * fieldNameToVerb('owner')       // 'owns'
+ * fieldNameToVerb('creator')     // 'creates'
+ * fieldNameToVerb('customField') // 'customField' (no mapping)
+ * ```
+ */
+export function fieldNameToVerb(fieldName) {
+    return _fieldToVerb[fieldName] ?? fieldName;
+}
+/**
+ * Checks if a verb is in passive form.
+ *
+ * A verb is considered passive if it ends with:
+ * - 'By' (managedBy, ownedBy, createdBy)
+ * - 'To' (relatedTo, linkedTo, connectedTo)
+ * - 'Of' (parent_of, child_of, partOf)
+ *
+ * @param verb - The verb to check
+ * @returns True if the verb is passive, false otherwise
+ *
+ * @example
+ * ```ts
+ * isPassiveVerb('managedBy')   // true
+ * isPassiveVerb('relatedTo')   // true
+ * isPassiveVerb('parent_of')   // true
+ * isPassiveVerb('manages')     // false
+ * ```
+ */
+export function isPassiveVerb(verb) {
+    if (verb.length === 0) {
+        return false;
+    }
+    // Check for common passive suffixes
+    return (verb.endsWith('By') ||
+        verb.endsWith('To') ||
+        verb.endsWith('Of') ||
+        verb.endsWith('_of'));
+}
+// =============================================================================
+// Extensibility Functions
+// =============================================================================
+/**
+ * Register a custom verb pair for forward/reverse derivation.
+ *
+ * This allows extending the verb derivation system with domain-specific
+ * verb mappings at runtime.
+ *
+ * @param forward - The forward (active) verb
+ * @param reverse - The reverse (passive) verb
+ *
+ * @example
+ * ```ts
+ * registerVerbPair('sponsors', 'sponsoredBy')
+ * deriveReverseVerb('sponsors')     // 'sponsoredBy'
+ * deriveReverseVerb('sponsoredBy')  // 'sponsors'
+ * ```
+ */
+export function registerVerbPair(forward, reverse) {
+    _forwardToReverse[forward] = reverse;
+    _reverseToForward[reverse] = forward;
+}
+/**
+ * Register a bidirectional verb pair.
+ *
+ * Bidirectional pairs are symmetric relationships where each verb
+ * maps to the other. For self-referential relationships, both
+ * arguments can be the same verb.
+ *
+ * @param verbA - The first verb
+ * @param verbB - The second verb (can be same as verbA for symmetric)
+ *
+ * @example
+ * ```ts
+ * // Asymmetric bidirectional
+ * registerBidirectionalPair('mentor_of', 'mentee_of')
+ * deriveReverseVerb('mentor_of')  // 'mentee_of'
+ * deriveReverseVerb('mentee_of')  // 'mentor_of'
+ *
+ * // Symmetric (self-referential)
+ * registerBidirectionalPair('relatedTo', 'relatedTo')
+ * deriveReverseVerb('relatedTo')  // 'relatedTo'
+ * ```
+ */
+export function registerBidirectionalPair(verbA, verbB) {
+    _bidirectionalPairs[verbA] = verbB;
+    _bidirectionalPairs[verbB] = verbA;
+}
+/**
+ * Register a field name to verb mapping.
+ *
+ * @param fieldName - The field name
+ * @param verb - The verb it derives to
+ *
+ * @example
+ * ```ts
+ * registerFieldVerb('coordinator', 'coordinates')
+ * fieldNameToVerb('coordinator')  // 'coordinates'
+ * ```
+ */
+export function registerFieldVerb(fieldName, verb) {
+    _fieldToVerb[fieldName] = verb;
+}
+//# sourceMappingURL=verb-derivation.js.map

package/dist/schema/verb-derivation.js.map

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

package/dist/schema/version.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Schema Version Tracking
+ *
+ * Provides utilities for tracking schema versions, computing schema hashes,
+ * and storing/retrieving version metadata from the database.
+ *
+ * @packageDocumentation
+ */
+import type { DatabaseSchema } from '../types.js';
+import type { DBProvider } from './provider.js';
+/**
+ * Schema version metadata stored in the database
+ */
+export interface SchemaVersionInfo {
+    /** The version number (incremented on each migration) */
+    version: number;
+    /** Hash of the schema structure for change detection */
+    schemaHash: string;
+    /** When this version was applied */
+    appliedAt?: string;
+    /** Description of the migration (if any) */
+    description?: string;
+}
+/**
+ * Compute a deterministic hash of a database schema
+ *
+ * The hash is computed by:
+ * 1. Sorting entity names alphabetically
+ * 2. For each entity, sorting field names alphabetically
+ * 3. Creating a normalized JSON representation
+ * 4. Computing a hash of the JSON string
+ *
+ * This ensures the same schema always produces the same hash,
+ * regardless of property insertion order in the original object.
+ *
+ * @param schema - The database schema to hash
+ * @returns A hex string hash of the schema
+ *
+ * @example
+ * ```ts
+ * const hash = computeSchemaHash({
+ *   User: { name: 'string', email: 'string' },
+ *   Post: { title: 'string', author: 'User.posts' }
+ * })
+ * // => '8a7b3c9d...'
+ * ```
+ */
+export declare function computeSchemaHash(schema: DatabaseSchema): string;
+/**
+ * Get the current schema version from the database
+ *
+ * Reads the _schema_meta entity to retrieve the current schema version
+ * and hash. Returns null if no version has been set yet (first run).
+ *
+ * @param provider - The database provider
+ * @returns The current schema version info, or null if not set
+ *
+ * @example
+ * ```ts
+ * const version = await getSchemaVersion(provider)
+ * if (version) {
+ *   console.log(`Current version: ${version.version}`)
+ *   console.log(`Schema hash: ${version.schemaHash}`)
+ * } else {
+ *   console.log('No schema version set - first run')
+ * }
+ * ```
+ */
+export declare function getSchemaVersion(provider: DBProvider): Promise<SchemaVersionInfo | null>;
+/**
+ * Set the schema version in the database
+ *
+ * Stores the schema version and hash as a _schema_meta entity.
+ * Creates the entity if it doesn't exist, or updates it if it does.
+ *
+ * @param provider - The database provider
+ * @param version - The new version number
+ * @param schemaHash - The hash of the current schema
+ * @param description - Optional description of the migration
+ *
+ * @example
+ * ```ts
+ * await setSchemaVersion(provider, 1, 'abc123', 'Initial schema')
+ * await setSchemaVersion(provider, 2, 'def456', 'Added email field to User')
+ * ```
+ */
+export declare function setSchemaVersion(provider: DBProvider, version: number, schemaHash: string, description?: string): Promise<void>;
+/**
+ * Check if the schema has changed since the last recorded version
+ *
+ * Compares the current schema hash with the stored hash to detect changes.
+ *
+ * @param provider - The database provider
+ * @param schema - The current schema definition
+ * @returns Object with changed status and hashes
+ *
+ * @example
+ * ```ts
+ * const { changed, currentHash, storedHash } = await hasSchemaChanged(provider, schema)
+ * if (changed) {
+ *   console.log('Schema has changed, migration may be needed')
+ * }
+ * ```
+ */
+export declare function hasSchemaChanged(provider: DBProvider, schema: DatabaseSchema): Promise<{
+    changed: boolean;
+    currentHash: string;
+    storedHash: string | null;
+    storedVersion: number | null;
+}>;
+//# sourceMappingURL=version.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/schema/version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAM/C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAA;IACf,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAA;IAClB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAgBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAuChE;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CA6B9F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,UAAU,EACpB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,UAAU,EACpB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC;IACT,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B,CAAC,CAUD"}

package/dist/schema/version.js

@@ -0,0 +1,190 @@
+/**
+ * Schema Version Tracking
+ *
+ * Provides utilities for tracking schema versions, computing schema hashes,
+ * and storing/retrieving version metadata from the database.
+ *
+ * @packageDocumentation
+ */
+// =============================================================================
+// Constants
+// =============================================================================
+/** Entity type for storing schema metadata */
+const SCHEMA_META_TYPE = 'SchemaMeta';
+/** ID for the schema version record */
+const SCHEMA_VERSION_ID = 'current';
+// =============================================================================
+// Hash Computation
+// =============================================================================
+/**
+ * Compute a deterministic hash of a database schema
+ *
+ * The hash is computed by:
+ * 1. Sorting entity names alphabetically
+ * 2. For each entity, sorting field names alphabetically
+ * 3. Creating a normalized JSON representation
+ * 4. Computing a hash of the JSON string
+ *
+ * This ensures the same schema always produces the same hash,
+ * regardless of property insertion order in the original object.
+ *
+ * @param schema - The database schema to hash
+ * @returns A hex string hash of the schema
+ *
+ * @example
+ * ```ts
+ * const hash = computeSchemaHash({
+ *   User: { name: 'string', email: 'string' },
+ *   Post: { title: 'string', author: 'User.posts' }
+ * })
+ * // => '8a7b3c9d...'
+ * ```
+ */
+export function computeSchemaHash(schema) {
+    // Create a normalized representation with sorted keys
+    const normalized = {};
+    // Sort entity names
+    const entityNames = Object.keys(schema).sort();
+    for (const entityName of entityNames) {
+        const entitySchema = schema[entityName];
+        const normalizedEntity = {};
+        // Sort field names within each entity
+        const fieldNames = Object.keys(entitySchema).sort();
+        for (const fieldName of fieldNames) {
+            const fieldDef = entitySchema[fieldName];
+            // Normalize array definitions to string representation
+            if (Array.isArray(fieldDef)) {
+                normalizedEntity[fieldName] = `[${fieldDef[0]}]`;
+            }
+            else {
+                normalizedEntity[fieldName] = fieldDef;
+            }
+        }
+        normalized[entityName] = normalizedEntity;
+    }
+    // Create JSON string and compute hash
+    const jsonString = JSON.stringify(normalized);
+    // Simple hash function (djb2 algorithm)
+    let hash = 5381;
+    for (let i = 0; i < jsonString.length; i++) {
+        const char = jsonString.charCodeAt(i);
+        hash = ((hash << 5) + hash) ^ char;
+    }
+    // Convert to positive hex string
+    return Math.abs(hash).toString(16).padStart(8, '0');
+}
+// =============================================================================
+// Version Storage
+// =============================================================================
+/**
+ * Get the current schema version from the database
+ *
+ * Reads the _schema_meta entity to retrieve the current schema version
+ * and hash. Returns null if no version has been set yet (first run).
+ *
+ * @param provider - The database provider
+ * @returns The current schema version info, or null if not set
+ *
+ * @example
+ * ```ts
+ * const version = await getSchemaVersion(provider)
+ * if (version) {
+ *   console.log(`Current version: ${version.version}`)
+ *   console.log(`Schema hash: ${version.schemaHash}`)
+ * } else {
+ *   console.log('No schema version set - first run')
+ * }
+ * ```
+ */
+export async function getSchemaVersion(provider) {
+    try {
+        const record = await provider.get(SCHEMA_META_TYPE, SCHEMA_VERSION_ID);
+        if (!record) {
+            return null;
+        }
+        const result = {
+            version: record['version'],
+            schemaHash: record['schemaHash'],
+        };
+        if (record['appliedAt'] !== undefined) {
+            result.appliedAt = record['appliedAt'];
+        }
+        if (record['description'] !== undefined) {
+            result.description = record['description'];
+        }
+        return result;
+    }
+    catch (error) {
+        // If the entity type doesn't exist yet, that's fine - return null
+        if (error instanceof Error &&
+            (error.message.includes('not found') || error.message.includes('does not exist'))) {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Set the schema version in the database
+ *
+ * Stores the schema version and hash as a _schema_meta entity.
+ * Creates the entity if it doesn't exist, or updates it if it does.
+ *
+ * @param provider - The database provider
+ * @param version - The new version number
+ * @param schemaHash - The hash of the current schema
+ * @param description - Optional description of the migration
+ *
+ * @example
+ * ```ts
+ * await setSchemaVersion(provider, 1, 'abc123', 'Initial schema')
+ * await setSchemaVersion(provider, 2, 'def456', 'Added email field to User')
+ * ```
+ */
+export async function setSchemaVersion(provider, version, schemaHash, description) {
+    const data = {
+        version,
+        schemaHash,
+        appliedAt: new Date().toISOString(),
+    };
+    if (description !== undefined) {
+        data['description'] = description;
+    }
+    // Try to get existing record
+    const existing = await provider.get(SCHEMA_META_TYPE, SCHEMA_VERSION_ID);
+    if (existing) {
+        // Update existing record
+        await provider.update(SCHEMA_META_TYPE, SCHEMA_VERSION_ID, data);
+    }
+    else {
+        // Create new record
+        await provider.create(SCHEMA_META_TYPE, SCHEMA_VERSION_ID, data);
+    }
+}
+/**
+ * Check if the schema has changed since the last recorded version
+ *
+ * Compares the current schema hash with the stored hash to detect changes.
+ *
+ * @param provider - The database provider
+ * @param schema - The current schema definition
+ * @returns Object with changed status and hashes
+ *
+ * @example
+ * ```ts
+ * const { changed, currentHash, storedHash } = await hasSchemaChanged(provider, schema)
+ * if (changed) {
+ *   console.log('Schema has changed, migration may be needed')
+ * }
+ * ```
+ */
+export async function hasSchemaChanged(provider, schema) {
+    const currentHash = computeSchemaHash(schema);
+    const versionInfo = await getSchemaVersion(provider);
+    return {
+        changed: versionInfo === null || versionInfo.schemaHash !== currentHash,
+        currentHash,
+        storedHash: versionInfo?.schemaHash ?? null,
+        storedVersion: versionInfo?.version ?? null,
+    };
+}
+//# sourceMappingURL=version.js.map

package/dist/schema/version.js.map

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