edinburgh 0.4.4 → 0.4.6

package/src/migrate.ts

@@ -11,12 +11,14 @@ const INDEX_ID_PREFIX = -2;
 export interface MigrationOptions {
     /** Limit migration to specific table names. */
     tables?: string[];
-    /** Whether to convert old primary indices for known tables (default: true). */
-    convertOldPrimaries?: boolean;
-    /** Whether to delete orphaned secondary/unique indices (default: true). */
-    deleteOrphanedIndexes?: boolean;
-    /** Whether to upgrade rows to the latest version (default: true). */
-    upgradeVersions?: boolean;
+    /** Populate secondary indexes for rows at old schema versions (default: true). */
+    populateSecondaries?: boolean;
+    /** Convert old primary indices when primary key fields changed (default: true). */
+    migratePrimaries?: boolean;
+    /** Rewrite all row data to the latest schema version (default: false). */
+    rewriteData?: boolean;
+    /** Delete orphaned secondary/unique index entries (default: true). */
+    removeOrphans?: boolean;
     /** Progress callback. */
     onProgress?: (info: ProgressInfo) => void;
 }
@@ -29,14 +31,16 @@ export interface ProgressInfo {
 }
 
 export interface MigrationResult {
-    /** Per-table stats for row upgrades. */
+    /** Per-table counts of secondary index entries populated. */
     secondaries: Record<string, number>;
-    /** Per-table stats for old primary conversions. */
+    /** Per-table counts of old primary rows migrated. */
     primaries: Record<string, number>;
     /** Per-table conversion failure counts by reason. */
     conversionFailures: Record<string, Record<string, number>>;
+    /** Per-table counts of rows rewritten to latest version. */
+    rewritten: Record<string, number>;
     /** Number of orphaned index entries deleted. */
-    orphaned: number;
+    orphans: number;
 }
 
 interface IndexDef {
@@ -91,23 +95,25 @@ async function forEachRow(
 }
 
 /**
- * Run database migration: upgrade all rows to the latest schema version,
- * convert old primary indices, and clean up orphaned secondary indices.
+ * Run database migration: populate secondary indexes for old-version rows,
+ * convert old primary indices, rewrite row data, and clean up orphaned indices.
  */
 export async function runMigration(options: MigrationOptions = {}): Promise<MigrationResult> {
     // Ensure any pending model/index inits are completed before building index maps
     await transact(() => {});
 
-    const convertOldPrimaries = options.convertOldPrimaries ?? true;
-    const deleteOrphanedIndexes = options.deleteOrphanedIndexes ?? true;
-    const upgradeVersions = options.upgradeVersions ?? true;
+    const populateSecondaries = options.populateSecondaries ?? true;
+    const migratePrimaries = options.migratePrimaries ?? true;
+    const rewriteData = options.rewriteData ?? false;
+    const removeOrphans = options.removeOrphans ?? true;
     const onProgress = options.onProgress;
 
     const result: MigrationResult = {
         secondaries: {},
         primaries: {},
         conversionFailures: {},
-        orphaned: 0,
+        rewritten: {},
+        orphans: 0,
     };
 
     // Build maps of known index IDs
@@ -147,10 +153,11 @@ export async function runMigration(options: MigrationOptions = {}): Promise<Migr
         allIndexDefs.push({ id, tableName, typeName, fieldNames, fieldTypes });
     });
 
