edinburgh 0.4.4 → 0.4.5

package/skill/SKILL.md

@@ -392,13 +392,9 @@ await Product.byCategory.batchProcess({is: "old"}, (product) => {
 // Commits every ~1 second or 4096 rows (configurable via limitSeconds, limitRows)
 ```
 
-### Schema Evolution
+### Lazy Schema Migrations
 
-Edinburgh handles schema changes automatically:
-
-- **Adding/removing fields**: Old rows are lazily migrated on read. New fields use their default value.
-- **Changing field types**: Requires a `static migrate()` function.
-- **Adding/removing indexes**: Requires running `npx migrate-edinburgh`.
+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.
 
 ```typescript
 @E.registerModel
@@ -406,15 +402,40 @@ class User extends E.Model<User> {
   static pk = E.primary(User, "id");
   id = E.field(E.identifier);
   name = E.field(E.string);
-  role = E.field(E.string, {default: "user"});  // new field
+  role = E.field(E.string);  // newly added field
 
   static migrate(record: Record<string, any>) {
-    record.role ??= "user";  // provide value for old rows
+    record.role ??= record.name.indexOf("admin") >= 0 ? "admin" : "user"; // set role based on name for old records
   }
 }
 ```
 
-Run `npx migrate-edinburgh` (or call `E.runMigration()`) after adding/removing indexes, changing index field types, or when a `migrate()` function affects indexed fields.
+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...
+- Is idempotent (meaning it can be safely run multiple times on the same row without changing the result after the first run), and
+- Should perform *all* transformation steps starting from the oldest version that could possibly still be in the database. (See the next section.)
+
+While lazy migration is convenient and often sufficient, in some cases you need migrations to happen immediately...
+
+### Forced Schema Migrations
+
+The `migrate-edinburgh` CLI tool will scan the entire database, pro-actively performing the following migrations:
+- **Populate secondary indexes**: If you added or changed secondary indexes, it will build them. Until you do, the indexes will be empty (or only contain instances that have been saved since the index was created).
+- **Migrate primary indexes**: In case you changed the primary key fields or field types (not recommended!) of a model, it will build the new primary index, as well as all secondary indexes (to point at the new primary keys). Until you do, all of your old data will appear to be missing! Note that this may fail on duplicates.
+- **Remove orphaned indexes**: If you removed or changed an index, the stale data will be deleted from the database.
+- **Rewrite primary data**: These are the types of migrations that would normally be done lazily on instance access. As there's usually not much benefit to doing this forcibly, and it can be very time-consuming (and generates a lot of I/O), this is *not* done by default. It may however be useful if you want to clean up the contents of your `migrate()` function, if you have control over all application deployments. Use the `--rewrite-data` flag to enable this.
+
+```bash
+npx migrate-edinburgh ./src/models.ts
+```
+
+Run `npx migrate-edinburgh` without arguments to see all options. You can also call `runMigration()` programmatically:
+
+```typescript
+import { runMigration } from "edinburgh";
+
+const result = await runMigration({ tables: ["User"] });
+console.log(result.secondaries);  // { User: 1500 }
+```
 
 ### preCommit Hook
 
@@ -476,125 +497,33 @@ The following is auto-generated from `src/edinburgh.ts`:
 
 **Signature:** `() => void`
 
-### init · function
+### [init](init.md) · function
 
 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(),
 the database will be automatically initialized with the default directory.
 
-**Signature:** `(dbDir: string) => void`
-
-**Parameters:**
-
-- `dbDir: string`
-
-**Examples:**
-
-```typescript
-init("./my-database");
-```
-
-### transact · function
+### [transact](transact.md) · function
 
 Executes a function within a database transaction context.
 
-Loading models (also through links in other models) and changing models can only be done from
-within a transaction.
-
-Transactions have a consistent view of the database, and changes made within a transaction are
-isolated from other transactions until they are committed. In case a commit clashes with changes
-made by another transaction, the transaction function will automatically be re-executed up to 6
-times.
-
-**Signature:** `<T>(fn: () => T) => Promise<T>`
-
-**Type Parameters:**
-
-- `T` - The return type of the transaction function.
-
-**Parameters:**
-
-- `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.
-
-**Throws:**
-
-- With code "RACING_TRANSACTION" if the transaction fails after retries due to conflicts.
-- With code "TXN_LIMIT" if maximum number of transactions is reached.
-- With code "LMDB-{code}" for LMDB-specific errors.
-
-**Examples:**
-
-```typescript
-const paid = await E.transact(() => {
-  const user = User.pk.get("john_doe");
-  if (user.credits > 0) {
-    user.credits--;
-    return true;
-  }
-  return false;
-});
-```
-```typescript
-// Transaction with automatic retry on conflicts
-await E.transact(() => {
-  const counter = Counter.pk.get("global") || new Counter({id: "global", value: 0});
-  counter.value++;
-});
-```
-
-### setMaxRetryCount · function
+### [setMaxRetryCount](setMaxRetryCount.md) · function
 
 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.
 
-**Signature:** `(count: number) => void`
-
-**Parameters:**
-
-- `count: number` - The maximum number of retries for a transaction.
-
-### setOnSaveCallback · function
+### [setOnSaveCallback](setOnSaveCallback.md) · function
 
 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`
-
-**Parameters:**
-
-- `callback: ((commitId: number, items: Map<Model<any>, 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
 
 **Signature:** `() => Promise<void>`
 
-### Model · abstract class
+### [Model](Model.md) · abstract class
 
 [object Object],[object Object],[object Object],[object Object],[object Object]
 
-**Type Parameters:**
-
-- `SUB` - The concrete model subclass (for proper typing).
-
-**Examples:**
-
-```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");
-}
-```
-
 #### Model.tableName · static property
 
 The database table name (defaults to class name).
@@ -613,120 +542,32 @@ Field configuration metadata.
 
 **Type:** `Record<string | number | symbol, FieldConfig<unknown>>`
 
-#### Model.migrate · static method
+#### [Model.migrate](Model_migrate.md) · static method
 
 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.
 
-This is called both during lazy loading (when a row is read from disk) and during batch
-migration (via `runMigration()` / `npx migrate-edinburgh`). The function's source code is hashed
-to detect changes. Modifying `migrate()` triggers a new schema version.
-
-If `migrate()` changes values of fields used in secondary or unique indexes, those indexes
-will only be updated when `runMigration()` is run (not during lazy loading).
-
-**Signature:** `(record: Record<string, any>) => void`
-
-**Parameters:**
-
-- `record: Record<string, any>` - - A plain object with all field values from the old schema version.
-
-**Examples:**
-
-```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);
-  role = E.field(E.string);  // new field
-
-  static migrate(record: Record<string, any>) {
-    record.role ??= "user";  // default for rows that predate the 'role' field
-  }
-}
-```
-
-#### Model.findAll · static method
+#### [Model.findAll](Model_findAll.md) · static method
 
 Find all instances of this model in the database, ordered by primary key.
 
-**Signature:** `<T extends typeof Model<unknown>>(this: T, opts?: { reverse?: boolean; }) => IndexRangeIterator<T>`
-
-**Parameters:**
-
-- `this: T`
-- `opts?: {reverse?: boolean}` - - Optional parameters.
-
-**Returns:** An iterator.
-
-#### Model.replaceInto · static method
+#### [Model.replaceInto](Model_replaceInto.md) · static method
 
 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.
-
-**Signature:** `<T extends typeof Model<any>>(this: T, obj: Partial<Omit<InstanceType<T>, "constructor">>) => InstanceType<T>`
-
-**Parameters:**
-
-- `this: T`
-- `obj: Partial<Omit<InstanceType<T>, "constructor">>` - - Partial model data that **must** include every primary key field.
-
-**Returns:** The loaded-and-updated or newly created instance.
-
-#### model.preCommit · method
+#### [model.preCommit](Model_preCommit.md) · method
 
 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.
 
-Common use cases:
-- Computing derived or denormalized fields
-- Enforcing cross-field validation rules
-- Creating or updating related model instances (newly created instances will also
-  have their `preCommit()` called)
-
-**Signature:** `() => void`
-
-**Parameters:**
-
-
-**Examples:**
-
-```typescript
-⁣@E.registerModel
-class Post extends E.Model<Post> {
-  static pk = E.primary(Post, "id");
-  id = E.field(E.identifier);
-  title = E.field(E.string);
-  slug = E.field(E.string);
-
-  preCommit() {
-    this.slug = this.title.toLowerCase().replace(/\s+/g, "-");
-  }
-}
-```
-
 #### model.getPrimaryKey · method
 
 **Signature:** `() => Uint8Array<ArrayBufferLike>`
 
-**Parameters:**
-
-
 **Returns:** The primary key for this instance.
 
-#### model.getPrimaryKeyHash · method
-
-**Signature:** `() => number`
-
-**Parameters:**
-
-
-**Returns:** A 53-bit positive integer non-cryptographic hash of the primary key, or undefined if not yet saved.
+#### [model.getPrimaryKeyHash](Model_getPrimaryKeyHash.md) · method
 
 #### model.isLazyField · method
 
@@ -736,161 +577,42 @@ class Post extends E.Model<Post> {
 
 - `field: keyof this`
 
-#### model.preventPersist · method
+#### [model.preventPersist](Model_preventPersist.md) · method
 
 Prevent this instance from being persisted to the database.
 
-**Signature:** `() => this`
-
-**Parameters:**
-
-
-**Returns:** This model instance for chaining.
-
-**Examples:**
-
-```typescript
-const user = User.load("user123");
-user.name = "New Name";
-user.preventPersist(); // Changes won't be saved
-```
-
-#### model.delete · method
+#### [model.delete](Model_delete.md) · method
 
 Delete this model instance from the database.
 
-Removes the instance and all its index entries from the database and prevents further persistence.
-
-**Signature:** `() => void`
-
-**Parameters:**
-
-
-**Examples:**
-
-```typescript
-const user = User.load("user123");
-user.delete(); // Removes from database
-```
-
-#### model.validate · method
+#### [model.validate](Model_validate.md) · method
 
 Validate all fields in this model instance.
 
-**Signature:** `(raise?: boolean) => Error[]`
-
-**Parameters:**
-
-- `raise: boolean` (optional) - - If true, throw on first validation error.
-
-**Returns:** Array of validation errors (empty if valid).
-
-**Examples:**
-
-```typescript
-const user = new User();
-const errors = user.validate();
-if (errors.length > 0) {
-  console.log("Validation failed:", errors);
-}
-```
-
-#### model.isValid · method
+#### [model.isValid](Model_isValid.md) · method
 
 Check if this model instance is valid.
 
-**Signature:** `() => boolean`
-
-**Parameters:**
-
-
-**Returns:** true if all validations pass.
-
-**Examples:**
-
-```typescript
-const user = new User({name: "John"});
-if (!user.isValid()) shoutAtTheUser();
-```
-
 #### model.getState · method
 
 **Signature:** `() => "created" | "deleted" | "loaded" | "lazy"`
 
-**Parameters:**
-
-
 #### model.toString · method
 
 **Signature:** `() => string`
 
-**Parameters:**
-
-
 #### model.[Symbol.for('nodejs.util.inspect.custom')] · method
 
 **Signature:** `() => string`
 
-**Parameters:**
-
-
-### registerModel · function
+### [registerModel](registerModel.md) · function
 
 Register a model class with the Edinburgh ORM system.
 
-**Signature:** `<T extends typeof Model<unknown>>(MyModel: T) => T`
-
-**Type Parameters:**
-
-- `T extends typeof Model<unknown>` - The model class type.
-
-**Parameters:**
-
-- `MyModel: T` - - The model class to register.
-
-**Returns:** The enhanced model class with ORM capabilities.
-
-**Examples:**
-
-```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);
-}
-```
-
-### field · function
+### [field](field.md) · function
 
 Create a field definition for a model property.
 
-This function uses TypeScript magic to return the field configuration object
-while appearing to return the actual field value type to the type system.
-This allows for both runtime introspection and compile-time type safety.
-
-**Signature:** `<T>(type: TypeWrapper<T>, options?: Partial<FieldConfig<T>>) => T`
-
-**Type Parameters:**
-
-- `T` - The field type.
-
-**Parameters:**
-
-- `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> {
-  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
 
 Type wrapper instance for the string type.
@@ -937,397 +659,90 @@ Type wrapper instance for the 'undefined' type.
 
 **Value:** `TypeWrapper<undefined>`
 
-### opt · function
+### [opt](opt.md) · function
 
 Create an optional type wrapper (allows undefined).
 
-**Signature:** `<const T extends TypeWrapper<unknown> | BasicType>(inner: T) => TypeWrapper<T extends TypeWrapper<infer U> ? U : T>`
-
-**Type Parameters:**
-
-- `T extends TypeWrapper<unknown>|BasicType` - Type wrapper or basic type to make optional.
-
-**Parameters:**
-
-- `inner: T` - - The inner type to make optional.
-
-**Returns:** A union type that accepts the inner type or undefined.
-
-**Examples:**
-
-```typescript
-const optionalString = E.opt(E.string);
-const optionalNumber = E.opt(E.number);
-```
-
-### or · function
+### [or](or.md) · function
 
 Create a union type wrapper from multiple type choices.
 
-**Signature:** `<const T extends (TypeWrapper<unknown> | BasicType)[]>(...choices: T) => TypeWrapper<UnwrapTypes<T>>`
-
-**Type Parameters:**
-
-- `T extends (TypeWrapper<unknown>|BasicType)[]` - Array of type wrapper or basic types.
-
-**Parameters:**
-
-- `choices: T` - - The type choices for the union.
-
-**Returns:** A union type instance.
-
-**Examples:**
-
-```typescript
-const stringOrNumber = E.or(E.string, E.number);
-const status = E.or("active", "inactive", "pending");
-```
-
-### array · function
+### [array](array.md) · function
 
 Create an array type wrapper with optional length constraints.
 
-**Signature:** `<const T>(inner: TypeWrapper<T>, opts?: { min?: number; max?: number; }) => TypeWrapper<T[]>`
-
-**Type Parameters:**
-
-- `T` - The element type.
-
-**Parameters:**
-
-- `inner: TypeWrapper<T>` - - Type wrapper for array elements.
-- `opts: {min?: number, max?: number}` (optional) - - Optional constraints (min/max length).
-
-**Returns:** An array type instance.
-
-**Examples:**
-
-```typescript
-const stringArray = E.array(E.string);
-const boundedArray = E.array(E.number, {min: 1, max: 10});
-```
-
-### set · function
+### [set](set.md) · function
 
 Create a Set type wrapper with optional length constraints.
 
-**Signature:** `<const T>(inner: TypeWrapper<T>, opts?: { min?: number; max?: number; }) => TypeWrapper<Set<T>>`
-
-**Type Parameters:**
-
-- `T` - The element type.
-
-**Parameters:**
-
-- `inner: TypeWrapper<T>` - - Type wrapper for set elements.
-- `opts: {min?: number, max?: number}` (optional) - - Optional constraints (min/max length).
-
-**Returns:** A set type instance.
-
-**Examples:**
-
-```typescript
-const stringSet = E.set(E.string);
-const boundedSet = E.set(E.number, {min: 1, max: 10});
-```
-
-### record · function
+### [record](record.md) · function
 
 Create a Record type wrapper for key-value objects with string or number keys.
 
-**Signature:** `<const T>(inner: TypeWrapper<T>) => TypeWrapper<Record<string | number, T>>`
-
-**Type Parameters:**
-
-- `T` - The value type.
-
-**Parameters:**
-
-- `inner: TypeWrapper<T>` - - Type wrapper for record values.
-
-**Returns:** A record type instance.
-
-**Examples:**
-
-```typescript
-const scores = E.record(E.number);  // Record<string | number, number>
-```
-
-### literal · function
+### [literal](literal.md) · function
 
 Create a literal type wrapper for a constant value.
 
-**Signature:** `<const T>(value: T) => TypeWrapper<T>`
-
-**Type Parameters:**
-
-- `T` - The literal type.
-
-**Parameters:**
-
-- `value: T` - - The literal value.
-
-**Returns:** A literal type instance.
-
-**Examples:**
-
-```typescript
-const statusType = E.literal("active");
-const countType = E.literal(42);
-```
-
-### link · function
+### [link](link.md) · function
 
 Create a link type wrapper for model relationships.
 
-**Signature:** `<const T extends typeof Model<any>>(TargetModel: T) => TypeWrapper<InstanceType<T>>`
-
-**Type Parameters:**
-
-- `T extends typeof Model<any>` - The target model class.
-
-**Parameters:**
-
-- `TargetModel: T` - - The model class this link points to.
-
-**Returns:** A link type instance.
-
-**Examples:**
-
-```typescript
-class User extends E.Model<User> {
-  posts = E.field(E.array(E.link(Post, 'author')));
-}
-
-class Post extends E.Model<Post> {
-  author = E.field(E.link(User));
-}
-```
-
-### index · function
+### [index](index.md) · function
 
 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:**
-
-- `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[]`
-
-**Returns:** A new SecondaryIndex instance.
-
-**Examples:**
-
-```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(" "));
-}
-```
-
-### primary · function
+### [primary](primary.md) · function
 
 Create a primary index on model fields.
 
-**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<...>; }`
-
-**Type Parameters:**
-
-- `M extends typeof Model` - The model class.
-- `F extends (keyof InstanceType<M> & string)` - The field name (for single field index).
-
-**Parameters:**
-
-- `MyModel: M` - - The model class to create the index for.
-- `field: F` - - Single field name for simple indexes.
-
-**Returns:** A new PrimaryIndex instance.
-
-**Examples:**
-
-```typescript
-class User extends E.Model<User> {
-  static pk = E.primary(User, ["id"]);
-  static pkSingle = E.primary(User, "id");
-}
-```
-
-### unique · function
+### [unique](unique.md) · function
 
 Create a unique index on model fields, or a computed unique 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[]): 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...`
-
-**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[]`
-
-**Returns:** A new UniqueIndex instance.
-
-**Examples:**
-
-```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}`]);
-}
-```
-
-### dump · function
+### [dump](dump.md) · function
 
 Dump database contents for debugging.
 
-Prints all indexes and their data to the console for inspection.
-This is primarily useful for development and debugging purposes.
-
-**Signature:** `() => void`
-
-### BaseIndex · abstract class
+### [BaseIndex](BaseIndex.md) · abstract class
 
 Base class for database indexes for efficient lookups on model fields.
 
-Indexes enable fast queries on specific field combinations and enforce uniqueness constraints.
-
-**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>`
-
-**Constructor Parameters:**
+#### [baseIndex.find](BaseIndex_find.md) · method
 
