edinburgh 0.4.6 → 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 as BaseIndex, PrimaryIndex, IndexRangeIterator } from "./indexes.js";
-import { addErrorPath, logLevel, assert, dbGet, hashBytes, bytesEqual } from "./utils.js";
-
 /**
  * Configuration interface for model fields.
  * @template T - The field type.
@@ -52,16 +37,16 @@ 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
- * class User extends E.Model<User> {
+ * 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});
- * }
+ * });
  * ```
  */
 export function field<T>(type: TypeWrapper<T>, options: Partial<FieldConfig<T>> = {}): T {
@@ -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,91 +64,521 @@ function isObjectEmpty(obj: object) {
 
 export type Change = Record<any, any> | "created" | "deleted";
 
+type FieldsOf<T> = T extends new () => infer I ? I : never;
+
+type PKArgs<FIELDS, PK> =
+    PK extends readonly (keyof FIELDS & string)[]
+        ? { [I in keyof PK]: PK[I] extends keyof FIELDS ? FIELDS[PK[I]] : never }
+        : PK extends keyof FIELDS & string
+            ? [FIELDS[PK]]
+            : [string];
+
+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)[] ? [V] : [R]
+    : never;
+
 /**
- * Register a model class with the Edinburgh ORM system.
- * 
- * @template T - The model class type.
- * @param MyModel - The model class to register.
- * @returns The enhanced model class with ORM capabilities.
- * 
- * @example
- * ```typescript
- * ⁣@E.registerModel
- * class User extends E.Model<User> {
- *   static pk = E.index(User, ["id"], "primary");
- *   id = E.field(E.identifier);
- *   name = E.field(E.string);
- * }
- * ```
+ * A model constructor with its generic information erased.
+ *
+ * Useful when accepting or storing arbitrary registered model classes.
  */
-export function registerModel<T extends typeof Model<unknown>>(MyModel: T): T {
-    const MockModel = getMockModel(MyModel);
+export type AnyModelClass = ModelClass<new () => any, readonly any[], any, any>;
 
-    // Copy own static methods/properties
-    for(const name of Object.getOwnPropertyNames(MyModel)) {
-        if (name !== 'length' && name !== 'prototype' && name !== 'name' && name !== 'mock' && name !== 'override') {
-            (MockModel as any)[name] = (MyModel as any)[name];
+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)!);
         }
     }
-    MockModel.tableName ||= MyModel.name;
+}
 
-    // Register the constructor by name
-    if (MockModel.tableName in modelRegistry) {
-        if (!(MyModel as any).override) {
-            throw new DatabaseError(`Model with table name '${MockModel.tableName}' already registered`, 'INIT_ERROR');
+// 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()]);
         }
-        delete modelRegistry[MockModel.tableName];
+        return new DataPack().write({
+            migrateHash: this._currentMigrateHash,
+            fields,
+            secondaryKeys: new Set(Object.values(this._secondaries || {}).map(sec => sec._signature!)),
+        }).toUint8Array();
     }
-    modelRegistry[MockModel.tableName] = MockModel;
 
-    return MockModel;   
-}
+    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,
+                };
+            }
 
-export function getMockModel<T extends typeof Model<unknown>>(OrgModel: T): T {
-    const AnyOrgModel = OrgModel as any;
-    if (AnyOrgModel._isMock) return OrgModel;
-    if (AnyOrgModel._mock) return AnyOrgModel._mock;
+            for (const fieldName of this._indexFields.keys()) {
+                this._freezePrimaryKeyDescriptors[fieldName] = {
+                    writable: false,
+                    enumerable: true,
+                };
+            }
+        }
 
