edinburgh 0.1.2

package/build/src/edinburgh.js

@@ -0,0 +1,93 @@
+import * as olmdb from "olmdb";
+import { MODIFIED_INSTANCES_SYMBOL, resetModelCaches } from "./models.js";
+// Re-export public API from models
+export { Model, registerModel, field, setOnSaveCallback } from "./models.js";
+// Re-export public API from types (only factory functions and instances)
+export { 
+// Pre-defined type instances
+string, number, boolean, identifier, undef, 
+// Type factory functions
+opt, or, array, literal, link, } from "./types.js";
+// Re-export public API from indexes
+export { index, primary, unique, dump, } from "./indexes.js";
+export { BaseIndex, UniqueIndex, PrimaryIndex } from './indexes.js';
+// Re-export from OLMDB
+export { init, onCommit, onRevert, getTransactionData, setTransactionData, DatabaseError } from "olmdb";
+/**
+* Executes a function within a database transaction context.
+*
+* Loading models (also through links in other models) and changing models can only be done from
+* within a transaction.
+*
+* Transactions have a consistent view of the database, and changes made within a transaction are
+* isolated from other transactions until they are committed. In case a commit clashes with changes
+* made by another transaction, the transaction function will automatically be re-executed up to 10
+* times.
+*
+* @template T - The return type of the transaction function.
+* @param fn - The function to execute within the transaction context.
+* @returns A promise that resolves with the function's return value.
+* @throws {TypeError} If nested transactions are attempted.
+* @throws {DatabaseError} With code "RACING_TRANSACTION" if the transaction fails after retries due to conflicts.
+* @throws {DatabaseError} With code "TRANSACTION_FAILED" if the transaction fails for other reasons.
+* @throws {DatabaseError} With code "TXN_LIMIT" if maximum number of transactions is reached.
+* @throws {DatabaseError} With code "LMDB-{code}" for LMDB-specific errors.
+*
+* @example
+* ```typescript
+* const paid = await E.transact(() => {
+*   const user = User.load("john_doe");
+*   // This is concurrency-safe - the function will rerun if it is raced by another transaction
+*   if (user.credits > 0) {
+*     user.credits--;
+*     return true;
+*   }
+*   return false;
+* });
+* ```
+* ```typescript
+* // Transaction with automatic retry on conflicts
+* await E.transact(() => {
+*   const counter = Counter.load("global") || new Counter({id: "global", value: 0});
+*   counter.value++;
+* });
+* ```
+*/
+export function transact(fn) {
+    return olmdb.transact(() => {
+        const modifiedInstances = new Set();
+        olmdb.setTransactionData(MODIFIED_INSTANCES_SYMBOL, modifiedInstances);
+        const savedInstances = new Set();
+        try {
+            const result = fn();
+            // Save all modified instances before committing.
+            while (modifiedInstances.size > 0) {
+                // Back referencing can cause models to be scheduled for save() a second time,
+                // which is why we require the outer loop.
+                for (const instance of modifiedInstances) {
+                    instance._save();
+                    savedInstances.add(instance);
+                    modifiedInstances.delete(instance);
+                }
+            }
+            return result;
+        }
+        catch (error) {
+            // Discard changes on all saved and still unsaved instances
+            for (const instance of savedInstances)
+                instance.preventPersist();
+            for (const instance of modifiedInstances)
+                instance.preventPersist();
+            throw error;
+        }
+    });
+}
+export async function deleteEverything() {
+    await olmdb.transact(() => {
+        for (const { key } of olmdb.scan()) {
+            olmdb.del(key);
+        }
+    });
+    await resetModelCaches();
+}
+//# sourceMappingURL=edinburgh.js.map