-- `MyModel`: - The model class this index belongs to.
-- `_fieldNames`: - Array of field names that make up this index.
-
-#### baseIndex.find · method
-
-**Signature:** `(opts?: FindOptions<ARGS>) => IndexRangeIterator<M>`
-
-**Parameters:**
-
-- `opts: FindOptions<ARGS>` (optional)
-
-#### baseIndex.batchProcess · method
+#### [baseIndex.batchProcess](BaseIndex_batchProcess.md) · method
 
 [object Object],[object Object],[object Object]
 
-**Signature:** `(opts: FindOptions<ARGS> & { limitSeconds?: number; limitRows?: number; }, callback: (row: InstanceType<M>) => void | Promise<void>) => Promise<...>`
-
-**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
 
 **Signature:** `() => string`
 
-**Parameters:**
-
-
-### UniqueIndex · class
+### [UniqueIndex](UniqueIndex.md) · class
 
 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>`
-
-#### uniqueIndex.get · method
+#### [uniqueIndex.get](UniqueIndex_get.md) · method
 
 Get a model instance by unique index key values.
 
-**Signature:** `(...args: ARGS) => InstanceType<M>`
-
-**Parameters:**
-
-- `args: ARGS` - - The unique index key values.
-
-**Returns:** The model instance if found, undefined otherwise.
-
-**Examples:**
-
-```typescript
-const userByEmail = User.byEmail.get("john@example.com");
-```
-
-### PrimaryIndex · class
+### [PrimaryIndex](PrimaryIndex.md) · class
 
 Primary index that stores the actual model data.
 
-**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.
-
-#### primaryIndex.get · method
+#### [primaryIndex.get](PrimaryIndex_get.md) · method
 
 Get a model instance by primary key values.
 
-**Signature:** `(...args: IndexArgTypes<M, F>) => InstanceType<M>`
-
-**Parameters:**
-
-- `args: IndexArgTypes<M, F>` - - The primary key values.
-
-**Returns:** The model instance if found, undefined otherwise.
-
-**Examples:**
-
-```typescript
-const user = User.pk.get("john_doe");
-```
-
-#### primaryIndex.getLazy · method
+#### [primaryIndex.getLazy](PrimaryIndex_getLazy.md) · method
 
 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.
 
-**Signature:** `(...args: IndexArgTypes<M, F>) => InstanceType<M>`
-
-**Parameters:**
-
-- `args: IndexArgTypes<M, F>` - Primary key field values. (Or a single Uint8Array containing the key.)
-
-**Returns:** The (lazily loaded) model instance.
-
-### SecondaryIndex · class
+### [SecondaryIndex](SecondaryIndex.md) · class
 
 Secondary index for non-unique lookups.
 
-**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>`
-
 ### Change · type
 
 **Type:** `Record<any, any> | "created" | "deleted"`
