@restatedev/restate-sdk 1.11.1 → 1.12.0

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","names":[],"sources":["../src/context.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\nimport type { Client, SendClient } from \"./types/rpc.js\";\nimport type {\n  RestateContext,\n  RestateObjectContext,\n  RestateObjectSharedContext,\n  RestateWorkflowContext,\n  RestateWorkflowSharedContext,\n  Service,\n  ServiceDefinitionFrom,\n  VirtualObject,\n  VirtualObjectDefinitionFrom,\n  Workflow,\n  WorkflowDefinitionFrom,\n  Serde,\n  Duration,\n} from \"@restatedev/restate-sdk-core\";\nimport { ContextImpl } from \"./context_impl.js\";\nimport type { TerminalError } from \"./types/errors.js\";\n\n/**\n * Represents the original request as sent to this handler.\n *\n * A request object includes the request headers, and the raw unparsed\n * request body.\n */\nexport interface Request {\n  /**\n   * The unique id that identifies the current function invocation. This id is guaranteed to be\n   * unique across invocations, but constant across reties and suspensions.\n   */\n  readonly id: string;\n\n  /**\n   * Request headers - the following headers capture the original invocation headers, as provided to\n   * the ingress.\n   */\n  readonly headers: ReadonlyMap<string, string>;\n\n  /**\n   * Attempt headers - the following headers are sent by the restate runtime.\n   * These headers are attempt specific, generated by the restate runtime uniquely for each attempt.\n   * These headers might contain information such as the W3C trace context, and attempt specific information.\n   */\n  readonly attemptHeaders: ReadonlyMap<string, string | string[] | undefined>;\n\n  /**\n   * Raw unparsed request body\n   */\n  readonly body: Uint8Array;\n\n  /**\n   * Extra arguments provided to the request handler:\n   * Lambda: [Context]\n   * Cloudflare workers: [Env, ExecutionContext]\n   * Deno: [ConnInfo]\n   * Bun: [Server]\n   * These arguments can contain request-specific values that could change after a suspension.\n   * Care should be taken to use them deterministically.\n   */\n  readonly extraArgs: unknown[];\n\n  /**\n   * This is a signal that is aborted when the current attempt has been completed either successful or unsuccessfully.\n   * When the signal is aborted, the current attempt has been completed and the handler should not perform any more work, other\n   * than cleanup any external resources that might be shared across attempts (e.g. database connections).\n   */\n  readonly attemptCompletedSignal: AbortSignal;\n}\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\nexport type TypedState = Record<string, any>;\nexport type UntypedState = { _: never };\n\n/**\n * Key value store operations. Only keyed services have an attached key-value store.\n */\nexport interface KeyValueStore<TState extends TypedState> {\n  /**\n   * Get/retrieve state from the Restate runtime.\n   * Note that state objects are serialized with `Buffer.from(JSON.stringify(theObject))`\n   * and deserialized with `JSON.parse(value.toString()) as T`.\n   *\n   * @param name key of the state to retrieve\n   * @returns a Promise that is resolved with the value of the state key\n   *\n   * @example\n   * const state = await ctx.get<string>(\"STATE\");\n   */\n  get<TValue, TKey extends keyof TState = string>(\n    name: TState extends UntypedState ? string : TKey,\n    serde?: Serde<TState extends UntypedState ? TValue : TState[TKey]>\n  ): Promise<(TState extends UntypedState ? TValue : TState[TKey]) | null>;\n\n  stateKeys(): Promise<Array<string>>;\n\n  /**\n   * Set/store state in the Restate runtime.\n   * Note that state objects are serialized with `Buffer.from(JSON.stringify(theObject))`\n   * and deserialized with `JSON.parse(value.toString()) as T`.\n   *\n   * @param name key of the state to set\n   * @param value value to set\n   *\n   * @example\n   * ctx.set(\"STATE\", \"Hello\");\n   */\n  set<TValue, TKey extends keyof TState = string>(\n    name: TState extends UntypedState ? string : TKey,\n    value: TState extends UntypedState ? TValue : TState[TKey],\n    serde?: Serde<TState extends UntypedState ? TValue : TState[TKey]>\n  ): void;\n\n  /**\n   * Clear/delete state in the Restate runtime.\n   * @param name key of the state to delete\n   *\n   * @example\n   * ctx.clear(\"STATE\");\n   */\n  clear<TKey extends keyof TState>(\n    name: TState extends UntypedState ? string : TKey\n  ): void;\n\n  /**\n   * Clear/delete all the state entries in the Restate runtime.\n   *\n   * @example\n   * ctx.clearAll();\n   */\n  clearAll(): void;\n}\n\n/**\n * @deprecated SendOptions on the client factory are deprecated, please use `restate.rpc.sendOpts` instead\n */\nexport interface SendOptions {\n  /**\n   * @deprecated SendOptions on the client factory are deprecated, please use `restate.rpc.sendOpts` instead\n   */\n  delay?: number;\n}\n\nexport interface ContextDate {\n  /** Returns the number of milliseconds elapsed since midnight, January 1, 1970 Universal Coordinated Time (UTC).\n   *  This is equivalent to Date.now()\n   */\n  now(): Promise<number>;\n  /** Returns the JSON representation of the current date.\n   * This is equivalent to new Date().toJSON()\n   **/\n  toJSON(): Promise<string>;\n}\n\n/**\n * A function that can be run and its result durably persisted by Restate.\n */\nexport type RunAction<T> = (() => Promise<T>) | (() => T);\n\nexport type RunOptions<T> = {\n  serde?: Serde<T>;\n\n  /**\n   * Max number of attempts (including the initial), before giving up.\n   *\n   * When giving up, `ctx.run` will throw a `TerminalError` wrapping the original error message.\n   */\n  maxRetryAttempts?: number;\n\n  /**\n   * @deprecated Use `maxRetryDuration` instead.\n   */\n  maxRetryDurationMillis?: number;\n\n  /**\n   * Max duration of retries, before giving up.\n   *\n   * When giving up, `ctx.run` will throw a `TerminalError` wrapping the original error message.\n   *\n   * If a number is provided, it will be interpreted as milliseconds.\n   */\n  maxRetryDuration?: Duration | number;\n\n  /**\n   * @deprecated Use `initialRetryInterval` instead.\n   */\n  initialRetryIntervalMillis?: number;\n\n  /**\n   * Initial interval for the first retry attempt.\n   * Retry interval will grow by a factor specified in `retryIntervalFactor`.\n   *\n   * The default is 50 milliseconds.\n   *\n   * If a number is provided, it will be interpreted as milliseconds.\n   */\n  initialRetryInterval?: Duration | number;\n\n  /**\n   * @deprecated Use `maxRetryInterval` instead.\n   */\n  maxRetryIntervalMillis?: number;\n\n  /**\n   * Max interval between retries.\n   * Retry interval will grow by a factor specified in `retryIntervalFactor`.\n   *\n   * The default is 10 seconds.\n   *\n   * If a number is provided, it will be interpreted as milliseconds.\n   */\n  maxRetryInterval?: Duration | number;\n\n  /**\n   * Exponentiation factor to use when computing the next retry delay.\n   *\n   * The default value is `2`, meaning retry interval will double at each attempt.\n   */\n  retryIntervalFactor?: number;\n};\n\n/**\n * Call a handler directly avoiding restate's type safety checks.\n * This is a generic mechanism to invoke handlers directly by only knowing\n * the service and handler name, (or key in the case of objects or workflows)\n */\nexport type GenericCall<REQ, RES> = {\n  service: string;\n  method: string;\n  parameter: REQ;\n  key?: string;\n  headers?: Record<string, string>;\n  inputSerde?: Serde<REQ>;\n  outputSerde?: Serde<RES>;\n  idempotencyKey?: string;\n  /**\n   * Observability name, recorded in the Restate journal.\n   */\n  name?: string;\n};\n\n/**\n * Send a message to an handler directly avoiding restate's type safety checks.\n * This is a generic mechanism to invoke handlers directly by only knowing\n * the service and handler name, (or key in the case of objects or workflows)\n */\nexport type GenericSend<REQ> = {\n  service: string;\n  method: string;\n  parameter: REQ;\n  key?: string;\n  headers?: Record<string, string>;\n  inputSerde?: Serde<REQ>;\n  delay?: Duration | number;\n  idempotencyKey?: string;\n  /**\n   * Observability name, recorded in the Restate journal.\n   */\n  name?: string;\n};\n\n/**\n * The context that gives access to all Restate-backed operations, for example\n *   - sending reliable messages / RPC through Restate\n *   - execute non-deterministic closures and memoize their result\n *   - sleeps and delayed calls\n *   - awakeables\n *   - ...\n *\n * Virtual objects can also access their key-value store using the {@link ObjectContext}.\n *\n */\nexport interface Context extends RestateContext {\n  /**\n   * Deterministic random methods; these are inherently predictable (seeded on the invocation ID, which is not secret)\n   * and so should not be used for any cryptographic purposes. They are useful for identifiers, idempotency keys,\n   * and for uniform sampling from a set of options. If a cryptographically secure value is needed, please generate that\n   * externally and capture the result with a side effect.\n   *\n   * Calls to these methods from inside `ctx.run` are disallowed and will fail - side effects must be idempotent, and\n   * these calls are not.\n   */\n  rand: Rand;\n\n  /**\n   * Console to use for logging. It attaches to each log message some contextual information,\n   * such as invoked service method and invocation id, and automatically excludes logs during replay.\n   */\n  console: Console;\n\n  /**\n   * Deterministic date.\n   */\n  date: ContextDate;\n\n  /**\n   * Run an operation and store the result in Restate. The operation will thus not\n   * be re-run during a later replay, but take the durable result from Restate.\n   *\n   * This let you capture potentially non-deterministic computation and interaction\n   * with external systems in a safe way.\n   *\n   * Failure semantics are:\n   *   - If an operation has run and persisted before, the result (value or Error) will be\n   *     taken from the Restate journal.\n   *   - There is a small window where an action may be re-run, if a failure\n   *     occurred between a successful run and persisting the result.\n   *   - No second action will be run while a previous run's result is not\n   *     yet durable. That way, effects that build on top of each other can assume\n   *     deterministic results from previous runs, and at most one run will be\n   *     re-executed on replay (the latest, if the failure happened in the small windows\n   *     described above).\n   *\n   * You can customize retry options by either:\n   *\n   * - Providing retry policy options in {@link RunOptions}\n   * - Throwing {@link RetryableError}, providing `retryAfter` option. This can be especially useful when interacting with HTTP requests returning the `Retry-After` header. You can combine the usage of throwing {@link RetryableError} with the `maxRetryAttempts`/`maxRetryDuration` from {@link RunOptions}.\n   *\n   * @example Run some external action and persist its result\n   * ```ts\n   * const result = await ctx.run(someExternalAction)\n   *```\n   * @example Add some retry options\n   * ```ts\n   * const result = await ctx.run(\"my action\", someExternalAction, { maxRetryAttempts: 10 })\n   * ```\n   * @example Terminal errors and retryable errors\n   * ```ts\n   * await ctx.run(\"payment action\", async () => {\n   *   const result = await paymentProvider.charge(txId, paymentInfo);\n   *   if (result.paymentRejected) {\n   *     // this action will not be retried anymore\n   *     throw new TerminalError(\"Payment failed\");\n   *   } else if (result.paymentGatewayBusy) {\n   *     // restate will retry automatically\n   *     // to bound retries, use RunOptions\n   *     throw new Error(\"Payment gateway busy\");\n   *   } else {\n   *     // success!\n   *   }\n   * });\n   * ```\n   * @example Retryable error with custom retry delay\n   * ```ts\n   * await ctx.run(\"payment action\", async () => {\n   *   const res = fetch(...);\n   *   if (!res.ok) {\n   *     // Read Retry-After header\n   *     const retryAfterHeader = res.headers['Retry-After']\n   *\n   *     // Use RetryableError to customize in how long to retry\n   *     throw RetryableError.from(cause, { retryAfter: { seconds: retryAfterHeader } })\n   *   }\n   * }, {\n   *   // Retry at most ten times\n   *   maxRetryAttempts: 10\n   * });\n   * ```\n   *\n   * @param action The function to run.\n   */\n  run<T>(action: RunAction<T>): RestatePromise<T>;\n\n  /**\n   * Same as {@link run}, but providing a name, used for observability purposes.\n   */\n  run<T>(name: string, action: RunAction<T>): RestatePromise<T>;\n\n  /**\n   * See {@link run}\n   */\n  run<T>(\n    name: string,\n    action: RunAction<T>,\n    options: RunOptions<T>\n  ): RestatePromise<T>;\n\n  /**\n   * Register an awakeable and pause the processing until the awakeable ID (and optional payload) have been returned to the service\n   * (via ctx.completeAwakeable(...)). The SDK deserializes the payload with `JSON.parse(result.toString()) as T`.\n   * @returns\n   * - id: the string ID that has to be used to complete the awakaeble by some external service\n   * - promise: the Promise that needs to be awaited and that is resolved with the payload that was supplied by the service which completed the awakeable\n   * @example Retryable errors and terminal errors\n   * const awakeable = ctx.awakeable<string>();\n   *\n   * // send the awakeable ID to some external service that will wake this one back up\n   * // The ID can be retrieved by:\n   * const id = awakeable.id;\n   *\n   * // ... send to external service ...\n   *\n   * // Wait for the external service to wake this service back up\n   * const result = await awakeable.promise;\n   */\n  awakeable<T>(serde?: Serde<T>): {\n    id: string;\n    promise: RestatePromise<T>;\n  };\n\n  /**\n   * Resolve an awakeable.\n   * @param id the string ID of the awakeable.\n   * This is supplied by the service that needs to be woken up.\n   * @param payload the payload to pass to the service that is woken up.\n   * The SDK serializes the payload with `Buffer.from(JSON.stringify(payload))`\n   * and deserializes it in the receiving service with `JSON.parse(result.toString()) as T`.\n   * @example Retryable error with custom retry delay\n   * // The sleeping service should have sent the awakeableIdentifier string to this service.\n   * ctx.resolveAwakeable(awakeableIdentifier, \"hello\");\n   */\n  resolveAwakeable<T>(id: string, payload?: T, serde?: Serde<T>): void;\n\n  /**\n   * Reject an awakeable. When rejecting, the service waiting on this awakeable will be woken up with a terminal error with the provided reason.\n   * @param id the string ID of the awakeable.\n   * This is supplied by the service that needs to be woken up.\n   * @param reason the reason of the rejection.\n   *\n   * @example\n   * // The sleeping service should have sent the awakeableIdentifier string to this service.\n   * ctx.rejectAwakeable(awakeableIdentifier, \"super bad error\");\n   */\n  rejectAwakeable(id: string, reason: string): void;\n\n  /**\n   * Sleep until a timeout has passed.\n   * @param duration either Duration type or milliseconds.\n   * @param name Observability name. This will be shown in the UI.\n   * This is a lower-bound.\n   *\n   * @example\n   * await ctx.sleep(1000);\n   */\n  sleep(duration: Duration | number, name?: string): RestatePromise<void>;\n\n  /**\n   * Makes a type-safe request/response RPC to the specified target service.\n   *\n   * The RPC goes through Restate and is guaranteed to be reliably delivered. The RPC is also\n   * journaled for durable execution and will thus not be duplicated when the handler is re-invoked\n   * for retries or after suspending.\n   *\n   * This call will return the result produced by the target handler, or the Error, if the target\n   * handler finishes with a Terminal Error.\n   *\n   * This call is a suspension point: The handler might suspend while awaiting the response and\n   * resume once the response is available.\n   *\n   * @example\n   * *Service Side:*\n   * ```ts\n   * const service = restate.service(\n   *   name: \"myservice\",\n   *   handlers: {\n   *    someAction:    async(ctx: restate.Context, req: string) => { ... },\n   *    anotherAction: async(ctx: restate.Context, count: number) => { ... }\n   * });\n   *\n   * // option 1: export only the type signature\n   * export type Service = typeof service;\n   *\n   *\n   * restate.serve({ services: [service], port: 9080 });\n   * ```\n   * *Client side:*\n   * ```ts\n   * // option 1: use only types and supply service name separately\n   * const result1 = await ctx.serviceClient<Service>({name: \"myservice\"}).someAction(\"hello!\");\n   *\n   * // option 2: use full API spec\n   * type MyService: Service = { name: \"myservice\" };\n   * const result2 = await ctx.serviceClient(Service).anotherAction(1337);\n   * ```\n   */\n  serviceClient<D>(opts: ServiceDefinitionFrom<D>): Client<Service<D>>;\n\n  /**\n   * Same as {@link serviceClient} but for virtual objects.\n   *\n   * @param opts\n   * @param key the virtual object key\n   */\n  objectClient<D>(\n    opts: VirtualObjectDefinitionFrom<D>,\n    key: string\n  ): Client<VirtualObject<D>>;\n\n  /**\n   * Same as {@link serviceClient} but for workflows.\n   *\n   * @param opts\n   * @param key the workflow key\n   */\n  workflowClient<D>(\n    opts: WorkflowDefinitionFrom<D>,\n    key: string\n  ): Client<Workflow<D>>;\n\n  /**\n   * Same as {@link objectSendClient} but for workflows.\n   *\n   * @param opts\n   * @param key the workflow key\n   */\n  workflowSendClient<D>(\n    opts: WorkflowDefinitionFrom<D>,\n    key: string\n  ): SendClient<Workflow<D>>;\n\n  /**\n   * Makes a type-safe one-way RPC to the specified target service. This method effectively behaves\n   * like enqueuing the message in a message queue.\n   *\n   * The message goes through Restate and is guaranteed to be reliably delivered. The RPC is also\n   * journaled for durable execution and will thus not be duplicated when the handler is re-invoked\n   * for retries or after suspending.\n   *\n   * This call will return immediately; the message sending happens asynchronously in the background.\n   * Despite that, the message is guaranteed to be sent, because the completion of the invocation that\n   * triggers the send (calls this function) happens logically after the sending. That means that any\n   * failure where the message does not reach Restate also cannot complete this invocation, and will\n   * hence recover this handler and (through the durable execution) recover the message to be sent.\n   *\n   * @example\n   * *Service Side:*\n   * ```ts\n   * const service = restate.service(\n   *   name: \"myservice\",\n   *   handlers: {\n   *    someAction:    async(ctx: restate.Context, req: string) => { ... },\n   *    anotherAction: async(ctx: restate.Context, count: number) => { ... }\n   * });\n   *\n   * // option 1: export only the type signature of the router\n   * export type MyApi = typeof service;\n   *\n   * // option 2: export the API definition with type and name (name)\n   * const MyService: MyApi = { name: \"myservice\" };\n   *\n   * restate.serve({ services: [service], port: 9080 });\n   * ```\n   * *Client side:*\n   * ```ts\n   * // option 1: use only types and supply service name separately\n   * ctx.serviceSendClient<MyApi>({name: \"myservice\"}).someAction(\"hello!\");\n   *\n   * // option 2: use full API spec\n   * ctx.serviceSendClient(MyService).anotherAction(1337);\n   * ```\n   */\n  serviceSendClient<D>(\n    service: ServiceDefinitionFrom<D>,\n    opts?: SendOptions\n  ): SendClient<Service<D>>;\n\n  /**\n   * Same as {@link serviceSendClient} but for virtual objects.\n   *\n   * @param obj\n   * @param key the virtual object key\n   * @param opts Send options\n   */\n  objectSendClient<D>(\n    obj: VirtualObjectDefinitionFrom<D>,\n    key: string,\n    opts?: SendOptions\n  ): SendClient<VirtualObject<D>>;\n\n  genericCall<REQ = Uint8Array, RES = Uint8Array>(\n    call: GenericCall<REQ, RES>\n  ): InvocationPromise<RES>;\n\n  genericSend<REQ = Uint8Array>(call: GenericSend<REQ>): InvocationHandle;\n\n  /**\n   * Returns the raw request that triggered that handler.\n   * Use that object to inspect the original request headers\n   */\n  request(): Request;\n\n  /**\n   * Cancel an invocation\n   *\n   * @param invocationId the invocation id to cancel\n   */\n  cancel(invocationId: InvocationId): void;\n\n  /**\n   * Attach to an invocation\n   *\n   * @param invocationId the invocation id to attach to\n   * @param serde the serde to use for the result, default to JSON serde.\n   */\n  attach<T>(invocationId: InvocationId, serde?: Serde<T>): RestatePromise<T>;\n}\n\n/**\n * The context that gives access to all Restate-backed operations, for example\n *   - sending reliable messages / RPC through Restate\n *   - access/update state\n *   - execute non-deterministic closures and memoize their result\n *   - sleeps and delayed calls\n *   - awakeables\n *   - ...\n *\n * This context can be used only within virtual objects.\n *\n */\nexport interface ObjectContext<TState extends TypedState = UntypedState>\n  extends Context, KeyValueStore<TState>, RestateObjectContext {\n  key: string;\n}\n\n/**\n * The context that gives access to all Restate-backed operations, for example\n *   - sending reliable messages / RPC through Restate\n *   - execute non-deterministic closures and memoize their result\n *   - sleeps and delayed calls\n *   - awakeables\n *   - ...\n *\n * This context can be used only within a shared virtual objects.\n *\n */\nexport interface ObjectSharedContext<TState extends TypedState = UntypedState>\n  extends Context, RestateObjectSharedContext {\n  key: string;\n\n  /**\n   * Get/retrieve state from the Restate runtime.\n   * Note that state objects are serialized with `Buffer.from(JSON.stringify(theObject))`\n   * and deserialized with `JSON.parse(value.toString()) as T`.\n   *\n   * @param name key of the state to retrieve\n   * @returns a Promise that is resolved with the value of the state key\n   *\n   * @example\n   * const state = await ctx.get<string>(\"STATE\");\n   */\n  get<TValue, TKey extends keyof TState = string>(\n    name: TState extends UntypedState ? string : TKey,\n    serde?: Serde<TState extends UntypedState ? TValue : TState[TKey]>\n  ): Promise<(TState extends UntypedState ? TValue : TState[TKey]) | null>;\n\n  /**\n   * Retrieve all the state keys for this object.\n   */\n  stateKeys(): Promise<Array<string>>;\n}\n\nexport interface Rand {\n  /**\n   * Equivalent of JS `Math.random()` but deterministic; seeded by the invocation ID of the current invocation,\n   * each call will return a new pseudorandom float within the range [0,1)\n   */\n  random(): number;\n\n  /**\n   * Using the same random source and seed as random(), produce a UUID version 4 string. This is inherently predictable\n   * based on the invocation ID and should not be used in cryptographic contexts\n   */\n  uuidv4(): string;\n}\n\n/**\n * A promise that can be combined using Promise combinators in RestateContext.\n */\nexport type RestatePromise<T> = Promise<T> & {\n  /**\n   * Creates a promise that awaits for the current promise up to the specified timeout duration.\n   * If the timeout is fired, this Promise will be rejected with a {@link TimeoutError}.\n   *\n   * @param millis duration of the sleep in millis.\n   * This is a lower-bound.\n   */\n  orTimeout(millis: Duration | number): RestatePromise<T>;\n\n  /**\n   * Creates a new {@link RestatePromise} that maps the result of this promise with\n   * the provided `mapper`, once this promise is fulfilled.\n   *\n   * **NOTE**: You **MUST** use this API when you need to map the result of a\n   * {@link RestatePromise} without `await`ing it, rather than using {@link Promise.then}.\n   * {@link Promise.then} is used by Restate to distinguish when awaiting an asynchronous operation,\n   * thus calling `.then` on several Restate promises can lead to concurrency issues.\n   *\n   * @param mapper the function to execute when this promise is fulfilled.\n   * If the promise completed successfully, `value` is provided as input, otherwise `failure` is provided as input.\n   * If this mapper returns a value, this value will be used to resolve the returned {@link RestatePromise}.\n   * If the mapper throws a {@link TerminalError}, this error will be used to reject the returned {@link RestatePromise}.\n   */\n  map<U>(mapper: (value?: T, failure?: TerminalError) => U): RestatePromise<U>;\n};\n\n/**\n * Represents an invocation id.\n * @see {@link InvocationIdParser}\n */\nexport type InvocationId = string & { __brand: \"InvocationId\" };\n\nexport const InvocationIdParser = {\n  /**\n   * Creates an invocation id from a string.\n   * @param id the string to use as invocation id.\n   */\n  fromString(id: string): InvocationId {\n    if (!id.startsWith(\"inv\")) {\n      throw new Error(\n        `Expected invocation id to start with 'inv' but got ${id}`\n      );\n    }\n    return id as InvocationId;\n  },\n};\n\nexport type InvocationHandle = {\n  // The invocation id of the call\n  readonly invocationId: Promise<InvocationId>;\n};\n\nexport type InvocationPromise<T> = RestatePromise<T> & InvocationHandle;\n\nexport const RestatePromise = {\n  /**\n   * Creates a Promise that is resolved with an array of results when all of the provided Promises\n   * resolve, or rejected when any Promise is rejected.\n   *\n   * See {@link Promise.all} for more details.\n   *\n   * @param values An iterable of Promises.\n   * @returns A new Promise.\n   */\n  all<const T extends readonly RestatePromise<unknown>[]>(\n    values: T\n  ): RestatePromise<{ -readonly [P in keyof T]: Awaited<T[P]> }> {\n    if (values.length === 0) {\n      throw new Error(\n        \"Expected combineable promise to have at least one promise\"\n      );\n    }\n    return ContextImpl.createCombinator(\n      (p) => Promise.all(p),\n      values\n    ) as RestatePromise<{\n      -readonly [P in keyof T]: Awaited<T[P]>;\n    }>;\n  },\n\n  /**\n   * Creates a Promise that is resolved or rejected when any of the provided Promises are resolved\n   * or rejected.\n   *\n   * See {@link Promise.race} for more details.\n   *\n   * @param values An iterable of Promises.\n   * @returns A new Promise.\n   */\n  race<const T extends readonly RestatePromise<unknown>[]>(\n    values: T\n  ): RestatePromise<Awaited<T[number]>> {\n    if (values.length === 0) {\n      throw new Error(\n        \"Expected combineable promise to have at least one promise\"\n      );\n    }\n    return ContextImpl.createCombinator(\n      (p) => Promise.race(p),\n      values\n    ) as RestatePromise<Awaited<T[number]>>;\n  },\n\n  /**\n   * Creates a promise that fulfills when any of the input's promises fulfills, with this first fulfillment value.\n   * It rejects when all the input's promises reject (including when an empty iterable is passed),\n   * with an AggregateError containing an array of rejection reasons.\n   *\n   * See {@link Promise.any} for more details.\n   *\n   * @param values An iterable of Promises.\n   * @returns A new Promise.\n   */\n  any<const T extends readonly RestatePromise<unknown>[]>(\n    values: T\n  ): RestatePromise<Awaited<T[number]>> {\n    if (values.length === 0) {\n      throw new Error(\n        \"Expected combineable promise to have at least one promise\"\n      );\n    }\n    return ContextImpl.createCombinator(\n      (p) => Promise.any(p),\n      values\n    ) as RestatePromise<Awaited<T[number]>>;\n  },\n\n  /**\n   * Creates a promise that fulfills when all the input's promises settle (including when an empty iterable is passed),\n   * with an array of objects that describe the outcome of each promise.\n   *\n   * See {@link Promise.allSettled} for more details.\n   *\n   * @param values An iterable of Promises.\n   * @returns A new Promise.\n   */\n  allSettled<const T extends readonly RestatePromise<unknown>[]>(\n    values: T\n  ): RestatePromise<{\n    -readonly [P in keyof T]: PromiseSettledResult<Awaited<T[P]>>;\n  }> {\n    if (values.length === 0) {\n      throw new Error(\n        \"Expected combineable promise to have at least one promise\"\n      );\n    }\n    return ContextImpl.createCombinator(\n      (p) => Promise.allSettled(p),\n      values\n    ) as RestatePromise<{\n      -readonly [P in keyof T]: PromiseSettledResult<Awaited<T[P]>>;\n    }>;\n  },\n};\n\n/**\n * Workflow bound durable promise\n *\n * See {@link WorkflowSharedContext} promise..\n */\nexport type DurablePromise<T> = Promise<T> & {\n  /**\n   * Returns the value of the promise, if it has been resolved.\n   */\n  peek(): Promise<T | undefined>;\n\n  /**\n   * Resolve the promise with the given value.\n   * @param value the value to resolve the promise with\n   */\n  resolve(value?: T): Promise<void>;\n\n  /**\n   * Reject the promise with the given error message.\n   * @param errorMsg the error message to use for rejection.\n   */\n  reject(errorMsg: string): Promise<void>;\n\n  /**\n   * Obtain a {@link RestatePromise} variant of this promise.\n   */\n  get(): RestatePromise<T>;\n};\n\nexport interface WorkflowSharedContext<TState extends TypedState = UntypedState>\n  extends ObjectSharedContext<TState>, RestateWorkflowSharedContext {\n  /**\n   * Create a durable promise that can be resolved or rejected during the workflow execution.\n   * The promise is bound to the workflow and will be persisted across suspensions and retries.\n   * @example Add some retry options\n   * ```ts\n   * const wf = restate.workflow({\n   *   name: \"myWorkflow\",\n   *   handlers: {\n   *     run: async (ctx: restate.WorkflowContext) => {\n   *       // ... do some work ...\n   *       const payment = await ctx.promise<Payment>(\"payment.succeeded\");\n   *       // ... do some more work ...\n   *     },\n   *\n   *     onPaymentSucceeded: async (ctx: restate.WorkflowContext, payment) => {\n   *       // ... handle payment succeeded ...\n   *       await ctx.promise(\"payment.succeeded\").resolve(payment);\n   *     }\n   * });\n   * ```\n   *\n   * @param name the name of the durable promise\n   */\n  promise<T>(name: string, serde?: Serde<T>): DurablePromise<T>;\n}\n\nexport interface WorkflowContext<TState extends TypedState = UntypedState>\n  extends\n    WorkflowSharedContext<TState>,\n    ObjectContext<TState>,\n    RestateWorkflowContext {}\n"],"mappings":";;;AAusBA,MAAa,qBAAqB,EAKhC,WAAW,IAA0B;AACnC,KAAI,CAAC,GAAG,WAAW,MAAM,CACvB,OAAM,IAAI,MACR,sDAAsD,KACvD;AAEH,QAAO;GAEV;AASD,MAAa,iBAAiB;CAU5B,IACE,QAC6D;AAC7D,MAAI,OAAO,WAAW,EACpB,OAAM,IAAI,MACR,4DACD;AAEH,SAAO,YAAY,kBAChB,MAAM,QAAQ,IAAI,EAAE,EACrB,OACD;;CAcH,KACE,QACoC;AACpC,MAAI,OAAO,WAAW,EACpB,OAAM,IAAI,MACR,4DACD;AAEH,SAAO,YAAY,kBAChB,MAAM,QAAQ,KAAK,EAAE,EACtB,OACD;;CAaH,IACE,QACoC;AACpC,MAAI,OAAO,WAAW,EACpB,OAAM,IAAI,MACR,4DACD;AAEH,SAAO,YAAY,kBAChB,MAAM,QAAQ,IAAI,EAAE,EACrB,OACD;;CAYH,WACE,QAGC;AACD,MAAI,OAAO,WAAW,EACpB,OAAM,IAAI,MACR,4DACD;AAEH,SAAO,YAAY,kBAChB,MAAM,QAAQ,WAAW,EAAE,EAC5B,OACD;;CAIJ"}
+{"version":3,"file":"context.js","names":[],"sources":["../src/context.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\nimport type { Client, SendClient } from \"./types/rpc.js\";\nimport type {\n  RestateContext,\n  RestateObjectContext,\n  RestateObjectSharedContext,\n  RestateWorkflowContext,\n  RestateWorkflowSharedContext,\n  Service,\n  ServiceDefinitionFrom,\n  VirtualObject,\n  VirtualObjectDefinitionFrom,\n  Workflow,\n  WorkflowDefinitionFrom,\n  Serde,\n  Duration,\n} from \"@restatedev/restate-sdk-core\";\nimport type { TerminalError } from \"./types/errors.js\";\nimport {\n  InternalRestatePromise,\n  CombinatorRestatePromise,\n  ConstRestatePromise,\n} from \"./promises.js\";\n\nexport interface Target {\n  service: string;\n  handler: string;\n  key?: string;\n  toString(): string;\n}\n\n/**\n * Represents the original request as sent to this handler.\n *\n * A request object includes the request headers, and the raw unparsed\n * request body.\n */\nexport interface Request {\n  readonly target: Target;\n\n  /**\n   * The unique id that identifies the current function invocation. This id is guaranteed to be\n   * unique across invocations, but constant across reties and suspensions.\n   */\n  readonly id: InvocationId;\n\n  /**\n   * Request headers - the following headers capture the original invocation headers, as provided to\n   * the ingress.\n   */\n  readonly headers: ReadonlyMap<string, string>;\n\n  /**\n   * Attempt headers - the following headers are sent by the restate runtime.\n   * These headers are attempt specific, generated by the restate runtime uniquely for each attempt.\n   * These headers might contain information such as the W3C trace context, and attempt specific information.\n   */\n  readonly attemptHeaders: ReadonlyMap<string, string | string[] | undefined>;\n\n  /**\n   * Raw unparsed request body\n   */\n  readonly body: Uint8Array;\n\n  /**\n   * Extra arguments provided to the request handler:\n   * Lambda: [Context]\n   * Cloudflare workers: [Env, ExecutionContext]\n   * Deno: [ConnInfo]\n   * Bun: [Server]\n   * These arguments can contain request-specific values that could change after a suspension.\n   * Care should be taken to use them deterministically.\n   */\n  readonly extraArgs: unknown[];\n\n  /**\n   * This is a signal that is aborted when the current attempt has been completed either successful or unsuccessfully.\n   * When the signal is aborted, the current attempt has been completed and the handler should not perform any more work, other\n   * than cleanup any external resources that might be shared across attempts (e.g. database connections).\n   */\n  readonly attemptCompletedSignal: AbortSignal;\n}\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\nexport type TypedState = Record<string, any>;\nexport type UntypedState = { _: never };\n\n/**\n * Key value store operations. Only keyed services have an attached key-value store.\n */\nexport interface KeyValueStore<TState extends TypedState> {\n  /**\n   * Get/retrieve state from the Restate runtime.\n   * Note that state objects are serialized with `Buffer.from(JSON.stringify(theObject))`\n   * and deserialized with `JSON.parse(value.toString()) as T`.\n   *\n   * @param name key of the state to retrieve\n   * @returns a Promise that is resolved with the value of the state key\n   *\n   * @example\n   * const state = await ctx.get<string>(\"STATE\");\n   */\n  get<TValue, TKey extends keyof TState = string>(\n    name: TState extends UntypedState ? string : TKey,\n    serde?: Serde<TState extends UntypedState ? TValue : TState[TKey]>\n  ): Promise<(TState extends UntypedState ? TValue : TState[TKey]) | null>;\n\n  stateKeys(): Promise<Array<string>>;\n\n  /**\n   * Set/store state in the Restate runtime.\n   * Note that state objects are serialized with `Buffer.from(JSON.stringify(theObject))`\n   * and deserialized with `JSON.parse(value.toString()) as T`.\n   *\n   * @param name key of the state to set\n   * @param value value to set\n   *\n   * @example\n   * ctx.set(\"STATE\", \"Hello\");\n   */\n  set<TValue, TKey extends keyof TState = string>(\n    name: TState extends UntypedState ? string : TKey,\n    value: TState extends UntypedState ? TValue : TState[TKey],\n    serde?: Serde<TState extends UntypedState ? TValue : TState[TKey]>\n  ): void;\n\n  /**\n   * Clear/delete state in the Restate runtime.\n   * @param name key of the state to delete\n   *\n   * @example\n   * ctx.clear(\"STATE\");\n   */\n  clear<TKey extends keyof TState>(\n    name: TState extends UntypedState ? string : TKey\n  ): void;\n\n  /**\n   * Clear/delete all the state entries in the Restate runtime.\n   *\n   * @example\n   * ctx.clearAll();\n   */\n  clearAll(): void;\n}\n\nexport interface ContextDate {\n  /** Returns the number of milliseconds elapsed since midnight, January 1, 1970 Universal Coordinated Time (UTC).\n   *  This is equivalent to Date.now()\n   */\n  now(): Promise<number>;\n  /** Returns the JSON representation of the current date.\n   * This is equivalent to new Date().toJSON()\n   **/\n  toJSON(): Promise<string>;\n}\n\n/**\n * A function that can be run and its result durably persisted by Restate.\n */\nexport type RunAction<T> = (() => Promise<T>) | (() => T);\n\nexport type RunOptions<T> = {\n  serde?: Serde<T>;\n\n  /**\n   * Max number of attempts (including the initial), before giving up.\n   *\n   * When giving up, `ctx.run` will throw a `TerminalError` wrapping the original error message.\n   */\n  maxRetryAttempts?: number;\n\n  /**\n   * Max duration of retries, before giving up.\n   *\n   * When giving up, `ctx.run` will throw a `TerminalError` wrapping the original error message.\n   *\n   * If a number is provided, it will be interpreted as milliseconds.\n   */\n  maxRetryDuration?: Duration | number;\n\n  /**\n   * Initial interval for the first retry attempt.\n   * Retry interval will grow by a factor specified in `retryIntervalFactor`.\n   *\n   * The default is 50 milliseconds.\n   *\n   * If a number is provided, it will be interpreted as milliseconds.\n   */\n  initialRetryInterval?: Duration | number;\n\n  /**\n   * Max interval between retries.\n   * Retry interval will grow by a factor specified in `retryIntervalFactor`.\n   *\n   * The default is 10 seconds.\n   *\n   * If a number is provided, it will be interpreted as milliseconds.\n   */\n  maxRetryInterval?: Duration | number;\n\n  /**\n   * Exponentiation factor to use when computing the next retry delay.\n   *\n   * The default value is `2`, meaning retry interval will double at each attempt.\n   */\n  retryIntervalFactor?: number;\n};\n\n/**\n * Call a handler directly avoiding restate's type safety checks.\n * This is a generic mechanism to invoke handlers directly by only knowing\n * the service and handler name, (or key in the case of objects or workflows)\n */\nexport type GenericCall<REQ, RES> = {\n  service: string;\n  method: string;\n  parameter: REQ;\n  key?: string;\n  headers?: Record<string, string>;\n  inputSerde?: Serde<REQ>;\n  outputSerde?: Serde<RES>;\n  idempotencyKey?: string;\n  /**\n   * Observability name, recorded in the Restate journal.\n   */\n  name?: string;\n};\n\n/**\n * Send a message to an handler directly avoiding restate's type safety checks.\n * This is a generic mechanism to invoke handlers directly by only knowing\n * the service and handler name, (or key in the case of objects or workflows)\n */\nexport type GenericSend<REQ> = {\n  service: string;\n  method: string;\n  parameter: REQ;\n  key?: string;\n  headers?: Record<string, string>;\n  inputSerde?: Serde<REQ>;\n  delay?: Duration | number;\n  idempotencyKey?: string;\n  /**\n   * Observability name, recorded in the Restate journal.\n   */\n  name?: string;\n};\n\n/**\n * The context that gives access to all Restate-backed operations, for example\n *   - sending reliable messages / RPC through Restate\n *   - execute non-deterministic closures and memoize their result\n *   - sleeps and delayed calls\n *   - awakeables\n *   - ...\n *\n * Virtual objects can also access their key-value store using the {@link ObjectContext}.\n *\n */\nexport interface Context extends RestateContext {\n  /**\n   * Deterministic random methods; these are inherently predictable (seeded on the invocation ID, which is not secret)\n   * and so should not be used for any cryptographic purposes. They are useful for identifiers, idempotency keys,\n   * and for uniform sampling from a set of options. If a cryptographically secure value is needed, please generate that\n   * externally and capture the result with a side effect.\n   *\n   * Calls to these methods from inside `ctx.run` are disallowed and will fail - side effects must be idempotent, and\n   * these calls are not.\n   */\n  rand: Rand;\n\n  /**\n   * Console to use for logging. It attaches to each log message some contextual information,\n   * such as invoked service method and invocation id, and automatically excludes logs during replay.\n   */\n  console: Console;\n\n  /**\n   * Deterministic date.\n   */\n  date: ContextDate;\n\n  /**\n   * Run an operation and store the result in Restate. The operation will thus not\n   * be re-run during a later replay, but take the durable result from Restate.\n   *\n   * This let you capture potentially non-deterministic computation and interaction\n   * with external systems in a safe way.\n   *\n   * Failure semantics are:\n   *   - If an operation has run and persisted before, the result (value or Error) will be\n   *     taken from the Restate journal.\n   *   - There is a small window where an action may be re-run, if a failure\n   *     occurred between a successful run and persisting the result.\n   *   - No second action will be run while a previous run's result is not\n   *     yet durable. That way, effects that build on top of each other can assume\n   *     deterministic results from previous runs, and at most one run will be\n   *     re-executed on replay (the latest, if the failure happened in the small windows\n   *     described above).\n   *\n   * You can customize retry options by either:\n   *\n   * - Providing retry policy options in {@link RunOptions}\n   * - Throwing {@link RetryableError}, providing `retryAfter` option. This can be especially useful when interacting with HTTP requests returning the `Retry-After` header. You can combine the usage of throwing {@link RetryableError} with the `maxRetryAttempts`/`maxRetryDuration` from {@link RunOptions}.\n   *\n   * @example Run some external action and persist its result\n   * ```ts\n   * const result = await ctx.run(someExternalAction)\n   *```\n   * @example Add some retry options\n   * ```ts\n   * const result = await ctx.run(\"my action\", someExternalAction, { maxRetryAttempts: 10 })\n   * ```\n   * @example Terminal errors and retryable errors\n   * ```ts\n   * await ctx.run(\"payment action\", async () => {\n   *   const result = await paymentProvider.charge(txId, paymentInfo);\n   *   if (result.paymentRejected) {\n   *     // this action will not be retried anymore\n   *     throw new TerminalError(\"Payment failed\");\n   *   } else if (result.paymentGatewayBusy) {\n   *     // restate will retry automatically\n   *     // to bound retries, use RunOptions\n   *     throw new Error(\"Payment gateway busy\");\n   *   } else {\n   *     // success!\n   *   }\n   * });\n   * ```\n   * @example Retryable error with custom retry delay\n   * ```ts\n   * await ctx.run(\"payment action\", async () => {\n   *   const res = fetch(...);\n   *   if (!res.ok) {\n   *     // Read Retry-After header\n   *     const retryAfterHeader = res.headers['Retry-After']\n   *\n   *     // Use RetryableError to customize in how long to retry\n   *     throw RetryableError.from(cause, { retryAfter: { seconds: retryAfterHeader } })\n   *   }\n   * }, {\n   *   // Retry at most ten times\n   *   maxRetryAttempts: 10\n   * });\n   * ```\n   *\n   * @param action The function to run.\n   */\n  run<T>(action: RunAction<T>): RestatePromise<T>;\n\n  /**\n   * Same as {@link run}, but providing a name, used for observability purposes.\n   */\n  run<T>(name: string, action: RunAction<T>): RestatePromise<T>;\n\n  /**\n   * See {@link run}\n   */\n  run<T>(\n    name: string,\n    action: RunAction<T>,\n    options: RunOptions<T>\n  ): RestatePromise<T>;\n\n  /**\n   * Register an awakeable and pause the processing until the awakeable ID (and optional payload) have been returned to the service\n   * (via ctx.completeAwakeable(...)). The SDK deserializes the payload with `JSON.parse(result.toString()) as T`.\n   * @returns\n   * - id: the string ID that has to be used to complete the awakaeble by some external service\n   * - promise: the Promise that needs to be awaited and that is resolved with the payload that was supplied by the service which completed the awakeable\n   * @example Retryable errors and terminal errors\n   * const awakeable = ctx.awakeable<string>();\n   *\n   * // send the awakeable ID to some external service that will wake this one back up\n   * // The ID can be retrieved by:\n   * const id = awakeable.id;\n   *\n   * // ... send to external service ...\n   *\n   * // Wait for the external service to wake this service back up\n   * const result = await awakeable.promise;\n   */\n  awakeable<T>(serde?: Serde<T>): {\n    id: string;\n    promise: RestatePromise<T>;\n  };\n\n  /**\n   * Resolve an awakeable.\n   * @param id the string ID of the awakeable.\n   * This is supplied by the service that needs to be woken up.\n   * @param payload the payload to pass to the service that is woken up.\n   * The SDK serializes the payload with `Buffer.from(JSON.stringify(payload))`\n   * and deserializes it in the receiving service with `JSON.parse(result.toString()) as T`.\n   * @example Retryable error with custom retry delay\n   * // The sleeping service should have sent the awakeableIdentifier string to this service.\n   * ctx.resolveAwakeable(awakeableIdentifier, \"hello\");\n   */\n  resolveAwakeable<T>(id: string, payload?: T, serde?: Serde<T>): void;\n\n  /**\n   * Reject an awakeable. When rejecting, the service waiting on this awakeable will be woken up with a terminal error with the provided reason.\n   * @param id the string ID of the awakeable.\n   * This is supplied by the service that needs to be woken up.\n   * @param reason the reason of the rejection, either a string message or a {@link TerminalError}.\n   *\n   * @example\n   * // The sleeping service should have sent the awakeableIdentifier string to this service.\n   * ctx.rejectAwakeable(awakeableIdentifier, \"super bad error\");\n   */\n  rejectAwakeable(id: string, reason: string | TerminalError): void;\n\n  /**\n   * Sleep until a timeout has passed.\n   * @param duration either Duration type or milliseconds.\n   * @param name Observability name. This will be shown in the UI.\n   * This is a lower-bound.\n   *\n   * @example\n   * await ctx.sleep(1000);\n   */\n  sleep(duration: Duration | number, name?: string): RestatePromise<void>;\n\n  /**\n   * Makes a type-safe request/response RPC to the specified target service.\n   *\n   * The RPC goes through Restate and is guaranteed to be reliably delivered. The RPC is also\n   * journaled for durable execution and will thus not be duplicated when the handler is re-invoked\n   * for retries or after suspending.\n   *\n   * This call will return the result produced by the target handler, or the Error, if the target\n   * handler finishes with a Terminal Error.\n   *\n   * This call is a suspension point: The handler might suspend while awaiting the response and\n   * resume once the response is available.\n   *\n   * @example\n   * *Service Side:*\n   * ```ts\n   * const service = restate.service(\n   *   name: \"myservice\",\n   *   handlers: {\n   *    someAction:    async(ctx: restate.Context, req: string) => { ... },\n   *    anotherAction: async(ctx: restate.Context, count: number) => { ... }\n   * });\n   *\n   * // option 1: export only the type signature\n   * export type Service = typeof service;\n   *\n   *\n   * restate.serve({ services: [service], port: 9080 });\n   * ```\n   * *Client side:*\n   * ```ts\n   * // option 1: use only types and supply service name separately\n   * const result1 = await ctx.serviceClient<Service>({name: \"myservice\"}).someAction(\"hello!\");\n   *\n   * // option 2: use full API spec\n   * type MyService: Service = { name: \"myservice\" };\n   * const result2 = await ctx.serviceClient(Service).anotherAction(1337);\n   * ```\n   */\n  serviceClient<D>(opts: ServiceDefinitionFrom<D>): Client<Service<D>>;\n\n  /**\n   * Same as {@link serviceClient} but for virtual objects.\n   *\n   * @param opts\n   * @param key the virtual object key\n   */\n  objectClient<D>(\n    opts: VirtualObjectDefinitionFrom<D>,\n    key: string\n  ): Client<VirtualObject<D>>;\n\n  /**\n   * Same as {@link serviceClient} but for workflows.\n   *\n   * @param opts\n   * @param key the workflow key\n   */\n  workflowClient<D>(\n    opts: WorkflowDefinitionFrom<D>,\n    key: string\n  ): Client<Workflow<D>>;\n\n  /**\n   * Same as {@link objectSendClient} but for workflows.\n   *\n   * @param opts\n   * @param key the workflow key\n   */\n  workflowSendClient<D>(\n    opts: WorkflowDefinitionFrom<D>,\n    key: string\n  ): SendClient<Workflow<D>>;\n\n  /**\n   * Makes a type-safe one-way RPC to the specified target service. This method effectively behaves\n   * like enqueuing the message in a message queue.\n   *\n   * The message goes through Restate and is guaranteed to be reliably delivered. The RPC is also\n   * journaled for durable execution and will thus not be duplicated when the handler is re-invoked\n   * for retries or after suspending.\n   *\n   * This call will return immediately; the message sending happens asynchronously in the background.\n   * Despite that, the message is guaranteed to be sent, because the completion of the invocation that\n   * triggers the send (calls this function) happens logically after the sending. That means that any\n   * failure where the message does not reach Restate also cannot complete this invocation, and will\n   * hence recover this handler and (through the durable execution) recover the message to be sent.\n   *\n   * @example\n   * *Service Side:*\n   * ```ts\n   * const service = restate.service(\n   *   name: \"myservice\",\n   *   handlers: {\n   *    someAction:    async(ctx: restate.Context, req: string) => { ... },\n   *    anotherAction: async(ctx: restate.Context, count: number) => { ... }\n   * });\n   *\n   * // option 1: export only the type signature of the router\n   * export type MyApi = typeof service;\n   *\n   * // option 2: export the API definition with type and name (name)\n   * const MyService: MyApi = { name: \"myservice\" };\n   *\n   * restate.serve({ services: [service], port: 9080 });\n   * ```\n   * *Client side:*\n   * ```ts\n   * // option 1: use only types and supply service name separately\n   * ctx.serviceSendClient<MyApi>({name: \"myservice\"}).someAction(\"hello!\");\n   *\n   * // option 2: use full API spec\n   * ctx.serviceSendClient(MyService).anotherAction(1337);\n   * ```\n   */\n  serviceSendClient<D>(\n    service: ServiceDefinitionFrom<D>\n  ): SendClient<Service<D>>;\n\n  /**\n   * Same as {@link serviceSendClient} but for virtual objects.\n   *\n   * @param obj\n   * @param key the virtual object key\n   * @param opts Send options\n   */\n  objectSendClient<D>(\n    obj: VirtualObjectDefinitionFrom<D>,\n    key: string\n  ): SendClient<VirtualObject<D>>;\n\n  genericCall<REQ = Uint8Array, RES = Uint8Array>(\n    call: GenericCall<REQ, RES>\n  ): InvocationPromise<RES>;\n\n  genericSend<REQ = Uint8Array>(call: GenericSend<REQ>): InvocationHandle;\n\n  /**\n   * Returns the raw request that triggered that handler.\n   * Use that object to inspect the original request headers\n   */\n  request(): Request;\n\n  /**\n   * Cancel an invocation\n   *\n   * @param invocationId the invocation id to cancel\n   */\n  cancel(invocationId: InvocationId): void;\n\n  /**\n   * Attach to an invocation\n   *\n   * @param invocationId the invocation id to attach to\n   * @param serde the serde to use for the result, default to JSON serde.\n   */\n  attach<T>(invocationId: InvocationId, serde?: Serde<T>): RestatePromise<T>;\n}\n\n/**\n * The context that gives access to all Restate-backed operations, for example\n *   - sending reliable messages / RPC through Restate\n *   - access/update state\n *   - execute non-deterministic closures and memoize their result\n *   - sleeps and delayed calls\n *   - awakeables\n *   - ...\n *\n * This context can be used only within virtual objects.\n *\n */\nexport interface ObjectContext<TState extends TypedState = UntypedState>\n  extends Context, KeyValueStore<TState>, RestateObjectContext {\n  key: string;\n}\n\n/**\n * The context that gives access to all Restate-backed operations, for example\n *   - sending reliable messages / RPC through Restate\n *   - execute non-deterministic closures and memoize their result\n *   - sleeps and delayed calls\n *   - awakeables\n *   - ...\n *\n * This context can be used only within a shared virtual objects.\n *\n */\nexport interface ObjectSharedContext<TState extends TypedState = UntypedState>\n  extends Context, RestateObjectSharedContext {\n  key: string;\n\n  /**\n   * Get/retrieve state from the Restate runtime.\n   * Note that state objects are serialized with `Buffer.from(JSON.stringify(theObject))`\n   * and deserialized with `JSON.parse(value.toString()) as T`.\n   *\n   * @param name key of the state to retrieve\n   * @returns a Promise that is resolved with the value of the state key\n   *\n   * @example\n   * const state = await ctx.get<string>(\"STATE\");\n   */\n  get<TValue, TKey extends keyof TState = string>(\n    name: TState extends UntypedState ? string : TKey,\n    serde?: Serde<TState extends UntypedState ? TValue : TState[TKey]>\n  ): Promise<(TState extends UntypedState ? TValue : TState[TKey]) | null>;\n\n  /**\n   * Retrieve all the state keys for this object.\n   */\n  stateKeys(): Promise<Array<string>>;\n}\n\nexport interface Rand {\n  /**\n   * Equivalent of JS `Math.random()` but deterministic; seeded by the invocation ID of the current invocation,\n   * each call will return a new pseudorandom float within the range [0,1)\n   */\n  random(): number;\n\n  /**\n   * Using the same random source and seed as random(), produce a UUID version 4 string. This is inherently predictable\n   * based on the invocation ID and should not be used in cryptographic contexts\n   */\n  uuidv4(): string;\n}\n\n/**\n * A promise that can be combined using Promise combinators in RestateContext.\n *\n * To check at runtime whether a value is a {@link RestatePromise}, use {@link isRestatePromise}.\n */\nexport type RestatePromise<T> = Promise<T> & {\n  /**\n   * Creates a promise that awaits for the current promise up to the specified timeout duration.\n   * If the timeout is fired, this Promise will be rejected with a {@link TimeoutError}.\n   *\n   * @param millis duration of the sleep in millis.\n   * This is a lower-bound.\n   */\n  orTimeout(millis: Duration | number): RestatePromise<T>;\n\n  /**\n   * Creates a new {@link RestatePromise} that maps the result of this promise with\n   * the provided `mapper`, once this promise is fulfilled.\n   *\n   * **NOTE**: You **MUST** use this API when you need to map the result of a\n   * {@link RestatePromise} without `await`ing it, rather than using {@link Promise.then}.\n   * {@link Promise.then} is used by Restate to distinguish when awaiting an asynchronous operation,\n   * thus calling `.then` on several Restate promises can lead to concurrency issues.\n   *\n   * **NOTE**: Contrary to `.then`, the closure is executed ONLY when the promise is awaited,\n   * and not eagerly as soon as the promise completes.\n   *\n   * @param mapper the function to execute when this promise is fulfilled.\n   * If the promise completed successfully, `value` is provided as input, otherwise `failure` is provided as input.\n   * If this mapper returns a value, this value will be used to resolve the returned {@link RestatePromise}.\n   * If the mapper throws a {@link TerminalError}, this error will be used to reject the returned {@link RestatePromise}.\n   */\n  map<U>(mapper: (value?: T, failure?: TerminalError) => U): RestatePromise<U>;\n};\n\n/**\n * Represents an invocation id.\n * @see {@link InvocationIdParser}\n */\nexport type InvocationId = string & { __brand: \"InvocationId\" };\n\nexport const InvocationIdParser = {\n  /**\n   * Creates an invocation id from a string.\n   * @param id the string to use as invocation id.\n   */\n  fromString(id: string): InvocationId {\n    if (!id.startsWith(\"inv\")) {\n      throw new Error(\n        `Expected invocation id to start with 'inv' but got ${id}`\n      );\n    }\n    return id as InvocationId;\n  },\n};\n\nexport type InvocationHandle = {\n  // The invocation id of the call\n  readonly invocationId: Promise<InvocationId>;\n};\n\nexport type InvocationPromise<T> = RestatePromise<T> & InvocationHandle;\n\nexport const RestatePromise = {\n  /**\n   * Creates a {@link RestatePromise} that is resolved with the given value.\n   *\n   * If the value is already a {@link RestatePromise}, it is returned as-is (mirroring\n   * the behavior of {@link Promise.resolve} when given a native {@link Promise}).\n   *\n   * @param value The value to resolve, or an existing {@link RestatePromise} to return.\n   * @returns A resolved {@link RestatePromise}, or the input promise unchanged.\n   */\n  resolve<T>(value: T): RestatePromise<Awaited<T>> {\n    if (value instanceof InternalRestatePromise) {\n      return value as unknown as RestatePromise<Awaited<T>>;\n    }\n    return ConstRestatePromise.resolve(value);\n  },\n\n  /**\n   * Creates a {@link RestatePromise} that is rejected with the given {@link TerminalError}.\n   *\n   * @param reason The {@link TerminalError} to reject with.\n   * @returns A rejected {@link RestatePromise}.\n   */\n  reject<T = never>(reason: TerminalError): RestatePromise<T> {\n    return ConstRestatePromise.reject(reason);\n  },\n\n  /**\n   * Creates a Promise that is resolved with an array of results when all of the provided Promises\n   * resolve, or rejected when any Promise is rejected.\n   *\n   * See {@link Promise.all} for more details.\n   *\n   * @param values An iterable of Promises.\n   * @returns A new Promise.\n   */\n  all<const T extends readonly RestatePromise<unknown>[]>(\n    values: T\n  ): RestatePromise<{ -readonly [P in keyof T]: Awaited<T[P]> }> {\n    return CombinatorRestatePromise.fromPromises(\n      (p) => Promise.all(p),\n      values\n    ) as RestatePromise<{\n      -readonly [P in keyof T]: Awaited<T[P]>;\n    }>;\n  },\n\n  /**\n   * Creates a Promise that is resolved or rejected when any of the provided Promises are resolved\n   * or rejected.\n   *\n   * See {@link Promise.race} for more details.\n   *\n   * @param values An iterable of Promises.\n   * @returns A new Promise.\n   */\n  race<const T extends readonly RestatePromise<unknown>[]>(\n    values: T\n  ): RestatePromise<Awaited<T[number]>> {\n    if (values.length === 0) {\n      return ConstRestatePromise.pending();\n    }\n    return CombinatorRestatePromise.fromPromises(\n      (p) => Promise.race(p),\n      values\n    ) as RestatePromise<Awaited<T[number]>>;\n  },\n\n  /**\n   * Creates a promise that fulfills when any of the input's promises fulfills, with this first fulfillment value.\n   * It rejects when all the input's promises reject (including when an empty iterable is passed),\n   * with an AggregateError containing an array of rejection reasons.\n   *\n   * See {@link Promise.any} for more details.\n   *\n   * @param values An iterable of Promises.\n   * @returns A new Promise.\n   */\n  any<const T extends readonly RestatePromise<unknown>[]>(\n    values: T\n  ): RestatePromise<Awaited<T[number]>> {\n    return CombinatorRestatePromise.fromPromises(\n      (p) => Promise.any(p),\n      values\n    ) as RestatePromise<Awaited<T[number]>>;\n  },\n\n  /**\n   * Creates a promise that fulfills when all the input's promises settle (including when an empty iterable is passed),\n   * with an array of objects that describe the outcome of each promise.\n   *\n   * See {@link Promise.allSettled} for more details.\n   *\n   * @param values An iterable of Promises.\n   * @returns A new Promise.\n   */\n  allSettled<const T extends readonly RestatePromise<unknown>[]>(\n    values: T\n  ): RestatePromise<{\n    -readonly [P in keyof T]: PromiseSettledResult<Awaited<T[P]>>;\n  }> {\n    return CombinatorRestatePromise.fromPromises(\n      (p) => Promise.allSettled(p),\n      values\n    ) as RestatePromise<{\n      -readonly [P in keyof T]: PromiseSettledResult<Awaited<T[P]>>;\n    }>;\n  },\n};\n\n/**\n * Workflow bound durable promise\n *\n * See {@link WorkflowSharedContext}.\n */\nexport type DurablePromise<T> = Promise<T> & {\n  /**\n   * Returns the value of the promise, if it has been resolved.\n   */\n  peek(): Promise<T | undefined>;\n\n  /**\n   * Resolve the promise with the given value.\n   * @param value the value to resolve the promise with\n   */\n  resolve(value?: T): Promise<void>;\n\n  /**\n   * Reject the promise with the given error message.\n   * @param errorMsg the error message to use for rejection.\n   */\n  reject(errorMsg: string): Promise<void>;\n\n  /**\n   * Obtain a {@link RestatePromise} variant of this promise.\n   */\n  get(): RestatePromise<T>;\n};\n\nexport interface WorkflowSharedContext<TState extends TypedState = UntypedState>\n  extends ObjectSharedContext<TState>, RestateWorkflowSharedContext {\n  /**\n   * Create a durable promise that can be resolved or rejected during the workflow execution.\n   * The promise is bound to the workflow and will be persisted across suspensions and retries.\n   * @example Add some retry options\n   * ```ts\n   * const wf = restate.workflow({\n   *   name: \"myWorkflow\",\n   *   handlers: {\n   *     run: async (ctx: restate.WorkflowContext) => {\n   *       // ... do some work ...\n   *       const payment = await ctx.promise<Payment>(\"payment.succeeded\");\n   *       // ... do some more work ...\n   *     },\n   *\n   *     onPaymentSucceeded: async (ctx: restate.WorkflowContext, payment) => {\n   *       // ... handle payment succeeded ...\n   *       await ctx.promise(\"payment.succeeded\").resolve(payment);\n   *     }\n   * });\n   * ```\n   *\n   * @param name the name of the durable promise\n   */\n  promise<T>(name: string, serde?: Serde<T>): DurablePromise<T>;\n}\n\nexport interface WorkflowContext<TState extends TypedState = UntypedState>\n  extends\n    WorkflowSharedContext<TState>,\n    ObjectContext<TState>,\n    RestateWorkflowContext {}\n"],"mappings":";;;AA8rBA,MAAa,qBAAqB,EAKhC,WAAW,IAA0B;AACnC,KAAI,CAAC,GAAG,WAAW,MAAM,CACvB,OAAM,IAAI,MACR,sDAAsD,KACvD;AAEH,QAAO;GAEV;AASD,MAAa,iBAAiB;CAU5B,QAAW,OAAsC;AAC/C,MAAI,iBAAiB,uBACnB,QAAO;AAET,SAAO,oBAAoB,QAAQ,MAAM;;CAS3C,OAAkB,QAA0C;AAC1D,SAAO,oBAAoB,OAAO,OAAO;;CAY3C,IACE,QAC6D;AAC7D,SAAO,yBAAyB,cAC7B,MAAM,QAAQ,IAAI,EAAE,EACrB,OACD;;CAcH,KACE,QACoC;AACpC,MAAI,OAAO,WAAW,EACpB,QAAO,oBAAoB,SAAS;AAEtC,SAAO,yBAAyB,cAC7B,MAAM,QAAQ,KAAK,EAAE,EACtB,OACD;;CAaH,IACE,QACoC;AACpC,SAAO,yBAAyB,cAC7B,MAAM,QAAQ,IAAI,EAAE,EACrB,OACD;;CAYH,WACE,QAGC;AACD,SAAO,yBAAyB,cAC7B,MAAM,QAAQ,WAAW,EAAE,EAC5B,OACD;;CAIJ"}

