@littlebigbrain/client 0.15.0 → 0.16.0

package/dist/types.d.ts

@@ -151,6 +151,12 @@ export interface SparqlResults {
      * plain strong read.
      */
     snapshot: Schemas["SnapshotView"] | null;
+    /**
+     * What the server measured for the request: timings, reads, plan counters
+     * and the join order with estimates. Present only when the request set
+     * `profile: true`.
+     */
+    profile?: Schemas["SparqlQueryProfile"];
 }
 /**
  * Parse a {@link Schemas.SparqlTextResponse} (whose `results` field carries the
@@ -158,6 +164,13 @@ export interface SparqlResults {
  * `{ variable: lexicalValue }` rows — the form most callers want, so they never
  * have to `JSON.parse` and zip `head.vars` with binding values by hand.
  */
+/**
+ * Send `profile` only when it is `true`. An answer without the field is the
+ * default, and a server that predates `profile` refuses unknown body fields.
+ */
+export declare function profileBody<B extends {
+    profile?: boolean;
+}>(body: B, profile?: boolean): B;
 export declare function parseSparqlResults(response: Schemas["SparqlTextResponse"]): SparqlResults;
 export declare function firstPatternVariable(patterns: Schemas["AnalyticTriplePattern"][]): string;
 export declare function attributeFilter(filter: AttributeFilter, defaultVar: string): Schemas["SparqlFilter"];

package/dist/types.js

@@ -4,16 +4,34 @@
  * `{ variable: lexicalValue }` rows — the form most callers want, so they never
  * have to `JSON.parse` and zip `head.vars` with binding values by hand.
  */
