@bandeira-tech/b3nd-save 0.8.1

package/esm/deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/rig/rig.d.ts

@@ -0,0 +1,295 @@
+/**
+ * @module
+ * Rig — the universal harness for b3nd.
+ *
+ * Single object that wires up backends, identity, and serving.
+ * Two core actions: send (outward to the network) and receive
+ * (inward from external sources). Everything else is observation.
+ *
+ * Supports per-operation client routing, synchronous hooks
+ * (pre/post), async events, and URI-pattern reactions.
+ */
+import type { Output, ProgramResult, ProtocolInterfaceNode, ReceiveResult, StatusResult } from "../types/types.js";
+import type { RigConfig, RigInfo } from "./types.js";
+import type { EventHandler, RigEventName } from "./events.js";
+import type { ReactionHandler } from "./reactions.js";
+import type { OperationHandle } from "./operation-handle.js";
+/**
+ * Rig — pure orchestration for b3nd.
+ *
+ * The rig is identity-free — it routes, validates, and dispatches.
+ * For authenticated operations, use `Identity.sign()` + `message()` +
+ * `rig.send()` directly.
+ *
+ * @example Unsigned operations
+ * ```typescript
+ * const local = connection(client, ["**"]);
+ * const rig = new Rig({
+ *   routes: { receive: [local], read: [local], observe: [local] },
+ * });
+ * const results = await rig.receive([["mutable://open/app/x", data]]);
+ * ```
+ *
+ * @example Authenticated send
+ * ```typescript
+ * // With messageDataHandler registered, the rig decomposes the
+ * // envelope into outputs + null-payload deletions for inputs.
+ * const id = await Identity.fromSeed("my-secret");
+ * const auth = [await id.sign({ inputs: [], outputs })];
+ * const envelope = await message({ auth, inputs: [], outputs });
+ * await rig.send([envelope]);
+ * ```
+ *
+ * @example With programs, hooks, events, and reactions
+ * ```typescript
+ * const local = connection(client, ["**"]);
+ * const rig = new Rig({
+ *   routes: { receive: [local], read: [local], observe: [local] },
+ *   programs,
+ *   handlers,
+ *   hooks: {
+ *     beforeReceive: (ctx) => { rateLimit(ctx.uri); },
+ *     afterRead: (ctx, result) => { audit(ctx.uri, result); },
+ *   },
+ *   on: {
+ *     "send:success": [audit],
+ *   },
+ *   reactions: {
+ *     "mutable://app/users/*": async (out, _read) => {
+ *       const id = out[0].split("/").pop();
+ *       return [[`notify://email/${id}`, { kind: "user-updated" }]];
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare class Rig {
+    private readonly _receiveRoutes;
+    private readonly _readRoutes;
+    private readonly _observeRoutes;
+    private readonly _dispatch;
+    private readonly _programs;
+    private readonly _handlers;
+    private readonly _hooks;
+    private readonly _events;
+    private readonly _reactors;
+    constructor(config: RigConfig);
+    /**
+     * Raw composite client — bypasses hooks, events, and react.
+     *
+     * Prefer passing the Rig itself (it satisfies `ProtocolInterfaceNode`).
+     * This getter exists for third-party code that requires a plain object.
+     */
+    get client(): ProtocolInterfaceNode;
+    /**
+     * Send tuples — the host application acting as the origin.
+     *
+     * Returns an `OperationHandle` that:
+     *   - Awaits to `ReceiveResult[]` once the pipeline (process →
+     *     handle) finishes. Pipeline-stage ack only — broadcast may
+     *     still be in flight.
+     *   - Fires per-stage events (`process:done`, `handle:emit`,
+     *     `route:success`/`route:error`, `settled`) scoped to this call.
+     *
+     * Dispatch to connections runs in the background; per-route outcomes
+     * arrive as events. Wait for `op.settled` for read-after-write
+     * guarantees across replicas.
+     *
+     * Use this when the host is the origin of the content (a button
+     * click, a worker emitting state, a signed envelope from
+     * `Identity.sign()` + `message()`). Use `receive()` when content arrives from
+     * elsewhere (a peer, a webhook, an upstream sync).
+     *
+     * @example
+     * ```typescript
+     * const op = rig.send([["mutable://app/state", { value: 42 }]]);
+     * op.on("route:error", (e) => retry(e.emission));
+     * const [result] = await op;             // pipeline ack
+     * await op.settled;                       // routes fully settled
+     * ```
+     */
+    send(outs: Output[]): OperationHandle;
+    /**
+     * Receive tuples — the host application accepting state from elsewhere.
+     *
+     * Same shape as `send()` but fires `beforeReceive`/`afterReceive`
+     * hooks and `receive:*` global events. Returns an `OperationHandle`
+     * with the same scoped per-stage events.
+     *
+     * @example
+     * ```typescript
+     * const [result] = await rig.receive([
+     *   ["mutable://open/external", { source: "webhook" }],
+     * ]);
+     * ```
+     */
+    receive(outs: Output[]): OperationHandle;
+    /**
+     * Same as `receive()` but throws if any input tuple is rejected at
+     * the pipeline stage. Convenience for callers that don't want to
+     * inspect `accepted`.
+     */
+    receiveOrThrow(outs: Output[]): Promise<ReceiveResult[]>;
+    /** Same as `send()` but throws on any pipeline-stage rejection. */
+    sendOrThrow(outs: Output[]): Promise<ReceiveResult[]>;
+    /**
+     * Classify a batch of tuples — runs registered programs.
+     *
+     * For each output, finds the program with the longest matching URI
+     * prefix and invokes it. Tuples whose URI matches no registered
+     * program get a default `{ code: "ok" }` classification (so the
+     * default-dispatch path persists them as-is).
+     *
+     * Pure: returns one `ProgramResult` per input tuple. No side effects.
+     */
+    process(outs: Output[]): Promise<ProgramResult[]>;
+    /**
+     * Run the handler for a classified tuple — returns the emissions.
+     *
+     * If no handler is registered for the result's code, the input tuple
+     * is returned as-is (default-persist). Handlers themselves return the
+     * `Output[]` they want the Rig to dispatch; this method surfaces that
+     * return for callers that want to compose the pipeline manually.
+     *
+     * Pure: no dispatch happens here. Use `send()` / `receive()` for the
+     * full pipeline including dispatch and reactions.
+     */
+    handle(out: Output, result: ProgramResult): Promise<Output[]>;
+    /**
+     * The pipeline body shared by `send()` and `receive()`.
+     *
+     * Returns an `OperationHandle` synchronously. The pipeline runs
+     * asynchronously inside; awaiting the handle resolves to the
+     * pipeline-stage `ReceiveResult[]` (process + handle outcome only).
+     * Per-route dispatch runs in the background; route outcomes arrive
+     * as events on the handle. `op.settled` resolves once every route
+     * has answered.
+     *
+     * Reactions fire after each emission's routes settle — once per
+     * emission, only if at least one route accepted. Their emissions
+     * spawn a fresh `rig.send(...)` operation, independent of this one.
+     */
+    private _pipeline;
+    /** Internal: pipeline body driven against an OperationHandleImpl. */
+    private _runPipeline;
+    /**
+     * Run process for a single output. Isolated so a thrown program
+     * doesn't fail the whole batch.
+     */
+    private _processOne;
+    /** Run the direction-appropriate after-hook with the standard payload. */
+    private _runAfterFor;
+    /**
+     * Per-emission, per-connection dispatch with route events.
+     *
+     * For each emission: find every connection in `routes.receive` that
+     * accepts the URI, dispatch the emission to each independently, emit
+     * `route:success` / `route:error` per (emission, connection). Once
+     * all routes for an emission settle, fire reactions if any route
+     * accepted. Reactions' returned tuples spawn a fresh `rig.send`
+     * operation (independent of this one).
+     *
+     * `input` is the original tuple that drove this dispatch — passed
+     * through so the `onError` hook can correlate route failures back
+     * to the input that triggered them.
+     */
+    private _dispatchRouteAware;
+    /**
+     * Fire reactions for a successfully-dispatched emission. Reaction
+     * returns are dispatched through a fresh `rig.send(...)` — that
+     * spawned operation has its own OperationHandle and is unrelated
+     * to the one that triggered it. Loops are usage error.
+     */
+    private _fireReactionsForEmission;
+    /** Internal read helper bound to the dispatch read interface. */
+    private _readFn;
+    /**
+     * Find the program with the longest matching URI prefix.
+     */
+    private _findProgram;
+    /**
+     * Read a batch of locators. Each locator goes to the first connection
+     * whose route pattern accepts it. Locators are opaque strings; the
+     * executing client owns any grammar interpretation.
+     */
+    read<T = unknown>(urls: string[]): Promise<Output<T>[]>;
+    /**
+     * Observe changes matching a URI pattern.
+     *
+     * Routes to the first connection that accepts `observe` for the pattern,
+     * then delegates to the client's native transport (SSE, internal events, etc).
+     *
+     * @example
+     * ```typescript
+     * const abort = new AbortController();
+     * for await (const uris of rig.observe(["mutable://data/market/**"], abort.signal)) {
+     *   for (const uri of uris) console.log(uri);
+     * }
+     * ```
+     */
+    observe(urls: string[], signal: AbortSignal): AsyncIterable<readonly string[]>;
+    /**
+     * Get a snapshot of this rig's current state.
+     *
+     * Pure local inspection, no network calls.
+     *
+     * @example
+     * ```typescript
+     * const info = rig.info();
+     * console.log(info.behavior.hooks);
+     * console.log(info.behavior.reactors);
+     * ```
+     */
+    info(): RigInfo;
+    /**
+     * Status — health + schema.
+     * Aggregates client status across all connections.
+     */
+    status(): Promise<StatusResult>;
+    /**
+     * Return any in-flight event handler promises and clear the queue.
+     */
+    drain(): Promise<void>[];
+    /**
+     * Register an event handler at runtime. Returns an unsubscribe function.
+     *
+     * @example
+     * ```typescript
+     * const unsub = rig.on("send:success", (event) => {
+     *   console.log(`Sent to ${event.uri}`);
+     * });
+     *
+     * // Later:
+     * unsub();
+     * ```
+     */
+    on(event: RigEventName, handler: EventHandler): () => void;
+    /** Remove a specific event handler. */
+    off(event: RigEventName, handler: EventHandler): void;
+    /**
+     * Register a react pattern at runtime. Returns an unsubscribe function.
+     *
+     * Fires on successful `send()` or `receive()` when the written URI
+     * matches the pattern. Fire-and-forget — errors are caught and logged.
+     *
+     * Reactions return `Output[]` — those tuples flow back through
+     * `rig.send` (full pipeline). See chapter 7 of RFC 001 for the
+     * productive-observation model.
+     *
+     * @example
+     * ```typescript
+     * const unsub = rig.reaction(
+     *   "mutable://app/users/*",
+     *   async (out, _read) => {
+     *     const id = out[0].split("/").pop();
+     *     return [[`notify://email/${id}`, { kind: "user-updated" }]];
+     *   },
+     * );
+     *
+     * // Later:
+     * unsub();
+     * ```
+     */
+    reaction(pattern: string, handler: ReactionHandler): () => void;
+}
+//# sourceMappingURL=rig.d.ts.map

package/esm/deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/rig/rig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rig.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/rig/rig.ts"],"names":[],"mappings":"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"}