edinburgh 0.4.6 → 0.6.0

package/build/src/models.d.ts

@@ -1,18 +1,7 @@
-import { AsyncLocalStorage } from "node:async_hooks";
+import DataPack from "./datapack.js";
 import { TypeWrapper } from "./types.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";
+import { type Transaction } from "./edinburgh.js";
+import { PrimaryKey, NonPrimaryIndex, IndexRangeIterator, FindOptions, VersionInfo } from "./indexes.js";
 /**
  * Configuration interface for model fields.
  * @template T - The field type.
@@ -33,53 +22,161 @@ 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 declare function field<T>(type: TypeWrapper<T>, options?: Partial<FieldConfig<T>>): T;
-export declare const modelRegistry: Record<string, typeof Model>;
 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.
+ * A model constructor with its generic information erased.
  *
- * @template T - The model class type.
- * @param MyModel - The model class to register.
- * @returns The enhanced model class with ORM capabilities.
+ * Useful when accepting or storing arbitrary registered model classes.
+ */
+export type AnyModelClass = ModelClass<new () => any, readonly any[], any, any>;
+type SecondaryRegistry<FIELDS> = Record<string, NonPrimaryIndex<Model<FIELDS>, readonly (keyof FIELDS & string)[], readonly any[]>>;
+export declare const modelRegistry: Record<string, AnyModelClass>;
+export declare const pendingModelInits: Set<AnyModelClass>;
+declare class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX = {}> extends PrimaryKey<Model<FIELDS>, readonly (keyof FIELDS & string)[], PKA> {
+    tableName: string;
+    fields: Record<string | symbol | number, FieldConfig<unknown>>;
+    _secondaries?: SecondaryRegistry<FIELDS>;
+    _nonKeyFields: (keyof FIELDS & string)[];
+    _lazyDescriptors: Record<string | symbol | number, PropertyDescriptor>;
+    _resetDescriptors: Record<string | symbol | number, PropertyDescriptor>;
+    _freezePrimaryKeyDescriptors: Record<string | symbol | number, PropertyDescriptor>;
+    _currentVersion: number;
+    _currentMigrateHash: number;
+    _versions: Map<number, VersionInfo>;
+    _serializeVersionValue(): Uint8Array;
+    _initialize(reset?: boolean): Promise<void>;
+    _getSecondary(name: string): NonPrimaryIndex<Model<FIELDS>, readonly (keyof FIELDS & string)[], readonly any[]>;
+    _get(txn: Transaction, args: PKA | Uint8Array, loadNow: false | Uint8Array): Model<FIELDS>;
+    _get(txn: Transaction, args: PKA | Uint8Array, loadNow: true): Model<FIELDS> | undefined;
+    _lazyLoad(model: Model<FIELDS>): void;
+    /**
+     * 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;
+    /**
+     * 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>;
+    _pairToInstance(txn: Transaction, keyBuffer: ArrayBuffer, valueBuffer: ArrayBuffer): Model<FIELDS>;
+    /**
+     * 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>;
+    /**
+     * 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;
+    /**
+     * 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>>;
+    /**
+     * 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>;
+    _loadValueFields(model: Model<FIELDS>, valueArray: Uint8Array): void;
+    _loadVersionInfo(txnId: number, version: number): VersionInfo;
+    _migrateValueFields(model: Model<FIELDS>, version: number, valuePack: DataPack): void;
+    _serializeValue(data: Record<string, any>): Uint8Array;
+}
+/**
+ * Runtime base constructor for model classes returned by `defineModel()`.
  *
- * @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);
- * }
- * ```
+ * Prefer the `ModelClass` type alias for annotations and the result of
+ * `defineModel()` for concrete model classes.
  */
-export declare function registerModel<T extends typeof Model<unknown>>(MyModel: T): T;
-export declare function getMockModel<T extends typeof Model<unknown>>(OrgModel: T): T;
+export declare const ModelClass: typeof 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 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 Model<SUB> {
-    constructor: typeof Model<SUB>;
+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 declare 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>;
 /**
  * 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
  *
@@ -105,65 +202,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}.
- *
- * @template SUB - The concrete model subclass (for proper typing).
+ *   instances.
  *
  * @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 declare 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 declare 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.
+    * 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()`.
      *
-     * 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.
+     * @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;
@@ -171,13 +249,13 @@ export declare 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">>);
     /**
      * 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.
@@ -190,9 +268,7 @@ export declare 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);
@@ -200,18 +276,12 @@ export declare 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;
-    static _loadCreateIndexes(): Promise<void>;
     _setLoadedField(fieldName: string, value: any): void;
+    _restoreLazyFields(): void;
     /**
      * @returns The primary key for this instance.
      */
@@ -230,32 +300,12 @@ export declare 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;
-    /**
-     * 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.
      *
@@ -263,14 +313,14 @@ export declare abstract class Model<SUB> {
      *
      * @example
      * ```typescript
-     * const user = User.load("user123");
+     * const user = User.get("user123");
      * user.delete(); // Removes from database
      * ```
      */
     delete(): void;
     /**
      * 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
@@ -297,3 +347,17 @@ export declare abstract class Model<SUB> {
     getState(): "deleted" | "created" | "loaded" | "lazy";
     toString(): string;
 }
+/**
+ * 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 declare function deleteEverything(): Promise<void>;
+/**
+ * A model instance, including its user-defined fields.
+ * @template FIELDS - The fields defined on this model.
+ */
+export type Model<FIELDS> = FIELDS & ModelBase;
+export declare const Model: typeof ModelBase;
+export {};