edinburgh 0.6.1 → 0.6.3

package/src/models.ts

@@ -1,7 +1,7 @@
 import * as lowlevel from "olmdb/lowlevel";
 import { DatabaseError } from "olmdb/lowlevel";
 import DataPack from "./datapack.js";
-import { deserializeType, serializeType, TypeWrapper, identifier } from "./types.js";
+import { deserializeType, serializeType, TypeWrapper, identifier, type FieldQueryArg, type FieldValue, type StripQueryArg } from "./types.js";
 import { transact, currentTxn, type Transaction } from "./edinburgh.js";
 
 import { PrimaryKey, NonPrimaryIndex, IndexRangeIterator, UniqueIndex, SecondaryIndex, FindOptions, VersionInfo } from "./indexes.js";
@@ -49,7 +49,7 @@ export interface FieldConfig<T> {
  * });
  * ```
  */
-export function field<T>(type: TypeWrapper<T>, options: Partial<FieldConfig<T>> = {}): T {
+export function field<TYPE extends TypeWrapper<any>>(type: TYPE, options: Partial<FieldConfig<FieldValue<TYPE>>> = {}): FieldValue<TYPE> {
     // Return the config object, but TypeScript sees it as type T
     options.type = type;
     return options as any;
@@ -66,28 +66,54 @@ export type Change = Record<any, any> | "created" | "deleted";
 
 type FieldsOf<T> = T extends new () => infer I ? I : never;
 
-type PKArgs<FIELDS, PK> =
-    PK extends readonly (keyof FIELDS & string)[]
-        ? { [I in keyof PK]: PK[I] extends keyof FIELDS ? FIELDS[PK[I]] : never }
-        : PK extends keyof FIELDS & string
-            ? [FIELDS[PK]]
+type PublicFields<FIELDS> = {
+    [K in keyof FIELDS]: StripQueryArg<FIELDS[K]>;
+};
+
+type QueryFields<FIELDS> = {
+    [K in keyof FIELDS]: FieldQueryArg<FIELDS[K]>;
+};
+
+type PublicModelOf<T extends new () => any> = Model<PublicFields<FieldsOf<T>>>;
+
+type IndexSpec<T extends new () => any> =
+    | (keyof FieldsOf<T> & string)
+    | readonly (keyof FieldsOf<T> & string)[]
+    | ((instance: PublicModelOf<T>) => any);
+
+type PKArgs<QUERY_FIELDS, PK> =
+    PK extends readonly (keyof QUERY_FIELDS & string)[]
+        ? { [I in keyof PK]: PK[I] extends keyof QUERY_FIELDS ? QUERY_FIELDS[PK[I]] : never }
+        : PK extends keyof QUERY_FIELDS & string
+            ? [QUERY_FIELDS[PK]]
             : [string];
 
-type IndexArgs<FIELDS, SPEC> =
-    SPEC extends readonly (keyof FIELDS & string)[]
-        ? { [I in keyof SPEC]: SPEC[I] extends keyof FIELDS ? FIELDS[SPEC[I]] : never }
-    : SPEC extends keyof FIELDS & string
-        ? [FIELDS[SPEC]]
+type IndexArgs<QUERY_FIELDS, SPEC> =
+    SPEC extends readonly (keyof QUERY_FIELDS & string)[]
+        ? { [I in keyof SPEC]: SPEC[I] extends keyof QUERY_FIELDS ? QUERY_FIELDS[SPEC[I]] : never }
+    : SPEC extends keyof QUERY_FIELDS & string
+        ? [QUERY_FIELDS[SPEC]]
     : SPEC extends (instance: any) => infer R
         ? 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, 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[]>>;
 
@@ -107,15 +133,15 @@ 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<PUBLIC_FIELDS, QUERY_FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX = {}> extends PrimaryKey<Model<PUBLIC_FIELDS>, readonly (keyof PUBLIC_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<PUBLIC_FIELDS>;
     // Cached list of non-primary fields used for value serialization.
-    _nonKeyFields!: (keyof FIELDS & string)[];
+    _nonKeyFields!: (keyof PUBLIC_FIELDS & string)[];
     // Lazy getter/setter descriptors installed on unloaded non-key fields.
     _lazyDescriptors: Record<string | symbol | number, PropertyDescriptor> = {};
     // Writable descriptors temporarily installed before hydrating value fields.
@@ -160,13 +186,13 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
                 this._lazyDescriptors[fieldName] = {
                     configurable: true,
                     enumerable: true,
-                    get(this: Model<FIELDS>) {
+                    get(this: Model<PUBLIC_FIELDS>) {
                         this.constructor._lazyLoad(this);
-                        return this[fieldName];
+                        return (this as any)[fieldName];
                     },
-                    set(this: Model<FIELDS>, value: any) {
+                    set(this: Model<PUBLIC_FIELDS>, value: any) {
                         this.constructor._lazyLoad(this);
-                        this[fieldName] = value;
+                        (this as any)[fieldName] = value;
                     },
                 };
                 this._resetDescriptors[fieldName] = {
@@ -200,20 +226,20 @@ 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): Model<PUBLIC_FIELDS>;
+    _get(txn: Transaction, args: PKA | Uint8Array, loadNow: true): Model<PUBLIC_FIELDS> | undefined;
+    _get(txn: Transaction, args: PKA | Uint8Array, loadNow: boolean | Uint8Array): Model<PUBLIC_FIELDS> | undefined {
         let key: Uint8Array;
         let keyParts: readonly any[] | undefined;
         if (args instanceof Uint8Array) {
             key = args;
         } else {
             key = this._argsToKeyBytes(args, false).toUint8Array();
-            keyParts = args;
+            keyParts = this._pkToArray(key);
         }
 
         const keyHash = hashBytes(key);
-        const cached = txn.instances.get(keyHash) as Model<FIELDS> | undefined;
+        const cached = txn.instances.get(keyHash) as Model<PUBLIC_FIELDS> | undefined;
         if (cached) {
             if (loadNow && loadNow !== true) {
                 Object.defineProperties(cached, this._resetDescriptors);
@@ -232,7 +258,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 Model<PUBLIC_FIELDS>;
         model._txn = txn;
         model._oldValues = {};
         txn.instances.set(keyHash, model);
@@ -259,7 +285,7 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
         return model;
     }
 
-    _lazyLoad(model: Model<FIELDS>) {
+    _lazyLoad(model: Model<PUBLIC_FIELDS>) {
         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');
@@ -269,23 +295,29 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
 
     /**
      * Load a model by primary key inside the current transaction.
+        *
+        * For `link(...)` primary-key fields, each argument may be the linked model
+        * instance or the linked model's primary key. Composite linked primary keys
+        * are passed as a tuple in that argument slot.
      *
      * @returns The matching model, or `undefined` if no row exists.
      */
-    get(...args: PKA): Model<FIELDS> | undefined {
+    get(...args: PKA): Model<PUBLIC_FIELDS> | undefined {
         return this._get(currentTxn(), args, true);
     }
 
     /**
      * Load a model by primary key without fetching its non-key fields immediately.
+        *
+        * Link-valued primary-key fields accept the same shorthand as `get()`.
      *
      * Accessing a lazy field later will load the remaining fields transparently.
      */
-    getLazy(...args: PKA): Model<FIELDS> {
+    getLazy(...args: PKA): Model<PUBLIC_FIELDS> {
         return this._get(currentTxn(), args, false);
     }
 
-    _pairToInstance(txn: Transaction, keyBuffer: ArrayBuffer, valueBuffer: ArrayBuffer): Model<FIELDS> {
+    _pairToInstance(txn: Transaction, keyBuffer: ArrayBuffer, valueBuffer: ArrayBuffer): Model<PUBLIC_FIELDS> {
         return this._get(txn, new Uint8Array(keyBuffer), new Uint8Array(valueBuffer))!;
     }
 
@@ -297,7 +329,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<PUBLIC_FIELDS>): Model<PUBLIC_FIELDS> {
         const keyArgs: any[] = [];
         for (const fieldName of this._indexFields.keys()) {
             if (!(fieldName in (obj as any))) {
@@ -305,7 +337,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 Model<PUBLIC_FIELDS> | undefined;
         if (existing) {
             for (const key in obj as any) {
                 if (!this._indexFields.has(key as any)) {
@@ -321,10 +353,12 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
      * Look up a model through a named unique index.
      *
      * @param name The name from the model's `unique` definition.
-     * @param args The unique-index key values.
+        * @param args The unique-index key values. For `link(...)` fields, pass
+        * either the linked model instance or the linked model's primary key. If the
+        * 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<QUERY_FIELDS, UNIQUE[K]>): Model<PUBLIC_FIELDS> | undefined {
         return (this._getSecondary(name) as any).getPK(...args);
     }
 
@@ -332,11 +366,12 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
      * Query rows through a named unique or secondary index.
      *
      * This mirrors `find()`, but targets a named entry from the model's `unique`
-     * or `index` registration.
+        * 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<QUERY_FIELDS, (UNIQUE & INDEX)[K]>, 'first'>): Model<PUBLIC_FIELDS> | undefined;
+    findBy<K extends string & keyof (UNIQUE & INDEX)>(name: K, opts: FindOptions<IndexArgs<QUERY_FIELDS, (UNIQUE & INDEX)[K]>, 'single'>): Model<PUBLIC_FIELDS>;
+    findBy<K extends string & keyof (UNIQUE & INDEX)>(name: K, opts?: FindOptions<IndexArgs<QUERY_FIELDS, (UNIQUE & INDEX)[K]>>): IndexRangeIterator<Model<PUBLIC_FIELDS>>;
     findBy(name: string, opts?: any): any {
         return this._getSecondary(name).find(opts);
     }
@@ -348,13 +383,13 @@ 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,
+        opts: FindOptions<IndexArgs<QUERY_FIELDS, (UNIQUE & INDEX)[K]>> & { limitSeconds?: number; limitRows?: number },
+        callback: (row: Model<PUBLIC_FIELDS>) => any,
     ): Promise<void> {
         return this._getSecondary(name).batchProcess(opts, callback as any);
     }
 
-    _loadValueFields(model: Model<FIELDS>, valueArray: Uint8Array) {
+    _loadValueFields(model: Model<PUBLIC_FIELDS>, valueArray: Uint8Array) {
         const valuePack = new DataPack(valueArray);
         const version = valuePack.readNumber();
 
@@ -390,7 +425,7 @@ class ModelClassRuntime<FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX =
         return info;
     }
 
-    _migrateValueFields(model: Model<FIELDS>, version: number, valuePack: DataPack) {
+    _migrateValueFields(model: Model<PUBLIC_FIELDS>, 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];
@@ -443,11 +478,11 @@ export const ModelClass = ModelClassRuntime;
  * @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, PUBLIC_FIELDS, QUERY_FIELDS, PKA extends readonly any[], UNIQUE = {}, INDEX = {}> =
+    STATICS
+    & ModelClassRuntime<PUBLIC_FIELDS, QUERY_FIELDS, PKA, UNIQUE, INDEX>
     & {
-        new (initial?: Partial<FieldsOf<T>>, txn?: Transaction): Model<FieldsOf<T>>;
+        new (initial?: Partial<PUBLIC_FIELDS>, txn?: Transaction): Model<PUBLIC_FIELDS>;
     };
 
 /**
@@ -475,13 +510,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 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>,
+    PublicFields<FieldsOf<T>>,
+    QueryFields<FieldsOf<T>>,
+    PKArgs<QueryFields<FieldsOf<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;

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";
 
 
@@ -87,6 +87,44 @@ export interface TypeWrapper<T> {
     default?(model: any): 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> =
+    T extends { get(...args: infer PKA): any } ? PKA : never;
+
+export type LinkPrimaryKeyInput<PKA extends readonly any[]> =
+    PKA extends readonly [infer ONLY]
+        ? ONLY | PKA
+        : PKA;
+
+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
+        : never;
+
+export type StripQueryArg<T> =
+    T extends ModelInstanceBase & { readonly [QUERY_ARG]?: any }
+        ? Model<{
+            [K in Exclude<keyof T, keyof ModelInstanceBase | typeof QUERY_ARG>]: T[K]
+        }>
+        : T extends { readonly [QUERY_ARG]?: any }
+            ? { [K in keyof T as K extends typeof QUERY_ARG ? never : K]: T[K] }
+            : T;
+
+export type FieldQueryArg<T> =
+    T extends { readonly [QUERY_ARG]?: infer QUERY }
+        ? Exclude<QUERY, undefined>
+        : T;
+
 
 class StringType extends TypeWrapper<string> {
     kind = 'string';
@@ -620,7 +658,7 @@ export class LinkType<T extends new (...args: any[]) => Model<any>> extends Type
     }
 
     getLinkedModel(): AnyModelClass {
-        if (!('getLazy' in this.TargetModel)) this.TargetModel = (this.TargetModel as unknown as () => T)();
+        if (!('getLazy' in (this.TargetModel as any))) this.TargetModel = (this.TargetModel as unknown as () => T)();
         return this.TargetModel as any;
     }
     
@@ -628,8 +666,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>) {
@@ -795,7 +833,9 @@ export function record<const T>(inner: TypeWrapper<T>): TypeWrapper<Record<strin
 * }, { pk: "id" });
 * ```
 */
-export function link<const T extends new (...args: any[]) => Model<any>>(TargetModel: T): TypeWrapper<InstanceType<T>>;
+export function link<const T extends new (...args: any[]) => Model<any>>(
+    TargetModel: T,
+): TypeWrapper<InstanceType<T>> & QueryArgCarrier<InstanceType<T> | LinkPrimaryKeyInput<LinkTargetPKArgs<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);