edinburgh 0.6.0 → 0.6.2

package/README.md

@@ -192,6 +192,22 @@ await E.transact(() => {
 });
 ```
 
+If a primary key or named index includes a `link(...)` field, lookup helpers either accept the linked row's instance object or its primary key. For linked models with composite primary keys, pass the full tuple in that slot:
+
+```typescript
+await E.transact(() => {
+  // So instead of..
+  const post1 = Post.getBy("author", Author.get(user.id), "Hello World");
+  // We can do..
+  const post2 = Post.getBy("author", user.id, "Hello World");
+  // Or..
+  const post3 = Post.getBy("author", [user.id], "Hello World");
+
+  // For an index that includes a link with a composite primary key..
+  const page = Comment.getBy("target", ["docs", "intro"], "overview");
+});
+```
+
 #### Range Queries
 
 Primary-key queries use `.find()`. Named unique and secondary indexes use `.findBy(name, ...)`:
@@ -553,7 +569,7 @@ await E.transact(() => {
 });
 ```
 
-### setMaxRetryCount · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L226)
+### setMaxRetryCount · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L232)
 
 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.
@@ -564,7 +580,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#L240)
+### setOnSaveCallback · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L249)
 
 Set a callback function to be called after a model is saved and committed.
 
@@ -577,11 +593,14 @@ 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.
 
-### Model · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+The callback is called within a new transaction context, allowing lazy-loads to happen. However, any
+changes made to Edinburgh models will not be saved.
+
+### Model · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 **Type:** `typeof ModelBase`
 
-### ModelClass · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+### ModelClass · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Runtime base constructor for model classes returned by `defineModel()`.
 
@@ -590,7 +609,7 @@ Prefer the `ModelClass` type alias for annotations and the result of
 
 **Type:** `typeof ModelClassRuntime`
 
-### AnyModelClass · [type](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L111)
+### AnyModelClass · [type](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L113)
 
 A model constructor with its generic information erased.
 
@@ -598,7 +617,7 @@ Useful when accepting or storing arbitrary registered model classes.
 
 **Type:** `ModelClass<new () => any, readonly any[], any, any>`
 
-### ModelBase · [abstract class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+### ModelBase · [abstract class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Base class for all database models in the Edinburgh ORM.
 
