@ferricstore/ferricstore 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (132) hide show
  1. package/LICENSE +200 -0
  2. package/README.md +250 -0
  3. package/dist/index.d.ts +1270 -0
  4. package/dist/index.js +5065 -0
  5. package/dist/index.js.map +1 -0
  6. package/docs/api/assets/hierarchy.js +1 -0
  7. package/docs/api/assets/highlight.css +99 -0
  8. package/docs/api/assets/icons.js +18 -0
  9. package/docs/api/assets/icons.svg +1 -0
  10. package/docs/api/assets/main.js +60 -0
  11. package/docs/api/assets/navigation.js +1 -0
  12. package/docs/api/assets/search.js +1 -0
  13. package/docs/api/assets/style.css +1633 -0
  14. package/docs/api/classes/BitmapStore.html +7 -0
  15. package/docs/api/classes/BloomFilterStore.html +9 -0
  16. package/docs/api/classes/CountMinSketchStore.html +8 -0
  17. package/docs/api/classes/CuckooFilterStore.html +10 -0
  18. package/docs/api/classes/FerricStoreClient.html +130 -0
  19. package/docs/api/classes/FerricStoreError.html +35 -0
  20. package/docs/api/classes/FlowAlreadyExistsError.html +35 -0
  21. package/docs/api/classes/FlowNotFoundError.html +35 -0
  22. package/docs/api/classes/FlowWrongStateError.html +35 -0
  23. package/docs/api/classes/GeoStore.html +8 -0
  24. package/docs/api/classes/HashStore.html +26 -0
  25. package/docs/api/classes/HyperLogLogStore.html +5 -0
  26. package/docs/api/classes/InvalidCommandError.html +35 -0
  27. package/docs/api/classes/JsonCodec.html +4 -0
  28. package/docs/api/classes/JsonStore.html +15 -0
  29. package/docs/api/classes/KeyValueStore.html +52 -0
  30. package/docs/api/classes/ListStore.html +22 -0
  31. package/docs/api/classes/LockHeldError.html +35 -0
  32. package/docs/api/classes/LockNotOwnedError.html +35 -0
  33. package/docs/api/classes/NativeAdapter.html +5 -0
  34. package/docs/api/classes/OverloadedError.html +37 -0
  35. package/docs/api/classes/Queue.html +9 -0
  36. package/docs/api/classes/QueueClient.html +4 -0
  37. package/docs/api/classes/QueueWorker.html +9 -0
  38. package/docs/api/classes/RawCodec.html +4 -0
  39. package/docs/api/classes/SetStore.html +19 -0
  40. package/docs/api/classes/SortedSetStore.html +19 -0
  41. package/docs/api/classes/StaleLeaseError.html +35 -0
  42. package/docs/api/classes/StreamStore.html +13 -0
  43. package/docs/api/classes/TDigestStore.html +16 -0
  44. package/docs/api/classes/TopKStore.html +8 -0
  45. package/docs/api/classes/Workflow.html +16 -0
  46. package/docs/api/classes/WorkflowClient.html +4 -0
  47. package/docs/api/classes/WorkflowContext.html +23 -0
  48. package/docs/api/classes/WorkflowFlowCommands.html +14 -0
  49. package/docs/api/classes/WorkflowWorker.html +6 -0
  50. package/docs/api/functions/classifyServerError.html +1 -0
  51. package/docs/api/functions/complete.html +1 -0
  52. package/docs/api/functions/fail.html +1 -0
  53. package/docs/api/functions/mapException.html +1 -0
  54. package/docs/api/functions/retry.html +1 -0
  55. package/docs/api/functions/transition.html +1 -0
  56. package/docs/api/hierarchy.html +1 -0
  57. package/docs/api/index.html +105 -0
  58. package/docs/api/interfaces/AutoBatchOptions.html +5 -0
  59. package/docs/api/interfaces/BackpressurePolicy.html +5 -0
  60. package/docs/api/interfaces/CancelOptions.html +8 -0
  61. package/docs/api/interfaces/ChildSpec.html +7 -0
  62. package/docs/api/interfaces/ClaimDueOptions.html +19 -0
  63. package/docs/api/interfaces/ClaimedItem.html +11 -0
  64. package/docs/api/interfaces/Codec.html +3 -0
  65. package/docs/api/interfaces/CommandExecutor.html +4 -0
  66. package/docs/api/interfaces/CompleteOptions.html +13 -0
  67. package/docs/api/interfaces/CompleteOutcome.html +9 -0
  68. package/docs/api/interfaces/CountMinMergeOptions.html +2 -0
  69. package/docs/api/interfaces/CreateItem.html +6 -0
  70. package/docs/api/interfaces/CreateManyOptions.html +15 -0
  71. package/docs/api/interfaces/CreateOptions.html +16 -0
  72. package/docs/api/interfaces/ExecutePipelineOptions.html +2 -0
  73. package/docs/api/interfaces/FailOptions.html +13 -0
  74. package/docs/api/interfaces/FailOutcome.html +9 -0
  75. package/docs/api/interfaces/FencedItem.html +5 -0
  76. package/docs/api/interfaces/FerricStoreClientOptions.html +4 -0
  77. package/docs/api/interfaces/FetchOrComputeResult.html +6 -0
  78. package/docs/api/interfaces/FlowRecord.html +20 -0
  79. package/docs/api/interfaces/GeoAddOptions.html +4 -0
  80. package/docs/api/interfaces/GeoMember.html +4 -0
  81. package/docs/api/interfaces/GetExOptions.html +6 -0
  82. package/docs/api/interfaces/JsonSetOptions.html +3 -0
  83. package/docs/api/interfaces/KeyInfo.html +7 -0
  84. package/docs/api/interfaces/MutateOptions.html +9 -0
  85. package/docs/api/interfaces/NamedValueMutation.html +5 -0
  86. package/docs/api/interfaces/NativeAdapterOptions.html +9 -0
  87. package/docs/api/interfaces/QueueOptions.html +4 -0
  88. package/docs/api/interfaces/QueueWorkerResult.html +5 -0
  89. package/docs/api/interfaces/RangeLimit.html +3 -0
  90. package/docs/api/interfaces/RateLimitResult.html +6 -0
  91. package/docs/api/interfaces/ReadOptions.html +10 -0
  92. package/docs/api/interfaces/ReclaimOptions.html +14 -0
  93. package/docs/api/interfaces/RetryOptions.html +13 -0
  94. package/docs/api/interfaces/RetryOutcome.html +9 -0
  95. package/docs/api/interfaces/RetryPolicy.html +7 -0
  96. package/docs/api/interfaces/ScanOptions.html +3 -0
  97. package/docs/api/interfaces/SetOptions.html +9 -0
  98. package/docs/api/interfaces/StateOptions.html +9 -0
  99. package/docs/api/interfaces/StateRegistration.html +11 -0
  100. package/docs/api/interfaces/StoreCommandClient.html +3 -0
  101. package/docs/api/interfaces/TDigestCreateOptions.html +2 -0
  102. package/docs/api/interfaces/TDigestMergeOptions.html +3 -0
  103. package/docs/api/interfaces/TopKReserveOptions.html +4 -0
  104. package/docs/api/interfaces/TransitionOptions.html +15 -0
  105. package/docs/api/interfaces/TransitionOutcome.html +10 -0
  106. package/docs/api/interfaces/ValueConfig.html +3 -0
  107. package/docs/api/interfaces/WorkerConfig.html +24 -0
  108. package/docs/api/interfaces/WorkflowOptions.html +5 -0
  109. package/docs/api/interfaces/WorkflowWorkerResult.html +5 -0
  110. package/docs/api/interfaces/XReadStream.html +3 -0
  111. package/docs/api/interfaces/ZAddMember.html +3 -0
  112. package/docs/api/interfaces/ZAddOptions.html +6 -0
  113. package/docs/api/media/design.md +59 -0
  114. package/docs/api/media/durable-queue.ts +24 -0
  115. package/docs/api/media/fanout.ts +38 -0
  116. package/docs/api/media/kv-store.ts +26 -0
  117. package/docs/api/media/order-workflow.ts +31 -0
  118. package/docs/api/media/signals.ts +47 -0
  119. package/docs/api/media/value-refs.ts +38 -0
  120. package/docs/api/modules.html +1 -0
  121. package/docs/api/types/BackoffKind.html +1 -0
  122. package/docs/api/types/Command.html +1 -0
  123. package/docs/api/types/CommandArgument.html +1 -0
  124. package/docs/api/types/ExceptionPolicy.html +1 -0
  125. package/docs/api/types/Outcome.html +1 -0
  126. package/docs/api/types/QueueBatchHandler.html +1 -0
  127. package/docs/api/types/QueueHandler.html +1 -0
  128. package/docs/api/types/WorkerProfile.html +1 -0
  129. package/docs/api/types/WorkflowHandler.html +1 -0
  130. package/docs/design.md +59 -0
  131. package/docs/python-parity.md +117 -0
  132. package/package.json +74 -0
