edinburgh 0.5.0 → 0.6.1

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

@@ -16,7 +16,8 @@ typed fields, primary key access, and optional secondary and unique indexes.
 
 **Parameters:**
 
-- `cls: T` - - A plain class whose properties use E.field().
-- `opts?: { pk?: PK, unique?: UNIQUE, index?: INDEX, tableName?: string, override?: boolean }` - - Registration options.
+- `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,15 +14,15 @@ 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
-const User = E.defineModel(class {
+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

@@ -10,19 +10,19 @@ Create a link type wrapper for model relationships.
 
 **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
-const Author = E.defineModel(class {
+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(class {
+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,14 @@
 
 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.
+
+The callback is called within a new transaction context, allowing lazy-loads to happen. However, any
+changes made to Edinburgh models will not be saved.

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.
 

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 {
@@ -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,20 +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,
+    type ModelClass,
+    type AnyModelClass,
+    type ModelBase,
     defineModel,
+    deleteEverything,
     field,
-    currentTxn,
 } 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 {
@@ -41,14 +42,33 @@ export {
     dump,
 } from "./indexes.js";
 
-export { BaseIndex, NonPrimaryIndex, UniqueIndex, 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;
 
@@ -88,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.
@@ -114,17 +134,17 @@ const STALE_INSTANCE_DESCRIPTOR = {
 * ```
 */
 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)) {
-                    await model._loadCreateIndexes();
+                const models = [...pendingModelInits];
+                pendingModelInits.clear();
+                for (const model of models) {
+                    await model._initialize();
                 }
             })();
             await pendingInit;
@@ -135,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;
@@ -144,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);
@@ -163,30 +183,36 @@ export async function transact<T>(fn: () => T): Promise<T> {
             } catch (e: any) {
                 try { lowlevel.abortTransaction(txnId); } catch {}
                 throw e;
-            } finally {
-                // Make the instances read-only to make it clear that their transaction has ended.
-                for (const instance of txn.instances) {
-                    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;
             }
 
-            const commitResult = lowlevel.commitTransaction(txnId);
-            const commitSeq = typeof commitResult === 'number' ? commitResult : await commitResult;
-
-            if (commitSeq > 0) {
-                // Success
-                if (onSaveItems?.size) {
+            if (onSaveItems?.size) {
+                // Perform writes, and start a new transaction at or past the point-in-time of our commit
+                const commitResult = lowlevel.commitTransaction(txnId, true);
+                if (typeof commitResult === 'object') {
+                    const commitSeq = await commitResult;
+                    if (commitSeq <= 0) continue; // Race condition - retry
+                    // Run the callback within our new transaction context, so it can fetch linked lazy fields if needed
                     onSaveCallback!(commitSeq, onSaveItems);
                 }
-                return result as T;
+                // else: only reads
+            }
+
+            // Make the instances read-only to make it clear that their transaction has ended.
+            for (const instance of txn.instances.values()) {
+                delete instance._oldValues;
+                Object.defineProperty(instance, "_txn", STALE_INSTANCE_DESCRIPTOR);
+                Object.freeze(instance);
             }
 
-            // Race condition - retry
+            // 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 = undefined as any;
+
+
+            // Commit the transaction and actually end it
+            if ((await lowlevel.commitTransaction(txnId)) <= 0) continue; // Race condition - retry
+
+            return result as T;
         }
         throw new DatabaseError("Transaction keeps getting raced", "RACING_TRANSACTION");
     // } catch (e: Error | any) {
@@ -207,7 +233,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.
@@ -216,36 +242,10 @@ let onSaveCallback: ((commitId: number, items: Map<Model<any>, Change>) => void)
  * `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.
+ * 
+ * The callback is called within a new transaction context, allowing lazy-loads to happen. However, any
+ * changes made to Edinburgh models will not be saved.
  */
-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._resetIndexes();
-        await model._loadCreateIndexes();
-    }
-}