@ferricstore/ferricstore 0.3.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.3.x` requires FerricStore server `0.9.1` or newer. FerricStore 0.9.1 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.9.1
+  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
@@ -550,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