edinburgh 0.3.0 → 0.4.2

package/src/models.ts

@@ -1,9 +1,35 @@
-import * as olmdb from "olmdb";
-import { DatabaseError } from "olmdb";
+import { DatabaseError } from "olmdb/lowlevel";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { TypeWrapper, identifier } from "./types.js";
+import { scheduleInit } from "./edinburgh.js";
+
+export const txnStorage = new AsyncLocalStorage<Transaction>();
+
+
+const PREVENT_PERSIST_DESCRIPTOR = {
+    get() {
+        throw new DatabaseError("Operation not allowed after preventPersist()", "NO_PERSIST");
+    },
+};
+
+/**
+ * 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, tryDelayedInits, delayedInits } from "./utils.js";
-import { on } from "events";
+import { addErrorPath, logLevel, assert, dbGet, hashBytes } from "./utils.js";
 
 /**
  * Configuration interface for model fields.
@@ -47,15 +73,6 @@ export function field<T>(type: TypeWrapper<T>, options: Partial<FieldConfig<T>>
 // Model registration and initialization
 export const modelRegistry: Record<string, typeof Model> = {};
 
-export function resetModelCaches() {
-    for(const model of Object.values(modelRegistry)) {
-        for(const index of model._secondaries || []) {
-            index._cachedIndexId = undefined;
-        }
-        delete model._primary?._cachedIndexId;
-    }
-}
-
 function isObjectEmpty(obj: object) {
     for (let _ of Object.keys(obj)) {
         return false;
@@ -63,9 +80,7 @@ function isObjectEmpty(obj: object) {
     return true;
 }
 
-export type ChangedModel = Model<unknown> & {
-    changed: Record<any, any> | "updated" | "deleted";
-}
+export type Change = Record<any, any> | "created" | "deleted";
 
 /**
  * Register a model class with the Edinburgh ORM system.
@@ -89,21 +104,21 @@ export function registerModel<T extends typeof Model<unknown>>(MyModel: T): T {
 
     // Copy own static methods/properties
     for(const name of Object.getOwnPropertyNames(MyModel)) {
-        if (name !== 'length' && name !== 'prototype' && name !== 'name' && name !== 'mock') {
+        if (name !== 'length' && name !== 'prototype' && name !== 'name' && name !== 'mock' && name !== 'override') {
             (MockModel as any)[name] = (MyModel as any)[name];
         }
     }
-
-    MockModel.tableName ||= MyModel.name; // Set the table name to the class name if not already set
+    MockModel.tableName ||= MyModel.name;
 
     // Register the constructor by name
-    if (MockModel.tableName in modelRegistry) throw new DatabaseError(`Model with table name '${MockModel.tableName}' already registered`, 'INIT_ERROR');
+    if (MockModel.tableName in modelRegistry) {
+        if (!(MyModel as any).override) {
+            throw new DatabaseError(`Model with table name '${MockModel.tableName}' already registered`, 'INIT_ERROR');
+        }
+        delete modelRegistry[MockModel.tableName];
+    }
     modelRegistry[MockModel.tableName] = MockModel;
 
-    // Attempt to instantiate the class and gather field metadata
-    delayedInits.add(MyModel);
-    tryDelayedInits();
-
     return MockModel;   
 }
 
@@ -112,16 +127,14 @@ export function getMockModel<T extends typeof Model<unknown>>(OrgModel: T): T {
     if (AnyOrgModel._isMock) return OrgModel;
     if (AnyOrgModel._mock) return AnyOrgModel._mock;
 
-    const name =  OrgModel.tableName || OrgModel.name;
-    const MockModel = function(this: any, initial?: Record<string,any>) {
-        if (delayedInits.has(this.constructor)) {
-            throw new DatabaseError("Cannot instantiate while linked models haven't been registered yet", 'INIT_ERROR');
-        }
-        if (initial && !isObjectEmpty(initial)) {
+    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);
         }
-        const instances = olmdb.getTransactionData(INSTANCES_SYMBOL) as Set<Model<any>>;
-        instances.add(this);
     } as any as T;
 
     // We want .constructor to point at our fake constructor function.
@@ -131,18 +144,15 @@ export function getMockModel<T extends typeof Model<unknown>>(OrgModel: T): T {
     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;
 }
 
 // Model base class and related symbols/state
 const INIT_INSTANCE_SYMBOL = Symbol();
 
-/** @internal Symbol used to attach modified instances to running transaction */
-export const INSTANCES_SYMBOL = Symbol('instances');
-
-/** @internal Symbol used to access the underlying model from a proxy */
-
 /**
  * Model interface that ensures proper typing for the constructor property.
  * @template SUB - The concrete model subclass.
@@ -158,19 +168,49 @@ export interface Model<SUB> {
  * change tracking, and relationship management. All model classes should extend
  * this base class and be decorated with `@registerModel`.
  *
+ * ### Schema Evolution
+ *
+ * Edinburgh tracks the schema version of each model automatically. When you add, remove, or
+ * change the types of fields, or add/remove indexes, Edinburgh detects the new schema version.
+ *
+ * **Lazy migration:** Changes to non-key field values are migrated lazily, when a row with an
+ * old schema version is read from disk, it is deserialized using the old schema and optionally
+ * transformed by the static `migrate()` function. This happens transparently on every read
+ * and requires no downtime or batch processing.
+ *
+ * **Batch migration (via `npx migrate-edinburgh` or `runMigration()`):** Certain schema changes
+ * require an explicit migration run:
+ * - Adding or removing secondary/unique indexes
+ * - Changing the fields or types of an existing index
+ * - A `migrate()` function that changes values used in secondary index fields
+ *
+ * The batch migration tool populates new indexes, deletes orphaned ones, and updates index
+ * entries whose values were changed by `migrate()`. It does *not* rewrite primary data rows
+ * (lazy migration handles that).
+ *
+ * ### Lifecycle Hooks
+ *
+ * - **`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}.
+ *
  * @template SUB - The concrete model subclass (for proper typing).
  * 
  * @example
  * ```typescript
  * ⁣@E.registerModel
  * class User extends E.Model<User> {
- *   static pk = E.index(User, ["id"], "primary");
+ *   static pk = E.primary(User, "id");
  *   
  *   id = E.field(E.identifier);
  *   name = E.field(E.string);
  *   email = E.field(E.string);
  *   
- *   static byEmail = E.index(User, "email", "unique");
+ *   static byEmail = E.unique(User, "email");
  * }
  * ```
  */
