edinburgh 0.5.0 → 0.6.0

package/src/models.ts

@@ -1,9 +1,13 @@
+import * as lowlevel from "olmdb/lowlevel";
 import { DatabaseError } from "olmdb/lowlevel";
-import { AsyncLocalStorage } from "node:async_hooks";
-import { TypeWrapper, identifier } from "./types.js";
-import { scheduleInit } from "./edinburgh.js";
+import DataPack from "./datapack.js";
+import { deserializeType, serializeType, TypeWrapper, identifier } from "./types.js";
+import { transact, currentTxn, type Transaction } from "./edinburgh.js";
 
-export const txnStorage = new AsyncLocalStorage<Transaction>();
+import { PrimaryKey, NonPrimaryIndex, IndexRangeIterator, UniqueIndex, SecondaryIndex, FindOptions, VersionInfo } from "./indexes.js";
+import { addErrorPath, dbGet, hashBytes, hashFunction } from "./utils.js";
+
+let nextFakePkHash = -1;
 
 
 const PREVENT_PERSIST_DESCRIPTOR = {
@@ -12,25 +16,6 @@ const PREVENT_PERSIST_DESCRIPTOR = {
     },
 };
 
-/**
- * Returns the current transaction from AsyncLocalStorage.
- * Throws if called outside a transact() callback.
- * @internal
- */
-export function currentTxn(): Transaction {
-    const txn = txnStorage.getStore();
-    if (!txn) throw new DatabaseError("No active transaction. Operations must be performed within a transact() callback.", 'NO_TRANSACTION');
-    return txn;
-}
-
-export interface Transaction {
-    id: number;
-    instances: Set<Model<unknown>>;
-    instancesByPk: Map<number, Model<unknown>>;
-}
-import { BaseIndex, NonPrimaryIndex, PrimaryIndex, IndexRangeIterator, UniqueIndex, SecondaryIndex, FindOptions } from "./indexes.js";
-import { addErrorPath, logLevel, assert, dbGet, hashBytes } from "./utils.js";
-
 /**
  * Configuration interface for model fields.
  * @template T - The field type.
@@ -52,13 +37,13 @@ export interface FieldConfig<T> {
  * This allows for both runtime introspection and compile-time type safety.
  * 
  * @template T - The field type.
- * @param type - The type wrapper for this field.
- * @param options - Additional field configuration options.
+ * @param type The type wrapper for this field.
+ * @param options Additional field configuration options.
  * @returns The field value (typed as T, but actually returns FieldConfig<T>).
  * 
  * @example
  * ```typescript
- * const User = E.defineModel(class {
+ * const User = E.defineModel("User", class {
  *   name = E.field(E.string, {description: "User's full name"});
  *   age = E.field(E.opt(E.number), {description: "User's age", default: 25});
  * });
@@ -70,11 +55,8 @@ export function field<T>(type: TypeWrapper<T>, options: Partial<FieldConfig<T>>
     return options as any;
 }
 
-// Model registration and initialization
-export const modelRegistry: Record<string, typeof Model> = {};
-
 function isObjectEmpty(obj: object) {
-    for (let _ of Object.keys(obj)) {
+    for (const _ of Object.keys(obj)) {
         return false;
     }
     return true;
@@ -82,10 +64,7 @@ function isObjectEmpty(obj: object) {
 
 export type Change = Record<any, any> | "created" | "deleted";
 
-let autoTableNameId = 0;
-
 type FieldsOf<T> = T extends new () => infer I ? I : never;
-type ModelInstance<FIELDS> = FIELDS & Model<FIELDS>;
 
 type PKArgs<FIELDS, PK> =
     PK extends readonly (keyof FIELDS & string)[]
@@ -94,36 +73,389 @@ type PKArgs<FIELDS, PK> =
             ? [FIELDS[PK]]
             : [string];
 
-type UniqueFor<SPEC> =
-    SPEC extends readonly string[] ? UniqueIndex<any, SPEC>
-    : SPEC extends string ? UniqueIndex<any, [SPEC]>
+type IndexArgs<FIELDS, SPEC> =
+    SPEC extends readonly (keyof FIELDS & string)[]
+        ? { [I in keyof SPEC]: SPEC[I] extends keyof FIELDS ? FIELDS[SPEC[I]] : never }
+    : SPEC extends keyof FIELDS & string
+        ? [FIELDS[SPEC]]
     : SPEC extends (instance: any) => infer R
-        ? R extends (infer V)[] ? UniqueIndex<any, [], [V]>
-        : UniqueIndex<any, [], [R]>
+        ? R extends (infer V)[] ? [V] : [R]
     : never;
 
-type SecondaryFor<SPEC> =
-    SPEC extends readonly string[] ? SecondaryIndex<any, SPEC>
-    : SPEC extends string ? SecondaryIndex<any, [SPEC]>
-    : SPEC extends (instance: any) => infer R
-        ? R extends (infer V)[] ? SecondaryIndex<any, [], [V]>
-        : SecondaryIndex<any, [], [R]>
-    : never;
+/**
+ * A model constructor with its generic information erased.
+ *
+ * Useful when accepting or storing arbitrary registered model classes.
+ */
+export type AnyModelClass = ModelClass<new () => any, readonly any[], any, any>;
+
+type SecondaryRegistry<FIELDS> = Record<string, NonPrimaryIndex<Model<FIELDS>, readonly (keyof FIELDS & string)[], readonly any[]>>;
+
+function copyStaticMembersFromClassChain(target: object, source: Function) {
+    for (let current: any = source; current && current !== Function.prototype; current = Object.getPrototypeOf(current)) {
+        for (const key of Object.getOwnPropertyNames(current)) {
+            if (key === 'length' || key === 'name' || key === 'prototype') continue;
+            if (Object.prototype.hasOwnProperty.call(target, key)) continue;
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(current, key)!);
+        }
+    }
+}
+
+// Model registration and initialization
+export const modelRegistry: Record<string, AnyModelClass> = {};
+export const pendingModelInits = new Set<AnyModelClass>();
+
+// These static members are attached dynamically in defineModel(), so 'declare' tells TypeScript
+// they exist at runtime without emitting duplicate class fields that would shadow those assignments.
+class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX = {}> extends PrimaryKey<Model<FIELDS>, readonly (keyof FIELDS & string)[], PKA> {
+    // Runtime table identifier used for index naming and diagnostics.
+    declare tableName: string;
+    // Field schema map used for validation and serialization.
+    declare fields: Record<string | symbol | number, FieldConfig<unknown>>;
+    // Registered unique/secondary indexes for this model.
+    declare _secondaries?: SecondaryRegistry<FIELDS>;
+    // Cached list of non-primary fields used for value serialization.
+    _nonKeyFields!: (keyof FIELDS & string)[];
+    // Lazy getter/setter descriptors installed on unloaded non-key fields.
+    _lazyDescriptors: Record<string | symbol | number, PropertyDescriptor> = {};
+    // Writable descriptors temporarily installed before hydrating value fields.
+    _resetDescriptors: Record<string | symbol | number, PropertyDescriptor> = {};
+    // Frozen descriptors applied to primary-key fields after key materialization.
+    _freezePrimaryKeyDescriptors: Record<string | symbol | number, PropertyDescriptor> = {};
+    // Active schema version number for value encoding.
+    _currentVersion!: number;
+    // Hash of the active migrate() function for schema identity.
+    _currentMigrateHash!: number;
+    // Cached historical schema metadata for lazy migration of old rows.
+    _versions: Map<number, VersionInfo> = new Map();
+
+    _serializeVersionValue(): Uint8Array {
+        const fields: [string, Uint8Array][] = [];
+        for (const fieldName of this._nonKeyFields) {
+            const tp = new DataPack();
+            serializeType(this.fields[fieldName].type, tp);
+            fields.push([fieldName, tp.toUint8Array()]);
+        }
+        return new DataPack().write({
+            migrateHash: this._currentMigrateHash,
+            fields,
+            secondaryKeys: new Set(Object.values(this._secondaries || {}).map(sec => sec._signature!)),
+        }).toUint8Array();
+    }
+
+    async _initialize(reset = false): Promise<void> {
+        const allFieldTypes = new Map<string, TypeWrapper<any>>();
+        for (const [fieldName, fieldConfig] of Object.entries(this.fields)) {
+            allFieldTypes.set(fieldName, fieldConfig.type);
+        }
+        await super._initializeIndex(allFieldTypes, reset);
+
+        if (reset || this._nonKeyFields === undefined) {
+            this._nonKeyFields = Object.keys(this.fields).filter(fieldName => !this._indexFields.has(fieldName as any)) as any;
+            this._lazyDescriptors = {};
+            this._resetDescriptors = {};
+            this._freezePrimaryKeyDescriptors = {};
+
+            for (const fieldName of this._nonKeyFields) {
+                this._lazyDescriptors[fieldName] = {
+                    configurable: true,
+                    enumerable: true,
+                    get(this: Model<FIELDS>) {
+                        this.constructor._lazyLoad(this);
+                        return this[fieldName];
+                    },
+                    set(this: Model<FIELDS>, value: any) {
+                        this.constructor._lazyLoad(this);
+                        this[fieldName] = value;
+                    },
+                };
+                this._resetDescriptors[fieldName] = {
+                    writable: true,
+                    enumerable: true,
+                };
+            }
+
+            for (const fieldName of this._indexFields.keys()) {
+                this._freezePrimaryKeyDescriptors[fieldName] = {
+                    writable: false,
+                    enumerable: true,
+                };
+            }
+        }
+
+        for (const sec of Object.values(this._secondaries || {})) {
+            await sec._initializeIndex(allFieldTypes, reset, this._indexFields);
+        }
+
+        const migrateFn = (this as any).migrate;
+        this._currentMigrateHash = migrateFn ? hashFunction(migrateFn) : 0;
+
+        const currentValueBytes = this._serializeVersionValue();
+        this._currentVersion = (await this._ensureVersionEntry(currentValueBytes)).version;
+    }
+
+    _getSecondary(name: string) {
+        const index = this._secondaries?.[name];
+        if (!index) throw new DatabaseError(`Unknown index '${name}' on model '${this.tableName}'`, 'INIT_ERROR');
+        return index;
+    }
+
+    _get(txn: Transaction, args: PKA | Uint8Array, loadNow: false | Uint8Array): Model<FIELDS>;
+    _get(txn: Transaction, args: PKA | Uint8Array, loadNow: true): Model<FIELDS> | undefined;
+    _get(txn: Transaction, args: PKA | Uint8Array, loadNow: boolean | Uint8Array): Model<FIELDS> | undefined {
+        let key: Uint8Array;
+        let keyParts: readonly any[] | undefined;
+        if (args instanceof Uint8Array) {
+            key = args;
+        } else {
+            key = this._argsToKeyBytes(args, false).toUint8Array();
+            keyParts = args;
+        }
+
+        const keyHash = hashBytes(key);
+        const cached = txn.instances.get(keyHash) as Model<FIELDS> | undefined;
+        if (cached) {
+            if (loadNow && loadNow !== true) {
+                Object.defineProperties(cached, this._resetDescriptors);
+                this._loadValueFields(cached, loadNow);
+            }
+            return cached;
+        }
+
+        let valueBuffer: Uint8Array | undefined;
+        if (loadNow) {
+            if (loadNow === true) {
+                valueBuffer = dbGet(txn.id, key);
+                if (!valueBuffer) return;
+            } else {
+                valueBuffer = loadNow;
+            }
+        }
+
+        const model = Object.create((this as any).prototype) as Model<FIELDS>;
+        model._txn = txn;
+        model._oldValues = {};
+        txn.instances.set(keyHash, model);
+
+        if (keyParts) {
+            let i = 0;
+            for (const fieldName of this._indexFields.keys()) {
+                model._setLoadedField(fieldName, keyParts[i++]);
+            }
+        } else {
+            const keyPack = new DataPack(key);
+            keyPack.readNumber();
+            for (const [fieldName, fieldType] of this._indexFields.entries()) {
+                model._setLoadedField(fieldName, fieldType.deserialize(keyPack));
+            }
+        }
+
+        model._setPrimaryKey(key, keyHash);
+        if (valueBuffer) {
+            this._loadValueFields(model, valueBuffer);
+        } else {
+            Object.defineProperties(model, this._lazyDescriptors);
+        }
+        return model;
+    }
+
+    _lazyLoad(model: Model<FIELDS>) {
+        const key = model._primaryKey!;
+        const valueBuffer = dbGet(model._txn.id, key);
+        if (!valueBuffer) throw new DatabaseError(`Lazy-loaded ${this.tableName}#${key} does not exist`, 'LAZY_FAIL');
+        Object.defineProperties(model, this._resetDescriptors);
+        this._loadValueFields(model, valueBuffer);
+    }
+
+    /**
+     * Load a model by primary key inside the current transaction.
+     *
+     * @returns The matching model, or `undefined` if no row exists.
+     */
+    get(...args: PKA): Model<FIELDS> | undefined {
+        return this._get(currentTxn(), args, true);
+    }
+
+    /**
+     * Load a model by primary key without fetching its non-key fields immediately.
+     *
+     * Accessing a lazy field later will load the remaining fields transparently.
+     */
+    getLazy(...args: PKA): Model<FIELDS> {
+        return this._get(currentTxn(), args, false);
+    }
+
+    _pairToInstance(txn: Transaction, keyBuffer: ArrayBuffer, valueBuffer: ArrayBuffer): Model<FIELDS> {
+        return this._get(txn, new Uint8Array(keyBuffer), new Uint8Array(valueBuffer))!;
+    }
+
+    /**
+     * Load an existing instance by primary key and update it, or create a new one.
+      * If a row already exists, its non-primary-key fields are updated in place.
+      * Otherwise, a new instance is created with `obj` as its initial properties.
+     *
+     * @param obj Partial model data that **must** include every primary key field.
+      * @returns The loaded-and-updated or newly created instance.
+     */
+    replaceInto(obj: Partial<FIELDS>): Model<FIELDS> {
+        const keyArgs: any[] = [];
+        for (const fieldName of this._indexFields.keys()) {
+            if (!(fieldName in (obj as any))) {
+                throw new DatabaseError(`replaceInto: missing primary key field '${fieldName}'`, "MISSING_PRIMARY_KEY");
+            }
+            keyArgs.push((obj as any)[fieldName]);
+        }
+        const existing = this.get(...keyArgs as any) as Model<FIELDS> | undefined;
+        if (existing) {
+            for (const key in obj as any) {
+                if (!this._indexFields.has(key as any)) {
+                    (existing as any)[key] = (obj as any)[key];
+                }
+            }
+            return existing;
+        }
+        return new (this as any)(obj);
+    }
+
+    /**
+     * Look up a model through a named unique index.
+     *
+     * @param name The name from the model's `unique` definition.
+     * @param args The unique-index key values.
+     * @returns The matching model instance, if any.
+     */
+    getBy<K extends string & keyof UNIQUE>(name: K, ...args: IndexArgs<FIELDS, UNIQUE[K]>): Model<FIELDS> | undefined {
+        return (this._getSecondary(name) as any).getPK(...args);
+    }
+
+    /**
+     * Query rows through a named unique or secondary index.
+     *
+     * This mirrors `find()`, but targets a named entry from the model's `unique`
+     * or `index` registration.
+     */
+    findBy<K extends string & keyof (UNIQUE & INDEX)>(name: K, opts: FindOptions<IndexArgs<FIELDS, (UNIQUE & INDEX)[K]>, 'first'>): Model<FIELDS> | undefined;
+    findBy<K extends string & keyof (UNIQUE & INDEX)>(name: K, opts: FindOptions<IndexArgs<FIELDS, (UNIQUE & INDEX)[K]>, 'single'>): Model<FIELDS>;
+    findBy<K extends string & keyof (UNIQUE & INDEX)>(name: K, opts?: FindOptions<IndexArgs<FIELDS, (UNIQUE & INDEX)[K]>>): IndexRangeIterator<Model<FIELDS>>;
+    findBy(name: string, opts?: any): any {
+        return this._getSecondary(name).find(opts);
+    }
+
+    /**
+     * Process rows from a named unique or secondary index in batched transactions.
+     *
+     * Uses the same range options as `findBy()`, plus batch limits.
+     */
+    batchProcessBy<K extends string & keyof (UNIQUE & INDEX)>(
+        name: K,
+        opts: FindOptions<IndexArgs<FIELDS, (UNIQUE & INDEX)[K]>> & { limitSeconds?: number; limitRows?: number },
+        callback: (row: Model<FIELDS>) => any,
+    ): Promise<void> {
+        return this._getSecondary(name).batchProcess(opts, callback as any);
+    }
+
+    _loadValueFields(model: Model<FIELDS>, valueArray: Uint8Array) {
+        const valuePack = new DataPack(valueArray);
+        const version = valuePack.readNumber();
+
+        if (version === this._currentVersion) {
+            for (const fieldName of this._nonKeyFields) {
+                model._setLoadedField(fieldName, this.fields[fieldName].type.deserialize(valuePack));
+            }
+        } else {
+            this._migrateValueFields(model, version, valuePack);
+        }
+    }
+
+    _loadVersionInfo(txnId: number, version: number): VersionInfo {
+        let info = this._versions.get(version);
+        if (info) return info;
+
+        const key = this._versionInfoKey(version);
+        const raw = dbGet(txnId, key);
+        if (!raw) throw new DatabaseError(`Version ${version} info not found for index ${this}`, 'CONSISTENCY_ERROR');
+
+        const obj = new DataPack(raw).read() as any;
+        if (!obj || typeof obj.migrateHash !== 'number' || !Array.isArray(obj.fields) || !(obj.secondaryKeys instanceof Set)) {
+            throw new DatabaseError(`Version ${version} info is corrupted for index ${this}`, 'CONSISTENCY_ERROR');
+        }
+
+        const nonKeyFields = new Map<string, TypeWrapper<any>>();
+        for (const [name, typeBytes] of obj.fields) {
+            nonKeyFields.set(name, deserializeType(new DataPack(typeBytes), 0));
+        }
+
+        info = { migrateHash: obj.migrateHash, nonKeyFields, secondaryKeys: obj.secondaryKeys as Set<string> };
+        this._versions.set(version, info);
+        return info;
+    }
+
+    _migrateValueFields(model: Model<FIELDS>, version: number, valuePack: DataPack) {
+        const versionInfo = this._loadVersionInfo(model._txn.id, version);
+        const record: Record<string, any> = {};
+        for (const [name] of this._indexFields.entries()) record[name] = (model as any)[name];
+        for (const [name, type] of versionInfo.nonKeyFields.entries()) {
+            record[name] = type.deserialize(valuePack);
+        }
+
+        const migrateFn = (this as any).migrate;
+        if (migrateFn) migrateFn(record);
+
+        for (const fieldName of this._nonKeyFields) {
+            if (fieldName in record) {
+                model._setLoadedField(fieldName, record[fieldName]);
+            } else if (fieldName in model) {
+                model._setLoadedField(fieldName, (model as any)[fieldName]);
+            } else {
+                throw new DatabaseError(`Field ${fieldName} is missing in migrated data for ${model}`, 'MIGRATION_ERROR');
+            }
+        }
+    }
+
+    _serializeValue(data: Record<string, any>): Uint8Array {
+        const valueBytes = new DataPack();
+        valueBytes.write(this._currentVersion);
+        for (const fieldName of this._nonKeyFields) {
+            const fieldConfig = this.fields[fieldName] as FieldConfig<unknown>;
+            fieldConfig.type.serialize(data[fieldName], valueBytes);
+        }
+        return valueBytes.toUint8Array();
+    }
+}
+
+/**
+ * Runtime base constructor for model classes returned by `defineModel()`.
+ *
+ * Prefer the `ModelClass` type alias for annotations and the result of
+ * `defineModel()` for concrete model classes.
+ */
+export const ModelClass = ModelClassRuntime;
+
+/**
+ * The static side of a model class returned by `defineModel()`.
+ *
+ * Besides the class constructor itself, this includes primary-key lookup
+ * helpers like `get()` and `getLazy()`, range-query helpers like `find()`, and
+ * named-index helpers like `getBy()` and `findBy()`.
+ *
+ * @template T - The original class passed to `defineModel()`.
+ * @template PKA - Tuple of primary-key argument types.
+ * @template UNIQUE - Named unique-index specifications.
+ * @template INDEX - Named secondary-index specifications.
+ */
+export type ModelClass<T extends new () => any, PKA extends readonly any[], UNIQUE = {}, INDEX = {}> =
+    T
+    & ModelClassRuntime<FieldsOf<T>, PKA, UNIQUE, INDEX>
+    & {
+        new (initial?: Partial<FieldsOf<T>>, txn?: Transaction): Model<FieldsOf<T>>;
+    };
 
