edinburgh 0.4.2 → 0.4.5

package/skill/SecondaryIndex.md

@@ -0,0 +1,9 @@
+### 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

@@ -0,0 +1,9 @@
+### 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

@@ -0,0 +1,17 @@
+#### 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/array.md

@@ -0,0 +1,23 @@
+### array · function
+
+Create an array type wrapper with optional length constraints.
+
+**Signature:** `<const T>(inner: TypeWrapper<T>, opts?: { min?: number; max?: number; }) => TypeWrapper<T[]>`
+
+**Type Parameters:**
+
+- `T` - The element type.
+
+**Parameters:**
+
+- `inner: TypeWrapper<T>` - - Type wrapper for array elements.
+- `opts: {min?: number, max?: number}` (optional) - - Optional constraints (min/max length).
+
+**Returns:** An array type instance.
+
+**Examples:**
+
+```typescript
+const stringArray = E.array(E.string);
+const boundedArray = E.array(E.number, {min: 1, max: 10});
+```

package/skill/dump.md

@@ -0,0 +1,8 @@
+### 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/field.md

@@ -0,0 +1,29 @@
+### field · function
+
+Create a field definition for a model property.
+
+This function uses TypeScript magic to return the field configuration object
+while appearing to return the actual field value type to the type system.
+This allows for both runtime introspection and compile-time type safety.
+
+**Signature:** `<T>(type: TypeWrapper<T>, options?: Partial<FieldConfig<T>>) => T`
+
+**Type Parameters:**
+
+- `T` - The field type.
+
+**Parameters:**
+
+- `type: TypeWrapper<T>` - - The type wrapper for this field.
+- `options: Partial<FieldConfig<T>>` (optional) - - Additional field configuration options.
+
+**Returns:** The field value (typed as T, but actually returns FieldConfig<T>).
+
+**Examples:**
+
+```typescript
+class User extends E.Model<User> {
+  name = E.field(E.string, {description: "User's full name"});
+  age = E.field(E.opt(E.number), {description: "User's age", default: 25});
+}
+```

package/skill/index.md

@@ -0,0 +1,32 @@
+### 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/init.md

@@ -0,0 +1,17 @@
+### init · function
+
+Initialize the database with the specified directory path.
+This function may be called multiple times with the same parameters. If it is not called before the first transact(),
+the database will be automatically initialized with the default directory.
+
+**Signature:** `(dbDir: string) => void`
+
+**Parameters:**
+
+- `dbDir: string`
+
+**Examples:**
+
+```typescript
+init("./my-database");
+```

package/skill/link.md

@@ -0,0 +1,27 @@
+### link · function
+
+Create a link type wrapper for model relationships.
+
+**Signature:** `<const T extends typeof Model<any>>(TargetModel: T) => TypeWrapper<InstanceType<T>>`
+
+**Type Parameters:**
+
+- `T extends typeof Model<any>` - The target model class.
+
+**Parameters:**
+
+- `TargetModel: T` - - The model class this link points to.
+
+**Returns:** A link type instance.
+
+**Examples:**
+
+```typescript
+class User extends E.Model<User> {
+  posts = E.field(E.array(E.link(Post, 'author')));
+}
+
+class Post extends E.Model<Post> {
+  author = E.field(E.link(User));
+}
+```

package/skill/literal.md

@@ -0,0 +1,22 @@
+### literal · function
+
+Create a literal type wrapper for a constant value.
+
+**Signature:** `<const T>(value: T) => TypeWrapper<T>`
+
+**Type Parameters:**
+
+- `T` - The literal type.
+
+**Parameters:**
+
+- `value: T` - - The literal value.
+
+**Returns:** A literal type instance.
+
+**Examples:**
+
+```typescript
+const statusType = E.literal("active");
+const countType = E.literal(42);
+```

package/skill/opt.md

@@ -0,0 +1,22 @@
+### opt · function
+
+Create an optional type wrapper (allows undefined).
+
+**Signature:** `<const T extends TypeWrapper<unknown> | BasicType>(inner: T) => TypeWrapper<T extends TypeWrapper<infer U> ? U : T>`
+
+**Type Parameters:**
+
+- `T extends TypeWrapper<unknown>|BasicType` - Type wrapper or basic type to make optional.
+
+**Parameters:**
+
+- `inner: T` - - The inner type to make optional.
+
+**Returns:** A union type that accepts the inner type or undefined.
+
+**Examples:**
+
+```typescript
+const optionalString = E.opt(E.string);
+const optionalNumber = E.opt(E.number);
+```

package/skill/or.md

@@ -0,0 +1,22 @@
+### or · function
+
+Create a union type wrapper from multiple type choices.
+
+**Signature:** `<const T extends (TypeWrapper<unknown> | BasicType)[]>(...choices: T) => TypeWrapper<UnwrapTypes<T>>`
+
+**Type Parameters:**
+
+- `T extends (TypeWrapper<unknown>|BasicType)[]` - Array of type wrapper or basic types.
+
+**Parameters:**
+
+- `choices: T` - - The type choices for the union.
+
+**Returns:** A union type instance.
+
+**Examples:**
+
+```typescript
+const stringOrNumber = E.or(E.string, E.number);
+const status = E.or("active", "inactive", "pending");
+```

