edinburgh 0.4.1 → 0.4.4

package/README.md

@@ -70,7 +70,9 @@ await E.transact(() => {
 });    
 ```
 
-## TypeScript Configuration
+## Tutorial
+
+### TypeScript Configuration
 
 When using TypeScript to transpile to JavaScript, make sure to enable the following options in your `tsconfig.json`:
 
@@ -83,15 +85,385 @@ When using TypeScript to transpile to JavaScript, make sure to enable the follow
 }
 ```
 
-## Logging
+### Defining Models
+
+Models are classes that extend `E.Model<Self>` and use the `@E.registerModel` decorator:
+
+```typescript
+import * as E from "edinburgh";
+
+@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);
+  age = E.field(E.number);
+}
+```
+
+Instance fields are declared with `E.field(type, options?)`. Available types:
+
+| Type | TypeScript type | Notes |
+|------|----------------|-------|
+| `E.string` | `string` | |
+| `E.orderedString` | `string` | Lexicographic sort in indexes; no null bytes |
+| `E.number` | `number` | |
+| `E.boolean` | `boolean` | |
+| `E.dateTime` | `Date` | Defaults to `new Date()` |
+| `E.identifier` | `string` | Auto-generated 8-char unique ID |
+| `E.opt(T)` | `T \| undefined` | Makes any type optional |
+| `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
+
+```typescript
+@E.registerModel
+class Post extends E.Model<Post> {
+  static pk = E.primary(Post, "id");
+
+  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()
+}
+```
+
+### Transactions
+
+All database operations must run inside `E.transact()`:
+
+```typescript
+// Initialize (optional — defaults to ".edinburgh" directory)
+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
+});
+
+// Read + Update
+await E.transact(() => {
+  const user = User.byEmail.get("alice@example.com");
+  if (user) user.age++;
+});
+
+// Return values from transactions
+const name = await E.transact(() => {
+  const user = User.byEmail.get("alice@example.com");
+  return user?.name;
+});
+```
+
+Transactions auto-retry on conflict (up to 6 times by default). Keep transaction functions idempotent.
+
+### Indexes
+
+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
+
+  sku = E.field(E.string);
+  name = E.field(E.string);
+  category = E.field(E.string);
+  price = E.field(E.number);
+}
+```
+
+If no `E.primary()` is declared, Edinburgh auto-creates one on an `id` field (adding `E.identifier` if missing).
+
+#### Lookups
+
+```typescript
+await E.transact(() => {
+  // Primary key lookup
+  const p = Product.pk.get("SKU-001");
+
+  // Unique index lookup
+  const p2 = Product.byName.get("Widget");
+
+  // All return undefined if not found
+});
+```
+
+#### Range Queries
+
+All index types support `.find()` for range iteration:
+
+```typescript
+await E.transact(() => {
+  // Exact match
+  for (const p of Product.byCategory.find({is: "electronics"})) {
+    console.log(p.name);
+  }
+
+  // Range (inclusive)
+  for (const p of Product.pk.find({from: "A", to: "M"})) {
+    console.log(p.sku);
+  }
+
+  // Exclusive bounds
+  for (const p of Product.pk.find({after: "A", before: "M"})) { ... }
+
+  // Open-ended
+  for (const p of Product.pk.find({from: "M"})) { ... }
+
+  // Reverse
+  for (const p of Product.pk.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
+});
+```
+
+#### Composite Indexes
+
+```typescript
+@E.registerModel
+class Event extends E.Model<Event> {
+  static pk = E.primary(Event, ["year", "month", "id"]);
+
+  year = E.field(E.number);
+  month = E.field(E.number);
+  id = E.field(E.identifier);
+  title = E.field(E.string);
+}
+
+await E.transact(() => {
+  // Prefix matching — find all events in 2025
+  for (const e of Event.pk.find({is: [2025]})) { ... }
+
+  // Find events in March 2025
+  for (const e of Event.pk.find({is: [2025, 3]})) { ... }
+});
+```
+
+#### 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.
 
