edinburgh 0.4.6 → 0.6.0

package/skill/Schema Evolution.md

@@ -0,0 +1,19 @@
+### 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).

package/skill/TypeWrapper_containsNull.md

@@ -0,0 +1,11 @@
+#### typeWrapper.containsNull · method
+
+Check if indexing should be skipped for this field value.
+
+**Signature:** `(value: T) => boolean`
+
+**Parameters:**
+
+- `value: T`
+
+**Returns:** true if indexing should be skipped.

package/skill/TypeWrapper_deserialize.md

@@ -0,0 +1,9 @@
+#### typeWrapper.deserialize · abstract method
+
+Deserialize a value from a Pack into an object property.
+
+**Signature:** `(pack: DataPack) => T`
+
+**Parameters:**
+
+- `pack: DataPack` - The Pack instance to read from.

package/skill/TypeWrapper_getError.md

@@ -0,0 +1,11 @@
+#### typeWrapper.getError · abstract method
+
+Validate a value.
+
+**Signature:** `(value: T) => void | DatabaseError`
+
+**Parameters:**
+
+- `value: T` - The value to validate.
+
+**Returns:** - A DatabaseError if validation fails.

package/skill/TypeWrapper_serialize.md

@@ -0,0 +1,10 @@
+#### typeWrapper.serialize · abstract method
+
+Serialize a value from an object property to a Pack.
+
+**Signature:** `(value: T, pack: DataPack) => void`
+
+**Parameters:**
+
+- `value: T` - The value to serialize.
+- `pack: DataPack` - The Pack instance to write to.

package/skill/TypeWrapper_serializeType.md

@@ -0,0 +1,9 @@
+#### typeWrapper.serializeType · method
+
+Serialize type metadata to a Pack (for schema serialization).
+
+**Signature:** `(pack: DataPack) => void`
+
+**Parameters:**
+
+- `pack: DataPack` - The Pack instance to write to.

package/skill/array.md

@@ -10,8 +10,8 @@ Create an array type wrapper with optional length constraints.
 
 **Parameters:**
 
-- `inner: TypeWrapper<T>` - - Type wrapper for array elements.
-- `opts: {min?: number, max?: number}` (optional) - - Optional constraints (min/max length).
+- `inner: TypeWrapper<T>` - Type wrapper for array elements.
+- `opts: {min?: number, max?: number}` (optional) - Optional constraints (min/max length).
 
 **Returns:** An array type instance.
 

package/skill/defineModel.md

@@ -0,0 +1,23 @@
+### defineModel · function
+
+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.
+
+**Signature:** `<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) | ...`
+
+**Type Parameters:**
+
+- `T extends new () => any`
+- `PK extends (keyof FieldsOf<T> & string) | readonly (keyof FieldsOf<T> & string)[]`
+- `UNIQUE extends Record<string, (keyof FieldsOf<T> & string) | readonly (keyof FieldsOf<T> & string)[] | ((instance: any) => any)>`
+- `INDEX extends Record<string, (keyof FieldsOf<T> & string) | readonly (keyof FieldsOf<T> & string)[] | ((instance: any) => any)>`
+
+**Parameters:**
+
+- `tableName: string` - The database table name for this model.
+- `cls: T` - A plain class whose properties use E.field().
+- `opts?: { pk?: PK, unique?: UNIQUE, index?: INDEX, override?: boolean }` - Registration options.
+
+**Returns:** The enhanced model constructor.

package/skill/deleteEverything.md

@@ -0,0 +1,8 @@
+### deleteEverything · function
+
+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.
+
+**Signature:** `() => Promise<void>`

package/skill/field.md

@@ -14,16 +14,16 @@ This allows for both runtime introspection and compile-time type safety.
 
 **Parameters:**
 
