edinburgh 0.1.3 → 0.4.1

package/build/src/models.d.ts

@@ -1,6 +1,18 @@
-import { DatabaseError } from "olmdb";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { TypeWrapper } from "./types.js";
-import { BaseIndex, PrimaryIndex } from "./indexes.js";
+export declare const txnStorage: AsyncLocalStorage<Transaction>;
+/**
+ * Returns the current transaction from AsyncLocalStorage.
+ * Throws if called outside a transact() callback.
+ * @internal
+ */
+export declare function currentTxn(): Transaction;
+export interface Transaction {
+    id: number;
+    instances: Set<Model<unknown>>;
+    instancesByPk: Map<number, Model<unknown>>;
+}
+import { BaseIndex as BaseIndex, PrimaryIndex, IndexRangeIterator } from "./indexes.js";
 /**
  * Configuration interface for model fields.
  * @template T - The field type.
@@ -35,21 +47,10 @@ export interface FieldConfig<T> {
  */
 export declare function field<T>(type: TypeWrapper<T>, options?: Partial<FieldConfig<T>>): T;
 export declare const modelRegistry: Record<string, typeof Model>;
-export declare function resetModelCaches(): void;
-type OnSaveType = (model: InstanceType<typeof Model>, newKey: Uint8Array | undefined, oldKey: Uint8Array | undefined) => void;
-/**
- * Set a callback function to be called after a model is saved and committed.
- *
- * @param callback The callback function to set. As arguments, it receives the model instance, the new key (undefined in case of a delete), and the old key (undefined in case of a create).
- */
-export declare function setOnSaveCallback(callback: OnSaveType | undefined): void;
+export type Change = Record<any, any> | "created" | "deleted";
 /**
  * Register a model class with the Edinburgh ORM system.
  *
- * This decorator function transforms the model class to use a proxy-based constructor
- * that enables change tracking and automatic field initialization. It also extracts
- * field metadata and sets up default values on the prototype.
- *
  * @template T - The model class type.
  * @param MyModel - The model class to register.
  * @returns The enhanced model class with ORM capabilities.
@@ -66,9 +67,6 @@ export declare function setOnSaveCallback(callback: OnSaveType | undefined): voi
  */
 export declare function registerModel<T extends typeof Model<unknown>>(MyModel: T): T;
 export declare function getMockModel<T extends typeof Model<unknown>>(OrgModel: T): T;
-/** @internal Symbol used to attach modified instances to running transaction */
-export declare const MODIFIED_INSTANCES_SYMBOL: unique symbol;
-/** @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.
@@ -83,62 +81,145 @@ 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");
  * }
  * ```
  */
 export declare abstract class Model<SUB> {
-    /** @internal Primary key index for this model. */
-    static _pk?: PrimaryIndex<any, any>;
-    /** @internal All indexes for this model, the primary key being first. */
-    static _indexes?: BaseIndex<any, any>[];
+    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, FieldConfig<unknown>>;
-    /** @internal Field configuration for this instance. */
-    _fields: Record<string, FieldConfig<unknown>>;
+    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;
     /**
-     * @internal State tracking for this model instance:
-     * - undefined: new instance, unmodified
-     * - 1: new instance, modified (and in modifiedInstances)
-     * - 2: loaded from disk, unmodified
-     * - 3: persistence disabled
-     * - array: loaded from disk, modified (and in modifiedInstances), array values are original index buffers
+     * @internal
+     * - _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
      */
-    _state: undefined | 1 | 2 | 3 | Array<Uint8Array>;
+    _oldValues: Record<string, any> | undefined | null;
+    _primaryKey: Uint8Array | undefined;
+    _primaryKeyHash: number | undefined;
+    _txn: Transaction;
     constructor(initial?: Partial<Omit<SUB, "constructor">>);
-    _save(): void;
     /**
-     * Load a model instance by primary key.
-     * @param args - Primary key field values.
-     * @returns The model instance if found, undefined otherwise.
+     * 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
-     * const user = User.load("user123");
-     * const post = Post.load("post456", "en");
+     * ⁣@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, "-");
+     *   }
+     * }
      * ```
      */
-    static load<SUB>(this: typeof Model<SUB>, ...args: any[]): SUB | undefined;
+    preCommit?(): void;
+    static _delayedInit(cleared?: boolean): Promise<void>;
+    _setLoadedField(fieldName: string, value: any): void;
+    /**
+     * @returns The primary key for this instance.
+     */
+    getPrimaryKey(): Uint8Array;
+    _setPrimaryKey(key: Uint8Array, hash?: number): void;
+    /**
+     * @returns A 53-bit positive integer non-cryptographic hash of the primary key, or undefined if not yet saved.
+     */
+    getPrimaryKeyHash(): number;
+    isLazyField(field: keyof this): boolean;
+    _write(txn: Transaction): undefined | Change;
     /**
      * Prevent this instance from being persisted to the database.
      *
-     * Removes the instance from the modified instances set and disables
-     * automatic persistence at transaction commit.
-     *
      * @returns This model instance for chaining.
      *
      * @example
@@ -149,6 +230,26 @@ export declare abstract class Model<SUB> {
      * ```
      */
     preventPersist(): 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>;
+    /**
+     * 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>;
     /**
      * Delete this model instance from the database.
      *
@@ -175,7 +276,7 @@ export declare abstract class Model<SUB> {
      * }
      * ```
      */
-    validate(raise?: boolean): DatabaseError[];
+    validate(raise?: boolean): Error[];
     /**
      * Check if this model instance is valid.
      * @returns true if all validations pass.
@@ -187,6 +288,6 @@ export declare abstract class Model<SUB> {
      * ```
      */
     isValid(): boolean;
+    getState(): "deleted" | "created" | "loaded" | "lazy";
+    toString(): string;
 }
-export declare const modificationTracker: ProxyHandler<any>;
-export {};