-type RegisteredModel<FIELDS, PKA extends readonly any[], UNIQUE, INDEX> = {
-    new (initial?: Partial<FIELDS>): ModelInstance<FIELDS>;
-    tableName: string;
-    fields: Record<string | symbol | number, FieldConfig<unknown>>;
-    get(...args: PKA): ModelInstance<FIELDS> | undefined;
-    getLazy(...args: PKA): ModelInstance<FIELDS>;
-    find(opts: FindOptions<PKA, 'first'>): ModelInstance<FIELDS> | undefined;
-    find(opts: FindOptions<PKA, 'single'>): ModelInstance<FIELDS>;
-    find(opts?: FindOptions<PKA>): IndexRangeIterator<any>;
-    batchProcess(opts?: FindOptions<PKA> & { limitSeconds?: number; limitRows?: number }, callback?: (row: ModelInstance<FIELDS>) => any): Promise<void>;
-    replaceInto(obj: Partial<FIELDS>): ModelInstance<FIELDS>;
-} &
-    { [K in keyof UNIQUE]: UniqueFor<UNIQUE[K]> } &
-    { [K in keyof INDEX]: SecondaryFor<INDEX[K]> };
+/**
+ * Minimal instance-side model shape used for typing the constructor property.
+ */
+export interface ModelBase {
+    constructor: AnyModelClass;
+}
 
 /**
  * Register a model class with the Edinburgh ORM system.
@@ -131,13 +463,13 @@ type RegisteredModel<FIELDS, PKA extends readonly any[], UNIQUE, INDEX> = {
  * Converts a plain class into a fully-featured model with database persistence,
  * typed fields, primary key access, and optional secondary and unique indexes.
  *
- * @param cls - A plain class whose properties use E.field().
- * @param opts - Registration options.
- * @param opts.pk - Primary key field name or array of field names.
- * @param opts.unique - Named unique index specifications (field name, field array, or compute function).
- * @param opts.index - Named secondary index specifications (field name, field array, or compute function).
- * @param opts.tableName - Explicit database table name.
- * @param opts.override - Replace a previous model with the same table name.
+ * @param tableName The database table name for this model.
+ * @param cls A plain class whose properties use E.field().
+ * @param opts Registration options.
+ * @param opts.pk Primary key field name or array of field names.
+ * @param opts.unique Named unique index specifications (field name, field array, or compute function).
+ * @param opts.index Named secondary index specifications (field name, field array, or compute function).
+ * @param opts.override Replace a previous model with the same table name.
  * @returns The enhanced model constructor.
  */
 export function defineModel<