-- `type: TypeWrapper<T>` - - The type wrapper for this field.
-- `options: Partial<FieldConfig<T>>` (optional) - - Additional field configuration options.
+- `type: TypeWrapper<T>` - The type wrapper for this field.
+- `options: Partial<FieldConfig<T>>` (optional) - Additional field configuration options.
 
 **Returns:** The field value (typed as T, but actually returns FieldConfig<T>).
 
 **Examples:**
 
 ```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});
-}
+});
 ```

package/skill/link.md

@@ -2,26 +2,28 @@
 
 Create a link type wrapper for model relationships.
 
-**Signature:** `<const T extends typeof Model<any>>(TargetModel: T) => TypeWrapper<InstanceType<T>>`
+**Signature:** `{ <const T extends new (...args: any[]) => Model<any>>(TargetModel: T): TypeWrapper<InstanceType<T>>; <const T extends new (...args: any[]) => Model<any>>(TargetModel: () => T): TypeWrapper<...>; }`
 
 **Type Parameters:**
 
-- `T extends typeof Model<any>` - The target model class.
+- `T extends new (...args: any[]) => Model<any>` - The target model class.
 
 **Parameters:**
 
-- `TargetModel: T` - - The model class this link points to.
+- `TargetModel: T` - The model class this link points to.
 
 **Returns:** A link type instance.
 
 **Examples:**
 
 ```typescript
-class User extends E.Model<User> {
-  posts = E.field(E.array(E.link(Post, 'author')));
-}
-
-class Post extends E.Model<Post> {
-  author = E.field(E.link(User));
-}
+const Author = E.defineModel("Author", class {
+  id = E.field(E.identifier);
+  posts = E.field(E.array(E.link(() => Book)));
+}, { pk: "id" });
+
+const Book = E.defineModel("Book", class {
+  id = E.field(E.identifier);
+  author = E.field(E.link(Author));
+}, { pk: "id" });
 ```

package/skill/literal.md

@@ -10,7 +10,7 @@ Create a literal type wrapper for a constant value.
 
 **Parameters:**
 
-- `value: T` - - The literal value.
+- `value: T` - The literal value.
 
 **Returns:** A literal type instance.
 

package/skill/opt.md

@@ -10,7 +10,7 @@ Create an optional type wrapper (allows undefined).
 
 **Parameters:**
 
-- `inner: T` - - The inner type to make optional.
+- `inner: T` - The inner type to make optional.
 
 **Returns:** A union type that accepts the inner type or undefined.
 

package/skill/or.md

@@ -10,7 +10,7 @@ Create a union type wrapper from multiple type choices.
 
 **Parameters:**
 
-- `choices: T` - - The type choices for the union.
+- `choices: T` - The type choices for the union.
 
 **Returns:** A union type instance.
 

package/skill/record.md

@@ -10,7 +10,7 @@ Create a Record type wrapper for key-value objects with string or number keys.
 
 **Parameters:**
 
-- `inner: TypeWrapper<T>` - - Type wrapper for record values.
+- `inner: TypeWrapper<T>` - Type wrapper for record values.
 
 **Returns:** A record type instance.
 

package/skill/set.md

@@ -10,8 +10,8 @@ Create a Set type wrapper with optional length constraints.
 
 **Parameters:**
 
-- `inner: TypeWrapper<T>` - - Type wrapper for set elements.
-- `opts: {min?: number, max?: number}` (optional) - - Optional constraints (min/max length).
+- `inner: TypeWrapper<T>` - Type wrapper for set elements.
+- `opts: {min?: number, max?: number}` (optional) - Optional constraints (min/max length).
 
 **Returns:** A set type instance.
 

package/skill/setOnSaveCallback.md

@@ -2,11 +2,11 @@
 
 Set a callback function to be called after a model is saved and committed.
 
-**Signature:** `(callback: (commitId: number, items: Map<Model<any>, Change>) => void) => void`
+**Signature:** `(callback: (commitId: number, items: Map<ModelBase, Change>) => void) => void`
 
 **Parameters:**
 
