edinburgh 0.1.3 → 0.4.1

package/build/src/indexes.d.ts

@@ -1,21 +1,28 @@
-import * as olmdb from "olmdb";
-import { Bytes } from "./bytes.js";
-import { Model } from "./models.js";
-/** @internal Symbol used to access the underlying model from a proxy */
-export declare const TARGET_SYMBOL: unique symbol;
+import DataPack from "./datapack.js";
+import { Model, Transaction } from "./models.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]];
 };
+/** Cached information about a specific version of a primary index's value format. */
+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. */
+    secondaryKeys: Set<string>;
+}
 /**
  * Iterator for range queries on indexes.
  * Handles common iteration logic for both primary and unique indexes.
  * Implements both Iterator and Iterable interfaces for efficiency.
  */
-declare class IndexRangeIterator<M extends typeof Model, F extends readonly (keyof InstanceType<M> & string)[]> implements Iterator<InstanceType<M>>, Iterable<InstanceType<M>> {
-    private iterator;
+export declare class IndexRangeIterator<M extends typeof Model> implements Iterator<InstanceType<M>>, Iterable<InstanceType<M>> {
+    private txn;
+    private iteratorId;
     private indexId;
     private parentIndex;
-    constructor(iterator: olmdb.DbIterator<any, any> | undefined, indexId: number, parentIndex: BaseIndex<M, F>);
+    constructor(txn: Transaction, iteratorId: number, indexId: number, parentIndex: BaseIndex<M, any>);
     [Symbol.iterator](): Iterator<InstanceType<M>>;
     next(): IteratorResult<InstanceType<M>>;
     count(): number;
@@ -46,72 +53,45 @@ type FindOptions<ARG_TYPES extends readonly any[]> = (({
 export declare abstract class BaseIndex<M extends typeof Model, const F extends readonly (keyof InstanceType<M> & string)[]> {
     _fieldNames: F;
     _MyModel: M;
+    _fieldTypes: Map<keyof InstanceType<M> & string, TypeWrapper<any>>;
+    _fieldCount: number;
+    _resetIndexFieldDescriptors: Record<string | symbol | number, PropertyDescriptor>;
     /**
      * 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, isPrimary?: boolean);
-    _cachedIndexId?: number;
-    /**
-     * Deserialize index key bytes back to field values.
-     * @param bytes - Bytes to read from.
-     * @returns Array of field values.
-     */
-    _deserializeKey(bytes: Bytes): IndexArgTypes<M, F>;
+    constructor(MyModel: M, _fieldNames: F);
+    _delayedInit(): Promise<void>;
+    _indexId?: number;
+    /** Human-readable signature for version tracking, e.g. "secondary category:string" */
+    _signature?: string;
     /**
-     * Extract model from iterator entry - implemented differently by each index type.
-     * @param keyBytes - Key bytes with index ID already read.
-     * @param valueBytes - Value bytes from the entry.
-     * @returns Model instance or undefined.
-     * @internal
-     */
-    abstract _getModelFromEntry(keyBytes: Bytes, valueBytes: Bytes): InstanceType<M> | undefined;
-    /**
-     * Serialize field values to bytes for index key.
+     * 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).
-     * @param bytes - Bytes to write to.
+     * @returns A Bytes instance containing the index id and serialized key parts.
      * @internal
      */
-    _serializeArgs(args: Partial<IndexArgTypes<M, F>> | readonly any[], bytes: Bytes): void;
+    _argsToKeyBytes(args: [], allowPartial: boolean): DataPack;
+    _argsToKeyBytes(args: Partial<IndexArgTypes<M, F>>, allowPartial: boolean): DataPack;
     /**
-     * Create database key from field values.
-     * @param args - Field values.
-     * @returns Database key bytes.
-     */
-    _getKeyFromArgs(args: IndexArgTypes<M, F>): Uint8Array;
-    /**
-     * Serialize model fields to bytes for index key.
-     * @param model - Model instance.
-     * @param bytes - Bytes to write to.
-     */
-    _serializeModel(model: InstanceType<M>, bytes: Bytes): void;
-    /**
-     * Create database key from model instance.
-     * @param model - Model instance.
-     * @param includeIndexId - Whether to include index ID in key.
-     * @returns Database key bytes or undefined if skipped.
-     * @internal
-     */
-    _getKeyFromModel(model: InstanceType<M>, includeIndexId: boolean): Uint8Array;
-    /**
-     * Extract field values from model for this index.
-     * @param model - Model instance.
-     * @returns Field values or undefined if should be skipped.
+     * 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
      */
-    _modelToArgs(model: InstanceType<M>): IndexArgTypes<M, F> | undefined;
-    /**
-     * Get or create unique index ID for this index.
-     * @returns Numeric index ID.
-     */
-    _getIndexId(): number;
+    abstract _pairToInstance(txn: Transaction, keyBuffer: ArrayBuffer, valueBuffer: ArrayBuffer): InstanceType<M>;
+    _hasNullIndexValues(data: Record<string, any>): boolean;
+    abstract _serializeKey(primaryKey: Uint8Array, data: Record<string, any>): Uint8Array;
+    _serializeKeyFields(data: Record<string, any>): DataPack;
     /**
-     * Check if indexing should be skipped for a model instance.
-     * @param model - Model instance.
-     * @returns true if indexing should be skipped.
+     * Retrieve (or create) a stable index ID from the DB, with retry on transaction races.
+     * Sets `this._indexId` on success.
      */
-    _checkSkip(model: InstanceType<M>): boolean;
+    _retrieveIndexId(): Promise<void>;
+    abstract _delete(txn: Transaction, primaryKey: Uint8Array, model: InstanceType<M>): void;
+    abstract _write(txn: Transaction, primaryKey: Uint8Array, model: InstanceType<M>): void;
     /**
      * Find model instances using flexible range query options.
      *
@@ -170,14 +150,25 @@ export declare abstract class BaseIndex<M extends typeof Model, const F extends
      * }
      * ```
      */
-    find(opts?: FindOptions<IndexArgTypes<M, F>>): IndexRangeIterator<M, F>;
+    _computeKeyBounds(opts: FindOptions<IndexArgTypes<M, F>>): [DataPack | undefined, DataPack | undefined] | null;
+    find(opts?: FindOptions<IndexArgTypes<M, F>>): IndexRangeIterator<M>;
     /**
-     * Save index entry for a model instance.
-     * @param model - Model instance to save.
-     * @param originalKey - Original key if updating.
+     * Process all 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.
+     *
+     * @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
      */
-    abstract _save(model: InstanceType<M>, originalKey?: Uint8Array): Uint8Array | undefined;
+    batchProcess(opts: (FindOptions<IndexArgTypes<M, F>> & {
+        limitSeconds?: number;
+        limitRows?: number;
+    }) | undefined, callback: (row: InstanceType<M>) => void | Promise<void>): Promise<void>;
     abstract _getTypeName(): string;
+    toString(): string;
 }
 /**
  * Primary index that stores the actual model data.
@@ -186,7 +177,22 @@ export declare abstract class BaseIndex<M extends typeof Model, const F extends
  * @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> {
+    _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.
@@ -199,20 +205,27 @@ export declare class PrimaryIndex<M extends typeof Model, const F extends readon
      */
     get(...args: IndexArgTypes<M, F>): InstanceType<M> | undefined;
     /**
-     * Extract model from iterator entry for primary index.
-     * @param keyBytes - Key bytes with index ID already read.
-     * @param valueBytes - Value bytes from the entry.
-     * @returns Model instance or undefined.
-     * @internal
+     * 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.
      */
-    _getModelFromEntry(keyBytes: Bytes, valueBytes: Bytes): InstanceType<M> | undefined;
-    /**
-     * Save primary index entry.
-     * @param model - Model instance.
-     * @param originalKey - Original key if updating.
-     */
-    _save(model: InstanceType<M>, originalKey?: Uint8Array): Uint8Array;
+    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;
+    _serializeKey(primaryKey: Uint8Array, _data: Record<string, any>): Uint8Array;
+    _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>;
     _getTypeName(): string;
+    _write(txn: Transaction, primaryKey: Uint8Array, data: Record<string, any>): void;
+    _delete(txn: Transaction, primaryKey: Uint8Array, _data: Record<string, any>): void;
 }
 /**
  * Unique index that stores references to the primary key.
@@ -221,6 +234,7 @@ export declare class PrimaryIndex<M extends typeof Model, const F extends readon
  * @template F - The field names that make up this index.
  */
 export declare class UniqueIndex<M extends typeof Model, const F extends readonly (keyof InstanceType<M> & string)[]> extends BaseIndex<M, F> {
+    constructor(MyModel: M, fieldNames: F);
     /**
      * Get a model instance by unique index key values.
      * @param args - The unique index key values.
@@ -232,20 +246,10 @@ export declare class UniqueIndex<M extends typeof Model, const F extends readonl
      * ```
      */
     get(...args: IndexArgTypes<M, F>): InstanceType<M> | undefined;
-    /**
-     * Extract model from iterator entry for unique index.
-     * @param keyBytes - Key bytes with index ID already read.
-     * @param valueBytes - Value bytes from the entry.
-     * @returns Model instance or undefined.
-     * @internal
-     */
-    _getModelFromEntry(keyBytes: Bytes, valueBytes: Bytes): InstanceType<M> | undefined;
-    /**
-     * Save unique index entry.
-     * @param model - Model instance.
-     * @param originalKey - Original key if updating.
-     */
-    _save(model: InstanceType<M>, originalKey?: Uint8Array): Uint8Array | undefined;
+    _serializeKey(primaryKey: Uint8Array, data: Record<string, any>): Uint8Array;
+    _delete(txn: Transaction, primaryKey: Uint8Array, data: Record<string, any>): void;
+    _write(txn: Transaction, primaryKey: Uint8Array, data: Record<string, any>): void;
+    _pairToInstance(txn: Transaction, keyBuffer: ArrayBuffer, valueBuffer: ArrayBuffer): InstanceType<M>;
     _getTypeName(): string;
 }
 /**
@@ -255,26 +259,11 @@ export declare class UniqueIndex<M extends typeof Model, const F extends readonl
  * @template F - The field names that make up this index.
  */
 export declare class SecondaryIndex<M extends typeof Model, const F extends readonly (keyof InstanceType<M> & string)[]> extends BaseIndex<M, F> {
-    /**
-     * Save secondary index entry.
-     * @param model - Model instance.
-     * @param originalKey - Original key if updating.
-     */
-    _save(model: InstanceType<M>, originalKey?: Uint8Array): Uint8Array | undefined;
-    /**
-     * Extract model from iterator entry for secondary index.
-     * @param keyBytes - Key bytes with index ID already read.
-     * @param valueBytes - Value bytes from the entry.
-     * @returns Model instance or undefined.
-     * @internal
-     */
-    _getModelFromEntry(keyBytes: Bytes, valueBytes: Bytes): InstanceType<M> | undefined;
-    /**
-     * Create secondary index key that includes both index fields and primary key.
-     * @param model - Model instance.
-     * @returns Database key bytes or undefined if skipped.
-     */
-    _getKeyFromModel(model: InstanceType<M>, includeIndexId: boolean): Uint8Array;
+    constructor(MyModel: M, fieldNames: F);
+    _pairToInstance(txn: Transaction, keyBuffer: ArrayBuffer, _valueBuffer: ArrayBuffer): InstanceType<M>;
+    _serializeKey(primaryKey: Uint8Array, model: InstanceType<M>): Uint8Array;
+    _write(txn: Transaction, primaryKey: Uint8Array, model: InstanceType<M>): void;
+    _delete(txn: Transaction, primaryKey: Uint8Array, model: InstanceType<M>): void;
     _getTypeName(): string;
 }
 export type Index<M extends typeof Model, F extends readonly (keyof InstanceType<M> & string)[]> = PrimaryIndex<M, F> | UniqueIndex<M, F> | SecondaryIndex<M, F>;