edinburgh 0.4.2 → 0.4.5

package/README.md

@@ -117,6 +117,8 @@ Instance fields are declared with `E.field(type, options?)`. Available types:
 | `E.or(A, B, ...)` | `A \| B \| ...` | Union type; args can be types or literal values |
 | `E.literal(v)` | literal type | Constant value; defaults to that value |
 | `E.array(T)` | `T[]` | Optional `{min, max}` constraints |
+| `E.set(T)` | `Set<T>` | Optional `{min, max}` constraints |
+| `E.record(T)` | `Record<string \| number, T>` | Key-value object with string/number keys |
 | `E.link(Model)` | `Model` | Foreign key, lazy-loaded on access |
 
 #### Defaults
@@ -250,6 +252,67 @@ await E.transact(() => {
 });
 ```
 
+#### Non-Persistent Properties
+
+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);
+  firstName = E.field(E.string);
+  lastName = E.field(E.string);
+
+  // Non-persisted property
+  cachedFullName?: string;
+
+  get fullName(): string {
+    this.cachedFullName ??= `${this.firstName} ${this.lastName}`;
+    return this.cachedFullName;
+  }
+
+  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).
+
+```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]] : []);
+
+  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));
+}
+
+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");
+
+  // Multi-value: each word in the title is indexed separately
+  for (const a of Article.byWord.find({is: "hello"})) { ... }
+
+  // Partial index: articles without email are skipped
+  for (const a of Article.byDomain.find({is: "acme.com"})) { ... }
+});
+```
+
+Computed indexes also support `find()` range queries and `batchProcess()`, just like field-based indexes.
+
 ### Relationships (Links)
 
 Use `E.link(Model)` for foreign keys:
@@ -325,13 +388,9 @@ await Product.byCategory.batchProcess({is: "old"}, (product) => {
 // Commits every ~1 second or 4096 rows (configurable via limitSeconds, limitRows)
 ```
 
-### Schema Evolution
-
-Edinburgh handles schema changes automatically:
+### Lazy Schema Migrations
 
-- **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
@@ -339,15 +398,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
 
@@ -409,7 +493,7 @@ The following is auto-generated from `src/edinburgh.ts`:
 
 **Signature:** `() => void`
 
-### init · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L65)
+### init · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L67)
 
 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(),
@@ -427,7 +511,7 @@ the database will be automatically initialized with the default directory.
 init("./my-database");
 ```
 
-### transact · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L116)
+### transact · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L118)
 
 Executes a function within a database transaction context.
 
@@ -477,7 +561,7 @@ await E.transact(() => {
 });
 ```
 
-### setMaxRetryCount · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L206)
+### setMaxRetryCount · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L208)
 
 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.
@@ -488,7 +572,7 @@ The default value is 6. Setting it to 0 will disable retries and cause transacti
 
 - `count: number` - The maximum number of retries for a transaction.
 
-### setOnSaveCallback · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L220)
+### setOnSaveCallback · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L222)
 
 Set a callback function to be called after a model is saved and committed.
 
@@ -501,11 +585,11 @@ Set a callback function to be called after a model is saved and committed.
 - A sequential number. Higher numbers have been committed after lower numbers.
 - A map of model instances to their changes. The change can be "created", "deleted", or an object containing the old values.
 
-### deleteEverything · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L225)
+### deleteEverything · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L227)
 
 **Signature:** `() => Promise<void>`
 
-### Model · [abstract class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L218)
+### Model · [abstract class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L220)
 
 [object Object],[object Object],[object Object],[object Object],[object Object]
 
@@ -528,25 +612,25 @@ class User extends E.Model<User> {
 }
 ```
 
-#### Model.tableName · [static property](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L225)
+#### Model.tableName · [static property](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L227)
 
 The database table name (defaults to class name).
 
 **Type:** `string`
 
-#### Model.override · [static property](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L229)
+#### Model.override · [static property](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L231)
 
 When true, registerModel replaces an existing model with the same tableName.
 
 **Type:** `boolean`
 
-#### Model.fields · [static property](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L230)
+#### Model.fields · [static property](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L232)
 
 Field configuration metadata.
 
 **Type:** `Record<string | number | symbol, FieldConfig<unknown>>`
 
-#### Model.migrate · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### Model.migrate · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 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
@@ -581,7 +665,7 @@ class User extends E.Model<User> {
 }
 ```
 
-#### Model.findAll · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### Model.findAll · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Find all instances of this model in the database, ordered by primary key.
 
@@ -594,7 +678,7 @@ Find all instances of this model in the database, ordered by primary key.
 
 **Returns:** An iterator.
 
-#### Model.replaceInto · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### Model.replaceInto · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Load an existing instance by primary key and update it, or create a new one.
 
