@restatedev/restate-sdk 1.11.0 → 1.12.0

package/dist/fetch.d.cts

@@ -1,10 +1,12 @@
 import { CancelledError, RestateError, RetryableError, RetryableErrorOptions, TerminalError, TimeoutError } from "./types/errors.cjs";
+import { Hooks, HooksProvider, Interceptor } from "./hooks.cjs";
 import { Client, ClientCallOptions, ClientSendOptions, InferArg, ObjectHandlerOpts, ObjectOptions, ObjectOpts, Opts, RemoveVoidArgument, RetryPolicy, SendClient, SendOpts, ServiceHandlerOpts, ServiceOptions, ServiceOpts, WorkflowHandlerOpts, WorkflowOptions, WorkflowOpts, handlers, object, rpc, service, workflow } from "./types/rpc.cjs";
-import { Context, ContextDate, DurablePromise, GenericCall, GenericSend, InvocationHandle, InvocationId, InvocationIdParser, InvocationPromise, KeyValueStore, ObjectContext, ObjectSharedContext, Rand, Request as Request$1, RestatePromise, RunAction, RunOptions, SendOptions, TypedState, UntypedState, WorkflowContext, WorkflowSharedContext } from "./context.cjs";
+import { Context, ContextDate, DurablePromise, GenericCall, GenericSend, InvocationHandle, InvocationId, InvocationIdParser, InvocationPromise, KeyValueStore, ObjectContext, ObjectSharedContext, Rand, Request as Request$1, RestatePromise, RunAction, RunOptions, Target, TypedState, UntypedState, WorkflowContext, WorkflowSharedContext } from "./context.cjs";
+import { internal_d_exports } from "./internal.cjs";
 import { LogMetadata, LogSource, LoggerContext, LoggerTransport, RestateLogLevel } from "./logging/logger_transport.cjs";
 import { DefaultServiceOptions, RestateEndpoint, RestateEndpointBase } from "./endpoint.cjs";
+import { isRestatePromise } from "./promises.cjs";
 import { EndpointOptions } from "./endpoint/types.cjs";
-import { internal_d_exports } from "./internal.cjs";
 import { CombineablePromise, Duration, JournalValueCodec, ObjectHandler, RestateContext, RestateObjectContext, RestateObjectSharedContext, RestateWorkflowContext, RestateWorkflowSharedContext, Serde, Service, ServiceDefinition, ServiceDefinitionFrom, ServiceHandler, VirtualObject, VirtualObjectDefinition, VirtualObjectDefinitionFrom, Workflow, WorkflowDefinition, WorkflowDefinitionFrom, WorkflowHandler, WorkflowSharedHandler, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, serde } from "./common_api.cjs";
 import { FetchEndpoint } from "./endpoint/fetch_endpoint.cjs";
 
