edinburgh 0.5.0 → 0.6.0

package/skill/SKILL.md

@@ -26,7 +26,7 @@ import * as E from "edinburgh";
 // Initialize the database (optional, defaults to ".edinburgh")
 E.init("./my-database");
 
-const User = E.defineModel(class {
+const User = E.defineModel("User", class {
     id = E.field(E.identifier);
     name = E.field(E.string);
     age = E.field(E.number);
@@ -46,9 +46,8 @@ const User = E.defineModel(class {
 }, {
     pk: "id",
     unique: {
-        byEmail: "email",
+        email: "email",
     },
-    tableName: "User",
 });
 
 await E.transact(() => {
@@ -65,7 +64,7 @@ await E.transact(() => {
 
 await E.transact(() => {
     // Query by unique index
-    const john = User.byEmail.get("john@example.com")!;
+  const john = User.getBy("email", "john@example.com")!;
 
     // The transaction will retry if there's a conflict, such as another transaction
     // modifying the same user (from another async function or another process)
@@ -81,12 +80,15 @@ await E.transact(() => {
 
 ### Defining Models
 
-Models are plain, usually anonymous, classes passed to `E.defineModel()`:
+A model is defined using the `E.defineModel()` function by passing it..
+- a consistent table name,
+- an (anonymous) class containing `E.field` database properties and optionally regular properties/methods, and
+- optional key/index configuration.
 
 ```typescript
 import * as E from "edinburgh";
 
-const User = E.defineModel(class {
+const User = E.defineModel("User", class {
   id = E.field(E.identifier);
   name = E.field(E.string);
   email = E.field(E.string);
@@ -94,9 +96,12 @@ const User = E.defineModel(class {
 }, {
   pk: "id",
   unique: {
-    byEmail: "email",
+    email: "email",
   },
 });
+// Add this if you want to use User as a type annotation (e.g. `let u: User`).
+// Not needed just to call User.get(), User.find(), new User(), etc.
+type User = InstanceType<typeof User>;
 ```
 
 Instance fields are declared with `E.field(type, options?)`. Available types:
@@ -120,7 +125,7 @@ Instance fields are declared with `E.field(type, options?)`. Available types:
 #### Defaults
 
 ```typescript
-const Post = E.defineModel(class {
+const Post = E.defineModel("Post", class {
   id = E.field(E.identifier); // auto-generated
   title = E.field(E.string);
   status = E.field(E.or("draft", "published"), {default: "draft"});
@@ -145,13 +150,13 @@ await E.transact(() => {
 
 // Read + Update
 await E.transact(() => {
-  const user = User.byEmail.get("alice@example.com");
+  const user = User.getBy("email", "alice@example.com");
   if (user) user.age++;
 });
 
 // Return values from transactions
 const name = await E.transact(() => {
-  const user = User.byEmail.get("alice@example.com");
+  const user = User.getBy("email", "alice@example.com");
   return user?.name;
 });
 ```
@@ -163,15 +168,15 @@ Transactions auto-retry on conflict (up to 6 times by default). Keep transaction
 Edinburgh supports three index types:
 
 ```typescript
-const Product = E.defineModel(class {
+const Product = E.defineModel("Product", class {
   sku = E.field(E.string);
   name = E.field(E.string);
   category = E.field(E.string);
   price = E.field(E.number);
 }, {
   pk: "sku",
-  unique: { byName: "name" },
-  index: { byCategory: "category" },
+  unique: { name: "name" },
+  index: { category: "category" },
 });
 ```
 
@@ -185,7 +190,7 @@ await E.transact(() => {
   const p1 = Product.get("SKU-001");
 
   // Unique index lookup
-  const p2 = Product.byName.get("Widget");
+  const p2 = Product.getBy("name", "Widget");
 
   // All return undefined if not found
 });
@@ -193,12 +198,12 @@ await E.transact(() => {
 
 #### Range Queries
 
-All index types support `.find()` for range iteration:
+Primary-key queries use `.find()`. Named unique and secondary indexes use `.findBy(name, ...)`:
 
 ```typescript
 await E.transact(() => {
   // Exact match
-  for (const p of Product.byCategory.find({is: "electronics"})) {
+  for (const p of Product.findBy("category", {is: "electronics"})) {
     console.log(p.name);
   }
 
@@ -217,15 +222,15 @@ await E.transact(() => {
   for (const p of Product.find({reverse: true})) { ... }
 
   // Count and fetch helpers
-  const count = Product.byCategory.find({is: "electronics"}).count();
-  const first = Product.byCategory.find({is: "electronics"}).fetch(); // first match or undefined
+  const count = Product.findBy("category", {is: "electronics"}).count();
+  const first = Product.findBy("category", {is: "electronics"}).fetch(); // first match or undefined
 });
 ```
 
 #### Composite Primary Keys
 
 ```typescript
-const Event = E.defineModel(class {
+const Event = E.defineModel("Event", class {
   year = E.field(E.number);
   month = E.field(E.number);
   id = E.field(E.identifier);
@@ -248,7 +253,7 @@ await E.transact(() => {
 You can freely add regular methods, getters, and other non-persistent properties to model classes. These work normally in JavaScript but are **not stored in the database** and **not synchronized** across transactions or processes.
 
 ```typescript
-const User = E.defineModel(class {
+const User = E.defineModel("User", class {
   firstName = E.field(E.string);
   lastName = E.field(E.string);
 
@@ -271,7 +276,7 @@ const User = E.defineModel(class {
 Instead of naming fields, you can pass a function as an index specification. The function receives a model instance and returns an **array** of index key values. Each element creates a separate index entry, enabling multi-value indexes. Return `[]` to skip indexing for that instance (partial index).
 
 ```typescript
-const Article = E.defineModel(class {
+const Article = E.defineModel("Article", class {
   id = E.field(E.identifier);
   firstName = E.field(E.string);
   lastName = E.field(E.string);
@@ -280,11 +285,11 @@ const Article = E.defineModel(class {
 }, {
   pk: "id",
   unique: {
-    byFullName: (a: any) => [`${a.firstName} ${a.lastName}`], // computed covering unique index
+    fullName: (a: any) => [`${a.firstName} ${a.lastName}`], // computed covering unique index
   },
   index: {
-    byDomain: (a: any) => a.email ? [a.email.split("@")[1]] : [], // computed partial index
-    byWord: (a: any) => a.title.toLowerCase().split(" "), // computed multi-index
+    domain: (a: any) => a.email ? [a.email.split("@")[1]] : [], // computed partial index
+    word: (a: any) => a.title.toLowerCase().split(" "), // computed multi-index
   },
 });
 
@@ -292,13 +297,13 @@ await E.transact(() => {
   new Article({ firstName: "Jane", lastName: "Doe", title: "Hello World", email: "jane@acme.com" });
 
   // Lookup via computed unique index
-  const jane = Article.byFullName.get("Jane Doe");
+  const jane = Article.getBy("fullName", "Jane Doe");
 
   // Multi-value: each word in the title is indexed separately
-  for (const a of Article.byWord.find({is: "hello"})) { ... }
+  for (const a of Article.findBy("word", {is: "hello"})) { ... }
 
   // Partial index: articles without email are skipped
-  for (const a of Article.byDomain.find({is: "acme.com"})) { ... }
+  for (const a of Article.findBy("domain", {is: "acme.com"})) { ... }
 });
 ```
 
@@ -307,12 +312,12 @@ await E.transact(() => {
 Use `E.link(Model)` for foreign keys. Use a thunk (a function that just returns a value) for forward references when needed:
 
 ```typescript
-const Author = E.defineModel(class {
+const Author = E.defineModel("Author", class {
   id = E.field(E.identifier);
   name = E.field(E.string);
 }, { pk: "id" });
 
-const Book = E.defineModel(class {
+const Book = E.defineModel("Book", class {
   id = E.field(E.identifier);
   title = E.field(E.string);
   author = E.field(E.link(Author));
@@ -385,7 +390,7 @@ await Product.batchProcess({ limitRows: 1000 }, (product) => {
 When you change a model's schema, Edinburgh lazily migrates old records on access. You can provide a `static migrate(record)` function to transform old rows:
 
 ```typescript
-const UserV2 = E.defineModel(class {
+const UserV2 = E.defineModel("User", class {
   id = E.field(E.identifier);
   name = E.field(E.string);
   role = E.field(E.string);  // newly added field
@@ -393,7 +398,7 @@ const UserV2 = E.defineModel(class {
   static migrate(record: Record<string, any>) {
     record.role ??= record.name.indexOf("admin") >= 0 ? "admin" : "user"; // set role based on name for old records
   }
-}
+})
 ```
 
 Edinburgh will lazily (re)run the `migrate` function on an instance whenever its implementation (the literal function code) has changed. For robustness, make sure that your `migrate` function...
@@ -428,7 +433,7 @@ console.log(result.secondaries);  // { User: 1500 }
 Compute derived fields before data is written:
 
 ```typescript
-const Article = E.defineModel(class {
+const Article = E.defineModel("Article", class {
   id = E.field(E.identifier);
   title = E.field(E.string);
   slug = E.field(E.string);
@@ -436,7 +441,7 @@ const Article = E.defineModel(class {
   preCommit() {
     this.slug = this.title.toLowerCase().replace(/\s+/g, "-");
   }
-}, { pk: "id" });
+});
 ```
 
 ### Change Tracking
@@ -477,9 +482,12 @@ ln -s ../../node_modules/edinburgh/skill .claude/skills/edinburgh
 
 The following is auto-generated from `src/edinburgh.ts`:
 
-### scheduleInit · function
+### currentTxn · function
 
-**Signature:** `() => void`
+Returns the current transaction from AsyncLocalStorage.
+Throws if called outside a transact() callback.
+
+**Signature:** `() => Transaction`
 
 ### [init](init.md) · function
 
@@ -500,82 +508,53 @@ The default value is 6. Setting it to 0 will disable retries and cause transacti
 
 Set a callback function to be called after a model is saved and committed.
 
-### deleteEverything · function
-
-**Signature:** `() => Promise<void>`
+### Model · class
 
-### [Model](Model.md) · abstract class
+**Type:** `typeof ModelBase`
 
-[object Object],[object Object],[object Object],[object Object],[object Object]
+### [ModelClass](ModelClass.md) · class
 
-#### Model.tableName · static property
+Runtime base constructor for model classes returned by `defineModel()`.
 
-The database table name (defaults to class name).
+### [AnyModelClass](AnyModelClass.md) · type
 
-**Type:** `string`
+A model constructor with its generic information erased.
 
-#### Model.override · static property
+### [ModelBase](ModelBase.md) · abstract class
 
-When true, defineModel replaces an existing model with the same tableName.
+Base class for all database models in the Edinburgh ORM.
 
-**Type:** `boolean`
+### [Schema Evolution](Schema Evolution.md)
 
-#### Model.fields · static property
+Edinburgh tracks the schema version of each model automatically. When you add, remove, or
+change the types of fields, or add/remove indexes, Edinburgh detects the new schema version.
 
-Field configuration metadata.
+### [Lifecycle Hooks](Lifecycle Hooks.md)
 
-**Type:** `Record<string | number | symbol, FieldConfig<unknown>>`
+- **`static migrate(record)`**: Called when deserializing rows written with an older schema
+  version. Receives a plain record object; mutate it in-place to match the current schema.
 
-#### [Model.migrate](Model_migrate.md) · static method
+#### [ModelBase.migrate](Lifecycle Hooks_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.
-
-#### Model.get · static method
+Receives a plain record with all fields and should mutate it in-place to match the current schema.
+It runs during lazy loading and during `runMigration()`. Changing this method creates a new schema version.
+If it updates values used by secondary or unique indexes, those index entries are refreshed only by `runMigration()`.
 
-**Signature:** `(...args: any[]) => any`
-
-**Parameters:**
-
-- `args: any[]`
-
-#### Model.getLazy · static method
-
-**Signature:** `(...args: any[]) => any`
-
-**Parameters:**
-
-- `args: any[]`
-
-#### Model.find · static method
-
-**Signature:** `(opts?: any) => any`
-
-**Parameters:**
-
-- `opts?: any`
-
-#### [Model.batchProcess](Model_batchProcess.md) · static method
-
-#### [Model.replaceInto](Model_replaceInto.md) · static method
-
-Load an existing instance by primary key and update it, or create a new one.
-
-#### [model.preCommit](Model_preCommit.md) · method
+#### [modelBase.preCommit](Lifecycle Hooks_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.
 
-#### model.getPrimaryKey · method
+#### modelBase.getPrimaryKey · method
 
 **Signature:** `() => Uint8Array<ArrayBufferLike>`
 
 **Returns:** The primary key for this instance.
 
-#### [model.getPrimaryKeyHash](Model_getPrimaryKeyHash.md) · method
+#### [modelBase.getPrimaryKeyHash](Lifecycle Hooks_getPrimaryKeyHash.md) · method
 
-#### model.isLazyField · method
+#### modelBase.isLazyField · method
 
 **Signature:** `(field: keyof this) => boolean`
 
@@ -583,31 +562,31 @@ Runs before data is written to disk, so changes made here are included in the co
 
 - `field: keyof this`
 
-#### [model.preventPersist](Model_preventPersist.md) · method
+#### [modelBase.preventPersist](Lifecycle Hooks_preventPersist.md) · method
 
 Prevent this instance from being persisted to the database.
 
-#### [model.delete](Model_delete.md) · method
+#### [modelBase.delete](Lifecycle Hooks_delete.md) · method
 
 Delete this model instance from the database.
 
-#### [model.validate](Model_validate.md) · method
+#### [modelBase.validate](Lifecycle Hooks_validate.md) · method
 
 Validate all fields in this model instance.
 
-#### [model.isValid](Model_isValid.md) · method
+#### [modelBase.isValid](Lifecycle Hooks_isValid.md) · method
 
 Check if this model instance is valid.
 
-#### model.getState · method
+#### modelBase.getState · method
 
 **Signature:** `() => "created" | "deleted" | "loaded" | "lazy"`
 
-#### model.toString · method
+#### modelBase.toString · method
 
 **Signature:** `() => string`
 
-#### model.[Symbol.for('nodejs.util.inspect.custom')] · method
+#### modelBase.[Symbol.for('nodejs.util.inspect.custom')] · method
 
 **Signature:** `() => string`
 
@@ -615,16 +594,13 @@ Check if this model instance is valid.
 
 Register a model class with the Edinburgh ORM system.
 
-### [field](field.md) · function
-
-Create a field definition for a model property.
+### [deleteEverything](deleteEverything.md) · function
 
-### currentTxn · function
+Delete every key/value entry in the database and reinitialize all registered models.
 
-Returns the current transaction from AsyncLocalStorage.
-Throws if called outside a transact() callback.
+### [field](field.md) · function
 
-**Signature:** `() => Transaction`
+Create a field definition for a model property.
 
 ### string · constant
 
@@ -700,68 +676,126 @@ Create a literal type wrapper for a constant value.
 
 Create a link type wrapper for model relationships.
 
-### [dump](dump.md) · function
+### dump · function
 
-Dump database contents for debugging.
+**Signature:** `() => void`
 
-### [BaseIndex](BaseIndex.md) · abstract class
+### [FindOptions](FindOptions.md) · type
 
-Base class for database indexes for efficient lookups on model fields.
+Range-query options accepted by `find()`, `findBy()`, `batchProcess()`, and `batchProcessBy()`.
 
-#### [baseIndex.find](BaseIndex_find.md) · method
+### IndexRangeIterator · class
 
-#### [baseIndex.find](BaseIndex_find_2.md) · method
+Iterator for range queries on indexes.
+Handles common iteration logic for both primary and unique indexes.
+Extends built-in Iterator to provide map/filter/reduce/toArray/etc.
 
-#### [baseIndex.find](BaseIndex_find_3.md) · method
+**Type Parameters:**
 
-#### [baseIndex.find](BaseIndex_find_4.md) · method
+- `ITEM`
 
-#### [baseIndex.batchProcess](BaseIndex_batchProcess.md) · method
+#### indexRangeIterator.[Symbol.iterator] · method
 
-[object Object],[object Object],[object Object]
+**Signature:** `() => this`
 
-#### baseIndex.toString · method
+#### indexRangeIterator.next · method
 
-**Signature:** `() => string`
+**Signature:** `() => IteratorResult<ITEM, any>`
 
-### [NonPrimaryIndex](NonPrimaryIndex.md) · abstract class
+#### indexRangeIterator.count · method
 
-Abstract base for all non-primary indexes (unique and secondary).
-Provides shared key serialization, write/delete/update logic.
+**Signature:** `() => number`
 
-### [UniqueIndex](UniqueIndex.md) · class
+#### indexRangeIterator.fetch · method
 
-Unique index that stores references to the primary key.
+**Signature:** `() => ITEM`
 
-#### uniqueIndex.get · method
+### Change · type
 
-**Signature:** `(...args: ARGS) => InstanceType<M>`
+**Type:** `Record<any, any> | "created" | "deleted"`
 
-**Parameters:**
+### FieldConfig · interface
 
-- `args: ARGS`
+Configuration interface for model fields.
 
-### [SecondaryIndex](SecondaryIndex.md) · class
+**Type Parameters:**
 
-Secondary index for non-unique lookups.
+- `T` - The field type.
 
-### Change · type
+#### fieldConfig.type · member
 
-**Type:** `Record<any, any> | "created" | "deleted"`
+The type wrapper that defines how this field is serialized/validated.
 
-### Transaction · interface
+**Type:** `TypeWrapper<T>`
 
-#### transaction.id · member
+#### fieldConfig.description · member
 
-**Type:** `number`
+Optional human-readable description of the field.
 
-#### transaction.instances · member
+**Type:** `string`
+
+#### fieldConfig.default · member
+
+Optional default value or function that generates default values.
+
+**Type:** `T | ((model: Record<string, any>) => T)`
+
+### TypeWrapper · abstract class
+
+**Type Parameters:**
+
+- `T` - The TypeScript type this wrapper represents.
+
+#### typeWrapper.kind · abstract property
+
+A string identifier for this type, used during serialization
+
+**Type:** `string`
+
+#### [typeWrapper.serialize](TypeWrapper_serialize.md) · abstract method
+
+Serialize a value from an object property to a Pack.
+
+#### [typeWrapper.deserialize](TypeWrapper_deserialize.md) · abstract method
+
+Deserialize a value from a Pack into an object property.
+
+#### [typeWrapper.getError](TypeWrapper_getError.md) · abstract method
+
+Validate a value.
+
+#### [typeWrapper.serializeType](TypeWrapper_serializeType.md) · method
+
+Serialize type metadata to a Pack (for schema serialization).
+
+#### [typeWrapper.containsNull](TypeWrapper_containsNull.md) · method
+
+Check if indexing should be skipped for this field value.
 
-**Type:** `Set<Model<unknown>>`
+#### typeWrapper.toString · method
 
-#### transaction.instancesByPk · member
+**Signature:** `() => string`
+
+#### typeWrapper.clone · method
+
+**Signature:** `(value: T) => T`
+
+**Parameters:**
+
+- `value: T`
+
+#### typeWrapper.equals · method
+
+**Signature:** `(value1: T, value2: T) => boolean`
+
+**Parameters:**
+
+- `value1: T`
+- `value2: T`
+
+#### typeWrapper.getLinkedModel · method
 
-**Type:** `Map<number, Model<unknown>>`
+**Signature:** `() => AnyModelClass`
 
 ### [DatabaseError](DatabaseError.md) · constant
 
@@ -843,3 +877,17 @@ Number of orphaned index entries deleted.
 
 **Type:** `number`
 
+### Transaction · interface
+
+#### transaction.id · member
+
+**Type:** `number`
+
+#### transaction.instances · member
+
+**Type:** `Map<number, ModelBase>`
+
+### txnStorage · constant
+
+**Value:** `AsyncLocalStorage<Transaction>`
+

package/skill/Schema Evolution.md

@@ -0,0 +1,19 @@
+### Schema Evolution
+
+Edinburgh tracks the schema version of each model automatically. When you add, remove, or
+change the types of fields, or add/remove indexes, Edinburgh detects the new schema version.
+
+**Lazy migration:** Changes to non-key field values are migrated lazily, when a row with an
+old schema version is read from disk, it is deserialized using the old schema and optionally
+transformed by the static `migrate()` function. This happens transparently on every read
+and requires no downtime or batch processing.
+
+**Batch migration (via `npx migrate-edinburgh` or `runMigration()`):** Certain schema changes
+require an explicit migration run:
+- Adding or removing secondary/unique indexes
+- Changing the fields or types of an existing index
+- A `migrate()` function that changes values used in secondary index fields
+
+The batch migration tool populates new indexes, deletes orphaned ones, and updates index
+entries whose values were changed by `migrate()`. It does *not* rewrite primary data rows
+(lazy migration handles that).

package/skill/TypeWrapper_containsNull.md

@@ -0,0 +1,11 @@
+#### typeWrapper.containsNull · method
+
+Check if indexing should be skipped for this field value.
+
+**Signature:** `(value: T) => boolean`
+
+**Parameters:**
+
+- `value: T`
+
+**Returns:** true if indexing should be skipped.

package/skill/TypeWrapper_deserialize.md

@@ -0,0 +1,9 @@
+#### typeWrapper.deserialize · abstract method
+
+Deserialize a value from a Pack into an object property.
+
+**Signature:** `(pack: DataPack) => T`
+
+**Parameters:**
+
+- `pack: DataPack` - The Pack instance to read from.

package/skill/TypeWrapper_getError.md

@@ -0,0 +1,11 @@
+#### typeWrapper.getError · abstract method
+
+Validate a value.
+
+**Signature:** `(value: T) => void | DatabaseError`
+
+**Parameters:**
+
+- `value: T` - The value to validate.
+
+**Returns:** - A DatabaseError if validation fails.

package/skill/TypeWrapper_serialize.md

@@ -0,0 +1,10 @@
+#### typeWrapper.serialize · abstract method
+
+Serialize a value from an object property to a Pack.
+
+**Signature:** `(value: T, pack: DataPack) => void`
+
+**Parameters:**
+
+- `value: T` - The value to serialize.
+- `pack: DataPack` - The Pack instance to write to.

package/skill/TypeWrapper_serializeType.md

@@ -0,0 +1,9 @@
+#### typeWrapper.serializeType · method
+
+Serialize type metadata to a Pack (for schema serialization).
+
+**Signature:** `(pack: DataPack) => void`
+
+**Parameters:**
+
+- `pack: DataPack` - The Pack instance to write to.