@@ -611,7 +695,7 @@ new instance is created with `obj` as its initial properties.
 
 **Returns:** The loaded-and-updated or newly created instance.
 
-#### model.preCommit · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### model.preCommit · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 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.
@@ -624,9 +708,6 @@ Common use cases:
 
 **Signature:** `() => void`
 
-**Parameters:**
-
-
 **Examples:**
 
 ```typescript
@@ -643,25 +724,19 @@ class Post extends E.Model<Post> {
 }
 ```
 
-#### model.getPrimaryKey · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### model.getPrimaryKey · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 **Signature:** `() => Uint8Array<ArrayBufferLike>`
 
-**Parameters:**
-
-
 **Returns:** The primary key for this instance.
 
-#### model.getPrimaryKeyHash · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### model.getPrimaryKeyHash · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 **Signature:** `() => number`
 
-**Parameters:**
-
-
 **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#L251)
+#### model.isLazyField · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 **Signature:** `(field: keyof this) => boolean`
 
@@ -669,15 +744,12 @@ class Post extends E.Model<Post> {
 
 - `field: keyof this`
 
-#### model.preventPersist · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### model.preventPersist · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Prevent this instance from being persisted to the database.
 
 **Signature:** `() => this`
 
-**Parameters:**
-
-
 **Returns:** This model instance for chaining.
 
 **Examples:**
@@ -688,7 +760,7 @@ user.name = "New Name";
 user.preventPersist(); // Changes won't be saved
 ```
 
-#### model.delete · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### model.delete · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Delete this model instance from the database.
 
@@ -696,9 +768,6 @@ Removes the instance and all its index entries from the database and prevents fu
 
 **Signature:** `() => void`
 
-**Parameters:**
-
-
 **Examples:**
 
 ```typescript
@@ -706,7 +775,7 @@ const user = User.load("user123");
 user.delete(); // Removes from database
 ```
 
-#### model.validate · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### model.validate · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Validate all fields in this model instance.
 
@@ -728,15 +797,12 @@ if (errors.length > 0) {
 }
 ```
 
-#### model.isValid · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### model.isValid · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Check if this model instance is valid.
 
 **Signature:** `() => boolean`
 
-**Parameters:**
-
-
 **Returns:** true if all validations pass.
 
 **Examples:**
@@ -746,28 +812,19 @@ const user = new User({name: "John"});
 if (!user.isValid()) shoutAtTheUser();
 ```
 
-#### model.getState · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### model.getState · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 **Signature:** `() => "created" | "deleted" | "loaded" | "lazy"`
 
-**Parameters:**
-
-
-#### model.toString · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### model.toString · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 **Signature:** `() => string`
 
-**Parameters:**
-
-
-#### model.[Symbol.for('nodejs.util.inspect.custom')] · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### model.[Symbol.for('nodejs.util.inspect.custom')] · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 **Signature:** `() => string`
 
-**Parameters:**
-
-
-### registerModel · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L111)
+### registerModel · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L113)
 
 Register a model class with the Edinburgh ORM system.
 
@@ -794,7 +851,7 @@ class User extends E.Model<User> {
 }
 ```
 
-### field · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L87)
+### field · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L89)
 
 Create a field definition for a model property.
 
@@ -824,13 +881,13 @@ class User extends E.Model<User> {
 }
 ```
 
-### string · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+### string · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Type wrapper instance for the string type.
 
 **Value:** `TypeWrapper<string>`
 
-### orderedString · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+### orderedString · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 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
@@ -840,37 +897,37 @@ may not contain null characters.
 
 **Value:** `TypeWrapper<string>`
 
-### number · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+### number · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Type wrapper instance for the number type.
 
 **Value:** `TypeWrapper<number>`
 
-### dateTime · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+### dateTime · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
-Type wrapper instance for the date/time type.
+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#L251)
+### boolean · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Type wrapper instance for the boolean type.
 
 **Value:** `TypeWrapper<boolean>`
 
-### identifier · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+### identifier · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Type wrapper instance for the identifier type.
 
 **Value:** `TypeWrapper<string>`
 
-### undef · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+### undef · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Type wrapper instance for the 'undefined' type.
 
 **Value:** `TypeWrapper<undefined>`
 
-### opt · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+### opt · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Create an optional type wrapper (allows undefined).
 
@@ -893,7 +950,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#L251)
+### or · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Create a union type wrapper from multiple type choices.
 
@@ -916,7 +973,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#L251)
+### array · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Create an array type wrapper with optional length constraints.
 
@@ -940,7 +997,53 @@ const stringArray = E.array(E.string);
 const boundedArray = E.array(E.number, {min: 1, max: 10});
 ```
 
-### literal · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+### set · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
+
+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](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
+
+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](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Create a literal type wrapper for a constant value.
 
@@ -963,7 +1066,7 @@ const statusType = E.literal("active");
 const countType = E.literal(42);
 ```
 
-### link · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+### link · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Create a link type wrapper for model relationships.
 
@@ -991,21 +1094,26 @@ class Post extends E.Model<Post> {
 }
 ```
 
-### index · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+### index · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
-Create a secondary index on model fields.
+Create a secondary index on model fields, or a computed secondary index using a function.
 
-**Signature:** `{ <M extends typeof Model, const F extends (keyof InstanceType<M> & string)>(MyModel: M, field: F): SecondaryIndex<M, [F]>; <M extends typeof Model, const FS extends readonly (keyof InstanceType<M> & string)[]>(MyModel: M, fields: FS): SecondaryIndex<...>; }`
+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.
-- `F extends (keyof InstanceType<M> & string)` - The field name (for single field index).
+- `V` - The computed index value type (for function-based indexes).
 
 **Parameters:**
 
 - `MyModel: M` - - The model class to create the index for.
-- `field: F` - - Single field name for simple indexes.
+- `fn: (instance: InstanceType<M>) => V[]`
 
 **Returns:** A new SecondaryIndex instance.
 
@@ -1015,10 +1123,11 @@ Create a secondary index on model fields.
 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](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+### primary · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Create a primary index on model fields.
 
@@ -1045,21 +1154,26 @@ class User extends E.Model<User> {
 }
 ```
 
-### unique · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+### unique · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
-Create a unique index on model fields.
+Create a unique index on model fields, or a computed unique index using a function.
 
-**Signature:** `{ <M extends typeof Model, const F extends (keyof InstanceType<M> & string)>(MyModel: M, field: F): UniqueIndex<M, [F]>; <M extends typeof Model, const FS extends readonly (keyof InstanceType<M> & string)[]>(MyModel: M, fields: FS): UniqueIndex<...>; }`
+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.
-- `F extends (keyof InstanceType<M> & string)` - The field name (for single field index).
+- `V` - The computed index value type (for function-based indexes).
 
 **Parameters:**
 
 - `MyModel: M` - - The model class to create the index for.
-- `field: F` - - Single field name for simple indexes.
+- `fn: (instance: InstanceType<M>) => V[]`
 
 **Returns:** A new UniqueIndex instance.
 
@@ -1069,10 +1183,11 @@ Create a unique index on model fields.
 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](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+### dump · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Dump database contents for debugging.
 
@@ -1081,7 +1196,7 @@ This is primarily useful for development and debugging purposes.
 
 **Signature:** `() => void`
 
-### BaseIndex · [abstract class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L127)
+### BaseIndex · [abstract class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L125)
 
 Base class for database indexes for efficient lookups on model fields.
 
@@ -1091,39 +1206,37 @@ Indexes enable fast queries on specific field combinations and enforce uniquenes
 
 - `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:**
 
 - `MyModel`: - The model class this index belongs to.
 - `_fieldNames`: - Array of field names that make up this index.
 
-#### baseIndex.find · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### baseIndex.find · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
-**Signature:** `(opts?: FindOptions<IndexArgTypes<M, F>>) => IndexRangeIterator<M>`
+**Signature:** `(opts?: FindOptions<ARGS>) => IndexRangeIterator<M>`
 
 **Parameters:**
 
-- `opts: FindOptions<IndexArgTypes<M, F>>` (optional)
+- `opts: FindOptions<ARGS>` (optional)
 
-#### baseIndex.batchProcess · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### baseIndex.batchProcess · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 [object Object],[object Object],[object Object]
 
-**Signature:** `(opts: FindOptions<IndexArgTypes<M, F>> & { limitSeconds?: number; limitRows?: number; }, callback: (row: InstanceType<M>) => void | Promise<...>) => Promise<...>`
+**Signature:** `(opts: FindOptions<ARGS> & { limitSeconds?: number; limitRows?: number; }, callback: (row: InstanceType<M>) => void | Promise<void>) => Promise<...>`
 
 **Parameters:**
 
-- `opts: FindOptions<IndexArgTypes<M, F>> & { limitSeconds?: number; limitRows?: number }` (optional) - - Query options (same as `find()`), plus:
+- `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#L251)
+#### baseIndex.toString · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 **Signature:** `() => string`
 
-**Parameters:**
-
-
-### UniqueIndex · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+### UniqueIndex · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Unique index that stores references to the primary key.
 
@@ -1131,16 +1244,17 @@ Unique index that stores references to the primary key.
 
 - `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](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### uniqueIndex.get · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Get a model instance by unique index key values.
 
-**Signature:** `(...args: IndexArgTypes<M, F>) => InstanceType<M>`
+**Signature:** `(...args: ARGS) => InstanceType<M>`
 
 **Parameters:**
 
-- `args: IndexArgTypes<M, F>` - - The unique index key values.
+- `args: ARGS` - - The unique index key values.
 
 **Returns:** The model instance if found, undefined otherwise.
 
@@ -1150,7 +1264,7 @@ Get a model instance by unique index key values.
 const userByEmail = User.byEmail.get("john@example.com");
 ```
 
-### PrimaryIndex · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+### PrimaryIndex · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Primary index that stores the actual model data.
 
@@ -1159,7 +1273,7 @@ Primary index that stores the actual model data.
 - `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](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### primaryIndex.get · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Get a model instance by primary key values.
 
@@ -1177,7 +1291,7 @@ Get a model instance by primary key values.
 const user = User.pk.get("john_doe");
 ```
 
-#### primaryIndex.getLazy · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+#### primaryIndex.getLazy · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 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
@@ -1191,7 +1305,7 @@ at that time.
 
 **Returns:** The (lazily loaded) model instance.
 
-### SecondaryIndex · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L251)
+### SecondaryIndex · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L253)
 
 Secondary index for non-unique lookups.
 
@@ -1199,8 +1313,9 @@ Secondary index for non-unique lookups.
 
 - `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](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L94)
