@ferricstore/ferricstore 0.2.0 → 0.5.0

package/README.md

@@ -18,7 +18,7 @@ Requires Node.js 22.22 or newer. The SDK ships ESM and CommonJS builds and is te
 
 ## Compatibility
 
-SDK `0.2.x` requires FerricStore server `0.8.0` or newer. FerricStore 0.8 is a
+SDK `0.5.x` requires FerricStore server `0.11.0` or newer. FerricStore 0.11 is a
 breaking beta API contract update, while the native wire protocol remains v1
 (`FSNP` framing and existing opcode numbers are unchanged). Capabilities and
 response-size limits are negotiated per connection from the HELLO-shaped
@@ -42,7 +42,50 @@ const { FerricStoreClient, JsonCodec } = require("@ferricstore/ferricstore");
 docker run -p 6388:6388 \
   -e FERRICSTORE_PROTECTED_MODE=false \
   -v ferricstore_data:/data \
-  ghcr.io/ferricstore/ferricstore:0.8.0
+  ghcr.io/ferricstore/ferricstore:0.11.0
+```
+
+## Query durable runs
+
+Use parameterized FQL for bounded, partition-scoped reads. Cursors are opaque
+and must be reused with the same query and parameters.
+
+```ts
+const client = await FerricStoreClient.fromUrl("ferric://127.0.0.1:6388");
+const query = `FROM runs
+WHERE partition_key = @partition AND type = @type AND state = @state
+ORDER BY updated_at_ms ASC LIMIT 25 RETURN RECORDS`;
+const params = { partition: "partition-a", type: "invoice", state: "queued" };
+
+const result = await client.query(query, params);
+const plan = await client.explain(query, params);
+const indexes = await client.queryIndexes();
+```
+
+Each index reports `coveringFields`, which identifies the built-in and dynamic
+`attribute.*` or `state_meta.*` fields that it can return without record
+hydration. Its `format` values are opaque storage-generation identifiers; use
+them to detect a rebuild requirement, not to decode server storage. The
+`counter` format is absent for indexes without counters.
+
+Select a sparse result map by adding up to 32 source-specific fields after
+`RETURN RECORD` or `RETURN RECORDS`, for example
+`RETURN RECORDS (run_id, state, attribute['customer'])`. A bare return keeps the
+complete public record. Projection runs after authorization, authoritative
+recheck, ordering, and cursor calculation: it reduces retained result data,
+encoding, network, and client decoding work, but not index scans or hydration.
+
+Use the source-aware builder to avoid hand-quoting result selectors:
+
+```ts
+const projected = projectFlowQuery(
+  "FROM runs WHERE partition_key = @partition AND run_id = @run",
+  "record",
+  FlowProjection.run.id,
+  FlowProjection.run.state,
+  FlowProjection.run.attribute("customer")
+);
+const result = await client.query(projected, { partition: "partition-a", run: "run-1" });
 ```
 
 ## Cluster-aware client
@@ -387,12 +430,25 @@ await flow.scheduleCreate("orders-every-five-minutes", {
 FIFO Flow state policy is opt-in per state:
 
 ```ts
-await flow.installPolicy("email", {
+const policy = await flow.installPolicy("email", {
   states: {
     queued: { mode: "fifo" }
   }
 });
 
+// Direct writes deep-patch by default. Fence concurrent editors with generation CAS.
+const updated = await flow.installPolicy("email", {
+  expectedGeneration: policy.generation,
+  maxActiveMs: 300_000
+});
+
+// Full replacement is explicit on the client API.
+await flow.installPolicy("email", {
+  expectedGeneration: updated.generation,
+  replace: true,
+  states: { queued: { mode: "fifo" } }
+});
+
 await flow.create("email-3", {
   partitionKey: "tenant-a:email",
   payload: Buffer.from("welcome"),
@@ -402,6 +458,10 @@ await flow.create("email-3", {
 ```
 
 FIFO states require a `partitionKey`; priority is for parallel states.
+`Workflow.installPolicy()` defaults to full replacement because workflow declarations
+describe a complete policy. Pass `replace: false` when a workflow install should patch.
+FIFO ordering is enforced by the server per `(type, state, partitionKey)`; worker
+concurrency remains available across different partitions.
 
 ## FerricStore KV And Data Structures
 
@@ -533,6 +593,15 @@ FERRICSTORE_INTEGRATION=1 npm run test:integration
 npm run integration:down
 ```
 
+Benchmark raw FQL and the record convenience layer against a live server. The default
+comparison interleaves both paths and fails if either performs more than one `FLOW.QUERY`
+or any `FLOW.GET` hydration per operation:
+
+```bash
+npm run build
+npm run bench:flow-query -- --requests 500 --concurrency 2 --rows 100 --pretty
+```
+
 Generate API docs with:
 
 ```bash