@jarenjs/linq 0.66.1 → 0.67.0

package/docs/DB-CLIENT.md

@@ -83,10 +83,9 @@ invent one. §2 keeps its D3 slot and its meaning — this is where every
 name a caller writes is named — under the title that describes what it
 holds.
 
-The vocabulary is small and the surface is not. Two exported names, and
-then whatever those two hand back: a client of frozen handles, each of
+The exports include the store door and its helpers. The door hands back a client of frozen handles, each of
 which is the store's own set plus the chain plus three additions. §2.1
-divides the two; §2.2 to §2.5 enumerate them.
+divides the responsibilities; §2.2 to §2.7 enumerate the surface.
 
 ### 2.1 What is the store's and what is the client's
 
@@ -105,14 +104,15 @@ decides which document answers a question about behaviour.
 | `client.collections.<name>` | the store's collection | the same chain start and `live`, typed from the pen's collection schema (§2.5) |
 | `saveChanges()`, `transaction(fn)`, `close()`, `capabilities`, `store` | the store's | pass-throughs; `saveChanges` and `live` exist exactly when the model declares entities, as on the store; `store` is the escape hatch, typed `TypedStore` |
 
-### 2.2 The three exported names
+### 2.2 The exported names
 
 The whole export surface: a door, a type-level reader for what it hands
-back, and the durable ledger over what it opened.
+back, the durable ledger over what it opened, and replication document authoring.
 
 | Name | Answers | Type reading |
 |---|---|---|
 | `open(model, options)` | a promise of the frozen client — `store`, `capabilities`, `entities`, `collections`, `transaction`, `close`, and `saveChanges`/`live` when the model declares entities | `Client<InferMeta<typeof model>>` for a pen model; `Client<E>` for `open<E>(json, …)`; the wide map for a bare JSON model |
+| `defineReplication(header)` | a logical replication document builder — §2.7 | `ReplicationPen` |
 | `defaultValidator()` | `new JarenValidator({ collectErrors: true })` with `stringFormats` and `dateTimeFormats` registered | `JarenValidator` |
 | `createDbLedger(client, options?)` | the contract idempotency ledger (`claim`/`commit`/`fail`/`lookup`/`sweep`) over a declared collection of the client's store — §2.6 | `DbLedger`; structurally `@jarenjs/contract`'s `Ledger` |
 