package/build/src/edinburgh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edinburgh.js","sourceRoot":"","sources":["../../src/edinburgh.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAS,yBAAyB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEjF,mCAAmC;AACnC,OAAO,EACH,KAAK,EACL,aAAa,EACb,KAAK,EACL,iBAAiB,EACpB,MAAM,aAAa,CAAC;AAGrB,yEAAyE;AACzE,OAAO;AACH,6BAA6B;AAC7B,MAAM,EACN,MAAM,EACN,OAAO,EACP,UAAU,EACV,KAAK;AACL,yBAAyB;AACzB,GAAG,EACH,EAAE,EACF,KAAK,EACL,OAAO,EACP,IAAI,GACP,MAAM,YAAY,CAAC;AAEpB,oCAAoC;AACpC,OAAO,EACH,KAAK,EACL,OAAO,EACP,MAAM,EACN,IAAI,GACP,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEpE,uBAAuB;AACvB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAGxG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuCE;AACF,MAAM,UAAU,QAAQ,CAAI,EAAW;IACnC,OAAO,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE;QACvB,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAc,CAAC;QAChD,KAAK,CAAC,kBAAkB,CAAC,yBAAyB,EAAE,iBAAiB,CAAC,CAAC;QAEvE,MAAM,cAAc,GAAoB,IAAI,GAAG,EAAE,CAAC;QAClD,IAAI,CAAC;YACD,MAAM,MAAM,GAAG,EAAE,EAAE,CAAC;YACpB,iDAAiD;YACjD,OAAM,iBAAiB,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;gBAC/B,8EAA8E;gBAC9E,0CAA0C;gBAC1C,KAAK,MAAM,QAAQ,IAAI,iBAAiB,EAAE,CAAC;oBACvC,QAAQ,CAAC,KAAK,EAAE,CAAC;oBACjB,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;oBAC7B,iBAAiB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBACvC,CAAC;YACL,CAAC;YAED,OAAO,MAAM,CAAC;QAClB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,2DAA2D;YAC3D,KAAK,MAAM,QAAQ,IAAI,cAAc;gBAAE,QAAQ,CAAC,cAAc,EAAE,CAAC;YACjE,KAAK,MAAM,QAAQ,IAAI,iBAAiB;gBAAE,QAAQ,CAAC,cAAc,EAAE,CAAC;YACpE,MAAM,KAAK,CAAC;QAChB,CAAC;IACL,CAAC,CAAC,CAAC;AACP,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB;IAClC,MAAM,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE;QACtB,KAAK,MAAM,EAAC,GAAG,EAAC,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YAC/B,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;IACL,CAAC,CAAC,CAAC;IACH,MAAM,gBAAgB,EAAE,CAAC;AAC7B,CAAC"}

package/build/src/indexes.d.ts

