edinburgh 0.4.6 → 0.6.0

package/build/src/utils.js

@@ -1,8 +1,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, message) {
@@ -50,8 +50,8 @@ export function dbDel(txnId, key) {
 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(error, path) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edinburgh",
-  "version": "0.4.6",
+  "version": "0.6.0",
   "author": "Frank van Viegen",
   "devDependencies": {
     "@types/bun": "^1.2.16",
@@ -49,8 +49,6 @@
     "test:node": "bun x vitest --bail 1 --watch=false --silent=passed-only",
     "prepack": "npm run build && npm run test && npm run build:docs",
     "build:docs": "rm -rf skill ; mkdir skill ; cat skill-header.md README.md > skill/SKILL.md && readme-tsdoc --split --file skill/SKILL.md && readme-tsdoc --repo-url https://github.com/vanviegen/edinburgh",
-
-    
     "postinstall": "[ -f .local-post-install.sh ] && sh .local-post-install.sh || true"
   },
   "trustedDependencies": [

package/skill/AnyModelClass.md

@@ -0,0 +1,7 @@
+### AnyModelClass · type
+
+A model constructor with its generic information erased.
+
+Useful when accepting or storing arbitrary registered model classes.
+
+**Type:** `ModelClass<new () => any, readonly any[], any, any>`

package/skill/FindOptions.md

@@ -0,0 +1,37 @@
+### FindOptions · type
+
+Range-query options accepted by `find()`, `findBy()`, `batchProcess()`, and `batchProcessBy()`.
+
+Supports exact-match lookups via `is`, inclusive bounds via `from` / `to`,
+exclusive bounds via `after` / `before`, and reverse scans.
+
+For single-field indexes, values can be passed directly. For composite indexes,
+pass tuples or partial tuples for prefix matching.
+
+**Type:** `(
+    (
+        {is: ArrayOrOnlyItem<ARG_TYPES>;} // Shortcut for setting `from` and `to` to the same value
+    |
+        (
+            (
+                {from: ArrayOrOnlyItem<ARG_TYPES>;}
+            |
+                {after: ArrayOrOnlyItem<ARG_TYPES>;}
+            |
+                {}
+            )
+        &
+            (
+                {to: ArrayOrOnlyItem<ARG_TYPES>;}
+            |
+                {before: ArrayOrOnlyItem<ARG_TYPES>;}
+            |
+                {}
+            )
+        )
+    ) &
+    {
+        reverse?: boolean;
+    }
+    & (FETCH extends undefined ? { fetch?: undefined } : { fetch: FETCH })
+)`

package/skill/Lifecycle Hooks.md

@@ -0,0 +1,24 @@
+### Lifecycle Hooks
+
+- **`static migrate(record)`**: Called when deserializing rows written with an older schema
+  version. Receives a plain record object; mutate it in-place to match the current schema.
+
+- **`preCommit()`**: Called on each modified instance right before the transaction commits.
+  Useful for computing derived fields, enforcing cross-field invariants, or creating related
+  instances.
+
+**Examples:**
+
+```typescript
+const User = E.defineModel("User", class {
+  id = E.field(E.identifier);
+  name = E.field(E.string);
+  email = E.field(E.string);
+}, {
+  pk: "id",
+  unique: { email: "email" },
+});
+// Optional: declare a companion type so `let u: User` works.
+// Not needed if you only use `new User()`, `User.find()`, etc.
+type User = InstanceType<typeof User>;
+```

package/skill/{Model_delete.md → Lifecycle Hooks_delete.md }

@@ -1,4 +1,4 @@
-#### model.delete · method
+#### modelBase.delete · method
 
 Delete this model instance from the database.
 
@@ -9,6 +9,6 @@ Removes the instance and all its index entries from the database and prevents fu
 **Examples:**
 
 ```typescript
-const user = User.load("user123");
+const user = User.get("user123");
 user.delete(); // Removes from database
 ```

package/skill/{Model_getPrimaryKeyHash.md → Lifecycle Hooks_getPrimaryKeyHash.md }

@@ -1,4 +1,4 @@
-#### model.getPrimaryKeyHash · method
+#### modelBase.getPrimaryKeyHash · method
 
 **Signature:** `() => number`
 

package/skill/{Model_isValid.md → Lifecycle Hooks_isValid.md }

@@ -1,4 +1,4 @@
-#### model.isValid · method
+#### modelBase.isValid · method
 
 Check if this model instance is valid.
 

package/skill/Lifecycle Hooks_migrate.md

@@ -0,0 +1,26 @@
+#### ModelBase.migrate · static method
+
+Optional migration function called when deserializing rows written with an older schema version.
+Receives a plain record with all fields and should mutate it in-place to match the current schema.
+It runs during lazy loading and during `runMigration()`. Changing this method creates a new schema version.
+If it updates values used by secondary or unique indexes, those index entries are refreshed only by `runMigration()`.
+
+**Signature:** `(record: Record<string, any>) => void`
+
+**Parameters:**
+
+- `record: Record<string, any>` - A plain object containing the row's field values from the older schema version.
+
+**Examples:**
+
+```typescript
+const User = E.defineModel("User", class {
+  id = E.field(E.identifier);
+  name = E.field(E.string);
+  role = E.field(E.string);
+
+  static migrate(record: Record<string, any>) {
+    record.role ??= "user";
+  }
+}, { pk: "id" });
+```

package/skill/{Model_preCommit.md → Lifecycle Hooks_preCommit.md }

@@ -1,4 +1,4 @@
-#### model.preCommit · method
+#### modelBase.preCommit · method
 
 Optional hook called on each modified instance right before the transaction commits.
 Runs before data is written to disk, so changes made here are included in the commit.
@@ -14,9 +14,7 @@ Common use cases:
 **Examples:**
 
 ```typescript
-⁣@E.registerModel
-class Post extends E.Model<Post> {
-  static pk = E.primary(Post, "id");
+const Post = E.defineModel("Post", class {
   id = E.field(E.identifier);
   title = E.field(E.string);
   slug = E.field(E.string);
@@ -24,5 +22,5 @@ class Post extends E.Model<Post> {
   preCommit() {
     this.slug = this.title.toLowerCase().replace(/\s+/g, "-");
   }
-}
+}, { pk: "id" });
 ```

package/skill/{Model_preventPersist.md → Lifecycle Hooks_preventPersist.md }

@@ -1,4 +1,4 @@
-#### model.preventPersist · method
+#### modelBase.preventPersist · method
 
 Prevent this instance from being persisted to the database.
 
@@ -9,7 +9,7 @@ Prevent this instance from being persisted to the database.
 **Examples:**
 
 ```typescript
-const user = User.load("user123");
+const user = User.get("user123");
 user.name = "New Name";
 user.preventPersist(); // Changes won't be saved
 ```

package/skill/{Model_validate.md → Lifecycle Hooks_validate.md }

@@ -1,4 +1,4 @@
-#### model.validate · method
+#### modelBase.validate · method
 
 Validate all fields in this model instance.
 
@@ -6,7 +6,7 @@ Validate all fields in this model instance.
 
 **Parameters:**
 
-- `raise: boolean` (optional) - - If true, throw on first validation error.
+- `raise: boolean` (optional) - If true, throw on first validation error.
 
 **Returns:** Array of validation errors (empty if valid).
 

package/skill/ModelBase.md

@@ -0,0 +1,7 @@
+### ModelBase · abstract class
+
+Base class for all database models in the Edinburgh ORM.
+
+Models represent database entities with typed fields, automatic serialization,
+change tracking, and relationship management. Model classes are created using
+`E.defineModel()`.

package/skill/ModelClass.md

@@ -0,0 +1,8 @@
+### ModelClass · class
+
+Runtime base constructor for model classes returned by `defineModel()`.
+
+Prefer the `ModelClass` type alias for annotations and the result of
+`defineModel()` for concrete model classes.
+
+**Type:** `typeof ModelClassRuntime`