@executablemd/durable-streams 0.6.0 → 0.7.0

package/esm/guard.js

@@ -0,0 +1,41 @@
+/**
+ * guardDurableStream — a host-side pre-persistence boundary.
+ *
+ * A gate runs once per live append, before the event reaches the backend.
+ * It receives a copy and returns nothing, so it can inspect or reject but
+ * never rewrite. When the gate completes, the original event is handed to
+ * the underlying stream exactly once. When the gate fails or is cancelled,
+ * the backend is never invoked and the failure propagates to the durable
+ * effect that produced the event.
+ *
+ * The backend append is a statement after the gate rather than a
+ * continuation passed to it. A gate therefore has nothing it can invoke
+ * twice, which preserves the protocol invariant that one durable yield
+ * produces at most one journal event.
+ */
+/**
+ * Wrap a durable stream so every live append passes through `gate` first.
+ *
+ * `readAll()` delegates straight to the underlying stream, so replaying a
+ * journal restores existing entries without gating them.
+ *
+ * Wrap the stream before execution begins to cover the complete live
+ * journal — root component imports, yields, child closes, and the root
+ * close.
+ *
+ * Rejection is per event. The rejected event never reaches the backend, but
+ * the resulting failure may lead the workflow to append a later `Close`
+ * event with an `err` result, and that close crosses the gate on its own.
+ */
+export function guardDurableStream(stream, gate) {
+    return {
+        readAll: () => stream.readAll(),
+        *append(event) {
+            // The gate sees a copy so "inspect or reject" is enforced rather than
+            // merely documented: the backend always receives the event the effect
+            // produced, whatever the gate did to the one it was handed.
+            yield* gate(structuredClone(event));
+            yield* stream.append(event);
+        },
+    };
+}

package/esm/mod.js

@@ -8,6 +8,8 @@
 // ReplayIndex
 export { ReplayIndex } from "./replay-index.js";
 export { InMemoryStream } from "./stream.js";
+// Pre-persistence gate — runs before an event reaches its backend
+export { guardDurableStream } from "./guard.js";
 // HTTP-backed stream adapter
 export { useHttpDurableStream } from "./http-stream.js";
 // Errors
@@ -19,7 +21,7 @@ export { ReplayGuard } from "./replay-guard.js";
 // Context
 export { DurableCtx } from "./context.js";
 // Serialization utilities
-export { deserializeError, effectionToProtocol, protocolToEffection, serializeError, } from "./serialize.js";
+export { deserializeError, effectionToProtocol, protocolToEffection, serializeDurableEvent, serializeError, } from "./serialize.js";
 // Core effect factories
 export { createDurableEffect, createDurableOperation } from "./effect.js";
 // Workflow-enabled effects

package/esm/serialize.js

@@ -5,7 +5,36 @@
  * - Protocol Result ({ status: "ok" | "err" | "cancelled" })
  * - Effection Result ({ ok: true, value } | { ok: false, error })
  * - Error ↔ SerializedError
+ *
+ * `serializeDurableEvent` is the shared NDJSON representation: file
+ * persistence writes it, and gates that inspect the persisted form derive
+ * it from the same function.
  */
