edinburgh 0.6.2 → 0.6.4

package/src/edinburgh.ts

@@ -10,6 +10,7 @@ export {
     type ModelClass,
     type AnyModelClass,
     type ModelBase,
+    type ModelLookup,
     defineModel,
     deleteEverything,
     field,
@@ -158,6 +159,7 @@ export async function transact<T>(fn: () => T): Promise<T> {
             const txn: Transaction = { id: txnId, instances: new Map() };
             const onSaveItems: Map<Model<unknown>, Change> | undefined = onSaveCallback ? new Map() : undefined;
 
+            let retry = false;
             let result: T | undefined;
             try {
                 await txnStorage.run(txn, async function() {
@@ -179,23 +181,33 @@ export async function transact<T>(fn: () => T): Promise<T> {
                             onSaveItems.set(instance, change);
                         }
                     }
+
+                    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) {
+                                try { lowlevel.abortTransaction(txnId); } catch {}
+                                retry = true;
+                                return;
+                            }
+                            // Run the callback within our renewed transaction context, so it can fetch linked lazy fields if needed
+                            try {
+                                onSaveCallback!(commitSeq, onSaveItems);
+                            } catch (e) {
+                                throw e;
+                            }
+                        }
+                        // else: only reads
+                    }
                 });
             } catch (e: any) {
                 try { lowlevel.abortTransaction(txnId); } catch {}
                 throw e;
             }
 