-You can enable debug logging to stdout by setting the `EDINBURGH_LOG_LEVEL` environment variable to a number from 0 to 3. Higher numbers produce more verbose logs, including model-level operations, updates, and reads.
+```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:
+
+```typescript
+@E.registerModel
+class Author extends E.Model<Author> {
+  static pk = E.primary(Author, "id");
+  id = E.field(E.identifier);
+  name = E.field(E.string);
+}
+
+@E.registerModel
+class Book extends E.Model<Book> {
+  static pk = E.primary(Book, "id");
+  id = E.field(E.identifier);
+  title = E.field(E.string);
+  author = E.field(E.link(Author));
+}
+
+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)!;
+  console.log(b.author.name);  // loads Author automatically (~1µs)
+});
+```
+
+### Deleting
+
+```typescript
+await E.transact(() => {
+  const user = User.pk.get(someId);
+  if (user) user.delete();
+});
+```
+
+### Model Utilities
+
+```typescript
+await E.transact(() => {
+  const user = new User({name: "Bob", email: "bob@example.com", age: 25});
+
+  user.validate();     // returns Error[]
+  user.isValid();      // returns boolean
+  user.getState();     // "created" | "loaded" | "lazy" | "deleted"
+  user.getPrimaryKey(); // Uint8Array
+  user.preventPersist(); // exclude from commit
+});
+
+// findAll iterates all instances
+await E.transact(() => {
+  for (const user of User.findAll()) { ... }
+  for (const user of User.findAll({reverse: true})) { ... }
+});
+
+// replaceInto: upsert by primary key
+await E.transact(() => {
+  User.replaceInto({id: existingId, name: "Updated Name", email: "new@example.com", age: 30});
+});
+```
+
+### Batch Processing
+
+For large datasets, `batchProcess` auto-commits in batches:
+
+```typescript
+await Product.byCategory.batchProcess({is: "old"}, (product) => {
+  product.category = "archived";
+});
+// Commits every ~1 second or 4096 rows (configurable via limitSeconds, limitRows)
+```
+
+### Schema Evolution
+
+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`.
+
+```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, {default: "user"});  // new field
+
+  static migrate(record: Record<string, any>) {
+    record.role ??= "user";  // provide value for old rows
+  }
+}
+```
+
+Run `npx migrate-edinburgh` (or call `E.runMigration()`) after adding/removing indexes, changing index field types, or when a `migrate()` function affects indexed fields.
+
+### preCommit Hook
+
+Compute derived fields before data is written:
+
+```typescript
+@E.registerModel
+class Article extends E.Model<Article> {
+  static pk = E.primary(Article, "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, "-");
+  }
+}
+```
+
+### Change Tracking
+
+Monitor commits with `setOnSaveCallback`:
+
+```typescript
+E.setOnSaveCallback((commitId, items) => {
+  for (const [instance, change] of items) {
+    if (change === "created") { /* new record */ }
+    else if (change === "deleted") { /* removed */ }
+    else { /* change is an object with old values of modified fields */ }
+  }
+});
+```
+
+### Logging
+
+Enable debug logging by setting the `EDINBURGH_LOG_LEVEL` environment variable (0–3). Higher numbers produce more verbose logs.
 
 - 0: no logging (default)
 - 1: model-level logs
 - 2: + update logs
 - 3: + read logs
 
+### AI Integration
+
+If you use Claude Code, GitHub Copilot or another AI agent that supports Skills, Edinburgh includes a `skill/` directory in its npm package that provides specialized knowledge to the AI about how to use the library effectively.
+
+Symlink the skill into your project's `.claude/skills` directory:
+
+```bash
+mkdir -p .claude/skills
+ln -s ../../node_modules/edinburgh/skill .claude/skills/edinburgh
+```
+
 ## API Reference
 
 The following is auto-generated from `src/edinburgh.ts`:
@@ -100,7 +472,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(),
@@ -118,7 +490,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.
 
@@ -168,7 +540,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.
@@ -179,7 +551,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.
 
@@ -192,11 +564,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]
 
@@ -219,25 +591,25 @@ class User extends E.Model<User> {
 }
 ```
 
-#### Model.tableName · [static property](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L226)
+#### 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#L230)
+#### 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#L231)
+#### 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
@@ -272,7 +644,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.
 
@@ -285,7 +657,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.
 
@@ -302,7 +674,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.
@@ -334,7 +706,7 @@ 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>`
 
@@ -343,7 +715,7 @@ class Post extends E.Model<Post> {
 
 **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`
 
@@ -352,7 +724,7 @@ class Post extends E.Model<Post> {
 
 **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`
 
@@ -360,7 +732,7 @@ 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.
 
@@ -379,7 +751,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.
 
@@ -397,7 +769,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.
 
@@ -419,7 +791,7 @@ 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.
 
@@ -437,28 +809,28 @@ 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.
 
@@ -485,7 +857,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.
 
@@ -515,13 +887,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
@@ -531,37 +903,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).
 
@@ -584,7 +956,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.
 
@@ -607,7 +979,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.
 
@@ -631,7 +1003,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.
 
@@ -654,7 +1072,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.
 
@@ -682,21 +1100,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.
 
@@ -706,10 +1129,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.
 
@@ -736,21 +1160,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, or a computed unique index using a function.
 
-Create a unique index on model fields.
+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, 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<...>; }`
+**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.
 
@@ -760,10 +1189,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.
 
@@ -772,7 +1202,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#L128)
+### 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.
 
@@ -782,39 +1212,40 @@ 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.
 
@@ -822,16 +1253,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.
 
@@ -841,7 +1273,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.
 
@@ -850,7 +1282,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.
 
@@ -868,7 +1300,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
@@ -882,7 +1314,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.
 
@@ -890,8 +1322,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"`
 
@@ -905,11 +1338,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.
@@ -919,7 +1352,7 @@ 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#L118)
 
 Run database migration: upgrade all rows to the latest schema version,
 convert old primary indices, and clean up orphaned secondary indices.
@@ -938,51 +1371,51 @@ Limit migration to specific table names.
 
 **Type:** `string[]`
 
-#### migrationOptions.convertOldPrimaries · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L22)
+#### migrationOptions.convertOldPrimaries · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L23)
 
 Whether to convert old primary indices for known tables (default: true).
 
 **Type:** `boolean`
 
-#### migrationOptions.deleteOrphanedIndexes · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L30)
+#### migrationOptions.deleteOrphanedIndexes · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L31)
 
 Whether to delete orphaned secondary/unique indices (default: true).
 
 **Type:** `boolean`
 
-#### migrationOptions.upgradeVersions · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L38)
+#### migrationOptions.upgradeVersions · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L39)
 
 Whether to upgrade rows to the latest version (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#L44)
 
 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#L49)
 
-#### 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#L51)
 
 Per-table stats for row upgrades.
 
 **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#L52)
 
 Per-table stats for old primary conversions.
 
 **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#L58)
 
 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)
+#### migrationResult.orphaned · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L59)
 
 Number of orphaned index entries deleted.