@@ -651,7 +670,7 @@ const User = E.defineModel("User", class {
 type User = InstanceType<typeof User>;
 ```
 
-#### ModelBase.migrate · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+#### ModelBase.migrate · [static method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Optional migration function called when deserializing rows written with an older schema version.
 Receives a plain record with all fields and should mutate it in-place to match the current schema.
@@ -678,7 +697,7 @@ const User = E.defineModel("User", class {
 }, { pk: "id" });
 ```
 
-#### modelBase.preCommit · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+#### modelBase.preCommit · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 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.
@@ -705,19 +724,19 @@ const Post = E.defineModel("Post", class {
 }, { pk: "id" });
 ```
 
-#### modelBase.getPrimaryKey · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+#### modelBase.getPrimaryKey · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 **Signature:** `() => Uint8Array<ArrayBufferLike>`
 
 **Returns:** The primary key for this instance.
 
-#### modelBase.getPrimaryKeyHash · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+#### modelBase.getPrimaryKeyHash · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 **Signature:** `() => number`
 
 **Returns:** A 53-bit positive integer non-cryptographic hash of the primary key, or undefined if not yet saved.
 
-#### modelBase.isLazyField · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+#### modelBase.isLazyField · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 **Signature:** `(field: keyof this) => boolean`
 
@@ -725,7 +744,7 @@ const Post = E.defineModel("Post", class {
 
 - `field: keyof this`
 
-#### modelBase.preventPersist · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+#### modelBase.preventPersist · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Prevent this instance from being persisted to the database.
 
@@ -741,7 +760,7 @@ user.name = "New Name";
 user.preventPersist(); // Changes won't be saved
 ```
 
-#### modelBase.delete · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+#### modelBase.delete · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Delete this model instance from the database.
 
@@ -756,7 +775,7 @@ const user = User.get("user123");
 user.delete(); // Removes from database
 ```
 
-#### modelBase.validate · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+#### modelBase.validate · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Validate all fields in this model instance.
 
@@ -778,7 +797,7 @@ if (errors.length > 0) {
 }
 ```
 
-#### modelBase.isValid · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+#### modelBase.isValid · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Check if this model instance is valid.
 
@@ -793,19 +812,19 @@ const user = new User({name: "John"});
 if (!user.isValid()) shoutAtTheUser();
 ```
 
-#### modelBase.getState · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+#### modelBase.getState · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 **Signature:** `() => "created" | "deleted" | "loaded" | "lazy"`
 
-#### modelBase.toString · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+#### modelBase.toString · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 **Signature:** `() => string`
 
-#### modelBase.[Symbol.for('nodejs.util.inspect.custom')] · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+#### modelBase.[Symbol.for('nodejs.util.inspect.custom')] · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 **Signature:** `() => string`
 
-### defineModel · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+### defineModel · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Register a model class with the Edinburgh ORM system.
 
@@ -829,7 +848,7 @@ typed fields, primary key access, and optional secondary and unique indexes.
 
 **Returns:** The enhanced model constructor.
 
-### deleteEverything · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+### deleteEverything · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Delete every key/value entry in the database and reinitialize all registered models.
 
@@ -838,7 +857,7 @@ for tests, local resets, or tooling that needs a completely empty database.
 
 **Signature:** `() => Promise<void>`
 
-### field · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L76)
+### field · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L77)
 
 Create a field definition for a model property.
 
@@ -846,16 +865,16 @@ This function uses TypeScript magic to return the field configuration object
 while appearing to return the actual field value type to the type system.
 This allows for both runtime introspection and compile-time type safety.
 
-**Signature:** `<T>(type: TypeWrapper<T>, options?: Partial<FieldConfig<T>>) => T`
+**Signature:** `<TYPE extends TypeWrapper<any>>(type: TYPE, options?: Partial<FieldConfig<FieldValue<TYPE>>>) => FieldValue<TYPE>`
 
 **Type Parameters:**
 
-- `T` - The field type.
+- `TYPE extends TypeWrapper<any>` - The field type.
 
 **Parameters:**
 
-- `type: TypeWrapper<T>` - The type wrapper for this field.
-- `options: Partial<FieldConfig<T>>` (optional) - Additional field configuration options.
+- `type: TYPE` - The type wrapper for this field.
+- `options: Partial<FieldConfig<FieldValue<TYPE>>>` (optional) - Additional field configuration options.
 
 **Returns:** The field value (typed as T, but actually returns FieldConfig<T>).
 
@@ -868,13 +887,13 @@ const User = E.defineModel("User", class {
 });
 ```
 
-### string · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+### string · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Type wrapper instance for the string type.
 
 **Value:** `TypeWrapper<string>`
 
-### orderedString · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+### orderedString · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 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
@@ -884,37 +903,37 @@ may not contain null characters.
 
 **Value:** `TypeWrapper<string>`
 
-### number · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+### number · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Type wrapper instance for the number type.
 
 **Value:** `TypeWrapper<number>`
 
-### dateTime · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+### dateTime · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 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#L243)
+### boolean · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Type wrapper instance for the boolean type.
 
 **Value:** `TypeWrapper<boolean>`
 
-### identifier · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+### identifier · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Type wrapper instance for the identifier type.
 
 **Value:** `TypeWrapper<string>`
 
-### undef · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+### undef · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Type wrapper instance for the 'undefined' type.
 
 **Value:** `TypeWrapper<undefined>`
 
-### opt · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+### opt · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Create an optional type wrapper (allows undefined).
 
@@ -937,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#L243)
+### or · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Create a union type wrapper from multiple type choices.
 
@@ -960,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#L243)
+### array · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Create an array type wrapper with optional length constraints.
 
@@ -984,7 +1003,7 @@ const stringArray = E.array(E.string);
 const boundedArray = E.array(E.number, {min: 1, max: 10});
 ```
 
-### set · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+### set · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Create a Set type wrapper with optional length constraints.
 
@@ -1008,7 +1027,7 @@ 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#L243)
+### record · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Create a Record type wrapper for key-value objects with string or number keys.
 
@@ -1030,7 +1049,7 @@ Create a Record type wrapper for key-value objects with string or number keys.
 const scores = E.record(E.number);  // Record<string | number, number>
 ```
 
-### literal · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+### literal · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Create a literal type wrapper for a constant value.
 
@@ -1053,11 +1072,11 @@ const statusType = E.literal("active");
 const countType = E.literal(42);
 ```
 
-### link · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+### link · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 Create a link type wrapper for model relationships.
 
-**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<...>; }`
+**Signature:** `{ <const T extends new (...args: any[]) => Model<any>>(TargetModel: T): TypeWrapper<InstanceType<T>> & QueryArgCarrier<InstanceType<T> | LinkPrimaryKeyInput<LinkTargetPKArgs<T>>>; <const T extends new (...args: any[]) => Model<any>>(TargetModel: () => T): TypeWrapper<...>; }`
 
 **Type Parameters:**
 
@@ -1083,11 +1102,11 @@ const Book = E.defineModel("Book", class {
 }, { pk: "id" });
 ```
 
-### dump · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L243)
+### dump · [function](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L252)
 
 **Signature:** `() => void`
 
-### FindOptions · [type](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L115)
+### FindOptions · [type](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L141)
 
 Range-query options accepted by `find()`, `findBy()`, `batchProcess()`, and `batchProcessBy()`.
 
@@ -1095,7 +1114,10 @@ Supports exact-match lookups via `is`, inclusive bounds via `from` / `to`,
 exclusive bounds via `after` / `before`, and reverse scans.
 
 For single-field indexes, values can be passed directly. For composite indexes,
-pass tuples or partial tuples for prefix matching.
+pass tuples or partial tuples for prefix matching. If an index field is a
+`link(...)`, you may pass either the linked model instance or the linked
+model's primary key. Composite linked primary keys are passed as tuples in
+that slot.
 
 **Type:** `(
     (
@@ -1125,7 +1147,7 @@ pass tuples or partial tuples for prefix matching.
     & (FETCH extends undefined ? { fetch?: undefined } : { fetch: FETCH })
 )`
 
-### IndexRangeIterator · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L73)
+### IndexRangeIterator · [class](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L90)
 
 Iterator for range queries on indexes.
 Handles common iteration logic for both primary and unique indexes.
@@ -1135,27 +1157,27 @@ Extends built-in Iterator to provide map/filter/reduce/toArray/etc.
 
 - `ITEM`
 
-#### indexRangeIterator.[Symbol.iterator] · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L78)
+#### indexRangeIterator.[Symbol.iterator] · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L100)
 
 **Signature:** `() => this`
 
-#### indexRangeIterator.next · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L80)
+#### indexRangeIterator.next · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L102)
 
 **Signature:** `() => IteratorResult<ITEM, any>`
 
-#### indexRangeIterator.count · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L102)
+#### indexRangeIterator.count · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L110)
 
 **Signature:** `() => number`
 
-#### indexRangeIterator.fetch · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L105)
+#### indexRangeIterator.fetch · [method](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L112)
 
 **Signature:** `() => ITEM`
 
-### Change · [type](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L85)
+### Change · [type](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L90)
 
 **Type:** `Record<any, any> | "created" | "deleted"`
 
-### FieldConfig · [interface](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L37)
+### FieldConfig · [interface](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L40)
 
 Configuration interface for model fields.
 
@@ -1169,13 +1191,13 @@ The type wrapper that defines how this field is serialized/validated.
 
 **Type:** `TypeWrapper<T>`
 
-#### fieldConfig.description · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L47)
+#### fieldConfig.description · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L48)
 
 Optional human-readable description of the field.
 
 **Type:** `string`
 
-#### fieldConfig.default · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L49)
+#### fieldConfig.default · [member](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L50)
 
 Optional default value or function that generates default values.
 
@@ -1273,7 +1295,7 @@ Check if indexing should be skipped for this field value.
 
 **Signature:** `() => AnyModelClass`
 
-### DatabaseError · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L166)
+### DatabaseError · [constant](https://github.com/vanviegen/edinburgh/blob/main/src/edinburgh.ts#L182)
 
 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.

package/build/src/edinburgh.d.ts

@@ -84,5 +84,8 @@ export declare function setMaxRetryCount(count: number): void;
  * `transact()` commit that has changes, with the following arguments:
  *   - A sequential number. Higher numbers have been committed after lower numbers.
  *   - A map of model instances to their changes. The change can be "created", "deleted", or an object containing the old values.
+ *
+ * The callback is called within a new transaction context, allowing lazy-loads to happen. However, any
+ * changes made to Edinburgh models will not be saved.
  */
 export declare function setOnSaveCallback(callback: ((commitId: number, items: Map<Model<unknown>, Change>) => void) | undefined): void;

package/build/src/edinburgh.js

@@ -140,27 +140,31 @@ export async function transact(fn) {
             catch { }
             throw e;
         }
-        finally {
-            // Make the instances read-only to make it clear that their transaction has ended.
-            for (const instance of txn.instances.values()) {
-                delete instance._oldValues;
-                Object.defineProperty(instance, "_txn", STALE_INSTANCE_DESCRIPTOR);
-                Object.freeze(instance);
-            }
-            // Destroy the transaction object, to make sure things crash if they are used after
-            // this point, and to help the GC reclaim memory.
-            txn.id = txn.instances = undefined;
-        }
-        const commitResult = lowlevel.commitTransaction(txnId);
-        const commitSeq = typeof commitResult === 'number' ? commitResult : await commitResult;
-        if (commitSeq > 0) {
-            // Success
-            if (onSaveItems?.size) {
+        if (onSaveItems?.size) {
+            // Perform writes, and start a new transaction at or past the point-in-time of our commit
+            const commitResult = lowlevel.commitTransaction(txnId, true);
+            if (typeof commitResult === 'object') {
+                const commitSeq = await commitResult;
+                if (commitSeq <= 0)
+                    continue; // Race condition - retry
+                // Run the callback within our new transaction context, so it can fetch linked lazy fields if needed
                 onSaveCallback(commitSeq, onSaveItems);
             }
-            return result;
+            // else: only reads
         }
-        // Race condition - retry
+        // Make the instances read-only to make it clear that their transaction has ended.
+        for (const instance of txn.instances.values()) {
+            delete instance._oldValues;
+            Object.defineProperty(instance, "_txn", STALE_INSTANCE_DESCRIPTOR);
+            Object.freeze(instance);
+        }
+        // Destroy the transaction object, to make sure things crash if they are used after
+        // this point, and to help the GC reclaim memory.
+        txn.id = txn.instances = undefined;
+        // Commit the transaction and actually end it
+        if ((await lowlevel.commitTransaction(txnId)) <= 0)
+            continue; // Race condition - retry
+        return result;
     }
     throw new DatabaseError("Transaction keeps getting raced", "RACING_TRANSACTION");
     // } catch (e: Error | any) {
@@ -187,6 +191,9 @@ let onSaveCallback;
  * `transact()` commit that has changes, with the following arguments:
  *   - A sequential number. Higher numbers have been committed after lower numbers.
  *   - A map of model instances to their changes. The change can be "created", "deleted", or an object containing the old values.
+ *
+ * The callback is called within a new transaction context, allowing lazy-loads to happen. However, any
+ * changes made to Edinburgh models will not be saved.
  */
 export function setOnSaveCallback(callback) {
     onSaveCallback = callback;

package/build/src/edinburgh.js.map

@@ -1 +1 @@
-{"version":3,"file":"edinburgh.js","sourceRoot":"","sources":["../../src/edinburgh.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"edinburgh.js","sourceRoot":"","sources":["../../src/edinburgh.ts"],"names":[],"mappings":"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"}

package/build/src/indexes.d.ts

@@ -48,7 +48,10 @@ type ArrayOrOnlyItem<ARG_TYPES extends readonly any[]> = ARG_TYPES extends reado
  * exclusive bounds via `after` / `before`, and reverse scans.
  *
  * For single-field indexes, values can be passed directly. For composite indexes,
- * pass tuples or partial tuples for prefix matching.
+ * pass tuples or partial tuples for prefix matching. If an index field is a
+ * `link(...)`, you may pass either the linked model instance or the linked
+ * model's primary key. Composite linked primary keys are passed as tuples in
+ * that slot.
  *
  * @template ARG_TYPES - Tuple of index argument types.
  * @template FETCH - Optional fetch mode used by overloads that return one row.

package/build/src/indexes.js

@@ -4,6 +4,15 @@ import DataPack from "./datapack.js";
 import { currentTxn, transact } from "./edinburgh.js";
 import { assert, logLevel, dbGet, dbPut, dbDel, hashBytes, hashFunction, bytesEqual, toBuffer } from "./utils.js";
 import { deserializeType, serializeType } from "./types.js";
+function serializeIndexArg(fieldType, arg, pack) {
+    const linkedModel = fieldType.getLinkedModel();
+    if (!linkedModel || arg instanceof linkedModel) {
+        fieldType.serialize(arg, pack);
+        return;
+    }
+    // Link lookups may pass the target row's primary key instead of a loaded instance.
+    pack.write(linkedModel._argsToKeyBytes(Array.isArray(arg) ? arg : [arg], false).toUint8Array());
+}
 const MAX_INDEX_ID_PREFIX = -1;
 const INDEX_ID_PREFIX = -2;
 const VERSION_INFO_PREFIX = -3;
@@ -107,7 +116,7 @@ export class BaseIndex {
             for (const fieldType of this._indexFields.values()) {
                 if (index >= args.length)
                     break;
-                fieldType.serialize(args[index++], bytes);
+                serializeIndexArg(fieldType, args[index++], bytes);
             }
         }
         return bytes;