-- `callback: ((commitId: number, items: Map<Model<any>, Change>) => void) | undefined` - The callback function to set. It gets called after each successful
+- `callback: ((commitId: number, items: Map<Model<unknown>, Change>) => void) | undefined` - The callback function to set. It gets called after each successful
 `transact()` commit that has changes, with the following arguments:
 - A sequential number. Higher numbers have been committed after lower numbers.
 - A map of model instances to their changes. The change can be "created", "deleted", or an object containing the old values.

package/skill/transact.md

@@ -18,7 +18,7 @@ times.
 
 **Parameters:**
 
-- `fn: () => T` - - The function to execute within the transaction context. Receives a Transaction instance.
+- `fn: () => T` - The function to execute within the transaction context. Receives a Transaction instance.
 
 **Returns:** A promise that resolves with the function's return value.
 
@@ -32,7 +32,7 @@ times.
 
 ```typescript
 const paid = await E.transact(() => {
-  const user = User.pk.get("john_doe");
+  const user = User.get("john_doe");
   if (user.credits > 0) {
     user.credits--;
     return true;
@@ -43,7 +43,7 @@ const paid = await E.transact(() => {
 ```typescript
 // Transaction with automatic retry on conflicts
 await E.transact(() => {
-  const counter = Counter.pk.get("global") || new Counter({id: "global", value: 0});
+  const counter = Counter.get("global") || new Counter({id: "global", value: 0});
   counter.value++;
 });
 ```

package/src/datapack.ts

@@ -46,7 +46,7 @@ export default class DataPack {
 
     /**
      * Create a new DataPack instance.
-     * @param data - Optional initial data as Uint8Array or buffer size as number.
+     * @param data Optional initial data as Uint8Array or buffer size as number.
      */
     constructor(data: Uint8Array | number = 1900) {
         if (data instanceof Uint8Array) {
@@ -59,10 +59,10 @@ export default class DataPack {
 
     /**
      * Helper function to write a multi-byte integer with length prefix
-     * @param value - The value to write
-     * @param headerType - The type bits (0-7) for the header
-     * @param invertBytes - Whether to invert bytes (for negative numbers)
-     * @param invertByteCount - Whether to invert the byte count (for type 0)
+     * @param value The value to write
+     * @param headerType The type bits (0-7) for the header
+     * @param invertBytes Whether to invert bytes (for negative numbers)
+     * @param invertByteCount Whether to invert the byte count (for type 0)
      */
     private writeMultiByteNumber(value: number, headerType: number, invertBytes: boolean = false, invertByteCount: boolean = false): void {
         let byteCount = 0;
@@ -87,8 +87,8 @@ export default class DataPack {
 
     /**
      * Helper function to read a multi-byte integer with length prefix
-     * @param byteCount - Number of bytes to read
-     * @param invertBytes - Whether to invert bytes (for negative numbers)
+     * @param byteCount Number of bytes to read
+     * @param invertBytes Whether to invert bytes (for negative numbers)
      * @returns The read value
      */
     private readMultiByteNumber(byteCount: number, invertBytes: boolean = false): number {
@@ -187,7 +187,7 @@ export default class DataPack {
             this.ensureCapacity(data.length);
             this.buffer.set(data, this.writePos);
             this.writePos += data.length;
-        } else if (Array.isArray(data)) {
+        } else if (Array.isArray(data) || (typeof data.length === 'number' && typeof data[Symbol.iterator] === 'function')) {
             // Type 4, subtype 5: array start
             this.buffer[this.writePos++] = (4 << 5) | 5;
             for (const item of data) {
@@ -383,7 +383,7 @@ export default class DataPack {
 
     /**
      * Ensure the buffer has capacity for additional bytes.
-     * @param bytesNeeded - Number of additional bytes needed.
+     * @param bytesNeeded Number of additional bytes needed.
      */
     private ensureCapacity(bytesNeeded: number): void {
         const needed = this.writePos + bytesNeeded;
@@ -511,7 +511,7 @@ export default class DataPack {
     /**
      * Like writeString but writes without a length prefix and with a null terminator, for ordered storage.
      * Can be read with {@link read} or {@link readString} just like any other string.
-     * @param str - The string to write. May not contain null characters.
+     * @param str The string to write. May not contain null characters.
      */
     writeOrderedString(str: string): DataPack {
         const utf8Bytes = new TextEncoder().encode(str);

package/src/edinburgh.ts

@@ -1,19 +1,21 @@
 import * as lowlevel from "olmdb/lowlevel";
 import { init as olmdbInit, DatabaseError } from "olmdb/lowlevel";
-import { modelRegistry, txnStorage, currentTxn } from "./models.js";
-
-let initNeeded = true;
-export function scheduleInit() { initNeeded = true; }
+import { AsyncLocalStorage } from "node:async_hooks";
+import { pendingModelInits } from "./models.js";
 
 
 // Re-export public API from models
 export {
     Model,
-    registerModel,
+    type ModelClass,
+    type AnyModelClass,
+    type ModelBase,
+    defineModel,
+    deleteEverything,
     field,
 } from "./models.js";
 
-import type { Transaction, Change, Model } from "./models.js";
+import type { Change, Model } from "./models.js";
 
 // Re-export public API from types (only factory functions and instances)
 export {
@@ -37,20 +39,36 @@ export {
 
 // Re-export public API from indexes
 export {
-    index,
-    primary,
-    unique,
     dump,
 } from "./indexes.js";
 
-export { BaseIndex, UniqueIndex, PrimaryIndex, SecondaryIndex } from './indexes.js';
+export type { FindOptions, IndexRangeIterator } from './indexes.js';
 
 export { type Change } from './models.js';
-export type { Transaction } from './models.js';
+export type { FieldConfig } from './models.js';
+export { TypeWrapper } from './types.js';
 export { DatabaseError } from "olmdb/lowlevel";
 export { runMigration } from './migrate.js';
 export type { MigrationOptions, MigrationResult } from './migrate.js';
 
+export interface Transaction {
+    id: number;
+    instances: Map<number, Model<unknown>>; // pkHash => instance
+}
+
+export const txnStorage = new AsyncLocalStorage<Transaction>();
+
+/**
+ * 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;
+}
+
 let olmdbReady = false;
 let maxRetryCount = 6;
 
@@ -90,7 +108,7 @@ const STALE_INSTANCE_DESCRIPTOR = {
 * times.
 * 
 * @template T - The return type of the transaction function.
-* @param fn - The function to execute within the transaction context. Receives a Transaction instance.
+* @param fn The function to execute within the transaction context. Receives a Transaction instance.
 * @returns A promise that resolves with the function's return value.
 * @throws {DatabaseError} With code "RACING_TRANSACTION" if the transaction fails after retries due to conflicts.
 * @throws {DatabaseError} With code "TXN_LIMIT" if maximum number of transactions is reached.
@@ -99,7 +117,7 @@ const STALE_INSTANCE_DESCRIPTOR = {
 * @example
 * ```typescript
 * const paid = await E.transact(() => {
-*   const user = User.pk.get("john_doe");
+*   const user = User.get("john_doe");
 *   if (user.credits > 0) {
 *     user.credits--;
 *     return true;
@@ -110,24 +128,23 @@ const STALE_INSTANCE_DESCRIPTOR = {
 * ```typescript
 * // Transaction with automatic retry on conflicts
 * await E.transact(() => {
-*   const counter = Counter.pk.get("global") || new Counter({id: "global", value: 0});
+*   const counter = Counter.get("global") || new Counter({id: "global", value: 0});
 *   counter.value++;
 * });
 * ```
 */
 export async function transact<T>(fn: () => T): Promise<T> {
-    while (initNeeded || pendingInit) {
-        // Make sure only one async task is doing the inits, the rest should wait for it
+    while (pendingModelInits.size || pendingInit) {
         if (pendingInit) {
             await pendingInit;
         } else {
             pendingInit = (async () => {
                 if (!olmdbReady) olmdbInit('.edinburgh');
                 olmdbReady = true;
-                initNeeded = false;
-                for (const model of Object.values(modelRegistry)) {
-                    model.initFields();
-                    await model._loadCreateIndexes();
+                const models = [...pendingModelInits];
+                pendingModelInits.clear();
+                for (const model of models) {
+                    await model._initialize();
                 }
             })();
             await pendingInit;
@@ -138,7 +155,7 @@ export async function transact<T>(fn: () => T): Promise<T> {
     // try {
         for (let retryCount = 0; retryCount < maxRetryCount; retryCount++) {
             const txnId = lowlevel.startTransaction();
-            const txn: Transaction = { id: txnId, instances: new Set(), instancesByPk: new Map() };
+            const txn: Transaction = { id: txnId, instances: new Map() };
             const onSaveItems: Map<Model<unknown>, Change> | undefined = onSaveCallback ? new Map() : undefined;
 
             let result: T | undefined;
@@ -147,16 +164,16 @@ export async function transact<T>(fn: () => T): Promise<T> {
                     result = await fn();
 
                     // Call preCommit() on all instances before writing.
-                    // Note: Set iteration visits newly added items, so preCommit() creating
+                    // Note: Map iteration visits newly added items, so preCommit() creating
                     // new instances is handled correctly.
-                    for (const instance of txn.instances) {
-                        instance.preCommit?.();
+                    for (const instance of txn.instances.values()) {
+                        if (instance._oldValues !== false) instance.preCommit?.();
                     }
 
                     // Save all modified instances before committing
                     // This needs to happen inside txnStorage.run, because resolving default values
                     // for identifiers requires database access.
-                    for (const instance of txn.instances) {
+                    for (const instance of txn.instances.values()) {
                         const change = instance._write(txn);
                         if (onSaveItems && change) {
                             onSaveItems.set(instance, change);
@@ -168,14 +185,14 @@ export async function transact<T>(fn: () => T): Promise<T> {
                 throw e;
             } finally {
                 // Make the instances read-only to make it clear that their transaction has ended.
-                for (const instance of txn.instances) {
+                for (const instance of txn.instances.values()) {
                     delete instance._oldValues;
                     Object.defineProperty(instance, "_txn", STALE_INSTANCE_DESCRIPTOR);
                     Object.freeze(instance);
                 }
                 // Destroy the transaction object, to make sure things crash if they are used after
                 // this point, and to help the GC reclaim memory.
-                txn.id = txn.instances = txn.instancesByPk = undefined as any;
+                txn.id = txn.instances = undefined as any;
             }
 
             const commitResult = lowlevel.commitTransaction(txnId);
@@ -210,7 +227,7 @@ export function setMaxRetryCount(count: number) {
     maxRetryCount = count;
 }
 
-let onSaveCallback: ((commitId: number, items: Map<Model<any>, Change>) => void) | undefined;
+let onSaveCallback: ((commitId: number, items: Map<Model<unknown>, Change>) => void) | undefined;
  
 /**
  * Set a callback function to be called after a model is saved and committed.
@@ -220,35 +237,6 @@ let onSaveCallback: ((commitId: number, items: Map<Model<any>, Change>) => void)
  *   - A sequential number. Higher numbers have been committed after lower numbers.
  *   - A map of model instances to their changes. The change can be "created", "deleted", or an object containing the old values.
  */
-export function setOnSaveCallback(callback: ((commitId: number, items: Map<Model<any>, Change>) => void) | undefined) {
+export function setOnSaveCallback(callback: ((commitId: number, items: Map<Model<unknown>, Change>) => void) | undefined) {
     onSaveCallback = callback;
 }
-
-
-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);
-            }
-        });
-    }
-    // Re-init indexes since metadata was deleted
-    for (const model of Object.values(modelRegistry)) {
-        if (!model.fields) continue;
-        model.initFields(true);
-        await model._loadCreateIndexes();
-    }
-}