@temporalio/nexus 1.13.0

package/LICENSE.md

@@ -0,0 +1,23 @@
+Temporal TypeScript SDK
+
+MIT License
+
+Copyright (c) 2021 Temporal Technologies Inc. All Rights Reserved
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,8 @@
+# `@temporalio/nexus`
+
+[![NPM](https://img.shields.io/npm/v/@temporalio/nexus?style=for-the-badge)](https://www.npmjs.com/package/@temporalio/nexus)
+
+Part of [Temporal](https://temporal.io)'s [TypeScript SDK](https://docs.temporal.io/typescript/introduction/).
+
+- [API reference](https://typescript.temporal.io/api/namespaces/nexus)
+- [Sample projects](https://github.com/temporalio/samples-typescript)

package/lib/context.d.ts

@@ -0,0 +1,48 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { Logger, MetricMeter } from '@temporalio/common';
+import { Client } from '@temporalio/client';
+export declare const asyncLocalStorage: AsyncLocalStorage<HandlerContext>;
+export declare function getHandlerContext(): HandlerContext;
+/**
+ * Context used internally in the SDK to propagate information from the worker to the Temporal Nexus helpers.
+ *
+ * @internal
+ * @hidden
+ */
+export interface HandlerContext {
+    log: Logger;
+    metrics: MetricMeter;
+    client: Client;
+    namespace: string;
+    taskQueue: string;
+}
+/**
+ * A logger for use in Nexus Handler scope.
+ *
+ * This defaults to the `Runtime`'s Logger (see {@link Runtime.logger}). Attributes from the
+ * current Nexus handler context are automatically included as metadata on every log entries. An
+ * extra `sdkComponent` metadata attribute is also added, with value `nexus`; this can be used
+ * for fine-grained filtering of log entries further downstream.
+ *
+ * To customize log attributes, register a {@link nexus.NexusOutboundCallsInterceptor} that
+ * intercepts the `getLogAttributes()` method.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export declare const log: Logger;
+/**
+ * A metric meter for use in Nexus handler scope, with Nexus handler-specific tags.
+ *
+ * To add custom tags, register a {@link nexus.NexusOutboundCallsInterceptor} that
+ * intercepts the `getMetricTags()` method.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export declare const metricMeter: MetricMeter;
+/**
+ * Returns a client to be used in a Nexus Operation's context, this Client is powered by the same
+ * NativeConnection that the worker was created with.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export declare function getClient(): Client;

package/lib/context.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.metricMeter = exports.log = exports.asyncLocalStorage = void 0;
+exports.getHandlerContext = getHandlerContext;
+exports.getClient = getClient;
+const node_async_hooks_1 = require("node:async_hooks");
+// Context Storage /////////////////////////////////////////////////////////////////////////////////
+// Make it safe to use @temporalio/nexus with multiple versions installed.
+const asyncLocalStorageSymbol = Symbol.for('__temporal_nexus_context_storage__');
+if (!globalThis[asyncLocalStorageSymbol]) {
+    globalThis[asyncLocalStorageSymbol] = new node_async_hooks_1.AsyncLocalStorage();
+}
+exports.asyncLocalStorage = globalThis[asyncLocalStorageSymbol];
+function getHandlerContext() {
+    const ctx = exports.asyncLocalStorage.getStore();
+    if (ctx == null) {
+        throw new ReferenceError('Not in a Nexus handler context');
+    }
+    return ctx;
+}
+// Basic APIs //////////////////////////////////////////////////////////////////////////////////////
+/**
+ * A logger for use in Nexus Handler scope.
+ *
+ * This defaults to the `Runtime`'s Logger (see {@link Runtime.logger}). Attributes from the
+ * current Nexus handler context are automatically included as metadata on every log entries. An
+ * extra `sdkComponent` metadata attribute is also added, with value `nexus`; this can be used
+ * for fine-grained filtering of log entries further downstream.
+ *
+ * To customize log attributes, register a {@link nexus.NexusOutboundCallsInterceptor} that
+ * intercepts the `getLogAttributes()` method.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+exports.log = {
+    log(level, message, meta) {
+        return getHandlerContext().log.log(level, message, meta);
+    },
+    trace(message, meta) {
+        return getHandlerContext().log.trace(message, meta);
+    },
+    debug(message, meta) {
+        return getHandlerContext().log.debug(message, meta);
+    },
+    info(message, meta) {
+        return getHandlerContext().log.info(message, meta);
+    },
+    warn(message, meta) {
+        return getHandlerContext().log.warn(message, meta);
+    },
+    error(message, meta) {
+        return getHandlerContext().log.error(message, meta);
+    },
+};
+/**
+ * A metric meter for use in Nexus handler scope, with Nexus handler-specific tags.
+ *
+ * To add custom tags, register a {@link nexus.NexusOutboundCallsInterceptor} that
+ * intercepts the `getMetricTags()` method.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+exports.metricMeter = {
+    createCounter(name, unit, description) {
+        return getHandlerContext().metrics.createCounter(name, unit, description);
+    },
+    createHistogram(name, valueType = 'int', unit, description) {
+        return getHandlerContext().metrics.createHistogram(name, valueType, unit, description);
+    },
+    createGauge(name, valueType = 'int', unit, description) {
+        return getHandlerContext().metrics.createGauge(name, valueType, unit, description);
+    },
+    withTags(tags) {
+        return getHandlerContext().metrics.withTags(tags);
+    },
+};
+/**
+ * Returns a client to be used in a Nexus Operation's context, this Client is powered by the same
+ * NativeConnection that the worker was created with.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+function getClient() {
+    return getHandlerContext().client;
+}
+//# sourceMappingURL=context.js.map

package/lib/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":";;;AAaA,8CAMC;AAiFD,8BAEC;AAtGD,uDAAqD;AAIrD,oGAAoG;AAEpG,0EAA0E;AAC1E,MAAM,uBAAuB,GAAG,MAAM,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;AACjF,IAAI,CAAE,UAAkB,CAAC,uBAAuB,CAAC,EAAE,CAAC;IACjD,UAAkB,CAAC,uBAAuB,CAAC,GAAG,IAAI,oCAAiB,EAAkB,CAAC;AACzF,CAAC;AACY,QAAA,iBAAiB,GAAuC,UAAkB,CAAC,uBAAuB,CAAC,CAAC;AAEjH,SAAgB,iBAAiB;IAC/B,MAAM,GAAG,GAAG,yBAAiB,CAAC,QAAQ,EAAE,CAAC;IACzC,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;QAChB,MAAM,IAAI,cAAc,CAAC,gCAAgC,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAgBD,oGAAoG;AAEpG;;;;;;;;;;;;GAYG;AACU,QAAA,GAAG,GAAW;IACzB,GAAG,CAAC,KAAe,EAAE,OAAe,EAAE,IAAkB;QACtD,OAAO,iBAAiB,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAC3D,CAAC;IACD,KAAK,CAAC,OAAe,EAAE,IAAkB;QACvC,OAAO,iBAAiB,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACtD,CAAC;IACD,KAAK,CAAC,OAAe,EAAE,IAAkB;QACvC,OAAO,iBAAiB,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACtD,CAAC;IACD,IAAI,CAAC,OAAe,EAAE,IAAkB;QACtC,OAAO,iBAAiB,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,CAAC,OAAe,EAAE,IAAkB;QACtC,OAAO,iBAAiB,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACrD,CAAC;IACD,KAAK,CAAC,OAAe,EAAE,IAAkB;QACvC,OAAO,iBAAiB,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACtD,CAAC;CACF,CAAC;AAEF;;;;;;;GAOG;AACU,QAAA,WAAW,GAAgB;IACtC,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW;QACnC,OAAO,iBAAiB,EAAE,CAAC,OAAO,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;IAC5E,CAAC;IACD,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,KAAK,EAAE,IAAI,EAAE,WAAW;QACxD,OAAO,iBAAiB,EAAE,CAAC,OAAO,CAAC,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;IACzF,CAAC;IACD,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,KAAK,EAAE,IAAI,EAAE,WAAW;QACpD,OAAO,iBAAiB,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;IACrF,CAAC;IACD,QAAQ,CAAC,IAAI;QACX,OAAO,iBAAiB,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC;CACF,CAAC;AAEF;;;;;GAKG;AACH,SAAgB,SAAS;IACvB,OAAO,iBAAiB,EAAE,CAAC,MAAM,CAAC;AACpC,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export { log, getClient, metricMeter, } from './context';
+export { startWorkflow, WorkflowHandle, WorkflowRunOperationHandler, WorkflowRunOperationStartHandler, WorkflowStartOptions, } from './workflow-helpers';

package/lib/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkflowRunOperationHandler = exports.startWorkflow = exports.metricMeter = exports.getClient = exports.log = void 0;
+var context_1 = require("./context");
+//
+Object.defineProperty(exports, "log", { enumerable: true, get: function () { return context_1.log; } });
+Object.defineProperty(exports, "getClient", { enumerable: true, get: function () { return context_1.getClient; } });
+Object.defineProperty(exports, "metricMeter", { enumerable: true, get: function () { return context_1.metricMeter; } });
+var workflow_helpers_1 = require("./workflow-helpers");
+Object.defineProperty(exports, "startWorkflow", { enumerable: true, get: function () { return workflow_helpers_1.startWorkflow; } });
+Object.defineProperty(exports, "WorkflowRunOperationHandler", { enumerable: true, get: function () { return workflow_helpers_1.WorkflowRunOperationHandler; } });
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,qCAKmB;AAJjB,EAAE;AACF,8FAAA,GAAG,OAAA;AACH,oGAAA,SAAS,OAAA;AACT,sGAAA,WAAW,OAAA;AAGb,uDAM4B;AAL1B,iHAAA,aAAa,OAAA;AAEb,+HAAA,2BAA2B,OAAA"}

package/lib/link-converter.d.ts

@@ -0,0 +1,6 @@
+import { Link as NexusLink } from 'nexus-rpc';
+import { temporal } from '@temporalio/proto';
+type WorkflowEventLink = temporal.api.common.v1.Link.IWorkflowEvent;
+export declare function convertWorkflowEventLinkToNexusLink(we: WorkflowEventLink): NexusLink;
+export declare function convertNexusLinkToWorkflowEventLink(link: NexusLink): WorkflowEventLink;
+export {};

package/lib/link-converter.js

@@ -0,0 +1,134 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertWorkflowEventLinkToNexusLink = convertWorkflowEventLinkToNexusLink;
+exports.convertNexusLinkToWorkflowEventLink = convertNexusLinkToWorkflowEventLink;
+const long_1 = __importDefault(require("long"));
+const proto_1 = require("@temporalio/proto");
+const { EventType } = proto_1.temporal.api.enums.v1;
+const LINK_EVENT_ID_PARAM = 'eventID';
+const LINK_EVENT_TYPE_PARAM = 'eventType';
+const LINK_REQUEST_ID_PARAM = 'requestID';
+const LINK_REFERENCE_TYPE_KEY = 'referenceType';
+const EVENT_REFERENCE_TYPE = 'EventReference';
+const REQUEST_ID_REFERENCE_TYPE = 'RequestIdReference';
+// fullName isn't part of the generated typed unfortunately.
+const WORKFLOW_EVENT_TYPE = proto_1.temporal.api.common.v1.Link.WorkflowEvent.fullName.slice(1);
+function convertWorkflowEventLinkToNexusLink(we) {
+    if (!we.namespace || !we.workflowId || !we.runId) {
+        throw new TypeError('Missing required fields: namespace, workflowId, or runId');
+    }
+    const url = new URL(`temporal:///namespaces/${encodeURIComponent(we.namespace)}/workflows/${encodeURIComponent(we.workflowId)}/${encodeURIComponent(we.runId)}/history`);
+    if (we.eventRef != null) {
+        url.search = convertLinkWorkflowEventEventReferenceToURLQuery(we.eventRef);
+    }
+    else if (we.requestIdRef != null) {
+        url.search = convertLinkWorkflowEventRequestIdReferenceToURLQuery(we.requestIdRef);
+    }
+    return {
+        url,
+        type: WORKFLOW_EVENT_TYPE,
+    };
+}
+function convertNexusLinkToWorkflowEventLink(link) {
+    if (link.url.protocol !== 'temporal:') {
+        throw new TypeError(`Invalid URL scheme: ${link.url}, expected 'temporal:', got '${link.url.protocol}'`);
+    }
+    // /namespaces/:namespace/workflows/:workflowId/:runId/history
+    const parts = link.url.pathname.split('/');
+    if (parts.length !== 7 || parts[1] !== 'namespaces' || parts[3] !== 'workflows' || parts[6] !== 'history') {
+        throw new TypeError(`Invalid URL path: ${link.url}`);
+    }
+    const namespace = decodeURIComponent(parts[2]);
+    const workflowId = decodeURIComponent(parts[4]);
+    const runId = decodeURIComponent(parts[5]);
+    const query = link.url.searchParams;
+    const refType = query.get(LINK_REFERENCE_TYPE_KEY);
+    const workflowEventLink = {
+        namespace,
+        workflowId,
+        runId,
+    };
+    switch (refType) {
+        case EVENT_REFERENCE_TYPE:
+            workflowEventLink.eventRef = convertURLQueryToLinkWorkflowEventEventReference(query);
+            break;
+        case REQUEST_ID_REFERENCE_TYPE:
+            workflowEventLink.requestIdRef = convertURLQueryToLinkWorkflowEventRequestIdReference(query);
+            break;
+        default:
+            throw new TypeError(`Unknown reference type: ${refType}`);
+    }
+    return workflowEventLink;
+}
+function convertLinkWorkflowEventEventReferenceToURLQuery(eventRef) {
+    const params = new URLSearchParams();
+    params.set(LINK_REFERENCE_TYPE_KEY, EVENT_REFERENCE_TYPE);
+    if (eventRef.eventId != null) {
+        const eventId = eventRef.eventId.toNumber();
+        if (eventId > 0) {
+            params.set(LINK_EVENT_ID_PARAM, `${eventId}`);
+        }
+    }
+    if (eventRef.eventType != null) {
+        const eventType = constantCaseToPascalCase(EventType[eventRef.eventType].replace('EVENT_TYPE_', ''));
+        params.set(LINK_EVENT_TYPE_PARAM, eventType);
+    }
+    return params.toString();
+}
+function convertURLQueryToLinkWorkflowEventEventReference(query) {
+    let eventId = 0;
+    const eventIdParam = query.get(LINK_EVENT_ID_PARAM);
+    if (eventIdParam && /^\d+$/.test(eventIdParam)) {
+        eventId = parseInt(eventIdParam, 10);
+    }
+    const eventTypeParam = query.get(LINK_EVENT_TYPE_PARAM);
+    if (!eventTypeParam) {
+        throw new TypeError(`Missing eventType parameter`);
+    }
+    const eventType = EventType[normalizeEnumValue(eventTypeParam, 'EVENT_TYPE')];
+    if (eventType == null) {
+        throw new TypeError(`Unknown eventType parameter: ${eventTypeParam}`);
+    }
+    return { eventId: long_1.default.fromNumber(eventId), eventType };
+}
+function convertLinkWorkflowEventRequestIdReferenceToURLQuery(requestIdRef) {
+    const params = new URLSearchParams();
+    params.set(LINK_REFERENCE_TYPE_KEY, REQUEST_ID_REFERENCE_TYPE);
+    if (requestIdRef.requestId != null) {
+        params.set(LINK_REQUEST_ID_PARAM, requestIdRef.requestId);
+    }
+    if (requestIdRef.eventType != null) {
+        const eventType = constantCaseToPascalCase(EventType[requestIdRef.eventType].replace('EVENT_TYPE_', ''));
+        params.set(LINK_EVENT_TYPE_PARAM, eventType);
+    }
+    return params.toString();
+}
+function convertURLQueryToLinkWorkflowEventRequestIdReference(query) {
+    const requestId = query.get(LINK_REQUEST_ID_PARAM);
+    const eventTypeParam = query.get(LINK_EVENT_TYPE_PARAM);
+    if (!eventTypeParam) {
+        throw new TypeError(`Missing eventType parameter`);
+    }
+    const eventType = EventType[normalizeEnumValue(eventTypeParam, 'EVENT_TYPE')];
+    if (eventType == null) {
+        throw new TypeError(`Unknown eventType parameter: ${eventTypeParam}`);
+    }
+    return { requestId, eventType };
+}
+function normalizeEnumValue(value, prefix) {
+    value = pascalCaseToConstantCase(value);
+    if (!value.startsWith(prefix)) {
+        value = `${prefix}_${value}`;
+    }
+    return value;
+}
+function pascalCaseToConstantCase(s) {
+    return s.replace(/[^\b][A-Z]/g, (m) => `${m[0]}_${m[1]}`).toUpperCase();
+}
+function constantCaseToPascalCase(s) {
+    return s.replace(/[A-Z]+_?/g, (m) => `${m[0]}${m.slice(1).toLocaleLowerCase()}`.replace(/_/, ''));
+}
+//# sourceMappingURL=link-converter.js.map

package/lib/link-converter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-converter.js","sourceRoot":"","sources":["../src/link-converter.ts"],"names":[],"mappings":";;;;;AAoBA,kFAoBC;AAED,kFAkCC;AA5ED,gDAAwB;AAExB,6CAA6C;AAE7C,MAAM,EAAE,SAAS,EAAE,GAAG,gBAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;AAK5C,MAAM,mBAAmB,GAAG,SAAS,CAAC;AACtC,MAAM,qBAAqB,GAAG,WAAW,CAAC;AAC1C,MAAM,qBAAqB,GAAG,WAAW,CAAC;AAC1C,MAAM,uBAAuB,GAAG,eAAe,CAAC;AAEhD,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AAC9C,MAAM,yBAAyB,GAAG,oBAAoB,CAAC;AAEvD,4DAA4D;AAC5D,MAAM,mBAAmB,GAAY,gBAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,aAAqB,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEzG,SAAgB,mCAAmC,CAAC,EAAqB;IACvE,IAAI,CAAC,EAAE,CAAC,SAAS,IAAI,CAAC,EAAE,CAAC,UAAU,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;QACjD,MAAM,IAAI,SAAS,CAAC,0DAA0D,CAAC,CAAC;IAClF,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,GAAG,CACjB,0BAA0B,kBAAkB,CAAC,EAAE,CAAC,SAAS,CAAC,cAAc,kBAAkB,CACxF,EAAE,CAAC,UAAU,CACd,IAAI,kBAAkB,CAAC,EAAE,CAAC,KAAK,CAAC,UAAU,CAC5C,CAAC;IAEF,IAAI,EAAE,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAC;QACxB,GAAG,CAAC,MAAM,GAAG,gDAAgD,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC7E,CAAC;SAAM,IAAI,EAAE,CAAC,YAAY,IAAI,IAAI,EAAE,CAAC;QACnC,GAAG,CAAC,MAAM,GAAG,oDAAoD,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC;IACrF,CAAC;IAED,OAAO;QACL,GAAG;QACH,IAAI,EAAE,mBAAmB;KAC1B,CAAC;AACJ,CAAC;AAED,SAAgB,mCAAmC,CAAC,IAAe;IACjE,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,KAAK,WAAW,EAAE,CAAC;QACtC,MAAM,IAAI,SAAS,CAAC,uBAAuB,IAAI,CAAC,GAAG,gCAAgC,IAAI,CAAC,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC;IAC3G,CAAC;IAED,8DAA8D;IAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,YAAY,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,WAAW,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;QAC1G,MAAM,IAAI,SAAS,CAAC,qBAAqB,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,MAAM,SAAS,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,MAAM,UAAU,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAE3C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC;IACpC,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;IAEnD,MAAM,iBAAiB,GAAsB;QAC3C,SAAS;QACT,UAAU;QACV,KAAK;KACN,CAAC;IAEF,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,oBAAoB;YACvB,iBAAiB,CAAC,QAAQ,GAAG,gDAAgD,CAAC,KAAK,CAAC,CAAC;YACrF,MAAM;QACR,KAAK,yBAAyB;YAC5B,iBAAiB,CAAC,YAAY,GAAG,oDAAoD,CAAC,KAAK,CAAC,CAAC;YAC7F,MAAM;QACR;YACE,MAAM,IAAI,SAAS,CAAC,2BAA2B,OAAO,EAAE,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED,SAAS,gDAAgD,CAAC,QAAwB;IAChF,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,MAAM,CAAC,GAAG,CAAC,uBAAuB,EAAE,oBAAoB,CAAC,CAAC;IAC1D,IAAI,QAAQ,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QAC5C,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAChB,MAAM,CAAC,GAAG,CAAC,mBAAmB,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IACD,IAAI,QAAQ,CAAC,SAAS,IAAI,IAAI,EAAE,CAAC;QAC/B,MAAM,SAAS,GAAG,wBAAwB,CAAC,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,CAAC;QACrG,MAAM,CAAC,GAAG,CAAC,qBAAqB,EAAE,SAAS,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;AAC3B,CAAC;AAED,SAAS,gDAAgD,CAAC,KAAsB;IAC9E,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,MAAM,YAAY,GAAG,KAAK,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IACpD,IAAI,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;QAC/C,OAAO,GAAG,QAAQ,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IACvC,CAAC;IACD,MAAM,cAAc,GAAG,KAAK,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACxD,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,MAAM,IAAI,SAAS,CAAC,6BAA6B,CAAC,CAAC;IACrD,CAAC;IACD,MAAM,SAAS,GAAG,SAAS,CAAC,kBAAkB,CAAC,cAAc,EAAE,YAAY,CAA2B,CAAC,CAAC;IACxG,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;QACtB,MAAM,IAAI,SAAS,CAAC,gCAAgC,cAAc,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,cAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;AAC1D,CAAC;AAED,SAAS,oDAAoD,CAAC,YAAgC;IAC5F,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,MAAM,CAAC,GAAG,CAAC,uBAAuB,EAAE,yBAAyB,CAAC,CAAC;IAC/D,IAAI,YAAY,CAAC,SAAS,IAAI,IAAI,EAAE,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,qBAAqB,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IAC5D,CAAC;IACD,IAAI,YAAY,CAAC,SAAS,IAAI,IAAI,EAAE,CAAC;QACnC,MAAM,SAAS,GAAG,wBAAwB,CAAC,SAAS,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,CAAC;QACzG,MAAM,CAAC,GAAG,CAAC,qBAAqB,EAAE,SAAS,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;AAC3B,CAAC;AAED,SAAS,oDAAoD,CAAC,KAAsB;IAClF,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACnD,MAAM,cAAc,GAAG,KAAK,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACxD,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,MAAM,IAAI,SAAS,CAAC,6BAA6B,CAAC,CAAC;IACrD,CAAC;IACD,MAAM,SAAS,GAAG,SAAS,CAAC,kBAAkB,CAAC,cAAc,EAAE,YAAY,CAA2B,CAAC,CAAC;IACxG,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;QACtB,MAAM,IAAI,SAAS,CAAC,gCAAgC,cAAc,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;AAClC,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAa,EAAE,MAAc;IACvD,KAAK,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9B,KAAK,GAAG,GAAG,MAAM,IAAI,KAAK,EAAE,CAAC;IAC/B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,wBAAwB,CAAC,CAAS;IACzC,OAAO,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AAC1E,CAAC;AAED,SAAS,wBAAwB,CAAC,CAAS;IACzC,OAAO,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,iBAAiB,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;AACpG,CAAC"}

package/lib/token.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @internal
+ * @hidden
+ */
+export interface WorkflowRunOperationToken {
+    /**
+     * Version of the token, by default we assume we're on version 1, this field is not emitted as part of the output,
+     * it's only used to reject newer token versions on load.
+     */
+    v?: number;
+    /**
+     * Type of the Operation. Must be OPERATION_TOKEN_TYPE_WORKFLOW_RUN.
+     */
+    t: OperationTokenType;
+    /**
+     * Namespace of the workflow.
+     */
+    ns: string;
+    /**
+     * ID of the workflow.
+     */
+    wid: string;
+}
+/**
+ * OperationTokenType is used to identify the type of Operation token.
+ * Currently, we only have one type of Operation token: WorkflowRun.
+ */
+type OperationTokenType = (typeof OperationTokenType)[keyof typeof OperationTokenType];
+/**
+ * @internal
+ * @hidden
+ */
+declare const OperationTokenType: {
+    readonly WORKFLOW_RUN: 1;
+};
+/**
+ * Generate a workflow run Operation token.
+ */
+export declare function generateWorkflowRunOperationToken(namespace: string, workflowId: string): string;
+/**
+ * Load and validate a workflow run Operation token.
+ */
+export declare function loadWorkflowRunOperationToken(data: string): WorkflowRunOperationToken;
+export declare function base64URLEncodeNoPadding(str: string): string;
+export {};

package/lib/token.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateWorkflowRunOperationToken = generateWorkflowRunOperationToken;
+exports.loadWorkflowRunOperationToken = loadWorkflowRunOperationToken;
+exports.base64URLEncodeNoPadding = base64URLEncodeNoPadding;
+/**
+ * @internal
+ * @hidden
+ */
+const OperationTokenType = {
+    WORKFLOW_RUN: 1,
+};
+/**
+ * Generate a workflow run Operation token.
+ */
+function generateWorkflowRunOperationToken(namespace, workflowId) {
+    const token = {
+        t: OperationTokenType.WORKFLOW_RUN,
+        ns: namespace,
+        wid: workflowId,
+    };
+    return base64URLEncodeNoPadding(JSON.stringify(token));
+}
+/**
+ * Load and validate a workflow run Operation token.
+ */
+function loadWorkflowRunOperationToken(data) {
+    if (!data) {
+        throw new TypeError('invalid workflow run token: token is empty');
+    }
+    let decoded;
+    try {
+        decoded = base64URLDecodeNoPadding(data);
+    }
+    catch (err) {
+        throw new TypeError('failed to decode token', { cause: err });
+    }
+    let token;
+    try {
+        token = JSON.parse(decoded);
+    }
+    catch (err) {
+        throw new TypeError('failed to unmarshal workflow run Operation token', { cause: err });
+    }
+    if (token.t !== OperationTokenType.WORKFLOW_RUN) {
+        throw new TypeError(`invalid workflow token type: ${token.t}, expected: ${OperationTokenType.WORKFLOW_RUN}`);
+    }
+    if (token.v !== undefined && token.v !== 0) {
+        throw new TypeError('invalid workflow run token: "v" field should not be present');
+    }
+    if (!token.wid) {
+        throw new TypeError('invalid workflow run token: missing workflow ID (wid)');
+    }
+    return token;
+}
+// Exported for use in tests.
+function base64URLEncodeNoPadding(str) {
+    const base64 = Buffer.from(str).toString('base64url');
+    return base64.replace(/[=]+$/, '');
+}
+function base64URLDecodeNoPadding(str) {
+    // Validate the string contains only valid base64URL characters
+    if (!/^[A-Za-z0-9_-]*$/.test(str)) {
+        throw new TypeError('invalid base64URL encoded string: contains invalid characters');
+    }
+    const paddingLength = str.length % 4;
+    if (paddingLength > 0) {
+        str += '='.repeat(4 - paddingLength);
+    }
+    return Buffer.from(str, 'base64url').toString('utf-8');
+}
+//# sourceMappingURL=token.js.map

package/lib/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":";;AA4CA,8EAOC;AAKD,sEA8BC;AAGD,4DAGC;AA3DD;;;GAGG;AACH,MAAM,kBAAkB,GAAG;IACzB,YAAY,EAAE,CAAC;CACP,CAAC;AAEX;;GAEG;AACH,SAAgB,iCAAiC,CAAC,SAAiB,EAAE,UAAkB;IACrF,MAAM,KAAK,GAA8B;QACvC,CAAC,EAAE,kBAAkB,CAAC,YAAY;QAClC,EAAE,EAAE,SAAS;QACb,GAAG,EAAE,UAAU;KAChB,CAAC;IACF,OAAO,wBAAwB,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;GAEG;AACH,SAAgB,6BAA6B,CAAC,IAAY;IACxD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,SAAS,CAAC,4CAA4C,CAAC,CAAC;IACpE,CAAC;IAED,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,wBAAwB,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,SAAS,CAAC,wBAAwB,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,KAAgC,CAAC;IACrC,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,SAAS,CAAC,kDAAkD,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IAC1F,CAAC;IAED,IAAI,KAAK,CAAC,CAAC,KAAK,kBAAkB,CAAC,YAAY,EAAE,CAAC;QAChD,MAAM,IAAI,SAAS,CAAC,gCAAgC,KAAK,CAAC,CAAC,eAAe,kBAAkB,CAAC,YAAY,EAAE,CAAC,CAAC;IAC/G,CAAC;IACD,IAAI,KAAK,CAAC,CAAC,KAAK,SAAS,IAAI,KAAK,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,SAAS,CAAC,6DAA6D,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;QACf,MAAM,IAAI,SAAS,CAAC,uDAAuD,CAAC,CAAC;IAC/E,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,6BAA6B;AAC7B,SAAgB,wBAAwB,CAAC,GAAW;IAClD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IACtD,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACrC,CAAC;AAED,SAAS,wBAAwB,CAAC,GAAW;IAC3C,+DAA+D;IAC/D,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,SAAS,CAAC,+DAA+D,CAAC,CAAC;IACvF,CAAC;IAED,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IACrC,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;QACtB,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AACzD,CAAC"}

package/lib/workflow-helpers.d.ts

@@ -0,0 +1,65 @@
+import * as nexus from 'nexus-rpc';
+import { Workflow } from '@temporalio/common';
+import { Replace } from '@temporalio/common/lib/type-helpers';
+import { WorkflowStartOptions as ClientWorkflowStartOptions } from '@temporalio/client';
+declare const isNexusWorkflowHandle: unique symbol;
+/**
+ * A handle to a running workflow that is returned by the {@link startWorkflow} helper.
+ * This handle should be returned by {@link WorkflowRunOperationStartHandler} implementations.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export interface WorkflowHandle<_T> {
+    readonly workflowId: string;
+    readonly runId: string;
+    /**
+     * Virtual type brand to maintain a distinction between {@link WorkflowHandle} provided by the
+     * {@link startWorkflow} helper (which will have attached links, request ID, completion URL, etc)
+     * and the `WorkflowHandle` type returned by the {@link WorkflowClient.start}.
+     *
+     * @internal
+     * @hidden
+     *
+     * @experimental Nexus support in Temporal SDK is experimental.
+     */
+    readonly [isNexusWorkflowHandle]: typeof isNexusWorkflowHandle;
+}
+/**
+ * Options for starting a workflow using {@link startWorkflow}, this type is identical to the
+ * client's `WorkflowStartOptions` with the exception that `taskQueue` is optional and defaults
+ * to the current worker's task queue.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export type WorkflowStartOptions<T extends Workflow> = Replace<ClientWorkflowStartOptions<T>, {
+    taskQueue?: string;
+}>;
+/**
+ * Starts a workflow run for a {@link WorkflowRunOperationStartHandler}, linking the execution chain
+ * to a Nexus Operation (subsequent runs started from continue-as-new and retries). Automatically
+ * propagates the callback, request ID, and back and forward links from the Nexus options to the
+ * Workflow.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export declare function startWorkflow<T extends Workflow>(ctx: nexus.StartOperationContext, workflowTypeOrFunc: string | T, workflowOptions: WorkflowStartOptions<T>): Promise<WorkflowHandle<T>>;
+/**
+ * A handler function for the {@link WorkflowRunOperationHandler} constructor.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export type WorkflowRunOperationStartHandler<I, O> = (ctx: nexus.StartOperationContext, input: I) => Promise<WorkflowHandle<O>>;
+/**
+ * A Nexus Operation implementation that is backed by a Workflow run.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export declare class WorkflowRunOperationHandler<I, O> implements nexus.OperationHandler<I, O> {
+    readonly handler: WorkflowRunOperationStartHandler<I, O>;
+    constructor(handler: WorkflowRunOperationStartHandler<I, O>);
+    start(ctx: nexus.StartOperationContext, input: I): Promise<nexus.HandlerStartOperationResult<O>>;
+    getInfo(_ctx: nexus.GetOperationInfoContext, _token: string): Promise<nexus.OperationInfo>;
+    getResult(_ctx: nexus.GetOperationResultContext, _token: string): Promise<O>;
+    cancel(_ctx: nexus.CancelOperationContext, token: string): Promise<void>;
+}
+export {};

package/lib/workflow-helpers.js

@@ -0,0 +1,122 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkflowRunOperationHandler = void 0;
+exports.startWorkflow = startWorkflow;
+const nexus = __importStar(require("nexus-rpc"));
+const internal_1 = require("@temporalio/client/lib/internal");
+const token_1 = require("./token");
+const link_converter_1 = require("./link-converter");
+const context_1 = require("./context");
+/**
+ * Starts a workflow run for a {@link WorkflowRunOperationStartHandler}, linking the execution chain
+ * to a Nexus Operation (subsequent runs started from continue-as-new and retries). Automatically
+ * propagates the callback, request ID, and back and forward links from the Nexus options to the
+ * Workflow.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+async function startWorkflow(ctx, workflowTypeOrFunc, workflowOptions) {
+    const { client, taskQueue } = (0, context_1.getHandlerContext)();
+    const links = Array();
+    if (ctx.inboundLinks?.length > 0) {
+        for (const l of ctx.inboundLinks) {
+            try {
+                links.push({
+                    workflowEvent: (0, link_converter_1.convertNexusLinkToWorkflowEventLink)(l),
+                });
+            }
+            catch (error) {
+                context_1.log.warn('failed to convert Nexus link to Workflow event link', { error });
+            }
+        }
+    }
+    const internalOptions = {
+        links,
+        requestId: ctx.requestId,
+    };
+    internalOptions.onConflictOptions = {
+        attachLinks: true,
+        attachCompletionCallbacks: true,
+        attachRequestId: true,
+    };
+    if (ctx.callbackUrl) {
+        internalOptions.completionCallbacks = [
+            {
+                nexus: { url: ctx.callbackUrl, header: ctx.callbackHeaders },
+                links, // pass in links here as well for older servers, newer servers dedupe them.
+            },
+        ];
+    }
+    const { taskQueue: userSpecifiedTaskQueue, ...rest } = workflowOptions;
+    const startOptions = {
+        ...rest,
+        taskQueue: userSpecifiedTaskQueue || taskQueue,
+        [internal_1.InternalWorkflowStartOptionsSymbol]: internalOptions,
+    };
+    const handle = await client.workflow.start(workflowTypeOrFunc, startOptions);
+    if (internalOptions.backLink?.workflowEvent != null) {
+        try {
+            ctx.outboundLinks.push((0, link_converter_1.convertWorkflowEventLinkToNexusLink)(internalOptions.backLink.workflowEvent));
+        }
+        catch (error) {
+            context_1.log.warn('failed to convert Workflow event link to Nexus link', { error });
+        }
+    }
+    return {
+        workflowId: handle.workflowId,
+        runId: handle.firstExecutionRunId,
+    };
+}
+/**
+ * A Nexus Operation implementation that is backed by a Workflow run.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+class WorkflowRunOperationHandler {
+    handler;
+    constructor(handler) {
+        this.handler = handler;
+    }
+    async start(ctx, input) {
+        const { namespace } = (0, context_1.getHandlerContext)();
+        const handle = await this.handler(ctx, input);
+        return nexus.HandlerStartOperationResult.async((0, token_1.generateWorkflowRunOperationToken)(namespace, handle.workflowId));
+    }
+    getInfo(_ctx, _token) {
+        // Not implemented in Temporal yet.
+        throw new nexus.HandlerError('NOT_IMPLEMENTED', 'Method not implemented');
+    }
+    getResult(_ctx, _token) {
+        // Not implemented in Temporal yet.
+        throw new nexus.HandlerError('NOT_IMPLEMENTED', 'Method not implemented');
+    }
+    async cancel(_ctx, token) {
+        const decoded = (0, token_1.loadWorkflowRunOperationToken)(token);
+        await (0, context_1.getClient)().workflow.getHandle(decoded.wid).cancel();
+    }
+}
+exports.WorkflowRunOperationHandler = WorkflowRunOperationHandler;
+//# sourceMappingURL=workflow-helpers.js.map

package/lib/workflow-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-helpers.js","sourceRoot":"","sources":["../src/workflow-helpers.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@temporalio/nexus",
+  "version": "1.13.0",
+  "description": "Temporal.io SDK Nexus sub-package",
+  "main": "lib/index.js",
+  "types": "./lib/index.d.ts",
+  "keywords": [
+    "temporal",
+    "workflow",
+    "worker",
+    "nexus"
+  ],
+  "author": "Temporal Technologies Inc. <sdk@temporal.io>",
+  "license": "MIT",
+  "dependencies": {
+    "@temporalio/client": "1.13.0",
+    "@temporalio/common": "1.13.0",
+    "@temporalio/proto": "1.13.0",
+    "long": "^5.2.3",
+    "nexus-rpc": "^0.0.1"
+  },
+  "bugs": {
+    "url": "https://github.com/temporalio/sdk-typescript/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/temporalio/sdk-typescript.git",
+    "directory": "packages/nexus"
+  },
+  "homepage": "https://github.com/temporalio/sdk-typescript/tree/main/packages/nexus",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">= 18.0.0"
+  },
+  "files": [
+    "src",
+    "lib"
+  ],
+  "gitHead": "cf7c1e7d70f0c775f1382fd335b8bd721495f8cc"
+}

package/src/context.ts

@@ -0,0 +1,103 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { Logger, LogLevel, LogMetadata, MetricMeter } from '@temporalio/common';
+import { Client } from '@temporalio/client';
+
+// Context Storage /////////////////////////////////////////////////////////////////////////////////
+
+// Make it safe to use @temporalio/nexus with multiple versions installed.
+const asyncLocalStorageSymbol = Symbol.for('__temporal_nexus_context_storage__');
+if (!(globalThis as any)[asyncLocalStorageSymbol]) {
+  (globalThis as any)[asyncLocalStorageSymbol] = new AsyncLocalStorage<HandlerContext>();
+}
+export const asyncLocalStorage: AsyncLocalStorage<HandlerContext> = (globalThis as any)[asyncLocalStorageSymbol];
+
+export function getHandlerContext(): HandlerContext {
+  const ctx = asyncLocalStorage.getStore();
+  if (ctx == null) {
+    throw new ReferenceError('Not in a Nexus handler context');
+  }
+  return ctx;
+}
+
+/**
+ * Context used internally in the SDK to propagate information from the worker to the Temporal Nexus helpers.
+ *
+ * @internal
+ * @hidden
+ */
+export interface HandlerContext {
+  log: Logger;
+  metrics: MetricMeter;
+  client: Client;
+  namespace: string;
+  taskQueue: string;
+}
+
+// Basic APIs //////////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * A logger for use in Nexus Handler scope.
+ *
+ * This defaults to the `Runtime`'s Logger (see {@link Runtime.logger}). Attributes from the
+ * current Nexus handler context are automatically included as metadata on every log entries. An
+ * extra `sdkComponent` metadata attribute is also added, with value `nexus`; this can be used
+ * for fine-grained filtering of log entries further downstream.
+ *
+ * To customize log attributes, register a {@link nexus.NexusOutboundCallsInterceptor} that
+ * intercepts the `getLogAttributes()` method.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export const log: Logger = {
+  log(level: LogLevel, message: string, meta?: LogMetadata): any {
+    return getHandlerContext().log.log(level, message, meta);
+  },
+  trace(message: string, meta?: LogMetadata): any {
+    return getHandlerContext().log.trace(message, meta);
+  },
+  debug(message: string, meta?: LogMetadata): any {
+    return getHandlerContext().log.debug(message, meta);
+  },
+  info(message: string, meta?: LogMetadata): any {
+    return getHandlerContext().log.info(message, meta);
+  },
+  warn(message: string, meta?: LogMetadata): any {
+    return getHandlerContext().log.warn(message, meta);
+  },
+  error(message: string, meta?: LogMetadata): any {
+    return getHandlerContext().log.error(message, meta);
+  },
+};
+
+/**
+ * A metric meter for use in Nexus handler scope, with Nexus handler-specific tags.
+ *
+ * To add custom tags, register a {@link nexus.NexusOutboundCallsInterceptor} that
+ * intercepts the `getMetricTags()` method.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export const metricMeter: MetricMeter = {
+  createCounter(name, unit, description) {
+    return getHandlerContext().metrics.createCounter(name, unit, description);
+  },
+  createHistogram(name, valueType = 'int', unit, description) {
+    return getHandlerContext().metrics.createHistogram(name, valueType, unit, description);
+  },
+  createGauge(name, valueType = 'int', unit, description) {
+    return getHandlerContext().metrics.createGauge(name, valueType, unit, description);
+  },
+  withTags(tags) {
+    return getHandlerContext().metrics.withTags(tags);
+  },
+};
+
+/**
+ * Returns a client to be used in a Nexus Operation's context, this Client is powered by the same
+ * NativeConnection that the worker was created with.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export function getClient(): Client {
+  return getHandlerContext().client;
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export {
+  //
+  log,
+  getClient,
+  metricMeter,
+} from './context';
+
+export {
+  startWorkflow,
+  WorkflowHandle,
+  WorkflowRunOperationHandler,
+  WorkflowRunOperationStartHandler,
+  WorkflowStartOptions,
+} from './workflow-helpers';

package/src/link-converter.ts

@@ -0,0 +1,152 @@
+import Long from 'long';
+import { Link as NexusLink } from 'nexus-rpc';
+import { temporal } from '@temporalio/proto';
+
+const { EventType } = temporal.api.enums.v1;
+type WorkflowEventLink = temporal.api.common.v1.Link.IWorkflowEvent;
+type EventReference = temporal.api.common.v1.Link.WorkflowEvent.IEventReference;
+type RequestIdReference = temporal.api.common.v1.Link.WorkflowEvent.IRequestIdReference;
+
+const LINK_EVENT_ID_PARAM = 'eventID';
+const LINK_EVENT_TYPE_PARAM = 'eventType';
+const LINK_REQUEST_ID_PARAM = 'requestID';
+const LINK_REFERENCE_TYPE_KEY = 'referenceType';
+
+const EVENT_REFERENCE_TYPE = 'EventReference';
+const REQUEST_ID_REFERENCE_TYPE = 'RequestIdReference';
+
+// fullName isn't part of the generated typed unfortunately.
+const WORKFLOW_EVENT_TYPE: string = (temporal.api.common.v1.Link.WorkflowEvent as any).fullName.slice(1);
+
+export function convertWorkflowEventLinkToNexusLink(we: WorkflowEventLink): NexusLink {
+  if (!we.namespace || !we.workflowId || !we.runId) {
+    throw new TypeError('Missing required fields: namespace, workflowId, or runId');
+  }
+  const url = new URL(
+    `temporal:///namespaces/${encodeURIComponent(we.namespace)}/workflows/${encodeURIComponent(
+      we.workflowId
+    )}/${encodeURIComponent(we.runId)}/history`
+  );
+
+  if (we.eventRef != null) {
+    url.search = convertLinkWorkflowEventEventReferenceToURLQuery(we.eventRef);
+  } else if (we.requestIdRef != null) {
+    url.search = convertLinkWorkflowEventRequestIdReferenceToURLQuery(we.requestIdRef);
+  }
+
+  return {
+    url,
+    type: WORKFLOW_EVENT_TYPE,
+  };
+}
+
+export function convertNexusLinkToWorkflowEventLink(link: NexusLink): WorkflowEventLink {
+  if (link.url.protocol !== 'temporal:') {
+    throw new TypeError(`Invalid URL scheme: ${link.url}, expected 'temporal:', got '${link.url.protocol}'`);
+  }
+
+  // /namespaces/:namespace/workflows/:workflowId/:runId/history
+  const parts = link.url.pathname.split('/');
+  if (parts.length !== 7 || parts[1] !== 'namespaces' || parts[3] !== 'workflows' || parts[6] !== 'history') {
+    throw new TypeError(`Invalid URL path: ${link.url}`);
+  }
+  const namespace = decodeURIComponent(parts[2]);
+  const workflowId = decodeURIComponent(parts[4]);
+  const runId = decodeURIComponent(parts[5]);
+
+  const query = link.url.searchParams;
+  const refType = query.get(LINK_REFERENCE_TYPE_KEY);
+
+  const workflowEventLink: WorkflowEventLink = {
+    namespace,
+    workflowId,
+    runId,
+  };
+
+  switch (refType) {
+    case EVENT_REFERENCE_TYPE:
+      workflowEventLink.eventRef = convertURLQueryToLinkWorkflowEventEventReference(query);
+      break;
+    case REQUEST_ID_REFERENCE_TYPE:
+      workflowEventLink.requestIdRef = convertURLQueryToLinkWorkflowEventRequestIdReference(query);
+      break;
+    default:
+      throw new TypeError(`Unknown reference type: ${refType}`);
+  }
+  return workflowEventLink;
+}
+
+function convertLinkWorkflowEventEventReferenceToURLQuery(eventRef: EventReference): string {
+  const params = new URLSearchParams();
+  params.set(LINK_REFERENCE_TYPE_KEY, EVENT_REFERENCE_TYPE);
+  if (eventRef.eventId != null) {
+    const eventId = eventRef.eventId.toNumber();
+    if (eventId > 0) {
+      params.set(LINK_EVENT_ID_PARAM, `${eventId}`);
+    }
+  }
+  if (eventRef.eventType != null) {
+    const eventType = constantCaseToPascalCase(EventType[eventRef.eventType].replace('EVENT_TYPE_', ''));
+    params.set(LINK_EVENT_TYPE_PARAM, eventType);
+  }
+  return params.toString();
+}
+
+function convertURLQueryToLinkWorkflowEventEventReference(query: URLSearchParams): EventReference {
+  let eventId = 0;
+  const eventIdParam = query.get(LINK_EVENT_ID_PARAM);
+  if (eventIdParam && /^\d+$/.test(eventIdParam)) {
+    eventId = parseInt(eventIdParam, 10);
+  }
+  const eventTypeParam = query.get(LINK_EVENT_TYPE_PARAM);
+  if (!eventTypeParam) {
+    throw new TypeError(`Missing eventType parameter`);
+  }
+  const eventType = EventType[normalizeEnumValue(eventTypeParam, 'EVENT_TYPE') as keyof typeof EventType];
+  if (eventType == null) {
+    throw new TypeError(`Unknown eventType parameter: ${eventTypeParam}`);
+  }
+  return { eventId: Long.fromNumber(eventId), eventType };
+}
+
+function convertLinkWorkflowEventRequestIdReferenceToURLQuery(requestIdRef: RequestIdReference): string {
+  const params = new URLSearchParams();
+  params.set(LINK_REFERENCE_TYPE_KEY, REQUEST_ID_REFERENCE_TYPE);
+  if (requestIdRef.requestId != null) {
+    params.set(LINK_REQUEST_ID_PARAM, requestIdRef.requestId);
+  }
+  if (requestIdRef.eventType != null) {
+    const eventType = constantCaseToPascalCase(EventType[requestIdRef.eventType].replace('EVENT_TYPE_', ''));
+    params.set(LINK_EVENT_TYPE_PARAM, eventType);
+  }
+  return params.toString();
+}
+
+function convertURLQueryToLinkWorkflowEventRequestIdReference(query: URLSearchParams): RequestIdReference {
+  const requestId = query.get(LINK_REQUEST_ID_PARAM);
+  const eventTypeParam = query.get(LINK_EVENT_TYPE_PARAM);
+  if (!eventTypeParam) {
+    throw new TypeError(`Missing eventType parameter`);
+  }
+  const eventType = EventType[normalizeEnumValue(eventTypeParam, 'EVENT_TYPE') as keyof typeof EventType];
+  if (eventType == null) {
+    throw new TypeError(`Unknown eventType parameter: ${eventTypeParam}`);
+  }
+  return { requestId, eventType };
+}
+
+function normalizeEnumValue(value: string, prefix: string) {
+  value = pascalCaseToConstantCase(value);
+  if (!value.startsWith(prefix)) {
+    value = `${prefix}_${value}`;
+  }
+  return value;
+}
+
+function pascalCaseToConstantCase(s: string) {
+  return s.replace(/[^\b][A-Z]/g, (m) => `${m[0]}_${m[1]}`).toUpperCase();
+}
+
+function constantCaseToPascalCase(s: string) {
+  return s.replace(/[A-Z]+_?/g, (m) => `${m[0]}${m.slice(1).toLocaleLowerCase()}`.replace(/_/, ''));
+}

package/src/token.ts

@@ -0,0 +1,107 @@
+/**
+ * @internal
+ * @hidden
+ */
+export interface WorkflowRunOperationToken {
+  /**
+   * Version of the token, by default we assume we're on version 1, this field is not emitted as part of the output,
+   * it's only used to reject newer token versions on load.
+   */
+  v?: number;
+
+  /**
+   * Type of the Operation. Must be OPERATION_TOKEN_TYPE_WORKFLOW_RUN.
+   */
+  t: OperationTokenType;
+
+  /**
+   * Namespace of the workflow.
+   */
+  ns: string;
+
+  /**
+   * ID of the workflow.
+   */
+  wid: string;
+}
+
+/**
+ * OperationTokenType is used to identify the type of Operation token.
+ * Currently, we only have one type of Operation token: WorkflowRun.
+ */
+type OperationTokenType = (typeof OperationTokenType)[keyof typeof OperationTokenType];
+
+/**
+ * @internal
+ * @hidden
+ */
+const OperationTokenType = {
+  WORKFLOW_RUN: 1,
+} as const;
+
+/**
+ * Generate a workflow run Operation token.
+ */
+export function generateWorkflowRunOperationToken(namespace: string, workflowId: string): string {
+  const token: WorkflowRunOperationToken = {
+    t: OperationTokenType.WORKFLOW_RUN,
+    ns: namespace,
+    wid: workflowId,
+  };
+  return base64URLEncodeNoPadding(JSON.stringify(token));
+}
+
+/**
+ * Load and validate a workflow run Operation token.
+ */
+export function loadWorkflowRunOperationToken(data: string): WorkflowRunOperationToken {
+  if (!data) {
+    throw new TypeError('invalid workflow run token: token is empty');
+  }
+
+  let decoded: string;
+  try {
+    decoded = base64URLDecodeNoPadding(data);
+  } catch (err) {
+    throw new TypeError('failed to decode token', { cause: err });
+  }
+
+  let token: WorkflowRunOperationToken;
+  try {
+    token = JSON.parse(decoded);
+  } catch (err) {
+    throw new TypeError('failed to unmarshal workflow run Operation token', { cause: err });
+  }
+
+  if (token.t !== OperationTokenType.WORKFLOW_RUN) {
+    throw new TypeError(`invalid workflow token type: ${token.t}, expected: ${OperationTokenType.WORKFLOW_RUN}`);
+  }
+  if (token.v !== undefined && token.v !== 0) {
+    throw new TypeError('invalid workflow run token: "v" field should not be present');
+  }
+  if (!token.wid) {
+    throw new TypeError('invalid workflow run token: missing workflow ID (wid)');
+  }
+
+  return token;
+}
+
+// Exported for use in tests.
+export function base64URLEncodeNoPadding(str: string): string {
+  const base64 = Buffer.from(str).toString('base64url');
+  return base64.replace(/[=]+$/, '');
+}
+
+function base64URLDecodeNoPadding(str: string): string {
+  // Validate the string contains only valid base64URL characters
+  if (!/^[A-Za-z0-9_-]*$/.test(str)) {
+    throw new TypeError('invalid base64URL encoded string: contains invalid characters');
+  }
+
+  const paddingLength = str.length % 4;
+  if (paddingLength > 0) {
+    str += '='.repeat(4 - paddingLength);
+  }
+
+  return Buffer.from(str, 'base64url').toString('utf-8');
+}

package/src/workflow-helpers.ts

@@ -0,0 +1,151 @@
+import * as nexus from 'nexus-rpc';
+import { Workflow } from '@temporalio/common';
+import { Replace } from '@temporalio/common/lib/type-helpers';
+import { WorkflowStartOptions as ClientWorkflowStartOptions } from '@temporalio/client';
+import { type temporal } from '@temporalio/proto';
+import { InternalWorkflowStartOptionsSymbol, InternalWorkflowStartOptions } from '@temporalio/client/lib/internal';
+import { generateWorkflowRunOperationToken, loadWorkflowRunOperationToken } from './token';
+import { convertNexusLinkToWorkflowEventLink, convertWorkflowEventLinkToNexusLink } from './link-converter';
+import { getClient, getHandlerContext, log } from './context';
+
+declare const isNexusWorkflowHandle: unique symbol;
+
+/**
+ * A handle to a running workflow that is returned by the {@link startWorkflow} helper.
+ * This handle should be returned by {@link WorkflowRunOperationStartHandler} implementations.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export interface WorkflowHandle<_T> {
+  readonly workflowId: string;
+  readonly runId: string;
+
+  /**
+   * Virtual type brand to maintain a distinction between {@link WorkflowHandle} provided by the
+   * {@link startWorkflow} helper (which will have attached links, request ID, completion URL, etc)
+   * and the `WorkflowHandle` type returned by the {@link WorkflowClient.start}.
+   *
+   * @internal
+   * @hidden
+   *
+   * @experimental Nexus support in Temporal SDK is experimental.
+   */
+  readonly [isNexusWorkflowHandle]: typeof isNexusWorkflowHandle;
+}
+
+/**
+ * Options for starting a workflow using {@link startWorkflow}, this type is identical to the
+ * client's `WorkflowStartOptions` with the exception that `taskQueue` is optional and defaults
+ * to the current worker's task queue.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export type WorkflowStartOptions<T extends Workflow> = Replace<ClientWorkflowStartOptions<T>, { taskQueue?: string }>;
+
+/**
+ * Starts a workflow run for a {@link WorkflowRunOperationStartHandler}, linking the execution chain
+ * to a Nexus Operation (subsequent runs started from continue-as-new and retries). Automatically
+ * propagates the callback, request ID, and back and forward links from the Nexus options to the
+ * Workflow.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export async function startWorkflow<T extends Workflow>(
+  ctx: nexus.StartOperationContext,
+  workflowTypeOrFunc: string | T,
+  workflowOptions: WorkflowStartOptions<T>
+): Promise<WorkflowHandle<T>> {
+  const { client, taskQueue } = getHandlerContext();
+  const links = Array<temporal.api.common.v1.ILink>();
+  if (ctx.inboundLinks?.length > 0) {
+    for (const l of ctx.inboundLinks) {
+      try {
+        links.push({
+          workflowEvent: convertNexusLinkToWorkflowEventLink(l),
+        });
+      } catch (error) {
+        log.warn('failed to convert Nexus link to Workflow event link', { error });
+      }
+    }
+  }
+  const internalOptions: InternalWorkflowStartOptions[typeof InternalWorkflowStartOptionsSymbol] = {
+    links,
+    requestId: ctx.requestId,
+  };
+
+  internalOptions.onConflictOptions = {
+    attachLinks: true,
+    attachCompletionCallbacks: true,
+    attachRequestId: true,
+  };
+
+  if (ctx.callbackUrl) {
+    internalOptions.completionCallbacks = [
+      {
+        nexus: { url: ctx.callbackUrl, header: ctx.callbackHeaders },
+        links, // pass in links here as well for older servers, newer servers dedupe them.
+      },
+    ];
+  }
+
+  const { taskQueue: userSpecifiedTaskQueue, ...rest } = workflowOptions;
+  const startOptions: ClientWorkflowStartOptions = {
+    ...rest,
+    taskQueue: userSpecifiedTaskQueue || taskQueue,
+    [InternalWorkflowStartOptionsSymbol]: internalOptions,
+  };
+
+  const handle = await client.workflow.start(workflowTypeOrFunc, startOptions);
+  if (internalOptions.backLink?.workflowEvent != null) {
+    try {
+      ctx.outboundLinks.push(convertWorkflowEventLinkToNexusLink(internalOptions.backLink.workflowEvent));
+    } catch (error) {
+      log.warn('failed to convert Workflow event link to Nexus link', { error });
+    }
+  }
+
+  return {
+    workflowId: handle.workflowId,
+    runId: handle.firstExecutionRunId,
+  } as WorkflowHandle<T>;
+}
+
+/**
+ * A handler function for the {@link WorkflowRunOperationHandler} constructor.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export type WorkflowRunOperationStartHandler<I, O> = (
+  ctx: nexus.StartOperationContext,
+  input: I
+) => Promise<WorkflowHandle<O>>;
+
+/**
+ * A Nexus Operation implementation that is backed by a Workflow run.
+ *
+ * @experimental Nexus support in Temporal SDK is experimental.
+ */
+export class WorkflowRunOperationHandler<I, O> implements nexus.OperationHandler<I, O> {
+  constructor(readonly handler: WorkflowRunOperationStartHandler<I, O>) {}
+
+  async start(ctx: nexus.StartOperationContext, input: I): Promise<nexus.HandlerStartOperationResult<O>> {
+    const { namespace } = getHandlerContext();
+    const handle = await this.handler(ctx, input);
+    return nexus.HandlerStartOperationResult.async(generateWorkflowRunOperationToken(namespace, handle.workflowId));
+  }
+
+  getInfo(_ctx: nexus.GetOperationInfoContext, _token: string): Promise<nexus.OperationInfo> {
+    // Not implemented in Temporal yet.
+    throw new nexus.HandlerError('NOT_IMPLEMENTED', 'Method not implemented');
+  }
+
+  getResult(_ctx: nexus.GetOperationResultContext, _token: string): Promise<O> {
+    // Not implemented in Temporal yet.
+    throw new nexus.HandlerError('NOT_IMPLEMENTED', 'Method not implemented');
+  }
+
+  async cancel(_ctx: nexus.CancelOperationContext, token: string): Promise<void> {
+    const decoded = loadWorkflowRunOperationToken(token);
+    await getClient().workflow.getHandle(decoded.wid).cancel();
+  }
+}