edinburgh 0.5.0 → 0.6.0

package/build/src/indexes.d.ts

@@ -1,15 +1,28 @@
 import DataPack from "./datapack.js";
-import { Model, Transaction } from "./models.js";
+import { type Transaction } from "./edinburgh.js";
 import { TypeWrapper } from "./types.js";
-type IndexArgTypes<M extends typeof Model<any>, F extends readonly (keyof InstanceType<M> & string)[]> = {
-    [I in keyof F]: InstanceType<M>[F[I]];
+type IndexItem = {
+    _setLoadedField(fieldName: string, value: any): void;
+    _restoreLazyFields?(): void;
+};
+type PrimaryKeyItem = IndexItem & {
+    _oldValues: Record<string, any> | undefined | null | false;
+    _primaryKey: Uint8Array | undefined;
+    _txn: Transaction;
+    _setPrimaryKey(key: Uint8Array, hash?: number): void;
+};
+type FieldTypes = ReadonlyMap<string, TypeWrapper<any>>;
+type LoadPrimary<ITEM> = (txn: Transaction, primaryKey: Uint8Array, loadNow: boolean | Uint8Array) => ITEM | undefined;
+type QueueInitialization = () => void;
+type IndexArgTypes<ITEM, F extends readonly (keyof ITEM & string)[]> = {
+    [I in keyof F]: ITEM[F[I]];
 };
 /** Cached information about a specific version of a primary index's value format. */
 export interface VersionInfo {
     migrateHash: number;
     /** Non-key field names → TypeWrappers for deserialization of this version's data. */
     nonKeyFields: Map<string, TypeWrapper<any>>;
-    /** Set of serialized secondary index signatures that existed in this version. */
+    /** Set of serialized secondary index signatures that existed in this version's data. */
     secondaryKeys: Set<string>;
 }
 /**
@@ -17,18 +30,29 @@ export interface VersionInfo {
  * Handles common iteration logic for both primary and unique indexes.
  * Extends built-in Iterator to provide map/filter/reduce/toArray/etc.
  */
-export declare class IndexRangeIterator<M extends typeof Model> extends Iterator<InstanceType<M>> {
+export declare class IndexRangeIterator<ITEM> extends Iterator<ITEM> {
     private txn;
     private iteratorId;
-    private indexId;
     private parentIndex;
-    constructor(txn: Transaction, iteratorId: number, indexId: number, parentIndex: BaseIndex<M, any>);
+    constructor(txn: Transaction, iteratorId: number, parentIndex: BaseIndex<ITEM, any>);
     [Symbol.iterator](): this;
-    next(): IteratorResult<InstanceType<M>>;
+    next(): IteratorResult<ITEM>;
     count(): number;
-    fetch(): InstanceType<M> | undefined;
+    fetch(): ITEM | undefined;
 }
 type ArrayOrOnlyItem<ARG_TYPES extends readonly any[]> = ARG_TYPES extends readonly [infer A] ? (A | Partial<ARG_TYPES>) : Partial<ARG_TYPES>;
+/**
+ * Range-query options accepted by `find()`, `findBy()`, `batchProcess()`, and `batchProcessBy()`.
+ *
+ * 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.
+ *
+ * @template ARG_TYPES - Tuple of index argument types.
+ * @template FETCH - Optional fetch mode used by overloads that return one row.
+ */
 export type FindOptions<ARG_TYPES extends readonly any[], FETCH extends 'first' | 'single' | undefined = undefined> = (({
     is: ArrayOrOnlyItem<ARG_TYPES>;
 } | (({
@@ -50,235 +74,91 @@ export type FindOptions<ARG_TYPES extends readonly any[], FETCH extends 'first'
  * Base class for database indexes for efficient lookups on model fields.
  *
  * Indexes enable fast queries on specific field combinations and enforce uniqueness constraints.
- *
- * @template M - The model class this index belongs to.
- * @template F - The field names that make up this index.
  */
-export declare abstract class BaseIndex<M extends typeof Model, const F extends readonly (keyof InstanceType<M> & string)[], ARGS extends readonly any[] = IndexArgTypes<M, F>> {
-    _fieldNames: F;
-    _MyModel: M;
-    _fieldTypes: Map<keyof InstanceType<M> & string, TypeWrapper<any>>;
-    _fieldCount: number;
+export declare abstract class BaseIndex<ITEM, const F extends readonly (keyof ITEM & string)[], ARGS extends readonly any[] = IndexArgTypes<ITEM, F>> {
+    tableName: string;
+    _indexFields: Map<F[number], TypeWrapper<any>>;
     _computeFn?: (data: any) => any[];
-    /**
-     * Create a new index.
-     * @param MyModel - The model class this index belongs to.
-     * @param _fieldNames - Array of field names that make up this index.
-     */
-    constructor(MyModel: M, _fieldNames: F);
-    _delayedInit(): Promise<void>;
     _indexId?: number;
-    /** Human-readable signature for version tracking, e.g. "secondary category:string" */
     _signature?: string;
-    /**
-     * Serialize array of key values to a (index-id prefixed) Bytes instance that can be used as a key.
-     * @param args - Field values to serialize (can be partial for range queries).
-     * @returns A Bytes instance containing the index id and serialized key parts.
-     * @internal
-     */
+    constructor(tableName: string, fieldNames: F);
+    _initializeIndex(fields: FieldTypes, reset?: boolean, primaryFieldTypes?: FieldTypes): Promise<void>;
     _argsToKeyBytes(args: [], allowPartial: boolean): DataPack;
     _argsToKeyBytes(args: Partial<ARGS>, allowPartial: boolean): DataPack;
+    abstract _pairToInstance(txn: Transaction, keyBuffer: ArrayBuffer, valueBuffer: ArrayBuffer): ITEM;
+    abstract _getTypeName(): string;
+    _retrieveIndexId(fields: FieldTypes, primaryFieldTypes?: FieldTypes): Promise<void>;
+    _computeKeyBounds(opts: FindOptions<ARGS>): [DataPack | undefined, DataPack | undefined] | null;
     /**
-     * Extract model from iterator entry - implemented differently by each index type.
-     * @param keyBuffer - Key bytes (including index id).
-     * @param valueBuffer - Value bytes from the entry.
-     * @returns Model instance or undefined.
-     * @internal
-     */
-    abstract _pairToInstance(txn: Transaction, keyBuffer: ArrayBuffer, valueBuffer: ArrayBuffer): InstanceType<M>;
-    /**
-     * Retrieve (or create) a stable index ID from the DB, with retry on transaction races.
-     * Sets `this._indexId` on success.
-     */
-    _retrieveIndexId(): Promise<void>;
-    /**
-     * Find model instances using flexible range query options.
-     *
-     * Supports exact matches, inclusive/exclusive range queries, and reverse iteration.
-     * For single-field indexes, you can pass values directly or in arrays.
-     * For multi-field indexes, pass arrays or partial arrays for prefix matching.
+     * Find rows using exact-match or range-query options.
      *
-     * @param opts - Query options object
-     * @param opts.is - Exact match (sets both `from` and `to` to same value)
-     * @param opts.from - Range start (inclusive)
-     * @param opts.after - Range start (exclusive)
-     * @param opts.to - Range end (inclusive)
-     * @param opts.before - Range end (exclusive)
-     * @param opts.reverse - Whether to iterate in reverse order
-     * @returns An iterable of model instances matching the query
+     * Supports exact matches, inclusive and exclusive bounds, open-ended ranges,
+     * and reverse iteration. For single-field indexes, values can be passed
+     * directly. For composite indexes, pass tuples or partial tuples.
      *
      * @example
      * ```typescript
-     * // Exact match
-     * for (const user of User.byEmail.find({is: "john@example.com"})) {
-     *   console.log(user.name);
-     * }
-     *
-     * // Range query (inclusive)
-     * for (const user of User.byEmail.find({from: "a@", to: "m@"})) {
-     *   console.log(user.email);
-     * }
-     *
-     * // Range query (exclusive)
-     * for (const user of User.byEmail.find({after: "a@", before: "m@"})) {
-     *   console.log(user.email);
-     * }
-     *
-     * // Open-ended ranges
-     * for (const user of User.byEmail.find({from: "m@"})) { // m@ and later
-     *   console.log(user.email);
-     * }
-     *
-     * for (const user of User.byEmail.find({to: "m@"})) { // up to and including m@
-     *   console.log(user.email);
-     * }
-     *
-     * // Reverse iteration
-     * for (const user of User.byEmail.find({reverse: true})) {
-     *   console.log(user.email); // Z to A order
-     * }
-     *
-     * // Multi-field index prefix matching
-     * for (const item of CompositeModel.find({from: ["electronics", "phones"]})) {
-     *   console.log(item.name); // All electronics/phones items
-     * }
-     *
-     * // For single-field indexes, you can use the value directly
-     * for (const user of User.byEmail.find({is: "john@example.com"})) {
-     *   console.log(user.name);
-     * }
+     * const exact = User.find({ is: "user-123", fetch: "first" });
+     * const email = [...User.findBy("email", { from: "a@test.com", to: "m@test.com" })];
+     * const reverse = [...Product.findBy("category", { is: "electronics", reverse: true })];
      * ```
      */
-    _computeKeyBounds(opts: FindOptions<ARGS>): [DataPack | undefined, DataPack | undefined] | null;
-    find(opts?: FindOptions<ARGS, 'first'>): InstanceType<M> | undefined;
-    find(opts: FindOptions<ARGS, 'single'>): InstanceType<M>;
-    find(opts?: FindOptions<ARGS>): IndexRangeIterator<M>;
+    find(opts: FindOptions<ARGS, 'first'>): ITEM | undefined;
+    find(opts: FindOptions<ARGS, 'single'>): ITEM;
+    find(opts?: FindOptions<ARGS>): IndexRangeIterator<ITEM>;
     /**
-     * Process all matching rows in batched transactions.
+     * Process matching rows in batched transactions.
      *
-     * Uses the same query options as {@link find}. The batch is committed and a new
-     * transaction started once either `limitSeconds` or `limitRows` is exceeded.
+     * Uses the same range options as {@link find}, plus optional row and time
+     * limits that control when the current transaction is committed and a new one starts.
      *
-     * @param opts - Query options (same as `find()`), plus:
-     * @param opts.limitSeconds - Max seconds per transaction batch (default: 1)
-     * @param opts.limitRows - Max rows per transaction batch (default: 4096)
-     * @param callback - Called for each matching row within a transaction
+     * @param opts Query options plus batch limits.
+     * @param callback Called for each matching row inside a transaction.
      */
     batchProcess(opts: (FindOptions<ARGS> & {
         limitSeconds?: number;
         limitRows?: number;
-    }) | undefined, callback: (row: InstanceType<M>) => void | Promise<void>): Promise<void>;
-    abstract _getTypeName(): string;
+    }) | undefined, callback: (row: ITEM) => void | Promise<void>): Promise<void>;
     toString(): string;
 }
-/**
- * Primary index that stores the actual model data.
- *
- * @template M - The model class this index belongs to.
- * @template F - The field names that make up this index.
- */
-export declare class PrimaryIndex<M extends typeof Model, const F extends readonly (keyof InstanceType<M> & string)[]> extends BaseIndex<M, F, IndexArgTypes<M, F>> {
-    _nonKeyFields: (keyof InstanceType<M> & string)[];
-    _lazyDescriptors: Record<string | symbol | number, PropertyDescriptor>;
-    _resetDescriptors: Record<string | symbol | number, PropertyDescriptor>;
-    _freezePrimaryKeyDescriptors: Record<string | symbol | number, PropertyDescriptor>;
-    /** Current version number for this primary index's value format. */
-    _currentVersion: number;
-    /** Hash of the current migrate() function source, or 0 if none. */
-    _currentMigrateHash: number;
-    /** Cached version info for old versions (loaded on demand). */
-    _versions: Map<number, VersionInfo>;
-    constructor(MyModel: M, fieldNames: F);
-    _delayedInit(): Promise<void>;
-    /** Serialize the current version fingerprint as a DataPack object. */
-    _serializeVersionValue(): Uint8Array;
-    /** Look up or create the current version number for this primary index. */
-    _initVersioning(): Promise<void>;
-    /**
-     * Get a model instance by primary key values.
-     * @param args - The primary key values.
-     * @returns The model instance if found, undefined otherwise.
-     *
-     * @example
-     * ```typescript
-     * const user = User.get("john_doe");
-     * ```
-     */
-    get(...args: IndexArgTypes<M, F>): InstanceType<M> | undefined;
-    /**
-     * 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.
-     * @param args Primary key field values. (Or a single Uint8Array containing the key.)
-     * @returns The (lazily loaded) model instance.
-     */
-    getLazy(...args: IndexArgTypes<M, F>): InstanceType<M>;
-    _get(txn: Transaction, args: IndexArgTypes<M, F> | Uint8Array, loadNow: false | Uint8Array): InstanceType<M>;
-    _get(txn: Transaction, args: IndexArgTypes<M, F> | Uint8Array, loadNow: true): InstanceType<M> | undefined;
-    /**
-     * Serialize primary key bytes from field values: indexId + typed field values.
-     */
-    _serializeKey(data: Record<string, any>): DataPack;
-    _lazyNow(model: InstanceType<M>): void;
-    _setNonKeyValues(model: InstanceType<M>, valueArray: Uint8Array): void;
-    /** Load a version's info from DB, caching the result. */
-    _loadVersionInfo(txnId: number, version: number): VersionInfo;
-    /** Deserialize and migrate a row from an old version. */
-    _migrateFromVersion(model: InstanceType<M>, version: number, valuePack: DataPack): void;
-    _keyToArray(key: Uint8Array): IndexArgTypes<M, F>;
-    _pairToInstance(txn: Transaction, keyBuffer: ArrayBuffer, valueBuffer: ArrayBuffer): InstanceType<M>;
+export declare abstract class PrimaryKey<ITEM extends PrimaryKeyItem, const F extends readonly (keyof ITEM & string)[], ARGS extends readonly any[] = IndexArgTypes<ITEM, F>> extends BaseIndex<ITEM, F, ARGS> {
     _getTypeName(): string;
-    _write(txn: Transaction, primaryKey: Uint8Array, data: Record<string, any>): void;
-    _delete(txn: Transaction, primaryKey: Uint8Array, _data: Record<string, any>): void;
+    abstract _serializeValue(data: Record<string, any>): Uint8Array;
+    _versionInfoKey(version: number): Uint8Array;
+    _ensureVersionEntry(currentValueBytes: Uint8Array): Promise<{
+        version: number;
+        created: boolean;
+    }>;
+    _serializePK(data: Record<string, any>): DataPack;
+    _pkToArray(key: Uint8Array): ARGS;
+    _writePK(txn: Transaction, primaryKey: Uint8Array, data: Record<string, any>): void;
+    _deletePK(txn: Transaction, primaryKey: Uint8Array, _data: Record<string, any>): void;
 }
-/**
- * Abstract base for all non-primary indexes (unique and secondary).
- * Provides shared key serialization, write/delete/update logic.
- */
-export declare abstract class NonPrimaryIndex<M extends typeof Model, const F extends readonly (keyof InstanceType<M> & string)[], ARGS extends readonly any[] = IndexArgTypes<M, F>> extends BaseIndex<M, F, ARGS> {
+export declare abstract class NonPrimaryIndex<ITEM extends IndexItem, const F extends readonly (keyof ITEM & string)[], ARGS extends readonly any[] = IndexArgTypes<ITEM, F>> extends BaseIndex<ITEM, F, ARGS> {
+    protected _loadPrimary: LoadPrimary<ITEM>;
     _resetIndexFieldDescriptors: Record<string | symbol | number, PropertyDescriptor>;
-    constructor(MyModel: M, fieldsOrFn: F | ((data: any) => any[]));
-    _delayedInit(): Promise<void>;
-    /**
-     * Build DataPack key prefixes (indexId + field/computed values). Returns [] to skip indexing.
-     * SecondaryIndex appends the primary key to each pack before converting to Uint8Array.
-     */
+    constructor(tableName: string, fieldsOrFn: F | ((data: any) => any[]), _loadPrimary: LoadPrimary<ITEM>, queueInitialization: QueueInitialization);
+    _initializeIndex(fields: FieldTypes, reset?: boolean, primaryFieldTypes?: FieldTypes): Promise<void>;
     _buildKeyPacks(data: Record<string, any>): DataPack[];
-    /** Serialize all index keys. Default: key = indexId + fields. */
     _serializeKeys(primaryKey: Uint8Array, data: Record<string, any>): Uint8Array[];
-    /** Write a single pre-serialized key — subclasses define value and uniqueness check. */
     abstract _writeKey(txn: Transaction, key: Uint8Array, primaryKey: Uint8Array): void;
-    _write(txn: Transaction, primaryKey: Uint8Array, model: InstanceType<M>): void;
-    _delete(txn: Transaction, primaryKey: Uint8Array, model: InstanceType<M>): void;
-    /**
-     * Granular update: diff old vs new keys and only insert/delete what changed.
-     * For non-computed indexes, uses a fast path that checks which fields changed.
-     */
-    _update(txn: Transaction, primaryKey: Uint8Array, newData: InstanceType<M>, oldData: Record<string, any>): number;
+    _write(txn: Transaction, primaryKey: Uint8Array, model: ITEM): void;
+    _delete(txn: Transaction, primaryKey: Uint8Array, model: ITEM): void;
+    _update(txn: Transaction, primaryKey: Uint8Array, newData: ITEM, oldData: Record<string, any>): number;
 }
-/**
- * Unique index that stores references to the primary key.
- */
-export declare class UniqueIndex<M extends typeof Model, const F extends readonly (keyof InstanceType<M> & string)[], ARGS extends readonly any[] = IndexArgTypes<M, F>> extends NonPrimaryIndex<M, F, ARGS> {
-    get(...args: ARGS): InstanceType<M> | undefined;
-    _writeKey(txn: Transaction, key: Uint8Array, primaryKey: Uint8Array): void;
-    _pairToInstance(txn: Transaction, keyBuffer: ArrayBuffer, valueBuffer: ArrayBuffer): InstanceType<M>;
+export declare class UniqueIndex<ITEM extends IndexItem, const F extends readonly (keyof ITEM & string)[], ARGS extends readonly any[] = IndexArgTypes<ITEM, F>> extends NonPrimaryIndex<ITEM, F, ARGS> {
+    constructor(tableName: string, fieldsOrFn: F | ((data: any) => any[]), loadPrimary: LoadPrimary<ITEM>, queueInitialization: QueueInitialization);
     _getTypeName(): string;
+    getPK(...args: ARGS): ITEM | undefined;
+    _writeKey(txn: Transaction, key: Uint8Array, primaryKey: Uint8Array): void;
+    _pairToInstance(txn: Transaction, keyBuffer: ArrayBuffer, valueBuffer: ArrayBuffer): ITEM;
 }
-/**
- * Secondary index for non-unique lookups.
- */
-export declare class SecondaryIndex<M extends typeof Model, const F extends readonly (keyof InstanceType<M> & string)[], ARGS extends readonly any[] = IndexArgTypes<M, F>> extends NonPrimaryIndex<M, F, ARGS> {
-    _pairToInstance(txn: Transaction, keyBuffer: ArrayBuffer, _valueBuffer: ArrayBuffer): InstanceType<M>;
+export declare class SecondaryIndex<ITEM extends IndexItem, const F extends readonly (keyof ITEM & string)[], ARGS extends readonly any[] = IndexArgTypes<ITEM, F>> extends NonPrimaryIndex<ITEM, F, ARGS> {
+    constructor(tableName: string, fieldsOrFn: F | ((data: any) => any[]), loadPrimary: LoadPrimary<ITEM>, queueInitialization: QueueInitialization);
+    _getTypeName(): string;
+    _pairToInstance(txn: Transaction, keyBuffer: ArrayBuffer, _valueBuffer: ArrayBuffer): ITEM;
     _serializeKeys(primaryKey: Uint8Array, data: Record<string, any>): Uint8Array[];
     _writeKey(txn: Transaction, key: Uint8Array, _primaryKey: Uint8Array): void;
-    _getTypeName(): string;
 }
-/**
- * Dump database contents for debugging.
- *
- * Prints all indexes and their data to the console for inspection.
- * This is primarily useful for development and debugging purposes.
- */
 export declare function dump(): void;
 export {};