@@ -49,5 +51,5 @@ interface FetchEndpointOptions extends EndpointOptions {
  */
 declare function createEndpointHandler(options: FetchEndpointOptions): (request: Request, ...extraArgs: unknown[]) => Promise<Response>;
 //#endregion
-export { CancelledError, Client, ClientCallOptions, ClientSendOptions, CombineablePromise, Context, ContextDate, DefaultServiceOptions, DurablePromise, Duration, EndpointOptions, type FetchEndpoint, FetchEndpointOptions, GenericCall, GenericSend, InferArg, InvocationHandle, InvocationId, InvocationIdParser, InvocationPromise, JournalValueCodec, KeyValueStore, LogMetadata, LogSource, LoggerContext, LoggerTransport, ObjectContext, ObjectHandler, ObjectHandlerOpts, ObjectOptions, ObjectOpts, ObjectSharedContext, Opts, Rand, RemoveVoidArgument, Request$1 as Request, RestateContext, RestateEndpoint, RestateEndpointBase, RestateError, RestateLogLevel, RestateObjectContext, RestateObjectSharedContext, RestatePromise, RestateWorkflowContext, RestateWorkflowSharedContext, RetryPolicy, RetryableError, RetryableErrorOptions, RunAction, RunOptions, SendClient, SendOptions, SendOpts, Serde, Service, ServiceDefinition, ServiceDefinitionFrom, ServiceHandler, ServiceHandlerOpts, ServiceOptions, ServiceOpts, TerminalError, TimeoutError, TypedState, UntypedState, VirtualObject, VirtualObjectDefinition, VirtualObjectDefinitionFrom, Workflow, WorkflowContext, WorkflowDefinition, WorkflowDefinitionFrom, WorkflowHandler, WorkflowHandlerOpts, WorkflowOptions, WorkflowOpts, WorkflowSharedContext, WorkflowSharedHandler, createEndpointHandler, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, endpoint, handlers, internal_d_exports as internal, object, rpc, serde, service, workflow };
+export { CancelledError, Client, ClientCallOptions, ClientSendOptions, CombineablePromise, Context, ContextDate, DefaultServiceOptions, DurablePromise, Duration, EndpointOptions, type FetchEndpoint, FetchEndpointOptions, GenericCall, GenericSend, Hooks, HooksProvider, InferArg, Interceptor, InvocationHandle, InvocationId, InvocationIdParser, InvocationPromise, JournalValueCodec, KeyValueStore, LogMetadata, LogSource, LoggerContext, LoggerTransport, ObjectContext, ObjectHandler, ObjectHandlerOpts, ObjectOptions, ObjectOpts, ObjectSharedContext, Opts, Rand, RemoveVoidArgument, Request$1 as Request, RestateContext, RestateEndpoint, RestateEndpointBase, RestateError, RestateLogLevel, RestateObjectContext, RestateObjectSharedContext, RestatePromise, RestateWorkflowContext, RestateWorkflowSharedContext, RetryPolicy, RetryableError, RetryableErrorOptions, RunAction, RunOptions, SendClient, SendOpts, Serde, Service, ServiceDefinition, ServiceDefinitionFrom, ServiceHandler, ServiceHandlerOpts, ServiceOptions, ServiceOpts, Target, TerminalError, TimeoutError, TypedState, UntypedState, VirtualObject, VirtualObjectDefinition, VirtualObjectDefinitionFrom, Workflow, WorkflowContext, WorkflowDefinition, WorkflowDefinitionFrom, WorkflowHandler, WorkflowHandlerOpts, WorkflowOptions, WorkflowOpts, WorkflowSharedContext, WorkflowSharedHandler, createEndpointHandler, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, endpoint, handlers, internal_d_exports as internal, isRestatePromise, object, rpc, serde, service, workflow };
 //# sourceMappingURL=fetch.d.cts.map

package/dist/fetch.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch.d.cts","names":[],"sources":["../src/fetch.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;iBAyBgB,QAAA,CAAA,GAAY;UAIX,oBAAA,SAA6B;;AAJ9C;AAIA;AAiCA;;;;;EAAmE,aAAA,CAAA,EAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;;iBAAnD,qBAAA,UAA+B,iCAAoB,qCAAA,QAAA"}
+{"version":3,"file":"fetch.d.cts","names":[],"sources":["../src/fetch.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;iBAyBgB,QAAA,CAAA,GAAY;UAIX,oBAAA,SAA6B;;;;AAJ9C;AAIA;AAiCA;;;EAAmE,aAAA,CAAA,EAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;;iBAAnD,qBAAA,UAA+B,iCAAoB,qCAAA,QAAA"}

package/dist/fetch.d.ts

@@ -1,10 +1,12 @@
 import { CancelledError, RestateError, RetryableError, RetryableErrorOptions, TerminalError, TimeoutError } from "./types/errors.js";
+import { Hooks, HooksProvider, Interceptor } from "./hooks.js";
 import { Client, ClientCallOptions, ClientSendOptions, InferArg, ObjectHandlerOpts, ObjectOptions, ObjectOpts, Opts, RemoveVoidArgument, RetryPolicy, SendClient, SendOpts, ServiceHandlerOpts, ServiceOptions, ServiceOpts, WorkflowHandlerOpts, WorkflowOptions, WorkflowOpts, handlers, object, rpc, service, workflow } from "./types/rpc.js";
-import { Context, ContextDate, DurablePromise, GenericCall, GenericSend, InvocationHandle, InvocationId, InvocationIdParser, InvocationPromise, KeyValueStore, ObjectContext, ObjectSharedContext, Rand, Request as Request$1, RestatePromise, RunAction, RunOptions, SendOptions, TypedState, UntypedState, WorkflowContext, WorkflowSharedContext } from "./context.js";
+import { Context, ContextDate, DurablePromise, GenericCall, GenericSend, InvocationHandle, InvocationId, InvocationIdParser, InvocationPromise, KeyValueStore, ObjectContext, ObjectSharedContext, Rand, Request as Request$1, RestatePromise, RunAction, RunOptions, Target, TypedState, UntypedState, WorkflowContext, WorkflowSharedContext } from "./context.js";
+import { internal_d_exports } from "./internal.js";
 import { LogMetadata, LogSource, LoggerContext, LoggerTransport, RestateLogLevel } from "./logging/logger_transport.js";
 import { DefaultServiceOptions, RestateEndpoint, RestateEndpointBase } from "./endpoint.js";
+import { isRestatePromise } from "./promises.js";
 import { EndpointOptions } from "./endpoint/types.js";
-import { internal_d_exports } from "./internal.js";
 import { CombineablePromise, Duration, JournalValueCodec, ObjectHandler, RestateContext, RestateObjectContext, RestateObjectSharedContext, RestateWorkflowContext, RestateWorkflowSharedContext, Serde, Service, ServiceDefinition, ServiceDefinitionFrom, ServiceHandler, VirtualObject, VirtualObjectDefinition, VirtualObjectDefinitionFrom, Workflow, WorkflowDefinition, WorkflowDefinitionFrom, WorkflowHandler, WorkflowSharedHandler, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, serde } from "./common_api.js";
 import { FetchEndpoint } from "./endpoint/fetch_endpoint.js";
 
@@ -49,5 +51,5 @@ interface FetchEndpointOptions extends EndpointOptions {
  */
 declare function createEndpointHandler(options: FetchEndpointOptions): (request: Request, ...extraArgs: unknown[]) => Promise<Response>;
 //#endregion
-export { CancelledError, Client, ClientCallOptions, ClientSendOptions, CombineablePromise, Context, ContextDate, DefaultServiceOptions, DurablePromise, Duration, EndpointOptions, type FetchEndpoint, FetchEndpointOptions, GenericCall, GenericSend, InferArg, InvocationHandle, InvocationId, InvocationIdParser, InvocationPromise, JournalValueCodec, KeyValueStore, LogMetadata, LogSource, LoggerContext, LoggerTransport, ObjectContext, ObjectHandler, ObjectHandlerOpts, ObjectOptions, ObjectOpts, ObjectSharedContext, Opts, Rand, RemoveVoidArgument, Request$1 as Request, RestateContext, RestateEndpoint, RestateEndpointBase, RestateError, RestateLogLevel, RestateObjectContext, RestateObjectSharedContext, RestatePromise, RestateWorkflowContext, RestateWorkflowSharedContext, RetryPolicy, RetryableError, RetryableErrorOptions, RunAction, RunOptions, SendClient, SendOptions, SendOpts, Serde, Service, ServiceDefinition, ServiceDefinitionFrom, ServiceHandler, ServiceHandlerOpts, ServiceOptions, ServiceOpts, TerminalError, TimeoutError, TypedState, UntypedState, VirtualObject, VirtualObjectDefinition, VirtualObjectDefinitionFrom, Workflow, WorkflowContext, WorkflowDefinition, WorkflowDefinitionFrom, WorkflowHandler, WorkflowHandlerOpts, WorkflowOptions, WorkflowOpts, WorkflowSharedContext, WorkflowSharedHandler, createEndpointHandler, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, endpoint, handlers, internal_d_exports as internal, object, rpc, serde, service, workflow };
+export { CancelledError, Client, ClientCallOptions, ClientSendOptions, CombineablePromise, Context, ContextDate, DefaultServiceOptions, DurablePromise, Duration, EndpointOptions, type FetchEndpoint, FetchEndpointOptions, GenericCall, GenericSend, Hooks, HooksProvider, InferArg, Interceptor, InvocationHandle, InvocationId, InvocationIdParser, InvocationPromise, JournalValueCodec, KeyValueStore, LogMetadata, LogSource, LoggerContext, LoggerTransport, ObjectContext, ObjectHandler, ObjectHandlerOpts, ObjectOptions, ObjectOpts, ObjectSharedContext, Opts, Rand, RemoveVoidArgument, Request$1 as Request, RestateContext, RestateEndpoint, RestateEndpointBase, RestateError, RestateLogLevel, RestateObjectContext, RestateObjectSharedContext, RestatePromise, RestateWorkflowContext, RestateWorkflowSharedContext, RetryPolicy, RetryableError, RetryableErrorOptions, RunAction, RunOptions, SendClient, SendOpts, Serde, Service, ServiceDefinition, ServiceDefinitionFrom, ServiceHandler, ServiceHandlerOpts, ServiceOptions, ServiceOpts, Target, TerminalError, TimeoutError, TypedState, UntypedState, VirtualObject, VirtualObjectDefinition, VirtualObjectDefinitionFrom, Workflow, WorkflowContext, WorkflowDefinition, WorkflowDefinitionFrom, WorkflowHandler, WorkflowHandlerOpts, WorkflowOptions, WorkflowOpts, WorkflowSharedContext, WorkflowSharedHandler, createEndpointHandler, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, endpoint, handlers, internal_d_exports as internal, isRestatePromise, object, rpc, serde, service, workflow };
 //# sourceMappingURL=fetch.d.ts.map

package/dist/fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch.d.ts","names":[],"sources":["../src/fetch.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;iBAyBgB,QAAA,CAAA,GAAY;UAIX,oBAAA,SAA6B;;AAJ9C;AAIA;AAiCA;;;;;EAAmE,aAAA,CAAA,EAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;;iBAAnD,qBAAA,UAA+B,iCAAoB,qCAAA,QAAA"}
+{"version":3,"file":"fetch.d.ts","names":[],"sources":["../src/fetch.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;iBAyBgB,QAAA,CAAA,GAAY;UAIX,oBAAA,SAA6B;;;;AAJ9C;AAIA;AAiCA;;;EAAmE,aAAA,CAAA,EAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;;iBAAnD,qBAAA,UAA+B,iCAAoB,qCAAA,QAAA"}

package/dist/fetch.js

@@ -1,6 +1,7 @@
 import { CancelledError, RestateError, RetryableError, TerminalError, TimeoutError } from "./types/errors.js";
-import { Opts, SendOpts, handlers, object, rpc, service, workflow } from "./types/rpc.js";
+import { isRestatePromise } from "./promises.js";
 import { InvocationIdParser, RestatePromise } from "./context.js";
+import { Opts, SendOpts, handlers, object, rpc, service, workflow } from "./types/rpc.js";
 import { internal_exports } from "./internal.js";
 import { CombineablePromise, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, serde } from "./common_api.js";
 import { FetchEndpointImpl } from "./endpoint/fetch_endpoint.js";
@@ -41,5 +42,5 @@ function createEndpointHandler(options) {
 }
 
 //#endregion
-export { CancelledError, CombineablePromise, InvocationIdParser, Opts, RestateError, RestatePromise, RetryableError, SendOpts, TerminalError, TimeoutError, createEndpointHandler, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, endpoint, handlers, internal_exports as internal, object, rpc, serde, service, workflow };
+export { CancelledError, CombineablePromise, InvocationIdParser, Opts, RestateError, RestatePromise, RetryableError, SendOpts, TerminalError, TimeoutError, createEndpointHandler, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, endpoint, handlers, internal_exports as internal, isRestatePromise, object, rpc, serde, service, workflow };
 //# sourceMappingURL=fetch.js.map

package/dist/fetch.js.map

@@ -1 +1 @@
-{"version":3,"file":"fetch.js","names":[],"sources":["../src/fetch.ts"],"sourcesContent":["/*\n * Copyright (c) 2023-2024 - Restate Software, Inc., Restate GmbH\n *\n * This file is part of the Restate SDK for Node.js/TypeScript,\n * which is released under the MIT license.\n *\n * You can find a copy of the license in file LICENSE in the root\n * directory of this repository or package, or at\n * https://github.com/restatedev/sdk-typescript/blob/main/LICENSE\n */\n\nexport * from \"./common_api.js\";\n\nimport {\n  type FetchEndpoint,\n  FetchEndpointImpl,\n} from \"./endpoint/fetch_endpoint.js\";\nimport type { EndpointOptions } from \"./endpoint/types.js\";\nimport { withOptions } from \"./endpoint/withOptions.js\";\n\n/**\n * Create a new {@link RestateEndpoint} in request response protocol mode.\n * Bidirectional mode (must be served over http2) can be enabled with .enableHttp2()\n * @deprecated Please use {@link createEndpointHandler}\n */\nexport function endpoint(): FetchEndpoint {\n  return new FetchEndpointImpl(\"REQUEST_RESPONSE\");\n}\n\nexport interface FetchEndpointOptions extends EndpointOptions {\n  /**\n   * Enables bidirectional communication for the handler.\n   *\n   * When set to `true`, the handler supports bidirectional streaming (e.g., via HTTP/2 or compatible HTTP/1.1 servers).\n   * When `false`, the handler operates in request-response mode only.\n   *\n   * @default false\n   */\n  bidirectional?: boolean;\n}\n\n/**\n * Creates a Fetch handler that encapsulates all the Restate services served by this endpoint.\n *\n * @param {FetchEndpointOptions} options - Configuration options for the endpoint handler.\n * @returns A fetch handler function.\n *\n * @example\n * A typical request-response handler would look like this:\n * ```\n * import { createEndpointHandler } from \"@restatedev/restate-sdk/fetch\";\n *\n * export const handler = createEndpointHandler({ services: [myService] })\n *\n * @example\n * A typical bidirectional handler (works with http2 and some http1.1 servers) would look like this:\n * ```\n * import { createEndpointHandler } from \"@restatedev/restate-sdk/fetch\";\n *\n * export const handler = createEndpointHandler({ services: [myService], bidirectional: true })\n *\n */\nexport function createEndpointHandler(options: FetchEndpointOptions) {\n  return withOptions<FetchEndpoint>(\n    new FetchEndpointImpl(\n      options.bidirectional ? \"BIDI_STREAM\" : \"REQUEST_RESPONSE\"\n    ),\n    options\n  ).handler().fetch;\n}\nexport { type FetchEndpoint } from \"./endpoint/fetch_endpoint.js\";\n"],"mappings":";;;;;;;;;;;;;;AAyBA,SAAgB,WAA0B;AACxC,QAAO,IAAI,kBAAkB,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;AAoClD,SAAgB,sBAAsB,SAA+B;AACnE,QAAO,YACL,IAAI,kBACF,QAAQ,gBAAgB,gBAAgB,mBACzC,EACD,QACD,CAAC,SAAS,CAAC"}
+{"version":3,"file":"fetch.js","names":[],"sources":["../src/fetch.ts"],"sourcesContent":["/*\n * Copyright (c) 2023-2024 - Restate Software, Inc., Restate GmbH\n *\n * This file is part of the Restate SDK for Node.js/TypeScript,\n * which is released under the MIT license.\n *\n * You can find a copy of the license in file LICENSE in the root\n * directory of this repository or package, or at\n * https://github.com/restatedev/sdk-typescript/blob/main/LICENSE\n */\n\nexport * from \"./common_api.js\";\n\nimport {\n  type FetchEndpoint,\n  FetchEndpointImpl,\n} from \"./endpoint/fetch_endpoint.js\";\nimport type { EndpointOptions } from \"./endpoint/types.js\";\nimport { withOptions } from \"./endpoint/withOptions.js\";\n\n/**\n * Create a new {@link RestateEndpoint} in request response protocol mode.\n * Bidirectional mode (must be served over http2) can be enabled with .enableHttp2()\n * @deprecated Please use {@link createEndpointHandler}\n */\nexport function endpoint(): FetchEndpoint {\n  return new FetchEndpointImpl(\"REQUEST_RESPONSE\");\n}\n\nexport interface FetchEndpointOptions extends EndpointOptions {\n  /**\n   * Enables bidirectional communication for the handler.\n   *\n   * When set to `true`, the handler supports bidirectional streaming (e.g., via HTTP/2 or compatible HTTP/1.1 servers).\n   * When `false`, the handler operates in request-response mode only.\n   *\n   * @default false\n   */\n  bidirectional?: boolean;\n}\n\n/**\n * Creates a Fetch handler that encapsulates all the Restate services served by this endpoint.\n *\n * @param {FetchEndpointOptions} options - Configuration options for the endpoint handler.\n * @returns A fetch handler function.\n *\n * @example\n * A typical request-response handler would look like this:\n * ```\n * import { createEndpointHandler } from \"@restatedev/restate-sdk/fetch\";\n *\n * export const handler = createEndpointHandler({ services: [myService] })\n *\n * @example\n * A typical bidirectional handler (works with http2 and some http1.1 servers) would look like this:\n * ```\n * import { createEndpointHandler } from \"@restatedev/restate-sdk/fetch\";\n *\n * export const handler = createEndpointHandler({ services: [myService], bidirectional: true })\n *\n */\nexport function createEndpointHandler(options: FetchEndpointOptions) {\n  return withOptions<FetchEndpoint>(\n    new FetchEndpointImpl(\n      options.bidirectional ? \"BIDI_STREAM\" : \"REQUEST_RESPONSE\"\n    ),\n    options\n  ).handler().fetch;\n}\nexport { type FetchEndpoint } from \"./endpoint/fetch_endpoint.js\";\n"],"mappings":";;;;;;;;;;;;;;;AAyBA,SAAgB,WAA0B;AACxC,QAAO,IAAI,kBAAkB,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;AAoClD,SAAgB,sBAAsB,SAA+B;AACnE,QAAO,YACL,IAAI,kBACF,QAAQ,gBAAgB,gBAAgB,mBACzC,EACD,QACD,CAAC,SAAS,CAAC"}

package/dist/hooks.d.cts

@@ -0,0 +1,87 @@
+import { Request } from "./context.cjs";
+
+//#region src/hooks.d.ts
+
+/**
+ * Interceptors wrap handler and ctx.run() execution. They are part of the
+ * invocation — anything that happens inside them (including after `next()`)
+ * affects the invocation outcome.
+ *
+ * ## Error behavior
+ *
+ * Errors thrown at any point (before or after `next()`) affect the invocation:
+ *
+ * - **{@link TerminalError}** — the invocation **fails immediately**, no retry.
+ * - **Any other error** — Restate **retries** the invocation.
+ * - On suspension or pause, `next()` also rejects with an error. This does not
+ *   mean the invocation failed — the attempt is simply ending. Do any cleanup
+ *   you need and rethrow.
+ *
+ * ## Output
+ *
+ * Interceptors **cannot alter the handler's success return value** (the `void`
+ * signature means there is no way to replace it), but they **can transform
+ * errors** by catching and rethrowing a different error.
+ *
+ * ## Rules
+ *
+ * - `next()` must be called exactly once.
+ *
+ * ## When interceptors fire
+ *
+ * - `handler` fires on every attempt.
+ * - `run` fires when the `ctx.run()` closure executes. If the result is
+ *   already in the journal, the closure is skipped and so is the interceptor.
+ *
+ * @example
+ * ```ts
+ * interceptor: {
+ *   handler: async (next) => {
+ *     console.log(`before ${ctx.request.target}`);
+ *     try {
+ *       await next();
+ *       console.log(`after ${ctx.request.target}`);
+ *     } catch (e) {
+ *       console.log(`error ${ctx.request.target}: ${e}`);
+ *       // Always rethrow — swallowing the error changes the
+ *       // invocation outcome. You can also throw a different
+ *       // error (e.g. TerminalError to fail immediately).
+ *       throw e;
+ *     }
+ *   },
+ *   run: async (name, next) => {
+ *     console.log(`  before run "${name}"`);
+ *     try {
+ *       await next();
+ *       console.log(`  after run "${name}"`);
+ *     } catch (e) {
+ *       console.log(`  error run "${name}": ${e}`);
+ *       throw e;
+ *     }
+ *   },
+ * }
+ * ```
+ */
+interface Interceptor {
+  /** Wraps the entire handler invocation. Fires on every attempt. */
+  handler?: (next: () => Promise<void>) => Promise<void>;
+  /**
+   * Wraps each `ctx.run()` call. Only fires for runs that actually execute —
+   * replayed runs (already in the journal) are skipped.
+   * `name` is the run's label.
+   */
+  run?: (name: string, next: () => Promise<void>) => Promise<void>;
+}
+interface Hooks {
+  interceptor?: Interceptor;
+}
+/**
+ * Factory called on every attempt. Receives the invocation request,
+ * returns hooks for that attempt's lifetime. Each attempt gets a fresh call.
+ */
+type HooksProvider = (ctx: {
+  request: Request;
+}) => Hooks;
+//#endregion
+export { Hooks, HooksProvider, Interceptor };
+//# sourceMappingURL=hooks.d.cts.map

package/dist/hooks.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.cts","names":[],"sources":["../src/hooks.ts"],"sourcesContent":[],"mappings":";;;;;;AAgEA;;;;;;AAaA;AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAvBiB,WAAA;;yBAEQ,kBAAkB;;;;;;mCAMR,kBAAkB;;UAKpC,KAAA;gBACD;;;;;;KASJ,aAAA;WAAiC;MAAc"}

package/dist/hooks.d.ts

@@ -0,0 +1,87 @@
+import { Request } from "./context.js";
+
+//#region src/hooks.d.ts
+
+/**
+ * Interceptors wrap handler and ctx.run() execution. They are part of the
+ * invocation — anything that happens inside them (including after `next()`)
+ * affects the invocation outcome.
+ *
+ * ## Error behavior
+ *
+ * Errors thrown at any point (before or after `next()`) affect the invocation:
+ *
+ * - **{@link TerminalError}** — the invocation **fails immediately**, no retry.
+ * - **Any other error** — Restate **retries** the invocation.
+ * - On suspension or pause, `next()` also rejects with an error. This does not
+ *   mean the invocation failed — the attempt is simply ending. Do any cleanup
+ *   you need and rethrow.
+ *
+ * ## Output
+ *
+ * Interceptors **cannot alter the handler's success return value** (the `void`
+ * signature means there is no way to replace it), but they **can transform
+ * errors** by catching and rethrowing a different error.
+ *
+ * ## Rules
+ *
+ * - `next()` must be called exactly once.
+ *
+ * ## When interceptors fire
+ *
+ * - `handler` fires on every attempt.
+ * - `run` fires when the `ctx.run()` closure executes. If the result is
+ *   already in the journal, the closure is skipped and so is the interceptor.
+ *
+ * @example
+ * ```ts
+ * interceptor: {
+ *   handler: async (next) => {
+ *     console.log(`before ${ctx.request.target}`);
+ *     try {
+ *       await next();
+ *       console.log(`after ${ctx.request.target}`);
+ *     } catch (e) {
+ *       console.log(`error ${ctx.request.target}: ${e}`);
+ *       // Always rethrow — swallowing the error changes the
+ *       // invocation outcome. You can also throw a different
+ *       // error (e.g. TerminalError to fail immediately).
+ *       throw e;
+ *     }
+ *   },
+ *   run: async (name, next) => {
+ *     console.log(`  before run "${name}"`);
+ *     try {
+ *       await next();
+ *       console.log(`  after run "${name}"`);
+ *     } catch (e) {
+ *       console.log(`  error run "${name}": ${e}`);
+ *       throw e;
+ *     }
+ *   },
+ * }
+ * ```
+ */
+interface Interceptor {
+  /** Wraps the entire handler invocation. Fires on every attempt. */
+  handler?: (next: () => Promise<void>) => Promise<void>;
+  /**
+   * Wraps each `ctx.run()` call. Only fires for runs that actually execute —
+   * replayed runs (already in the journal) are skipped.
+   * `name` is the run's label.
+   */
+  run?: (name: string, next: () => Promise<void>) => Promise<void>;
+}
+interface Hooks {
+  interceptor?: Interceptor;
+}
+/**
+ * Factory called on every attempt. Receives the invocation request,
+ * returns hooks for that attempt's lifetime. Each attempt gets a fresh call.
+ */
+type HooksProvider = (ctx: {
+  request: Request;
+}) => Hooks;
+//#endregion
+export { Hooks, HooksProvider, Interceptor };
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","names":[],"sources":["../src/hooks.ts"],"sourcesContent":[],"mappings":";;;;;;AAgEA;;;;;;AAaA;AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAvBiB,WAAA;;yBAEQ,kBAAkB;;;;;;mCAMR,kBAAkB;;UAKpC,KAAA;gBACD;;;;;;KASJ,aAAA;WAAiC;MAAc"}

package/dist/hooks.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":""}

package/dist/index.cjs

@@ -1,7 +1,8 @@
 const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
 const require_errors = require('./types/errors.cjs');
-const require_rpc = require('./types/rpc.cjs');
+const require_promises = require('./promises.cjs');
 const require_context = require('./context.cjs');
+const require_rpc = require('./types/rpc.cjs');
 const require_internal = require('./internal.cjs');
 const require_common_api = require('./common_api.cjs');
 const require_node = require('./node.cjs');
@@ -37,6 +38,7 @@ Object.defineProperty(exports, 'internal', {
     return require_internal.internal_exports;
   }
 });
+exports.isRestatePromise = require_promises.isRestatePromise;
 exports.object = require_rpc.object;
 Object.defineProperty(exports, 'rpc', {
   enumerable: true,

package/dist/index.d.cts

@@ -1,10 +1,12 @@
 import { CancelledError, RestateError, RetryableError, RetryableErrorOptions, TerminalError, TimeoutError } from "./types/errors.cjs";
+import { Hooks, HooksProvider, Interceptor } from "./hooks.cjs";
 import { Client, ClientCallOptions, ClientSendOptions, InferArg, ObjectHandlerOpts, ObjectOptions, ObjectOpts, Opts, RemoveVoidArgument, RetryPolicy, SendClient, SendOpts, ServiceHandlerOpts, ServiceOptions, ServiceOpts, WorkflowHandlerOpts, WorkflowOptions, WorkflowOpts, handlers, object, rpc, service, workflow } from "./types/rpc.cjs";
-import { Context, ContextDate, DurablePromise, GenericCall, GenericSend, InvocationHandle, InvocationId, InvocationIdParser, InvocationPromise, KeyValueStore, ObjectContext, ObjectSharedContext, Rand, Request, RestatePromise, RunAction, RunOptions, SendOptions, TypedState, UntypedState, WorkflowContext, WorkflowSharedContext } from "./context.cjs";
+import { Context, ContextDate, DurablePromise, GenericCall, GenericSend, InvocationHandle, InvocationId, InvocationIdParser, InvocationPromise, KeyValueStore, ObjectContext, ObjectSharedContext, Rand, Request, RestatePromise, RunAction, RunOptions, Target, TypedState, UntypedState, WorkflowContext, WorkflowSharedContext } from "./context.cjs";
+import { internal_d_exports } from "./internal.cjs";
 import { LogMetadata, LogSource, LoggerContext, LoggerTransport, RestateLogLevel } from "./logging/logger_transport.cjs";
 import { DefaultServiceOptions, RestateEndpoint, RestateEndpointBase } from "./endpoint.cjs";
+import { isRestatePromise } from "./promises.cjs";
 import { EndpointOptions } from "./endpoint/types.cjs";
-import { internal_d_exports } from "./internal.cjs";
 import { CombineablePromise, Duration, JournalValueCodec, ObjectHandler, RestateContext, RestateObjectContext, RestateObjectSharedContext, RestateWorkflowContext, RestateWorkflowSharedContext, Serde, Service, ServiceDefinition, ServiceDefinitionFrom, ServiceHandler, VirtualObject, VirtualObjectDefinition, VirtualObjectDefinitionFrom, Workflow, WorkflowDefinition, WorkflowDefinitionFrom, WorkflowHandler, WorkflowSharedHandler, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, serde } from "./common_api.cjs";
-import { ServeOptions, createEndpointHandler, endpoint, serve } from "./node.cjs";
-export { CancelledError, Client, ClientCallOptions, ClientSendOptions, CombineablePromise, Context, ContextDate, DefaultServiceOptions, DurablePromise, Duration, EndpointOptions, GenericCall, GenericSend, InferArg, InvocationHandle, InvocationId, InvocationIdParser, InvocationPromise, JournalValueCodec, KeyValueStore, LogMetadata, LogSource, LoggerContext, LoggerTransport, ObjectContext, ObjectHandler, ObjectHandlerOpts, ObjectOptions, ObjectOpts, ObjectSharedContext, Opts, Rand, RemoveVoidArgument, Request, RestateContext, RestateEndpoint, RestateEndpointBase, RestateError, RestateLogLevel, RestateObjectContext, RestateObjectSharedContext, RestatePromise, RestateWorkflowContext, RestateWorkflowSharedContext, RetryPolicy, RetryableError, RetryableErrorOptions, RunAction, RunOptions, SendClient, SendOptions, SendOpts, Serde, ServeOptions, Service, ServiceDefinition, ServiceDefinitionFrom, ServiceHandler, ServiceHandlerOpts, ServiceOptions, ServiceOpts, TerminalError, TimeoutError, TypedState, UntypedState, VirtualObject, VirtualObjectDefinition, VirtualObjectDefinitionFrom, Workflow, WorkflowContext, WorkflowDefinition, WorkflowDefinitionFrom, WorkflowHandler, WorkflowHandlerOpts, WorkflowOptions, WorkflowOpts, WorkflowSharedContext, WorkflowSharedHandler, createEndpointHandler, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, endpoint, handlers, internal_d_exports as internal, object, rpc, serde, serve, service, workflow };
+import { NodeEndpointOptions, ServeOptions, createEndpointHandler, endpoint, serve } from "./node.cjs";
+export { CancelledError, Client, ClientCallOptions, ClientSendOptions, CombineablePromise, Context, ContextDate, DefaultServiceOptions, DurablePromise, Duration, EndpointOptions, GenericCall, GenericSend, Hooks, HooksProvider, InferArg, Interceptor, InvocationHandle, InvocationId, InvocationIdParser, InvocationPromise, JournalValueCodec, KeyValueStore, LogMetadata, LogSource, LoggerContext, LoggerTransport, NodeEndpointOptions, ObjectContext, ObjectHandler, ObjectHandlerOpts, ObjectOptions, ObjectOpts, ObjectSharedContext, Opts, Rand, RemoveVoidArgument, Request, RestateContext, RestateEndpoint, RestateEndpointBase, RestateError, RestateLogLevel, RestateObjectContext, RestateObjectSharedContext, RestatePromise, RestateWorkflowContext, RestateWorkflowSharedContext, RetryPolicy, RetryableError, RetryableErrorOptions, RunAction, RunOptions, SendClient, SendOpts, Serde, ServeOptions, Service, ServiceDefinition, ServiceDefinitionFrom, ServiceHandler, ServiceHandlerOpts, ServiceOptions, ServiceOpts, Target, TerminalError, TimeoutError, TypedState, UntypedState, VirtualObject, VirtualObjectDefinition, VirtualObjectDefinitionFrom, Workflow, WorkflowContext, WorkflowDefinition, WorkflowDefinitionFrom, WorkflowHandler, WorkflowHandlerOpts, WorkflowOptions, WorkflowOpts, WorkflowSharedContext, WorkflowSharedHandler, createEndpointHandler, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, endpoint, handlers, internal_d_exports as internal, isRestatePromise, object, rpc, serde, serve, service, workflow };

package/dist/index.d.ts

@@ -1,10 +1,12 @@
 import { CancelledError, RestateError, RetryableError, RetryableErrorOptions, TerminalError, TimeoutError } from "./types/errors.js";
+import { Hooks, HooksProvider, Interceptor } from "./hooks.js";
 import { Client, ClientCallOptions, ClientSendOptions, InferArg, ObjectHandlerOpts, ObjectOptions, ObjectOpts, Opts, RemoveVoidArgument, RetryPolicy, SendClient, SendOpts, ServiceHandlerOpts, ServiceOptions, ServiceOpts, WorkflowHandlerOpts, WorkflowOptions, WorkflowOpts, handlers, object, rpc, service, workflow } from "./types/rpc.js";
-import { Context, ContextDate, DurablePromise, GenericCall, GenericSend, InvocationHandle, InvocationId, InvocationIdParser, InvocationPromise, KeyValueStore, ObjectContext, ObjectSharedContext, Rand, Request, RestatePromise, RunAction, RunOptions, SendOptions, TypedState, UntypedState, WorkflowContext, WorkflowSharedContext } from "./context.js";
+import { Context, ContextDate, DurablePromise, GenericCall, GenericSend, InvocationHandle, InvocationId, InvocationIdParser, InvocationPromise, KeyValueStore, ObjectContext, ObjectSharedContext, Rand, Request, RestatePromise, RunAction, RunOptions, Target, TypedState, UntypedState, WorkflowContext, WorkflowSharedContext } from "./context.js";
+import { internal_d_exports } from "./internal.js";
 import { LogMetadata, LogSource, LoggerContext, LoggerTransport, RestateLogLevel } from "./logging/logger_transport.js";
 import { DefaultServiceOptions, RestateEndpoint, RestateEndpointBase } from "./endpoint.js";
+import { isRestatePromise } from "./promises.js";
 import { EndpointOptions } from "./endpoint/types.js";
-import { internal_d_exports } from "./internal.js";
 import { CombineablePromise, Duration, JournalValueCodec, ObjectHandler, RestateContext, RestateObjectContext, RestateObjectSharedContext, RestateWorkflowContext, RestateWorkflowSharedContext, Serde, Service, ServiceDefinition, ServiceDefinitionFrom, ServiceHandler, VirtualObject, VirtualObjectDefinition, VirtualObjectDefinitionFrom, Workflow, WorkflowDefinition, WorkflowDefinitionFrom, WorkflowHandler, WorkflowSharedHandler, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, serde } from "./common_api.js";
-import { ServeOptions, createEndpointHandler, endpoint, serve } from "./node.js";
-export { CancelledError, Client, ClientCallOptions, ClientSendOptions, CombineablePromise, Context, ContextDate, DefaultServiceOptions, DurablePromise, Duration, EndpointOptions, GenericCall, GenericSend, InferArg, InvocationHandle, InvocationId, InvocationIdParser, InvocationPromise, JournalValueCodec, KeyValueStore, LogMetadata, LogSource, LoggerContext, LoggerTransport, ObjectContext, ObjectHandler, ObjectHandlerOpts, ObjectOptions, ObjectOpts, ObjectSharedContext, Opts, Rand, RemoveVoidArgument, Request, RestateContext, RestateEndpoint, RestateEndpointBase, RestateError, RestateLogLevel, RestateObjectContext, RestateObjectSharedContext, RestatePromise, RestateWorkflowContext, RestateWorkflowSharedContext, RetryPolicy, RetryableError, RetryableErrorOptions, RunAction, RunOptions, SendClient, SendOptions, SendOpts, Serde, ServeOptions, Service, ServiceDefinition, ServiceDefinitionFrom, ServiceHandler, ServiceHandlerOpts, ServiceOptions, ServiceOpts, TerminalError, TimeoutError, TypedState, UntypedState, VirtualObject, VirtualObjectDefinition, VirtualObjectDefinitionFrom, Workflow, WorkflowContext, WorkflowDefinition, WorkflowDefinitionFrom, WorkflowHandler, WorkflowHandlerOpts, WorkflowOptions, WorkflowOpts, WorkflowSharedContext, WorkflowSharedHandler, createEndpointHandler, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, endpoint, handlers, internal_d_exports as internal, object, rpc, serde, serve, service, workflow };
+import { NodeEndpointOptions, ServeOptions, createEndpointHandler, endpoint, serve } from "./node.js";
+export { CancelledError, Client, ClientCallOptions, ClientSendOptions, CombineablePromise, Context, ContextDate, DefaultServiceOptions, DurablePromise, Duration, EndpointOptions, GenericCall, GenericSend, Hooks, HooksProvider, InferArg, Interceptor, InvocationHandle, InvocationId, InvocationIdParser, InvocationPromise, JournalValueCodec, KeyValueStore, LogMetadata, LogSource, LoggerContext, LoggerTransport, NodeEndpointOptions, ObjectContext, ObjectHandler, ObjectHandlerOpts, ObjectOptions, ObjectOpts, ObjectSharedContext, Opts, Rand, RemoveVoidArgument, Request, RestateContext, RestateEndpoint, RestateEndpointBase, RestateError, RestateLogLevel, RestateObjectContext, RestateObjectSharedContext, RestatePromise, RestateWorkflowContext, RestateWorkflowSharedContext, RetryPolicy, RetryableError, RetryableErrorOptions, RunAction, RunOptions, SendClient, SendOpts, Serde, ServeOptions, Service, ServiceDefinition, ServiceDefinitionFrom, ServiceHandler, ServiceHandlerOpts, ServiceOptions, ServiceOpts, Target, TerminalError, TimeoutError, TypedState, UntypedState, VirtualObject, VirtualObjectDefinition, VirtualObjectDefinitionFrom, Workflow, WorkflowContext, WorkflowDefinition, WorkflowDefinitionFrom, WorkflowHandler, WorkflowHandlerOpts, WorkflowOptions, WorkflowOpts, WorkflowSharedContext, WorkflowSharedHandler, createEndpointHandler, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, endpoint, handlers, internal_d_exports as internal, isRestatePromise, object, rpc, serde, serve, service, workflow };

package/dist/index.js

@@ -1,8 +1,9 @@
 import { CancelledError, RestateError, RetryableError, TerminalError, TimeoutError } from "./types/errors.js";
-import { Opts, SendOpts, handlers, object, rpc, service, workflow } from "./types/rpc.js";
+import { isRestatePromise } from "./promises.js";
 import { InvocationIdParser, RestatePromise } from "./context.js";
+import { Opts, SendOpts, handlers, object, rpc, service, workflow } from "./types/rpc.js";
 import { internal_exports } from "./internal.js";
 import { CombineablePromise, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, serde } from "./common_api.js";
 import { createEndpointHandler, endpoint, serve } from "./node.js";
 
-export { CancelledError, CombineablePromise, InvocationIdParser, Opts, RestateError, RestatePromise, RetryableError, SendOpts, TerminalError, TimeoutError, createEndpointHandler, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, endpoint, handlers, internal_exports as internal, object, rpc, serde, serve, service, workflow };
+export { CancelledError, CombineablePromise, InvocationIdParser, Opts, RestateError, RestatePromise, RetryableError, SendOpts, TerminalError, TimeoutError, createEndpointHandler, createObjectHandler, createObjectSharedHandler, createServiceHandler, createWorkflowHandler, createWorkflowSharedHandler, endpoint, handlers, internal_exports as internal, isRestatePromise, object, rpc, serde, serve, service, workflow };

package/dist/internal.cjs

@@ -1,6 +1,8 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_errors = require('./types/errors.cjs');
 
 //#region src/internal.ts
-var internal_exports = {};
+var internal_exports = /* @__PURE__ */ require_rolldown_runtime.__export({ isSuspendedError: () => require_errors.isSuspendedError });
 
 //#endregion
 Object.defineProperty(exports, 'internal_exports', {

package/dist/internal.d.cts

@@ -1,8 +1,10 @@
-import { Context } from "./context.cjs";
+import { TerminalError, isSuspendedError } from "./types/errors.cjs";
+import { Context, InvocationId, RestatePromise } from "./context.cjs";
+import { Serde } from "@restatedev/restate-sdk-core";
 
 //#region src/internal.d.ts
 declare namespace internal_d_exports {
-  export { ContextInternal };
+  export { ContextInternal, InvocationReference, SignalReference, isSuspendedError };
 }
 /**
  * Internal {@link Context} interface exposing additional features.
@@ -21,6 +23,188 @@ interface ContextInternal extends Context {
    * @experimental
    */
   isProcessing(): boolean;
+  /**
+   * Returns a {@link RestatePromise} that resolves with `undefined` when Restate signals cancellation
+   * of the current invocation.
+   *
+   * This method **MUST** only be used when the handler (or its parent service/endpoint) is configured
+   * with `explicitCancellation: true`. Without configuring this option, cancellations are propagated automatically,
+   * and this promise will **NEVER** resolve.
+   *
+   * **Promise reuse:** calling this method multiple times returns the **same** promise instance as long as
+   * the current cancellation signal has not yet arrived. Once the promise resolves (cancellation received),
+   * later calls return a **new** promise that will resolve on the next cancellation signal.
+   *
+   * @example Race a long-running side effect against cancellation
+   * ```ts
+   * const greeter = restate.service({
+   *   name: "greeter",
+   *   handlers: {
+   *     greet: async (ctx: restate.Context, name: string) => {
+   *       ctxInternal = ctx as restate.internal.ContextInternal;
+   *       const result = await RestatePromise.race([
+   *         ctx.run(() => longRunningTask(name)),
+   *         ctxInternal.cancellation().map(() => { throw new restate.TerminalError("Cancelled") }),
+   *       ]);
+   *       return result;
+   *     },
+   *   },
+   *   options: { explicitCancellation: true },
+   * });
+   * ```
+   *
+   * @example Use the cancellation promise to create an AbortSignal for ctx.run
+   * ```ts
+   * const greeter = restate.service({
+   *   name: "greeter",
+   *   handlers: {
+   *     greet: async (ctx: restate.Context, name: string) => {
+   *       const ctxInternal = ctx as restate.internal.ContextInternal;
+   *       const controller = new AbortController();
+   *       const cancellation = ctxInternal.cancellation()
+   *         .map(() => {
+   *            controller.abort();
+   *            throw new restate.TerminalError("Cancelled");
+   *         });
+   *
+   *       return RestatePromise.race([
+   *         ctx.run(() => fetch(`https://api.example.com/greet/${name}`, { signal: controller.signal })),
+   *         cancellation,
+   *       ]);
+   *     },
+   *   },
+   *   options: { explicitCancellation: true },
+   * });
+   * ```
+   *
+   * @example Handle cancellation, perform cleanup, then listen for the next cancellation
+   * ```ts
+   * const greeter = restate.service({
+   *   name: "greeter",
+   *   handlers: {
+   *     greet: async (ctx: restate.Context, name: string) => {
+   *       const ctxInternal = ctx as restate.internal.ContextInternal;
+   *       try {
+   *         return await RestatePromise.race([
+   *           ctx.run(() => longRunningTask(name)),
+   *           ctxInternal.cancellation().map(() => { throw new restate.TerminalError("Cancelled") }),
+   *         ]);
+   *       } catch (e) {
+   *         // Perform cleanup
+   *         await ctx.run(() => cleanupResources(name));
+   *
+   *         // After cancellation is resolved, ctx.cancellation() returns a fresh promise.
+   *         // Race cleanup confirmation against the next cancellation signal.
+   *         await RestatePromise.race([
+   *           ctx.run(() => confirmCleanup(name)),
+   *           ctxInternal.cancellation().map(() => { throw new restate.TerminalError("Canceled during cleanup") }),
+   *         ]);
+   *       }
+   *     },
+   *   },
+   *   options: { explicitCancellation: true },
+   * });
+   * ```
+   *
+   * @experimental
+   */
+  cancellation(): RestatePromise<void>;
+  /**
+   * Cancel all previous calls made from this handler.
+   *
+   * This method **MUST** only be used when the handler (or its parent service/endpoint) is configured
+   * with `explicitCancellation: true`. Without configuring this option, this operation will always be a no-op.
+   *
+   * @return the invocation id of the canceled calls.
+   * @experimental
+   */
+  cancelPreviousCalls(): RestatePromise<InvocationId[]>;
+  /**
+   * Wait for a named signal to arrive on the current invocation.
+   *
+   * Signals are identified by name and are scoped to the current invocation.
+   * Another handler can send a signal to this invocation using
+   * {@link InvocationReference.signal}, specifying this invocation's
+   * ID (available via `ctx.request().id`) and the same signal name.
+   *
+   * @param name the name of the signal to wait for.
+   * @param serde optional custom serializer/deserializer for the payload.
+   * @returns a {@link RestatePromise} that resolves when the signal arrives.
+   *
+   * @example
+   * const ctxInternal = ctx as restate.internal.ContextInternal;
+   * const approved = await ctxInternal.signal<boolean>("approved");
+   *
+   * @experimental
+   */
+  signal<T>(name: string, serde?: Serde<T>): RestatePromise<T>;
+  /**
+   * Get a reference to a target invocation, to send signals to it.
+   *
+   * @param invocationId the invocation ID of the target invocation.
+   * @returns an {@link InvocationReference} for the target invocation.
+   *
+   * @example
+   * const ctxInternal = ctx as restate.internal.ContextInternal;
+   * const target = ctxInternal.invocation(targetInvocationId);
+   * target.signal("approved").resolve(true);
+   * target.signal("approved").reject("Request denied");
+   *
+   * @experimental
+   */
+  invocation(invocationId: InvocationId): InvocationReference;
+}
+/**
+ * A reference to a target invocation, used to send signals.
+ *
+ * @experimental
+ */
+interface InvocationReference {
+  /**
+   * Get a handle to a named signal on the target invocation.
+   *
+   * @param name the name of the signal.
+   * @param serde optional custom serializer/deserializer for the payload.
+   * @returns a {@link SignalReference} to resolve or reject the signal.
+   *
+   * @experimental
+   */
+  signal<T>(name: string, serde?: Serde<T>): SignalReference<T>;
+  /**
+   * Cancel the target invocation.
+   */
+  cancel(): void;
+  /**
+   * Attach to the target invocation and wait for its result.
+   *
+   * @param serde optional custom serializer/deserializer for the result.
+   * @returns a {@link RestatePromise} that resolves with the invocation result.
+   */
+  attach<T>(serde?: Serde<T>): RestatePromise<T>;
+}
+/**
+ * A handle to send a signal value to a target invocation.
+ *
+ * @experimental
+ */
+interface SignalReference<T> {
+  /**
+   * Resolve the signal with a value.
+   *
+   * @param payload the payload to send.
+   *
+   * @experimental
+   */
+  resolve(payload?: T): void;
+  /**
+   * Reject the signal. The target invocation waiting on this signal will be
+   * woken up with a terminal error containing the provided reason.
+   *
+   * @param reason the reason for rejection, either a string message or a {@link TerminalError}.
+   *
+   * @experimental
+   */
+  reject(reason: string | TerminalError): void;
 }
 //#endregion
 export { internal_d_exports };

package/dist/internal.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"internal.d.cts","names":[],"sources":["../src/internal.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AASA;;;UAAiB,eAAA,SAAwB"}
+{"version":3,"file":"internal.d.cts","names":[],"sources":["../src/internal.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;UAaiB,eAAA,SAAwB;EAAxB;;;;;;;;EA+IU,YAAA,EAAA,EAAA,OAAA;EAAe;;;AAQ1C;;;;;;;;;;AA+BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAtFkB;;;;;;;;;;yBAWO,eAAe;;;;;;;;;;;;;;;;;;;kCAoBN,MAAM,KAAK,eAAe;;;;;;;;;;;;;;;2BAgBjC,eAAe;;;;;;;UAQzB,mBAAA;;;;;;;;;;kCAUiB,MAAM,KAAK,gBAAgB;;;;;;;;;;;oBAazC,MAAM,KAAK,eAAe;;;;;;;UAQ7B;;;;;;;;oBAQG;;;;;;;;;0BAUM"}