edinburgh 0.5.0 → 0.6.1

package/README.md

@@ -22,7 +22,7 @@ import * as E from "edinburgh";
 // Initialize the database (optional, defaults to ".edinburgh")
 E.init("./my-database");
 
-const User = E.defineModel(class {
+const User = E.defineModel("User", class {
     id = E.field(E.identifier);
     name = E.field(E.string);
     age = E.field(E.number);
@@ -42,9 +42,8 @@ const User = E.defineModel(class {
 }, {
     pk: "id",
     unique: {
-        byEmail: "email",
+        email: "email",
     },
-    tableName: "User",
 });
 
 await E.transact(() => {
@@ -61,7 +60,7 @@ await E.transact(() => {
 
 await E.transact(() => {
     // Query by unique index
-    const john = User.byEmail.get("john@example.com")!;
+  const john = User.getBy("email", "john@example.com")!;
 
     // The transaction will retry if there's a conflict, such as another transaction
     // modifying the same user (from another async function or another process)
@@ -77,12 +76,15 @@ await E.transact(() => {
 
 ### Defining Models
 
-Models are plain, usually anonymous, classes passed to `E.defineModel()`:
+A model is defined using the `E.defineModel()` function by passing it..
+- a consistent table name,
+- an (anonymous) class containing `E.field` database properties and optionally regular properties/methods, and
+- optional key/index configuration.
 
 ```typescript
 import * as E from "edinburgh";
 
-const User = E.defineModel(class {
+const User = E.defineModel("User", class {
   id = E.field(E.identifier);
   name = E.field(E.string);
   email = E.field(E.string);
@@ -90,9 +92,12 @@ const User = E.defineModel(class {
 }, {
   pk: "id",
   unique: {
-    byEmail: "email",
+    email: "email",
   },
 });
+// Add this if you want to use User as a type annotation (e.g. `let u: User`).
+// Not needed just to call User.get(), User.find(), new User(), etc.
+type User = InstanceType<typeof User>;
 ```
 
 Instance fields are declared with `E.field(type, options?)`. Available types:
@@ -116,7 +121,7 @@ Instance fields are declared with `E.field(type, options?)`. Available types:
 #### Defaults
 
 ```typescript
-const Post = E.defineModel(class {
+const Post = E.defineModel("Post", class {
   id = E.field(E.identifier); // auto-generated
   title = E.field(E.string);
   status = E.field(E.or("draft", "published"), {default: "draft"});
@@ -141,13 +146,13 @@ await E.transact(() => {
 
 // Read + Update
 await E.transact(() => {
-  const user = User.byEmail.get("alice@example.com");
+  const user = User.getBy("email", "alice@example.com");
   if (user) user.age++;
 });
 
 // Return values from transactions
 const name = await E.transact(() => {
-  const user = User.byEmail.get("alice@example.com");
+  const user = User.getBy("email", "alice@example.com");
   return user?.name;
 });
 ```
@@ -159,15 +164,15 @@ Transactions auto-retry on conflict (up to 6 times by default). Keep transaction
 Edinburgh supports three index types:
 
 ```typescript
-const Product = E.defineModel(class {
+const Product = E.defineModel("Product", class {
   sku = E.field(E.string);
   name = E.field(E.string);
   category = E.field(E.string);
   price = E.field(E.number);
 }, {
   pk: "sku",
-  unique: { byName: "name" },
-  index: { byCategory: "category" },
+  unique: { name: "name" },
+  index: { category: "category" },
 });
 ```
 
@@ -181,7 +186,7 @@ await E.transact(() => {
   const p1 = Product.get("SKU-001");
 
   // Unique index lookup
-  const p2 = Product.byName.get("Widget");
+  const p2 = Product.getBy("name", "Widget");
 
   // All return undefined if not found
 });
@@ -189,12 +194,12 @@ await E.transact(() => {
 
 #### Range Queries
 
-All index types support `.find()` for range iteration:
+Primary-key queries use `.find()`. Named unique and secondary indexes use `.findBy(name, ...)`:
 
 ```typescript
 await E.transact(() => {
   // Exact match
-  for (const p of Product.byCategory.find({is: "electronics"})) {
+  for (const p of Product.findBy("category", {is: "electronics"})) {
     console.log(p.name);
   }
 
@@ -213,15 +218,15 @@ await E.transact(() => {
   for (const p of Product.find({reverse: true})) { ... }
 
   // Count and fetch helpers
-  const count = Product.byCategory.find({is: "electronics"}).count();
-  const first = Product.byCategory.find({is: "electronics"}).fetch(); // first match or undefined
+  const count = Product.findBy("category", {is: "electronics"}).count();
+  const first = Product.findBy("category", {is: "electronics"}).fetch(); // first match or undefined
 });
 ```
 
 #### Composite Primary Keys
 
 ```typescript
-const Event = E.defineModel(class {
+const Event = E.defineModel("Event", class {
   year = E.field(E.number);
   month = E.field(E.number);
   id = E.field(E.identifier);
@@ -244,7 +249,7 @@ await E.transact(() => {
 You can freely add regular methods, getters, and other non-persistent properties to model classes. These work normally in JavaScript but are **not stored in the database** and **not synchronized** across transactions or processes.
 
 ```typescript
-const User = E.defineModel(class {
+const User = E.defineModel("User", class {
   firstName = E.field(E.string);
   lastName = E.field(E.string);
 
@@ -267,7 +272,7 @@ const User = E.defineModel(class {
 Instead of naming fields, you can pass a function as an index specification. The function receives a model instance and returns an **array** of index key values. Each element creates a separate index entry, enabling multi-value indexes. Return `[]` to skip indexing for that instance (partial index).
 
 ```typescript
-const Article = E.defineModel(class {
+const Article = E.defineModel("Article", class {
   id = E.field(E.identifier);
   firstName = E.field(E.string);
   lastName = E.field(E.string);
@@ -276,11 +281,11 @@ const Article = E.defineModel(class {
 }, {
   pk: "id",
   unique: {
-    byFullName: (a: any) => [`${a.firstName} ${a.lastName}`], // computed covering unique index
+    fullName: (a: any) => [`${a.firstName} ${a.lastName}`], // computed covering unique index
   },
   index: {
-    byDomain: (a: any) => a.email ? [a.email.split("@")[1]] : [], // computed partial index
-    byWord: (a: any) => a.title.toLowerCase().split(" "), // computed multi-index
+    domain: (a: any) => a.email ? [a.email.split("@")[1]] : [], // computed partial index
+    word: (a: any) => a.title.toLowerCase().split(" "), // computed multi-index
   },
 });
 
@@ -288,13 +293,13 @@ await E.transact(() => {
   new Article({ firstName: "Jane", lastName: "Doe", title: "Hello World", email: "jane@acme.com" });
 
   // Lookup via computed unique index
-  const jane = Article.byFullName.get("Jane Doe");
+  const jane = Article.getBy("fullName", "Jane Doe");
 
   // Multi-value: each word in the title is indexed separately
-  for (const a of Article.byWord.find({is: "hello"})) { ... }
+  for (const a of Article.findBy("word", {is: "hello"})) { ... }
 
   // Partial index: articles without email are skipped
-  for (const a of Article.byDomain.find({is: "acme.com"})) { ... }
+  for (const a of Article.findBy("domain", {is: "acme.com"})) { ... }
 });
 ```
 
@@ -303,12 +308,12 @@ await E.transact(() => {
 Use `E.link(Model)` for foreign keys. Use a thunk (a function that just returns a value) for forward references when needed:
 
 ```typescript
-const Author = E.defineModel(class {
+const Author = E.defineModel("Author", class {
   id = E.field(E.identifier);
   name = E.field(E.string);
 }, { pk: "id" });
 
-const Book = E.defineModel(class {
+const Book = E.defineModel("Book", class {
   id = E.field(E.identifier);
   title = E.field(E.string);
   author = E.field(E.link(Author));
@@ -381,7 +386,7 @@ await Product.batchProcess({ limitRows: 1000 }, (product) => {
 When you change a model's schema, Edinburgh lazily migrates old records on access. You can provide a `static migrate(record)` function to transform old rows:
 
 ```typescript
-const UserV2 = E.defineModel(class {
+const UserV2 = E.defineModel("User", class {
   id = E.field(E.identifier);
   name = E.field(E.string);
   role = E.field(E.string);  // newly added field
@@ -389,7 +394,7 @@ const UserV2 = E.defineModel(class {
   static migrate(record: Record<string, any>) {
     record.role ??= record.name.indexOf("admin") >= 0 ? "admin" : "user"; // set role based on name for old records
   }
-}
+})
 ```
 
 Edinburgh will lazily (re)run the `migrate` function on an instance whenever its implementation (the literal function code) has changed. For robustness, make sure that your `migrate` function...
@@ -424,7 +429,7 @@ console.log(result.secondaries);  // { User: 1500 }
 Compute derived fields before data is written:
 
 ```typescript
-const Article = E.defineModel(class {
+const Article = E.defineModel("Article", class {
   id = E.field(E.identifier);
   title = E.field(E.string);
   slug = E.field(E.string);
@@ -432,7 +437,7 @@ const Article = E.defineModel(class {
   preCommit() {
     this.slug = this.title.toLowerCase().replace(/\s+/g, "-");
   }
-}, { pk: "id" });
+});
 ```
 
 ### Change Tracking
@@ -473,11 +478,14 @@ ln -s ../../node_modules/edinburgh/skill .claude/skills/edinburgh
 
 The following is auto-generated from `src/edinburgh.ts`:
 
-### scheduleInit · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L6)
+### currentTxn · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L66)
 
-**Signature:** `() => void`
+Returns the current transaction from AsyncLocalStorage.
+Throws if called outside a transact() callback.
+
+**Signature:** `() => Transaction`
 
-### init · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L65)
+### init · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L85)
 
 Initialize the database with the specified directory path.
 This function may be called multiple times with the same parameters. If it is not called before the first transact(),
@@ -495,7 +503,7 @@ the database will be automatically initialized with the default directory.
 init("./my-database");
 ```
 
-### transact · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L116)
+### transact · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L136)
 
 Executes a function within a database transaction context.
 
@@ -515,7 +523,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.
 
@@ -545,7 +553,7 @@ await E.transact(() => {
 });
 ```
 
-### setMaxRetryCount · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L206)
+### setMaxRetryCount · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L232)
 
 Set the maximum number of retries for a transaction in case of conflicts.
 The default value is 6. Setting it to 0 will disable retries and cause transactions to fail immediately on conflict.
@@ -556,146 +564,124 @@ The default value is 6. Setting it to 0 will disable retries and cause transacti
 
 - `count: number` - The maximum number of retries for a transaction.
 
-### setOnSaveCallback · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L220)
+### setOnSaveCallback · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L249)
 
 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.
 
-### deleteEverything · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L225)
+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.
 
-**Signature:** `() => Promise<void>`
-
-### Model · [abstract class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+### Model · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
-[object Object],[object Object],[object Object],[object Object],[object Object]
+**Type:** `typeof ModelBase`
 
-**Type Parameters:**
+### ModelClass · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
-- `SUB` - The concrete model subclass (for proper typing).
+Runtime base constructor for model classes returned by `defineModel()`.
 
-**Examples:**
-
-```typescript
-const User = E.defineModel(class {
-  id = E.field(E.identifier);
-  name = E.field(E.string);
-  email = E.field(E.string);
-}, {
-  pk: "id",
-  unique: { byEmail: "email" },
-});
-```
+Prefer the `ModelClass` type alias for annotations and the result of
+`defineModel()` for concrete model classes.
 
-#### Model.tableName · [static property](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+**Type:** `typeof ModelClassRuntime`
 
-The database table name (defaults to class name).
+### AnyModelClass · [type](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L111)
 
-**Type:** `string`
+A model constructor with its generic information erased.
 
-#### Model.override · [static property](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+Useful when accepting or storing arbitrary registered model classes.
 
-When true, defineModel replaces an existing model with the same tableName.
+**Type:** `ModelClass<new () => any, readonly any[], any, any>`
 
-**Type:** `boolean`
+### ModelBase · [abstract class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
-#### Model.fields · [static property](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+Base class for all database models in the Edinburgh ORM.
 
-Field configuration metadata.
+Models represent database entities with typed fields, automatic serialization,
+change tracking, and relationship management. Model classes are created using
+`E.defineModel()`.
 
-**Type:** `Record<string | number | symbol, FieldConfig<unknown>>`
+### Schema Evolution
 
-#### Model.migrate · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+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.
 
-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.
+**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.
 
-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.
+**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
 
-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).
+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).
 
-**Signature:** `(record: Record<string, any>) => void`
+### Lifecycle Hooks
 
-**Parameters:**
+- **`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.
 
-- `record: Record<string, any>` - - A plain object with all field values from the old schema version.
+- **`preCommit()`**: Called on each modified instance right before the transaction commits.
+  Useful for computing derived fields, enforcing cross-field invariants, or creating related
+  instances.
 
 **Examples:**
 
 ```typescript
-const User = E.defineModel(class {
+const User = E.defineModel("User", class {
   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
-  }
-}, { pk: "id" });
+  email = E.field(E.string);
+}, {
+  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>;
 ```
 
-#### Model.get · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
-
-**Signature:** `(...args: any[]) => any`
-
-**Parameters:**
-
-- `args: any[]`
-
-#### Model.getLazy · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
-
-**Signature:** `(...args: any[]) => any`
-
-**Parameters:**
-
-- `args: any[]`
-
-#### Model.find · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
-
-**Signature:** `(opts?: any) => any`
+#### ModelBase.migrate · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
-**Parameters:**
-
-- `opts?: any`
-
-#### Model.batchProcess · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+Optional migration function called when deserializing rows written with an older schema version.
+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()`.
 
-**Signature:** `(opts: any, callback?: any) => any`
+**Signature:** `(record: Record<string, any>) => void`
 
 **Parameters:**
 
-- `opts: any`
-- `callback?: any`
-
-#### Model.replaceInto · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
-
-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.
+- `record: Record<string, any>` - A plain object containing the row's field values from the older schema version.
 
-**Signature:** `<T extends typeof Model<any>>(this: T, obj: Partial<Record<string, any>>) => InstanceType<T>`
-
-**Parameters:**
+**Examples:**
 
-- `this: T`
-- `obj: Partial<Record<string, any>>` - - Partial model data that **must** include every primary key field.
+```typescript
+const User = E.defineModel("User", class {
+  id = E.field(E.identifier);
+  name = E.field(E.string);
+  role = E.field(E.string);
 
-**Returns:** The loaded-and-updated or newly created instance.
+  static migrate(record: Record<string, any>) {
+    record.role ??= "user";
+  }
+}, { pk: "id" });
+```
 
-#### model.preCommit · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+#### modelBase.preCommit · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 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.
@@ -711,7 +697,7 @@ Common use cases:
 **Examples:**
 
 ```typescript
-const Post = E.defineModel(class {
+const Post = E.defineModel("Post", class {
   id = E.field(E.identifier);
   title = E.field(E.string);
   slug = E.field(E.string);
@@ -722,19 +708,19 @@ const Post = E.defineModel(class {
 }, { pk: "id" });
 ```
 
-#### model.getPrimaryKey · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+#### modelBase.getPrimaryKey · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 **Signature:** `() => Uint8Array<ArrayBufferLike>`
 
 **Returns:** The primary key for this instance.
 
-#### model.getPrimaryKeyHash · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+#### modelBase.getPrimaryKeyHash · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 **Signature:** `() => number`
 
 **Returns:** A 53-bit positive integer non-cryptographic hash of the primary key, or undefined if not yet saved.
 
-#### model.isLazyField · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+#### modelBase.isLazyField · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 **Signature:** `(field: keyof this) => boolean`
 
@@ -742,7 +728,7 @@ const Post = E.defineModel(class {
 
 - `field: keyof this`
 
-#### model.preventPersist · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+#### modelBase.preventPersist · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Prevent this instance from being persisted to the database.
 
@@ -758,7 +744,7 @@ user.name = "New Name";
 user.preventPersist(); // Changes won't be saved
 ```
 
-#### model.delete · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+#### modelBase.delete · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Delete this model instance from the database.
 
@@ -773,7 +759,7 @@ const user = User.get("user123");
 user.delete(); // Removes from database
 ```
 
-#### model.validate · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+#### modelBase.validate · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Validate all fields in this model instance.
 
@@ -781,7 +767,7 @@ Validate all fields in this model instance.
 
 **Parameters:**
 
-- `raise: boolean` (optional) - - If true, throw on first validation error.
+- `raise: boolean` (optional) - If true, throw on first validation error.
 
 **Returns:** Array of validation errors (empty if valid).
 
@@ -795,7 +781,7 @@ if (errors.length > 0) {
 }
 ```
 
-#### model.isValid · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+#### modelBase.isValid · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Check if this model instance is valid.
 
@@ -810,19 +796,19 @@ const user = new User({name: "John"});
 if (!user.isValid()) shoutAtTheUser();
 ```
 
-#### model.getState · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+#### modelBase.getState · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 **Signature:** `() => "created" | "deleted" | "loaded" | "lazy"`
 
-#### model.toString · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+#### modelBase.toString · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 **Signature:** `() => string`
 
-#### model.[Symbol.for('nodejs.util.inspect.custom')] · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+#### modelBase.[Symbol.for('nodejs.util.inspect.custom')] · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 **Signature:** `() => string`
 
-### defineModel · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L164)
+### defineModel · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Register a model class with the Edinburgh ORM system.
 
@@ -840,12 +826,22 @@ 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.
 
-### field · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L87)
+### deleteEverything · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+
+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>`
+
+### field · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L76)
 
 Create a field definition for a model property.
 
@@ -861,27 +857,20 @@ 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});
 });
 ```
 
-### currentTxn · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L21)
-
-Returns the current transaction from AsyncLocalStorage.
-Throws if called outside a transact() callback.
-
-**Signature:** `() => Transaction`
-
 ### string · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Type wrapper instance for the string type.
@@ -940,7 +929,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.
 
@@ -963,7 +952,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.
 
@@ -986,8 +975,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.
 
@@ -1010,8 +999,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.
 
@@ -1034,7 +1023,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.
 
@@ -1056,7 +1045,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.
 
@@ -1079,19 +1068,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" });
@@ -1099,135 +1088,195 @@ const Book = E.defineModel(class {
 
 ### dump · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
-Dump database contents for debugging.
+**Signature:** `() => void`
+
+### FindOptions · [type](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L115)
+
+Range-query options accepted by `find()`, `findBy()`, `batchProcess()`, and `batchProcessBy()`.
+
+Supports exact-match lookups via `is`, inclusive bounds via `from` / `to`,
+exclusive bounds via `after` / `before`, and reverse scans.
+
+For single-field indexes, values can be passed directly. For composite indexes,
+pass tuples or partial tuples for prefix matching.
+
+**Type:** `(
+    (
+        {is: ArrayOrOnlyItem<ARG_TYPES>;} // Shortcut for setting `from` and `to` to the same value
+    |
+        (
+            (
+                {from: ArrayOrOnlyItem<ARG_TYPES>;}
+            |
+                {after: ArrayOrOnlyItem<ARG_TYPES>;}
+            |
+                {}
+            )
+        &
+            (
+                {to: ArrayOrOnlyItem<ARG_TYPES>;}
+            |
+                {before: ArrayOrOnlyItem<ARG_TYPES>;}
+            |
+                {}
+            )
+        )
+    ) &
+    {
+        reverse?: boolean;
+    }
+    & (FETCH extends undefined ? { fetch?: undefined } : { fetch: FETCH })
+)`
+
+### IndexRangeIterator · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L73)
+
+Iterator for range queries on indexes.
+Handles common iteration logic for both primary and unique indexes.
+Extends built-in Iterator to provide map/filter/reduce/toArray/etc.
+
+**Type Parameters:**
 
-Prints all indexes and their data to the console for inspection.
-This is primarily useful for development and debugging purposes.
+- `ITEM`
 
-**Signature:** `() => void`
+#### indexRangeIterator.[Symbol.iterator] · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L78)
+
+**Signature:** `() => this`
+
+#### indexRangeIterator.next · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L80)
+
+**Signature:** `() => IteratorResult<ITEM, any>`
 
-### BaseIndex · [abstract class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L130)
+#### indexRangeIterator.count · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L102)
+
+**Signature:** `() => number`
+
+#### indexRangeIterator.fetch · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L105)
+
+**Signature:** `() => ITEM`
+
+### Change · [type](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L85)
+
+**Type:** `Record<any, any> | "created" | "deleted"`
 
-Base class for database indexes for efficient lookups on model fields.
+### FieldConfig · [interface](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L37)
 
-Indexes enable fast queries on specific field combinations and enforce uniqueness constraints.
+Configuration interface for model fields.
 
 **Type Parameters:**
 
-- `M extends typeof Model` - The model class this index belongs to.
-- `F extends readonly (keyof InstanceType<M> & string)[]` - The field names that make up this index.
-- `ARGS extends readonly any[] = IndexArgTypes<M, F>`
+- `T` - The field type.
 
-**Constructor Parameters:**
+#### fieldConfig.type · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L45)
 
-- `MyModel`: - The model class this index belongs to.
-- `_fieldNames`: - Array of field names that make up this index.
+The type wrapper that defines how this field is serialized/validated.
 
-#### baseIndex.find · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+**Type:** `TypeWrapper<T>`
 
-**Signature:** `{ (opts?: FindOptions<ARGS, "first">): InstanceType<M>; (opts: FindOptions<ARGS, "single">): InstanceType<M>; (opts?: FindOptions<...>): IndexRangeIterator<...>; }`
+#### fieldConfig.description · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L47)
 
-**Parameters:**
+Optional human-readable description of the field.
 
-- `opts?: FindOptions<ARGS, 'first'>`
+**Type:** `string`
 
-#### baseIndex.find · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+#### fieldConfig.default · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L49)
 
-**Signature:** `{ (opts?: FindOptions<ARGS, "first">): InstanceType<M>; (opts: FindOptions<ARGS, "single">): InstanceType<M>; (opts?: FindOptions<...>): IndexRangeIterator<...>; }`
+Optional default value or function that generates default values.
 
-**Parameters:**
+**Type:** `T | ((model: Record<string, any>) => T)`
 
-- `opts: FindOptions<ARGS, 'single'>`
+### TypeWrapper · [abstract class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L33)
 
-#### baseIndex.find · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+**Type Parameters:**
 
-**Signature:** `{ (opts?: FindOptions<ARGS, "first">): InstanceType<M>; (opts: FindOptions<ARGS, "single">): InstanceType<M>; (opts?: FindOptions<...>): IndexRangeIterator<...>; }`
+- `T` - The TypeScript type this wrapper represents.
 
-**Parameters:**
+#### typeWrapper.kind · [abstract property](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L47)
 
-- `opts?: FindOptions<ARGS>`
+A string identifier for this type, used during serialization
+
+**Type:** `string`
 
-#### baseIndex.find · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+#### typeWrapper.serialize · [abstract method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L52)
 
-**Signature:** `{ (opts?: FindOptions<ARGS, "first">): InstanceType<M>; (opts: FindOptions<ARGS, "single">): InstanceType<M>; (opts?: FindOptions<...>): IndexRangeIterator<...>; }`
+Serialize a value from an object property to a Pack.
+
+**Signature:** `(value: T, pack: DataPack) => void`
 
 **Parameters:**
 
-- `opts: any` (optional)
+- `value: T` - The value to serialize.
+- `pack: DataPack` - The Pack instance to write to.
 
-#### baseIndex.batchProcess · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+#### typeWrapper.deserialize · [abstract method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L59)
 
-[object Object],[object Object],[object Object]
+Deserialize a value from a Pack into an object property.
 
-**Signature:** `(opts: FindOptions<ARGS, undefined> & { limitSeconds?: number; limitRows?: number; }, callback: (row: InstanceType<M>) => void | Promise<void>) => Promise<...>`
+**Signature:** `(pack: DataPack) => T`
 
 **Parameters:**
 
-- `opts: FindOptions<ARGS> & { limitSeconds?: number; limitRows?: number }` (optional) - - Query options (same as `find()`), plus:
-- `callback: (row: InstanceType<M>) => void | Promise<void>` - - Called for each matching row within a transaction
+- `pack: DataPack` - The Pack instance to read from.
 
-#### baseIndex.toString · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+#### typeWrapper.getError · [abstract method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L64)
 
-**Signature:** `() => string`
+Validate a value.
 
-### NonPrimaryIndex · [abstract class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+**Signature:** `(value: T) => void | DatabaseError`
 
-Abstract base for all non-primary indexes (unique and secondary).
-Provides shared key serialization, write/delete/update logic.
+**Parameters:**
 
-**Type Parameters:**
+- `value: T` - The value to validate.
 
-- `M extends typeof Model`
-- `F extends readonly (keyof InstanceType<M> & string)[]`
-- `ARGS extends readonly any[] = IndexArgTypes<M, F>`
+**Returns:** - A DatabaseError if validation fails.
 
-### UniqueIndex · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+#### typeWrapper.serializeType · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L68)
 
-Unique index that stores references to the primary key.
+Serialize type metadata to a Pack (for schema serialization).
 
-**Type Parameters:**
+**Signature:** `(pack: DataPack) => void`
+
+**Parameters:**
 
-- `M extends typeof Model`
-- `F extends readonly (keyof InstanceType<M> & string)[]`
-- `ARGS extends readonly any[] = IndexArgTypes<M, F>`
+- `pack: DataPack` - The Pack instance to write to.
 
-#### uniqueIndex.get · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+#### typeWrapper.containsNull · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L77)
 
-**Signature:** `(...args: ARGS) => InstanceType<M>`
+Check if indexing should be skipped for this field value.
+
+**Signature:** `(value: T) => boolean`
 
 **Parameters:**
 
-- `args: ARGS`
+- `value: T`
 
-### SecondaryIndex · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
+**Returns:** true if indexing should be skipped.
 
-Secondary index for non-unique lookups.
+#### typeWrapper.toString · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L78)
 
-**Type Parameters:**
+**Signature:** `() => string`
 
-- `M extends typeof Model`
-- `F extends readonly (keyof InstanceType<M> & string)[]`
-- `ARGS extends readonly any[] = IndexArgTypes<M, F>`
+#### typeWrapper.clone · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L81)
 
-### Change · [type](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L94)
+**Signature:** `(value: T) => T`
 
-**Type:** `Record<any, any> | "created" | "deleted"`
+**Parameters:**
 
-### Transaction · [interface](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L39)
+- `value: T`
 
-#### transaction.id · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L41)
+#### typeWrapper.equals · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L85)
 
-**Type:** `number`
+**Signature:** `(value1: T, value2: T) => boolean`
 
-#### transaction.instances · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L42)
+**Parameters:**
 
-**Type:** `Set<Model<unknown>>`
+- `value1: T`
+- `value2: T`
 
-#### transaction.instancesByPk · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L44)
+#### typeWrapper.getLinkedModel · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L90)
 
-**Type:** `Map<number, Model<unknown>>`
+**Signature:** `() => AnyModelClass`
 
-### DatabaseError · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L156)
+### DatabaseError · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L174)
 
 The DatabaseError class is used to represent errors that occur during database operations.
 It extends the built-in Error class and has a machine readable error code string property.
@@ -1237,7 +1286,7 @@ Invalid function arguments will throw TypeError.
 
 **Value:** `DatabaseErrorConstructor`
 
-### runMigration · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L122)
+### runMigration · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L121)
 
 Run database migration: populate secondary indexes for old-version rows,
 convert old primary indices, rewrite row data, and clean up orphaned indices.
@@ -1250,13 +1299,13 @@ convert old primary indices, rewrite row data, and clean up orphaned indices.
 
 ### MigrationOptions · [interface](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L13)
 
-#### migrationOptions.tables · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L17)
+#### migrationOptions.tables · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L18)
 
 Limit migration to specific table names.
 
 **Type:** `string[]`
 
-#### migrationOptions.populateSecondaries · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L21)
+#### migrationOptions.populateSecondaries · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L22)
 
 Populate secondary indexes for rows at old schema versions (default: true).
 
@@ -1268,27 +1317,27 @@ Convert old primary indices when primary key fields changed (default: true).
 
 **Type:** `boolean`
 
-#### migrationOptions.rewriteData · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L37)
+#### migrationOptions.rewriteData · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L38)
 
 Rewrite all row data to the latest schema version (default: false).
 
 **Type:** `boolean`
 
-#### migrationOptions.removeOrphans · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L44)
+#### migrationOptions.removeOrphans · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L45)
 
 Delete orphaned secondary/unique index entries (default: true).
 
 **Type:** `boolean`
 
-#### migrationOptions.onProgress · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L44)
+#### migrationOptions.onProgress · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L45)
 
 Progress callback.
 
 **Type:** `(info: ProgressInfo) => void`
 
-### MigrationResult · [interface](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L49)
+### MigrationResult · [interface](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L50)
 
-#### migrationResult.secondaries · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L50)
+#### migrationResult.secondaries · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L52)
 
 Per-table counts of secondary index entries populated.
 
@@ -1300,21 +1349,35 @@ Per-table counts of old primary rows migrated.
 
 **Type:** `Record<string, number>`
 
-#### migrationResult.conversionFailures · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L57)
+#### migrationResult.conversionFailures · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L59)
 
 Per-table conversion failure counts by reason.
 
 **Type:** `Record<string, Record<string, number>>`
 
-#### migrationResult.rewritten · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L60)
+#### migrationResult.rewritten · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L63)
 
 Per-table counts of rows rewritten to latest version.
 
 **Type:** `Record<string, number>`
 
-#### migrationResult.orphans · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L65)
+#### migrationResult.orphans · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L67)
 
 Number of orphaned index entries deleted.
 
 **Type:** `number`
 
+### Transaction · [interface](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L54)
+
+#### transaction.id · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L55)
+
+**Type:** `number`
+
+#### transaction.instances · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L56)
+
+**Type:** `Map<number, ModelBase>`
+
+### txnStorage · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L59)
+
+**Value:** `AsyncLocalStorage<Transaction>`
+