+/**
+ * Render one durable event as its NDJSON record, terminating newline
+ * included.
+ *
+ * This is ordinary `JSON.stringify(event) + "\n"`. Field order follows the
+ * event object's own insertion order; nothing is sorted, normalized, or
+ * otherwise canonicalized. The value of sharing it is that file persistence
+ * and anything inspecting the persisted form cannot drift apart, not that
+ * the output is a canonical form of the event.
+ *
+ * Serialization fails when `JSON.stringify` throws — a circular structure or
+ * a `BigInt` — or when it does not return a string. Values that
+ * `JSON.stringify` silently coerces or drops are left alone: `undefined`,
+ * function and symbol members are omitted, non-finite numbers become `null`,
+ * and non-plain objects serialize through `toJSON`.
+ */
+export function serializeDurableEvent(event) {
+    const record = JSON.stringify(event);
+    // JSON.stringify returns undefined rather than throwing when the value
+    // itself has no JSON representation.
+    if (typeof record !== "string") {
+        throw new TypeError("serializeDurableEvent: event has no JSON representation");
+    }
+    return `${record}\n`;
+}
 /** Serialize an Error to a JSON-safe SerializedError. */
 export function serializeError(error) {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@executablemd/durable-streams",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Durable, replayable event streams for executable.md.",
   "homepage": "https://executable.md",
   "repository": {

package/types/guard.d.ts

@@ -0,0 +1,42 @@
+/**
+ * guardDurableStream — a host-side pre-persistence boundary.
+ *
+ * A gate runs once per live append, before the event reaches the backend.
+ * It receives a copy and returns nothing, so it can inspect or reject but
+ * never rewrite. When the gate completes, the original event is handed to
+ * the underlying stream exactly once. When the gate fails or is cancelled,
+ * the backend is never invoked and the failure propagates to the durable
+ * effect that produced the event.
+ *
+ * The backend append is a statement after the gate rather than a
+ * continuation passed to it. A gate therefore has nothing it can invoke
+ * twice, which preserves the protocol invariant that one durable yield
+ * produces at most one journal event.
+ */
+import type { Operation } from "effection";
+import type { DurableStream } from "./stream.js";
+import type { DurableEvent } from "./types.js";
+/**
+ * A check that runs before a durable event is persisted.
+ *
+ * Completing successfully admits the event. Failing or being cancelled
+ * rejects it. A gate inspects or rejects, and nothing else: it returns no
+ * value, and the event it receives is a copy, so writing to that copy
+ * changes nothing about what gets journaled.
+ */
+export type DurableEventGate = (event: DurableEvent) => Operation<void>;
+/**
+ * Wrap a durable stream so every live append passes through `gate` first.
+ *
+ * `readAll()` delegates straight to the underlying stream, so replaying a
+ * journal restores existing entries without gating them.
+ *
+ * Wrap the stream before execution begins to cover the complete live
+ * journal — root component imports, yields, child closes, and the root
+ * close.
+ *
+ * Rejection is per event. The rejected event never reaches the backend, but
+ * the resulting failure may lead the workflow to append a later `Close`
+ * event with an `err` result, and that close crosses the gate on its own.
+ */
+export declare function guardDurableStream(stream: DurableStream, gate: DurableEventGate): DurableStream;

package/types/mod.d.ts

@@ -10,6 +10,8 @@ export { ReplayIndex } from "./replay-index.js";
 export type { YieldEntry } from "./replay-index.js";
 export type { DurableStream } from "./stream.js";
 export { InMemoryStream } from "./stream.js";
+export { guardDurableStream } from "./guard.js";
+export type { DurableEventGate } from "./guard.js";
 export { useHttpDurableStream } from "./http-stream.js";
 export type { HttpDurableStreamHandle, HttpDurableStreamOptions } from "./http-stream.js";
 export { ContinuePastCloseDivergenceError, DivergenceError, EarlyReturnDivergenceError, StaleInputError, } from "./errors.js";
@@ -19,7 +21,7 @@ export { ReplayGuard } from "./replay-guard.js";
 export type { ReplayOutcome } from "./replay-guard.js";
 export { DurableCtx } from "./context.js";
 export type { DurableContext } from "./context.js";
-export { deserializeError, effectionToProtocol, protocolToEffection, serializeError, } from "./serialize.js";
+export { deserializeError, effectionToProtocol, protocolToEffection, serializeDurableEvent, serializeError, } from "./serialize.js";
 export { createDurableEffect, createDurableOperation } from "./effect.js";
 export type { Executor } from "./effect.js";
 export { durableAction, durableCall, durableSleep, versionCheck } from "./operations.js";

package/types/serialize.d.ts

@@ -5,8 +5,29 @@
  * - Protocol Result ({ status: "ok" | "err" | "cancelled" })
  * - Effection Result ({ ok: true, value } | { ok: false, error })
  * - Error ↔ SerializedError
+ *
+ * `serializeDurableEvent` is the shared NDJSON representation: file
+ * persistence writes it, and gates that inspect the persisted form derive
+ * it from the same function.
+ */
+import type { DurableEvent, EffectionResult, Result, SerializedError } from "./types.js";
+/**
+ * Render one durable event as its NDJSON record, terminating newline
+ * included.
+ *
+ * This is ordinary `JSON.stringify(event) + "\n"`. Field order follows the
+ * event object's own insertion order; nothing is sorted, normalized, or
+ * otherwise canonicalized. The value of sharing it is that file persistence
+ * and anything inspecting the persisted form cannot drift apart, not that
+ * the output is a canonical form of the event.
+ *
+ * Serialization fails when `JSON.stringify` throws — a circular structure or
+ * a `BigInt` — or when it does not return a string. Values that
+ * `JSON.stringify` silently coerces or drops are left alone: `undefined`,
+ * function and symbol members are omitted, non-finite numbers become `null`,
+ * and non-plain objects serialize through `toJSON`.
  */
-import type { EffectionResult, Result, SerializedError } from "./types.js";
+export declare function serializeDurableEvent(event: DurableEvent): string;
 /** Serialize an Error to a JSON-safe SerializedError. */
 export declare function serializeError(error: Error): SerializedError;
 /** Deserialize a SerializedError back to an Error. */