@hatchet-dev/typescript-sdk 1.34.0-alpha.1 → 1.34.0

package/v1/client/admin.js

@@ -8,17 +8,6 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-var __rest = (this && this.__rest) || function (s, e) {
-    var t = {};
-    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
-        t[p] = s[p];
-    if (s != null && typeof Object.getOwnPropertySymbols === "function")
-        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
-            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
-                t[p[i]] = s[p[i]];
-        }
-    return t;
-};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -26,51 +15,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AdminClient = void 0;
 const hatchet_error_1 = __importDefault(require("../../util/errors/hatchet-error"));
 const idempotency_collision_error_1 = require("../../util/errors/idempotency-collision-error");
-const bulk_trigger_idempotency_collision_error_1 = require("../../util/errors/bulk-trigger-idempotency-collision-error");
 const workflow_run_ref_1 = __importDefault(require("../../util/workflow-run-ref"));
-const connect_1 = require("@connectrpc/connect");
-const workflows_pb_1 = require("../../protoc-es/v1/workflows_pb");
 const nice_grpc_1 = require("nice-grpc");
 const grpc_helpers_1 = require("../../util/grpc-helpers");
 const config_loader_1 = require("../../util/config-loader");
 const child_listener_client_1 = require("../../clients/listeners/run-listener/child-listener-client");
 const workflows_1 = require("../../protoc/workflows");
 const rpc_1 = require("../../clients/admin/rpc");
+const trigger_request_1 = require("../../clients/admin/trigger-request");
 const transport_1 = require("../../clients/transport");
 const retrier_1 = require("../../util/retrier");
 const batch_1 = require("../../util/batch");
