@jarenjs/db 0.34.0

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@jarenjs/db",
+  "private": false,
+  "version": "0.34.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./node": {
+      "types": "./types/node.d.ts",
+      "default": "./src/drivers/node.js"
+    },
+    "./bun": {
+      "types": "./types/bun.d.ts",
+      "default": "./src/drivers/bun.js"
+    },
+    "./wasm": {
+      "types": "./types/wasm.d.ts",
+      "default": "./src/drivers/wasm.js"
+    },
+    "./typed": {
+      "types": "./types/typed.d.ts",
+      "default": "./src/typed.js"
+    },
+    "./app": {
+      "types": "./types/app.d.ts",
+      "default": "./src/app.js"
+    },
+    "./schemas/*": "./schemas/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "types/",
+    "dist/types/",
+    "src/",
+    "schemas/",
+    "docs/",
+    "ARCHITECTURE.md"
+  ],
+  "description": "Document storage for the Jaren suite: a model document declares collections as JSON Schemas with indexes; openStore applies DDL through a dialect and gives transactional, schema-validated reads and writes over SQLite on Node, Bun, or an injected wasm handle",
+  "author": "joham",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jklarenbeek/jarenjs.git",
+    "directory": "packages/db"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "jaren",
+    "json",
+    "sqlite",
+    "document-store",
+    "json-schema",
+    "database"
+  ],
+  "scripts": {
+    "build": "npm run build:types",
+    "build:types": "tsc -p tsconfig.json",
+    "prepack": "npm run build:types"
+  },
+  "dependencies": {
+    "@jarenjs/core": "^0.34.0",
+    "@jarenjs/json": "^0.34.0",
+    "@jarenjs/validate": "^0.34.0"
+  },
+  "bin": {
+    "jaren-db": "./src/cli.js"
+  }
+}

package/schemas/jaren-migration.draft-07.schema.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://jarenjs.dev/schemas/jaren-migration/draft-07",
+  "title": "Jaren migration document",
+  "description": "A jaren-migration document evolves a store from one shape to another: ordered steps of rendered DDL, JSLT data transforms and query assertions, between two shape hashes. The hashes identify SHAPES (hashContent over the canonicalized model document), not version numbers a human must remember to bump; a migration whose from-hash does not match the database's recorded shape refuses to run.",
+  "type": "object",
+  "properties": {
+    "$migration": {
+      "description": "The migration format version.",
+      "const": "0.1"
+    },
+    "id": {
+      "description": "The migration's unique identifier, recorded in the history table.",
+      "type": "string",
+      "minLength": 1
+    },
+    "from": {
+      "description": "The shape hash this migration applies to.",
+      "type": "string",
+      "minLength": 1
+    },
+    "to": {
+      "description": "The shape hash this migration produces.",
+      "type": "string",
+      "minLength": 1
+    },
+    "note": {
+      "description": "Free prose for the reader; ignored by the runner.",
+      "type": "string"
+    },
+    "steps": {
+      "description": "Ordered steps; the order is the contract. A pure widening may carry NO steps — the migration then only moves the recorded shape.",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/step"
+      }
+    }
+  },
+  "required": [
+    "$migration",
+    "id",
+    "from",
+    "to",
+    "steps"
+  ],
+  "additionalProperties": false,
+  "definitions": {
+    "step": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/ddlStep"
+        },
+        {
+          "$ref": "#/definitions/jsltStep"
+        },
+        {
+          "$ref": "#/definitions/queryStep"
+        }
+      ]
+    },
+    "ddlStep": {
+      "description": "One rendered DDL statement, produced by the planner through the dialect and shown before it is executed.",
+      "type": "object",
+      "properties": {
+        "kind": {
+          "const": "ddl"
+        },
+        "sql": {
+          "type": "string",
+          "minLength": 1
+        },
+        "note": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "sql"
+      ],
+      "additionalProperties": false
+    },
+    "jsltStep": {
+      "description": "Rewrite every document of a collection through a compiled JSLT stylesheet, in batches, inside the migration's transaction. A draft step (the planner's identity placeholder) refuses to run until the author fills it in.",
+      "type": "object",
+      "properties": {
+        "kind": {
+          "const": "jslt"
+        },
+        "collection": {
+          "type": "string",
+          "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+        },
+        "stylesheet": {
+          "description": "A JSLT stylesheet (an array of match/body rules; the empty array is the identity transform).",
+          "type": "array"
+        },
+        "draft": {
+          "description": "True on a planner-emitted placeholder: the schema changed and no transform can be inferred. The runner refuses a draft step.",
+          "type": "boolean"
+        },
+        "note": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "collection",
+        "stylesheet"
+      ],
+      "additionalProperties": false
+    },
+    "queryStep": {
+      "description": "An assertion: the query runs over the collection's documents and must answer an empty sequence (expect 'empty', the default) or an EBV-true value (expect 'ebv') for the migration to proceed. This is how a migration states its own precondition.",
+      "type": "object",
+      "properties": {
+        "kind": {
+          "const": "query"
+        },
+        "collection": {
+          "type": "string",
+          "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+        },
+        "assert": {
+          "description": "A Jaren query document over the collection's documents."
+        },
+        "expect": {
+          "enum": [
+            "empty",
+            "ebv"
+          ]
+        },
+        "note": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "collection",
+        "assert"
+      ],
+      "additionalProperties": false
+    }
+  }
+}