package/skill/primary.md

@@ -0,0 +1,26 @@
+### 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/record.md

@@ -0,0 +1,21 @@
+### record · function
+
+Create a Record type wrapper for key-value objects with string or number keys.
+
+**Signature:** `<const T>(inner: TypeWrapper<T>) => TypeWrapper<Record<string | number, T>>`
+
+**Type Parameters:**
+
+- `T` - The value type.
+
+**Parameters:**
+
+- `inner: TypeWrapper<T>` - - Type wrapper for record values.
+
+**Returns:** A record type instance.
+
+**Examples:**
+
+```typescript
+const scores = E.record(E.number);  // Record<string | number, number>
+```

package/skill/registerModel.md

@@ -0,0 +1,26 @@
+### 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);
+}
+```

package/skill/runMigration.md

@@ -0,0 +1,10 @@
+### runMigration · function
+
+Run database migration: populate secondary indexes for old-version rows,
+convert old primary indices, rewrite row data, and clean up orphaned indices.
+
+**Signature:** `(options?: MigrationOptions) => Promise<MigrationResult>`
+
+**Parameters:**
+
+- `options: MigrationOptions` (optional)

package/skill/set.md

@@ -0,0 +1,23 @@
+### set · function
+
+Create a Set type wrapper with optional length constraints.
+
+**Signature:** `<const T>(inner: TypeWrapper<T>, opts?: { min?: number; max?: number; }) => TypeWrapper<Set<T>>`
+
+**Type Parameters:**
+
+- `T` - The element type.
+
+**Parameters:**
+
+- `inner: TypeWrapper<T>` - - Type wrapper for set elements.
+- `opts: {min?: number, max?: number}` (optional) - - Optional constraints (min/max length).
+
+**Returns:** A set type instance.
+
+**Examples:**
+
+```typescript
+const stringSet = E.set(E.string);
+const boundedSet = E.set(E.number, {min: 1, max: 10});
+```

package/skill/setMaxRetryCount.md

@@ -0,0 +1,10 @@
+### setMaxRetryCount · function
+
+Set the maximum number of retries for a transaction in case of conflicts.
+The default value is 6. Setting it to 0 will disable retries and cause transactions to fail immediately on conflict.
+
+**Signature:** `(count: number) => void`
+
+**Parameters:**
+
+- `count: number` - The maximum number of retries for a transaction.

package/skill/setOnSaveCallback.md

@@ -0,0 +1,12 @@
+### setOnSaveCallback · function
+
+Set a callback function to be called after a model is saved and committed.
+
+**Signature:** `(callback: (commitId: number, items: Map<Model<any>, Change>) => void) => void`
+
+**Parameters:**
+
+- `callback: ((commitId: number, items: Map<Model<any>, Change>) => void) | undefined` - The callback function to set. It gets called after each successful
+`transact()` commit that has changes, with the following arguments:
+- A sequential number. Higher numbers have been committed after lower numbers.
+- A map of model instances to their changes. The change can be "created", "deleted", or an object containing the old values.

package/skill/transact.md

@@ -0,0 +1,49 @@
+### transact · function
+
+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 6
+times.
+
+**Signature:** `<T>(fn: () => T) => Promise<T>`
+
+**Type Parameters:**
+
+- `T` - The return type of the transaction function.
+
+**Parameters:**
+
+- `fn: () => T` - - The function to execute within the transaction context. Receives a Transaction instance.
+
+**Returns:** A promise that resolves with the function's return value.
+
+**Throws:**
+
+- With code "RACING_TRANSACTION" if the transaction fails after retries due to conflicts.
+- With code "TXN_LIMIT" if maximum number of transactions is reached.
+- With code "LMDB-{code}" for LMDB-specific errors.
+
+**Examples:**
+
+```typescript
+const paid = await E.transact(() => {
+  const user = User.pk.get("john_doe");
+  if (user.credits > 0) {
+    user.credits--;
+    return true;
+  }
+  return false;
+});
+```
+```typescript
+// Transaction with automatic retry on conflicts
+await E.transact(() => {
+  const counter = Counter.pk.get("global") || new Counter({id: "global", value: 0});
+  counter.value++;
+});
+```

package/skill/unique.md

@@ -0,0 +1,32 @@
+### unique · function
+
+Create a unique index on model fields, or a computed unique 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[]): UniqueIndex<M, [], [V]>; <M extends typeof Model, const F extends (keyof InstanceType<M> & string)>(MyModel: M, field: F): UniqueIndex<...>; <M extends typeof Model, const FS extends readonly (keyof InstanceType<M> & string)[]>(MyMode...`
+
+**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 UniqueIndex instance.
+
+**Examples:**
+
+```typescript
+class User extends E.Model<User> {
+  static byEmail = E.unique(User, "email");
+  static byNameAge = E.unique(User, ["name", "age"]);
+  static byFullName = E.unique(User, (u: User) => [`${u.firstName} ${u.lastName}`]);
+}
+```