-            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);
-                }
-                // else: only reads
-            }
+            if (retry) continue;
 
             // Make the instances read-only to make it clear that their transaction has ended.
             for (const instance of txn.instances.values()) {
@@ -243,8 +255,8 @@ let onSaveCallback: ((commitId: number, items: Map<Model<unknown>, Change>) => v
  *   - 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.
+ * The callback is called within a new transaction context at or after the committed state, so lazy-loads
+ * and additional writes are allowed.
  */
 export function setOnSaveCallback(callback: ((commitId: number, items: Map<Model<unknown>, Change>) => void) | undefined) {
     onSaveCallback = callback;

package/src/models.ts

@@ -65,6 +65,20 @@ function isObjectEmpty(obj: object) {
 export type Change = Record<any, any> | "created" | "deleted";
 
 type FieldsOf<T> = T extends new () => infer I ? I : never;
+type ModelFields<T extends new () => any> = FieldsOf<T>;
+
+export interface ModelLookup<PKA extends readonly any[] = readonly any[]> {
+    get(...args: PKA): any;
+}
+
+type ModelInstance<FIELDS, PKA extends readonly any[] = readonly any[]> = Model<FIELDS, ModelLookup<PKA>>;
+
+type PublicModelOf<T extends new () => any> = Model<ModelFields<T>>;
+
+type IndexSpec<T extends new () => any> =
+    | (keyof ModelFields<T> & string)
+    | readonly (keyof ModelFields<T> & string)[]
+    | ((instance: PublicModelOf<T>) => any);
 
 type PKArgs<FIELDS, PK> =
     PK extends readonly (keyof FIELDS & string)[]
@@ -82,14 +96,25 @@ type IndexArgs<FIELDS, SPEC> =
         ? R extends (infer V)[] ? [V] : [R]
     : never;
 
+type PublicIndexSpec<SPEC> =
+    SPEC extends (instance: infer INSTANCE) => infer R
+        ? (instance: INSTANCE) => R
+        : SPEC;
+
+type PublicIndexSpecs<SPECS> = {
+    [K in keyof SPECS]: PublicIndexSpec<SPECS[K]>;
+};
+
 /**
  * A model constructor with its generic information erased.
  *
  * Useful when accepting or storing arbitrary registered model classes.
  */
-export type AnyModelClass = ModelClass<new () => any, readonly any[], any, any>;
+export type AnyModelClass = ModelClass<object, any, readonly any[], any, any>;
+
+type StaticMembers<T extends new () => any> = Pick<T, Exclude<keyof T, 'prototype'>>;
 
-type SecondaryRegistry<FIELDS> = Record<string, NonPrimaryIndex<Model<FIELDS>, readonly (keyof FIELDS & string)[], readonly any[]>>;
+type SecondaryRegistry<FIELDS, PKA extends readonly any[]> = Record<string, NonPrimaryIndex<ModelInstance<FIELDS, PKA>, readonly (keyof FIELDS & string)[], readonly any[]>>;
 
 function copyStaticMembersFromClassChain(target: object, source: Function) {
     for (let current: any = source; current && current !== Function.prototype; current = Object.getPrototypeOf(current)) {
@@ -107,13 +132,13 @@ export const pendingModelInits = new Set<AnyModelClass>();
 
 // These static members are attached dynamically in defineModel(), so 'declare' tells TypeScript
 // they exist at runtime without emitting duplicate class fields that would shadow those assignments.
-class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX = {}> extends PrimaryKey<Model<FIELDS>, readonly (keyof FIELDS & string)[], PKA> {
+class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX = {}> extends PrimaryKey<ModelInstance<FIELDS, PKA>, readonly (keyof FIELDS & string)[], PKA> {
     // Runtime table identifier used for index naming and diagnostics.
     declare tableName: string;
     // Field schema map used for validation and serialization.
     declare fields: Record<string | symbol | number, FieldConfig<unknown>>;
     // Registered unique/secondary indexes for this model.
-    declare _secondaries?: SecondaryRegistry<FIELDS>;
+    declare _secondaries?: SecondaryRegistry<FIELDS, PKA>;
     // Cached list of non-primary fields used for value serialization.
     _nonKeyFields!: (keyof FIELDS & string)[];
     // Lazy getter/setter descriptors installed on unloaded non-key fields.
@@ -160,13 +185,13 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
                 this._lazyDescriptors[fieldName] = {
                     configurable: true,
                     enumerable: true,
-                    get(this: Model<FIELDS>) {
+                    get(this: ModelInstance<FIELDS, PKA>) {
                         this.constructor._lazyLoad(this);
-                        return this[fieldName];
+                        return (this as any)[fieldName];
                     },
-                    set(this: Model<FIELDS>, value: any) {
+                    set(this: ModelInstance<FIELDS, PKA>, value: any) {
                         this.constructor._lazyLoad(this);
-                        this[fieldName] = value;
+                        (this as any)[fieldName] = value;
                     },
                 };
                 this._resetDescriptors[fieldName] = {
@@ -200,9 +225,9 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
         return index;
     }
 
-    _get(txn: Transaction, args: PKA | Uint8Array, loadNow: false | Uint8Array): Model<FIELDS>;
-    _get(txn: Transaction, args: PKA | Uint8Array, loadNow: true): Model<FIELDS> | undefined;
-    _get(txn: Transaction, args: PKA | Uint8Array, loadNow: boolean | Uint8Array): Model<FIELDS> | undefined {
+    _get(txn: Transaction, args: PKA | Uint8Array, loadNow: false | Uint8Array): ModelInstance<FIELDS, PKA>;
+    _get(txn: Transaction, args: PKA | Uint8Array, loadNow: true): ModelInstance<FIELDS, PKA> | undefined;
+    _get(txn: Transaction, args: PKA | Uint8Array, loadNow: boolean | Uint8Array): ModelInstance<FIELDS, PKA> | undefined {
         let key: Uint8Array;
         let keyParts: readonly any[] | undefined;
         if (args instanceof Uint8Array) {
@@ -213,7 +238,7 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
         }
 
         const keyHash = hashBytes(key);
-        const cached = txn.instances.get(keyHash) as Model<FIELDS> | undefined;
+        const cached = txn.instances.get(keyHash) as ModelInstance<FIELDS, PKA> | undefined;
         if (cached) {
             if (loadNow && loadNow !== true) {
                 Object.defineProperties(cached, this._resetDescriptors);
@@ -232,7 +257,7 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
             }
         }
 
-        const model = Object.create((this as any).prototype) as Model<FIELDS>;
+        const model = Object.create((this as any).prototype) as ModelInstance<FIELDS, PKA>;
         model._txn = txn;
         model._oldValues = {};
         txn.instances.set(keyHash, model);
@@ -259,7 +284,7 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
         return model;
     }
 
-    _lazyLoad(model: Model<FIELDS>) {
+    _lazyLoad(model: ModelInstance<FIELDS, PKA>) {
         const key = model._primaryKey!;
         const valueBuffer = dbGet(model._txn.id, key);
         if (!valueBuffer) throw new DatabaseError(`Lazy-loaded ${this.tableName}#${key} does not exist`, 'LAZY_FAIL');
@@ -276,7 +301,7 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
      *
      * @returns The matching model, or `undefined` if no row exists.
      */
-    get(...args: PKA): Model<FIELDS> | undefined {
+    get(...args: PKA): ModelInstance<FIELDS, PKA> | undefined {
         return this._get(currentTxn(), args, true);
     }
 
@@ -287,11 +312,11 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
      *
      * Accessing a lazy field later will load the remaining fields transparently.
      */
-    getLazy(...args: PKA): Model<FIELDS> {
+    getLazy(...args: PKA): ModelInstance<FIELDS, PKA> {
         return this._get(currentTxn(), args, false);
     }
 
-    _pairToInstance(txn: Transaction, keyBuffer: ArrayBuffer, valueBuffer: ArrayBuffer): Model<FIELDS> {
+    _pairToInstance(txn: Transaction, keyBuffer: ArrayBuffer, valueBuffer: ArrayBuffer): ModelInstance<FIELDS, PKA> {
         return this._get(txn, new Uint8Array(keyBuffer), new Uint8Array(valueBuffer))!;
     }
 
@@ -303,7 +328,7 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
      * @param obj Partial model data that **must** include every primary key field.
       * @returns The loaded-and-updated or newly created instance.
      */
-    replaceInto(obj: Partial<FIELDS>): Model<FIELDS> {
+    replaceInto(obj: Partial<FIELDS>): ModelInstance<FIELDS, PKA> {
         const keyArgs: any[] = [];
         for (const fieldName of this._indexFields.keys()) {
             if (!(fieldName in (obj as any))) {
@@ -311,7 +336,7 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
             }
             keyArgs.push((obj as any)[fieldName]);
         }
-        const existing = this.get(...keyArgs as any) as Model<FIELDS> | undefined;
+        const existing = this.get(...keyArgs as any) as ModelInstance<FIELDS, PKA> | undefined;
         if (existing) {
             for (const key in obj as any) {
                 if (!this._indexFields.has(key as any)) {
@@ -332,7 +357,7 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
         * linked model uses a composite primary key, pass the full tuple in that slot.
      * @returns The matching model instance, if any.
      */
-    getBy<K extends string & keyof UNIQUE>(name: K, ...args: IndexArgs<FIELDS, UNIQUE[K]>): Model<FIELDS> | undefined {
+    getBy<K extends string & keyof UNIQUE>(name: K, ...args: IndexArgs<FIELDS, UNIQUE[K]>): ModelInstance<FIELDS, PKA> | undefined {
         return (this._getSecondary(name) as any).getPK(...args);
     }
 
@@ -343,9 +368,9 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
         * or `index` registration. Link-valued index fields accept either the linked
         * model instance or the linked model's primary key tuple/value.
      */
-    findBy<K extends string & keyof (UNIQUE & INDEX)>(name: K, opts: FindOptions<IndexArgs<FIELDS, (UNIQUE & INDEX)[K]>, 'first'>): Model<FIELDS> | undefined;
-    findBy<K extends string & keyof (UNIQUE & INDEX)>(name: K, opts: FindOptions<IndexArgs<FIELDS, (UNIQUE & INDEX)[K]>, 'single'>): Model<FIELDS>;
-    findBy<K extends string & keyof (UNIQUE & INDEX)>(name: K, opts?: FindOptions<IndexArgs<FIELDS, (UNIQUE & INDEX)[K]>>): IndexRangeIterator<Model<FIELDS>>;
+    findBy<K extends string & keyof (UNIQUE & INDEX)>(name: K, opts: FindOptions<IndexArgs<FIELDS, (UNIQUE & INDEX)[K]>, 'first'>): ModelInstance<FIELDS, PKA> | undefined;
+    findBy<K extends string & keyof (UNIQUE & INDEX)>(name: K, opts: FindOptions<IndexArgs<FIELDS, (UNIQUE & INDEX)[K]>, 'single'>): ModelInstance<FIELDS, PKA>;
+    findBy<K extends string & keyof (UNIQUE & INDEX)>(name: K, opts?: FindOptions<IndexArgs<FIELDS, (UNIQUE & INDEX)[K]>>): IndexRangeIterator<ModelInstance<FIELDS, PKA>>;
     findBy(name: string, opts?: any): any {
         return this._getSecondary(name).find(opts);
     }
@@ -358,12 +383,12 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
     batchProcessBy<K extends string & keyof (UNIQUE & INDEX)>(
         name: K,
         opts: FindOptions<IndexArgs<FIELDS, (UNIQUE & INDEX)[K]>> & { limitSeconds?: number; limitRows?: number },
-        callback: (row: Model<FIELDS>) => any,
+        callback: (row: ModelInstance<FIELDS, PKA>) => any,
     ): Promise<void> {
         return this._getSecondary(name).batchProcess(opts, callback as any);
     }
 
-    _loadValueFields(model: Model<FIELDS>, valueArray: Uint8Array) {
+    _loadValueFields(model: ModelInstance<FIELDS, PKA>, valueArray: Uint8Array) {
         const valuePack = new DataPack(valueArray);
         const version = valuePack.readNumber();
 
@@ -399,7 +424,7 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
         return info;
     }
 
-    _migrateValueFields(model: Model<FIELDS>, version: number, valuePack: DataPack) {
+    _migrateValueFields(model: ModelInstance<FIELDS, PKA>, version: number, valuePack: DataPack) {
         const versionInfo = this._loadVersionInfo(model._txn.id, version);
         const record: Record<string, any> = {};
         for (const [name] of this._indexFields.entries()) record[name] = (model as any)[name];
@@ -447,23 +472,23 @@ export const ModelClass = ModelClassRuntime;
  * helpers like `get()` and `getLazy()`, range-query helpers like `find()`, and
  * named-index helpers like `getBy()` and `findBy()`.
  *
- * @template T - The original class passed to `defineModel()`.
+ * @template FIELDS - The user-defined fields of the model instance.
  * @template PKA - Tuple of primary-key argument types.
  * @template UNIQUE - Named unique-index specifications.
  * @template INDEX - Named secondary-index specifications.
  */
-export type ModelClass<T extends new () => any, PKA extends readonly any[], UNIQUE = {}, INDEX = {}> =
-    T
-    & ModelClassRuntime<FieldsOf<T>, PKA, UNIQUE, INDEX>
+export type ModelClass<STATICS, FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX = {}> =
+    STATICS
+    & ModelClassRuntime<FIELDS, PKA, UNIQUE, INDEX>
     & {
-        new (initial?: Partial<FieldsOf<T>>, txn?: Transaction): Model<FieldsOf<T>>;
+        new (initial?: Partial<FIELDS>, txn?: Transaction): ModelInstance<FIELDS, PKA>;
     };
 
 /**
  * Minimal instance-side model shape used for typing the constructor property.
  */
-export interface ModelBase {
-    constructor: AnyModelClass;
+export interface ModelBase<LOOKUP extends ModelLookup = ModelLookup> {
+    constructor: LOOKUP & AnyModelClass;
 }
 
 /**
@@ -483,14 +508,20 @@ export interface ModelBase {
  */
 export function defineModel<
     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) | readonly (keyof FieldsOf<T> & string)[] | ((instance: any) => any)>,
+    const PK extends (keyof ModelFields<T> & string) | readonly (keyof ModelFields<T> & string)[],
+    const UNIQUE extends Record<string, IndexSpec<T>>,
+    const INDEX extends Record<string, IndexSpec<T>>,
 >(
     tableName: string,
     cls: T,
     opts?: { pk?: PK, unique?: UNIQUE, index?: INDEX, override?: boolean }
-): ModelClass<T, PKArgs<FieldsOf<T>, PK>, UNIQUE, INDEX> {
+): ModelClass<
+    StaticMembers<T>,
+    ModelFields<T>,
+    PKArgs<ModelFields<T>, PK>,
+    PublicIndexSpecs<UNIQUE>,
+    PublicIndexSpecs<INDEX>
+> {
     Object.setPrototypeOf(cls.prototype, ModelBase.prototype);
     const MockModel = function(this: any, initial?: Record<string, any>, txn: Transaction = currentTxn()) {
         this._txn = txn;
@@ -977,5 +1008,5 @@ export async function deleteEverything(): Promise<void> {
  * A model instance, including its user-defined fields.
  * @template FIELDS - The fields defined on this model.
  */
-export type Model<FIELDS> = FIELDS & ModelBase;
+export type Model<FIELDS, LOOKUP extends ModelLookup = ModelLookup> = FIELDS & ModelBase<LOOKUP>;
 export const Model = ModelBase;

package/src/types.ts

@@ -2,7 +2,7 @@ import DataPack from "./datapack.js";
 import { DatabaseError } from "olmdb/lowlevel";
 import { currentTxn } from "./edinburgh.js";
 import { Model, modelRegistry } from "./models.js";
-import type { AnyModelClass } from "./models.js";
+import type { AnyModelClass, ModelBase as ModelInstanceBase } from "./models.js";
 import { assert, addErrorPath, dbGet } from "./utils.js";
 
 
@@ -90,7 +90,7 @@ export interface TypeWrapper<T> {
 // Hidden type-only metadata used to widen lookup arguments without widening assignment types.
 export declare const QUERY_ARG: unique symbol;
 
-export type LinkTargetPKArgs<T extends new (...args: any) => any> =
+export type LinkTargetPKArgs<T extends { get(...args: any): any }> =
     T extends { get(...args: infer PKA): any } ? PKA : never;
 
 export type LinkPrimaryKeyInput<PKA extends readonly any[]> =
@@ -102,17 +102,15 @@ type QueryArgCarrier<QUERY> = {
     readonly [QUERY_ARG]?: QUERY;
 };
 
-type QueryAnnotated<T, QUERY> = T & QueryArgCarrier<QUERY>;
-
 export type FieldValue<TYPE extends TypeWrapper<any>> =
     TYPE extends TypeWrapper<infer T>
-        ? TYPE extends { readonly [QUERY_ARG]?: infer QUERY }
-            ? QueryAnnotated<T, Exclude<QUERY, undefined>>
-            : T
+        ? T
         : never;
 
 export type FieldQueryArg<T> =
-    T extends { readonly [QUERY_ARG]?: infer QUERY }
+    T extends ModelInstanceBase<infer LOOKUP>
+        ? T | LinkPrimaryKeyInput<LinkTargetPKArgs<LOOKUP>>
+        : T extends { readonly [QUERY_ARG]?: infer QUERY }
         ? Exclude<QUERY, undefined>
         : T;
 
@@ -657,8 +655,8 @@ export class LinkType<T extends new (...args: any[]) => Model<any>> extends Type
         pack.write(model.getPrimaryKey());
     }
     
-    deserialize(pack: DataPack) {
-        return this.getLinkedModel()._get(currentTxn(), pack.readUint8Array(), false);
+    deserialize(pack: DataPack): InstanceType<T> {
+        return this.getLinkedModel()._get(currentTxn(), pack.readUint8Array(), false) as InstanceType<T>;
     }
     
     getError(value: InstanceType<T>) {
@@ -826,7 +824,7 @@ export function record<const T>(inner: TypeWrapper<T>): TypeWrapper<Record<strin
 */
 export function link<const T extends new (...args: any[]) => Model<any>>(
     TargetModel: T,
-): TypeWrapper<InstanceType<T>> & QueryArgCarrier<InstanceType<T> | LinkPrimaryKeyInput<LinkTargetPKArgs<T>>>;
+): TypeWrapper<InstanceType<T>>;
 export function link<const T extends new (...args: any[]) => Model<any>>(TargetModel: () => T): TypeWrapper<InstanceType<T>>;
 export function link(TargetModel: any): TypeWrapper<any> {
     return new LinkType(TargetModel);