@@ -185,9 +225,43 @@ export abstract class Model<SUB> {
     /** 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>>;
 
+    /**
+     * 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.
+     *
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * ⁣@E.registerModel
+     * class User extends E.Model<User> {
+     *   static pk = E.primary(User, "id");
+     *   id = E.field(E.identifier);
+     *   name = E.field(E.string);
+     *   role = E.field(E.string);  // new field
+     *
+     *   static migrate(record: Record<string, any>) {
+     *     record.role ??= "user";  // default for rows that predate the 'role' field
+     *   }
+     * }
+     * ```
+     */
+    static migrate?(record: Record<string, any>): void;
+
     /*
      * IMPORTANT: We cannot use instance property initializers here, because we will be
      * initializing the class through a fake constructor that will skip these. This is
@@ -196,118 +270,157 @@ export abstract class Model<SUB> {
     
     /** 
      * @internal
-     * - !_oldValues: New instance, not yet saved.
-     * - _oldValues && _primaryKey: Loaded (possibly only partial, still lazy) from disk, _oldValues contains (partial) old values
+     * - _oldValues===undefined: New instance, not yet saved.
+     * - _oldValues===null: Instance is to be deleted.
+     * - _oldValues is an object: Loaded (possibly only partial, still lazy) from disk, _oldValues contains (partial) old values
      */
-    _oldValues: Partial<Model<SUB>> | undefined;
+    _oldValues: Record<string, any> | undefined | null;
     _primaryKey: Uint8Array | undefined;
-
-    /**
-     * This property can be used in `setOnSave` callbacks to determine how a model instance has changed.
-     * If the value is undefined, the instance has been created. If it's "deleted" the instance has
-     * been deleted. If its an object, the instance has been modified and the object contains the old values.
-     * 
-     * Note: this property should **not** be accessed *during* a `transact()` -- it's state is an implementation
-     * detail that may change semantics at any minor release.
-     */
-    changed?: Record<any,any> | "deleted" | "created";
-
-    // Reference the static `fields` property; the mock constructor copies it here for performance
-    _fields!: Record<string | symbol | number, FieldConfig<unknown>>;
+    _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) {
-            throw new DatabaseError("The model needs a @registerModel decorator", 'INIT_ERROR');
-        }
+        if (initial as any === INIT_INSTANCE_SYMBOL) return;
+        throw new DatabaseError("The model needs a @registerModel decorator", 'INIT_ERROR');
     }
 