+/**
+ * Send `profile` only when it is `true`. An answer without the field is the
+ * default, and a server that predates `profile` refuses unknown body fields.
+ */
+export function profileBody(body, profile) {
+    const { profile: bodyProfile, ...rest } = body;
+    return (bodyProfile ?? profile) === true
+        ? { ...rest, profile: true }
+        : rest;
+}
 export function parseSparqlResults(response) {
     const doc = JSON.parse(response.results);
     const vars = doc.head?.vars ?? [];
     const snapshot = response.snapshot ?? null;
+    const profile = response.profile ? { profile: response.profile } : {};
     if (typeof doc.boolean === "boolean") {
-        return { vars, boolean: doc.boolean, bindings: [], rows: [], snapshot };
+        return {
+            vars,
+            boolean: doc.boolean,
+            bindings: [],
+            rows: [],
+            snapshot,
+            ...profile,
+        };
     }
     const bindings = doc.results?.bindings ?? [];
     const rows = bindings.map((binding) => Object.fromEntries(Object.entries(binding).map(([name, term]) => [name, term.value])));
-    return { vars, boolean: null, bindings, rows, snapshot };
+    return { vars, boolean: null, bindings, rows, snapshot, ...profile };
 }
 export function firstPatternVariable(patterns) {
     for (const pattern of patterns) {

package/dist/workflows.d.ts

@@ -0,0 +1,207 @@
+import type { LbbClient, Schemas } from "./client.js";
+import type { CallOptions } from "./transport.js";
+type Turn = Schemas["WorkflowTurn"];
+type Instance = Schemas["WorkflowInstance"];
+/** A permanent handler/replay error; ordinary thrown errors retry up to max_attempts. */
+export declare class WorkflowError extends Error {
+}
+export interface WorkflowResult<S, R = unknown, M = unknown> {
+    state: S;
+    result?: R;
+    continuation?: {
+        message: M;
+    };
+}
+export interface WorkflowStepOptions {
+    kind?: "step" | "model" | "tool";
+    /** Per-attempt execution limit, independent of worker lease renewal (default 5 minutes). */
+    timeoutMs?: number;
+    /** Require explicit progress from the operation, independent of worker liveness. */
+    heartbeatTimeoutMs?: number;
+}
+export interface WorkflowStepContext {
+    effectId: string;
+    signal: AbortSignal;
+    /** Last progress checkpoint from a previous attempt, or null. */
+    checkpoint: unknown;
+    heartbeat(details: unknown, options?: {
+        checkpoint?: unknown;
+    }): Promise<void>;
+}
+export type WorkflowSignalResult<T> = {
+    received: true;
+    value: T;
+} | {
+    received: false;
+    value: null;
+};
+export interface WorkflowContext {
+    readonly signal: AbortSignal;
+    readonly workflowId: string;
+    readonly messageId: string;
+    readonly turn: number;
+    /** Sequential named effects only. Pass effectId to the external service as its idempotency key. */
+    step<T>(key: string, effect: (context: WorkflowStepContext) => Promise<T>, options?: WorkflowStepOptions): Promise<T>;
+    /** Wait without holding a worker; signals can arrive before registration. */
+    waitForSignal<T = unknown>(key: string, options: {
+        name: string;
+        timeoutMs: number;
+    }): Promise<WorkflowSignalResult<T>>;
+    /** Checkpoint and release the worker until the timer is due. */
+    sleep(key: string, milliseconds: number): Promise<void>;
+    /** Commit state and append a new message at the inbox tail in one transaction. */
+    continue<S, M>(state: S, message: M): WorkflowResult<S, never, M>;
+}
+interface RegisteredWorkflow {
+    name: string;
+    version: string;
+    initialState: unknown;
+    execute(ctx: WorkflowContext, state: unknown, message: unknown): Promise<WorkflowResult<unknown>>;
+}
+export interface WorkflowDefinition<S, M> extends RegisteredWorkflow {
+    initialState: S;
+    start(client: LbbClient, id: string, options?: {
+        leaseMs?: number;
+        maxAttempts?: number;
+    }): Promise<WorkflowHandle<M>>;
+}
+/** Define a version-pinned message handler. Put I/O, clock reads and randomness inside ctx.step. */
+export declare function workflow<S, M, R = unknown>(definition: {
+    name: string;
+    version: string;
+    initialState: S;
+    onMessage(ctx: WorkflowContext, state: S, message: M): Promise<WorkflowResult<S, R, M>>;
+}): WorkflowDefinition<S, M>;
+export declare class WorkflowHandle<M = unknown> {
+    private readonly api;
+    readonly id: string;
+    constructor(api: WorkflowNamespace, id: string);
+    status(options?: CallOptions): Promise<Instance>;
+    /** Reuse id when retrying the same message, including after a client restart. */
+    send(message: M, options: {
+        id: string;
+    } & CallOptions): Promise<Turn>;
+    /** Deliver an approval, callback or other event to a specific run, including while it waits. */
+    signal(name: string, value: unknown, options: {
+        turn: number;
+        id: string;
+    } & CallOptions): Promise<Turn>;
+    history(options?: {
+        after?: number;
+        limit?: number;
+    } & CallOptions): Promise<{
+        next_after?: number | null;
+        turns: import("./schema.js").components["schemas"]["WorkflowTurn"][];
+    }>;
+    pause(options?: CallOptions): Promise<{
+        completed_turns: number;
+        created_at_ms: number;
+        current_turn?: null | import("./schema.js").components["schemas"]["WorkflowTurn"];
+        history_pruned_through?: number;
+        history_through: number;
+        id: string;
+        pending_messages: number;
+        sequence: number;
+        state: unknown;
+        status: import("./schema.js").components["schemas"]["WorkflowInstanceStatus"];
+        updated_at_ms: number;
+        version: string;
+        workflow_type: string;
+    }>;
+    resume(options?: CallOptions): Promise<{
+        completed_turns: number;
+        created_at_ms: number;
+        current_turn?: null | import("./schema.js").components["schemas"]["WorkflowTurn"];
+        history_pruned_through?: number;
+        history_through: number;
+        id: string;
+        pending_messages: number;
+        sequence: number;
+        state: unknown;
+        status: import("./schema.js").components["schemas"]["WorkflowInstanceStatus"];
+        updated_at_ms: number;
+        version: string;
+        workflow_type: string;
+    }>;
+    retry(turn: number, options?: CallOptions): Promise<{
+        completed_turns: number;
+        created_at_ms: number;
+        current_turn?: null | import("./schema.js").components["schemas"]["WorkflowTurn"];
+        history_pruned_through?: number;
+        history_through: number;
+        id: string;
+        pending_messages: number;
+        sequence: number;
+        state: unknown;
+        status: import("./schema.js").components["schemas"]["WorkflowInstanceStatus"];
+        updated_at_ms: number;
+        version: string;
+        workflow_type: string;
+    }>;
+    cancelTurn(turn: number, options?: CallOptions): Promise<{
+        completed_turns: number;
+        created_at_ms: number;
+        current_turn?: null | import("./schema.js").components["schemas"]["WorkflowTurn"];
+        history_pruned_through?: number;
+        history_through: number;
+        id: string;
+        pending_messages: number;
+        sequence: number;
+        state: unknown;
+        status: import("./schema.js").components["schemas"]["WorkflowInstanceStatus"];
+        updated_at_ms: number;
+        version: string;
+        workflow_type: string;
+    }>;
+}
+export declare class WorkflowNamespace {
+    private readonly client;
+    constructor(client: LbbClient);
+    handle<M = unknown>(id: string): WorkflowHandle<M>;
+    start<S, M>(definition: WorkflowDefinition<S, M>, id: string, options?: {
+        leaseMs?: number;
+        maxAttempts?: number;
+    }): Promise<WorkflowHandle<M>>;
+    create(request: Schemas["WorkflowInstanceCreateRequest"], options?: CallOptions): Promise<Instance>;
+    get(id: string, options?: CallOptions): Promise<Instance>;
+    list(options?: {
+        after?: string;
+        limit?: number;
+    } & CallOptions): Promise<Schemas["WorkflowInstanceListResponse"]>;
+    send(workflowId: string, message: unknown, options: {
+        id: string;
+    } & CallOptions): Promise<Turn>;
+    signal(workflowId: string, name: string, value: unknown, options: {
+        turn: number;
+        id: string;
+    } & CallOptions): Promise<Turn>;
+    history(id: string, options?: {
+        after?: number;
+        limit?: number;
+    } & CallOptions): Promise<Schemas["WorkflowTurnHistoryResponse"]>;
+    control(id: string, action: Schemas["WorkflowInstanceAction"], turn?: number, options?: CallOptions): Promise<Instance>;
+    /**
+     * Delete an instance with its turns and history. `deleted` is false when
+     * no instance had the id, or when a retry finished an earlier delete.
+     * The id can be created again once this returns.
+     */
+    deleteInstance(id: string, options?: CallOptions): Promise<Schemas["WorkflowInstanceDeleteResponse"]>;
+}
+/** One turn at a time per worker; run additional worker processes for concurrency. */
+export declare class WorkflowWorker {
+    private readonly client;
+    private readonly definitions;
+    private readonly options;
+    constructor(client: LbbClient, definitions: readonly RegisteredWorkflow[], options: {
+        worker: string;
+    });
+    run(options: {
+        signal: AbortSignal;
+    }): Promise<void>;
+    runOnce(options?: {
+        signal?: AbortSignal;
+        waitMs?: number;
+    }): Promise<boolean>;
+    private execute;
+}
+export {};