@@ -1346,26 +761,15 @@ Secondary index for non-unique lookups.
 
 **Type:** `Map<number, Model<unknown>>`
 
-### DatabaseError · constant
+### [DatabaseError](DatabaseError.md) · constant
 
 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.
 
-The lowlevel API will throw DatabaseError instances for all database-related errors.
-Invalid function arguments will throw TypeError.
-
-**Value:** `DatabaseErrorConstructor`
-
-### runMigration · function
-
-Run database migration: upgrade all rows to the latest schema version,
-convert old primary indices, and clean up orphaned secondary indices.
-
-**Signature:** `(options?: MigrationOptions) => Promise<MigrationResult>`
-
-**Parameters:**
+### [runMigration](runMigration.md) · function
 
-- `options: MigrationOptions` (optional)
+Run database migration: populate secondary indexes for old-version rows,
+convert old primary indices, rewrite row data, and clean up orphaned indices.
 
 ### MigrationOptions · interface
 
@@ -1375,21 +779,27 @@ Limit migration to specific table names.
 
 **Type:** `string[]`
 
-#### migrationOptions.convertOldPrimaries · member
+#### migrationOptions.populateSecondaries · member
 
-Whether to convert old primary indices for known tables (default: true).
+Populate secondary indexes for rows at old schema versions (default: true).
 
 **Type:** `boolean`
 