+### Change · [type](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L95)
 
 **Type:** `Record<any, any> | "created" | "deleted"`
 
@@ -1214,11 +1329,11 @@ Secondary index for non-unique lookups.
 
 **Type:** `Set<Model<unknown>>`
 
-#### transaction.instancesByPk · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L44)
+#### transaction.instancesByPk · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L46)
 
 **Type:** `Map<number, Model<unknown>>`
 
-### DatabaseError · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L156)
+### DatabaseError · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L157)
 
 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.
@@ -1228,10 +1343,10 @@ Invalid function arguments will throw TypeError.
 
 **Value:** `DatabaseErrorConstructor`
 
-### runMigration · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L116)
+### runMigration · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L124)
 
-Run database migration: upgrade all rows to the latest schema version,
-convert old primary indices, and clean up orphaned secondary indices.
+Run database migration: populate secondary indexes for old-version rows,
+convert old primary indices, rewrite row data, and clean up orphaned indices.
 
 **Signature:** `(options?: MigrationOptions) => Promise<MigrationResult>`
 
@@ -1247,99 +1362,65 @@ Limit migration to specific table names.
 
 **Type:** `string[]`
 
-#### migrationOptions.convertOldPrimaries · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L22)
+#### migrationOptions.populateSecondaries · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L23)
+
+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)
 