-    // Phase 1: Upgrade existing rows to latest version
-    if (upgradeVersions) {
+    // Phase 1: Populate secondary indexes and/or rewrite row data
+    if (populateSecondaries || rewriteData) {
         for (const [indexId, { model, primary }] of primaryByIndexId) {
-            let upgraded = 0;
+            let secondaryCount = 0;
+            let rewrittenCount = 0;
             const migrateFn = (model as any).migrate as ((record: Record<string, any>) => void) | undefined;
             const secondaries = model._secondaries || [];
 
@@ -176,45 +183,56 @@ export async function runMigration(options: MigrationOptions = {}): Promise<Migr
                 const preMigrate = migrateFn ? structuredClone(record) : undefined;
                 if (migrateFn) migrateFn(record);
 
-                // Handle secondaries (primary is left as-is for lazy migration on read)
-                for (const sec of secondaries) {
-                    if (!versionInfo.secondaryKeys.has(sec._signature!)) {
-                        // New secondary, write entry
-                        sec._write(txn, keyBuf, record as any);
-                        upgraded++;
-                    } else if (preMigrate) {
-                        if (sec._computeFn) {
-                            // Computed indexes: compare serialized keys to avoid unnecessary re-indexing
-                            const oldKeyBytes = sec._serializeKeyFields(preMigrate).toUint8Array();
-                            const newKeyBytes = sec._serializeKeyFields(record).toUint8Array();
-                            if (!bytesEqual(oldKeyBytes, newKeyBytes)) {
-                                sec._delete(txn, keyBuf, preMigrate as any);
-                                sec._write(txn, keyBuf, record as any);
-                                upgraded++;
-                            }
-                        } else {
-                            // Existing secondary, update if migrate changed any of its fields
-                            for (const [field, type] of sec._fieldTypes.entries()) {
-                                if (!type.equals(preMigrate[field], record[field])) {
+                // Populate/update secondary indexes
+                if (populateSecondaries) {
+                    for (const sec of secondaries) {
+                        if (!versionInfo.secondaryKeys.has(sec._signature!)) {
+                            // New secondary, write entry
+                            sec._write(txn, keyBuf, record as any);
+                            secondaryCount++;
+                        } else if (preMigrate) {
+                            if (sec._computeFn) {
+                                // Computed indexes: compare serialized keys to avoid unnecessary re-indexing
+                                const oldKeyBytes = sec._serializeKeyFields(preMigrate).toUint8Array();
+                                const newKeyBytes = sec._serializeKeyFields(record).toUint8Array();
+                                if (!bytesEqual(oldKeyBytes, newKeyBytes)) {
                                     sec._delete(txn, keyBuf, preMigrate as any);
                                     sec._write(txn, keyBuf, record as any);
-                                    upgraded++;
-                                    break;
+                                    secondaryCount++;
+                                }
+                            } else {
+                                // Existing secondary, update if migrate changed any of its fields
+                                for (const [field, type] of sec._fieldTypes.entries()) {
+                                    if (!type.equals(preMigrate[field], record[field])) {
+                                        sec._delete(txn, keyBuf, preMigrate as any);
+                                        sec._write(txn, keyBuf, record as any);
+                                        secondaryCount++;
+                                        break;
+                                    }
                                 }
                             }
                         }
                     }
                 }
 
+                // Rewrite primary row data to current version
+                if (rewriteData) {
+                    primary._write(txn, keyBuf, record);
+                    rewrittenCount++;
+                }
             });
 
-            onProgress?.({ phase: 'secondaries', processed: upgraded, table: model.tableName });
-            if (upgraded > 0) result.secondaries[model.tableName] = upgraded;
+            onProgress?.({ phase: 'secondaries', processed: secondaryCount, table: model.tableName });
+            if (secondaryCount > 0) result.secondaries[model.tableName] = secondaryCount;
+            if (rewrittenCount > 0) {
+                onProgress?.({ phase: 'rewritten', processed: rewrittenCount, table: model.tableName });
+                result.rewritten[model.tableName] = rewrittenCount;
+            }
         }
     }
 
     // Phase 2: Convert old primary indices with known table names
-    if (convertOldPrimaries) {
+    if (migratePrimaries) {
         for (const oldDef of allIndexDefs) {
             if (oldDef.typeName !== 'primary') continue;
             if (knownIndexIds.has(oldDef.id)) continue; // Known index, skip
@@ -266,14 +284,14 @@ export async function runMigration(options: MigrationOptions = {}): Promise<Migr
     }
 
     // Phase 3: Delete orphaned secondary/unique index entries
-    if (deleteOrphanedIndexes) {
+    if (removeOrphans) {
         for (const def of allIndexDefs) {
             if (knownIndexIds.has(def.id) || def.typeName === 'primary') continue;
             await forEachRow(def.id, (txn, keyBuf) => {
                 dbDel(txn.id, keyBuf);
-                result.orphaned++;
+                result.orphans++;
             });
-            onProgress?.({ phase: 'orphaned', processed: result.orphaned });
+            onProgress?.({ phase: 'orphans', processed: result.orphans });
         }
     }
 

package/src/models.ts

@@ -166,7 +166,7 @@ export interface Model<SUB> {
  * 
  * Models represent database entities with typed fields, automatic serialization,
  * change tracking, and relationship management. All model classes should extend
- * this base class and be decorated with `@registerModel`.
+ * this base class and be decorated with `@E.registerModel`.
  *
  * ### Schema Evolution
  *
@@ -283,7 +283,7 @@ export abstract class Model<SUB> {
         // This constructor will only be called once, from `initModels`. All other instances will
         // be created by the 'fake' constructor. The typing for `initial` *is* important though.
         if (initial as any === INIT_INSTANCE_SYMBOL) return;
-        throw new DatabaseError("The model needs a @registerModel decorator", 'INIT_ERROR');
+        throw new DatabaseError("The model needs a @E.registerModel decorator", 'INIT_ERROR');
     }
 
     /**
@@ -313,70 +313,78 @@ export abstract class Model<SUB> {
      */
     preCommit?(): void;
 
-    static async _delayedInit(cleared?: boolean): Promise<void> {
+    /**
+     * Transform the model's `E.field` properties into the appropriate JavaScript properties. Normally this is done
+     * automatically when using `transact()`, but in case you need to access `Model.fields` directly before the first
+     * transaction, you can call this method manually.
+     */
+    static initFields(reset?: boolean): void {
         const MockModel = getMockModel(this);
 
-        if (cleared) {
+        if (reset) {
             MockModel._primary._indexId = undefined;
             MockModel._primary._versions.clear();
             for (const sec of MockModel._secondaries || []) sec._indexId = undefined;
         }
 
-        if (!MockModel.fields) {
-            // First-time init: gather field configs from a temporary instance of the original class.
-            const OrgModel = (MockModel as any)._original || this;
-            const instance = new (OrgModel as any)(INIT_INSTANCE_SYMBOL);
+        if (MockModel.fields) return;
 
-            // If no primary key exists, create one using 'id' field
-            if (!MockModel._primary) {
-                if (!instance.id) {
-                    instance.id = { type: identifier }; 
-                }
-                // @ts-ignore-next-line - `id` is not part of the type, but the user probably shouldn't touch it anyhow
-                new PrimaryIndex(MockModel, ['id']);
+        // First-time init: gather field configs from a temporary instance of the original class.
+        const OrgModel = (MockModel as any)._original || this;
+        const instance = new (OrgModel as any)(INIT_INSTANCE_SYMBOL);
+
+        // If no primary key exists, create one using 'id' field
+        if (!MockModel._primary) {
+            if (!instance.id) {
+                instance.id = { type: identifier }; 
             }
+            // @ts-ignore-next-line - `id` is not part of the type, but the user probably shouldn't touch it anyhow
+            new PrimaryIndex(MockModel, ['id']);
+        }
 
-            MockModel.fields = {};
-            for (const key in instance) {
-                const value = instance[key] as FieldConfig<unknown>;
-                // Check if this property contains field metadata
-                if (value && value.type instanceof TypeWrapper) {
-                    // Set the configuration on the constructor's `fields` property
-                    MockModel.fields[key] = value;
-
-                    // Set default value on the prototype
-                    const defObj = value.default===undefined ? value.type : value;
-                    const def = defObj.default;
-                    if (typeof def === 'function') {
-                        // The default is a function. We'll define a getter on the property in the model prototype,
-                        // and once it is read, we'll run the function and set the value as a plain old property
-                        // on the instance object.
-                        Object.defineProperty(MockModel.prototype, key, {    
-                            get() {
-                                // This will call set(), which will define the property on the instance.
-                                return (this[key] = def.call(defObj, this));
-                            },
-                            set(val: any) {
-                                Object.defineProperty(this, key, {
-                                    value: val,
-                                    configurable: true,
-                                    writable: true,
-                                    enumerable: true,
-                                })
-                            },
-                            configurable: true,    
-                        });
-                    } else if (def !== undefined) {
-                        (MockModel.prototype as any)[key] = def;
-                    }
+        MockModel.fields = {};
+        for (const key in instance) {
+            const value = instance[key] as FieldConfig<unknown>;
+            // Check if this property contains field metadata
+            if (value && value.type instanceof TypeWrapper) {
+                // Set the configuration on the constructor's `fields` property
+                MockModel.fields[key] = value;
+
+                // Set default value on the prototype
+                const defObj = value.default===undefined ? value.type : value;
+                const def = defObj.default;
+                if (typeof def === 'function') {
+                    // The default is a function. We'll define a getter on the property in the model prototype,
+                    // and once it is read, we'll run the function and set the value as a plain old property
+                    // on the instance object.
+                    Object.defineProperty(MockModel.prototype, key, {    
+                        get() {
+                            // This will call set(), which will define the property on the instance.
+                            return (this[key] = def.call(defObj, this));
+                        },
+                        set(val: any) {
+                            Object.defineProperty(this, key, {
+                                value: val,
+                                configurable: true,
+                                writable: true,
+                                enumerable: true,
+                            })
+                        },
+                        configurable: true,    
+                    });
+                } else if (def !== undefined) {
+                    (MockModel.prototype as any)[key] = def;
                 }
             }
+        }
 
-            if (logLevel >= 1) {
-                console.log(`[edinburgh] Registered model ${MockModel.tableName} with fields: ${Object.keys(MockModel.fields).join(' ')}`);
-            }
+        if (logLevel >= 1) {
+            console.log(`[edinburgh] Registered model ${MockModel.tableName} with fields: ${Object.keys(MockModel.fields).join(' ')}`);
         }
+    }
 
+    static async _loadCreateIndexes(): Promise<void> {
+        const MockModel = getMockModel(this);
         // Always run index inits (idempotent, skip if already initialized)
         await MockModel._primary._delayedInit();
         for (const sec of MockModel._secondaries || []) await sec._delayedInit();