@johannc-dev/zyrk 0.0.0-stage → 0.2.0

package/dist/local.d.ts

@@ -0,0 +1,235 @@
+import { type PendingEvent, type ReplayProgress } from "./local-replay.js";
+import { LocalData } from "./local-data.js";
+import { LocalStorage, type AreaConfig } from "./local-storage.js";
+import { accountLimits, execLimits } from "./limits.js";
+import { type JobFailure, type JobResult, type JobStatus, type Json, type Program, type Subscription } from "./sdk.js";
+/** The sandbox bootstrap shipped with the package (see scripts/build.mjs). */
+export declare function sandboxBootstrap(): string;
+export type ProgramSource = 
+/** Entry point (`.ts`/`.js`), built as `zyrk deploy` builds it. */
+string
+/** A built bundle (`.functions/program.js`). */
+ | {
+    readonly code: string;
+}
+/** A program object imported in your test (runs with Node's globals). */
+ | Program;
+type Numbers<T> = {
+    readonly [K in keyof T]: number;
+};
+export interface LocalLimits {
+    readonly exec: Numbers<typeof execLimits>;
+    readonly account: Numbers<typeof accountLimits>;
+}
+export interface LocalOptions {
+    /** Directory written by `zyrk export`, or a {@link LocalData}. */
+    readonly data?: string | LocalData;
+    /**
+     * Program state: a folder (kept in `<folder>/<program>.json` between
+     * runs), or initial values in memory. Default: empty, in memory.
+     */
+    readonly state?: string | Readonly<Record<string, Json>>;
+    /** User storage: a folder, or `"memory"` (default). */
+    readonly storage?: string | LocalStorage;
+    /** Storage areas and their quotas (default: `short` and `long` as documented). */
+    readonly storageAreas?: Readonly<Record<string, AreaConfig>>;
+    /** Print logs and emits as they happen (`zyrk dev`), or receive them. */
+    readonly console?: boolean | ((line: ConsoleLine) => void);
+    /** Program name in `ctx.execution.program` (default `local`). */
+    readonly program?: string;
+    /** Override limits (default: the service's, `@johannc-dev/zyrk/limits`). */
+    readonly limits?: {
+        readonly exec?: Partial<Numbers<typeof execLimits>>;
+        readonly account?: Partial<Numbers<typeof accountLimits>>;
+    };
+    /** `zyrk build` type-checking of an entry point (default true). */
+    readonly typecheck?: boolean;
+    readonly now?: () => number;
+    /**
+     * The account's webhook, as `PUT /v1/functions/webhook` would set it.
+     * Default: none, so `ctx.webhook.send` rejects with
+     * `webhook_not_configured`, as on the service. Messages are never sent
+     * locally: they stay queued (`queueLimit`, default 1000, then
+     * `webhook_queue_full` or `dropped: true` with `onFull: "drop"`).
+     */
+    readonly webhook?: LocalWebhook;
+}
+/** {@link LocalOptions.webhook}. */
+export interface LocalWebhook {
+    /** A webhook is set (default false). */
+    readonly configured?: boolean;
+    /** Not paused (default true). */
+    readonly enabled?: boolean;
+    /** Messages waiting before the queue is full (default 1000, the service's). */
+    readonly queueLimit?: number;
+}
+export interface ConsoleLine {
+    readonly kind: "log" | "emit" | "webhook";
+    readonly execution: string;
+    readonly function: string;
+    readonly value: Json;
+}
+export interface LocalUsage {
+    /** Rough: process CPU while the execution ran, reads excluded (parallel jobs overlap). */
+    cpuMs: number;
+    readMs: number;
+    wallMs: number;
+    readBytes: number;
+    readCalls: number;
+    hostOps: number;
+    outputBytes: number;
+    /** Rough: growth of Node's heap while the execution ran. */
+    peakHeapBytes: number;
+}
+/** One execution, as `GET /executions/{id}` would show it. */
+export interface LocalExecution {
+    readonly id: string;
+    readonly function: string;
+    readonly args: Json;
+    readonly status: JobStatus;
+    readonly result?: Json;
+    readonly error?: JobFailure;
+    readonly logs: readonly Json[];
+    readonly emits: readonly Json[];
+    readonly usage: LocalUsage;
+    readonly children: readonly string[];
+    /** Id of the continuation (`ctx.jobs.continue`), if any. */
+    readonly next?: string;
+}
+/** What {@link LocalRunner.run} answers: the last execution of the chain, and the chain. */
+export interface LocalRun {
+    readonly id: string;
+    readonly status: "succeeded" | "failed" | "cancelled";
+    readonly result?: Json;
+    /** The result as the sandbox serializes it (the bytes the service stores). */
+    readonly resultText?: string;
+    readonly error?: JobFailure;
+    /** Logs and emits of the whole chain (continuations included). */
+    readonly logs: readonly Json[];
+    readonly emits: readonly Json[];
+    /** `ctx.webhook.send` payloads of the chain (never sent locally). */
+    readonly webhooks: readonly Json[];
+    readonly executions: readonly LocalExecution[];
+    /** Where this run may differ from the service. */
+    readonly warnings: readonly string[];
+}
+/**
+ * A local account with one program: executions, their jobs, the program's
+ * state and subscriptions, and user storage. Keep one runner across calls
+ * to keep state between executions, as the service does.
+ */
+export declare class LocalRunner {
+    #private;
+    readonly data: LocalData | undefined;
+    readonly storage: LocalStorage;
+    readonly limits: LocalLimits;
+    /** Committed program state. */
+    readonly state: Map<string, Json>;
+    /** Active subscriptions (declared, then changed by `ctx.subscriptions`). */
+    readonly subscriptions: Map<string, Subscription>;
+    readonly warnings: string[];
+    private constructor();
+    /** Builds (entry path) or takes a bundle, and reads its description as the service does at deploy. */
+    static load(source: ProgramSource, options?: LocalOptions): Promise<LocalRunner>;
+    /** Resolves when no execution runs or waits any more (jobs, completions). */
+    idle(): Promise<void>;
+    /** Every job of the account, as `ctx.jobs.result` sees it. */
+    jobs(): JobResult[];
+    /** Every execution, in start order. */
+    executions(): LocalExecution[];
+    /**
+     * Runs `fn(args)` as `zyrk run` does, follows its continuations, and
+     * answers the last execution of the chain. Jobs it started may still run:
+     * `await runner.idle()` to wait for them.
+     */
+    run(fn: string, args?: Json): Promise<LocalRun>;
+    /**
+     * Replays a subscription over `[sinceMs, untilMs)` from exported history,
+     * as the service's replays do (local-replay.ts): the same deliveries, at
+     * most 32 events each, one at a time (the next waits for the previous one
+     * and its jobs), with `replay: { id, delivery, clockMs, sinceMs, untilMs,
+     * simulated: true }`. The deliveries run in an isolated copy of the
+     * program: its state starts empty and is not this runner's, and
+     * `ctx.subscriptions` fails there (`replay_isolated`). Stops at the first
+     * delivery that fails (`delivery_failed`).
+     */
+    replay(options: ReplayOptions): Promise<LocalReplay>;
+    /** The events {@link replay} delivers, without running anything. */
+    replayEvents(s: Subscription, o: ReplayOptions): PendingEvent[];
+}
+export interface ReplayOptions {
+    /** Name of an active subscription of the program. */
+    readonly subscription: string;
+    readonly sinceMs: number;
+    readonly untilMs: number;
+    /** Events per delivery, 1 to 32 (default 32, as the service). */
+    readonly eventsPerDelivery?: number;
+    /**
+     * Events per delivery, 1 to 1,000: the service's `batchSize` (larger
+     * batches than live, opt-in). Wins over `eventsPerDelivery`.
+     */
+    readonly batchSize?: number;
+    /** Stop after this many deliveries. */
+    readonly maxDeliveries?: number;
+    /**
+     * Receives the replay's emits and execution records as they come, as the
+     * service sends them (`GET /replays/{id}/emits`): `{kind: "emitted",
+     * data, seq}` then `{kind: "execution", execution, seq}` per delivery.
+     * With it, `runs` and `emits` of the answer stay empty (nothing is kept).
+     */
+    readonly onFeed?: (item: Record<string, Json>) => void;
+    /**
+     * Without `onFeed`: bytes of emits and records kept before the replay
+     * fails with `replay_feed_full` (the service's bound, 16 MiB).
+     */
+    readonly feedBytes?: number;
+    /** Longest wall-clock time (default 30 min, the service's). */
+    readonly maxDurationMs?: number;
+    /**
+     * Copies what the replay wrote in its own storage space to the runner's
+     * storage when it succeeds (otherwise that space is dropped): the
+     * objects of area `from` (default `to`), or only `keys`, into `to`,
+     * within that area's quota (refused as a whole).
+     */
+    readonly keepStorage?: KeepStorage;
+}
+/** {@link ReplayOptions.keepStorage}. */
+export interface KeepStorage {
+    readonly to: "long" | "durable";
+    readonly from?: "short" | "long" | "durable";
+    readonly keys?: readonly string[];
+}
+/** The service's `ReplayLimits::max_duration_ms` (30 min). */
+export declare const REPLAY_MAX_DURATION_MS: number;
+/** The service's `FeedLimits::replay_bytes` (16 MiB). */
+export declare const REPLAY_FEED_BYTES: number;
+/** What {@link LocalRunner.replay} answers (the service's replay record, locally). */
+export interface LocalReplay {
+    readonly id: string;
+    readonly status: "succeeded" | "failed";
+    /** `delivery_failed` when a delivery failed for good. */
+    readonly error?: JobFailure;
+    /** One run per delivery, in order. */
+    readonly runs: readonly LocalRun[];
+    /** The isolated state at the end (the runner's own state is untouched). */
+    readonly state: ReadonlyMap<string, Json>;
+    readonly emits: readonly Json[];
+    readonly progress: Readonly<ReplayProgress>;
+    readonly warnings: readonly string[];
+    /** What `keepStorage` copied (or why nothing was). */
+    readonly keptStorage?: {
+        readonly copied: true;
+        readonly objects: number;
+        readonly bytes: number;
+    } | {
+        readonly copied: false;
+        readonly error: JobFailure;
+    };
+}
+/**
+ * Runs one function locally, as `zyrk run` does in the service, and waits
+ * for the jobs it started. For several runs sharing state, use
+ * {@link LocalRunner}.
+ */
+export declare function runLocal(source: ProgramSource, fn: string, args?: Json, options?: LocalOptions): Promise<LocalRun>;
+export {};