@@ -298,6 +298,17 @@ await db.transaction(async (tx) => {                          // a settlement in
 });
 ```
 
+### 2.7 Replication documents
+
+The DB client forwards `replication` open options to its Store. Access committed
+pages, frontiers, conflicts and resets through `client.store.replication`.
+`defineReplication({ replica, seq, frontier, model })` authors a logical envelope:
+chain `.change(table, key, before, after)`, then `.toDocument()` or `.toJSON()`.
+It shares the Store's normalization authority and preserves operation order.
+See the [replication format](../../db/docs/REPLICATION-FORMAT.md) for causality,
+conflict policy and bounded reset contracts. Authoring does not allocate a
+committed sequence; normal replication exports the Store's committed pages.
+
 ## 3. Worked examples
 
 The client's examples are not builder-to-document pairs, and this is
@@ -815,10 +826,10 @@ never builds one; the migration between two of them is
 
 ## 7. Cost
 
-`@jarenjs/linq/db` builds to **<!--fact:bundle.db-->591,917<!--/fact--> bytes** as a minified,
+`@jarenjs/linq/db` builds to **<!--fact:bundle.db-->623,994<!--/fact--> bytes** as a minified,
 tree-shaken ESM bundle — the figure `scripts/check-tree-shaking.js`
 measures and `npm run test:tree-shaking` reports, published rounded
-(<!--fact:bundle.db.kb-->592<!--/fact--> kB) beside the other nine subpath prices in
+(<!--fact:bundle.db.kb-->624<!--/fact--> kB) beside the other nine subpath prices in
 [docs/CONSUMING.md](../../../docs/CONSUMING.md).
 
 It is by far the largest of the ten, and the reason is §1.1's edge rather

package/docs/LINQ-FORMAT.md

@@ -35,7 +35,7 @@ is the index of the ten, and it is how a reader reaches any of them.
 <!--fact:pens.index-->
 | Document | Lines | What it writes, and when to open it |
 |---|---:|---|
-| [LINQ-FORMAT.md](LINQ-FORMAT.md) | 819 | this file, the binder and the family's **normative reference**: what a pen is, the rules all of them keep, the shared `JL01xx` table, and the cross-pen views derived from the ten guides it indexes. **Read it when** you want a rule that is true of every pen, an index of the eleven documents, or one place to look up a method without knowing which pen owns it |
+| [LINQ-FORMAT.md](LINQ-FORMAT.md) | 820 | this file, the binder and the family's **normative reference**: what a pen is, the rules all of them keep, the shared `JL01xx` table, and the cross-pen views derived from the ten guides it indexes. **Read it when** you want a rule that is true of every pen, an index of the eleven documents, or one place to look up a method without knowing which pen owns it |
 | [QUERY-PEN.md](QUERY-PEN.md) | 1,724 | the chain, `.` — query documents (`jaren-query`) and the provider seam. **Read it when** you are querying data, or implementing a provider that answers a query document |
 | [SCHEMA-PEN.md](SCHEMA-PEN.md) | 1,218 | `./schema` — JSON Schema 2020-12: the structural keywords, the constraints and the annotations, each with a method of its own, plus `$query`, `$defs`/`$ref` recursion and the normalizer's per-field predicates. **Read it when** you are describing the shape of data — for validation, for a form, or as the base of an entity |
 | [MODEL-PEN.md](MODEL-PEN.md) | 1,092 | `./model` — the `x-entity` vocabulary on JSON Schema, and the `$model` 0.1 document `openStore` accepts unchanged. **Read it when** you are declaring a store's entities, their keys and their relations |
@@ -45,7 +45,7 @@ is the index of the ten, and it is how a reader reaches any of them.
 | [FLOW-PEN.md](FLOW-PEN.md) | 1,033 | `./flow` — `jaren-fsm` 0.1 machines and `jaren-dag` 0.1 dataflows, every query-valued member captured. **Read it when** you are declaring a state machine or a dependency graph of tasks |
 | [APP-PEN.md](APP-PEN.md) | 1,143 | `./app` — the `jaren-app` 0.1 document `createApp` runs, and the JSON Schema of its state beside it. **Read it when** you are declaring a whole application: state, view, actions, effects |
 | [FORMS-PEN.md](FORMS-PEN.md) | 940 | `./forms` — the `x-form` vocabulary on JSON Schema, and `assertOnSubmit()`, the same rules' layer-3 `$query` twin. **Read it when** you are turning a schema into a form |
-| [DB-CLIENT.md](DB-CLIENT.md) | 882 | `./db` — the client: the store's typed front door, not a pen, and the package's one runtime edge. **Read it when** you are reading or writing rows: `load`, `include`, `link`/`unlink`, `live` |
+| [DB-CLIENT.md](DB-CLIENT.md) | 893 | `./db` — the client: the store's typed front door, not a pen, and the package's one runtime edge. **Read it when** you are reading or writing rows: `load`, `include`, `link`/`unlink`, `live` |
 <!--/fact-->
 
 Every row of that table is derived, and none of it is written here: the
@@ -201,7 +201,7 @@ and the bundle is the byte count the tree-shaking probe builds.
 <!--fact:pens.census-->
 | Document | Subpath | Lines | Mapping rows | Worked examples | Refusals | Bundle |
 |---|---|---:|---:|---:|---:|---:|
-| [LINQ-FORMAT.md](LINQ-FORMAT.md) | — | 819 | — | — | — | — |
+| [LINQ-FORMAT.md](LINQ-FORMAT.md) | — | 820 | — | — | — | — |
 | [QUERY-PEN.md](QUERY-PEN.md) | `.` | 1,724 | 34 | 8 | 15 | 174,264 B |
 | [SCHEMA-PEN.md](SCHEMA-PEN.md) | `./schema` | 1,218 | 66 | 10 | 4 | 33,156 B |
 | [MODEL-PEN.md](MODEL-PEN.md) | `./model` | 1,092 | 28 | 6 | 3 | 41,582 B |
@@ -211,8 +211,8 @@ and the bundle is the byte count the tree-shaking probe builds.
 | [FLOW-PEN.md](FLOW-PEN.md) | `./flow` | 1,033 | 16 | 7 | 3 | 19,910 B |
 | [APP-PEN.md](APP-PEN.md) | `./app` | 1,143 | 22 | 7 | 3 | 47,444 B |
 | [FORMS-PEN.md](FORMS-PEN.md) | `./forms` | 940 | 18 | 6 | 3 | 37,312 B |
-| [DB-CLIENT.md](DB-CLIENT.md) | `./db` | 882 | 40 | 4 | 2 | 591,917 B |
-| **eleven documents** | | **11,808** | **290** | **67** | | |
+| [DB-CLIENT.md](DB-CLIENT.md) | `./db` | 893 | 41 | 4 | 2 | 623,994 B |
+| **eleven documents** | | **11,820** | **291** | **67** | | |
 <!--/fact-->
 
 A pen whose mapping rows are far below its worked examples is a pen
@@ -263,7 +263,7 @@ it and each document publishes it. The rounded column is what
 | `@jarenjs/linq/flow` | [FLOW-PEN.md](FLOW-PEN.md) | 19,910 B | 20 kB |
 | `@jarenjs/linq/app` | [APP-PEN.md](APP-PEN.md) | 47,444 B | 47 kB |
 | `@jarenjs/linq/forms` | [FORMS-PEN.md](FORMS-PEN.md) | 37,312 B | 37 kB |
-| `@jarenjs/linq/db` | [DB-CLIENT.md](DB-CLIENT.md) | 591,917 B | 592 kB |
+| `@jarenjs/linq/db` | [DB-CLIENT.md](DB-CLIENT.md) | 623,994 B | 624 kB |
 <!--/fact-->
 
 Read these as prices, not as scores. `./db` is the largest by an order of
@@ -767,11 +767,12 @@ it says.
 | `client.collections.<name>` | the store's collection | the same chain start and `live`, typed from the pen's collection schema (§2.5) |
 | `saveChanges()`, `transaction(fn)`, `close()`, `capabilities`, `store` | the store's | pass-throughs; `saveChanges` and `live` exist exactly when the model declares entities, as on the store; `store` is the escape hatch, typed `TypedStore` |
 
-**The three exported names**
+**The exported names**
 
 | Name | Answers | Type reading |
 |---|---|---|
 | `open(model, options)` | a promise of the frozen client — `store`, `capabilities`, `entities`, `collections`, `transaction`, `close`, and `saveChanges`/`live` when the model declares entities | `Client<InferMeta<typeof model>>` for a pen model; `Client<E>` for `open<E>(json, …)`; the wide map for a bare JSON model |
+| `defineReplication(header)` | a logical replication document builder — §2.7 | `ReplicationPen` |
 | `defaultValidator()` | `new JarenValidator({ collectErrors: true })` with `stringFormats` and `dateTimeFormats` registered | `JarenValidator` |
 | `createDbLedger(client, options?)` | the contract idempotency ledger (`claim`/`commit`/`fail`/`lookup`/`sweep`) over a declared collection of the client's store — §2.6 | `DbLedger`; structurally `@jarenjs/contract`'s `Ledger` |
 

package/docs/QUERY-PEN.md

@@ -1705,7 +1705,7 @@ making:
 `docs/CONSUMING.md` states the rounded price of all ten subpaths in one
 table, each figure held equal to the same measurements. Two of its rows
 are the ones to read together: the chain at <!--fact:bundle.chain.kb-->174<!--/fact--> kB and
-`./db` at <!--fact:bundle.db.kb-->592<!--/fact--> kB.
+`./db` at <!--fact:bundle.db.kb-->624<!--/fact--> kB.
 The client costs what the store costs, by construction, and the chain
 costs what running a query costs.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/linq",
   "private": false,
-  "version": "0.66.1",
+  "version": "0.67.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -84,13 +84,13 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.66.1",
-    "@jarenjs/json": "^0.66.1"
+    "@jarenjs/core": "^0.67.0",
+    "@jarenjs/json": "^0.67.0"
   },
   "peerDependencies": {
-    "@jarenjs/db": "^0.66.1",
-    "@jarenjs/formats": "^0.66.1",
-    "@jarenjs/validate": "^0.66.1"
+    "@jarenjs/db": "^0.67.0",
+    "@jarenjs/formats": "^0.67.0",
+    "@jarenjs/validate": "^0.67.0"
   },
   "peerDependenciesMeta": {
     "@jarenjs/db": {

package/src/db/index.js

@@ -22,3 +22,4 @@
 
 export { open, defaultValidator } from './open.js';
 export { createDbLedger } from './ledger.js';
+export { defineReplication } from './replication.js';

package/src/db/replication.js

@@ -0,0 +1,20 @@
+//@ts-check
+/** Deterministic logical-envelope authoring through the DB format authority. */
+import { normalizeReplication } from '@jarenjs/db';
+
+/** Start a transport-neutral replication document; changes remain in declared order.
+ * @param {{ replica: string, seq: number, frontier: Record<string, number>, model: string }} header */
+export function defineReplication(header) {
+  const operations = [];
+  const builder = Object.freeze({
+    /** @param {string} table @param {string} key @param {any} before @param {any} after */
+    change(table, key, before, after) {
+      operations.push(structuredClone({ table, key, before, after }));
+      return builder;
+    },
+    toDocument() { return normalizeReplication({ $replication: '0.1', ...header, operations }); },
+    toJSON() { return builder.toDocument(); },
+  });
+  header = structuredClone(header);
+  return builder;
+}

package/types/db.d.ts

@@ -357,3 +357,10 @@ export type Client<E extends MetaMap<E>, C = Record<string, unknown>> = {
     options?: TransactionOptions): Promise<Awaited<R>>;
   close(options?: { graceMs?: number }): Promise<void>;
 } & ([keyof E] extends [never] ? {} : EntityClientMembers);
+
+/** Author a logical envelope using the DB's canonical format validator. */
+export function defineReplication(header: Omit<import('@jarenjs/db').ReplicationEnvelope, '$replication' | 'operations'>): {
+  change(table: string, key: string, before: Record<string, unknown> | null, after: Record<string, unknown> | null): ReturnType<typeof defineReplication>;
+  toDocument(): import('@jarenjs/db').ReplicationEnvelope;
+  toJSON(): import('@jarenjs/db').ReplicationEnvelope;
+};