ai-database 2.1.3 → 2.3.0

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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"}