edinburgh 0.4.6 → 0.6.0

package/src/types.ts

@@ -1,8 +1,9 @@
 import DataPack from "./datapack.js";
 import { DatabaseError } from "olmdb/lowlevel";
-import { Model, modelRegistry, FieldConfig, currentTxn } from "./models.js";
+import { currentTxn } from "./edinburgh.js";
+import { Model, modelRegistry } from "./models.js";
+import type { AnyModelClass } from "./models.js";
 import { assert, addErrorPath, dbGet } from "./utils.js";
-import { PrimaryIndex, BaseIndex, IndexRangeIterator } from "./indexes.js";
 
 
 /**
@@ -25,34 +26,34 @@ export abstract class TypeWrapper<const T> {
     
     /**
     * Serialize a value from an object property to a Pack.
-    * @param value - The value to serialize.
-    * @param pack - The Pack instance to write to.
+    * @param value The value to serialize.
+    * @param pack The Pack instance to write to.
     */
     abstract serialize(value: T, pack: DataPack): void;
 
     /**
     * Deserialize a value from a Pack into an object property.
-    * @param pack - The Pack instance to read from.
+    * @param pack The Pack instance to read from.
     */
     abstract deserialize(pack: DataPack): T;
 
     /**
     * Validate a value.
-    * @param value - The value to validate.
+    * @param value The value to validate.
     * @returns - A DatabaseError if validation fails.
     */
     abstract getError(value: T): DatabaseError | void;
     
     /**
     * Serialize type metadata to a Pack (for schema serialization).
-    * @param pack - The Pack instance to write to.
+    * @param pack The Pack instance to write to.
     */
     serializeType(pack: DataPack) {}
     
     /**
     * Check if indexing should be skipped for this field value.
-    * @param obj - The object containing the value.
-    * @param prop - The property name or index.
+    * @param obj The object containing the value.
+    * @param prop The property name or index.
     * @returns true if indexing should be skipped.
     */
     containsNull(value: T): boolean {
@@ -71,7 +72,7 @@ export abstract class TypeWrapper<const T> {
         return value1 === value2;
     }
 
-    getLinkedModel(): (typeof Model<unknown>) | undefined {
+    getLinkedModel(): undefined | AnyModelClass {
         return;
     }
 }
@@ -80,7 +81,7 @@ export abstract class TypeWrapper<const T> {
 export interface TypeWrapper<T> {
     /**
     * Generate a default value for this type.
-    * @param model - The model instance.
+    * @param model The model instance.
     * @returns The default value.
     */
     default?(model: any): T;
@@ -181,8 +182,8 @@ class ArrayType<T> extends TypeWrapper<T[]> {
     
     /**
     * Create a new ArrayType.
-    * @param inner - Type wrapper for array elements.
-    * @param opts - Array constraints (min/max length).
+    * @param inner Type wrapper for array elements.
+    * @param opts Array constraints (min/max length).
     */
     constructor(public inner: TypeWrapper<T>, public opts: {min?: number, max?: number} = {}) {
         super();
@@ -262,7 +263,7 @@ export class SetType<T> extends TypeWrapper<Set<T>> {
 
     /**
     * Create a new SetType.
-    * @param inner - Type wrapper for set elements.
+    * @param inner Type wrapper for set elements.
     */
     constructor(public inner: TypeWrapper<T>, public opts: {min?: number, max?: number} = {}) {
         super();
@@ -355,7 +356,7 @@ class RecordType<T> extends TypeWrapper<Record<string | number, T>> {
 
     serialize(value: Record<string | number, T>, pack: DataPack) {
         pack.writeCollectionBoundary('object');
-        for (const key of Object.keys(value)) {
+        for (const key in value) {
             pack.writeObjectKey(key);
             this.inner.serialize(value[key], pack);
         }
@@ -374,7 +375,7 @@ class RecordType<T> extends TypeWrapper<Record<string | number, T>> {
     }
 
     getError(value: Record<string | number, T>) {
-        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value) || (typeof value.length === 'number' && typeof value[Symbol.iterator as any] === 'function')) {
             return new DatabaseError(`Expected object, got ${typeof value}`, 'INVALID_TYPE');
         }
         for (const key of Object.keys(value)) {
@@ -431,7 +432,7 @@ class OrType<const T> extends TypeWrapper<T> {
     
     /**
     * Create a new OrType.
-    * @param choices - Array of type wrappers representing the union choices.
+    * @param choices Array of type wrappers representing the union choices.
     */
     constructor(public choices: TypeWrapper<T>[]) {
         super();
@@ -522,7 +523,7 @@ class LiteralType<const T> extends TypeWrapper<T> {
     
     /**
     * Create a new LiteralType.
-    * @param value - The literal value this type represents.
+    * @param value The literal value this type represents.
     */
     constructor(public value: T) {
         super();
@@ -596,7 +597,7 @@ class IdentifierType extends TypeWrapper<string> {
         let id: string;
         do {
             id = DataPack.generateIdentifier();
-        } while (dbGet(model._txn.id, new DataPack().write(model.constructor._primary!._indexId!).writeIdentifier(id).toUint8Array()));
+        } while (dbGet(model._txn.id, new DataPack().write(model.constructor._indexId!).writeIdentifier(id).toUint8Array()));
         return id;
     }
 }
@@ -605,17 +606,22 @@ class IdentifierType extends TypeWrapper<string> {
 * @internal Type wrapper for model relationships (foreign keys).
 * @template T - The target model class type.
 */
-export class LinkType<T extends typeof Model<unknown>> extends TypeWrapper<InstanceType<T>> {
+export class LinkType<T extends new (...args: any[]) => Model<any>> extends TypeWrapper<InstanceType<T>> {
     kind = 'link';
-    tableName: string;
+    private TargetModel: T | (() => T);
 
     /**
     * Create a new LinkType.
-    * @param TargetModel - The model class this link points to.
+    * @param TargetModel The model class this link points to, or a thunk for forward references.
     */
-    constructor(TargetModel: T) {
+    constructor(TargetModel: T | (() => T)) {
         super();
-        this.tableName = (TargetModel as any).tableName || TargetModel.name;
+        this.TargetModel = TargetModel;
+    }
+
+    getLinkedModel(): AnyModelClass {
+        if (!('getLazy' in this.TargetModel)) this.TargetModel = (this.TargetModel as unknown as () => T)();
+        return this.TargetModel as any;
     }
     
     serialize(model: InstanceType<T>, pack: DataPack) {
@@ -623,31 +629,28 @@ export class LinkType<T extends typeof Model<unknown>> extends TypeWrapper<Insta
     }
     
     deserialize(pack: DataPack) {
-        return modelRegistry[this.tableName]._primary!._get(currentTxn(), pack.readUint8Array(), false);
+        return this.getLinkedModel()._get(currentTxn(), pack.readUint8Array(), false);
     }
     
     getError(value: InstanceType<T>) {
-        if (!(value instanceof modelRegistry[this.tableName])) {
-            return new DatabaseError(`Expected instance of ${this.tableName}, got ${typeof value}`, 'VALUE_ERROR');
+        const TargetModel = this.getLinkedModel();
+        if (!((value as any) instanceof TargetModel)) {
+            return new DatabaseError(`Expected instance of ${TargetModel.tableName}, got ${typeof value}`, 'VALUE_ERROR');
         }
     }
     
     serializeType(pack: DataPack): void {
-        pack.write(this.tableName);
+        pack.write(this.getLinkedModel().tableName);
     }
     
     static deserializeType(pack: DataPack, featureFlags: number): LinkType<any> {
         const tableName = pack.readString();
         const targetModel = modelRegistry[tableName];
         if (!targetModel) throw new DatabaseError(`Could not deserialize undefined model ${tableName}`, 'DESERIALIZATION_ERROR');
-        return new LinkType(targetModel);
+        return new LinkType(targetModel as any);
     }
 
-    toString() { return `link<${this.tableName}>`; }
-
-    getLinkedModel(): T {
-        return modelRegistry[this.tableName] as T;
-    }
+    toString() { return `link<${this.getLinkedModel().tableName}>`; }
 }
 
 /** Type wrapper instance for the string type. */
@@ -679,7 +682,7 @@ export const undef = new LiteralType(undefined) as TypeWrapper<undefined>;
 /**
 * Create a literal type wrapper for a constant value.
 * @template T - The literal type.
-* @param value - The literal value.
+* @param value The literal value.
 * @returns A literal type instance.
 * 
 * @example
@@ -695,7 +698,7 @@ export function literal<const T>(value: T): TypeWrapper<T> {
 /**
 * Create a union type wrapper from multiple type choices.
 * @template T - Array of type wrapper or basic types.
-* @param choices - The type choices for the union.
+* @param choices The type choices for the union.
 * @returns A union type instance.
 * 
 * @example
@@ -711,7 +714,7 @@ export function or<const T extends (TypeWrapper<unknown>|BasicType)[]>(...choice
 /**
 * Create an optional type wrapper (allows undefined).
 * @template T - Type wrapper or basic type to make optional.
-* @param inner - The inner type to make optional.
+* @param inner The inner type to make optional.
 * @returns A union type that accepts the inner type or undefined.
 * 
 * @example
@@ -727,8 +730,8 @@ export function opt<const T extends TypeWrapper<unknown>|BasicType>(inner: T): T
 /**
 * Create an array type wrapper with optional length constraints.
 * @template T - The element type.
-* @param inner - Type wrapper for array elements.
-* @param opts - Optional constraints (min/max length).
+* @param inner Type wrapper for array elements.
+* @param opts Optional constraints (min/max length).
 * @returns An array type instance.
 * 
 * @example
@@ -744,8 +747,8 @@ export function array<const T>(inner: TypeWrapper<T>, opts: {min?: number, max?:
 /**
 * Create a Set type wrapper with optional length constraints.
 * @template T - The element type.
-* @param inner - Type wrapper for set elements.
-* @param opts - Optional constraints (min/max length).
+* @param inner Type wrapper for set elements.
+* @param opts Optional constraints (min/max length).
 * @returns A set type instance.
 *
 * @example
@@ -761,7 +764,7 @@ export function set<const T>(inner: TypeWrapper<T>, opts: {min?: number, max?: n
 /**
 * Create a Record type wrapper for key-value objects with string or number keys.
 * @template T - The value type.
-* @param inner - Type wrapper for record values.
+* @param inner Type wrapper for record values.
 * @returns A record type instance.
 *
 * @example
@@ -776,21 +779,25 @@ export function record<const T>(inner: TypeWrapper<T>): TypeWrapper<Record<strin
 /**
 * Create a link type wrapper for model relationships.
 * @template T - The target model class.
-* @param TargetModel - The model class this link points to.
+* @param TargetModel The model class this link points to.
 * @returns A link type instance.
 * 
 * @example
 * ```typescript
-* class User extends E.Model<User> {
-*   posts = E.field(E.array(E.link(Post, 'author')));
-* }
+* const Author = E.defineModel("Author", class {
+*   id = E.field(E.identifier);
+*   posts = E.field(E.array(E.link(() => Book)));
+* }, { pk: "id" });
 * 
-* class Post extends E.Model<Post> {
-*   author = E.field(E.link(User));
-* }
+* const Book = E.defineModel("Book", class {
+*   id = E.field(E.identifier);
+*   author = E.field(E.link(Author));
+* }, { pk: "id" });
 * ```
 */
-export function link<const T extends typeof Model<any>>(TargetModel: T): TypeWrapper<InstanceType<T>> {
+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>>;
+export function link(TargetModel: any): TypeWrapper<any> {
     return new LinkType(TargetModel);
 }
 
@@ -810,8 +817,8 @@ function wrapIfLiteral(type: any) {
 
 /**
 * Serialize a type wrapper to a Pack for schema persistence.
-* @param arg - The type wrapper to serialize.
-* @param pack - The Pack instance to write to.
+* @param arg The type wrapper to serialize.
+* @param pack The Pack instance to write to.
 */
 export function serializeType(arg: TypeWrapper<any>, pack: DataPack) {
     pack.write(arg.kind);
@@ -834,8 +841,8 @@ const TYPE_WRAPPERS: Record<string, TypeWrapper<any> | {deserializeType: (pack:
 
 /**
 * Deserialize a type wrapper from a Pack.
-* @param pack - The Pack instance to read from.
-* @param featureFlags - Feature flags for version compatibility.
+* @param pack The Pack instance to read from.
+* @param featureFlags Feature flags for version compatibility.
 * @returns The deserialized type wrapper.
 */
 export function deserializeType(pack: DataPack, featureFlags: number): TypeWrapper<any> {

package/src/utils.ts

@@ -2,8 +2,8 @@ import * as lowlevel from "olmdb/lowlevel";
 
 /**
  * Assert function for runtime checks with TypeScript assertion support.
- * @param cond - Condition to check.
- * @param message - Optional error message.
+ * @param cond Condition to check.
+ * @param message Optional error message.
  * @throws {Error} If condition is false.
  */
 export function assert(cond: any, message?: string): asserts cond {
@@ -58,8 +58,8 @@ export const ERROR_AT = /^(.*) at ([a-zA-Z0-9_.]+)$/;
 
 /**
  * Add a path segment to an exception for better error reporting.
- * @param error - The (Database)Error to modify.
- * @param path - The path segment to add (string or number).
+ * @param error The (Database)Error to modify.
+ * @param path The path segment to add (string or number).
  * @returns The modified DatabaseError.
  */
 export function addErrorPath<T>(error: T, path: string | number): T {

package/skill/BaseIndex.md

@@ -1,16 +0,0 @@
-### BaseIndex · abstract class
-
-Base class for database indexes for efficient lookups on model fields.
-
-Indexes enable fast queries on specific field combinations and enforce uniqueness constraints.
-
-**Type Parameters:**
-
-- `M extends typeof Model` - The model class this index belongs to.
-- `F extends readonly (keyof InstanceType<M> & string)[]` - The field names that make up this index.
-- `ARGS extends readonly any[] = IndexArgTypes<M, F>`
-
-**Constructor Parameters:**
-
-- `MyModel`: - The model class this index belongs to.
-- `_fieldNames`: - Array of field names that make up this index.

package/skill/BaseIndex_batchProcess.md

@@ -1,10 +0,0 @@
-#### baseIndex.batchProcess · method
-
-[object Object],[object Object],[object Object]
-
-**Signature:** `(opts: FindOptions<ARGS> & { limitSeconds?: number; limitRows?: number; }, callback: (row: InstanceType<M>) => void | Promise<void>) => Promise<...>`
-
-**Parameters:**
-
-- `opts: FindOptions<ARGS> & { limitSeconds?: number; limitRows?: number }` (optional) - - Query options (same as `find()`), plus:
-- `callback: (row: InstanceType<M>) => void | Promise<void>` - - Called for each matching row within a transaction

package/skill/BaseIndex_find.md

@@ -1,7 +0,0 @@
-#### baseIndex.find · method
-
-**Signature:** `(opts?: FindOptions<ARGS>) => IndexRangeIterator<M>`
-
-**Parameters:**
-
-- `opts: FindOptions<ARGS>` (optional)

package/skill/Model.md

@@ -1,22 +0,0 @@
-### Model · abstract class
-
-[object Object],[object Object],[object Object],[object Object],[object Object]
-
-**Type Parameters:**
-
-- `SUB` - The concrete model subclass (for proper typing).
-
-**Examples:**
-
-```typescript
-⁣@E.registerModel
-class User extends E.Model<User> {
-  static pk = E.primary(User, "id");
-  
-  id = E.field(E.identifier);
-  name = E.field(E.string);
-  email = E.field(E.string);
-  
-  static byEmail = E.unique(User, "email");
-}
-```

package/skill/Model_findAll.md

@@ -1,12 +0,0 @@
-#### Model.findAll · static method
-
-Find all instances of this model in the database, ordered by primary key.
-
-**Signature:** `<T extends typeof Model<unknown>>(this: T, opts?: { reverse?: boolean; }) => IndexRangeIterator<T>`
-
-**Parameters:**
-
-- `this: T`
-- `opts?: {reverse?: boolean}` - - Optional parameters.
-
-**Returns:** An iterator.

package/skill/Model_migrate.md

@@ -1,34 +0,0 @@
-#### Model.migrate · static method
-
-Optional migration function called when deserializing rows written with an older schema version.
-Receives a plain record with all fields (primary key fields + value fields) and should mutate it
-in-place to match the current schema.
-
-This is called both during lazy loading (when a row is read from disk) and during batch
-migration (via `runMigration()` / `npx migrate-edinburgh`). The function's source code is hashed
-to detect changes. Modifying `migrate()` triggers a new schema version.
-
-If `migrate()` changes values of fields used in secondary or unique indexes, those indexes
-will only be updated when `runMigration()` is run (not during lazy loading).
-
-**Signature:** `(record: Record<string, any>) => void`
-
-**Parameters:**
-
-- `record: Record<string, any>` - - A plain object with all field values from the old schema version.
-
-**Examples:**
-
-```typescript
-⁣@E.registerModel
-class User extends E.Model<User> {
-  static pk = E.primary(User, "id");
-  id = E.field(E.identifier);
-  name = E.field(E.string);
-  role = E.field(E.string);  // new field
-
-  static migrate(record: Record<string, any>) {
-    record.role ??= "user";  // default for rows that predate the 'role' field
-  }
-}
-```

package/skill/Model_replaceInto.md

@@ -1,16 +0,0 @@
-#### Model.replaceInto · static method
-
-Load an existing instance by primary key and update it, or create a new one.
-
-The provided object must contain all primary key fields. If a matching row exists,
-the remaining properties from `obj` are set on the loaded instance. Otherwise a
-new instance is created with `obj` as its initial properties.
-
-**Signature:** `<T extends typeof Model<any>>(this: T, obj: Partial<Omit<InstanceType<T>, "constructor">>) => InstanceType<T>`
-
-**Parameters:**
-
-- `this: T`
-- `obj: Partial<Omit<InstanceType<T>, "constructor">>` - - Partial model data that **must** include every primary key field.
-
-**Returns:** The loaded-and-updated or newly created instance.

package/skill/PrimaryIndex.md

@@ -1,8 +0,0 @@
-### PrimaryIndex · class
-
-Primary index that stores the actual model data.
-
-**Type Parameters:**
-
-- `M extends typeof Model` - The model class this index belongs to.
-- `F extends readonly (keyof InstanceType<M> & string)[]` - The field names that make up this index.

package/skill/PrimaryIndex_get.md

@@ -1,17 +0,0 @@
-#### primaryIndex.get · method
-
-Get a model instance by primary key values.
-
-**Signature:** `(...args: IndexArgTypes<M, F>) => InstanceType<M>`
-
-**Parameters:**
-
-- `args: IndexArgTypes<M, F>` - - The primary key values.
-
-**Returns:** The model instance if found, undefined otherwise.
-
-**Examples:**
-
-```typescript
-const user = User.pk.get("john_doe");
-```

package/skill/PrimaryIndex_getLazy.md

@@ -1,13 +0,0 @@
-#### primaryIndex.getLazy · method
-
-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.
-
-**Signature:** `(...args: IndexArgTypes<M, F>) => InstanceType<M>`
-
-**Parameters:**
-
-- `args: IndexArgTypes<M, F>` - Primary key field values. (Or a single Uint8Array containing the key.)
-
-**Returns:** The (lazily loaded) model instance.

package/skill/SecondaryIndex.md

@@ -1,9 +0,0 @@
-### SecondaryIndex · class
-
-Secondary index for non-unique lookups.
-
-**Type Parameters:**
-
-- `M extends typeof Model` - The model class this index belongs to.
-- `F extends readonly (keyof InstanceType<M> & string)[]` - The field names that make up this index.
-- `ARGS extends readonly any[] = IndexArgTypes<M, F>`

package/skill/UniqueIndex.md

@@ -1,9 +0,0 @@
-### UniqueIndex · class
-
-Unique index that stores references to the primary key.
-
-**Type Parameters:**
-
-- `M extends typeof Model` - The model class this index belongs to.
-- `F extends readonly (keyof InstanceType<M> & string)[]` - The field names that make up this index.
-- `ARGS extends readonly any[] = IndexArgTypes<M, F>`

package/skill/UniqueIndex_get.md

@@ -1,17 +0,0 @@
-#### uniqueIndex.get · method
-
-Get a model instance by unique index key values.
-
-**Signature:** `(...args: ARGS) => InstanceType<M>`
-
-**Parameters:**
-
-- `args: ARGS` - - The unique index key values.
-
-**Returns:** The model instance if found, undefined otherwise.
-
-**Examples:**
-
-```typescript
-const userByEmail = User.byEmail.get("john@example.com");
-```

package/skill/dump.md

@@ -1,8 +0,0 @@
-### dump · function
-
-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.
-
-**Signature:** `() => void`

package/skill/index.md

@@ -1,32 +0,0 @@
-### index · function
-
-Create a secondary index on model fields, or a computed secondary index using a function.
-
-For field-based indexes, pass a field name or array of field names.
-For computed indexes, pass a function that takes a model instance and returns an array of
-index keys. Return `[]` to skip indexing for that instance. Each array element creates a
-separate index entry, enabling multi-value indexes (e.g., indexing by each word in a name).
-
-**Signature:** `{ <M extends typeof Model, V>(MyModel: M, fn: (instance: InstanceType<M>) => V[]): SecondaryIndex<M, [], [V]>; <M extends typeof Model, const F extends (keyof InstanceType<M> & string)>(MyModel: M, field: F): SecondaryIndex<...>; <M extends typeof Model, const FS extends readonly (keyof InstanceType<M> & string)[]>(...`
-
-**Type Parameters:**
-
-- `M extends typeof Model` - The model class.
-- `V` - The computed index value type (for function-based indexes).
-
-**Parameters:**
-
-- `MyModel: M` - - The model class to create the index for.
-- `fn: (instance: InstanceType<M>) => V[]`
-
-**Returns:** A new SecondaryIndex instance.
-
-**Examples:**
-
-```typescript
-class User extends E.Model<User> {
-  static byAge = E.index(User, "age");
-  static byTagsDate = E.index(User, ["tags", "createdAt"]);
-  static byWord = E.index(User, (u: User) => u.name.split(" "));
-}
-```

package/skill/primary.md

@@ -1,26 +0,0 @@
-### primary · function
-
-Create a primary index on model fields.
-
-**Signature:** `{ <M extends typeof Model, const F extends (keyof InstanceType<M> & string)>(MyModel: M, field: F): PrimaryIndex<M, [F]>; <M extends typeof Model, const FS extends readonly (keyof InstanceType<M> & string)[]>(MyModel: M, fields: FS): PrimaryIndex<...>; }`
-
-**Type Parameters:**
-
-- `M extends typeof Model` - The model class.
-- `F extends (keyof InstanceType<M> & string)` - The field name (for single field index).
-
-**Parameters:**
-
-- `MyModel: M` - - The model class to create the index for.
-- `field: F` - - Single field name for simple indexes.
-
-**Returns:** A new PrimaryIndex instance.
-
-**Examples:**
-
-```typescript
-class User extends E.Model<User> {
-  static pk = E.primary(User, ["id"]);
-  static pkSingle = E.primary(User, "id");
-}
-```

package/skill/registerModel.md

@@ -1,26 +0,0 @@
-### registerModel · function
-
-Register a model class with the Edinburgh ORM system.
-
-**Signature:** `<T extends typeof Model<unknown>>(MyModel: T) => T`
-
-**Type Parameters:**
-
-- `T extends typeof Model<unknown>` - The model class type.
-
-**Parameters:**
-
-- `MyModel: T` - - The model class to register.
-
-**Returns:** The enhanced model class with ORM capabilities.
-
-**Examples:**
-
-```typescript
-⁣@E.registerModel
-class User extends E.Model<User> {
-  static pk = E.index(User, ["id"], "primary");
-  id = E.field(E.identifier);
-  name = E.field(E.string);
-}
-```