@ferricstore/ferricstore 0.1.0 → 0.1.2

package/README.md

@@ -22,7 +22,7 @@ Requires Node.js 24 or newer. The SDK is ESM-only and tested with Node 24 and 26
 docker run -p 6388:6388 \
   -e FERRICSTORE_PROTECTED_MODE=false \
   -v ferricstore_data:/data \
-  ghcr.io/ferricstore/ferricstore:0.5.2
+  ghcr.io/ferricstore/ferricstore:0.6.0
 ```
 
 ## Durable Queue

package/dist/index.d.ts

@@ -484,12 +484,15 @@ interface ChildSpec {
     values?: Record<string, unknown>;
     valueRefs?: Record<string, string>;
 }
+type StateMetaValue = string | number | boolean | Buffer;
+type StateMeta = Record<string, StateMetaValue>;
 interface CreateItem {
     id: string;
     payload?: unknown;
     partitionKey?: string;
     values?: Record<string, unknown>;
     valueRefs?: Record<string, string>;
+    stateMeta?: StateMeta;
 }
 declare const CLAIMED_ITEM_WIRE: unique symbol;
 interface ClaimedItemWire {
@@ -557,6 +560,8 @@ interface FlowRecord<TPayload = unknown> {
     valueOmitted?: Record<string, unknown>;
     valueMissing?: Record<string, unknown>;
     attributes?: Record<string, unknown>;
+    stateMeta?: Record<string, unknown>;
+    indexedStateMeta?: string;
     raw?: unknown;
 }
 
@@ -586,6 +591,7 @@ interface CreateOptions {
     retentionTtlMs?: number;
     values?: Record<string, unknown>;
     valueRefs?: Record<string, string>;
+    stateMeta?: StateMeta;
     returnRecord?: boolean;
 }
 interface CreateManyOptions extends Omit<CreateOptions, "payload" | "partitionKey" | "returnRecord"> {
@@ -622,6 +628,7 @@ interface MutateOptions {
     valueRefs?: Record<string, string>;
     dropValues?: string[];
     overrideValues?: string[];
+    stateMeta?: StateMeta;
     nowMs?: number;
     returnRecord?: boolean;
 }
@@ -654,6 +661,7 @@ interface CancelOptions {
     reason?: unknown;
     ttlMs?: number;
     nowMs?: number;
+    stateMeta?: StateMeta;
     returnRecord?: boolean;
 }
 interface ReadOptions {
@@ -836,6 +844,7 @@ declare class FerricStoreClient {
         valueRefs?: Record<string, string>;
         dropValues?: string[];
         overrideValues?: string[];
+        stateMeta?: StateMeta;
         ttlMs?: number;
         nowMs?: number;
         independent?: boolean;
@@ -851,6 +860,7 @@ declare class FerricStoreClient {
         valueRefs?: Record<string, string>;
         dropValues?: string[];
         overrideValues?: string[];
+        stateMeta?: StateMeta;
         runAtMs?: number;
         nowMs?: number;
         priority?: number;
@@ -864,6 +874,7 @@ declare class FerricStoreClient {
         valueRefs?: Record<string, string>;
         dropValues?: string[];
         overrideValues?: string[];
+        stateMeta?: StateMeta;
         runAtMs?: number;
         nowMs?: number;
         independent?: boolean;
@@ -876,6 +887,7 @@ declare class FerricStoreClient {
         valueRefs?: Record<string, string>;
         dropValues?: string[];
         overrideValues?: string[];
+        stateMeta?: StateMeta;
         ttlMs?: number;
         nowMs?: number;
         independent?: boolean;
@@ -883,6 +895,7 @@ declare class FerricStoreClient {
     cancel(id: string, options: CancelOptions): Promise<FlowRecord | Buffer | unknown>;
     cancelMany(partitionKey: string | undefined, items: FencedItem[], options?: {
         reason?: unknown;
+        stateMeta?: StateMeta;
         ttlMs?: number;
         nowMs?: number;
         independent?: boolean;
@@ -937,6 +950,7 @@ declare class FerricStoreClient {
         state?: string;
         retry?: RetryPolicy;
         retentionTtlMs?: number;
+        indexedStateMeta?: string;
     }): Promise<unknown>;
     policyGet(type: string, options?: {
         state?: string;
@@ -999,6 +1013,7 @@ interface NamedValueMutation {
     valueRefs?: Record<string, string>;
     dropValues?: string[];
     overrideValues?: string[];
+    stateMeta?: StateMeta;
 }
 interface TransitionOutcome extends NamedValueMutation {
     readonly kind: "transition";
@@ -1065,6 +1080,7 @@ declare class Queue {
         retentionTtlMs?: number;
         values?: Record<string, unknown>;
         valueRefs?: Record<string, string>;
+        stateMeta?: StateMeta;
         returnRecord?: boolean;
     }): Promise<FlowRecord | Buffer | unknown>;
     enqueueMany(items: CreateItem[], options?: {
@@ -1077,6 +1093,7 @@ declare class Queue {
         retentionTtlMs?: number;
         values?: Record<string, unknown>;
         valueRefs?: Record<string, string>;
+        stateMeta?: StateMeta;
     }): Promise<unknown[] | unknown>;
     worker(options?: WorkerConfig): QueueWorker;
 }
@@ -1167,6 +1184,7 @@ declare class Workflow {
         retentionTtlMs?: number;
         values?: Record<string, unknown>;
         valueRefs?: Record<string, string>;
+        stateMeta?: StateMeta;
         returnRecord?: boolean;
     }): Promise<FlowRecord | Buffer | unknown>;
     startMany(items: {
@@ -1175,6 +1193,7 @@ declare class Workflow {
         partitionKey?: string;
         values?: Record<string, unknown>;
         valueRefs?: Record<string, string>;
+        stateMeta?: StateMeta;
     }[], options?: {
         state?: string;
         partitionKey?: string;
@@ -1186,6 +1205,7 @@ declare class Workflow {
         retentionTtlMs?: number;
         values?: Record<string, unknown>;
         valueRefs?: Record<string, string>;
+        stateMeta?: StateMeta;
     }): Promise<unknown[] | unknown>;
     signal(id: string, options: Parameters<FerricStoreClient["signal"]>[1]): Promise<unknown>;
     get(id: string, options?: Parameters<FerricStoreClient["get"]>[1]): Promise<FlowRecord | undefined>;
@@ -1211,6 +1231,8 @@ declare class WorkflowContext {
     get partitionKey(): string | undefined;
     get payload(): unknown;
     get values(): Record<string, unknown>;
+    get stateMeta(): Record<string, unknown>;
+    get indexedStateMeta(): string | undefined;
     get valueRefs(): Record<string, unknown>;
     get leaseToken(): Buffer;
     get fencingToken(): number;
@@ -1267,4 +1289,4 @@ declare class WorkflowWorker {
     private applyHandlerError;
 }
 
-export { type AutoBatchOptions, type BackoffKind, type BackpressurePolicy, BitmapStore, BloomFilterStore, type CancelOptions, type ChildSpec, type ClaimDueOptions, type ClaimedItem, type Codec, type Command, type CommandArgument, type CommandExecutor, type CompleteOptions, type CompleteOutcome, type CountMinMergeOptions, CountMinSketchStore, type CreateItem, type CreateManyOptions, type CreateOptions, CuckooFilterStore, type ExceptionPolicy, type ExecutePipelineOptions, type FailOptions, type FailOutcome, type FencedItem, FerricStoreClient, type FerricStoreClientOptions, FerricStoreError, type FetchOrComputeResult, FlowAlreadyExistsError, FlowNotFoundError, type FlowRecord, FlowWrongStateError, type GeoAddOptions, type GeoMember, GeoStore, type GetExOptions, HashStore, HyperLogLogStore, InvalidCommandError, JsonCodec, type JsonSetOptions, JsonStore, type KeyInfo, KeyValueStore, ListStore, LockHeldError, LockNotOwnedError, type MutateOptions, type NamedValueMutation, NativeAdapter, type NativeAdapterOptions, type Outcome, OverloadedError, Queue, type QueueBatchHandler, QueueClient, type QueueHandler, type QueueOptions, QueueWorker, type QueueWorkerResult, type RangeLimit, type RateLimitResult, RawCodec, type ReadOptions, type ReclaimOptions, type RetryOptions, type RetryOutcome, type RetryPolicy, type ScanOptions, type SetOptions, SetStore, SortedSetStore, StaleLeaseError, type StateOptions, type StateRegistration, type StoreCommandClient, StreamStore, type TDigestCreateOptions, type TDigestMergeOptions, TDigestStore, type TopKReserveOptions, TopKStore, type TransitionOptions, type TransitionOutcome, type ValueConfig, type WorkerConfig, type WorkerProfile, Workflow, WorkflowClient, WorkflowContext, WorkflowFlowCommands, type WorkflowHandler, type WorkflowOptions, WorkflowWorker, type WorkflowWorkerResult, type XReadStream, type ZAddMember, type ZAddOptions, classifyServerError, complete, fail, mapException, retry, transition };
+export { type AutoBatchOptions, type BackoffKind, type BackpressurePolicy, BitmapStore, BloomFilterStore, type CancelOptions, type ChildSpec, type ClaimDueOptions, type ClaimedItem, type Codec, type Command, type CommandArgument, type CommandExecutor, type CompleteOptions, type CompleteOutcome, type CountMinMergeOptions, CountMinSketchStore, type CreateItem, type CreateManyOptions, type CreateOptions, CuckooFilterStore, type ExceptionPolicy, type ExecutePipelineOptions, type FailOptions, type FailOutcome, type FencedItem, FerricStoreClient, type FerricStoreClientOptions, FerricStoreError, type FetchOrComputeResult, FlowAlreadyExistsError, FlowNotFoundError, type FlowRecord, FlowWrongStateError, type GeoAddOptions, type GeoMember, GeoStore, type GetExOptions, HashStore, HyperLogLogStore, InvalidCommandError, JsonCodec, type JsonSetOptions, JsonStore, type KeyInfo, KeyValueStore, ListStore, LockHeldError, LockNotOwnedError, type MutateOptions, type NamedValueMutation, NativeAdapter, type NativeAdapterOptions, type Outcome, OverloadedError, Queue, type QueueBatchHandler, QueueClient, type QueueHandler, type QueueOptions, QueueWorker, type QueueWorkerResult, type RangeLimit, type RateLimitResult, RawCodec, type ReadOptions, type ReclaimOptions, type RetryOptions, type RetryOutcome, type RetryPolicy, type ScanOptions, type SetOptions, SetStore, SortedSetStore, StaleLeaseError, type StateMeta, type StateMetaValue, type StateOptions, type StateRegistration, type StoreCommandClient, StreamStore, type TDigestCreateOptions, type TDigestMergeOptions, TDigestStore, type TopKReserveOptions, TopKStore, type TransitionOptions, type TransitionOutcome, type ValueConfig, type WorkerConfig, type WorkerProfile, Workflow, WorkflowClient, WorkflowContext, WorkflowFlowCommands, type WorkflowHandler, type WorkflowOptions, WorkflowWorker, type WorkflowWorkerResult, type XReadStream, type ZAddMember, type ZAddOptions, classifyServerError, complete, fail, mapException, retry, transition };

package/dist/index.js

@@ -284,6 +284,9 @@ function buildProtocolCommand(args) {
   if (command === "DEL") {
     return { opcode: OPCODES.del, payload: { keys: commandArgs } };
   }
+  if (command.startsWith("FLOW.") && hasFlowCommandOnlyOption(commandArgs)) {
+    return commandExec(args);
+  }
   if (command === "FLOW.CREATE") {
     return flowCreatePayload(commandArgs) ?? commandExec(args);
   }
@@ -643,6 +646,15 @@ function writeOptionalBinary(out, offset, value) {
   }
   return writeBinary(out, offset, value);
 }
+function hasFlowCommandOnlyOption(args) {
+  return args.some((arg) => {
+    if (typeof arg !== "string" && !Buffer2.isBuffer(arg)) {
+      return false;
+    }
+    const token = asText(arg).toUpperCase();
+    return token === "STATE_META" || token === "INDEXED_STATE_META";
+  });
+}
 function flowCreatePayload(args) {
   if (args.length < 7) return void 0;
   const id = args[0];
@@ -2858,6 +2870,8 @@ function flowRecordFromResp(value, codec) {
     valueOmitted: toStringKeyMap(field(value, "value_omitted")),
     valueMissing: toStringKeyMap(field(value, "value_missing")),
     attributes: plainObjectField(value, "attributes"),
+    stateMeta: toStringKeyMap(field(value, "state_meta")),
+    indexedStateMeta: optionalString(field(value, "indexed_state_meta")),
     raw: value
   };
 }
@@ -3242,6 +3256,7 @@ var FerricStoreClient = class _FerricStoreClient {
     append(args, "PRIORITY", options.priority);
     appendBool(args, "IDEMPOTENT", options.idempotent);
     append(args, "RETENTION_TTL_MS", options.retentionTtlMs);
+    appendStateMeta(args, options.stateMeta);
     appendNamedValues(args, this.codec, options);
     const response = await this.executeProducerWrite(args);
     if (options.returnRecord === true) {
@@ -3301,6 +3316,7 @@ var FerricStoreClient = class _FerricStoreClient {
       }
     }
     const currentNowMs = options.nowMs ?? nowMs();
+    const stateMeta = sharedCreateManyStateMeta(items, options.stateMeta);
     const mixed = partitionKey == null && items.some((item) => item.partitionKey != null);
     const auto = partitionKey == null && !mixed;
     const wirePartition = mixed ? "MIXED" : auto ? "AUTO" : partitionKey;
@@ -3319,6 +3335,7 @@ var FerricStoreClient = class _FerricStoreClient {
     appendBool(args, "IDEMPOTENT", options.idempotent);
     appendBool(args, "INDEPENDENT", options.independent);
     append(args, "RETENTION_TTL_MS", options.retentionTtlMs);
+    appendStateMeta(args, stateMeta);
     const extendedItems = items.some((item) => item.values != null || item.valueRefs != null) || mixed && items.some((item) => item.partitionKey == null);
     if (extendedItems) {
       args.push("ITEMS_EXT", items.length);
@@ -3499,6 +3516,7 @@ var FerricStoreClient = class _FerricStoreClient {
     appendEncoded(args, "PAYLOAD", this.codec, options.payload);
     append(args, "RUN_AT", options.runAtMs ?? currentNowMs);
     append(args, "PRIORITY", options.priority);
+    appendStateMeta(args, options.stateMeta);
     appendNamedValues(args, this.codec, options);
     const response = await this.command(...args);
     if (options.returnRecord === true) {
@@ -3520,6 +3538,7 @@ var FerricStoreClient = class _FerricStoreClient {
     appendEncoded(args, "RESULT", this.codec, options.result);
     appendEncoded(args, "PAYLOAD", this.codec, options.payload);
     append(args, "TTL", options.ttlMs);
+    appendStateMeta(args, options.stateMeta);
     appendNamedValues(args, this.codec, options);
     const response = await this.command(...args);
     if (options.returnRecord === true) {
@@ -3540,6 +3559,7 @@ var FerricStoreClient = class _FerricStoreClient {
     if (options.returnOkOnSuccess === true) {
       args.push("RETURN", "OK_ON_SUCCESS");
     }
+    appendStateMeta(args, options.stateMeta);
     appendNamedValues(args, this.codec, options);
     appendClaimedItems(args, partitionKey, items, "FLOW.COMPLETE_MANY");
     return this.recordsOrResponse(await this.command(...args));
@@ -3566,6 +3586,7 @@ var FerricStoreClient = class _FerricStoreClient {
     append(args, "PRIORITY", options.priority);
     append(args, "NOW", options.nowMs ?? nowMs());
     appendBool(args, "INDEPENDENT", options.independent);
+    appendStateMeta(args, options.stateMeta);
     appendNamedValues(args, this.codec, options);
     appendFencedItems(args, partitionKey, options.items, "FLOW.TRANSITION_MANY", true);
     return this.recordsOrResponse(await this.command(...args));
@@ -3584,6 +3605,7 @@ var FerricStoreClient = class _FerricStoreClient {
     appendEncoded(args, "ERROR", this.codec, options.error);
     appendEncoded(args, "PAYLOAD", this.codec, options.payload);
     append(args, "RUN_AT", options.runAtMs);
+    appendStateMeta(args, options.stateMeta);
     appendNamedValues(args, this.codec, options);
     const response = await this.command(...args);
     if (options.returnRecord === true) {
@@ -3601,6 +3623,7 @@ var FerricStoreClient = class _FerricStoreClient {
     append(args, "RUN_AT", options.runAtMs);
     append(args, "NOW", options.nowMs ?? nowMs());
     appendBool(args, "INDEPENDENT", options.independent);
+    appendStateMeta(args, options.stateMeta);
     appendNamedValues(args, this.codec, options);
     appendClaimedItems(args, partitionKey, items, "FLOW.RETRY_MANY");
     return this.recordsOrResponse(await this.command(...args));
@@ -3619,6 +3642,7 @@ var FerricStoreClient = class _FerricStoreClient {
     appendEncoded(args, "ERROR", this.codec, options.error);
     appendEncoded(args, "PAYLOAD", this.codec, options.payload);
     append(args, "TTL", options.ttlMs);
+    appendStateMeta(args, options.stateMeta);
     appendNamedValues(args, this.codec, options);
     const response = await this.command(...args);
     if (options.returnRecord === true) {
@@ -3636,6 +3660,7 @@ var FerricStoreClient = class _FerricStoreClient {
     append(args, "TTL", options.ttlMs);
     append(args, "NOW", options.nowMs ?? nowMs());
     appendBool(args, "INDEPENDENT", options.independent);
+    appendStateMeta(args, options.stateMeta);
     appendNamedValues(args, this.codec, options);
     appendClaimedItems(args, partitionKey, items, "FLOW.FAIL_MANY");
     return this.recordsOrResponse(await this.command(...args));
@@ -3646,6 +3671,7 @@ var FerricStoreClient = class _FerricStoreClient {
     append(args, "PARTITION", options.partitionKey);
     appendEncoded(args, "REASON", this.codec, options.reason);
     append(args, "TTL", options.ttlMs);
+    appendStateMeta(args, options.stateMeta);
     const response = await this.command(...args);
     if (options.returnRecord === true) {
       return await this.recordOrGet(response, id, options.partitionKey);
@@ -3661,7 +3687,8 @@ var FerricStoreClient = class _FerricStoreClient {
     append(args, "TTL", options.ttlMs);
     append(args, "NOW", options.nowMs ?? nowMs());
     appendBool(args, "INDEPENDENT", options.independent);
-    appendFencedItems(args, partitionKey, items, "FLOW.CANCEL_MANY", true);
+    appendStateMeta(args, options.stateMeta);
+    appendFencedItems(args, partitionKey, items, "FLOW.CANCEL_MANY", false);
     return this.recordsOrResponse(await this.command(...args));
   }
   async rewind(id, options = {}) {
@@ -3762,6 +3789,7 @@ var FerricStoreClient = class _FerricStoreClient {
   }
   async installPolicy(type, options = {}) {
     const args = ["FLOW.POLICY.SET", type];
+    append(args, "INDEXED_STATE_META", options.indexedStateMeta);
     append(args, "STATE", options.state);
     if (options.retry != null) {
       appendRetryPolicy(args, options.retry);
@@ -4092,6 +4120,41 @@ function appendReadOptions(args, options) {
   appendBool(args, "INCLUDE_COLD", options.includeCold);
   appendBool(args, "CONSISTENT_PROJECTION", options.consistentProjection);
 }
+function appendStateMeta(args, stateMeta) {
+  for (const [name, value] of Object.entries(stateMeta ?? {})) {
+    args.push("STATE_META", name, value);
+  }
+}
+function sharedCreateManyStateMeta(items, stateMeta) {
+  const itemMetas = items.map((item) => item.stateMeta).filter((meta) => meta != null);
+  if (itemMetas.length === 0) {
+    return stateMeta;
+  }
+  const first = itemMetas[0];
+  if (first == null) {
+    return stateMeta;
+  }
+  if (itemMetas.some((meta) => !stateMetaEquals(meta, first))) {
+    throw new Error("createMany supports shared stateMeta only; use stateMeta or separate create calls for per-item stateMeta");
+  }
+  if (stateMeta != null && !stateMetaEquals(stateMeta, first)) {
+    throw new Error("createMany item stateMeta must match shared stateMeta when both are provided");
+  }
+  return first;
+}
+function stateMetaEquals(left, right) {
+  const leftEntries = Object.entries(left);
+  if (leftEntries.length !== Object.keys(right).length) {
+    return false;
+  }
+  return leftEntries.every(([key, value]) => stateMetaValueEquals(value, right[key]));
+}
+function stateMetaValueEquals(left, right) {
+  if (Buffer.isBuffer(left) || Buffer.isBuffer(right)) {
+    return Buffer.isBuffer(left) && Buffer.isBuffer(right) && left.equals(right);
+  }
+  return Object.is(left, right);
+}
 function appendNamedCounts(args, codec, values, valueRefs) {
   args.push(Object.keys(values).length);
   for (const [name, value] of Object.entries(values)) {
@@ -4516,6 +4579,7 @@ var QueueWorker = class {
         partitionKey: job.partitionKey,
         payload: outcome.payload,
         runAtMs: outcome.runAtMs,
+        stateMeta: outcome.stateMeta,
         valueRefs: outcome.valueRefs,
         values: outcome.values
       });
@@ -4528,6 +4592,7 @@ var QueueWorker = class {
         leaseToken: job.leaseToken,
         partitionKey: job.partitionKey,
         payload: outcome.payload,
+        stateMeta: outcome.stateMeta,
         ttlMs: outcome.ttlMs,
         valueRefs: outcome.valueRefs,
         values: outcome.values
@@ -4540,6 +4605,7 @@ var QueueWorker = class {
       partitionKey: job.partitionKey,
       payload: outcome.payload,
       result: outcome.result,
+      stateMeta: outcome.stateMeta,
       ttlMs: outcome.ttlMs,
       valueRefs: outcome.valueRefs,
       values: outcome.values
@@ -4559,7 +4625,7 @@ var QueueWorker = class {
   }
 };
 function isBatchableComplete(outcome) {
-  return outcome.kind === "complete" && outcome.payload === void 0 && outcome.result === void 0 && outcome.ttlMs === void 0 && outcome.values === void 0 && outcome.valueRefs === void 0 && outcome.dropValues === void 0 && outcome.overrideValues === void 0;
+  return outcome.kind === "complete" && outcome.payload === void 0 && outcome.result === void 0 && outcome.ttlMs === void 0 && outcome.values === void 0 && outcome.valueRefs === void 0 && outcome.dropValues === void 0 && outcome.overrideValues === void 0 && outcome.stateMeta === void 0;
 }
 function normalizeWorkerConfig(options) {
   if (options.profile !== "throughput") {
@@ -4686,6 +4752,12 @@ var WorkflowContext = class {
   get values() {
     return "values" in this.job && this.job.values != null ? this.job.values : {};
   }
+  get stateMeta() {
+    return "stateMeta" in this.job && this.job.stateMeta != null ? this.job.stateMeta : {};
+  }
+  get indexedStateMeta() {
+    return "indexedStateMeta" in this.job ? this.job.indexedStateMeta : void 0;
+  }
   get valueRefs() {
     return "valueRefs" in this.job && this.job.valueRefs != null ? this.job.valueRefs : {};
   }
@@ -4945,6 +5017,7 @@ async function applyTransition(client, ctx, outcome, returnRecord) {
     priority: outcome.priority,
     returnRecord,
     runAtMs: outcome.runAtMs,
+    stateMeta: outcome.stateMeta,
     toState: outcome.toState,
     valueRefs: outcome.valueRefs,
     values: outcome.values
@@ -4960,6 +5033,7 @@ async function applyComplete(client, ctx, outcome, returnRecord) {
     payload: outcome.payload,
     result: outcome.result,
     returnRecord,
+    stateMeta: outcome.stateMeta,
     ttlMs: outcome.ttlMs,
     valueRefs: outcome.valueRefs,
     values: outcome.values
@@ -4976,6 +5050,7 @@ async function applyRetry(client, ctx, outcome, returnRecord) {
     payload: outcome.payload,
     returnRecord,
     runAtMs: outcome.runAtMs,
+    stateMeta: outcome.stateMeta,
     valueRefs: outcome.valueRefs,
     values: outcome.values
   });
@@ -4990,6 +5065,7 @@ async function applyFail(client, ctx, outcome, returnRecord) {
     partitionKey: ctx.partitionKey,
     payload: outcome.payload,
     returnRecord,
+    stateMeta: outcome.stateMeta,
     ttlMs: outcome.ttlMs,
     valueRefs: outcome.valueRefs,
     values: outcome.values