@@ -146,31 +478,27 @@ export function defineModel<
     const UNIQUE extends Record<string, (keyof FieldsOf<T> & string) | readonly (keyof FieldsOf<T> & string)[] | ((instance: any) => any)>,
     const INDEX extends Record<string, (keyof FieldsOf<T> & string) | readonly (keyof FieldsOf<T> & string)[] | ((instance: any) => any)>,
 >(
+    tableName: string,
     cls: T,
-    opts?: { pk?: PK, unique?: UNIQUE, index?: INDEX, tableName?: string, override?: boolean }
-): RegisteredModel<FieldsOf<T>, PKArgs<FieldsOf<T>, PK>, UNIQUE, INDEX>;
-
-export function defineModel(cls: any, opts?: any): any {
-    Object.setPrototypeOf(cls.prototype, Model.prototype);
-
+    opts?: { pk?: PK, unique?: UNIQUE, index?: INDEX, override?: boolean }
+): ModelClass<T, PKArgs<FieldsOf<T>, PK>, UNIQUE, INDEX> {
+    Object.setPrototypeOf(cls.prototype, ModelBase.prototype);
     const MockModel = function(this: any, initial?: Record<string, any>, txn: Transaction = currentTxn()) {
         this._txn = txn;
-        txn.instances.add(this);
+        txn.instances.set(nextFakePkHash--, this);
         if (initial) Object.assign(this, initial);
     } as any;
 
+    const normalizeSpec = (spec: any) => typeof spec === 'string' ? [spec] : spec;
+    const queueInitialization = () => { pendingModelInits.add(MockModel); };
+    const loadPrimary = (txn: Transaction, primaryKey: Uint8Array, loadNow: boolean | Uint8Array) => MockModel._get(txn, primaryKey, loadNow);
+
     cls.prototype.constructor = MockModel;
-    Object.setPrototypeOf(MockModel, Model);
+    Object.setPrototypeOf(MockModel, ModelClassRuntime.prototype);
     MockModel.prototype = cls.prototype;
-    MockModel._original = cls;
+    copyStaticMembersFromClassChain(MockModel, cls);
 
-    for (const name of Object.getOwnPropertyNames(cls)) {
-        if (name !== 'length' && name !== 'prototype' && name !== 'name') {
-            MockModel[name] = cls[name];
-        }
-    }
-
-    MockModel.tableName = opts?.tableName || cls.name || `Model${++autoTableNameId}`;
+    MockModel.tableName = tableName;
 
     if (MockModel.tableName in modelRegistry) {
         if (!opts?.override) {
@@ -213,38 +541,38 @@ export function defineModel(cls: any, opts?: any): any {
         }
     }
 
-    if (opts?.pk) {
-        new PrimaryIndex(MockModel, Array.isArray(opts.pk) ? opts.pk : [opts.pk]);
-    } else {
-        new PrimaryIndex(MockModel, ['id']);
+    const primaryFields = opts?.pk ? (Array.isArray(opts.pk) ? opts.pk : [opts.pk]) : ['id'];
+    MockModel._indexFields = new Map();
+    for (const fieldName of primaryFields) {
+        const fieldConfig = MockModel.fields[fieldName];
+        if (!fieldConfig) {
+            throw new DatabaseError(`Unknown primary key field '${fieldName}' on model '${tableName}'`, 'INIT_ERROR');
+        }
+        MockModel._indexFields.set(fieldName, fieldConfig.type);
     }
 
-    const normalizeSpec = (spec: any) => typeof spec === 'string' ? [spec] : spec;
+    MockModel._secondaries = {};
+    MockModel._lazyDescriptors = {};
+    MockModel._resetDescriptors = {};
+    MockModel._freezePrimaryKeyDescriptors = {};
+    MockModel._versions = new Map();
 
     if (opts?.unique) {
         for (const [name, spec] of Object.entries<any>(opts.unique)) {
-            MockModel[name] = new UniqueIndex(MockModel, normalizeSpec(spec));
+            MockModel._secondaries[name] = new UniqueIndex(tableName, normalizeSpec(spec), loadPrimary, queueInitialization);
         }
     }
     if (opts?.index) {
         for (const [name, spec] of Object.entries<any>(opts.index)) {
-            MockModel[name] = new SecondaryIndex(MockModel, normalizeSpec(spec));
+            MockModel._secondaries[name] = new SecondaryIndex(tableName, normalizeSpec(spec), loadPrimary, queueInitialization);
         }
     }
 
     modelRegistry[MockModel.tableName] = MockModel;
-    scheduleInit();
+    pendingModelInits.add(MockModel);
     return MockModel;
 }
 
-/**
- * Model interface that ensures proper typing for the constructor property.
- * @template SUB - The concrete model subclass.
- */
-export interface Model<SUB> {
-  constructor: typeof Model<SUB>;
-}
-
 /**
  * Base class for all database models in the Edinburgh ORM.
  * 
@@ -276,73 +604,44 @@ export interface Model<SUB> {
  *
  * - **`static migrate(record)`**: Called when deserializing rows written with an older schema
  *   version. Receives a plain record object; mutate it in-place to match the current schema.
- *   See {@link Model.migrate}.
  *
  * - **`preCommit()`**: Called on each modified instance right before the transaction commits.
  *   Useful for computing derived fields, enforcing cross-field invariants, or creating related
- *   instances. See {@link Model.preCommit}.
+ *   instances.
  *
- * @template SUB - The concrete model subclass (for proper typing).
- * 
  * @example
  * ```typescript
- * const User = E.defineModel(class {
+ * const User = E.defineModel("User", class {
  *   id = E.field(E.identifier);
  *   name = E.field(E.string);
  *   email = E.field(E.string);
  * }, {
  *   pk: "id",
- *   unique: { byEmail: "email" },
+ *   unique: { email: "email" },
  * });
+ * // Optional: declare a companion type so `let u: User` works.
+ * // Not needed if you only use `new User()`, `User.find()`, etc.
+ * type User = InstanceType<typeof User>;
  * ```
  */
-
-
-export abstract class Model<SUB> {
-    static _primary: PrimaryIndex<any, any>;
-
-    /** @internal All non-primary indexes for this model. */
-    static _secondaries?: NonPrimaryIndex<any, readonly (keyof any & string)[]>[];
-
-    /** The database table name (defaults to class name). */
-    static tableName: string;
-
-    /** When true, defineModel replaces an existing model with the same tableName. */
-    static override?: boolean;
-
-    /** Field configuration metadata. */
-    static fields: Record<string | symbol | number, FieldConfig<unknown>>;
-
-    // Alias statics that delegate to _primary, used by migrate.ts
-    static get _indexId() { return this._primary?._indexId; }
-    static get _currentVersion() { return this._primary._currentVersion; }
-    static get _pkFieldTypes() { return this._primary._fieldTypes; }
-    static _loadVersionInfo(txnId: number, version: number) { return this._primary._loadVersionInfo(txnId, version); }
-    static _writePrimary(txn: Transaction, pk: Uint8Array, data: Record<string, any>) { this._primary._write(txn, pk, data as any); }
-
+export abstract class ModelBase {
     /**
      * Optional migration function called when deserializing rows written with an older schema version.
-     * Receives a plain record with all fields (primary key fields + value fields) and should mutate it
-     * in-place to match the current schema.
-     *
-     * This is called both during lazy loading (when a row is read from disk) and during batch
-     * migration (via `runMigration()` / `npx migrate-edinburgh`). The function's source code is hashed
-     * to detect changes. Modifying `migrate()` triggers a new schema version.
+    * Receives a plain record with all fields and should mutate it in-place to match the current schema.
+    * It runs during lazy loading and during `runMigration()`. Changing this method creates a new schema version.
+    * If it updates values used by secondary or unique indexes, those index entries are refreshed only by `runMigration()`.
      *
-     * If `migrate()` changes values of fields used in secondary or unique indexes, those indexes
-     * will only be updated when `runMigration()` is run (not during lazy loading).
-     *
-     * @param record - A plain object with all field values from the old schema version.
+     * @param record A plain object containing the row's field values from the older schema version.
      *
      * @example
      * ```typescript
-     * const User = E.defineModel(class {
+     * const User = E.defineModel("User", class {
      *   id = E.field(E.identifier);
      *   name = E.field(E.string);
-     *   role = E.field(E.string);  // new field
+     *   role = E.field(E.string);
      *
      *   static migrate(record: Record<string, any>) {
-     *     record.role ??= "user";  // default for rows that predate the 'role' field
+     *     record.role ??= "user";
      *   }
      * }, { pk: "id" });
      * ```
@@ -359,17 +658,14 @@ export abstract class Model<SUB> {
      * @internal
      * - _oldValues===undefined: New instance, not yet saved.
      * - _oldValues===null: Instance is to be deleted.
+     * - _oldValues===false: Instance excluded from persistence (preventPersist).
      * - _oldValues is an object: Loaded (possibly only partial, still lazy) from disk, _oldValues contains (partial) old values
      */
-    _oldValues: Record<string, any> | undefined | null;
+    _oldValues: Record<string, any> | undefined | null | false;
     _primaryKey: Uint8Array | undefined;
     _primaryKeyHash: number | undefined;
     _txn!: Transaction;
 
-    constructor(initial: Partial<Omit<SUB, "constructor">> = {}) {
-        throw new DatabaseError("Use defineModel() to create model classes", 'INIT_ERROR');
-    }
-
     /**
      * Optional hook called on each modified instance right before the transaction commits.
      * Runs before data is written to disk, so changes made here are included in the commit.
@@ -382,7 +678,7 @@ export abstract class Model<SUB> {
      *
      * @example
      * ```typescript
-     * const Post = E.defineModel(class {
+     * const Post = E.defineModel("Post", class {
      *   id = E.field(E.identifier);
      *   title = E.field(E.string);
      *   slug = E.field(E.string);
@@ -395,23 +691,11 @@ export abstract class Model<SUB> {
      */
     preCommit?(): void;
 
-    static _resetIndexes(): void {
-        this._primary._indexId = undefined;
-        this._primary._versions.clear();
-        for (const sec of this._secondaries || []) sec._indexId = undefined;
-    }
-
-    static async _loadCreateIndexes(): Promise<void> {
-        await this._primary._delayedInit();
-        for (const sec of this._secondaries || []) await sec._delayedInit();
-        await this._primary._initVersioning();
-    }
-
     _setLoadedField(fieldName: string, value: any) {
-        const oldValues = this._oldValues!;
+        const oldValues = this._oldValues! as Record<string, any>;
         if (oldValues.hasOwnProperty(fieldName)) return; // Already loaded earlier (as part of index key?)
 
-        this[fieldName as keyof Model<SUB>] = value;
+        (this as any)[fieldName] = value;
         if (typeof value === 'object' && value !== null) {            
             const fieldType = (this.constructor.fields[fieldName] as FieldConfig<unknown>).type;
             oldValues[fieldName] = fieldType.clone(value);
@@ -421,13 +705,24 @@ export abstract class Model<SUB> {
         }
     }
 
+    _restoreLazyFields() {
+        const oldValues = this._oldValues;
+        if (!oldValues || oldValues === null) return;
+        for (const [fieldName, descriptor] of Object.entries(this.constructor._lazyDescriptors)) {
+            if (!oldValues.hasOwnProperty(fieldName)) {
+                Object.defineProperty(this, fieldName, descriptor);
+            }
+        }
+    }
+
     /**
      * @returns The primary key for this instance.
      */
     getPrimaryKey(): Uint8Array {
         let key = this._primaryKey;
         if (key === undefined) {
-            key = this.constructor._primary!._serializeKey(this).toUint8Array();
+            if (this._oldValues === false) throw new DatabaseError("Operation not allowed after preventPersist()", "NO_PERSIST");
+            key = this.constructor._serializePK(this).toUint8Array();
             this._setPrimaryKey(key);
         }
         return key;
@@ -436,7 +731,7 @@ export abstract class Model<SUB> {
     _setPrimaryKey(key: Uint8Array, hash?: number) {
         this._primaryKey = key;
         this._primaryKeyHash = hash ?? hashBytes(key);
-        Object.defineProperties(this, this.constructor._primary._freezePrimaryKeyDescriptors);
+        Object.defineProperties(this, this.constructor._freezePrimaryKeyDescriptors);
     }
 
     /**
@@ -448,21 +743,23 @@ export abstract class Model<SUB> {
     }
 
     isLazyField(field: keyof this) {
-        const descr = this.constructor._primary!._lazyDescriptors[field];
-        return !!(descr && 'get' in descr && descr.get === Reflect.getOwnPropertyDescriptor(this, field)?.get);
+        const oldValues = this._oldValues;
+        return !!(oldValues && oldValues !== null && field in this.constructor._lazyDescriptors && !oldValues.hasOwnProperty(field));
     }
 
     _write(txn: Transaction): undefined | Change {
         const oldValues = this._oldValues;
 
+        if (oldValues === false) return; // preventPersist() was called
+
         if (oldValues === null) { // Delete instance
             const pk = this._primaryKey;
             // Temporarily restore _oldValues so computed indexes can trigger lazy loads
             this._oldValues = {};
-            for(const index of this.constructor._secondaries || []) {
+            for (const index of Object.values(this.constructor._secondaries || {})) {
                 index._delete(txn, pk!, this);
             }
-            this.constructor._primary._delete(txn, pk!, this);
+            this.constructor._deletePK(txn, pk!, this);
             
             return "deleted";
         }
@@ -477,10 +774,10 @@ export abstract class Model<SUB> {
             }
 
             // Insert the primary index
-            this.constructor._primary!._write(txn, pk!, this);
+            this.constructor._writePK(txn, pk!, this);
 
             // Insert all secondaries
-            for (const index of this.constructor._secondaries || []) {
+            for (const index of Object.values(this.constructor._secondaries || {})) {
                 index._write(txn, pk!, this);
             }
 
@@ -493,10 +790,11 @@ export abstract class Model<SUB> {
 
         // Add old values of changed fields to 'changed'.
         const changed: Record<string, any> = {};
-        const fields = this.constructor.fields;
+        const cls = this.constructor;
+        const fields = cls.fields;
         for(const fieldName in oldValues) {
             const oldValue = oldValues[fieldName];
-            const newValue = this[fieldName as keyof Model<SUB>];
+            const newValue = this[fieldName as keyof ModelBase];
             if (newValue !== oldValue  && !(fields[fieldName] as FieldConfig<unknown>).type.equals(newValue, oldValue)) {
                 changed[fieldName] = oldValue;
             }
@@ -505,7 +803,7 @@ export abstract class Model<SUB> {
         if (isObjectEmpty(changed)) return; // No changes, nothing to do
 
         // Make sure primary has not been changed
-        for (const field of this.constructor._primary!._fieldTypes.keys()) {
+        for (const field of cls._indexFields.keys()) {
             if (changed.hasOwnProperty(field)) {
                 throw new DatabaseError(`Cannot modify primary key field: ${field}`, "CHANGE_PRIMARY");
             }
@@ -518,10 +816,10 @@ export abstract class Model<SUB> {
 
         // Update the primary index
         const pk = this._primaryKey!;
-        this.constructor._primary!._write(txn, pk, this);
+        cls._writePK(txn, pk, this);
 
         // Update any secondaries with changed fields
-        for (const index of this.constructor._secondaries || []) {
+        for (const index of Object.values(cls._secondaries || {})) {
             index._update(txn, pk, this, oldValues);
         }
         return changed;
@@ -540,60 +838,15 @@ export abstract class Model<SUB> {
      * ```
      */
     preventPersist() {
-        this._txn.instances.delete(this);
+        if (this._oldValues === undefined && this._primaryKey !== undefined) {
+            throw new DatabaseError("Cannot preventPersist() after PK has been used", "INVALID");
+        }
+        this._oldValues = false;
         // Have access to '_txn' throw a descriptive error:
         Object.defineProperty(this, "_txn", PREVENT_PERSIST_DESCRIPTOR);
         return this;
     }
 
-    static get(...args: any[]): any {
-        return this._primary!.get(...args);
-    }
-
-    static getLazy(...args: any[]): any {
-        return this._primary!.getLazy(...args);
-    }
-
-    static find(opts?: any): any {
-        return this._primary!.find(opts);
-    }
-
-    static batchProcess(opts: any, callback?: any): any {
-        return this._primary!.batchProcess(opts, callback);
-    }
-
-    /**
-     * Load an existing instance by primary key and update it, or create a new one.
-     *
-     * The provided object must contain all primary key fields. If a matching row exists,
-     * the remaining properties from `obj` are set on the loaded instance. Otherwise a
-     * new instance is created with `obj` as its initial properties.
-     *
-     * @param obj - Partial model data that **must** include every primary key field.
-     * @returns The loaded-and-updated or newly created instance.
-     */
-    static replaceInto<T extends typeof Model<any>>(this: T, obj: Partial<Record<string, any>>): InstanceType<T> {
-        const pk = this._primary!;
-        const keyArgs = [];
-        for (const fieldName of pk._fieldTypes.keys()) {
-            if (!(fieldName in (obj as any))) {
-                throw new DatabaseError(`replaceInto: missing primary key field '${fieldName}'`, "MISSING_PRIMARY_KEY");
-            }
-            keyArgs.push((obj as any)[fieldName]);
-        }
-
-        const existing = pk.get(...keyArgs as any) as InstanceType<T> | undefined;
-        if (existing) {
-            for (const key in obj as any) {
-                if (!pk._fieldTypes.has(key as any)) {
-                    (existing as any)[key] = (obj as any)[key];
-                }
-            }
-            return existing;
-        }
-        return new (this as any)(obj) as InstanceType<T>;
-    }
-
     /**
      * Delete this model instance from the database.
      * 
@@ -606,13 +859,13 @@ export abstract class Model<SUB> {
      * ```
      */
     delete() {
-        if (this._oldValues === undefined) throw new DatabaseError("Cannot delete unsaved instance", "NOT_SAVED");
+        if (this._oldValues === undefined) throw new DatabaseError("Cannot delete unsaved instance", "INVALID");
         this._oldValues = null;
     }
 
     /**
      * Validate all fields in this model instance.
-     * @param raise - If true, throw on first validation error.
+     * @param raise If true, throw on first validation error.
      * @returns Array of validation errors (empty if valid).
      * 
      * @example
@@ -626,11 +879,12 @@ export abstract class Model<SUB> {
      */
     validate(raise: boolean = false): Error[] {
         const errors: Error[] = [];
+        const cls = this.constructor;
         
-        for (const [key, fieldConfig] of Object.entries(this.constructor.fields)) {
+        for (const [key, fieldConfig] of Object.entries(cls.fields)) {
             let e = fieldConfig.type.getError((this as any)[key]);
             if (e) {
-                e = addErrorPath(e, this.constructor.tableName+"."+key);
+                e = addErrorPath(e, cls.tableName+"."+key);
                 if (raise) throw e;
                 errors.push(e as Error);
             }
@@ -655,7 +909,7 @@ export abstract class Model<SUB> {
     getState(): "deleted" | "created" | "loaded" | "lazy" {
         if (this._oldValues === null) return "deleted";
         if (this._oldValues === undefined) return "created";
-        for(const [key,descr] of Object.entries(this.constructor._primary!._lazyDescriptors)) {
+        for(const [key,descr] of Object.entries(this.constructor._lazyDescriptors)) {
             if (descr && 'get' in descr && descr.get === Reflect.getOwnPropertyDescriptor(this, key)?.get) {
                 return "lazy";
             }
@@ -664,12 +918,55 @@ export abstract class Model<SUB> {
     }
 
     toString(): string {
-        const primary = this.constructor._primary;
-        const pk = primary._keyToArray(this._primaryKey || primary._serializeKey(this).toUint8Array(false));
-        return `{Model:${this.constructor.tableName} ${this.getState()} ${pk}}`;
+        const cls = this.constructor;
+        const pk = cls._pkToArray(this._primaryKey || cls._serializePK(this).toUint8Array(false));
+        return `{Model:${cls.tableName} ${this.getState()} ${pk}}`;
     }
 
     [Symbol.for('nodejs.util.inspect.custom')]() {
         return this.toString();
     }
 }
+
+/**
+ * Delete every key/value entry in the database and reinitialize all registered models.
+ *
+ * This clears rows, index metadata, and schema-version records. It is mainly useful
+ * for tests, local resets, or tooling that needs a completely empty database.
+ */
+export async function deleteEverything(): Promise<void> {
+    let done = false;
+    while (!done) {
+        await transact(() => {
+            const txn = currentTxn();
+            const iteratorId = lowlevel.createIterator(txn.id, undefined, undefined, false);
+            const deadline = Date.now() + 150;
+            let count = 0;
+            try {
+                while (true) {
+                    const raw = lowlevel.readIterator(iteratorId);
+                    if (!raw) {
+                        done = true;
+                        break;
+                    }
+                    lowlevel.del(txn.id, raw.key);
+                    if (++count >= 4096 || Date.now() >= deadline) break;
+                }
+            } finally {
+                lowlevel.closeIterator(iteratorId);
+            }
+        });
+    }
+
+    for (const model of Object.values(modelRegistry)) {
+        pendingModelInits.delete(model);
+        await model._initialize(true);
+    }
+}
+
+/**
+ * A model instance, including its user-defined fields.
+ * @template FIELDS - The fields defined on this model.
+ */
+export type Model<FIELDS> = FIELDS & ModelBase;
+export const Model = ModelBase;