package/src/datapack.ts

@@ -14,6 +14,8 @@ const COLORS = USE_COLORS ? ['\x1b[32m', '\x1b[33m', '\x1b[34m', '\x1b[35m'] : [
 const RESET_COLOR = USE_COLORS ? '\x1b[0m' : '';
 const ERROR_COLOR = USE_COLORS ? '\x1b[31m' : ''; // red
 
+const COLLECTION_BOUNDARIES = {'array': 5, 'object': 6, 'map': 7, 'set': 8, 'end': 9};
+
 let toStringTermCount = 0;
 let useExtendedLogging = typeof process !== 'undefined' ? !!process.env?.DATAPACK_EXTENDED_LOGGING : false;
 
@@ -32,6 +34,8 @@ export default class DataPack {
 
     public readPos: number = 0;
     public writePos: number = 0;
+
+    static EOD = EOD;
     
     /**
      * Backward compatibility: Access to the internal buffer
@@ -578,24 +582,62 @@ export default class DataPack {
      * });
      */
     writeCollection(type: 'array' | 'set', bodyFunc: (addField: (value: any) => void) => void): DataPack;
-    writeCollection(type: 'object', bodyFunc: (addField: (field: number|string|symbol, value: any) => void) => void): DataPack;
+    writeCollection(type: 'object', bodyFunc: (addField: (field: number|string, value: any) => void) => void): DataPack;
     writeCollection(type: 'map', bodyFunc: (addField: (field: any, value: any) => void) => void): DataPack;
 
-    writeCollection(type: string, bodyFunc: (addField: (a: any, b?: any) => void) => void): DataPack {
-        let subType = {'array': 5, 'object': 6, 'map': 7, 'set': 8}[type];
-        if (!subType) throw new Error(`Invalid collection type: ${type}`);
-        this.buffer[this.writePos++] = (4 << 5) | subType; // Collection start
+    writeCollection(type: 'array' | 'set' | 'object' | 'map', bodyFunc: (addField: (a: any, b?: any) => void) => void): DataPack {
+        this.writeCollectionBoundary(type);
 
         bodyFunc((type === 'array' || type === 'set') ? (value: any) => {
             this.write(value);
-        } : (name, value) => {
+        } : (type === 'object') ? (name, value) => {
+            this.writeObjectKey(name);
+            this.write(value);
+        } : (name, value) => { // map
             this.write(name);
             this.write(value);
         });
-        this.buffer[this.writePos++] = (4 << 5) | 9; // EOD
+
+        return this.writeCollectionBoundary('end');
+    }
+
+    /**
+     * Write a collection boundary marker (start or end) for arrays, sets, objects, or maps.
+     * This is a low-level method for advanced use cases. Use `writeCollection` (or just `write`)
+     * if possible.
+     */
+    writeCollectionBoundary(marker: 'array' | 'set' | 'object' | 'map' | 'end'): DataPack {
+        let subType = COLLECTION_BOUNDARIES[marker];
+        if (!subType) throw new Error(`Invalid collection type: ${marker}`);
+        this.buffer[this.writePos++] = (4 << 5) | subType;
         return this;
     }
 
+    /**
+     * Writes either a string or a number, converting strings to numbers if they represent javascript-safe integers.
+     * This is useful for writing object keys, which are always strings but may be more compactly represented as numbers.
+     */
+    writeObjectKey(key: number | string): void {
+        if (typeof key === 'string') {
+            const num = parseInt(key, 10);
+            if (num.toString() == key) key = num;
+
+        } else if (typeof key !== 'number') {
+            key = '' + key;
+        }
+        this.write(key);
+    }
+
+    /**
+     * Read and consume a collection boundary marker, validating it matches the expected type.
+     */
+    readCollectionBoundary(expected: 'array' | 'set' | 'object' | 'map' | 'end'): void {
+        if (this.readPos >= this.writePos) this.notEnoughData('collection boundary');
+        const byte = this.buffer[this.readPos++];
+        const expectedByte = (4 << 5) | COLLECTION_BOUNDARIES[expected];
+        if (byte !== expectedByte) throw new Error(`Expected ${expected} boundary but got byte ${byte}`);
+    }
+
     /** 
      * Increment the last byte of the buffer. If it was already 255 set it to 0 and
      * increment the previous byte, and so on. If all bytes were 255, return undefined.

package/src/edinburgh.ts

@@ -29,6 +29,8 @@ export {
     opt,
     or,
     array,
+    set,
+    record,
     literal,
     link,
 } from "./types.js";