edinburgh 0.4.6 → 0.6.0

package/README.md

@@ -22,85 +22,82 @@ import * as E from "edinburgh";
 // Initialize the database (optional, defaults to ".edinburgh")
 E.init("./my-database");
 
-// Define a model
-@E.registerModel
-class User extends E.Model<User> {
-    // Define a primary key (optional, defaults to using the "id" field)
-    static pk = E.primary(User, "id");
-    // Define a unique index on the email field
-    static byEmail = E.unique(User, "email");
-
-    // Define fields with simple types -- they will be type-checked at compile time and validated at runtime.
+const User = E.defineModel("User", class {
     id = E.field(E.identifier);
     name = E.field(E.string);
     age = E.field(E.number);
-    email = E.field(E.opt(E.string)); // TypeScript: undefined | string
-
-    // Link to another instance of this model
-    supervisor = E.field(E.opt(E.link(User)));
-
-    // A field with a more elaborate type. In TypeScript: `User | User[] | "unknown" | "whatever"`
-    something = E.field(E.or(E.link(User), E.array(E.link(User)), E.literal("unknown"), E.literal("whatever")), { default: "unknown" });
-}
+    email = E.field(E.opt(E.string));
+    // Optional link to another instance of this model (needs a function as `User` is not defined yet at this point)
+    supervisor = E.field(E.opt(E.link(() => User)));
+    // A field with a more elaborate type. In TypeScript: `User | User[] | "unknown" | "whatever"`, defaulting to "unknown".
+    something = E.field(
+        E.or(
+            E.link(() => User),
+            E.array(E.link(() => User)),
+            E.literal("unknown"),
+            E.literal("whatever")
+        ),
+        { default: "unknown" }
+    );
+}, {
+    pk: "id",
+    unique: {
+        email: "email",
+    },
+});
 
-// Use in transactions
 await E.transact(() => {
-    const boss = new User({
-        name: "Big Boss",
-        age: 50,
-    });
-    const john = new User({ // Unique 'id' is automatically generated if not provided
-        name: "John Doe", 
+    // Unique 'id' values are auto-generated if not provided
+    const boss = new User({ name: "Big Boss", age: 50 });
+    new User({
+        name: "John Doe",
         age: 41,
         email: "john@example.com",
         supervisor: boss, // Link to another model instance
     });
+    // Newly instantiated models are automatically saved to the database on transaction commit
 });
 
 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)
     john.age++;
 
     // The supervisor object is lazy loaded on first access
-    console.log(`${john.supervisor!.name} is ${john.name}'s supervisor`);  
+    console.log(`${john.supervisor!.name} is ${john.name}'s supervisor`);
 });    
 ```
 
 ## Tutorial
 
-### TypeScript Configuration
-
-When using TypeScript to transpile to JavaScript, make sure to enable the following options in your `tsconfig.json`:
-
-```json
-{
-    "compilerOptions": {
-        "target": "es2022",
-        "experimentalDecorators": true
-    }
-}
-```
 
 ### Defining Models
 
-Models are classes that extend `E.Model<Self>` and use the `@E.registerModel` decorator:
+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";
 
-@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);
   age = E.field(E.number);
-}
+}, {
+  pk: "id",
+  unique: {
+    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:
@@ -124,16 +121,13 @@ Instance fields are declared with `E.field(type, options?)`. Available types:
 #### Defaults
 
 ```typescript
-@E.registerModel
-class Post extends E.Model<Post> {
-  static pk = E.primary(Post, "id");
-
-  id = E.field(E.identifier);  // auto-generated
+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"});
-  tags = E.field(E.array(E.string), {default: () => []});  // use function for mutable defaults
-  createdAt = E.field(E.dateTime);  // dateTime defaults to new Date()
-}
+  tags = E.field(E.array(E.string), {default: () => []}); // use function for mutable defaults
+  createdAt = E.field(E.dateTime); // dateTime defaults to new Date()
+}, { pk: "id" });
 ```
 
 ### Transactions
@@ -146,19 +140,19 @@ E.init("./my-database");
 
 // Create
 await E.transact(() => {
-  const user = new User({name: "Alice", email: "alice@example.com", age: 30});
-  // user.id is auto-generated
+  // User.id is auto-generated
+  new User({name: "Alice", email: "alice@example.com", age: 30});
 });
 
 // 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;
 });
 ```