package/docs/api/types/WorkflowHandler.html ADDED
@@ -0,0 +1 @@
1
+ <!DOCTYPE html><html class="default" lang="en" data-base="../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>WorkflowHandler | @ferricstore/ferricstore</title><meta name="description" content="Documentation for @ferricstore/ferricstore"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../assets/style.css"/><link rel="stylesheet" href="../assets/highlight.css"/><script defer src="../assets/main.js"></script><script async src="../assets/icons.js" id="tsd-icons-script"></script><script async src="../assets/search.js" id="tsd-search-script"></script><script async src="../assets/navigation.js" id="tsd-nav-script"></script><script async src="../assets/hierarchy.js" id="tsd-hierarchy-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../index.html" class="title">@ferricstore/ferricstore</a><div id="tsd-toolbar-links"></div><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-search"></use></svg></button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-menu"></use></svg></a></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="" aria-current="page">WorkflowHandler</a></li></ul><h1>Type Alias WorkflowHandler</h1></div><div class="tsd-signature"><span class="tsd-kind-type-alias">WorkflowHandler</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-symbol">(</span><br/>    <span class="tsd-kind-parameter">ctx</span><span class="tsd-signature-symbol">:</span> <a href="../classes/WorkflowContext.html" class="tsd-signature-type tsd-kind-class">WorkflowContext</a><span class="tsd-signature-symbol">,</span><br/><span class="tsd-signature-symbol">)</span> <span class="tsd-signature-symbol">=&gt;</span> <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><a href="Outcome.html" class="tsd-signature-type tsd-kind-type-alias">Outcome</a> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">void</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">&gt;</span> <span class="tsd-signature-symbol">|</span> <a href="Outcome.html" class="tsd-signature-type tsd-kind-type-alias">Outcome</a> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">void</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">unknown</span></div><div class="tsd-type-declaration"><h4>Type Declaration</h4><ul class="tsd-parameters"><li class="tsd-parameter-signature"><ul class="tsd-signatures"><li class="tsd-signature" id="__type"><span class="tsd-signature-symbol">(</span><br/>    <span class="tsd-kind-parameter">ctx</span><span class="tsd-signature-symbol">:</span> <a href="../classes/WorkflowContext.html" class="tsd-signature-type tsd-kind-class">WorkflowContext</a><span class="tsd-signature-symbol">,</span><br/><span class="tsd-signature-symbol">)</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><a href="Outcome.html" class="tsd-signature-type tsd-kind-type-alias">Outcome</a> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">void</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">&gt;</span> <span class="tsd-signature-symbol">|</span> <a href="Outcome.html" class="tsd-signature-type tsd-kind-type-alias">Outcome</a> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">void</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">unknown</span></li><li class="tsd-description"><div class="tsd-parameters"><h4 class="tsd-parameters-title">Parameters</h4><ul class="tsd-parameter-list"><li><span><span class="tsd-kind-parameter">ctx</span>: <a href="../classes/WorkflowContext.html" class="tsd-signature-type tsd-kind-class">WorkflowContext</a></span></li></ul></div><h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><a href="Outcome.html" class="tsd-signature-type tsd-kind-type-alias">Outcome</a> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">void</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">&gt;</span> <span class="tsd-signature-symbol">|</span> <a href="Outcome.html" class="tsd-signature-type tsd-kind-type-alias">Outcome</a> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">void</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">unknown</span></h4></li></ul></li></ul></div><aside class="tsd-sources"><ul><li>Defined in <a href="https://github.com/ferricstore/ferricstore-typescript/blob/main/src/workflow.ts#L17">src/workflow.ts:17</a></li></ul></aside></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../assets/icons.svg#icon-chevronDown"></use></svg><h3>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div></div><div class="site-menu"><nav class="tsd-navigation"><a href="../modules.html">@ferricstore/ferricstore</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer></footer><div class="overlay"></div></body></html>
package/docs/design.md ADDED
@@ -0,0 +1,59 @@
1
+ # SDK Design
2
+
3
+ FerricFlow is centered on durable state-machine records.
4
+
5
+ The TypeScript SDK keeps that visible. A workflow has a `type`, `id`, current `state`, payload/value refs, lease/fencing data, retry metadata, history, and terminal status. Workers claim a state, execute normal TypeScript code, then explicitly write one of four outcomes:
6
+
7
+ ```ts
8
+ return transition("charged");
9
+ return complete({ result: { ok: true } });
10
+ return retry({ error: "rate limited" });
11
+ return fail({ error: "bad input" });
12
+ ```
13
+
14
+ ## What The SDK Does
15
+
16
+ - Builds typed `FLOW.*` commands over FerricStore's native protocol.
17
+ - Uses the SDK native adapter with Buffer-safe binary values.
18
+ - Provides a low-level `FerricStoreClient` for direct command control.
19
+ - Provides `QueueClient` for durable queue-shaped workloads.
20
+ - Provides `WorkflowClient` for explicit state-machine workflows.
21
+ - Keeps payload serialization in an SDK codec, not in FerricStore.
22
+
23
+ ## What The SDK Does Not Do
24
+
25
+ - It does not replay workflow code.
26
+ - It does not require decorators.
27
+ - It does not instrument user functions.
28
+ - It does not require a TypeScript service to own every workflow state.
29
+
30
+ This matters because a Flow can move between services. For example, one TypeScript worker can handle `created`, a Go service can handle `charged`, and a Python service can handle `receipt`. FerricFlow stores the durable state between them.
31
+
32
+ ## Relation To Temporal And DBOS Examples
33
+
34
+ Temporal’s TypeScript SDK separates clients, workers, workflow code, and activities. DBOS TypeScript examples register workflows and steps. Those are useful API references for how TypeScript users expect to organize workflow code.
35
+
36
+ FerricFlow’s runtime model is different. The important unit is not a replayed TypeScript function. The important unit is the Flow record and its explicit state transitions.
37
+
38
+ That is why this SDK uses ordinary handler registration:
39
+
40
+ ```ts
41
+ order.state("created", async (ctx) => {
42
+ await chargeCard(ctx.payload);
43
+ return transition("charged");
44
+ });
45
+ ```
46
+
47
+ The handler is just code. The durable result is the `FLOW.TRANSITION` command.
48
+
49
+ ## Throughput-Oriented Choices
50
+
51
+ The SDK keeps the hot path thin:
52
+
53
+ - no local replay sandbox;
54
+ - no generated wrappers around handler code;
55
+ - Native commands use FerricStore's multiplexed `ferric://` protocol;
56
+ - batch APIs such as `enqueueMany`, `completeMany`, `retryMany`, and `failMany` are exposed directly;
57
+ - value refs let workers hydrate only the named values they need.
58
+
59
+ The storage throughput story belongs mostly to FerricStore itself: FerricStore owns the storage path and FerricFlow state is stored inside FerricStore, not through an external workflow database client from this SDK.
package/docs/python-parity.md ADDED
@@ -0,0 +1,117 @@
1
+ # Python SDK Parity
2
+
3
+ This checklist tracks TypeScript SDK parity against `ferricstore-python`.
4
+
5
+ Legend:
6
+
7
+ - Done: typed TS API exists.
8
+ - Partial: usable through TS, but Python has a richer helper or worker feature.
9
+ - Raw: use `client.command(...)`.
10
+
11
+ ## Core Client
12
+
13
+ | Python SDK Surface | TypeScript Status | Notes |
14
+ | --- | --- | --- |
15
+ | `FerricStoreClient.from_url` | Done | `FerricStoreClient.fromUrl` over FerricStore native protocol. |
16
+ | `command` | Done | Raw native command escape hatch. |
17
+ | `pipeline` | Done | Takes command arrays. |
18
+ | `close` | Done | Closes owned adapter. |
19
+ | `RawCodec` / `JsonCodec` / custom codec | Done | `Codec` interface. |
20
+ | Typed server error mapping | Done | Common FerricStore errors mapped. |
21
+ | Backpressure on producer writes | Done | Retry on overload for create/enqueue paths. |
22
+ | `autobatch` | Done | `autoBatch` client option groups eligible concurrent commands into native `PIPELINE` frames. |
23
+
24
+ ## Server Commands
25
+
26
+ | Command Family | TypeScript Status | Notes |
27
+ | --- | --- | --- |
28
+ | `PING`, `ECHO`, `INFO` | Done | `ping`, `echo`, `serverInfo`. `FerricStoreClient.info(type)` remains the `FLOW.INFO` helper. |
29
+ | `CONFIG` | Done | `configGet`, `configSet`, `configGetLocal`, `configResetStat`, `configRewrite`. |
30
+ | `SLOWLOG`, `COMMAND`, `CLIENT` introspection | Done | Thin typed helpers for supported subcommands. |
31
+ | `PUBLISH`, `PUBSUB` introspection | Done | Subscription-mode commands stay raw because they change connection behavior. |
32
+ | `ACL`, `AUTH` | Done | Thin typed helpers. |
33
+ | `MULTI`, `EXEC`, `WATCH`, subscriber mode | Raw | Use `client.command(...)`; these are connection-state flows. |
34
+
35
+ ## FerricStore Native Commands
36
+
37
+ | Command Family | TypeScript Status |
38
+ | --- | --- |
39
+ | `CAS` | Done |
40
+ | `LOCK`, `UNLOCK`, `EXTEND` | Done |
41
+ | `RATELIMIT.ADD` | Done |
42
+ | `FETCH_OR_COMPUTE*` | Done |
43
+ | `FERRICSTORE.KEY_INFO` | Done |
44
+ | `FERRICSTORE.CONFIG`, `HOTNESS`, `METRICS`, `BLOBGC`, `DOCTOR` | Done |
45
+ | `CLUSTER.HEALTH`, `STATS`, `KEYSLOT`, `SLOTS`, `STATUS`, `ROLE`, `JOIN`, `LEAVE`, `FAILOVER`, `PROMOTE`, `DEMOTE` | Done |
46
+
47
+ ## FerricFlow Commands
48
+
49
+ | Command | TypeScript Status |
50
+ | --- | --- |
51
+ | `FLOW.CREATE` | Done |
52
+ | `FLOW.CREATE_MANY` | Done |
53
+ | `FLOW.VALUE.PUT` | Done |
54
+ | `FLOW.VALUE.MGET` | Done |
55
+ | `FLOW.SIGNAL` | Done |
56
+ | `FLOW.CLAIM_DUE` | Done |
57
+ | `FLOW.RECLAIM` | Done |
58
+ | `FLOW.EXTEND_LEASE` | Done |
59
+ | `FLOW.TRANSITION`, `FLOW.TRANSITION_MANY` | Done |
60
+ | `FLOW.COMPLETE`, `FLOW.COMPLETE_MANY` | Done |
61
+ | `FLOW.RETRY`, `FLOW.RETRY_MANY` | Done |
62
+ | `FLOW.FAIL`, `FLOW.FAIL_MANY` | Done |
63
+ | `FLOW.CANCEL`, `FLOW.CANCEL_MANY` | Done |
64
+ | `FLOW.REWIND` | Done |
65
+ | `FLOW.GET`, `FLOW.LIST`, `FLOW.TERMINALS`, `FLOW.FAILURES`, `FLOW.STUCK` | Done |
66
+ | `FLOW.BY_PARENT`, `FLOW.BY_ROOT`, `FLOW.BY_CORRELATION` | Done |
67
+ | `FLOW.INFO`, `FLOW.HISTORY` | Done |
68
+ | `FLOW.SPAWN_CHILDREN` | Done |
69
+ | `FLOW.POLICY.SET`, `FLOW.POLICY.GET` | Done |
70
+ | `FLOW.RETENTION_CLEANUP` | Done |
71
+
72
+ ## Queue API
73
+
74
+ | Python SDK Surface | TypeScript Status | Notes |
75
+ | --- | --- | --- |
76
+ | `QueueClient.queue` | Done | `new QueueClient(flow).queue(...)`. |
77
+ | `Queue.enqueue`, `enqueue_many` | Done | `enqueue`, `enqueueMany`. |
78
+ | Worker `run_once`, `run` | Done | Async TS worker loop. |
79
+ | Exception policy retry/fail/raise | Done | Covered by tests. |
80
+ | Batch handler, start/stop/join/stats | Partial | Python worker has a richer threaded lifecycle and batch scheduler. TS has async `run`/`runOnce`. |
81
+ | Advanced partition scanning/cooldowns | Partial | Python has more throughput scheduler controls. |
82
+
83
+ ## Workflow API
84
+
85
+ | Python SDK Surface | TypeScript Status | Notes |
86
+ | --- | --- | --- |
87
+ | `WorkflowClient.workflow` | Done | Explicit state-machine workflow builder. |
88
+ | `Workflow.start`, `start_many` | Done | `start`, `startMany`. |
89
+ | `state(...)` registration | Done | TS uses `workflow.state(name, handler, opts)`. |
90
+ | Outcomes `transition`, `complete`, `retry`, `fail` | Done | Same conceptual model. |
91
+ | `WorkflowContext.flow.*` helpers | Done | Current-flow helper surface exists. |
92
+ | Lazy value refs | Done | `ctx.value`, `ctx.valueMany`. |
93
+ | Spawn children / fanout | Done | `ctx.flow.spawnChildren`. |
94
+ | Class/decorator workflow style | Partial | Python has class/decorator ergonomics; TS currently uses registration. |
95
+ | Batch apply optimization | Partial | Python has richer uniform batch apply paths. TS has low-level many commands. |
96
+ | Worker lifecycle start/stop/join/stats | Partial | TS worker is async-loop based. |
97
+
98
+ ## KV/Data-Structure Commands
99
+
100
+ | Redis-Compatible Family | TypeScript Status |
101
+ | --- | --- |
102
+ | String/key/TTL/object commands | Done through `client.kv`. |
103
+ | Hash commands including hash field TTL | Done through `client.hash`. |
104
+ | List commands including blocking variants | Done through `client.lists`. |
105
+ | Set commands | Done through `client.sets`. |
106
+ | Sorted set commands | Done through `client.zset`; commands not supported by FerricStore are intentionally absent. |
107
+ | Stream commands and consumer groups | Done through `client.stream` for the supported FerricStore stream surface. |
108
+ | Bitmap, HyperLogLog, Geo | Done through `client.bitmap`, `client.hyperloglog`, `client.geo`. |
109
+ | Bloom, Cuckoo, Count-Min, TopK, TDigest | Done through `client.bloom`, `client.cuckoo`, `client.cms`, `client.topk`, `client.tdigest`. |
110
+ | JSON | Done through `client.json`. |
111
+
112
+ ## Main Remaining Gaps
113
+
114
+ - Live integration parity against a running FerricStore server.
115
+ - Advanced worker scheduling parity with Python.
116
+ - Class/decorator workflow ergonomics.
117
+ - Full generated command matrix tests for every Redis-compatible helper and edge option.
package/package.json ADDED
@@ -0,0 +1,74 @@
1
+ {
2
+ "name": "@ferricstore/ferricstore",
3
+ "version": "0.1.0",
4
+ "description": "TypeScript SDK for FerricStore and FerricFlow",
5
+ "type": "module",
6
+ "license": "Apache-2.0",
7
+ "publishConfig": {
8
+ "access": "public",
9
+ "provenance": true
10
+ },
11
+ "author": "FerricStore",
12
+ "homepage": "https://github.com/ferricstore/ferricstore-typescript#readme",
13
+ "repository": {
14
+ "type": "git",
15
+ "url": "git+https://github.com/ferricstore/ferricstore-typescript.git"
16
+ },
17
+ "bugs": {
18
+ "url": "https://github.com/ferricstore/ferricstore-typescript/issues"
19
+ },
20
+ "keywords": [
21
+ "durable-execution",
22
+ "ferricflow",
23
+ "ferricstore",
24
+ "queue",
25
+ "redis",
26
+ "state-machine",
27
+ "workflow"
28
+ ],
29
+ "engines": {
30
+ "node": ">=24"
31
+ },
32
+ "packageManager": "npm@11.6.2",
33
+ "sideEffects": false,
34
+ "exports": {
35
+ ".": {
36
+ "types": "./dist/index.d.ts",
37
+ "import": "./dist/index.js"
38
+ },
39
+ "./package.json": "./package.json"
40
+ },
41
+ "files": [
42
+ "dist",
43
+ "docs",
44
+ "README.md",
45
+ "LICENSE"
46
+ ],
47
+ "scripts": {
48
+ "build": "tsup src/index.ts --format esm --dts --sourcemap --clean",
49
+ "check": "npm run typecheck && npm run lint && npm run test && npm run build && npm run docs:check",
50
+ "docs": "typedoc",
51
+ "docs:check": "typedoc --logLevel Warn",
52
+ "integration:down": "docker compose down -v",
53
+ "integration:up": "docker compose up -d ferricstore && node scripts/wait-for-ferricstore.mjs",
54
+ "lint": "eslint .",
55
+ "pack:dry-run": "npm pack --dry-run",
56
+ "test": "vitest run tests/*.test.ts",
57
+ "test:integration": "vitest run tests/integration",
58
+ "typecheck": "tsc --noEmit",
59
+ "bench:kv": "node benchmarks/kv-benchmark.mjs",
60
+ "bench:dbos": "node benchmarks/dbos-style-benchmark.mjs"
61
+ },
62
+ "devDependencies": {
63
+ "@emnapi/core": "^1.11.1",
64
+ "@emnapi/runtime": "^1.11.1",
65
+ "@eslint/js": "^10.0.1",
66
+ "@types/node": "^25.9.2",
67
+ "eslint": "^10.4.1",
68
+ "tsup": "^8.5.1",
69
+ "typedoc": "^0.28.19",
70
+ "typescript": "^6.0.3",
71
+ "typescript-eslint": "^8.60.1",
72
+ "vitest": "^4.1.8"
73
+ }
74
+ }