package/dist/context_impl.cjs

@@ -1,10 +1,10 @@
 const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
-const require_sdk_shared_core_wasm_bindings = require('./endpoint/handlers/vm/sdk_shared_core_wasm_bindings.cjs');
 const require_errors = require('./types/errors.cjs');
-const require_rpc = require('./types/rpc.cjs');
-const require_rand = require('./utils/rand.cjs');
 const require_completable_promise = require('./utils/completable_promise.cjs');
 const require_promises = require('./promises.cjs');
+const require_rpc = require('./types/rpc.cjs');
+const require_sdk_shared_core_wasm_bindings = require('./endpoint/handlers/vm/sdk_shared_core_wasm_bindings.cjs');
+const require_rand = require('./utils/rand.cjs');
 const require_io = require('./io.cjs');
 let __restatedev_restate_sdk_core = require("@restatedev/restate-sdk-core");
 __restatedev_restate_sdk_core = require_rolldown_runtime.__toESM(__restatedev_restate_sdk_core);
@@ -23,9 +23,13 @@ var ContextImpl = class {
 	outputPump;
 	runClosuresTracker;
 	promisesExecutor;
-	defaultSerde;
 	serviceKey;
-	constructor(coreVm, input, console, handlerKind, vmLogger, invocationRequest, invocationEndPromise, inputReader, outputWriter, journalValueCodec, defaultSerde, asTerminalError) {
+	runInterceptor;
+	cancellationPromise;
+	defaultSerde;
+	asTerminalError;
+	trackedInvocationIdPromises;
+	constructor(coreVm, input, console, handlerKind, vmLogger, invocationRequest, invocationEndPromise, inputReader, outputWriter, journalValueCodec, executionOptions) {
 		this.coreVm = coreVm;
 		this.console = console;
 		this.handlerKind = handlerKind;
@@ -33,18 +37,26 @@ var ContextImpl = class {
 		this.invocationRequest = invocationRequest;
 		this.invocationEndPromise = invocationEndPromise;
 		this.journalValueCodec = journalValueCodec;
-		this.asTerminalError = asTerminalError;
 		this.rand = new require_rand.RandImpl(input.random_seed, () => {});
 		this.outputPump = new require_io.OutputPump(coreVm, outputWriter);
 		this.runClosuresTracker = new RunClosuresTracker();
-		this.promisesExecutor = new require_promises.PromisesExecutor(coreVm, new require_io.InputPump(coreVm, inputReader, this.handleInvocationEndError.bind(this)), this.outputPump, this.runClosuresTracker, this.promiseExecutorErrorCallback.bind(this));
-		this.defaultSerde = defaultSerde ?? __restatedev_restate_sdk_core.serde.json;
+		this.promisesExecutor = new require_promises.PromisesExecutor(coreVm, new require_io.InputPump(coreVm, inputReader, this.abortAttempt.bind(this)), this.outputPump, this.runClosuresTracker, this.abortAttempt.bind(this));
 		this.serviceKey = input.key;
+		this.runInterceptor = (_name, runner) => runner();
+		this.defaultSerde = executionOptions?.defaultSerde ?? __restatedev_restate_sdk_core.serde.json;
+		this.asTerminalError = executionOptions?.asTerminalError;
+		this.trackedInvocationIdPromises = executionOptions?.explicitCancellation ? [] : void 0;
+	}
+	setRunInterceptor(interceptor) {
+		this.runInterceptor = interceptor;
 	}
 	isProcessing() {
 		return this.coreVm.is_processing();
 	}
 	cancel(invocationId) {
+		this._cancel(invocationId);
+	}
+	_cancel(invocationId) {
 		this.processNonCompletableEntry(require_sdk_shared_core_wasm_bindings.WasmCommandType.CancelInvocation, () => {}, (vm) => vm.sys_cancel_invocation(invocationId));
 	}
 	attach(invocationId, serde$1) {
@@ -83,17 +95,18 @@ var ContextImpl = class {
 		try {
 			parameter = this.journalValueCodec.encode(requestSerde.serialize(call.parameter));
 		} catch (e) {
-			this.handleInvocationEndError(e, (vm, error) => vm.notify_error_for_next_command(error.message, error.stack, require_sdk_shared_core_wasm_bindings.WasmCommandType.Call));
-			return new require_promises.InvocationPendingPromise(this);
+			this.abortAttempt(e, require_sdk_shared_core_wasm_bindings.WasmCommandType.Call);
+			return Object.assign(require_promises.ConstRestatePromise.pending(), { invocationId: require_promises.pendingPromise() });
 		}
 		try {
 			const call_handles = this.coreVm.sys_call(call.service, call.method, parameter, call.key, call.headers ? Object.entries(call.headers).map(([key, value]) => new require_sdk_shared_core_wasm_bindings.WasmHeader(key, value)) : [], call.idempotencyKey, call.name);
 			const commandIndex = this.coreVm.last_command_index();
-			const invocationIdPromise = new require_promises.RestateSinglePromise(this, call_handles.invocation_id_completion_id, completeCommandPromiseUsing(require_sdk_shared_core_wasm_bindings.WasmCommandType.Call, commandIndex, InvocationIdCompleter));
-			return new require_promises.RestateInvocationPromise(this, call_handles.call_completion_id, completeCommandPromiseUsing(require_sdk_shared_core_wasm_bindings.WasmCommandType.Call, commandIndex, SuccessWithSerde(responseSerde, this.journalValueCodec), Failure), invocationIdPromise);
+			const invocationIdPromise = new require_promises.SingleRestatePromise(this, call_handles.invocation_id_completion_id, completeCommandPromiseUsing(require_sdk_shared_core_wasm_bindings.WasmCommandType.Call, commandIndex, InvocationIdCompleter));
+			this.trackedInvocationIdPromises?.push(invocationIdPromise);
+			return new require_promises.InvocationRestatePromise(this, call_handles.call_completion_id, completeCommandPromiseUsing(require_sdk_shared_core_wasm_bindings.WasmCommandType.Call, commandIndex, SuccessWithSerde(responseSerde, this.journalValueCodec), Failure), invocationIdPromise);
 		} catch (e) {
-			this.handleInvocationEndError(e);
-			return new require_promises.InvocationPendingPromise(this);
+			this.abortAttempt(e);
+			return Object.assign(require_promises.ConstRestatePromise.pending(), { invocationId: require_promises.pendingPromise() });
 		}
 	}
 	genericSend(send) {
@@ -102,16 +115,16 @@ var ContextImpl = class {
 		try {
 			parameter = this.journalValueCodec.encode(requestSerde.serialize(send.parameter));
 		} catch (e) {
-			this.handleInvocationEndError(e, (vm, error) => vm.notify_error_for_next_command(error.message, error.stack, require_sdk_shared_core_wasm_bindings.WasmCommandType.OneWayCall));
-			return new require_promises.InvocationPendingPromise(this);
+			this.abortAttempt(e, require_sdk_shared_core_wasm_bindings.WasmCommandType.OneWayCall);
+			return Object.assign(require_promises.ConstRestatePromise.pending(), { invocationId: require_promises.pendingPromise() });
 		}
 		try {
 			const delay = send.delay !== void 0 ? (0, __restatedev_restate_sdk_core.millisOrDurationToMillis)(send.delay) : void 0;
 			const handles = this.coreVm.sys_send(send.service, send.method, parameter, send.key, send.headers ? Object.entries(send.headers).map(([key, value]) => new require_sdk_shared_core_wasm_bindings.WasmHeader(key, value)) : [], delay !== void 0 && delay > 0 ? BigInt(delay) : void 0, send.idempotencyKey, send.name);
 			const commandIndex = this.coreVm.last_command_index();
-			return { invocationId: new require_promises.RestateSinglePromise(this, handles.invocation_id_completion_id, completeCommandPromiseUsing(require_sdk_shared_core_wasm_bindings.WasmCommandType.OneWayCall, commandIndex, InvocationIdCompleter)) };
+			return { invocationId: new require_promises.SingleRestatePromise(this, handles.invocation_id_completion_id, completeCommandPromiseUsing(require_sdk_shared_core_wasm_bindings.WasmCommandType.OneWayCall, commandIndex, InvocationIdCompleter)) };
 		} catch (e) {
-			this.handleInvocationEndError(e);
+			this.abortAttempt(e);
 			return { invocationId: require_promises.pendingPromise() };
 		}
 	}
@@ -124,14 +137,14 @@ var ContextImpl = class {
 	workflowClient({ name }, key) {
 		return require_rpc.makeRpcCallProxy((call) => this.genericCall(call), this.defaultSerde, name, key);
 	}
-	serviceSendClient({ name }, opts) {
-		return require_rpc.makeRpcSendProxy((send) => this.genericSend(send), this.defaultSerde, name, void 0, opts?.delay);
+	serviceSendClient({ name }) {
+		return require_rpc.makeRpcSendProxy((send) => this.genericSend(send), this.defaultSerde, name, void 0);
 	}
-	objectSendClient({ name }, key, opts) {
-		return require_rpc.makeRpcSendProxy((send) => this.genericSend(send), this.defaultSerde, name, key, opts?.delay);
+	objectSendClient({ name }, key) {
+		return require_rpc.makeRpcSendProxy((send) => this.genericSend(send), this.defaultSerde, name, key);
 	}
-	workflowSendClient({ name }, key, opts) {
-		return require_rpc.makeRpcSendProxy((send) => this.genericSend(send), this.defaultSerde, name, key, opts?.delay);
+	workflowSendClient({ name }, key) {
+		return require_rpc.makeRpcSendProxy((send) => this.genericSend(send), this.defaultSerde, name, key);
 	}
 	run(nameOrAction, actionSecondParameter, options) {
 		const { name, action } = unpackRunParameters(nameOrAction, actionSecondParameter);
@@ -140,8 +153,8 @@ var ContextImpl = class {
 		try {
 			handle = this.coreVm.sys_run(name ?? "");
 		} catch (e) {
-			this.handleInvocationEndError(e);
-			return new require_promises.RestatePendingPromise(this);
+			this.abortAttempt(e);
+			return require_promises.ConstRestatePromise.pending();
 		}
 		const commandIndex = this.coreVm.last_command_index();
 		const doRun = async () => {
@@ -149,7 +162,9 @@ var ContextImpl = class {
 			let res;
 			let err;
 			try {
-				res = await action();
+				await this.runInterceptor(name ?? "", async () => {
+					res = await action();
+				});
 			} catch (e) {
 				err = require_errors.ensureError(e, this.asTerminalError);
 			}
@@ -163,22 +178,17 @@ var ContextImpl = class {
 						value
 					}))
 				});
-				else if (err instanceof require_errors.RetryableError) {
-					const maxRetryDuration = options?.maxRetryDuration ?? options?.maxRetryDurationMillis;
-					this.coreVm.propose_run_completion_failure_transient_with_delay_override(handle, err.message, err.stack, BigInt(attemptDuration), err.retryAfter !== void 0 ? BigInt((0, __restatedev_restate_sdk_core.millisOrDurationToMillis)(err.retryAfter)) : void 0, options?.maxRetryAttempts, maxRetryDuration !== void 0 ? BigInt((0, __restatedev_restate_sdk_core.millisOrDurationToMillis)(maxRetryDuration)) : void 0);
-				} else {
+				else if (err instanceof require_errors.RetryableError) this.coreVm.propose_run_completion_failure_transient_with_delay_override(handle, err.message, err.stack, BigInt(attemptDuration), err.retryAfter !== void 0 ? BigInt((0, __restatedev_restate_sdk_core.millisOrDurationToMillis)(err.retryAfter)) : void 0, options?.maxRetryAttempts, options?.maxRetryDuration !== void 0 ? BigInt((0, __restatedev_restate_sdk_core.millisOrDurationToMillis)(options?.maxRetryDuration)) : void 0);
+				else {
 					this.vmLogger.warn(`Error when processing ctx.run '${name}'.\n`, err);
 					let retryPolicy;
-					if (options?.retryIntervalFactor !== void 0 || options?.maxRetryAttempts !== void 0 || options?.initialRetryInterval !== void 0 || options?.initialRetryIntervalMillis !== void 0 || options?.maxRetryDuration !== void 0 || options?.maxRetryDurationMillis !== void 0 || options?.maxRetryInterval !== void 0 || options?.maxRetryIntervalMillis !== void 0) {
-						const maxRetryDuration = options?.maxRetryDuration ?? options?.maxRetryDurationMillis;
-						retryPolicy = {
-							factor: options?.retryIntervalFactor ?? 2,
-							initial_interval: (0, __restatedev_restate_sdk_core.millisOrDurationToMillis)(options?.initialRetryInterval ?? options?.initialRetryIntervalMillis ?? 50),
-							max_attempts: options?.maxRetryAttempts,
-							max_duration: maxRetryDuration === void 0 ? void 0 : (0, __restatedev_restate_sdk_core.millisOrDurationToMillis)(maxRetryDuration),
-							max_interval: (0, __restatedev_restate_sdk_core.millisOrDurationToMillis)(options?.maxRetryInterval ?? options?.maxRetryIntervalMillis ?? { seconds: 10 })
-						};
-					}
+					if (options?.retryIntervalFactor !== void 0 || options?.maxRetryAttempts !== void 0 || options?.initialRetryInterval !== void 0 || options?.maxRetryDuration !== void 0 || options?.maxRetryInterval !== void 0) retryPolicy = {
+						factor: options?.retryIntervalFactor ?? 2,
+						initial_interval: (0, __restatedev_restate_sdk_core.millisOrDurationToMillis)(options?.initialRetryInterval ?? 50),
+						max_attempts: options?.maxRetryAttempts,
+						max_duration: options?.maxRetryDuration === void 0 ? void 0 : (0, __restatedev_restate_sdk_core.millisOrDurationToMillis)(options?.maxRetryDuration),
+						max_interval: (0, __restatedev_restate_sdk_core.millisOrDurationToMillis)(options?.maxRetryInterval ?? { seconds: 10 })
+					};
 					this.coreVm.propose_run_completion_failure_transient(handle, err.message, err.stack, BigInt(attemptDuration), retryPolicy);
 				}
 				else {
@@ -187,13 +197,13 @@ var ContextImpl = class {
 					this.coreVm.propose_run_completion_success(handle, encodedRes);
 				}
 			} catch (e) {
-				this.handleInvocationEndError(e);
+				this.abortAttempt(e);
 				return require_promises.pendingPromise();
 			}
 			await this.outputPump.awaitNextProgress();
 		};
 		this.runClosuresTracker.registerRunClosure(handle, doRun);
-		return new require_promises.RestateSinglePromise(this, handle, completeCommandPromiseUsing(require_sdk_shared_core_wasm_bindings.WasmCommandType.Run, commandIndex, SuccessWithSerde(serde$1, this.journalValueCodec), Failure));
+		return new require_promises.SingleRestatePromise(this, handle, completeCommandPromiseUsing(require_sdk_shared_core_wasm_bindings.WasmCommandType.Run, commandIndex, SuccessWithSerde(serde$1, this.journalValueCodec), Failure));
 	}
 	sleep(duration, name) {
 		return this.processCompletableEntry(require_sdk_shared_core_wasm_bindings.WasmCommandType.Sleep, () => {
@@ -208,15 +218,15 @@ var ContextImpl = class {
 		try {
 			awakeable = this.coreVm.sys_awakeable();
 		} catch (e) {
-			this.handleInvocationEndError(e);
+			this.abortAttempt(e);
 			return {
 				id: "invalid",
-				promise: new require_promises.RestatePendingPromise(this)
+				promise: require_promises.ConstRestatePromise.pending()
 			};
 		}
 		return {
 			id: awakeable.id,
-			promise: new require_promises.RestateSinglePromise(this, awakeable.handle, completeSignalPromiseUsing(VoidAsUndefined, SuccessWithSerde(serde$1 ?? this.defaultSerde, this.journalValueCodec), Failure))
+			promise: new require_promises.SingleRestatePromise(this, awakeable.handle, completeSignalPromiseUsing(VoidAsUndefined, SuccessWithSerde(serde$1 ?? this.defaultSerde, this.journalValueCodec), Failure))
 		};
 	}
 	resolveAwakeable(id, payload, serde$1) {
@@ -229,41 +239,53 @@ var ContextImpl = class {
 	}
 	rejectAwakeable(id, reason) {
 		this.processNonCompletableEntry(require_sdk_shared_core_wasm_bindings.WasmCommandType.CompleteAwakeable, () => {}, (vm) => {
-			vm.sys_complete_awakeable_failure(id, {
-				code: require_errors.UNKNOWN_ERROR_CODE,
-				message: reason,
-				metadata: []
-			});
+			vm.sys_complete_awakeable_failure(id, toWasmFailure(reason));
 		});
 	}
+	signal(name, serde$1) {
+		let handle;
+		try {
+			handle = this.coreVm.sys_signal(name);
+		} catch (e) {
+			this.abortAttempt(e);
+			return require_promises.ConstRestatePromise.pending();
+		}
+		return new require_promises.SingleRestatePromise(this, handle, completeSignalPromiseUsing(VoidAsUndefined, SuccessWithSerde(serde$1 ?? this.defaultSerde, this.journalValueCodec), Failure));
+	}
+	invocation(invocationId) {
+		return new InvocationReferenceImpl(this, invocationId);
+	}
 	promise(name, serde$1) {
 		return new DurablePromiseImpl(this, name, serde$1);
 	}
-	static createCombinator(combinatorConstructor, promises) {
-		const self = require_promises.extractContext(promises[0]);
-		if (!self) throw new Error("Not a combinable promise");
-		const castedPromises = [];
-		for (const promise of promises) {
-			if (require_promises.extractContext(promise) !== self) {
-				self.handleInvocationEndError(/* @__PURE__ */ new Error("You're mixing up RestatePromises from different RestateContext. This is not supported."));
-				return new require_promises.RestatePendingPromise(self);
-			}
-			castedPromises.push(promise);
-		}
-		return new require_promises.RestateCombinatorPromise(self, combinatorConstructor, castedPromises);
+	cancellation() {
+		if (!this.cancellationPromise || this.cancellationPromise.isCompleted()) this.cancellationPromise = new require_promises.SingleRestatePromise(this, 1, completeSignalPromiseUsing(VoidAsUndefined));
+		return this.cancellationPromise;
+	}
+	cancelPreviousCalls() {
+		if (!this.trackedInvocationIdPromises) return require_promises.ConstRestatePromise.resolve([]);
+		return require_promises.CombinatorRestatePromise.fromPromises((p) => Promise.allSettled(p), this.trackedInvocationIdPromises.splice(0)).map((results, failure) => {
+			if (failure) throw failure;
+			const cancelled = [];
+			for (const result of results) if (result.status === "fulfilled") {
+				this._cancel(result.value);
+				cancelled.push(result.value);
+			} else this.console.warn(`Error when trying to get invocation id: ${result.reason}`);
+			return cancelled;
+		});
 	}
 	processNonCompletableEntry(commandType, prepare, vmCall) {
 		let input;
 		try {
 			input = prepare();
 		} catch (e) {
-			this.handleInvocationEndError(e, (vm, error) => vm.notify_error_for_next_command(error.message, error.stack, commandType));
+			this.abortAttempt(e, commandType);
 			return;
 		}
 		try {
 			vmCall(this.coreVm, input);
 		} catch (e) {
-			this.handleInvocationEndError(e);
+			this.abortAttempt(e);
 		}
 	}
 	processCompletableEntry(commandType, prepare, vmCall, ...completers) {
@@ -271,40 +293,38 @@ var ContextImpl = class {
 		try {
 			input = prepare();
 		} catch (e) {
-			this.handleInvocationEndError(e, (vm, error) => vm.notify_error_for_next_command(error.message, error.stack, commandType));
-			return new require_promises.RestatePendingPromise(this);
+			this.abortAttempt(e, commandType);
+			return require_promises.ConstRestatePromise.pending();
 		}
 		let handle;
 		try {
 			handle = vmCall(this.coreVm, input);
 		} catch (e) {
-			this.handleInvocationEndError(e);
-			return new require_promises.RestatePendingPromise(this);
+			this.abortAttempt(e);
+			return require_promises.ConstRestatePromise.pending();
 		}
 		const commandIndex = this.coreVm.last_command_index();
-		return new require_promises.RestateSinglePromise(this, handle, completeCommandPromiseUsing(commandType, commandIndex, ...completers));
-	}
-	promiseExecutorErrorCallback(e) {
-		if (e instanceof AsyncCompleterError) {
-			const cause = require_errors.ensureError(e.cause);
-			require_errors.logError(this.vmLogger, e.cause);
-			this.coreVm.notify_error_for_specific_command(cause.message, cause.stack, e.commandType, e.commandIndex, null);
-		} else {
-			const error = require_errors.ensureError(e);
-			require_errors.logError(this.vmLogger, error);
-			if (!(error instanceof require_errors.RestateError)) this.coreVm.notify_error(error.message, error.stack);
-		}
-		this.invocationEndPromise.resolve();
+		return new require_promises.SingleRestatePromise(this, handle, completeCommandPromiseUsing(commandType, commandIndex, ...completers));
 	}
-	handleInvocationEndError(e, notify_vm_error = (vm, error$1) => {
-		vm.notify_error(error$1.message, error$1.stack);
-	}) {
-		const error = require_errors.ensureError(e);
-		require_errors.logError(this.vmLogger, error);
-		notify_vm_error(this.coreVm, error);
-		this.invocationEndPromise.resolve();
+	abortAttempt(e, commandType) {
+		this.invocationEndPromise.reject(commandType !== void 0 ? new CommandError(e, commandType) : require_errors.ensureError(e));
 	}
 };
+function toWasmFailure(reason) {
+	if (typeof reason === "string") return {
+		code: require_errors.UNKNOWN_ERROR_CODE,
+		message: reason,
+		metadata: []
+	};
+	return {
+		code: reason.code,
+		message: reason.message,
+		metadata: Object.entries(reason.metadata ?? {}).map(([key, value]) => ({
+			key,
+			value
+		}))
+	};
+}
 function unpackRunParameters(a, b) {
 	if (typeof a === "string") {
 		if (typeof b !== "function") throw new TypeError("");
@@ -317,6 +337,38 @@ function unpackRunParameters(a, b) {
 	if (b) throw new TypeError("unexpected a function as a second parameter.");
 	return { action: a };
 }
+var InvocationReferenceImpl = class {
+	constructor(ctx, invocationId) {
+		this.ctx = ctx;
+		this.invocationId = invocationId;
+	}
+	signal(name, serde$1) {
+		return new SignalReferenceImpl(this.ctx, this.invocationId, name, serde$1);
+	}
+	cancel() {
+		this.ctx.cancel(this.invocationId);
+	}
+	attach(serde$1) {
+		return this.ctx.attach(this.invocationId, serde$1);
+	}
+};
+var SignalReferenceImpl = class {
+	serde;
+	constructor(ctx, invocationId, name, serde$1) {
+		this.ctx = ctx;
+		this.invocationId = invocationId;
+		this.name = name;
+		this.serde = serde$1 ?? this.ctx.defaultSerde;
+	}
+	resolve(payload) {
+		this.ctx.processNonCompletableEntry(require_sdk_shared_core_wasm_bindings.WasmCommandType.SendSignal, () => this.ctx.journalValueCodec.encode(this.serde.serialize(payload)), (vm, bytes) => vm.sys_complete_signal_success(this.invocationId, this.name, bytes));
+	}
+	reject(reason) {
+		this.ctx.processNonCompletableEntry(require_sdk_shared_core_wasm_bindings.WasmCommandType.SendSignal, () => {}, (vm) => {
+			vm.sys_complete_signal_failure(this.invocationId, this.name, toWasmFailure(reason));
+		});
+	}
+};
 var DurablePromiseImpl = class {
 	serde;
 	constructor(ctx, name, serde$1) {
@@ -376,19 +428,25 @@ var RunClosuresTracker = class {
 		}
 	}
 };
-var AsyncCompleterError = class {
+var CommandError = class extends Error {
 	constructor(cause, commandType, commandIndex) {
+		const msg = cause instanceof Error ? cause.message : String(cause);
+		super(msg, { cause });
 		this.cause = cause;
 		this.commandType = commandType;
 		this.commandIndex = commandIndex;
 	}
+	/** True when the error is for a specific command that exists in the journal. */
+	get hasCommandIndex() {
+		return this.commandIndex !== void 0;
+	}
 };
 function completeCommandPromiseUsing(commandType, commandIndex, ...completers) {
 	return async (value, prom) => {
 		try {
 			for (const completer of completers) if (await completer(value, prom)) return;
 		} catch (e) {
-			throw new AsyncCompleterError(e, commandType, commandIndex);
+			throw new CommandError(e, commandType, commandIndex);
 		}
 		throw new Error(`Unexpected variant in async result: ${JSON.stringify(value)}`);
 	};
@@ -455,4 +513,5 @@ const InvocationIdCompleter = (value, prom) => {
 };
 
 //#endregion
+exports.CommandError = CommandError;
 exports.ContextImpl = ContextImpl;

package/dist/context_impl.d.cts

@@ -0,0 +1,8 @@
+import "./types/errors.cjs";
+import "./types/rpc.cjs";
+import "./context.cjs";
+import "./internal.cjs";
+import "./endpoint/components.cjs";
+import "./endpoint/handlers/types.cjs";
+import "./promises.cjs";
+import { Duration, JournalValueCodec, Serde, Service, ServiceDefinitionFrom, VirtualObject, VirtualObjectDefinitionFrom, Workflow, WorkflowDefinitionFrom } from "@restatedev/restate-sdk-core";