@@ -170,30 +164,29 @@ Transactions auto-retry on conflict (up to 6 times by default). Keep transaction
 Edinburgh supports three index types:
 
 ```typescript
-@E.registerModel
-class Product extends E.Model<Product> {
-  static pk = E.primary(Product, "sku");           // primary: one per model, stores data
-  static byName = E.unique(Product, "name");       // unique: enforces uniqueness + fast lookup
-  static byCategory = E.index(Product, "category");// secondary: non-unique, for queries
-
+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: { name: "name" },
+  index: { category: "category" },
+});
 ```
 
-If no `E.primary()` is declared, Edinburgh auto-creates one on an `id` field (adding `E.identifier` if missing).
+If no `pk` is provided, Edinburgh auto-creates one on an `id` field, adding it as an `E.identifier` field if needed.
 
 #### Lookups
 
 ```typescript
 await E.transact(() => {
   // Primary key lookup
-  const p = Product.pk.get("SKU-001");
+  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
 });
@@ -201,54 +194,53 @@ 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);
   }
 
   // Range (inclusive)
-  for (const p of Product.pk.find({from: "A", to: "M"})) {
+  for (const p of Product.find({from: "A", to: "M"})) {
     console.log(p.sku);
   }
 
   // Exclusive bounds
-  for (const p of Product.pk.find({after: "A", before: "M"})) { ... }
+  for (const p of Product.find({after: "A", before: "M"})) { ... }
 
   // Open-ended
-  for (const p of Product.pk.find({from: "M"})) { ... }
+  for (const p of Product.find({from: "M"})) { ... }
 
   // Reverse
-  for (const p of Product.pk.find({reverse: true})) { ... }
+  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 Indexes
+#### Composite Primary Keys
 
 ```typescript
-@E.registerModel
-class Event extends E.Model<Event> {
-  static pk = E.primary(Event, ["year", "month", "id"]);
-
+const Event = E.defineModel("Event", class {
   year = E.field(E.number);
   month = E.field(E.number);
   id = E.field(E.identifier);
   title = E.field(E.string);
-}
+}, {
+  pk: ["year", "month", "id"] as const,
+});
 
 await E.transact(() => {
   // Prefix matching — find all events in 2025
-  for (const e of Event.pk.find({is: [2025]})) { ... }
+  for (const e of Event.find({is: [2025]})) { ... }
 
   // Find events in March 2025
-  for (const e of Event.pk.find({is: [2025, 3]})) { ... }
+  for (const e of Event.find({is: [2025, 3]})) { ... }
 });
 ```
 
@@ -257,10 +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
-@E.registerModel
-class User extends E.Model<User> {
-  static pk = E.primary(User, "id");
-  id = E.field(E.identifier);
+const User = E.defineModel("User", class {
   firstName = E.field(E.string);
   lastName = E.field(E.string);
 
@@ -275,70 +264,68 @@ class User extends E.Model<User> {
   greet(): string {
     return `Hello, ${this.fullName}!`;
   }
-}
+});
 ```
 
 #### Computed Indexes
 
-Instead of naming fields, you can pass a **function** to `E.unique()` or `E.index()`. 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).
+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
-@E.registerModel
-class Article extends E.Model<Article> {
-  static pk = E.primary(Article, "id");
-  static byFullName = E.unique(Article, (a: Article) => [`${a.firstName} ${a.lastName}`]);
-  static byWord = E.index(Article, (a: Article) => a.title.toLowerCase().split(" "));
-  static byDomain = E.index(Article, (a: Article) => a.email ? [a.email.split("@")[1]] : []);
-
+const Article = E.defineModel("Article", class {
   id = E.field(E.identifier);
   firstName = E.field(E.string);
   lastName = E.field(E.string);
   title = E.field(E.string);
   email = E.field(E.opt(E.string));
-}
+}, {
+  pk: "id",
+  unique: {
+    fullName: (a: any) => [`${a.firstName} ${a.lastName}`], // computed covering unique index
+  },
+  index: {
+    domain: (a: any) => a.email ? [a.email.split("@")[1]] : [], // computed partial index
+    word: (a: any) => a.title.toLowerCase().split(" "), // computed multi-index
+  },
+});
 
 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"})) { ... }
 });
 ```
 
-Computed indexes also support `find()` range queries and `batchProcess()`, just like field-based indexes.
-
-### Relationships (Links)
+### Relationships
 
-Use `E.link(Model)` for foreign keys:
+Use `E.link(Model)` for foreign keys. Use a thunk (a function that just returns a value) for forward references when needed:
 
 ```typescript