-    const MockModel = function(this: any, initial?: Record<string,any> | undefined, txn: Transaction = currentTxn()) {
-        // This constructor should only be called when the user does 'new Model'. We'll bypass this when
-        // loading objects. Add to 'instances', so the object will be saved.
-        this._txn = txn;
-        txn.instances.add(this);
-        if (initial) {
-            Object.assign(this, initial);
-        }
-    } as any as T;
-
-    // We want .constructor to point at our fake constructor function.
-    OrgModel.prototype.constructor = MockModel as any;
-
-    // Copy the prototype chain for the constructor as well as for instantiated objects
-    Object.setPrototypeOf(MockModel, Object.getPrototypeOf(OrgModel));
-    MockModel.prototype = OrgModel.prototype;
-    (MockModel as any)._isMock = true;
-    (MockModel as any)._original = OrgModel;
-    AnyOrgModel._mock = MockModel;
-    scheduleInit();
-    return MockModel;
+        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();
+    }
 }
 
-// Model base class and related symbols/state
-const INIT_INSTANCE_SYMBOL = Symbol();
+/**
+ * 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;
 
 /**
- * Model interface that ensures proper typing for the constructor property.
- * @template SUB - The concrete model subclass.
+ * 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 interface Model<SUB> {
-  constructor: typeof Model<SUB>;
+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>>;
+    };
+
+/**
+ * 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.
+ *
+ * Converts a plain class into a fully-featured model with database persistence,
+ * typed fields, primary key access, and optional secondary and unique indexes.
+ *
+ * @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<
+    T extends new () => any,
+    const PK extends (keyof FieldsOf<T> & string) | readonly (keyof FieldsOf<T> & string)[],
+    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, 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.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, ModelClassRuntime.prototype);
+    MockModel.prototype = cls.prototype;
+    copyStaticMembersFromClassChain(MockModel, cls);
+
+    MockModel.tableName = tableName;
+
+    if (MockModel.tableName in modelRegistry) {
+        if (!opts?.override) {
+            throw new DatabaseError(`Model with table name '${MockModel.tableName}' already registered`, 'INIT_ERROR');
+        }
+        delete modelRegistry[MockModel.tableName];
+    }
+
+    const instance = new cls();
+    if (!opts?.pk && !instance.id) {
+        instance.id = { type: identifier };
+    }
+
+    MockModel.fields = {};
+    for (const key in instance) {
+        const value = instance[key] as FieldConfig<unknown>;
+        if (value && value.type instanceof TypeWrapper) {
+            MockModel.fields[key] = value;
+
+            const defObj = value.default === undefined ? value.type : value;
+            const def = defObj.default;
+            if (typeof def === 'function') {
+                Object.defineProperty(MockModel.prototype, key, {
+                    get() {
+                        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[key] = def;
+            }
+        }
+    }
+
+    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);
+    }
+
+    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._secondaries[name] = new UniqueIndex(tableName, normalizeSpec(spec), loadPrimary, queueInitialization);
+        }
+    }
+    if (opts?.index) {
+        for (const [name, spec] of Object.entries<any>(opts.index)) {
+            MockModel._secondaries[name] = new SecondaryIndex(tableName, normalizeSpec(spec), loadPrimary, queueInitialization);
+        }
+    }
+
+    modelRegistry[MockModel.tableName] = MockModel;
+    pendingModelInits.add(MockModel);
+    return MockModel;
 }
 
 /**
  * Base class for all database models in the Edinburgh ORM.
  * 
  * 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 `@E.registerModel`.
+ * change tracking, and relationship management. Model classes are created using
+ * `E.defineModel()`.
  *
  * ### Schema Evolution
  *
@@ -192,72 +604,46 @@ 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
- * ⁣@E.registerModel
- * class User extends E.Model<User> {
- *   static pk = E.primary(User, "id");
- *   
+ * const User = E.defineModel("User", class {
  *   id = E.field(E.identifier);
  *   name = E.field(E.string);
  *   email = E.field(E.string);
- *   
- *   static byEmail = E.unique(User, "email");
- * }
+ * }, {
+ *   pk: "id",
+ *   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?: BaseIndex<any, readonly (keyof any & string)[]>[];
-
-    /** The database table name (defaults to class name). */
-    static tableName: string;
-
-    /** When true, registerModel replaces an existing model with the same tableName. */
-    static override?: boolean;
-
-    /** Field configuration metadata. */
-    static fields: Record<string | symbol | number, FieldConfig<unknown>>;
-
+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
-     * ⁣@E.registerModel
-     * class User extends E.Model<User> {
-     *   static pk = E.primary(User, "id");
+     * 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" });
      * ```
      */
     static migrate?(record: Record<string, any>): void;
@@ -272,20 +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">> = {}) {
-        // 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 @E.registerModel decorator", '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.
@@ -298,9 +678,7 @@ export abstract class Model<SUB> {
      *
      * @example
      * ```typescript
-     * ⁣@E.registerModel
-     * class Post extends E.Model<Post> {
-     *   static pk = E.primary(Post, "id");
+     * const Post = E.defineModel("Post", class {
      *   id = E.field(E.identifier);
      *   title = E.field(E.string);
      *   slug = E.field(E.string);
@@ -308,94 +686,16 @@ export abstract class Model<SUB> {
      *   preCommit() {
      *     this.slug = this.title.toLowerCase().replace(/\s+/g, "-");
      *   }
-     * }
+     * }, { pk: "id" });
      * ```
      */
     preCommit?(): 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 (reset) {
-            MockModel._primary._indexId = undefined;
-            MockModel._primary._versions.clear();
-            for (const sec of MockModel._secondaries || []) sec._indexId = undefined;
-        }
-
-        if (MockModel.fields) return;
-
-        // 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;
-                }
-            }
-        }
-
-        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();
-        await MockModel._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);
@@ -405,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!._serializeKeyFields(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;
@@ -420,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);
     }
 
     /**
@@ -432,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";
         }
@@ -461,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);
             }
 
@@ -476,11 +789,12 @@ export abstract class Model<SUB> {
         // the whole object just to see if something changed.
 
         // Add old values of changed fields to 'changed'.
-        const fields = this.constructor.fields;
-        let changed : Record<any, any> = {};
+        const changed: Record<string, any> = {};
+        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;
             }
@@ -489,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");
             }
@@ -502,27 +816,11 @@ 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 || []) {
-            if (index._computeFn) {
-                // Computed indexes may depend on any field — compare serialized keys
-                const oldKeyBytes = index._serializeKeyFields(oldValues).toUint8Array();
-                const newKeyBytes = index._serializeKeyFields(this as any).toUint8Array();
-                if (!bytesEqual(oldKeyBytes, newKeyBytes)) {
-                    index._delete(txn, pk, oldValues);
-                    index._write(txn, pk, this);
-                }
-            } else {
-                for (const field of index._fieldTypes.keys()) {
-                    if (changed.hasOwnProperty(field)) {
-                        index._delete(txn, pk, oldValues);
-                        index._write(txn, pk, this);
-                        break;
-                    }
-                }
-            }
+        for (const index of Object.values(cls._secondaries || {})) {
+            index._update(txn, pk, this, oldValues);
         }
         return changed;
     }
@@ -534,60 +832,21 @@ export abstract class Model<SUB> {
      * 
      * @example
      * ```typescript
-     * const user = User.load("user123");
+     * const user = User.get("user123");
      * user.name = "New Name";
      * user.preventPersist(); // Changes won't be saved
      * ```
      */
     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;
     }
 
-    /**
-     * Find all instances of this model in the database, ordered by primary key.
-     * @param opts - Optional parameters.
-     * @param opts.reverse - If true, iterate in reverse order.
-     * @returns An iterator.
-     */
-    static findAll<T extends typeof Model<unknown>>(this: T, opts?: {reverse?: boolean}): IndexRangeIterator<T> {
-        return this._primary!.find(opts);
-    }
-
-    /**
-     * 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<Omit<InstanceType<T>, "constructor">>): 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.
      * 
@@ -595,18 +854,18 @@ export abstract class Model<SUB> {
      * 
      * @example
      * ```typescript
-     * const user = User.load("user123");
+     * const user = User.get("user123");
      * user.delete(); // Removes from database
      * ```
      */
     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
@@ -620,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);
             }
@@ -649,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";
             }
@@ -658,12 +918,55 @@ export abstract class Model<SUB> {
     }
 
     toString(): string {
-        const primary = this.constructor._primary;
-        const pk = primary._keyToArray(this._primaryKey || primary._serializeKeyFields(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;