-Whether to convert old primary indices for known tables (default: true).
+Convert old primary indices when primary key fields changed (default: true).
 
 **Type:** `boolean`
 
-#### migrationOptions.deleteOrphanedIndexes · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L30)
+#### migrationOptions.rewriteData · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L40)
 
-Whether to delete orphaned secondary/unique indices (default: true).
+Rewrite all row data to the latest schema version (default: false).
 
 **Type:** `boolean`
 
-#### migrationOptions.upgradeVersions · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L38)
+#### migrationOptions.removeOrphans · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L46)
 
-Whether to upgrade rows to the latest version (default: true).
+Delete orphaned secondary/unique index entries (default: true).
 
 **Type:** `boolean`
 
-#### migrationOptions.onProgress · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L42)
+#### migrationOptions.onProgress · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L48)
 
 Progress callback.
 
 **Type:** `(info: ProgressInfo) => void`
 
-### MigrationResult · [interface](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L47)
+### MigrationResult · [interface](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L51)
 
-#### migrationResult.secondaries · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L49)
+#### migrationResult.secondaries · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L54)
 
-Per-table stats for row upgrades.
+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#L50)
+#### migrationResult.primaries · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L59)
 
-Per-table stats for old primary conversions.
+Per-table counts of old primary rows migrated.
 
 **Type:** `Record<string, number>`
 
-#### migrationResult.conversionFailures · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L56)
+#### migrationResult.conversionFailures · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L59)
 
 Per-table conversion failure counts by reason.
 
 **Type:** `Record<string, Record<string, number>>`
 
-#### migrationResult.orphaned · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L57)
-
-Number of orphaned index entries deleted.
-
-**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
+#### migrationResult.rewritten · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L64)
 
-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.
+Per-table counts of rows rewritten to latest version.
 
-```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](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L68)
 
-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 }
-```