-@E.registerModel
-class Author extends E.Model<Author> {
-  static pk = E.primary(Author, "id");
+const Author = E.defineModel("Author", class {
   id = E.field(E.identifier);
   name = E.field(E.string);
-}
+}, { pk: "id" });
 
-@E.registerModel
-class Book extends E.Model<Book> {
-  static pk = E.primary(Book, "id");
+const Book = E.defineModel("Book", class {
   id = E.field(E.identifier);
   title = E.field(E.string);
   author = E.field(E.link(Author));
-}
+}, { pk: "id" });
 
 await E.transact(() => {
   const author = new Author({name: "Tolkien"});
   const book = new Book({title: "The Hobbit", author});
 
   // Later: linked models are lazy-loaded on property access
-  const b = Book.pk.get(book.id)!;
+  const b = Book.get(book.id)!;
+  console.log(b.author.id);    // no need to load yet..
   console.log(b.author.name);  // loads Author automatically (~1µs)
 });
 ```
@@ -347,7 +334,7 @@ await E.transact(() => {
 
 ```typescript
 await E.transact(() => {
-  const user = User.pk.get(someId);
+  const user = User.get(someId);
   if (user) user.delete();
 });
 ```
@@ -365,10 +352,16 @@ await E.transact(() => {
   user.preventPersist(); // exclude from commit
 });
 
-// findAll iterates all instances
+// find() iterates all instances (or use range options)
 await E.transact(() => {
-  for (const user of User.findAll()) { ... }
-  for (const user of User.findAll({reverse: true})) { ... }
+  for (const user of User.find()) { ... }
+  for (const user of User.find({reverse: true})) { ... }
+
+  // {fetch: 'first'} returns a single instance or undefined
+  const first = User.find({fetch: 'first'});
+
+  // {fetch: 'single'} returns a single instance, or throws if there are none or more than one
+  const only = User.find({fetch: 'single'});
 });
 
 // replaceInto: upsert by primary key
@@ -382,7 +375,7 @@ await E.transact(() => {
 For large datasets, `batchProcess` auto-commits in batches:
 
 ```typescript