@@ -0,0 +1,348 @@
+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;
+type IndexArgTypes<M extends typeof Model<any>, F extends readonly (keyof InstanceType<M> & string)[]> = {
+    [I in keyof F]: InstanceType<M>[F[I]];
+};
+/**
+ * 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;
+    private indexId;
+    private parentIndex;
+    constructor(iterator: olmdb.DbIterator<any, any> | undefined, indexId: number, parentIndex: BaseIndex<M, F>);
+    [Symbol.iterator](): Iterator<InstanceType<M>>;
+    next(): IteratorResult<InstanceType<M>>;
+    count(): number;
+    fetch(): InstanceType<M> | undefined;
+}
+type ArrayOrOnlyItem<ARG_TYPES extends readonly any[]> = ARG_TYPES extends readonly [infer A] ? (A | Partial<ARG_TYPES>) : Partial<ARG_TYPES>;
+type FindOptions<ARG_TYPES extends readonly any[]> = (({
+    is: ArrayOrOnlyItem<ARG_TYPES>;
+} | (({
+    from: ArrayOrOnlyItem<ARG_TYPES>;
+} | {
+    after: ArrayOrOnlyItem<ARG_TYPES>;
+} | {}) & ({
+    to: ArrayOrOnlyItem<ARG_TYPES>;
+} | {
+    before: ArrayOrOnlyItem<ARG_TYPES>;
+} | {}))) & {
+    reverse?: boolean;
+});
+/**
+ * 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)[]> {
+    _fieldNames: F;
+    _MyModel: M;
+    /**
+     * 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>;
+    /**
+     * 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.
+     * @param args - Field values to serialize (can be partial for range queries).
+     * @param bytes - Bytes to write to.
+     * @internal
+     */
+    _serializeArgs(args: Partial<IndexArgTypes<M, F>> | readonly any[], bytes: Bytes): void;
+    /**
+     * 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.
+     * @internal
+     */
+    _modelToArgs(model: InstanceType<M>): IndexArgTypes<M, F> | undefined;
+    /**
+     * Get or create unique index ID for this index.
+     * @returns Numeric index ID.
+     */
+    _getIndexId(): number;
+    /**
+     * Check if indexing should be skipped for a model instance.
+     * @param model - Model instance.
+     * @returns true if indexing should be skipped.
+     */
+    _checkSkip(model: InstanceType<M>): boolean;
+    /**
+     * 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.
+     *
+     * @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
+     *
+     * @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.pk.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);
+     * }
+     * ```
+     */
+    find(opts?: FindOptions<IndexArgTypes<M, F>>): IndexRangeIterator<M, F>;
+    /**
+     * Save index entry for a model instance.
+     * @param model - Model instance to save.
+     * @param originalKey - Original key if updating.
+     */
+    abstract _save(model: InstanceType<M>, originalKey?: Uint8Array): Uint8Array | undefined;
+    abstract _getTypeName(): 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> {
+    constructor(MyModel: M, fieldNames: F);
+    /**
+     * 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.pk.get("john_doe");
+     * ```
+     */
+    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
+     */
+    _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;
+    _getTypeName(): string;
+}
+/**
+ * Unique index that stores references to the primary key.
+ *
+ * @template M - The model class this index belongs to.
+ * @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> {
+    /**
+     * Get a model instance by unique index key values.
+     * @param args - The unique index key values.
+     * @returns The model instance if found, undefined otherwise.
+     *
+     * @example
+     * ```typescript
+     * const userByEmail = User.byEmail.get("john@example.com");
+     * ```
+     */
+    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;
+    _getTypeName(): string;
+}
+/**
+ * Secondary index for non-unique lookups.
+ *
+ * @template M - The model class this index belongs to.
+ * @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;
+    _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>;
+/**
+ * Create a primary index on model fields.
+ * @template M - The model class.
+ * @template F - The field name (for single field index).
+ * @template FS - The field names array (for composite index).
+ * @param MyModel - The model class to create the index for.
+ * @param field - Single field name for simple indexes.
+ * @param fields - Array of field names for composite indexes.
+ * @returns A new PrimaryIndex instance.
+ *
+ * @example
+ * ```typescript
+ * class User extends E.Model<User> {
+ *   static pk = E.primary(User, ["id"]);
+ *   static pkSingle = E.primary(User, "id");
+ * }
+ * ```
+ */
+export declare function primary<M extends typeof Model, const F extends (keyof InstanceType<M> & string)>(MyModel: M, field: F): PrimaryIndex<M, [F]>;
+export declare function primary<M extends typeof Model, const FS extends readonly (keyof InstanceType<M> & string)[]>(MyModel: M, fields: FS): PrimaryIndex<M, FS>;
+/**
+ * Create a unique index on model fields.
+ * @template M - The model class.
+ * @template F - The field name (for single field index).
+ * @template FS - The field names array (for composite index).
+ * @param MyModel - The model class to create the index for.
+ * @param field - Single field name for simple indexes.
+ * @param fields - Array of field names for composite indexes.
+ * @returns A new UniqueIndex instance.
+ *
+ * @example
+ * ```typescript
+ * class User extends E.Model<User> {
+ *   static byEmail = E.unique(User, "email");
+ *   static byNameAge = E.unique(User, ["name", "age"]);
+ * }
+ * ```
+ */
+export declare function unique<M extends typeof Model, const F extends (keyof InstanceType<M> & string)>(MyModel: M, field: F): UniqueIndex<M, [F]>;
+export declare function unique<M extends typeof Model, const FS extends readonly (keyof InstanceType<M> & string)[]>(MyModel: M, fields: FS): UniqueIndex<M, FS>;
+/**
+ * Create a secondary index on model fields.
+ * @template M - The model class.
+ * @template F - The field name (for single field index).
+ * @template FS - The field names array (for composite index).
+ * @param MyModel - The model class to create the index for.
+ * @param field - Single field name for simple indexes.
+ * @param fields - Array of field names for composite indexes.
+ * @returns A new SecondaryIndex instance.
+ *
+ * @example
+ * ```typescript
+ * class User extends E.Model<User> {
+ *   static byAge = E.index(User, "age");
+ *   static byTagsDate = E.index(User, ["tags", "createdAt"]);
+ * }
+ * ```
+ */
+export declare function index<M extends typeof Model, const F extends (keyof InstanceType<M> & string)>(MyModel: M, field: F): SecondaryIndex<M, [F]>;
+export declare function index<M extends typeof Model, const FS extends readonly (keyof InstanceType<M> & string)[]>(MyModel: M, fields: FS): SecondaryIndex<M, FS>;
+/**
+ * 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 {};