edinburgh 0.4.5 → 0.5.0

package/skill/SKILL.md

@@ -26,39 +26,41 @@ import * as E from "edinburgh";
 // Initialize the database (optional, defaults to ".edinburgh")
 E.init("./my-database");
 
-// Define a model
-@E.registerModel
-class User extends E.Model<User> {
-    // Define a primary key (optional, defaults to using the "id" field)
-    static pk = E.primary(User, "id");
-    // Define a unique index on the email field
-    static byEmail = E.unique(User, "email");
-
-    // Define fields with simple types -- they will be type-checked at compile time and validated at runtime.
+const User = E.defineModel(class {
     id = E.field(E.identifier);
     name = E.field(E.string);
     age = E.field(E.number);
-    email = E.field(E.opt(E.string)); // TypeScript: undefined | string
-
-    // Link to another instance of this model
-    supervisor = E.field(E.opt(E.link(User)));
-
-    // A field with a more elaborate type. In TypeScript: `User | User[] | "unknown" | "whatever"`
-    something = E.field(E.or(E.link(User), E.array(E.link(User)), E.literal("unknown"), E.literal("whatever")), { default: "unknown" });
-}
+    email = E.field(E.opt(E.string));
+    // Optional link to another instance of this model (needs a function as `User` is not defined yet at this point)
+    supervisor = E.field(E.opt(E.link(() => User)));
+    // A field with a more elaborate type. In TypeScript: `User | User[] | "unknown" | "whatever"`, defaulting to "unknown".
+    something = E.field(
+        E.or(
+            E.link(() => User),
+            E.array(E.link(() => User)),
+            E.literal("unknown"),
+            E.literal("whatever")
+        ),
+        { default: "unknown" }
+    );
+}, {
+    pk: "id",
+    unique: {
+        byEmail: "email",
+    },
+    tableName: "User",
+});
 