-#### migrationOptions.deleteOrphanedIndexes · member
+#### migrationOptions.migratePrimaries · member
 
-Whether to delete orphaned secondary/unique indices (default: true).
+Convert old primary indices when primary key fields changed (default: true).
 
 **Type:** `boolean`
 
-#### migrationOptions.upgradeVersions · member
+#### migrationOptions.rewriteData · member
 
-Whether to upgrade rows to the latest version (default: true).
+Rewrite all row data to the latest schema version (default: false).
+
+**Type:** `boolean`
+
+#### migrationOptions.removeOrphans · member
+
+Delete orphaned secondary/unique index entries (default: true).
 
 **Type:** `boolean`
 
@@ -1403,13 +813,13 @@ Progress callback.
 
 #### migrationResult.secondaries · member
 
-Per-table stats for row upgrades.
+Per-table counts of secondary index entries populated.
 
 **Type:** `Record<string, number>`
 
 #### migrationResult.primaries · member
 
-Per-table stats for old primary conversions.
+Per-table counts of old primary rows migrated.
 
 **Type:** `Record<string, number>`
 
@@ -1419,55 +829,15 @@ Per-table conversion failure counts by reason.
 
 **Type:** `Record<string, Record<string, number>>`
 
-#### migrationResult.orphaned · member
+#### migrationResult.rewritten · member
 