package/schemas/jaren-migration.schema.json

@@ -0,0 +1,144 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://jarenjs.dev/schemas/jaren-migration",
+ "title": "Jaren migration document",
+ "description": "A jaren-migration document evolves a store from one shape to another: ordered steps of rendered DDL, JSLT data transforms and query assertions, between two shape hashes. The hashes identify SHAPES (hashContent over the canonicalized model document), not version numbers a human must remember to bump; a migration whose from-hash does not match the database's recorded shape refuses to run.",
+ "type": "object",
+ "properties": {
+  "$migration": {
+   "description": "The migration format version.",
+   "const": "0.1"
+  },
+  "id": {
+   "description": "The migration's unique identifier, recorded in the history table.",
+   "type": "string",
+   "minLength": 1
+  },
+  "from": {
+   "description": "The shape hash this migration applies to.",
+   "type": "string",
+   "minLength": 1
+  },
+  "to": {
+   "description": "The shape hash this migration produces.",
+   "type": "string",
+   "minLength": 1
+  },
+  "note": {
+   "description": "Free prose for the reader; ignored by the runner.",
+   "type": "string"
+  },
+  "steps": {
+   "description": "Ordered steps; the order is the contract. A pure widening may carry NO steps — the migration then only moves the recorded shape.",
+   "type": "array",
+   "items": {
+    "$ref": "#/$defs/step"
+   }
+  }
+ },
+ "required": [
+  "$migration",
+  "id",
+  "from",
+  "to",
+  "steps"
+ ],
+ "additionalProperties": false,
+ "$defs": {
+  "step": {
+   "oneOf": [
+    {
+     "$ref": "#/$defs/ddlStep"
+    },
+    {
+     "$ref": "#/$defs/jsltStep"
+    },
+    {
+     "$ref": "#/$defs/queryStep"
+    }
+   ]
+  },
+  "ddlStep": {
+   "description": "One rendered DDL statement, produced by the planner through the dialect and shown before it is executed.",
+   "type": "object",
+   "properties": {
+    "kind": {
+     "const": "ddl"
+    },
+    "sql": {
+     "type": "string",
+     "minLength": 1
+    },
+    "note": {
+     "type": "string"
+    }
+   },
+   "required": [
+    "kind",
+    "sql"
+   ],
+   "additionalProperties": false
+  },
+  "jsltStep": {
+   "description": "Rewrite every document of a collection through a compiled JSLT stylesheet, in batches, inside the migration's transaction. A draft step (the planner's identity placeholder) refuses to run until the author fills it in.",
+   "type": "object",
+   "properties": {
+    "kind": {
+     "const": "jslt"
+    },
+    "collection": {
+     "type": "string",
+     "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+    },
+    "stylesheet": {
+     "description": "A JSLT stylesheet (an array of match/body rules; the empty array is the identity transform).",
+     "type": "array"
+    },
+    "draft": {
+     "description": "True on a planner-emitted placeholder: the schema changed and no transform can be inferred. The runner refuses a draft step.",
+     "type": "boolean"
+    },
+    "note": {
+     "type": "string"
+    }
+   },
+   "required": [
+    "kind",
+    "collection",
+    "stylesheet"
+   ],
+   "additionalProperties": false
+  },
+  "queryStep": {
+   "description": "An assertion: the query runs over the collection's documents and must answer an empty sequence (expect 'empty', the default) or an EBV-true value (expect 'ebv') for the migration to proceed. This is how a migration states its own precondition.",
+   "type": "object",
+   "properties": {
+    "kind": {
+     "const": "query"
+    },
+    "collection": {
+     "type": "string",
+     "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+    },
+    "assert": {
+     "description": "A Jaren query document over the collection's documents."
+    },
+    "expect": {
+     "enum": [
+      "empty",
+      "ebv"
+     ]
+    },
+    "note": {
+     "type": "string"
+    }
+   },
+   "required": [
+    "kind",
+    "collection",
+    "assert"
+   ],
+   "additionalProperties": false
+  }
+ }
+}

package/schemas/jaren-model.draft-07.schema.json

@@ -0,0 +1,149 @@
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "$id": "https://jarenjs.dev/schemas/jaren-model/draft-07",
+ "title": "Jaren model document",
+ "description": "A jaren-model document declares the collections of a store: each collection is a JSON Schema for its documents, a key declaration (an RFC 6901 pointer for caller-supplied keys, or null with a declared identity for store-allocated ones), and the indexes over singular JSONPath expressions. A model declares collections (the storage subset: every property JSONB, no relations), entities (the relational subset: keys, typed columns, relations via the x-entity vocabulary), or both; vocabulary is added to THIS format, never as a second format.",
+ "type": "object",
+ "properties": {
+  "$model": {
+   "description": "The model format version.",
+   "const": "0.1"
+  },
+  "collections": {
+   "description": "Collection name (an identifier) to collection declaration.",
+   "type": "object",
+   "minProperties": 1,
+   "propertyNames": {
+    "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+   },
+   "additionalProperties": {
+    "$ref": "#/definitions/collection"
+   }
+  },
+  "entities": {
+   "description": "Entity name (an identifier) to entity declaration. The x-entity vocabulary lives INSIDE each entity schema's property subschemas and is documented in MODEL-FORMAT.md §9; stripping it leaves a plain JSON Schema.",
+   "type": "object",
+   "minProperties": 1,
+   "propertyNames": {
+    "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+   },
+   "additionalProperties": {
+    "$ref": "#/definitions/entity"
+   }
+  }
+ },
+ "required": [
+  "$model"
+ ],
+ "additionalProperties": false,
+ "definitions": {
+  "collection": {
+   "description": "One collection: a document schema, the key declaration, and the declared indexes. A collection without a key pointer MUST declare how keys are allocated; allocation is declared, never guessed.",
+   "type": "object",
+   "properties": {
+    "schema": {
+     "description": "The JSON Schema every stored document validates against (through the injected hook). Also the type source for indexed paths.",
+     "type": "object"
+    },
+    "key": {
+     "description": "Where the caller-supplied key lives in the document, as an RFC 6901 pointer selecting at least one member — or null when the store allocates.",
+     "type": [
+      "string",
+      "null"
+     ],
+     "pattern": "^/"
+    },
+    "identity": {
+     "description": "How keys come to be: 'caller' (the default when a key pointer is declared), or — only with \"key\": null — 'uuid' (crypto.randomUUID) or 'integer' (database-allocated).",
+     "enum": [
+      "caller",
+      "uuid",
+      "integer"
+     ]
+    },
+    "indexes": {
+     "description": "Declared indexes; each singular path becomes a generated column plus an index.",
+     "type": "array",
+     "items": {
+      "$ref": "#/definitions/index"
+     }
+    },
+    "x-rename": {
+     "description": "Migration hint: this collection was previously named the given identifier. Read by the migration planner (a rename cannot be inferred from a diff); ignored by the store.",
+     "type": "string",
+     "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+    }
+   },
+   "required": [
+    "schema"
+   ],
+   "additionalProperties": false
+  },
+  "index": {
+   "description": "One index over a singular JSONPath expression (or a composite over several). A non-singular path is rejected at open (JD0004).",
+   "type": "object",
+   "properties": {
+    "name": {
+     "description": "The index name, unique within its collection.",
+     "type": "string",
+     "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+    },
+    "path": {
+     "description": "A singular JSONPath expression into the stored document ($.email), or a non-empty array of them for a composite index.",
+     "oneOf": [
+      {
+       "type": "string",
+       "minLength": 1
+      },
+      {
+       "type": "array",
+       "items": {
+        "type": "string",
+        "minLength": 1
+       },
+       "minItems": 1
+      }
+     ]
+    },
+    "unique": {
+     "description": "Whether the index enforces uniqueness. Defaults to false.",
+     "type": "boolean"
+    }
+   },
+   "required": [
+    "name",
+    "path"
+   ],
+   "additionalProperties": false
+  },
+  "entity": {
+   "description": "One entity: an object schema whose top-level properties map to columns per the hybrid rule (scalars become typed columns, nested shapes stay JSONB); keys, indexes, defaults and relations are declared with x-entity inside the schema.",
+   "type": "object",
+   "properties": {
+    "schema": {
+     "type": "object"
+    },
+    "x-rename": {
+     "type": "string",
+     "description": "Declares this entity as the rename of the named from-model entity (MIGRATION-FORMAT §9): a rename is declared, never inferred."
+    }
+   },
+   "required": [
+    "schema"
+   ],
+   "additionalProperties": false
+  }
+ },
+ "anyOf": [
+  {
+   "required": [
+    "collections"
+   ]
+  },
+  {
+   "required": [
+    "entities"
+   ]
+  }
+ ]
+}

package/schemas/jaren-model.schema.json

@@ -0,0 +1,149 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://jarenjs.dev/schemas/jaren-model",
+ "title": "Jaren model document",
+ "description": "A jaren-model document declares the collections of a store: each collection is a JSON Schema for its documents, a key declaration (an RFC 6901 pointer for caller-supplied keys, or null with a declared identity for store-allocated ones), and the indexes over singular JSONPath expressions. A model declares collections (the storage subset: every property JSONB, no relations), entities (the relational subset: keys, typed columns, relations via the x-entity vocabulary), or both; vocabulary is added to THIS format, never as a second format.",
+ "type": "object",
+ "properties": {
+  "$model": {
+   "description": "The model format version.",
+   "const": "0.1"
+  },
+  "collections": {
+   "description": "Collection name (an identifier) to collection declaration.",
+   "type": "object",
+   "minProperties": 1,
+   "propertyNames": {
+    "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+   },
+   "additionalProperties": {
+    "$ref": "#/$defs/collection"
+   }
+  },
+  "entities": {
+   "description": "Entity name (an identifier) to entity declaration. The x-entity vocabulary lives INSIDE each entity schema's property subschemas and is documented in MODEL-FORMAT.md \u00a79; stripping it leaves a plain JSON Schema.",
+   "type": "object",
+   "minProperties": 1,
+   "propertyNames": {
+    "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+   },
+   "additionalProperties": {
+    "$ref": "#/$defs/entity"
+   }
+  }
+ },
+ "required": [
+  "$model"
+ ],
+ "additionalProperties": false,
+ "$defs": {
+  "collection": {
+   "description": "One collection: a document schema, the key declaration, and the declared indexes. A collection without a key pointer MUST declare how keys are allocated; allocation is declared, never guessed.",
+   "type": "object",
+   "properties": {
+    "schema": {
+     "description": "The JSON Schema every stored document validates against (through the injected hook). Also the type source for indexed paths.",
+     "type": "object"
+    },
+    "key": {
+     "description": "Where the caller-supplied key lives in the document, as an RFC 6901 pointer selecting at least one member \u2014 or null when the store allocates.",
+     "type": [
+      "string",
+      "null"
+     ],
+     "pattern": "^/"
+    },
+    "identity": {
+     "description": "How keys come to be: 'caller' (the default when a key pointer is declared), or \u2014 only with \"key\": null \u2014 'uuid' (crypto.randomUUID) or 'integer' (database-allocated).",
+     "enum": [
+      "caller",
+      "uuid",
+      "integer"
+     ]
+    },
+    "indexes": {
+     "description": "Declared indexes; each singular path becomes a generated column plus an index.",
+     "type": "array",
+     "items": {
+      "$ref": "#/$defs/index"
+     }
+    },
+    "x-rename": {
+     "description": "Migration hint: this collection was previously named the given identifier. Read by the migration planner (a rename cannot be inferred from a diff); ignored by the store.",
+     "type": "string",
+     "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+    }
+   },
+   "required": [
+    "schema"
+   ],
+   "additionalProperties": false
+  },
+  "index": {
+   "description": "One index over a singular JSONPath expression (or a composite over several). A non-singular path is rejected at open (JD0004).",
+   "type": "object",
+   "properties": {
+    "name": {
+     "description": "The index name, unique within its collection.",
+     "type": "string",
+     "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+    },
+    "path": {
+     "description": "A singular JSONPath expression into the stored document ($.email), or a non-empty array of them for a composite index.",
+     "oneOf": [
+      {
+       "type": "string",
+       "minLength": 1
+      },
+      {
+       "type": "array",
+       "items": {
+        "type": "string",
+        "minLength": 1
+       },
+       "minItems": 1
+      }
+     ]
+    },
+    "unique": {
+     "description": "Whether the index enforces uniqueness. Defaults to false.",
+     "type": "boolean"
+    }
+   },
+   "required": [
+    "name",
+    "path"
+   ],
+   "additionalProperties": false
+  },
+  "entity": {
+   "description": "One entity: an object schema whose top-level properties map to columns per the hybrid rule (scalars become typed columns, nested shapes stay JSONB); keys, indexes, defaults and relations are declared with x-entity inside the schema.",
+   "type": "object",
+   "properties": {
+    "schema": {
+     "type": "object"
+    },
+    "x-rename": {
+     "type": "string",
+     "description": "Declares this entity as the rename of the named from-model entity (MIGRATION-FORMAT \u00a79): a rename is declared, never inferred."
+    }
+   },
+   "required": [
+    "schema"
+   ],
+   "additionalProperties": false
+  }
+ },
+ "anyOf": [
+  {
+   "required": [
+    "collections"
+   ]
+  },
+  {
+   "required": [
+    "entities"
+   ]
+  }
+ ]
+}