-// Use in transactions
 await E.transact(() => {
-    const boss = new User({
-        name: "Big Boss",
-        age: 50,
-    });
-    const john = new User({ // Unique 'id' is automatically generated if not provided
-        name: "John Doe", 
+    // Unique 'id' values are auto-generated if not provided
+    const boss = new User({ name: "Big Boss", age: 50 });
+    new User({
+        name: "John Doe",
         age: 41,
         email: "john@example.com",
         supervisor: boss, // Link to another model instance
     });
+    // Newly instantiated models are automatically saved to the database on transaction commit
 });
 
 await E.transact(() => {
@@ -70,41 +72,31 @@ await E.transact(() => {
     john.age++;
 
     // The supervisor object is lazy loaded on first access
-    console.log(`${john.supervisor!.name} is ${john.name}'s supervisor`);  
+    console.log(`${john.supervisor!.name} is ${john.name}'s supervisor`);
 });    
 ```
 
 ## Tutorial
 
-### TypeScript Configuration
-
-When using TypeScript to transpile to JavaScript, make sure to enable the following options in your `tsconfig.json`:
-
-```json
-{
-    "compilerOptions": {
-        "target": "es2022",
-        "experimentalDecorators": true
-    }
-}
-```
 
 ### Defining Models
 
-Models are classes that extend `E.Model<Self>` and use the `@E.registerModel` decorator:
+Models are plain, usually anonymous, classes passed to `E.defineModel()`:
 
 ```typescript
 import * as E from "edinburgh";
 
-@E.registerModel
-class User extends E.Model<User> {
-  static pk = E.primary(User, "id");
-
+const User = E.defineModel(class {
   id = E.field(E.identifier);
   name = E.field(E.string);
   email = E.field(E.string);
   age = E.field(E.number);
-}
+}, {
+  pk: "id",
+  unique: {
+    byEmail: "email",
+  },
+});
 ```
 
 Instance fields are declared with `E.field(type, options?)`. Available types:
@@ -128,16 +120,13 @@ Instance fields are declared with `E.field(type, options?)`. Available types:
 #### Defaults
 
 ```typescript
-@E.registerModel
-class Post extends E.Model<Post> {
-  static pk = E.primary(Post, "id");
-
-  id = E.field(E.identifier);  // auto-generated
+const Post = E.defineModel(class {
+  id = E.field(E.identifier); // auto-generated
   title = E.field(E.string);
   status = E.field(E.or("draft", "published"), {default: "draft"});
-  tags = E.field(E.array(E.string), {default: () => []});  // use function for mutable defaults
-  createdAt = E.field(E.dateTime);  // dateTime defaults to new Date()
-}
+  tags = E.field(E.array(E.string), {default: () => []}); // use function for mutable defaults
+  createdAt = E.field(E.dateTime); // dateTime defaults to new Date()
+}, { pk: "id" });
 ```
 
 ### Transactions
@@ -150,8 +139,8 @@ E.init("./my-database");
 
 // Create
 await E.transact(() => {
-  const user = new User({name: "Alice", email: "alice@example.com", age: 30});
-  // user.id is auto-generated
+  // User.id is auto-generated
+  new User({name: "Alice", email: "alice@example.com", age: 30});
 });
 
 // Read + Update
@@ -174,27 +163,26 @@ Transactions auto-retry on conflict (up to 6 times by default). Keep transaction
 Edinburgh supports three index types:
 
 ```typescript
-@E.registerModel
-class Product extends E.Model<Product> {
-  static pk = E.primary(Product, "sku");           // primary: one per model, stores data
-  static byName = E.unique(Product, "name");       // unique: enforces uniqueness + fast lookup
-  static byCategory = E.index(Product, "category");// secondary: non-unique, for queries
-
+const Product = E.defineModel(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" },
+});
 ```
 
-If no `E.primary()` is declared, Edinburgh auto-creates one on an `id` field (adding `E.identifier` if missing).
+If no `pk` is provided, Edinburgh auto-creates one on an `id` field, adding it as an `E.identifier` field if needed.
 
 #### Lookups
 
 ```typescript
 await E.transact(() => {
   // Primary key lookup
-  const p = Product.pk.get("SKU-001");
+  const p1 = Product.get("SKU-001");
 
   // Unique index lookup
   const p2 = Product.byName.get("Widget");
@@ -215,18 +203,18 @@ await E.transact(() => {
   }
 
   // Range (inclusive)
-  for (const p of Product.pk.find({from: "A", to: "M"})) {
+  for (const p of Product.find({from: "A", to: "M"})) {
     console.log(p.sku);
   }
 
   // Exclusive bounds
-  for (const p of Product.pk.find({after: "A", before: "M"})) { ... }
+  for (const p of Product.find({after: "A", before: "M"})) { ... }
 
   // Open-ended
-  for (const p of Product.pk.find({from: "M"})) { ... }
+  for (const p of Product.find({from: "M"})) { ... }
 
   // Reverse
-  for (const p of Product.pk.find({reverse: true})) { ... }
+  for (const p of Product.find({reverse: true})) { ... }
 
   // Count and fetch helpers
   const count = Product.byCategory.find({is: "electronics"}).count();
@@ -234,25 +222,24 @@ await E.transact(() => {
 });
 ```
 
-#### Composite Indexes
+#### Composite Primary Keys
 
 ```typescript
-@E.registerModel
-class Event extends E.Model<Event> {
-  static pk = E.primary(Event, ["year", "month", "id"]);
-
+const Event = E.defineModel(class {
   year = E.field(E.number);
   month = E.field(E.number);
   id = E.field(E.identifier);
   title = E.field(E.string);
-}
+}, {
+  pk: ["year", "month", "id"] as const,
+});
 
 await E.transact(() => {
   // Prefix matching — find all events in 2025
-  for (const e of Event.pk.find({is: [2025]})) { ... }
+  for (const e of Event.find({is: [2025]})) { ... }
 
   // Find events in March 2025
-  for (const e of Event.pk.find({is: [2025, 3]})) { ... }
+  for (const e of Event.find({is: [2025, 3]})) { ... }
 });
 ```
 
@@ -261,10 +248,7 @@ await E.transact(() => {
 You can freely add regular methods, getters, and other non-persistent properties to model classes. These work normally in JavaScript but are **not stored in the database** and **not synchronized** across transactions or processes.
 
 ```typescript
-@E.registerModel
-class User extends E.Model<User> {
-  static pk = E.primary(User, "id");
-  id = E.field(E.identifier);
+const User = E.defineModel(class {
   firstName = E.field(E.string);
   lastName = E.field(E.string);
 
@@ -279,27 +263,30 @@ class User extends E.Model<User> {
   greet(): string {
     return `Hello, ${this.fullName}!`;
   }
-}
+});
 ```
 
 #### Computed Indexes
 
-Instead of naming fields, you can pass a **function** to `E.unique()` or `E.index()`. The function receives a model instance and returns an **array** of index key values. Each element creates a separate index entry, enabling multi-value indexes. Return `[]` to skip indexing for that instance (partial index).
+Instead of naming fields, you can pass a function as an index specification. The function receives a model instance and returns an **array** of index key values. Each element creates a separate index entry, enabling multi-value indexes. Return `[]` to skip indexing for that instance (partial index).
 
 ```typescript
-@E.registerModel
-class Article extends E.Model<Article> {
-  static pk = E.primary(Article, "id");
-  static byFullName = E.unique(Article, (a: Article) => [`${a.firstName} ${a.lastName}`]);
-  static byWord = E.index(Article, (a: Article) => a.title.toLowerCase().split(" "));
-  static byDomain = E.index(Article, (a: Article) => a.email ? [a.email.split("@")[1]] : []);
-
+const Article = E.defineModel(class {
   id = E.field(E.identifier);
   firstName = E.field(E.string);
   lastName = E.field(E.string);
   title = E.field(E.string);
   email = E.field(E.opt(E.string));
-}
+}, {
+  pk: "id",
+  unique: {
+    byFullName: (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
+  },
+});
 
 await E.transact(() => {
   new Article({ firstName: "Jane", lastName: "Doe", title: "Hello World", email: "jane@acme.com" });
@@ -315,34 +302,29 @@ await E.transact(() => {
 });
 ```
 
-Computed indexes also support `find()` range queries and `batchProcess()`, just like field-based indexes.
-
-### Relationships (Links)
+### Relationships
 
-Use `E.link(Model)` for foreign keys:
+Use `E.link(Model)` for foreign keys. Use a thunk (a function that just returns a value) for forward references when needed:
 
 ```typescript
-@E.registerModel
-class Author extends E.Model<Author> {
-  static pk = E.primary(Author, "id");
+const Author = E.defineModel(class {
   id = E.field(E.identifier);
   name = E.field(E.string);
-}
+}, { pk: "id" });
 
-@E.registerModel
-class Book extends E.Model<Book> {
-  static pk = E.primary(Book, "id");
+const Book = E.defineModel(class {
   id = E.field(E.identifier);
   title = E.field(E.string);
   author = E.field(E.link(Author));
-}
+}, { pk: "id" });
 
 await E.transact(() => {
   const author = new Author({name: "Tolkien"});
   const book = new Book({title: "The Hobbit", author});
 
   // Later: linked models are lazy-loaded on property access
-  const b = Book.pk.get(book.id)!;
+  const b = Book.get(book.id)!;
+  console.log(b.author.id);    // no need to load yet..
   console.log(b.author.name);  // loads Author automatically (~1µs)
 });
 ```
@@ -351,7 +333,7 @@ await E.transact(() => {
 
 ```typescript
 await E.transact(() => {
-  const user = User.pk.get(someId);
+  const user = User.get(someId);
   if (user) user.delete();
 });
 ```
@@ -369,10 +351,16 @@ await E.transact(() => {
   user.preventPersist(); // exclude from commit
 });
 
-// findAll iterates all instances
+// find() iterates all instances (or use range options)
 await E.transact(() => {
-  for (const user of User.findAll()) { ... }
-  for (const user of User.findAll({reverse: true})) { ... }
+  for (const user of User.find()) { ... }
+  for (const user of User.find({reverse: true})) { ... }
+
+  // {fetch: 'first'} returns a single instance or undefined
+  const first = User.find({fetch: 'first'});
+
+  // {fetch: 'single'} returns a single instance, or throws if there are none or more than one
+  const only = User.find({fetch: 'single'});
 });
 
 // replaceInto: upsert by primary key
@@ -386,7 +374,7 @@ await E.transact(() => {
 For large datasets, `batchProcess` auto-commits in batches:
 
 ```typescript
-await Product.byCategory.batchProcess({is: "old"}, (product) => {
+await Product.batchProcess({ limitRows: 1000 }, (product) => {
   product.category = "archived";
 });
 // Commits every ~1 second or 4096 rows (configurable via limitSeconds, limitRows)
@@ -394,12 +382,10 @@ await Product.byCategory.batchProcess({is: "old"}, (product) => {
 
 ### Lazy Schema Migrations
 
-When you change a model's schema, Edinburgh will lazily try to migrate old records on access. This allows you to deploy code changes without downtime or a separate migration step. Optionally, you may provide a `static migrate(record: Record<string, any>)` function on the model to transform old records during lazy migration. If there is a migration error (like a new field without a default value, or an incompatible type change), a run-time error is thrown when loading the affected model instance.
+When you change a model's schema, Edinburgh lazily migrates old records on access. You can provide a `static migrate(record)` function to transform old rows:
 
 ```typescript
-@E.registerModel
-class User extends E.Model<User> {
-  static pk = E.primary(User, "id");
+const UserV2 = E.defineModel(class {
   id = E.field(E.identifier);
   name = E.field(E.string);
   role = E.field(E.string);  // newly added field
@@ -442,9 +428,7 @@ console.log(result.secondaries);  // { User: 1500 }
 Compute derived fields before data is written:
 
 ```typescript
-@E.registerModel
-class Article extends E.Model<Article> {
-  static pk = E.primary(Article, "id");
+const Article = E.defineModel(class {
   id = E.field(E.identifier);
   title = E.field(E.string);
   slug = E.field(E.string);
@@ -452,7 +436,7 @@ class Article extends E.Model<Article> {
   preCommit() {
     this.slug = this.title.toLowerCase().replace(/\s+/g, "-");
   }
-}
+}, { pk: "id" });
 ```
 
 ### Change Tracking
@@ -532,7 +516,7 @@ The database table name (defaults to class name).
 
 #### Model.override · static property
 
-When true, registerModel replaces an existing model with the same tableName.
+When true, defineModel replaces an existing model with the same tableName.
 
 **Type:** `boolean`
 
@@ -548,9 +532,31 @@ Optional migration function called when deserializing rows written with an older
 Receives a plain record with all fields (primary key fields + value fields) and should mutate it
 in-place to match the current schema.
 
-#### [Model.findAll](Model_findAll.md) · static method
+#### Model.get · static method
 
-Find all instances of this model in the database, ordered by primary key.
+**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
 
@@ -605,7 +611,7 @@ Check if this model instance is valid.
 
 **Signature:** `() => string`
 
-### [registerModel](registerModel.md) · function
+### [defineModel](defineModel.md) · function
 
 Register a model class with the Edinburgh ORM system.
 
@@ -613,6 +619,13 @@ Register a model class with the Edinburgh ORM system.
 
 Create a field definition for a model property.
 
+### currentTxn · function
+
+Returns the current transaction from AsyncLocalStorage.
+Throws if called outside a transact() callback.
+
+**Signature:** `() => Transaction`
+
 ### string · constant
 
 Type wrapper instance for the string type.
@@ -687,18 +700,6 @@ Create a literal type wrapper for a constant value.
 
 Create a link type wrapper for model relationships.
 
-### [index](index.md) · function
-
-Create a secondary index on model fields, or a computed secondary index using a function.
-
-### [primary](primary.md) · function
-
-Create a primary index on model fields.
-
-### [unique](unique.md) · function
-
-Create a unique index on model fields, or a computed unique index using a function.
-
 ### [dump](dump.md) · function
 
 Dump database contents for debugging.
@@ -709,6 +710,12 @@ Base class for database indexes for efficient lookups on model fields.
 
 #### [baseIndex.find](BaseIndex_find.md) · method
 
+#### [baseIndex.find](BaseIndex_find_2.md) · method
+
+#### [baseIndex.find](BaseIndex_find_3.md) · method
+
+#### [baseIndex.find](BaseIndex_find_4.md) · method
+
 #### [baseIndex.batchProcess](BaseIndex_batchProcess.md) · method
 
 [object Object],[object Object],[object Object]
@@ -717,27 +724,22 @@ Base class for database indexes for efficient lookups on model fields.
 
 **Signature:** `() => string`
 
-### [UniqueIndex](UniqueIndex.md) · class
-
-Unique index that stores references to the primary key.
-
-#### [uniqueIndex.get](UniqueIndex_get.md) · method
+### [NonPrimaryIndex](NonPrimaryIndex.md) · abstract class
 
-Get a model instance by unique index key values.
+Abstract base for all non-primary indexes (unique and secondary).
+Provides shared key serialization, write/delete/update logic.
 
-### [PrimaryIndex](PrimaryIndex.md) · class
+### [UniqueIndex](UniqueIndex.md) · class
 
-Primary index that stores the actual model data.
+Unique index that stores references to the primary key.
 
-#### [primaryIndex.get](PrimaryIndex_get.md) · method
+#### uniqueIndex.get · method
 
-Get a model instance by primary key values.
+**Signature:** `(...args: ARGS) => InstanceType<M>`
 
-#### [primaryIndex.getLazy](PrimaryIndex_getLazy.md) · method
+**Parameters:**
 
-Does the same as as `get()`, but will delay loading the instance from disk until the first
-property access. In case it turns out the instance doesn't exist, an error will be thrown
-at that time.
+- `args: ARGS`
 
 ### [SecondaryIndex](SecondaryIndex.md) · class
 

package/skill/SecondaryIndex.md

@@ -4,6 +4,6 @@ Secondary index for non-unique lookups.
 
 **Type Parameters:**
 
-- `M extends typeof Model` - The model class this index belongs to.
-- `F extends readonly (keyof InstanceType<M> & string)[]` - The field names that make up this index.
+- `M extends typeof Model`
+- `F extends readonly (keyof InstanceType<M> & string)[]`
 - `ARGS extends readonly any[] = IndexArgTypes<M, F>`

package/skill/UniqueIndex.md

@@ -4,6 +4,6 @@ Unique index that stores references to the primary key.
 
 **Type Parameters:**
 
-- `M extends typeof Model` - The model class this index belongs to.
-- `F extends readonly (keyof InstanceType<M> & string)[]` - The field names that make up this index.
+- `M extends typeof Model`
+- `F extends readonly (keyof InstanceType<M> & string)[]`
 - `ARGS extends readonly any[] = IndexArgTypes<M, F>`

package/skill/defineModel.md

@@ -0,0 +1,22 @@
+### defineModel · function
+
+Register a model class with the Edinburgh ORM system.
+
+Converts a plain class into a fully-featured model with database persistence,
+typed fields, primary key access, and optional secondary and unique indexes.
+
+**Signature:** `<T extends new () => any, const PK extends (keyof FieldsOf<T> & string) | readonly (keyof FieldsOf<T> & string)[], const UNIQUE extends Record<string, (keyof FieldsOf<T> & string) | readonly (keyof FieldsOf<T> & string)[] | ((instance: any) => any)>, const INDEX extends Record<string, (keyof FieldsOf<T> & string) | ...`
+
+**Type Parameters:**
+
+- `T extends new () => any`
+- `PK extends (keyof FieldsOf<T> & string) | readonly (keyof FieldsOf<T> & string)[]`
+- `UNIQUE extends Record<string, (keyof FieldsOf<T> & string) | readonly (keyof FieldsOf<T> & string)[] | ((instance: any) => any)>`
+- `INDEX extends Record<string, (keyof FieldsOf<T> & string) | readonly (keyof FieldsOf<T> & string)[] | ((instance: any) => any)>`
+
+**Parameters:**
+
+- `cls: T` - - A plain class whose properties use E.field().
+- `opts?: { pk?: PK, unique?: UNIQUE, index?: INDEX, tableName?: string, override?: boolean }` - - Registration options.
+
+**Returns:** The enhanced model constructor.

package/skill/field.md

@@ -22,8 +22,8 @@ This allows for both runtime introspection and compile-time type safety.
 **Examples:**
 
 ```typescript
-class User extends E.Model<User> {
+const User = E.defineModel(class {
   name = E.field(E.string, {description: "User's full name"});
   age = E.field(E.opt(E.number), {description: "User's age", default: 25});
-}
+});
 ```

package/skill/link.md

@@ -2,11 +2,11 @@
 
 Create a link type wrapper for model relationships.
 
-**Signature:** `<const T extends typeof Model<any>>(TargetModel: T) => TypeWrapper<InstanceType<T>>`
+**Signature:** `{ <const T extends new (...args: any[]) => Model<any>>(TargetModel: T): TypeWrapper<InstanceType<T>>; <const T extends new (...args: any[]) => Model<any>>(TargetModel: () => T): TypeWrapper<...>; }`
 
 **Type Parameters:**
 
-- `T extends typeof Model<any>` - The target model class.
+- `T extends new (...args: any[]) => Model<any>` - The target model class.
 
 **Parameters:**
 
@@ -17,11 +17,13 @@ Create a link type wrapper for model relationships.
 **Examples:**
 
 ```typescript
-class User extends E.Model<User> {
-  posts = E.field(E.array(E.link(Post, 'author')));
-}
-
-class Post extends E.Model<Post> {
-  author = E.field(E.link(User));
-}
+const Author = E.defineModel(class {
+  id = E.field(E.identifier);
+  posts = E.field(E.array(E.link(() => Book)));
+}, { pk: "id" });
+
+const Book = E.defineModel(class {
+  id = E.field(E.identifier);
+  author = E.field(E.link(Author));
+}, { pk: "id" });
 ```

package/skill/transact.md

@@ -32,7 +32,7 @@ times.
 
 ```typescript
 const paid = await E.transact(() => {
-  const user = User.pk.get("john_doe");
+  const user = User.get("john_doe");
   if (user.credits > 0) {
     user.credits--;
     return true;
@@ -43,7 +43,7 @@ const paid = await E.transact(() => {
 ```typescript
 // Transaction with automatic retry on conflicts
 await E.transact(() => {
-  const counter = Counter.pk.get("global") || new Counter({id: "global", value: 0});
+  const counter = Counter.get("global") || new Counter({id: "global", value: 0});
   counter.value++;
 });
 ```

package/src/datapack.ts

@@ -187,7 +187,7 @@ export default class DataPack {
             this.ensureCapacity(data.length);
             this.buffer.set(data, this.writePos);
             this.writePos += data.length;
-        } else if (Array.isArray(data)) {
+        } else if (Array.isArray(data) || (typeof data.length === 'number' && typeof data[Symbol.iterator] === 'function')) {
             // Type 4, subtype 5: array start
             this.buffer[this.writePos++] = (4 << 5) | 5;
             for (const item of data) {