edinburgh 0.4.4 → 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/migrate-cli.ts

@@ -1,22 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * migrate-edinburgh CLI tool
- * 
- * Runs database migrations: upgrades all rows to the latest schema version,
- * converts old primary indices, and cleans up orphaned secondary indices.
- * 
- * Usage:
- *   npx migrate-edinburgh --import ./src/models.ts [options]
- * 
- * Options:
- *   --import <path>     Path to the module that registers all models (required)
- *   --db <path>         Database directory (default: .edinburgh)
- *   --tables <names>    Comma-separated list of table names to migrate
- *   --batch-size <n>    Number of rows per transaction batch (default: 500)
- *   --no-convert        Skip converting old primary indices
- *   --no-cleanup        Skip deleting orphaned secondary indices
- *   --no-upgrade        Skip upgrading rows to latest version
+ * See `npx migrate-edinburgh --help` for usage.
  */
 
 import { runMigration, type MigrationOptions } from './migrate.js';
@@ -24,43 +9,49 @@ import { runMigration, type MigrationOptions } from './migrate.js';
 function parseArgs(args: string[]): { importPath: string, options: MigrationOptions & { dbDir?: string } } {
     let importPath = '';
     const options: MigrationOptions & { dbDir?: string } = {};
+    const tables: string[] = [];
     
     for (let i = 0; i < args.length; i++) {
-        switch (args[i]) {
-            case '--import':
-                importPath = args[++i];
-                break;
+        const arg = args[i];
+        switch (arg) {
             case '--db':
                 options.dbDir = args[++i];
                 break;
-            case '--tables':
-                options.tables = args[++i].split(',').map(s => s.trim());
-                break;
-            case '--no-convert':
-                options.convertOldPrimaries = false;
-                break;
-            case '--no-cleanup':
-                options.deleteOrphanedIndexes = false;
-                break;
-            case '--no-upgrade':
-                options.upgradeVersions = false;
-                break;
+            case '+secondaries': options.populateSecondaries = true; break;
+            case '-secondaries': options.populateSecondaries = false; break;
+            case '+primaries': options.migratePrimaries = true; break;
+            case '-primaries': options.migratePrimaries = false; break;
+            case '+data': options.rewriteData = true; break;
+            case '-data': options.rewriteData = false; break;
+            case '+orphans': options.removeOrphans = true; break;
+            case '-orphans': options.removeOrphans = false; break;
             default:
-                if (args[i].startsWith('-')) {
-                    console.error(`Unknown option: ${args[i]}`);
+                if (arg.startsWith('-') || arg.startsWith('+')) {
+                    console.error(`Unknown option: ${arg}`);
                     process.exit(1);
                 }
+                if (!importPath) {
+                    importPath = arg;
+                } else {
+                    tables.push(arg);
+                }
         }
     }
     
+    if (tables.length > 0) options.tables = tables;
+    
     if (!importPath) {
-        console.error('Usage: npx migrate-edinburgh --import <path> [options]');
-        console.error('  --import <path>     Module that registers all models (required)');
-        console.error('  --db <path>         Database directory (default: .edinburgh)');
-        console.error('  --tables <names>    Comma-separated table names');
-        console.error('  --no-convert        Skip old primary conversion');
-        console.error('  --no-cleanup        Skip orphaned index cleanup');
-        console.error('  --no-upgrade        Skip version upgrades');
+        console.error('Usage: npx migrate-edinburgh <import_path> [<table> ...] [options]');
+        console.error('');
+        console.error('  <import_path>     Module that registers all models (required)');
+        console.error('  <table>           Table names to migrate (default: all)');
+        console.error('');
+        console.error('Options:');
+        console.error('  --db <path>       Database directory (default: .edinburgh)');
+        console.error('  -secondaries      Skip populating secondary indexes');
+        console.error('  -primaries        Skip migrating old primary indexes');
+        console.error('  -orphans          Skip removing orphaned index entries');
+        console.error('  +data             Rewrite all row data to latest schema version');
         process.exit(1);
     }
     
@@ -99,14 +90,21 @@ async function main() {
     
     // Report results
     if (Object.keys(result.secondaries).length > 0) {
-        console.log('Upgraded rows:');
+        console.log('Populated secondary indexes:');
         for (const [table, count] of Object.entries(result.secondaries)) {
             console.log(`  ${table}: ${count}`);
         }
     }
     
+    if (Object.keys(result.rewritten).length > 0) {
+        console.log('Rewritten rows:');
+        for (const [table, count] of Object.entries(result.rewritten)) {
+            console.log(`  ${table}: ${count}`);
+        }
+    }
+    
     if (Object.keys(result.primaries).length > 0) {
-        console.log('Converted old primary rows:');
+        console.log('Migrated old primary rows:');
         for (const [table, count] of Object.entries(result.primaries)) {
             console.log(`  ${table}: ${count}`);
         }
@@ -121,11 +119,11 @@ async function main() {
         }
     }
     
-    if (result.orphaned > 0) {
-        console.log(`Deleted ${result.orphaned} orphaned index entries`);
+    if (result.orphans > 0) {
+        console.log(`Deleted ${result.orphans} orphaned index entries`);
     }
     
-    if (Object.keys(result.secondaries).length === 0 && Object.keys(result.primaries).length === 0 && result.orphaned === 0) {
+    if (Object.keys(result.secondaries).length === 0 && Object.keys(result.primaries).length === 0 && Object.keys(result.rewritten).length === 0 && result.orphans === 0) {
         console.log('No migration needed - database is up to date.');
     }