-await Product.byCategory.batchProcess({is: "old"}, (product) => {
+await Product.batchProcess({ limitRows: 1000 }, (product) => {
   product.category = "archived";
 });
 // Commits every ~1 second or 4096 rows (configurable via limitSeconds, limitRows)
@@ -390,12 +383,10 @@ await Product.byCategory.batchProcess({is: "old"}, (product) => {
 
 ### Lazy Schema Migrations
 
-When you change a model's schema, Edinburgh will lazily try to migrate old records on access. This allows you to deploy code changes without downtime or a separate migration step. Optionally, you may provide a `static migrate(record: Record<string, any>)` function on the model to transform old records during lazy migration. If there is a migration error (like a new field without a default value, or an incompatible type change), a run-time error is thrown when loading the affected model instance.
+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
-@E.registerModel
-class User extends E.Model<User> {
-  static pk = E.primary(User, "id");
+const UserV2 = E.defineModel("User", class {
   id = E.field(E.identifier);
   name = E.field(E.string);
   role = E.field(E.string);  // newly added field
@@ -403,7 +394,7 @@ class User extends E.Model<User> {
   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...
@@ -438,9 +429,7 @@ console.log(result.secondaries);  // { User: 1500 }
 Compute derived fields before data is written:
 
 ```typescript
-@E.registerModel
-class Article extends E.Model<Article> {
-  static pk = E.primary(Article, "id");
+const Article = E.defineModel("Article", class {
   id = E.field(E.identifier);
   title = E.field(E.string);
   slug = E.field(E.string);
@@ -448,7 +437,7 @@ class Article extends E.Model<Article> {
   preCommit() {
     this.slug = this.title.toLowerCase().replace(/\s+/g, "-");
   }
-}
+});
 ```
 
 ### Change Tracking
@@ -489,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.
 
-### init · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L67)
+**Signature:** `() => Transaction`
+
+### 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(),
@@ -511,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#L118)
+### transact · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L136)
 
 Executes a function within a database transaction context.
 
@@ -531,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 +537,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;
@@ -556,12 +548,12 @@ 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++;
 });
 ```
 
-### setMaxRetryCount · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L209)
+### setMaxRetryCount · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L226)
 
 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.
@@ -572,142 +564,121 @@ 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#L223)
+### setOnSaveCallback · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L240)
 
 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#L228)
+### Model · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
-**Signature:** `() => Promise<void>`
+**Type:** `typeof ModelBase`
 
-### Model · [abstract class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L221)
+### ModelClass · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
-[object Object],[object Object],[object Object],[object Object],[object Object]
+Runtime base constructor for model classes returned by `defineModel()`.
 
-**Type Parameters:**
+Prefer the `ModelClass` type alias for annotations and the result of
+`defineModel()` for concrete model classes.
 
-- `SUB` - The concrete model subclass (for proper typing).
+**Type:** `typeof ModelClassRuntime`
 
-**Examples:**
+### AnyModelClass · [type](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L111)
 
-```typescript
-⁣@E.registerModel
-class User extends E.Model<User> {
-  static pk = E.primary(User, "id");
-  
-  id = E.field(E.identifier);
-  name = E.field(E.string);
-  email = E.field(E.string);
-  
-  static byEmail = E.unique(User, "email");
-}
-```
+A model constructor with its generic information erased.
 
-#### Model.tableName · [static property](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L225)
+Useful when accepting or storing arbitrary registered model classes.
 
-The database table name (defaults to class name).
+**Type:** `ModelClass<new () => any, readonly any[], any, any>`
 
-**Type:** `string`
+### ModelBase · [abstract class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
-#### Model.override · [static property](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L231)
+Base class for all database models in the Edinburgh ORM.
 
-When true, registerModel replaces an existing model with the same tableName.
+Models represent database entities with typed fields, automatic serialization,
+change tracking, and relationship management. Model classes are created using
+`E.defineModel()`.
 
-**Type:** `boolean`
+### Schema Evolution
 
-#### Model.fields · [static property](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L233)
+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.
 
-Field configuration metadata.
+**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.
 
-**Type:** `Record<string | number | symbol, FieldConfig<unknown>>`
+**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
 
-#### Model.migrate · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+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).
 
-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.
+### Lifecycle Hooks
 
-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.
+- **`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.
 
-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).
-
-**Signature:** `(record: Record<string, any>) => void`
-
-**Parameters:**
-
-- `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
-⁣@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
-
-  static migrate(record: Record<string, any>) {
-    record.role ??= "user";  // default for rows that predate the 'role' field
-  }
-}
+  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.initFields · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
-
-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.
-
-**Signature:** `(reset?: boolean) => void`
-
-**Parameters:**
-
-- `reset?: boolean`
-
-#### Model.findAll · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+#### ModelBase.migrate · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
-Find all instances of this model in the database, ordered by primary key.
+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:** `<T extends typeof Model<unknown>>(this: T, opts?: { reverse?: boolean; }) => IndexRangeIterator<T>`
+**Signature:** `(record: Record<string, any>) => void`
 
 **Parameters:**
 
-- `this: T`
-- `opts?: {reverse?: boolean}` - - Optional parameters.
-
-**Returns:** An iterator.
-
-#### Model.replaceInto · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
-
-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<Omit<InstanceType<T>, "constructor">>) => InstanceType<T>`
-
-**Parameters:**
+**Examples:**
 
-- `this: T`
-- `obj: Partial<Omit<InstanceType<T>, "constructor">>` - - 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#L255)
+#### modelBase.preCommit · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 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.
@@ -723,9 +694,7 @@ Common use cases:
 **Examples:**
 
 ```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);
@@ -733,22 +702,22 @@ class Post extends E.Model<Post> {
   preCommit() {
     this.slug = this.title.toLowerCase().replace(/\s+/g, "-");
   }
-}
+}, { pk: "id" });
 ```
 
-#### model.getPrimaryKey · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+#### modelBase.getPrimaryKey · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 **Signature:** `() => Uint8Array<ArrayBufferLike>`
 
 **Returns:** The primary key for this instance.
 
-#### model.getPrimaryKeyHash · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+#### modelBase.getPrimaryKeyHash · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 **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#L255)
+#### modelBase.isLazyField · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 **Signature:** `(field: keyof this) => boolean`
 
@@ -756,7 +725,7 @@ class Post extends E.Model<Post> {
 
 - `field: keyof this`
 
-#### model.preventPersist · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+#### modelBase.preventPersist · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Prevent this instance from being persisted to the database.
 
@@ -767,12 +736,12 @@ Prevent this instance from being persisted to the database.
 **Examples:**
 
 ```typescript
-const user = User.load("user123");
+const user = User.get("user123");
 user.name = "New Name";
 user.preventPersist(); // Changes won't be saved
 ```
 
-#### model.delete · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+#### modelBase.delete · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Delete this model instance from the database.
 
@@ -783,11 +752,11 @@ Removes the instance and all its index entries from the database and prevents fu
 **Examples:**
 
 ```typescript
-const user = User.load("user123");
+const user = User.get("user123");
 user.delete(); // Removes from database
 ```
 
-#### model.validate · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+#### modelBase.validate · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Validate all fields in this model instance.
 
@@ -795,7 +764,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).
 
@@ -809,7 +778,7 @@ if (errors.length > 0) {
 }
 ```
 
-#### model.isValid · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+#### modelBase.isValid · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Check if this model instance is valid.
 
@@ -824,46 +793,52 @@ const user = new User({name: "John"});
 if (!user.isValid()) shoutAtTheUser();
 ```
 
-#### model.getState · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+#### modelBase.getState · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 **Signature:** `() => "created" | "deleted" | "loaded" | "lazy"`
 
-#### model.toString · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+#### modelBase.toString · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 **Signature:** `() => string`
 
-#### model.[Symbol.for('nodejs.util.inspect.custom')] · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+#### modelBase.[Symbol.for('nodejs.util.inspect.custom')] · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 **Signature:** `() => string`
 
-### registerModel · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L113)
+### defineModel · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Register a model class with the Edinburgh ORM system.
 
-**Signature:** `<T extends typeof Model<unknown>>(MyModel: T) => T`
+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 typeof Model<unknown>` - The model class type.
+- `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:**
 
-- `MyModel: T` - - The model class to register.
+- `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 class with ORM capabilities.
+**Returns:** The enhanced model constructor.
 
-**Examples:**
+### deleteEverything · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
-```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);
-}
-```
+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.
 
-### field · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L89)
+**Signature:** `() => Promise<void>`
+
+### field · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L76)
 
 Create a field definition for a model property.
 
@@ -879,27 +854,27 @@ 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});
-}
+});
 ```
 
-### string · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+### string · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Type wrapper instance for the string type.
 
 **Value:** `TypeWrapper<string>`
 
-### orderedString · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+### orderedString · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Type wrapper instance for the ordered string type, which is just like a string
 except that it sorts lexicographically in the database (instead of by incrementing
@@ -909,37 +884,37 @@ may not contain null characters.
 
 **Value:** `TypeWrapper<string>`
 
-### number · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+### number · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Type wrapper instance for the number type.
 
 **Value:** `TypeWrapper<number>`
 
-### dateTime · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+### dateTime · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Type wrapper instance for the date/time type. Stored without timezone info, rounded to whole seconds.
 
 **Value:** `TypeWrapper<Date>`
 
-### boolean · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+### boolean · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Type wrapper instance for the boolean type.
 
 **Value:** `TypeWrapper<boolean>`
 
-### identifier · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+### identifier · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Type wrapper instance for the identifier type.
 
 **Value:** `TypeWrapper<string>`
 
-### undef · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+### undef · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Type wrapper instance for the 'undefined' type.
 
 **Value:** `TypeWrapper<undefined>`
 
-### opt · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+### opt · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Create an optional type wrapper (allows undefined).
 
@@ -951,7 +926,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.
 
@@ -962,7 +937,7 @@ const optionalString = E.opt(E.string);
 const optionalNumber = E.opt(E.number);
 ```
 
-### or · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+### or · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Create a union type wrapper from multiple type choices.
 
@@ -974,7 +949,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.
 
@@ -985,7 +960,7 @@ const stringOrNumber = E.or(E.string, E.number);
 const status = E.or("active", "inactive", "pending");
 ```
 
-### array · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+### array · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Create an array type wrapper with optional length constraints.
 
@@ -997,8 +972,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.
 
@@ -1009,7 +984,7 @@ const stringArray = E.array(E.string);
 const boundedArray = E.array(E.number, {min: 1, max: 10});
 ```
 
-### set · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+### set · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Create a Set type wrapper with optional length constraints.
 
@@ -1021,8 +996,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.
 
@@ -1033,7 +1008,7 @@ const stringSet = E.set(E.string);
 const boundedSet = E.set(E.number, {min: 1, max: 10});
 ```
 
-### record · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+### record · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Create a Record type wrapper for key-value objects with string or number keys.
 
@@ -1045,7 +1020,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.
 
@@ -1055,7 +1030,7 @@ Create a Record type wrapper for key-value objects with string or number keys.
 const scores = E.record(E.number);  // Record<string | number, number>
 ```
 
-### literal · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+### literal · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 Create a literal type wrapper for a constant value.
 
@@ -1067,7 +1042,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.
 
@@ -1078,274 +1053,227 @@ const statusType = E.literal("active");
 const countType = E.literal(42);
 ```
 
-### link · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+### link · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
 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')));
-}
+const Author = E.defineModel("Author", class {
+  id = E.field(E.identifier);
+  posts = E.field(E.array(E.link(() => Book)));
+}, { pk: "id" });
 
-class Post extends E.Model<Post> {
-  author = E.field(E.link(User));
-}
+const Book = E.defineModel("Book", class {
+  id = E.field(E.identifier);
+  author = E.field(E.link(Author));
+}, { pk: "id" });
 ```
 
-### index · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
-
-Create a secondary index on model fields, or a computed secondary index using a function.
-
-For field-based indexes, pass a field name or array of field names.
-For computed indexes, pass a function that takes a model instance and returns an array of
-index keys. Return `[]` to skip indexing for that instance. Each array element creates a
-separate index entry, enabling multi-value indexes (e.g., indexing by each word in a name).
-
-**Signature:** `{ <M extends typeof Model, V>(MyModel: M, fn: (instance: InstanceType<M>) => V[]): SecondaryIndex<M, [], [V]>; <M extends typeof Model, const F extends (keyof InstanceType<M> & string)>(MyModel: M, field: F): SecondaryIndex<...>; <M extends typeof Model, const FS extends readonly (keyof InstanceType<M> & string)[]>(...`
-
-**Type Parameters:**
+### dump · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
 
-- `M extends typeof Model` - The model class.
-- `V` - The computed index value type (for function-based indexes).
-
-**Parameters:**
+**Signature:** `() => void`
 
-- `MyModel: M` - - The model class to create the index for.
-- `fn: (instance: InstanceType<M>) => V[]`
+### 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 })
+)`
 
-**Returns:** A new SecondaryIndex instance.
+### IndexRangeIterator · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L73)
 
-**Examples:**
+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.
 
-```typescript
-class User extends E.Model<User> {
-  static byAge = E.index(User, "age");
-  static byTagsDate = E.index(User, ["tags", "createdAt"]);
-  static byWord = E.index(User, (u: User) => u.name.split(" "));
-}
-```
+**Type Parameters:**
 
-### primary · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+- `ITEM`
 
-Create a primary index on model fields.
+#### indexRangeIterator.[Symbol.iterator] · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L78)
 
-**Signature:** `{ <M extends typeof Model, const F extends (keyof InstanceType<M> & string)>(MyModel: M, field: F): PrimaryIndex<M, [F]>; <M extends typeof Model, const FS extends readonly (keyof InstanceType<M> & string)[]>(MyModel: M, fields: FS): PrimaryIndex<...>; }`
+**Signature:** `() => this`
 
-**Type Parameters:**
+#### indexRangeIterator.next · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L80)
 
-- `M extends typeof Model` - The model class.
-- `F extends (keyof InstanceType<M> & string)` - The field name (for single field index).
+**Signature:** `() => IteratorResult<ITEM, any>`
 
-**Parameters:**
+#### indexRangeIterator.count · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L102)
 
-- `MyModel: M` - - The model class to create the index for.
-- `field: F` - - Single field name for simple indexes.
+**Signature:** `() => number`
 
-**Returns:** A new PrimaryIndex instance.
+#### indexRangeIterator.fetch · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L105)
 
-**Examples:**
+**Signature:** `() => ITEM`
 
-```typescript
-class User extends E.Model<User> {
-  static pk = E.primary(User, ["id"]);
-  static pkSingle = E.primary(User, "id");
-}
-```
-
-### unique · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+### Change · [type](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L85)
 
-Create a unique index on model fields, or a computed unique index using a function.
+**Type:** `Record<any, any> | "created" | "deleted"`
 
-For field-based indexes, pass a field name or array of field names.
-For computed indexes, pass a function that takes a model instance and returns an array of
-index keys. Return `[]` to skip indexing for that instance. Each array element creates a
-separate index entry, enabling multi-value indexes (e.g., indexing by each word in a name).
+### FieldConfig · [interface](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L37)
 
-**Signature:** `{ <M extends typeof Model, V>(MyModel: M, fn: (instance: InstanceType<M>) => V[]): UniqueIndex<M, [], [V]>; <M extends typeof Model, const F extends (keyof InstanceType<M> & string)>(MyModel: M, field: F): UniqueIndex<...>; <M extends typeof Model, const FS extends readonly (keyof InstanceType<M> & string)[]>(MyMode...`
+Configuration interface for model fields.
 
 **Type Parameters:**
 
-- `M extends typeof Model` - The model class.
-- `V` - The computed index value type (for function-based indexes).
-
-**Parameters:**
-
-- `MyModel: M` - - The model class to create the index for.
-- `fn: (instance: InstanceType<M>) => V[]`
+- `T` - The field type.
 
-**Returns:** A new UniqueIndex instance.
+#### fieldConfig.type · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L45)
 
-**Examples:**
+The type wrapper that defines how this field is serialized/validated.
 
-```typescript
-class User extends E.Model<User> {
-  static byEmail = E.unique(User, "email");
-  static byNameAge = E.unique(User, ["name", "age"]);
-  static byFullName = E.unique(User, (u: User) => [`${u.firstName} ${u.lastName}`]);
-}
-```
+**Type:** `TypeWrapper<T>`
 
-### dump · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+#### fieldConfig.description · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L47)
 
-Dump database contents for debugging.
+Optional human-readable description of the field.
 
-Prints all indexes and their data to the console for inspection.
-This is primarily useful for development and debugging purposes.
+**Type:** `string`
 
-**Signature:** `() => void`
+#### fieldConfig.default · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L49)
 
-### BaseIndex · [abstract class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L123)
+Optional default value or function that generates default values.
 
-Base class for database indexes for efficient lookups on model fields.
+**Type:** `T | ((model: Record<string, any>) => T)`
 
-Indexes enable fast queries on specific field combinations and enforce uniqueness constraints.
+### TypeWrapper · [abstract class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L33)
 
 **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 TypeScript type this wrapper represents.
 
-**Constructor Parameters:**
+#### typeWrapper.kind · [abstract property](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L47)
 
-- `MyModel`: - The model class this index belongs to.
-- `_fieldNames`: - Array of field names that make up this index.
+A string identifier for this type, used during serialization
 
-#### baseIndex.find · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
-
-**Signature:** `(opts?: FindOptions<ARGS>) => IndexRangeIterator<M>`
-
-**Parameters:**
-
-- `opts: FindOptions<ARGS>` (optional)
+**Type:** `string`
 
-#### baseIndex.batchProcess · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+#### typeWrapper.serialize · [abstract method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L52)
 
-[object Object],[object Object],[object Object]
+Serialize a value from an object property to a Pack.
 
-**Signature:** `(opts: FindOptions<ARGS> & { limitSeconds?: number; limitRows?: number; }, callback: (row: InstanceType<M>) => void | Promise<void>) => Promise<...>`
+**Signature:** `(value: T, pack: DataPack) => void`
 
 **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
-
-#### baseIndex.toString · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
-
-**Signature:** `() => string`
-
-### UniqueIndex · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
-
-Unique index that stores references to the primary key.
-
-**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>`
+- `value: T` - The value to serialize.
+- `pack: DataPack` - The Pack instance to write to.
 
-#### uniqueIndex.get · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+#### typeWrapper.deserialize · [abstract method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L59)
 
-Get a model instance by unique index key values.
+Deserialize a value from a Pack into an object property.
 
-**Signature:** `(...args: ARGS) => InstanceType<M>`
+**Signature:** `(pack: DataPack) => T`
 
 **Parameters:**
 
-- `args: ARGS` - - The unique index key values.
+- `pack: DataPack` - The Pack instance to read from.
 
-**Returns:** The model instance if found, undefined otherwise.
+#### typeWrapper.getError · [abstract method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L64)
 
-**Examples:**
+Validate a value.
 
-```typescript
-const userByEmail = User.byEmail.get("john@example.com");
-```
-
-### PrimaryIndex · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+**Signature:** `(value: T) => void | DatabaseError`
 
-Primary index that stores the actual model data.
+**Parameters:**
 
-**Type Parameters:**
+- `value: T` - The value to validate.
 
-- `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.
+**Returns:** - A DatabaseError if validation fails.
 
-#### primaryIndex.get · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+#### typeWrapper.serializeType · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L68)
 
-Get a model instance by primary key values.
+Serialize type metadata to a Pack (for schema serialization).
 
-**Signature:** `(...args: IndexArgTypes<M, F>) => InstanceType<M>`
+**Signature:** `(pack: DataPack) => void`
 
 **Parameters:**
 
-- `args: IndexArgTypes<M, F>` - - The primary key values.
+- `pack: DataPack` - The Pack instance to write to.
 
-**Returns:** The model instance if found, undefined otherwise.
+#### typeWrapper.containsNull · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L77)
 
-**Examples:**
-
-```typescript
-const user = User.pk.get("john_doe");
-```
-
-#### primaryIndex.getLazy · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
-
-Does the same as as `get()`, but will delay loading the instance from disk until the first
-property access. In case it turns out the instance doesn't exist, an error will be thrown
-at that time.
+Check if indexing should be skipped for this field value.
 
-**Signature:** `(...args: IndexArgTypes<M, F>) => InstanceType<M>`
+**Signature:** `(value: T) => boolean`
 
 **Parameters:**
 
-- `args: IndexArgTypes<M, F>` - Primary key field values. (Or a single Uint8Array containing the key.)
+- `value: T`
 
-**Returns:** The (lazily loaded) model instance.
+**Returns:** true if indexing should be skipped.
 
-### SecondaryIndex · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L255)
+#### typeWrapper.toString · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L78)
 
-Secondary index for non-unique lookups.
+**Signature:** `() => string`
 
-**Type Parameters:**
+#### typeWrapper.clone · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L81)
 
-- `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>`
+**Signature:** `(value: T) => T`
 
-### Change · [type](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L95)
+**Parameters:**
 
-**Type:** `Record<any, any> | "created" | "deleted"`
+- `value: T`
 
-### Transaction · [interface](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L38)
+#### typeWrapper.equals · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L85)
 
-#### transaction.id · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L41)
+**Signature:** `(value1: T, value2: T) => boolean`
 
-**Type:** `number`
-
-#### 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#L46)
+#### 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#L158)
+### DatabaseError · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L166)
 
 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.
@@ -1355,7 +1283,7 @@ Invalid function arguments will throw TypeError.
 
 **Value:** `DatabaseErrorConstructor`
 
-### runMigration · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L124)
+### 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.
@@ -1366,7 +1294,7 @@ convert old primary indices, rewrite row data, and clean up orphaned indices.
 
 - `options: MigrationOptions` (optional)
 
-### MigrationOptions · [interface](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L16)
+### 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#L18)
 
@@ -1374,45 +1302,45 @@ Limit migration to specific table names.
 
 **Type:** `string[]`
 
-#### migrationOptions.populateSecondaries · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L23)
+#### 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).
 
 **Type:** `boolean`
 
-#### migrationOptions.migratePrimaries · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L32)
+#### migrationOptions.migratePrimaries · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L29)
 
 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#L40)
+#### 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#L46)
+#### 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#L48)
+#### 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#L51)
+### 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#L54)
+#### migrationResult.secondaries · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L52)
 
 Per-table counts of secondary index entries populated.
 
 **Type:** `Record<string, number>`
 
-#### migrationResult.primaries · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L59)
+#### migrationResult.primaries · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L56)
 
 Per-table counts of old primary rows migrated.
 
@@ -1424,15 +1352,29 @@ 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#L64)
+#### 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#L68)
+#### 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>`
+