@graphrefly/graphrefly 0.46.0 → 0.47.1

package/dist/utils/messaging/index.d.cts

@@ -1,4 +1,5 @@
 import * as _graphrefly_pure_ts_extra from '@graphrefly/pure-ts/extra';
+import { ReactiveLogBundle } from '@graphrefly/pure-ts/extra';
 import { BaseAuditRecord } from '../../base/mutation/index.cjs';
 import { Node } from '@graphrefly/pure-ts/core';
 import { Graph, GraphOptions } from '@graphrefly/pure-ts/graph';
@@ -329,7 +330,7 @@ declare class TopicGraph<T> extends Graph {
     attachEventStorage(tiers: readonly _graphrefly_pure_ts_extra.AppendLogStorageTier<T>[]): () => void;
     retained(): readonly T[];
     /** Internal log bundle — used by TopicBridgeGraph for `attach`. */
-    get _logBundle(): _graphrefly_pure_ts_extra.ReactiveLogBundle<T>;
+    get _logBundle(): ReactiveLogBundle<T>;
 }
 type SubscriptionOptions = {
     graph?: GraphOptions;
@@ -558,5 +559,117 @@ declare function subscription<T>(name: string, topicGraph: TopicGraph<T>, opts?:
  * downstream subscription on the bridge's `output` node instead.
  */
 declare function topicBridge<TIn, TOut = TIn>(name: string, sourceTopic: TopicGraph<TIn>, targetTopic: TopicGraph<TOut>, opts?: TopicBridgeOptions<TIn, TOut>): TopicBridgeGraph<TIn, TOut>;
+type ProjectorPoisonPolicy = "halt" | "deadLetter";
+/** A poison entry routed to {@link LogProjectorGraph.deadLetter}. */
+type DeadLetterEntry<T> = {
+    readonly item: T;
+    /** `Error.message` (or `String(thrown)`) from the failing `sink`. */
+    readonly error: string;
+    /** Absolute 0-based log position of the poisoned item. */
+    readonly cursorPos: number;
+};
+type LogProjectorOptions<T> = {
+    graph?: GraphOptions;
+    /**
+     * Per-item side-effecting projection.
+     *
+     * **Transient-vs-poison contract (read this).** The projector cannot tell
+     * "this will project later" from "this will never project" — only the sink
+     * knows. So the contract is:
+     * - **Return normally** (sync return, or a resolved Promise) → the item is
+     *   *handled*; the cursor advances. Use this for the success path AND for
+     *   any transient/skip condition the sink wants to no-op (e.g. an optional
+     *   native feature not yet available — return without throwing; the entry
+     *   is simply considered done for this projector).
+     * - **Throw / reject** → the item is *poison*; the {@link onPoison} policy
+     *   applies. Do NOT throw for transient conditions or the item is
+     *   dead-lettered (or halts the stream).
+     */
+    readonly sink: (item: T) => void | Promise<void>;
+    /**
+     * Behaviour when `sink` throws/rejects on an item (poison):
+     * - `"halt"` (default) — stop projecting at the poison item; the cursor
+     *   does NOT advance past it (head-of-line stop). `position` stalls — that
+     *   is the observable signal. No retry/backoff is built in.
+     * - `"deadLetter"` — publish `{ item, error, cursorPos }` to the
+     *   {@link LogProjectorGraph.deadLetter} topic and advance past it, so
+     *   newer entries still project.
+     */
+    readonly onPoison?: ProjectorPoisonPolicy;
+    /**
+     * Initial cursor position. `"retained"` (default) projects all history;
+     * `"now"` skips existing entries (project only future appends); a number
+     * starts at that absolute index.
+     */
+    readonly from?: "retained" | "now" | number;
+    /** Retained window for the `deadLetter` topic. Default 1024. */
+    readonly deadLetterRetainedLimit?: number;
+};
+/**
+ * Cursor-driven projector over a {@link TopicGraph} or {@link ReactiveLogBundle}.
+ *
+ * Topology (mounted on the returned graph):
+ *  - `subscription` (TopicGraph source only) — the hardened
+ *    {@link SubscriptionGraph} cursor; or a local `cursor` state + the
+ *    bundle's `fromCursor` view (ReactiveLogBundle source).
+ *  - `drain` — an `effect` that, on every not-yet-projected wave, schedules a
+ *    serialized async pass that calls `sink` per item (mirrors the
+ *    `SubscriptionGraph.ackPump` / `TopicBridge.ackPump` effect precedent +
+ *    memo:Re's `inFlight` chain — one wave processed at a time).
+ *  - `deadLetter` — a real {@link TopicGraph} (NOT a callback): poison entries
+ *    are observable in `describe()` and subscribable, instead of memo:Re's
+ *    silent `break`.
+ *
+ * **No imperative reads.** Observe `position` (cursor) / subscribe to
+ * `deadLetter`. `idle()` is a test-only await convenience.
+ *
+ * @category patterns
+ */
+declare class LogProjectorGraph<T> extends Graph {
+    /** Reactive count of fully-projected entries (the cursor; read-only). */
+    readonly position: Node<number>;
+    /**
+     * Poison entries (populated when `onPoison: "deadLetter"`). A real topic —
+     * subscribable + visible in `describe()`.
+     */
+    readonly deadLetter: TopicGraph<DeadLetterEntry<T>>;
+    private _inFlight;
+    constructor(name: string, source: TopicGraph<T> | ReactiveLogBundle<T>, opts: LogProjectorOptions<T>);
+    /**
+     * Await any in-flight drain pass. **Test convenience only** — the canonical
+     * reactive observable is {@link LogProjectorGraph.position}.
+     */
+    idle(): Promise<void>;
+}
+/**
+ * Creates a cursor-driven log/topic projector with a typed poison-failure
+ * policy and an observable dead-letter topic.
+ *
+ * @example
+ * ```ts
+ * import { logProjector, topic } from "@graphrefly/graphrefly";
+ *
+ * const events = topic<Doc>("docs");
+ * const proj = logProjector("indexer", events, {
+ *   sink: async (doc) => { await index(doc); },   // throw ⇒ poison
+ *   onPoison: "deadLetter",
+ * });
+ * proj.deadLetter.events.subscribe(/* observe poison *​/);
+ * ```
+ *
+ * @remarks
+ * **Use an UNBOUNDED source for durable / long-lived projection.** The cursor
+ * is an absolute index; the underlying `fromCursor` view slices the source's
+ * *current* entries array. A `TopicGraph` with a `retainedLimit` (or a
+ * `ReactiveLogBundle` with `maxSize`) trims its head, so an absolute cursor
+ * past the retained window reads the wrong offset (skips entries or stalls).
+ * This is inherited `subscription()` / `fromCursor` behaviour, not specific to
+ * `logProjector` — but it matters here because projection is typically
+ * long-lived. For unbounded projection pass a source with NO `retainedLimit` /
+ * `maxSize` (memo:Re's `changesetLog` is unbounded ✓).
+ *
+ * @category patterns
+ */
+declare function logProjector<T>(name: string, source: TopicGraph<T> | ReactiveLogBundle<T>, opts: LogProjectorOptions<T>): LogProjectorGraph<T>;
 
-export { CONTEXT_TOPIC, DEFERRED_TOPIC, type HubRemoveTopicRecord, INJECTIONS_TOPIC, type JsonSchema, type MessagingAuditRecord, MessagingHubGraph, type MessagingHubOptions, PROMPTS_TOPIC, type PullAndAckResult, RESPONSES_TOPIC, SPAWNS_TOPIC, STANDARD_TOPICS, type StandardTopic, type SubscriptionAckRecord, SubscriptionGraph, type SubscriptionOptions, type SubscriptionPullAndAckRecord, TODOS_TOPIC, TopicBridgeGraph, type TopicBridgeOptions, TopicGraph, type TopicMessage, type TopicOptions, type TopicPublishRecord, TopicRegistry, hubRemoveTopicKeyOf, messagingHub, subscription, subscriptionAckKeyOf, subscriptionPullAndAckKeyOf, topic, topicBridge, topicPublishKeyOf };
+export { CONTEXT_TOPIC, DEFERRED_TOPIC, type DeadLetterEntry, type HubRemoveTopicRecord, INJECTIONS_TOPIC, type JsonSchema, LogProjectorGraph, type LogProjectorOptions, type MessagingAuditRecord, MessagingHubGraph, type MessagingHubOptions, PROMPTS_TOPIC, type ProjectorPoisonPolicy, type PullAndAckResult, RESPONSES_TOPIC, SPAWNS_TOPIC, STANDARD_TOPICS, type StandardTopic, type SubscriptionAckRecord, SubscriptionGraph, type SubscriptionOptions, type SubscriptionPullAndAckRecord, TODOS_TOPIC, TopicBridgeGraph, type TopicBridgeOptions, TopicGraph, type TopicMessage, type TopicOptions, type TopicPublishRecord, TopicRegistry, hubRemoveTopicKeyOf, logProjector, messagingHub, subscription, subscriptionAckKeyOf, subscriptionPullAndAckKeyOf, topic, topicBridge, topicPublishKeyOf };

package/dist/utils/messaging/index.d.ts

@@ -1,4 +1,5 @@
 import * as _graphrefly_pure_ts_extra from '@graphrefly/pure-ts/extra';
+import { ReactiveLogBundle } from '@graphrefly/pure-ts/extra';
 import { BaseAuditRecord } from '../../base/mutation/index.js';
 import { Node } from '@graphrefly/pure-ts/core';
 import { Graph, GraphOptions } from '@graphrefly/pure-ts/graph';
@@ -329,7 +330,7 @@ declare class TopicGraph<T> extends Graph {
     attachEventStorage(tiers: readonly _graphrefly_pure_ts_extra.AppendLogStorageTier<T>[]): () => void;
     retained(): readonly T[];
     /** Internal log bundle — used by TopicBridgeGraph for `attach`. */
-    get _logBundle(): _graphrefly_pure_ts_extra.ReactiveLogBundle<T>;
+    get _logBundle(): ReactiveLogBundle<T>;
 }
 type SubscriptionOptions = {
     graph?: GraphOptions;
@@ -558,5 +559,117 @@ declare function subscription<T>(name: string, topicGraph: TopicGraph<T>, opts?:
  * downstream subscription on the bridge's `output` node instead.
  */
 declare function topicBridge<TIn, TOut = TIn>(name: string, sourceTopic: TopicGraph<TIn>, targetTopic: TopicGraph<TOut>, opts?: TopicBridgeOptions<TIn, TOut>): TopicBridgeGraph<TIn, TOut>;
+type ProjectorPoisonPolicy = "halt" | "deadLetter";
+/** A poison entry routed to {@link LogProjectorGraph.deadLetter}. */
+type DeadLetterEntry<T> = {
+    readonly item: T;
+    /** `Error.message` (or `String(thrown)`) from the failing `sink`. */
+    readonly error: string;
+    /** Absolute 0-based log position of the poisoned item. */
+    readonly cursorPos: number;
+};
+type LogProjectorOptions<T> = {
+    graph?: GraphOptions;
+    /**
+     * Per-item side-effecting projection.
+     *
+     * **Transient-vs-poison contract (read this).** The projector cannot tell
+     * "this will project later" from "this will never project" — only the sink
+     * knows. So the contract is:
+     * - **Return normally** (sync return, or a resolved Promise) → the item is
+     *   *handled*; the cursor advances. Use this for the success path AND for
+     *   any transient/skip condition the sink wants to no-op (e.g. an optional
+     *   native feature not yet available — return without throwing; the entry
+     *   is simply considered done for this projector).
+     * - **Throw / reject** → the item is *poison*; the {@link onPoison} policy
+     *   applies. Do NOT throw for transient conditions or the item is
+     *   dead-lettered (or halts the stream).
+     */
+    readonly sink: (item: T) => void | Promise<void>;
+    /**
+     * Behaviour when `sink` throws/rejects on an item (poison):
+     * - `"halt"` (default) — stop projecting at the poison item; the cursor
+     *   does NOT advance past it (head-of-line stop). `position` stalls — that
+     *   is the observable signal. No retry/backoff is built in.
+     * - `"deadLetter"` — publish `{ item, error, cursorPos }` to the
+     *   {@link LogProjectorGraph.deadLetter} topic and advance past it, so
+     *   newer entries still project.
+     */
+    readonly onPoison?: ProjectorPoisonPolicy;
+    /**
+     * Initial cursor position. `"retained"` (default) projects all history;
+     * `"now"` skips existing entries (project only future appends); a number
+     * starts at that absolute index.
+     */
+    readonly from?: "retained" | "now" | number;
+    /** Retained window for the `deadLetter` topic. Default 1024. */
+    readonly deadLetterRetainedLimit?: number;
+};
+/**
+ * Cursor-driven projector over a {@link TopicGraph} or {@link ReactiveLogBundle}.
+ *
+ * Topology (mounted on the returned graph):
+ *  - `subscription` (TopicGraph source only) — the hardened
+ *    {@link SubscriptionGraph} cursor; or a local `cursor` state + the
+ *    bundle's `fromCursor` view (ReactiveLogBundle source).
+ *  - `drain` — an `effect` that, on every not-yet-projected wave, schedules a
+ *    serialized async pass that calls `sink` per item (mirrors the
+ *    `SubscriptionGraph.ackPump` / `TopicBridge.ackPump` effect precedent +
+ *    memo:Re's `inFlight` chain — one wave processed at a time).
+ *  - `deadLetter` — a real {@link TopicGraph} (NOT a callback): poison entries
+ *    are observable in `describe()` and subscribable, instead of memo:Re's
+ *    silent `break`.
+ *
+ * **No imperative reads.** Observe `position` (cursor) / subscribe to
+ * `deadLetter`. `idle()` is a test-only await convenience.
+ *
+ * @category patterns
+ */
+declare class LogProjectorGraph<T> extends Graph {
+    /** Reactive count of fully-projected entries (the cursor; read-only). */
+    readonly position: Node<number>;
+    /**
+     * Poison entries (populated when `onPoison: "deadLetter"`). A real topic —
+     * subscribable + visible in `describe()`.
+     */
+    readonly deadLetter: TopicGraph<DeadLetterEntry<T>>;
+    private _inFlight;
+    constructor(name: string, source: TopicGraph<T> | ReactiveLogBundle<T>, opts: LogProjectorOptions<T>);
+    /**
+     * Await any in-flight drain pass. **Test convenience only** — the canonical
+     * reactive observable is {@link LogProjectorGraph.position}.
+     */
+    idle(): Promise<void>;
+}
+/**
+ * Creates a cursor-driven log/topic projector with a typed poison-failure
+ * policy and an observable dead-letter topic.
+ *
+ * @example
+ * ```ts
+ * import { logProjector, topic } from "@graphrefly/graphrefly";
+ *
+ * const events = topic<Doc>("docs");
+ * const proj = logProjector("indexer", events, {
+ *   sink: async (doc) => { await index(doc); },   // throw ⇒ poison
+ *   onPoison: "deadLetter",
+ * });
+ * proj.deadLetter.events.subscribe(/* observe poison *​/);
+ * ```
+ *
+ * @remarks
+ * **Use an UNBOUNDED source for durable / long-lived projection.** The cursor
+ * is an absolute index; the underlying `fromCursor` view slices the source's
+ * *current* entries array. A `TopicGraph` with a `retainedLimit` (or a
+ * `ReactiveLogBundle` with `maxSize`) trims its head, so an absolute cursor
+ * past the retained window reads the wrong offset (skips entries or stalls).
+ * This is inherited `subscription()` / `fromCursor` behaviour, not specific to
+ * `logProjector` — but it matters here because projection is typically
+ * long-lived. For unbounded projection pass a source with NO `retainedLimit` /
+ * `maxSize` (memo:Re's `changesetLog` is unbounded ✓).
+ *
+ * @category patterns
+ */
+declare function logProjector<T>(name: string, source: TopicGraph<T> | ReactiveLogBundle<T>, opts: LogProjectorOptions<T>): LogProjectorGraph<T>;
 
-export { CONTEXT_TOPIC, DEFERRED_TOPIC, type HubRemoveTopicRecord, INJECTIONS_TOPIC, type JsonSchema, type MessagingAuditRecord, MessagingHubGraph, type MessagingHubOptions, PROMPTS_TOPIC, type PullAndAckResult, RESPONSES_TOPIC, SPAWNS_TOPIC, STANDARD_TOPICS, type StandardTopic, type SubscriptionAckRecord, SubscriptionGraph, type SubscriptionOptions, type SubscriptionPullAndAckRecord, TODOS_TOPIC, TopicBridgeGraph, type TopicBridgeOptions, TopicGraph, type TopicMessage, type TopicOptions, type TopicPublishRecord, TopicRegistry, hubRemoveTopicKeyOf, messagingHub, subscription, subscriptionAckKeyOf, subscriptionPullAndAckKeyOf, topic, topicBridge, topicPublishKeyOf };
+export { CONTEXT_TOPIC, DEFERRED_TOPIC, type DeadLetterEntry, type HubRemoveTopicRecord, INJECTIONS_TOPIC, type JsonSchema, LogProjectorGraph, type LogProjectorOptions, type MessagingAuditRecord, MessagingHubGraph, type MessagingHubOptions, PROMPTS_TOPIC, type ProjectorPoisonPolicy, type PullAndAckResult, RESPONSES_TOPIC, SPAWNS_TOPIC, STANDARD_TOPICS, type StandardTopic, type SubscriptionAckRecord, SubscriptionGraph, type SubscriptionOptions, type SubscriptionPullAndAckRecord, TODOS_TOPIC, TopicBridgeGraph, type TopicBridgeOptions, TopicGraph, type TopicMessage, type TopicOptions, type TopicPublishRecord, TopicRegistry, hubRemoveTopicKeyOf, logProjector, messagingHub, subscription, subscriptionAckKeyOf, subscriptionPullAndAckKeyOf, topic, topicBridge, topicPublishKeyOf };

package/dist/utils/messaging/index.js

@@ -2,6 +2,7 @@ import {
   CONTEXT_TOPIC,
   DEFERRED_TOPIC,
   INJECTIONS_TOPIC,
+  LogProjectorGraph,
   MessagingHubGraph,
   PROMPTS_TOPIC,
   RESPONSES_TOPIC,
@@ -13,6 +14,7 @@ import {
   TopicGraph,
   TopicRegistry,
   hubRemoveTopicKeyOf,
+  logProjector,
   messagingHub,
   subscription,
   subscriptionAckKeyOf,
@@ -20,7 +22,7 @@ import {
   topic,
   topicBridge,
   topicPublishKeyOf
-} from "../../chunk-Q3EYOCZB.js";
+} from "../../chunk-NPRP3MCV.js";
 import "../../chunk-FMPF42Q4.js";
 import "../../chunk-BXGZFGZ4.js";
 import "../../chunk-AZDQPQ3V.js";
@@ -28,6 +30,7 @@ export {
   CONTEXT_TOPIC,
   DEFERRED_TOPIC,
   INJECTIONS_TOPIC,
+  LogProjectorGraph,
   MessagingHubGraph,
   PROMPTS_TOPIC,
   RESPONSES_TOPIC,
@@ -39,6 +42,7 @@ export {
   TopicGraph,
   TopicRegistry,
   hubRemoveTopicKeyOf,
+  logProjector,
   messagingHub,
   subscription,
   subscriptionAckKeyOf,