-    static _delayedInit(): boolean {
+    /**
+     * 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.
+     *
+     * Common use cases:
+     * - Computing derived or denormalized fields
+     * - Enforcing cross-field validation rules
+     * - Creating or updating related model instances (newly created instances will also
+     *   have their `preCommit()` called)
+     *
+     * @example
+     * ```typescript
+     * ⁣@E.registerModel
+     * class Post extends E.Model<Post> {
+     *   static pk = E.primary(Post, "id");
+     *   id = E.field(E.identifier);
+     *   title = E.field(E.string);
+     *   slug = E.field(E.string);
+     *
+     *   preCommit() {
+     *     this.slug = this.title.toLowerCase().replace(/\s+/g, "-");
+     *   }
+     * }
+     * ```
+     */
+    preCommit?(): void;
+
+    static async _delayedInit(cleared?: boolean): Promise<void> {
         const MockModel = getMockModel(this);
-        // Create an instance (the only one to ever exist) of the actual class,
-        // in order to gather field config data. 
-        let instance;
-        try {
-            instance = new (this as any)(INIT_INSTANCE_SYMBOL);
-        } catch(e) {
-            if (!(e instanceof ReferenceError)) throw e;
-            // ReferenceError: Cannot access 'SomeLinkedClass' before initialization.
-            // We'll try again after the next class has successfully initialized.
-            return false;
+
+        if (cleared) {
+            MockModel._primary._indexId = undefined;
+            MockModel._primary._versions.clear();
+            for (const sec of MockModel._secondaries || []) sec._indexId = undefined;
         }
 
-        // If no primary key exists, create one using 'id' field
-        if (!MockModel._primary) {
-            // If no `id` field exists, add it automatically
-            if (!instance.id) {
-                instance.id = { type: identifier }; 
+        if (!MockModel.fields) {
+            // First-time init: gather field configs from a temporary instance of the original class.
+            const OrgModel = (MockModel as any)._original || this;
+            const instance = new (OrgModel as any)(INIT_INSTANCE_SYMBOL);
+
+            // If 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']);
             }
-            // @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 = MockModel.prototype._fields = {};
-        for (const key in instance) {
-            const value = instance[key] as FieldConfig<unknown>;
-            // Check if this property contains field metadata
-            if (value && value.type instanceof TypeWrapper) {
-                // Set the configuration on the constructor's `fields` property
-                MockModel.fields[key] = value;
-
-                // Set default value on the prototype
-                const defObj = value.default===undefined ? value.type : value;
-                const def = defObj.default;
-                if (typeof def === 'function') {
-                    // The default is a function. We'll define a getter on the property in the model prototype,
-                    // and once it is read, we'll run the function and set the value as a plain old property
-                    // on the instance object.
-                    Object.defineProperty(MockModel.prototype, key, {    
-                        get() {
-                            // This will call set(), which will define the property on the instance.
-                            return (this[key] = def.call(defObj, this));
-                        },
-                        set(val: any) {
-                            Object.defineProperty(this, key, {
-                                value: val,
-                                configurable: true,
-                                writable: true,
-                                enumerable: true,
-                            })
-                        },
-                        configurable: true,    
-                    });
-                } else if (def !== undefined) {
-                    (MockModel.prototype as any)[key] = def;
+            MockModel.fields = {};
+            for (const key in instance) {
+                const value = instance[key] as FieldConfig<unknown>;
+                // Check if this property contains field metadata
+                if (value && value.type instanceof TypeWrapper) {
+                    // Set the configuration on the constructor's `fields` property
+                    MockModel.fields[key] = value;
+
+                    // Set default value on the prototype
+                    const defObj = value.default===undefined ? value.type : value;
+                    const def = defObj.default;
+                    if (typeof def === 'function') {
+                        // The default is a function. We'll define a getter on the property in the model prototype,
+                        // and once it is read, we'll run the function and set the value as a plain old property
+                        // on the instance object.
+                        Object.defineProperty(MockModel.prototype, key, {    
+                            get() {
+                                // This will call set(), which will define the property on the instance.
+                                return (this[key] = def.call(defObj, this));
+                            },
+                            set(val: any) {
+                                Object.defineProperty(this, key, {
+                                    value: val,
+                                    configurable: true,
+                                    writable: true,
+                                    enumerable: true,
+                                })
+                            },
+                            configurable: true,    
+                        });
+                    } else if (def !== undefined) {
+                        (MockModel.prototype as any)[key] = def;
+                    }
                 }
             }
-        }
 
-        if (logLevel >= 1) {
-            console.log(`Registered model ${MockModel.tableName} with fields: ${Object.keys(MockModel.fields).join(' ')}`);
+            if (logLevel >= 1) {
+                console.log(`[edinburgh] Registered model ${MockModel.tableName} with fields: ${Object.keys(MockModel.fields).join(' ')}`);
+            }
         }
 
-        return true;
+        // 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 orgValues = this._oldValues ||= Object.create(Object.getPrototypeOf(this));
-        if (orgValues.hasOwnProperty(fieldName)) return; // Already loaded earlier (as part of index key?)
+        const oldValues = this._oldValues!;
+        if (oldValues.hasOwnProperty(fieldName)) return; // Already loaded earlier (as part of index key?)
 
-        const fieldType = (this._fields[fieldName] as FieldConfig<unknown>).type;
         this[fieldName as keyof Model<SUB>] = value;
-        orgValues[fieldName] = fieldType.clone(value);
+        if (typeof value === 'object' && value !== null) {            
+            const fieldType = (this.constructor.fields[fieldName] as FieldConfig<unknown>).type;
+            oldValues[fieldName] = fieldType.clone(value);
+        } else {
+            // This path is just an optimization
+            oldValues[fieldName] = value;
+        }
     }
 
     /**
-     * @returns The primary key for this instance, or undefined if not yet saved.
+     * @returns The primary key for this instance.
      */
-    getPrimaryKey(): Uint8Array | undefined {
-        return this._primaryKey;
+    getPrimaryKey(): Uint8Array {
+        let key = this._primaryKey;
+        if (key === undefined) {
+            key = this.constructor._primary!._serializeKeyFields(this).toUint8Array();
+            this._setPrimaryKey(key);
+        }
+        return key;
     }
 
-    _getCreatePrimaryKey(): Uint8Array {
-        return this._primaryKey ||= this.constructor._primary!._instanceToKeySingleton(this);
+    _setPrimaryKey(key: Uint8Array, hash?: number) {
+        this._primaryKey = key;
+        this._primaryKeyHash = hash ?? hashBytes(key);
+        Object.defineProperties(this, this.constructor._primary._freezePrimaryKeyDescriptors);
+    }
+
+    /**
+     * @returns A 53-bit positive integer non-cryptographic hash of the primary key, or undefined if not yet saved.
+     */
+    getPrimaryKeyHash(): number {
+        if (this._primaryKeyHash === undefined) this.getPrimaryKey();
+        return this._primaryKeyHash!;
     }
 
     isLazyField(field: keyof this) {
@@ -315,82 +428,83 @@ export abstract class Model<SUB> {
         return !!(descr && 'get' in descr && descr.get === Reflect.getOwnPropertyDescriptor(this, field)?.get);
     }
 
-    _onCommit(onSaveQueue: ChangedModel[] | undefined) {
+    _write(txn: Transaction): undefined | Change {
         const oldValues = this._oldValues;
-        let changed : Record<any, any> | "created" | "deleted";
-
-        if (oldValues)  {
-            // We're doing an update. Note that we may still be in a lazy state, and we don't want to load
-            // the whole object just to see if something changed.
-
-            //  Delete all items from this.changed that have not actually changed.
-            const fields = this._fields;
-            changed = {};
-            for(const fieldName of Object.keys(oldValues) as Iterable<keyof Model<SUB>>) {
-                const oldValue = oldValues[fieldName];
-                if (!(fields[fieldName] as FieldConfig<unknown>).type.equals(this[fieldName], oldValue)) {
-                    changed[fieldName] = oldValue;
-                }
-            }
-            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()) {
-                if (changed.hasOwnProperty(field)) {
-                    throw new DatabaseError(`Cannot modify primary key field: ${field}`, "CHANGE_PRIMARY");
-                }
-            }
 
-            // We have changes. Now it's okay for any lazy fields to be loaded (which the validate will trigger).
-
-            // Raise any validation errors
-            this.validate(true);
-
-            // Update the primary index
-            this.constructor._primary!._write(this);
-
-            // Update any secondaries with changed fields
-            for (const index of this.constructor._secondaries || []) {
-                for (const field of index._fieldTypes.keys()) {
-                    if (changed.hasOwnProperty(field)) {
-                        // We need to update this index - first delete the old one
-                        index._delete(oldValues);
-                        index._write(this)
-                        break;
-                    }
-                }
-            }
-        } else if (this._primaryKey) { // Deleted instance
-            this.constructor._primary._delete(this);
+        if (oldValues === null) { // Delete instance
+            const pk = this._primaryKey;
+            this.constructor._primary._delete(txn, pk!, this);
             for(const index of this.constructor._secondaries || []) {
-                index._delete(this);
+                index._delete(txn, pk!, this);
             }
-            changed = "deleted";
-        } else {
-            // New instance
-            // Raise any validation errors
+            
+            return "deleted";
+        }
+        
+        if (oldValues === undefined) { // Create instance
             this.validate(true);
 
             // Make sure the primary key does not already exist
-            if (olmdb.get(this._getCreatePrimaryKey())) {
+            const pk = this.getPrimaryKey();
+            if (dbGet(txn.id, pk!)) {
                 throw new DatabaseError("Unique constraint violation", "UNIQUE_CONSTRAINT");
             }
 
             // Insert the primary index
-            this.constructor._primary!._write(this);
+            this.constructor._primary!._write(txn, pk!, this);
 
             // Insert all secondaries
             for (const index of this.constructor._secondaries || []) {
-                index._write(this);
+                index._write(txn, pk!, this);
+            }
+
+            return "created";
+        }
+
+        // oldValues is an object.
+        // We're doing an update. Note that we may still be in a lazy state, and we don't want to load
+        // 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> = {};
+        for(const fieldName in oldValues) {
+            const oldValue = oldValues[fieldName];
+            const newValue = this[fieldName as keyof Model<SUB>];
+            if (newValue !== oldValue  && !(fields[fieldName] as FieldConfig<unknown>).type.equals(newValue, oldValue)) {
+                changed[fieldName] = oldValue;
             }
+        }
 
-            changed = "created";
+        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()) {
+            if (changed.hasOwnProperty(field)) {
+                throw new DatabaseError(`Cannot modify primary key field: ${field}`, "CHANGE_PRIMARY");
+            }
         }
 
-        if (onSaveQueue) {
-            this.changed = changed;
-            onSaveQueue.push(this as ChangedModel);
+        // We have changes. Now it's okay for any lazy fields to be loaded (which the validate will trigger).
+
+        // Raise any validation errors
+        this.validate(true);
+
+        // Update the primary index
+        const pk = this._primaryKey!;
+        this.constructor._primary!._write(txn, pk, this);
+
+        // Update any secondaries with changed fields
+        for (const index of this.constructor._secondaries || []) {
+            for (const field of index._fieldTypes.keys()) {
+                if (changed.hasOwnProperty(field)) {
+                    index._delete(txn, pk, oldValues);
+                    index._write(txn, pk, this);
+                    break;
+                }
+            }
         }
+        return changed;
     }
 
     /**
@@ -406,8 +520,9 @@ export abstract class Model<SUB> {
      * ```
      */
     preventPersist() {
-        const instances = olmdb.getTransactionData(INSTANCES_SYMBOL) as Set<Model<any>>;
-        instances.delete(this);
+        this._txn.instances.delete(this);
+        // Have access to '_txn' throw a descriptive error:
+        Object.defineProperty(this, "_txn", PREVENT_PERSIST_DESCRIPTOR);
         return this;
     }
 
@@ -421,6 +536,38 @@ export abstract class Model<SUB> {
         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.
      * 
@@ -433,8 +580,8 @@ export abstract class Model<SUB> {
      * ```
      */
     delete() {
-        if (!this._primaryKey) throw new DatabaseError("Cannot delete unsaved instance", "NOT_SAVED");
-        this._oldValues = undefined;
+        if (this._oldValues === undefined) throw new DatabaseError("Cannot delete unsaved instance", "NOT_SAVED");
+        this._oldValues = null;
     }
 
     /**
@@ -454,7 +601,7 @@ export abstract class Model<SUB> {
     validate(raise: boolean = false): Error[] {
         const errors: Error[] = [];
         
-        for (const [key, fieldConfig] of Object.entries(this._fields)) {
+        for (const [key, fieldConfig] of Object.entries(this.constructor.fields)) {
             let e = fieldConfig.type.getError((this as any)[key]);
             if (e) {
                 e = addErrorPath(e, this.constructor.tableName+"."+key);
@@ -478,4 +625,25 @@ export abstract class Model<SUB> {
     isValid(): boolean {
         return this.validate().length === 0;
     }
+
+    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)) {
+            if (descr && 'get' in descr && descr.get === Reflect.getOwnPropertyDescriptor(this, key)?.get) {
+                return "lazy";
+            }
+        }
+        return "loaded";
+    }
+
+    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}}`;
+    }
+
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return this.toString();
+    }
 }