-const apply_namespace_1 = require("../../util/apply-namespace");
-/**
- * The engine answers a trigger whose idempotency key is already taken with `ALREADY_EXISTS`
- * and attaches the collision details to the status. The Connect client decodes those details
- * from the trailer, so the error carries everything needed to build the SDK's collision errors.
- */
-function isAlreadyExists(e) {
-    return e instanceof connect_1.ConnectError && e.code === connect_1.Code.AlreadyExists;
-}
-function extractExistingRunId(e) {
-    var _a;
-    const [detail] = e.findDetails(workflows_pb_1.IdempotencyCollisionErrorSchema);
-    return (_a = detail === null || detail === void 0 ? void 0 : detail.existingRunExternalId) !== null && _a !== void 0 ? _a : '';
-}
-function extractBulkTriggerCollision(e) {
-    const [detail] = e.findDetails(workflows_pb_1.BulkTriggerIdempotencyCollisionErrorSchema);
-    if (!detail)
-        return null;
-    return new bulk_trigger_idempotency_collision_error_1.BulkTriggerIdempotencyCollisionError(detail.successfulWorkflowRunExternalIds, detail.collisions.map((c) => new idempotency_collision_error_1.IdempotencyCollisionError(c.existingRunExternalId)));
-}
-function convertDesiredWorkerLabels(labels) {
-    return Object.fromEntries(Object.entries(labels).map(([key, label]) => [
-        key,
-        {
-            strValue: typeof label.value === 'string' ? label.value : undefined,
-            intValue: typeof label.value === 'number' ? label.value : undefined,
-            required: label.required,
-            weight: label.weight,
-            comparator: label.comparator,
-        },
-    ]));
-}
 class AdminClient {
     constructor(config, api, runs, transport = (0, transport_1.createNodeTransport)(config)) {
         this.config = config;
@@ -111,24 +66,16 @@ class AdminClient {
     runWorkflow(workflowName, input, options) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
-                const computedName = (0, apply_namespace_1.applyNamespace)(workflowName, this.config.namespace).toLowerCase();
-                const inputStr = JSON.stringify(input);
-                const opts = options !== null && options !== void 0 ? options : {};
-                const { additionalMetadata, parentStepRunId, parentTaskRunExternalId, desiredWorkerLabels } = opts, rest = __rest(opts, ["additionalMetadata", "parentStepRunId", "parentTaskRunExternalId", "desiredWorkerLabels"]);
-                const request = Object.assign(Object.assign({ name: computedName, input: inputStr }, rest), { 
-                    // API expects `parentTaskRunExternalId`; accept old names as aliases.
-                    parentTaskRunExternalId: parentTaskRunExternalId !== null && parentTaskRunExternalId !== void 0 ? parentTaskRunExternalId : parentStepRunId, additionalMetadata: additionalMetadata ? JSON.stringify(additionalMetadata) : undefined, priority: opts.priority, desiredWorkerLabels: desiredWorkerLabels
-                        ? convertDesiredWorkerLabels(desiredWorkerLabels)
-                        : {} });
-                const resp = yield (0, retrier_1.retrier)(() => __awaiter(this, void 0, void 0, function* () { return this.workflowsGrpc.triggerWorkflow(request); }), this.logger, Object.assign(Object.assign({}, this.config.retrier), { shouldRetry: (e) => !isAlreadyExists(e) }));
+                const request = (0, trigger_request_1.buildTriggerWorkflowRequest)(workflowName, input, options, this.config.namespace);
+                const resp = yield (0, retrier_1.retrier)(() => __awaiter(this, void 0, void 0, function* () { return this.workflowsGrpc.triggerWorkflow(request); }), this.logger, Object.assign(Object.assign({}, this.config.retrier), { shouldRetry: (e) => !(0, trigger_request_1.isAlreadyExists)(e) }));
                 const id = resp.workflowRunId;
                 const ref = new workflow_run_ref_1.default(id, this.listenerClient, this.runs, options === null || options === void 0 ? void 0 : options.parentId, options === null || options === void 0 ? void 0 : options._standaloneTaskName);
                 yield ref.getWorkflowRunId();
                 return ref;
             }
             catch (e) {
-                if (isAlreadyExists(e)) {
-                    throw new idempotency_collision_error_1.IdempotencyCollisionError(extractExistingRunId(e));
+                if ((0, trigger_request_1.isAlreadyExists)(e)) {
+                    throw new idempotency_collision_error_1.IdempotencyCollisionError((0, trigger_request_1.extractExistingRunId)(e));
                 }
                 throw new hatchet_error_1.default(e instanceof Error ? e.message : String(e));
             }
@@ -147,17 +94,7 @@ class AdminClient {
         return __awaiter(this, arguments, void 0, function* (workflowRuns, batchSize = 500) {
             var _a;
             // Prepare workflows to be triggered in bulk
-            const workflowRequests = workflowRuns.map(({ workflowName, input, options }) => {
-                const computedName = (0, apply_namespace_1.applyNamespace)(workflowName, this.config.namespace).toLowerCase();
-                const inputStr = JSON.stringify(input);
-                const opts = options !== null && options !== void 0 ? options : {};
-                const { additionalMetadata, parentStepRunId, parentTaskRunExternalId, desiredWorkerLabels } = opts, rest = __rest(opts, ["additionalMetadata", "parentStepRunId", "parentTaskRunExternalId", "desiredWorkerLabels"]);
-                return Object.assign(Object.assign({ name: computedName, input: inputStr }, rest), { 
-                    // API expects `parentTaskRunExternalId`; accept old names as aliases.
-                    parentTaskRunExternalId: parentTaskRunExternalId !== null && parentTaskRunExternalId !== void 0 ? parentTaskRunExternalId : parentStepRunId, additionalMetadata: additionalMetadata ? JSON.stringify(additionalMetadata) : undefined, desiredWorkerLabels: desiredWorkerLabels
-                        ? convertDesiredWorkerLabels(desiredWorkerLabels)
-                        : {} });
-            });
+            const workflowRequests = workflowRuns.map(({ workflowName, input, options }) => (0, trigger_request_1.buildTriggerWorkflowRequest)(workflowName, input, options, this.config.namespace));
             const batches = (0, batch_1.batch)(workflowRequests, batchSize, (_a = this.config.grpc_max_send_message_length) !== null && _a !== void 0 ? _a : 4 * 1024 * 1024);
             this.logger.debug(`batching ${batches.length} batches`);
             try {
@@ -168,7 +105,7 @@ class AdminClient {
                         workflows: payloads,
                     });
                     // Call the bulk trigger workflow method for this batch
-                    const bulkTriggerWorkflowResponse = yield (0, retrier_1.retrier)(() => __awaiter(this, void 0, void 0, function* () { return this.workflowsGrpc.bulkTriggerWorkflow(request); }), this.logger, Object.assign(Object.assign({}, this.config.retrier), { shouldRetry: (e) => !isAlreadyExists(e) }));
+                    const bulkTriggerWorkflowResponse = yield (0, retrier_1.retrier)(() => __awaiter(this, void 0, void 0, function* () { return this.workflowsGrpc.bulkTriggerWorkflow(request); }), this.logger, Object.assign(Object.assign({}, this.config.retrier), { shouldRetry: (e) => !(0, trigger_request_1.isAlreadyExists)(e) }));
                     this.logger.debug(`batch ${batchIndex + 1} of ${batches.length}`);
                     // Map the results back to their original indices
                     const batchResults = bulkTriggerWorkflowResponse.workflowRunIds.map((resp, index) => {
@@ -181,8 +118,8 @@ class AdminClient {
                 return results;
             }
             catch (e) {
-                if (isAlreadyExists(e)) {
-                    const collision = extractBulkTriggerCollision(e);
+                if ((0, trigger_request_1.isAlreadyExists)(e)) {
+                    const collision = (0, trigger_request_1.extractBulkTriggerCollision)(e);
                     if (collision)
                         throw collision;
                 }

package/v1/client/client.d.ts

@@ -13,12 +13,13 @@ import { DispatcherClient } from '../../clients/dispatcher/dispatcher-client';
 import { Logger } from '../../util/logger';
 import { RunListenerClient } from '../../clients/listeners/run-listener/child-listener-client';
 import { DurableListenerClient } from '../../clients/listeners/durable-listener/durable-listener-client';
+import { type Transport } from '../../clients/transport';
 import { CreateTaskWorkflowOpts, CreateWorkflowOpts, RunOpts, BaseWorkflowDeclaration, WorkflowDeclaration, TaskWorkflowDeclaration, CreateDurableTaskWorkflowOpts, CreateBatchTaskWorkflowOpts } from '../declaration';
 import { BatchTaskFn } from '../task';
 import type { LegacyWorkflow } from '../../legacy/legacy-transformer';
 import { IHatchetClient } from './client.interface';
 import { CreateWorkerOpts, Worker } from './worker/worker';
-import { CELClient, CronClient, FiltersClient, LogsClient, MetricsClient, RatelimitsClient, RunsClient, ScheduleClient, TenantClient, WebhooksClient, WorkersClient, WorkflowsClient } from './features';
+import { CELClient, CronClient, FiltersClient, LogsClient, MetricsClient, RatelimitsClient, RunsClient, ScheduleClient, StreamsClient, TenantClient, WebhooksClient, WorkersClient, WorkflowsClient } from './features';
 import { InputType, OutputType, UnknownInputType, StrictWorkflowOutputType, Resolved } from '../types';
 import { AdminClient } from './admin';
 import { DurableContext } from './worker/context';
@@ -241,6 +242,11 @@ export declare class HatchetClient<GlobalInput extends Record<string, any> = {},
      * @internal
      */
     get listener(): RunListenerClient;
+    /**
+     * The Connect transport the client's unary RPCs go through
+     * @internal
+     */
+    get transport(): Transport;
     /**
      * @deprecated use client.events instead
      * @hidden
@@ -288,6 +294,13 @@ export declare class HatchetClient<GlobalInput extends Record<string, any> = {},
      * @returns A runs client instance
      */
     get runs(): RunsClient;
+    private _streams;
+    /**
+     * Get the streams client for publishing to and reading from durable,
+     * topic-based streams
+     * @returns A streams client instance
+     */
+    get streams(): StreamsClient;
     private _workflows;
     /**
      * Get the workflows client for creating and managing workflows

package/v1/client/client.js

@@ -321,6 +321,13 @@ class HatchetClient {
     get listener() {
         return this._listener;
     }
+    /**
+     * The Connect transport the client's unary RPCs go through
+     * @internal
+     */
+    get transport() {
+        return this._transport;
+    }
     /**
      * @deprecated use client.events instead
      * @hidden
@@ -398,6 +405,17 @@ class HatchetClient {
         }
         return this._runs;
     }
+    /**
+     * Get the streams client for publishing to and reading from durable,
+     * topic-based streams
+     * @returns A streams client instance
+     */
+    get streams() {
+        if (!this._streams) {
+            this._streams = new features_1.StreamsClient(this);
+        }
+        return this._streams;
+    }
     /**
      * Get the workflows client for creating and managing workflows
      * @returns A workflows client instance

package/v1/client/features/index.d.ts

@@ -10,3 +10,4 @@ export * from './filters';
 export * from './tenant';
 export * from './webhooks';
 export * from './cel';
+export * from './streams';

package/v1/client/features/index.js

@@ -26,3 +26,4 @@ __exportStar(require("./filters"), exports);
 __exportStar(require("./tenant"), exports);
 __exportStar(require("./webhooks"), exports);
 __exportStar(require("./cel"), exports);
+__exportStar(require("./streams"), exports);

package/v1/client/features/runs.d.ts

@@ -1,32 +1,13 @@
 import WorkflowRunRef from '../../../util/workflow-run-ref';
-import { V1TaskStatus } from '../../../clients/rest/generated/data-contracts';
 import { RunListenerClient } from '../../../clients/listeners/run-listener/child-listener-client';
 import { WorkflowsClient } from './workflows';
 import { HatchetClient } from '../client';
-import { runStatusToJSON } from '../../../protoc/v1/workflows';
-export type RunDetail = {
-    status: V1TaskStatus;
-    done: boolean;
-    input: unknown;
-    additionalMetadata: unknown;
-    isEvicted: boolean;
-    taskRuns: Record<string, TaskRunDetail>;
-};
-export type TaskRunDetail = {
-    externalId: string;
-    readableId: string;
-    status: V1TaskStatus;
-    output: unknown;
-    error?: string;
-    isEvicted: boolean;
-};
+import { runStatusToJSON } from '../../../core/run-detail';
+import type { RunDetail, RunFilterBase, TaskRunDetail } from '../../../core/types';
+export type { RunDetail, TaskRunDetail };
 export { runStatusToJSON };
-export type RunFilter = {
-    since?: Date;
-    until?: Date;
-    statuses?: V1TaskStatus[];
+export type RunFilter = RunFilterBase & {
     workflowNames?: string[];
-    additionalMetadata?: Record<string, string>;
 };
 export type CancelRunOpts = {
     ids?: string[];
@@ -90,10 +71,11 @@ export declare class RunsClient {
     tenantId: string;
     workflows: WorkflowsClient;
     listener: RunListenerClient;
-    private _config;
-    private _adminGrpc;
+    private _transport;
+    private _adminRpc;
     constructor(client: HatchetClient);
-    private get adminGrpc();
+    /** The v1 admin RPCs on the client's Connect transport, the same path the core client uses. */
+    private get adminRpc();
     /**
      * Gets a task or workflow run by its ID.
      * @param run - The ID of the run to get.
@@ -105,7 +87,7 @@ export declare class RunsClient {
      * @param run - The ID of the run to get the status of.
      * @returns A promise that resolves to the status of the run.
      */
-    get_status<T = any>(run: string | WorkflowRunRef<T>): Promise<V1TaskStatus>;
+    get_status<T = any>(run: string | WorkflowRunRef<T>): Promise<import("../../../clients/rest/generated/data-contracts").V1TaskStatus>;
     /**
      * Gets run details
      * @param run - The workflow run ID (string) or a WorkflowRunRef.

package/v1/client/features/runs.js

@@ -34,55 +34,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RunsClient = exports.runStatusToJSON = void 0;
 const workflow_run_ref_1 = __importDefault(require("../../../util/workflow-run-ref"));
-const data_contracts_1 = require("../../../clients/rest/generated/data-contracts");
 const child_listener_client_1 = require("../../../clients/listeners/run-listener/child-listener-client");
-const workflows_1 = require("../../../protoc/v1/workflows");
-Object.defineProperty(exports, "runStatusToJSON", { enumerable: true, get: function () { return workflows_1.runStatusToJSON; } });
-const grpc_helpers_1 = require("../../../util/grpc-helpers");
-// EVICTED is not in V1TaskStatus; treat as RUNNING per the proto comment.
-const PROTO_STATUS_MAP = {
-    [workflows_1.RunStatus.QUEUED]: data_contracts_1.V1TaskStatus.QUEUED,
-    [workflows_1.RunStatus.RUNNING]: data_contracts_1.V1TaskStatus.RUNNING,
-    [workflows_1.RunStatus.COMPLETED]: data_contracts_1.V1TaskStatus.COMPLETED,
-    [workflows_1.RunStatus.FAILED]: data_contracts_1.V1TaskStatus.FAILED,
-    [workflows_1.RunStatus.CANCELLED]: data_contracts_1.V1TaskStatus.CANCELLED,
-    [workflows_1.RunStatus.EVICTED]: data_contracts_1.V1TaskStatus.RUNNING,
-    [workflows_1.RunStatus.UNRECOGNIZED]: data_contracts_1.V1TaskStatus.RUNNING,
-};
-function decodeBytes(b) {
-    if (!(b === null || b === void 0 ? void 0 : b.length))
-        return null;
-    try {
-        return JSON.parse(new TextDecoder().decode(b));
-    }
-    catch (_a) {
-        return null;
-    }
-}
-function toRunDetail(raw) {
-    var _a;
-    return {
-        status: (_a = PROTO_STATUS_MAP[raw.status]) !== null && _a !== void 0 ? _a : data_contracts_1.V1TaskStatus.RUNNING,
-        done: raw.done,
-        input: decodeBytes(raw.input),
-        additionalMetadata: decodeBytes(raw.additionalMetadata),
-        isEvicted: raw.isEvicted,
-        taskRuns: Object.fromEntries(Object.entries(raw.taskRuns).map(([id, tr]) => {
-            var _a;
-            return [
-                id,
-                {
-                    externalId: tr.externalId,
-                    readableId: tr.readableId,
-                    status: (_a = PROTO_STATUS_MAP[tr.status]) !== null && _a !== void 0 ? _a : data_contracts_1.V1TaskStatus.RUNNING,
-                    output: decodeBytes(tr.output),
-                    error: tr.error,
-                    isEvicted: tr.isEvicted,
-                },
-            ];
-        })),
-    };
-}
+const rpc_1 = require("../../../clients/admin/rpc");
+const run_detail_1 = require("../../../core/run-detail");
+Object.defineProperty(exports, "runStatusToJSON", { enumerable: true, get: function () { return run_detail_1.runStatusToJSON; } });
 /**
  * The runs client is a client for interacting with task and workflow runs within Hatchet.
  */
@@ -92,14 +47,14 @@ class RunsClient {
         this.tenantId = client.tenantId;
         this.workflows = client.workflows;
         this.listener = client._listener;
-        this._config = client.config;
+        this._transport = client.transport;
     }
-    get adminGrpc() {
-        if (!this._adminGrpc) {
-            const { client } = (0, grpc_helpers_1.createGrpcClient)(this._config, workflows_1.AdminServiceDefinition);
-            this._adminGrpc = client;
+    /** The v1 admin RPCs on the client's Connect transport, the same path the core client uses. */
+    get adminRpc() {
+        if (!this._adminRpc) {
+            this._adminRpc = (0, rpc_1.createV1AdminRpc)(this._transport);
         }
-        return this._adminGrpc;
+        return this._adminRpc;
     }
     /**
      * Gets a task or workflow run by its ID.
@@ -133,7 +88,7 @@ class RunsClient {
     getDetails(run) {
         return __awaiter(this, void 0, void 0, function* () {
             const runId = typeof run === 'string' ? run : yield run.getWorkflowRunId();
-            return toRunDetail(yield this.adminGrpc.getRunDetails({ externalId: runId }));
+            return (0, run_detail_1.toRunDetail)(yield this.adminRpc.getRunDetails({ externalId: runId }));
         });
     }
     /**

package/v1/client/features/streams.d.ts

@@ -0,0 +1,47 @@
+import { HatchetClient } from '../client';
+export type StreamEvent = {
+    /** the message payload */
+    payload: Uint8Array;
+    /** resumes events() right after this event */
+    cursor: string;
+    /** when the message was stored */
+    createdAt?: Date;
+};
+export type StreamCallOptions = {
+    namespace?: string;
+    cursor?: string;
+    /** ends an events() iteration cleanly, without throwing */
+    signal?: AbortSignal;
+};
+/**
+ * StreamsClient publishes to and reads from durable topics. Unlike
+ * `runs.subscribeToStream`, topics are stored, independent of any run, and
+ * readers can resume from a cursor.
+ */
+export declare class StreamsClient {
+    private _config;
+    private _grpc;
+    private producers;
+    private publishChains;
+    constructor(client: HatchetClient);
+    private get grpc();
+    private publishOrdered;
+    /**
+     * Resolves once the message is stored. A client's messages to a topic are
+     * delivered in the order publish() was called.
+     * @param topic - the topic to publish to
+     * @param message - the message payload
+     * @param options - optional namespace override
+     */
+    publish(topic: string, message: Uint8Array | string, options?: StreamCallOptions): Promise<void>;
+    /**
+     * Yields topic's messages after options.cursor, or from the oldest retained.
+     * If the connection drops, it resubscribes from the last message yielded, so
+     * nothing is skipped or repeated. Ends when the server hangs up an idle
+     * subscription, options.signal aborts, or the caller stops iterating; throws
+     * on errors a retry can't fix, such as an expired cursor.
+     * @param topic - the topic to read from
+     * @param options - optional namespace override, resume cursor, and abort signal
+     */
+    events(topic: string, options?: StreamCallOptions): AsyncIterable<StreamEvent>;
+}

package/v1/client/features/streams.js

@@ -0,0 +1,210 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamsClient = void 0;
+const crypto_1 = require("crypto");
+const nice_grpc_1 = require("nice-grpc");
+const grpc_helpers_1 = require("../../../util/grpc-helpers");
+const grpc_error_1 = require("../../../util/grpc-error");
+const sleep_1 = __importDefault(require("../../../util/sleep"));
+const streams_1 = require("../../../protoc/v1/streams");
+// the server stored nothing, so the seq is unused
+function publishRejectedBeforeStoring(err) {
+    const code = (0, grpc_error_1.getGrpcErrorCode)(err);
+    return (code === nice_grpc_1.Status.INVALID_ARGUMENT ||
+        code === nice_grpc_1.Status.RESOURCE_EXHAUSTED ||
+        code === nice_grpc_1.Status.UNAUTHENTICATED ||
+        code === nice_grpc_1.Status.PERMISSION_DENIED);
+}
+// retrying a subscribe that failed with these can't succeed
+const permanentSubscribeErrors = new Set([
+    nice_grpc_1.Status.INVALID_ARGUMENT,
+    nice_grpc_1.Status.PERMISSION_DENIED,
+    nice_grpc_1.Status.UNAUTHENTICATED,
+    nice_grpc_1.Status.OUT_OF_RANGE,
+    nice_grpc_1.Status.FAILED_PRECONDITION,
+    nice_grpc_1.Status.NOT_FOUND,
+]);
+const resubscribeMinDelayMs = 250;
+const resubscribeMaxDelayMs = 10000;
+function shouldResubscribe(err, attempt) {
+    const code = (0, grpc_error_1.getGrpcErrorCode)(err);
+    if (code === undefined || permanentSubscribeErrors.has(code)) {
+        return false;
+    }
+    // proxies answer 404 while an engine restarts, but on a first attempt it means no streams support
+    if (code === nice_grpc_1.Status.UNIMPLEMENTED) {
+        return attempt > 0;
+    }
+    return true;
+}
+/**
+ * StreamsClient publishes to and reads from durable topics. Unlike
+ * `runs.subscribeToStream`, topics are stored, independent of any run, and
+ * readers can resume from a cursor.
+ */
+class StreamsClient {
+    constructor(client) {
+        // per (namespace, topic); seq only advances after a publish succeeds
+        this.producers = new Map();
+        // serializes publishes per (namespace, topic) so two never share a seq; the
+        // stored promise always resolves, so one failure doesn't block later calls
+        this.publishChains = new Map();
+        this._config = client.config;
+    }
+    get grpc() {
+        if (!this._grpc) {
+            const { client } = (0, grpc_helpers_1.createGrpcClient)(this._config, streams_1.V1StreamsDefinition);
+            this._grpc = client;
+        }
+        return this._grpc;
+    }
+    publishOrdered(key_1, namespace_1, topic_1, payload_1) {
+        return __awaiter(this, arguments, void 0, function* (key, namespace, topic, payload, retryGap = true) {
+            let producer = this.producers.get(key);
+            if (!producer) {
+                producer = { producerId: (0, crypto_1.randomUUID)(), seq: 0 };
+                this.producers.set(key, producer);
+            }
+            try {
+                yield this.grpc.publish({
+                    namespace,
+                    topic,
+                    payload,
+                    producerId: producer.producerId,
+                    producerSeq: producer.seq,
+                });
+            }
+            catch (err) {
+                // it may still land, and a different payload under its seq would be dropped as a duplicate
+                if (!publishRejectedBeforeStoring(err)) {
+                    this.producers.set(key, { producerId: (0, crypto_1.randomUUID)(), seq: 0 });
+                }
+                // a gap stored nothing (e.g. the watermark passed cursor retention), so resend as the new producer
+                if (retryGap && (0, grpc_error_1.getGrpcErrorCode)(err) === nice_grpc_1.Status.FAILED_PRECONDITION) {
+                    return this.publishOrdered(key, namespace, topic, payload, false);
+                }
+                throw err;
+            }
+            producer.seq += 1;
+        });
+    }
+    /**
+     * Resolves once the message is stored. A client's messages to a topic are
+     * delivered in the order publish() was called.
+     * @param topic - the topic to publish to
+     * @param message - the message payload
+     * @param options - optional namespace override
+     */
+    publish(topic, message, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const payload = typeof message === 'string' ? new TextEncoder().encode(message) : message;
+            const namespace = (_a = options === null || options === void 0 ? void 0 : options.namespace) !== null && _a !== void 0 ? _a : '';
+            const key = `${namespace}\u0000${topic}`;
+            const previous = (_b = this.publishChains.get(key)) !== null && _b !== void 0 ? _b : Promise.resolve();
+            const publishPromise = previous.then(() => this.publishOrdered(key, namespace, topic, payload));
+            this.publishChains.set(key, publishPromise.catch(() => { }));
+            return publishPromise;
+        });
+    }
+    /**
+     * Yields topic's messages after options.cursor, or from the oldest retained.
+     * If the connection drops, it resubscribes from the last message yielded, so
+     * nothing is skipped or repeated. Ends when the server hangs up an idle
+     * subscription, options.signal aborts, or the caller stops iterating; throws
+     * on errors a retry can't fix, such as an expired cursor.
+     * @param topic - the topic to read from
+     * @param options - optional namespace override, resume cursor, and abort signal
+     */
+    events(topic, options) {
+        return __asyncGenerator(this, arguments, function* events_1() {
+            var _a, e_1, _b, _c;
+            var _d;
+            const namespace = (_d = options === null || options === void 0 ? void 0 : options.namespace) !== null && _d !== void 0 ? _d : '';
+            const signal = options === null || options === void 0 ? void 0 : options.signal;
+            let { cursor } = options !== null && options !== void 0 ? options : {};
+            let failures = 0;
+            for (let attempt = 0;; attempt += 1) {
+                try {
+                    const stream = this.grpc.subscribe({ namespace, topic, cursor }, { signal });
+                    try {
+                        for (var _e = true, stream_1 = (e_1 = void 0, __asyncValues(stream)), stream_1_1; stream_1_1 = yield __await(stream_1.next()), _a = stream_1_1.done, !_a; _e = true) {
+                            _c = stream_1_1.value;
+                            _e = false;
+                            const msg = _c;
+                            if (msg.hangup) {
+                                return yield __await(void 0);
+                            }
+                            failures = 0;
+                            for (const entry of msg.entries) {
+                                ({ cursor } = entry);
+                                yield yield __await({
+                                    payload: entry.payload,
+                                    cursor: entry.cursor,
+                                    createdAt: entry.createdAt,
+                                });
+                            }
+                        }
+                    }
+                    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                    finally {
+                        try {
+                            if (!_e && !_a && (_b = stream_1.return)) yield __await(_b.call(stream_1));
+                        }
+                        finally { if (e_1) throw e_1.error; }
+                    }
+                    // ending without a hangup means the engine went away, e.g. it is shutting down
+                }
+                catch (err) {
+                    if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+                        return yield __await(void 0);
+                    }
+                    if (!shouldResubscribe(err, attempt)) {
+                        throw err;
+                    }
+                }
+                const delayMs = Math.min(resubscribeMinDelayMs * 2 ** failures, resubscribeMaxDelayMs);
+                failures += 1;
+                try {
+                    yield __await((0, sleep_1.default)(delayMs * (0.5 + Math.random() / 2), signal));
+                }
+                catch (_f) {
+                    return yield __await(void 0);
+                }
+            }
+        });
+    }
+}
+exports.StreamsClient = StreamsClient;

package/v1/examples/durable-streams/publish-latency.d.ts

@@ -0,0 +1,15 @@
+import { HatchetClient } from '../..';
+export type PublishLatencyStats = {
+    count: number;
+    avgMs: number;
+    p50Ms: number;
+    p99Ms: number;
+    maxMs: number;
+    throughputPerSec: number;
+};
+/**
+ * Times `count` sequential publishes, after `warmupCount` unmeasured ones
+ * absorb connection setup and topic creation.
+ */
+export declare function measurePublishLatency(hatchet: HatchetClient, topic: string, payload: Uint8Array | string, count: number, warmupCount?: number): Promise<PublishLatencyStats>;
+export declare function formatPublishLatency(stats: PublishLatencyStats): string;