-Number of orphaned index entries deleted.
+Per-table counts of rows rewritten to latest version.
 
-**Type:** `number`
-
-## Schema Migrations
-
-Edinburgh automatically tracks the schema version of each model. When you change fields, field types, indexes, or the `migrate()` function, Edinburgh detects a new schema version.
-
-### What happens automatically (lazy migration)
-
-Changes to regular (non-index) field values are migrated lazily. When a row with an old schema version is loaded from disk, it is deserialized using the old field types and transformed by the optional static `migrate()` function. This is transparent and requires no downtime.
-
-```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);
-  role = E.field(E.string);  // newly added field
-
-  static migrate(record: Record<string, any>) {
-    record.role ??= "user";  // provide a default for old rows
-  }
-}
-```
-
-### What requires `migrate-edinburgh`
-
-The `migrate-edinburgh` CLI tool (or the `runMigration()` API) must be run when:
-
-- **Adding or removing** secondary or unique indexes
-- **Changing the fields or types** of an existing index
-- A **`migrate()` function changes values** that are used in index fields
-
-The tool populates new indexes, removes orphaned ones, and updates index entries whose values were changed by `migrate()`. It does *not* rewrite primary data rows - lazy migration handles that on read.
-
-```bash
-npx migrate-edinburgh --import ./src/models.ts
-```
+**Type:** `Record<string, number>`
 
-Run `npx migrate-edinburgh` to see all of its options.
+#### migrationResult.orphans · member
 
-You can also call `runMigration()` programmatically:
+Number of orphaned index entries deleted.
 
-```typescript
-import { runMigration } from "edinburgh";
+**Type:** `number`
 
-const result = await runMigration({ tables: ["User"] });
-console.log(result.upgraded);  // { User: 1500 }
-```