@ahoo-wang/wow-client 9.2.0-rc.0

package/dist/client/command/commandHeaders.d.cts

@@ -0,0 +1,75 @@
+/**
+ * Command Header Constants
+ *
+ * The HTTP headers a Wow command route reads. Each value is a string literal
+ * type, so `CommandRequestHeaders` can type the value of every header by its
+ * name. {@link commandHeaders} and {@link waitStrategy} build them from typed
+ * options.
+ *
+ * Mirrors `CommandComponent.Header` in
+ * `wow-openapi/src/main/kotlin/me/ahoo/wow/openapi/aggregate/command/CommandComponent.kt`.
+ *
+ * @example
+ * ```typescript
+ * const headers: CommandRequestHeaders = {
+ *   [CommandHeaders.TENANT_ID]: 'tenant-123',
+ *   [CommandHeaders.WAIT_STAGE]: CommandStage.SNAPSHOT,
+ * };
+ * ```
+ */
+export declare const CommandHeaders: Readonly<{
+    /** Prefix of the command headers */
+    readonly COMMAND_HEADERS_PREFIX: "Command-";
+    /** Tenant of the command, when the route has no tenant path segment */
+    readonly TENANT_ID: "Command-Tenant-Id";
+    /** Owner of the command, when the route has no owner path segment */
+    readonly OWNER_ID: "Command-Owner-Id";
+    /**
+     * Space identifier header, `Wow-Space-Id`
+     * Used to send the command into a space. The server reads it only for an
+     * aggregate declared `@AggregateRoute(spaced = true)`; any other aggregate
+     * ignores it and keeps the default space.
+     *
+     * The server shares this header with queries, so it has the `Wow-` prefix
+     * rather than `Command-`; it is the same value as {@link WowHeaders.SPACE_ID}.
+     */
+    readonly SPACE_ID: "Wow-Space-Id";
+    /** Aggregate the command targets, when the route has no id path segment */
+    readonly AGGREGATE_ID: "Command-Aggregate-Id";
+    /** The aggregate version the command expects; a mismatch is a conflict */
+    readonly AGGREGATE_VERSION: "Command-Aggregate-Version";
+    /** Prefix of the wait headers */
+    readonly WAIT_PREFIX: "Command-Wait-";
+    /** How long the server waits for the wait stage, in milliseconds */
+    readonly WAIT_TIME_OUT: "Command-Wait-Timeout";
+    /** The stage to wait for; the server waits for `PROCESSED` when absent */
+    readonly WAIT_STAGE: "Command-Wait-Stage";
+    /** The bounded context whose processing the wait stage refers to */
+    readonly WAIT_CONTEXT: "Command-Wait-Context";
+    /** The processor whose processing the wait stage refers to */
+    readonly WAIT_PROCESSOR: "Command-Wait-Processor";
+    /** The function whose processing the wait stage refers to */
+    readonly WAIT_FUNCTION: "Command-Wait-Function";
+    /** Prefix of the wait-chain tail headers */
+    readonly WAIT_TAIL_PREFIX: "Command-Wait-Tail-";
+    /** The stage the command a saga sends must reach; only with `SAGA_HANDLED` */
+    readonly WAIT_TAIL_STAGE: "Command-Wait-Tail-Stage";
+    /** The bounded context of the wait-chain tail */
+    readonly WAIT_TAIL_CONTEXT: "Command-Wait-Tail-Context";
+    /** The processor of the wait-chain tail */
+    readonly WAIT_TAIL_PROCESSOR: "Command-Wait-Tail-Processor";
+    /** The function of the wait-chain tail */
+    readonly WAIT_TAIL_FUNCTION: "Command-Wait-Tail-Function";
+    /** Idempotency key of the command; a repeated one is refused */
+    readonly REQUEST_ID: "Command-Request-Id";
+    /** Whether the server may process the command locally, `true` or `false` */
+    readonly LOCAL_FIRST: "Command-Local-First";
+    /** Bounded context of the aggregate, for the `/wow/command/send` route */
+    readonly COMMAND_AGGREGATE_CONTEXT: "Command-Aggregate-Context";
+    /** Name of the aggregate, for the `/wow/command/send` route */
+    readonly COMMAND_AGGREGATE_NAME: "Command-Aggregate-Name";
+    /** Fully qualified command type, for the `/wow/command/send` route */
+    readonly COMMAND_TYPE: "Command-Type";
+    /** Prefix of the custom headers the server copies into the command header */
+    readonly COMMAND_HEADER_X_PREFIX: "Command-Header-";
+}>;

package/dist/client/command/commandHeaders.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Command Header Constants
+ *
+ * The HTTP headers a Wow command route reads. Each value is a string literal
+ * type, so `CommandRequestHeaders` can type the value of every header by its
+ * name. {@link commandHeaders} and {@link waitStrategy} build them from typed
+ * options.
+ *
+ * Mirrors `CommandComponent.Header` in
+ * `wow-openapi/src/main/kotlin/me/ahoo/wow/openapi/aggregate/command/CommandComponent.kt`.
+ *
+ * @example
+ * ```typescript
+ * const headers: CommandRequestHeaders = {
+ *   [CommandHeaders.TENANT_ID]: 'tenant-123',
+ *   [CommandHeaders.WAIT_STAGE]: CommandStage.SNAPSHOT,
+ * };
+ * ```
+ */
+export declare const CommandHeaders: Readonly<{
+    /** Prefix of the command headers */
+    readonly COMMAND_HEADERS_PREFIX: "Command-";
+    /** Tenant of the command, when the route has no tenant path segment */
+    readonly TENANT_ID: "Command-Tenant-Id";
+    /** Owner of the command, when the route has no owner path segment */
+    readonly OWNER_ID: "Command-Owner-Id";
+    /**
+     * Space identifier header, `Wow-Space-Id`
+     * Used to send the command into a space. The server reads it only for an
+     * aggregate declared `@AggregateRoute(spaced = true)`; any other aggregate
+     * ignores it and keeps the default space.
+     *
+     * The server shares this header with queries, so it has the `Wow-` prefix
+     * rather than `Command-`; it is the same value as {@link WowHeaders.SPACE_ID}.
+     */
+    readonly SPACE_ID: "Wow-Space-Id";
+    /** Aggregate the command targets, when the route has no id path segment */
+    readonly AGGREGATE_ID: "Command-Aggregate-Id";
+    /** The aggregate version the command expects; a mismatch is a conflict */
+    readonly AGGREGATE_VERSION: "Command-Aggregate-Version";
+    /** Prefix of the wait headers */
+    readonly WAIT_PREFIX: "Command-Wait-";
+    /** How long the server waits for the wait stage, in milliseconds */
+    readonly WAIT_TIME_OUT: "Command-Wait-Timeout";
+    /** The stage to wait for; the server waits for `PROCESSED` when absent */
+    readonly WAIT_STAGE: "Command-Wait-Stage";
+    /** The bounded context whose processing the wait stage refers to */
+    readonly WAIT_CONTEXT: "Command-Wait-Context";
+    /** The processor whose processing the wait stage refers to */
+    readonly WAIT_PROCESSOR: "Command-Wait-Processor";
+    /** The function whose processing the wait stage refers to */
+    readonly WAIT_FUNCTION: "Command-Wait-Function";
+    /** Prefix of the wait-chain tail headers */
+    readonly WAIT_TAIL_PREFIX: "Command-Wait-Tail-";
+    /** The stage the command a saga sends must reach; only with `SAGA_HANDLED` */
+    readonly WAIT_TAIL_STAGE: "Command-Wait-Tail-Stage";
+    /** The bounded context of the wait-chain tail */
+    readonly WAIT_TAIL_CONTEXT: "Command-Wait-Tail-Context";
+    /** The processor of the wait-chain tail */
+    readonly WAIT_TAIL_PROCESSOR: "Command-Wait-Tail-Processor";
+    /** The function of the wait-chain tail */
+    readonly WAIT_TAIL_FUNCTION: "Command-Wait-Tail-Function";
+    /** Idempotency key of the command; a repeated one is refused */
+    readonly REQUEST_ID: "Command-Request-Id";
+    /** Whether the server may process the command locally, `true` or `false` */
+    readonly LOCAL_FIRST: "Command-Local-First";
+    /** Bounded context of the aggregate, for the `/wow/command/send` route */
+    readonly COMMAND_AGGREGATE_CONTEXT: "Command-Aggregate-Context";
+    /** Name of the aggregate, for the `/wow/command/send` route */
+    readonly COMMAND_AGGREGATE_NAME: "Command-Aggregate-Name";
+    /** Fully qualified command type, for the `/wow/command/send` route */
+    readonly COMMAND_TYPE: "Command-Type";
+    /** Prefix of the custom headers the server copies into the command header */
+    readonly COMMAND_HEADER_X_PREFIX: "Command-Header-";
+}>;

package/dist/client/command/commandHeaders.es.js

@@ -0,0 +1,31 @@
+import { WowHeaders as e } from "../../error/headers.es.js";
+//#region src/client/command/commandHeaders.ts
+var t = Object.freeze({
+	COMMAND_HEADERS_PREFIX: "Command-",
+	TENANT_ID: "Command-Tenant-Id",
+	OWNER_ID: "Command-Owner-Id",
+	SPACE_ID: e.SPACE_ID,
+	AGGREGATE_ID: "Command-Aggregate-Id",
+	AGGREGATE_VERSION: "Command-Aggregate-Version",
+	WAIT_PREFIX: "Command-Wait-",
+	WAIT_TIME_OUT: "Command-Wait-Timeout",
+	WAIT_STAGE: "Command-Wait-Stage",
+	WAIT_CONTEXT: "Command-Wait-Context",
+	WAIT_PROCESSOR: "Command-Wait-Processor",
+	WAIT_FUNCTION: "Command-Wait-Function",
+	WAIT_TAIL_PREFIX: "Command-Wait-Tail-",
+	WAIT_TAIL_STAGE: "Command-Wait-Tail-Stage",
+	WAIT_TAIL_CONTEXT: "Command-Wait-Tail-Context",
+	WAIT_TAIL_PROCESSOR: "Command-Wait-Tail-Processor",
+	WAIT_TAIL_FUNCTION: "Command-Wait-Tail-Function",
+	REQUEST_ID: "Command-Request-Id",
+	LOCAL_FIRST: "Command-Local-First",
+	COMMAND_AGGREGATE_CONTEXT: "Command-Aggregate-Context",
+	COMMAND_AGGREGATE_NAME: "Command-Aggregate-Name",
+	COMMAND_TYPE: "Command-Type",
+	COMMAND_HEADER_X_PREFIX: "Command-Header-"
+});
+//#endregion
+export { t as CommandHeaders };
+
+//# sourceMappingURL=commandHeaders.es.js.map

package/dist/client/command/commandHeaders.es.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandHeaders.es.js","names":["CommandHeaders","WowHeaders"],"sources":["../../../src/client/command/commandHeaders.ts"],"sourcesContent":["/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { WowHeaders } from '../../error/headers.js';\n\n/**\n * Command Header Constants\n *\n * The HTTP headers a Wow command route reads. Each value is a string literal\n * type, so `CommandRequestHeaders` can type the value of every header by its\n * name. {@link commandHeaders} and {@link waitStrategy} build them from typed\n * options.\n *\n * Mirrors `CommandComponent.Header` in\n * `wow-openapi/src/main/kotlin/me/ahoo/wow/openapi/aggregate/command/CommandComponent.kt`.\n *\n * @example\n * ```typescript\n * const headers: CommandRequestHeaders = {\n *   [CommandHeaders.TENANT_ID]: 'tenant-123',\n *   [CommandHeaders.WAIT_STAGE]: CommandStage.SNAPSHOT,\n * };\n * ```\n */\nexport const CommandHeaders = Object.freeze({\n  /** Prefix of the command headers */\n  COMMAND_HEADERS_PREFIX: 'Command-',\n\n  /** Tenant of the command, when the route has no tenant path segment */\n  TENANT_ID: 'Command-Tenant-Id',\n\n  /** Owner of the command, when the route has no owner path segment */\n  OWNER_ID: 'Command-Owner-Id',\n\n  /**\n   * Space identifier header, `Wow-Space-Id`\n   * Used to send the command into a space. The server reads it only for an\n   * aggregate declared `@AggregateRoute(spaced = true)`; any other aggregate\n   * ignores it and keeps the default space.\n   *\n   * The server shares this header with queries, so it has the `Wow-` prefix\n   * rather than `Command-`; it is the same value as {@link WowHeaders.SPACE_ID}.\n   */\n  SPACE_ID: WowHeaders.SPACE_ID,\n\n  /** Aggregate the command targets, when the route has no id path segment */\n  AGGREGATE_ID: 'Command-Aggregate-Id',\n\n  /** The aggregate version the command expects; a mismatch is a conflict */\n  AGGREGATE_VERSION: 'Command-Aggregate-Version',\n\n  /** Prefix of the wait headers */\n  WAIT_PREFIX: 'Command-Wait-',\n\n  /** How long the server waits for the wait stage, in milliseconds */\n  WAIT_TIME_OUT: 'Command-Wait-Timeout',\n\n  /** The stage to wait for; the server waits for `PROCESSED` when absent */\n  WAIT_STAGE: 'Command-Wait-Stage',\n\n  /** The bounded context whose processing the wait stage refers to */\n  WAIT_CONTEXT: 'Command-Wait-Context',\n\n  /** The processor whose processing the wait stage refers to */\n  WAIT_PROCESSOR: 'Command-Wait-Processor',\n\n  /** The function whose processing the wait stage refers to */\n  WAIT_FUNCTION: 'Command-Wait-Function',\n\n  /** Prefix of the wait-chain tail headers */\n  WAIT_TAIL_PREFIX: 'Command-Wait-Tail-',\n\n  /** The stage the command a saga sends must reach; only with `SAGA_HANDLED` */\n  WAIT_TAIL_STAGE: 'Command-Wait-Tail-Stage',\n\n  /** The bounded context of the wait-chain tail */\n  WAIT_TAIL_CONTEXT: 'Command-Wait-Tail-Context',\n\n  /** The processor of the wait-chain tail */\n  WAIT_TAIL_PROCESSOR: 'Command-Wait-Tail-Processor',\n\n  /** The function of the wait-chain tail */\n  WAIT_TAIL_FUNCTION: 'Command-Wait-Tail-Function',\n\n  /** Idempotency key of the command; a repeated one is refused */\n  REQUEST_ID: 'Command-Request-Id',\n\n  /** Whether the server may process the command locally, `true` or `false` */\n  LOCAL_FIRST: 'Command-Local-First',\n\n  /** Bounded context of the aggregate, for the `/wow/command/send` route */\n  COMMAND_AGGREGATE_CONTEXT: 'Command-Aggregate-Context',\n\n  /** Name of the aggregate, for the `/wow/command/send` route */\n  COMMAND_AGGREGATE_NAME: 'Command-Aggregate-Name',\n\n  /** Fully qualified command type, for the `/wow/command/send` route */\n  COMMAND_TYPE: 'Command-Type',\n\n  /** Prefix of the custom headers the server copies into the command header */\n  COMMAND_HEADER_X_PREFIX: 'Command-Header-',\n} as const);\n"],"mappings":";;AAkCA,IAAaA,IAAiB,OAAO,OAAO;CAE1C,wBAAwB;CAGxB,WAAW;CAGX,UAAU;CAWV,UAAUC,EAAW;CAGrB,cAAc;CAGd,mBAAmB;CAGnB,aAAa;CAGb,eAAe;CAGf,YAAY;CAGZ,cAAc;CAGd,gBAAgB;CAGhB,eAAe;CAGf,kBAAkB;CAGlB,iBAAiB;CAGjB,mBAAmB;CAGnB,qBAAqB;CAGrB,oBAAoB;CAGpB,YAAY;CAGZ,aAAa;CAGb,2BAA2B;CAG3B,wBAAwB;CAGxB,cAAc;CAGd,yBAAyB;AAC3B,CAAU"}

package/dist/client/command/commandRequest.cjs

@@ -0,0 +1,2 @@
+const e=require("../../model/command.cjs"),t=require("./commandHeaders.cjs");var n=new Set(Object.values(e.CommandStage));function r(e,t){if(!n.has(t))throw TypeError(`${e} must be one of ${[...n].join(`, `)}, got [${t}].`);return t}function i(e,t,n){if(!Number.isSafeInteger(t)||t<n)throw TypeError(`${e} must be an integer of at least ${n}, got [${t}].`);return`${t}`}function a(e,t,n){n!==void 0&&(e[t]=n)}function o(e){let n={};return a(n,t.CommandHeaders.TENANT_ID,e.tenantId),a(n,t.CommandHeaders.OWNER_ID,e.ownerId),a(n,t.CommandHeaders.SPACE_ID,e.spaceId),a(n,t.CommandHeaders.AGGREGATE_ID,e.aggregateId),e.aggregateVersion!==void 0&&(n[t.CommandHeaders.AGGREGATE_VERSION]=i(`aggregateVersion`,e.aggregateVersion,0)),a(n,t.CommandHeaders.REQUEST_ID,e.requestId),e.localFirst!==void 0&&(n[t.CommandHeaders.LOCAL_FIRST]=e.localFirst?`true`:`false`),n}function s(n){let o={};if(n.stage!==void 0&&(o[t.CommandHeaders.WAIT_STAGE]=r(`stage`,n.stage)),a(o,t.CommandHeaders.WAIT_CONTEXT,n.context),a(o,t.CommandHeaders.WAIT_PROCESSOR,n.processor),a(o,t.CommandHeaders.WAIT_FUNCTION,n.function),n.tail!==void 0){if(n.stage!==e.CommandStage.SAGA_HANDLED)throw TypeError(`A wait tail needs the SAGA_HANDLED stage.`);o[t.CommandHeaders.WAIT_TAIL_STAGE]=r(`tail.stage`,n.tail.stage),a(o,t.CommandHeaders.WAIT_TAIL_CONTEXT,n.tail.context),a(o,t.CommandHeaders.WAIT_TAIL_PROCESSOR,n.tail.processor),a(o,t.CommandHeaders.WAIT_TAIL_FUNCTION,n.tail.function)}return n.timeoutMs!==void 0&&(o[t.CommandHeaders.WAIT_TIME_OUT]=i(`timeoutMs`,n.timeoutMs,1)),o}exports.commandHeaders=o,exports.waitStrategy=s;
+//# sourceMappingURL=commandRequest.cjs.map

package/dist/client/command/commandRequest.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandRequest.cjs","names":["CommandStage","CommandHeaders","require_command","require_commandHeaders","STAGES","stageName","stage","label","integer","value","minimum","put","name","commandHeaders","headers","options","waitStrategy"],"sources":["../../../src/client/command/commandRequest.ts"],"sourcesContent":["/*\n * Copyright [2021-present] [ahoo wang <ahoowang@qq.com> (https://github.com/Ahoo-Wang)].\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *      http://www.apache.org/licenses/LICENSE-2.0\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { RequestHeaders, UrlParams } from '@ahoo-wang/fetcher';\nimport { CommandHeaders } from './commandHeaders.js';\nimport type { UrlPathParams } from '../routing.js';\nimport type { ParameterRequest } from '@ahoo-wang/fetcher-decorator';\nimport { CommandStage } from '../../model/index.js';\nimport type { CommandBody } from './types.js';\n\n/** A command stage, as the enum member or as its name. */\nexport type CommandStageName = CommandStage | `${CommandStage}`;\n\n/**\n * The headers of a command request.\n *\n * Every command header is optional and typed by what the server parses:\n * a stage is a {@link CommandStage}, a version or a timeout is an integer,\n * `Local-First` is a boolean. Any other header (`Authorization`, a\n * `Command-Header-*` extension, …) is still allowed as a string. Build these\n * with {@link commandHeaders} and {@link waitStrategy} rather than by hand.\n *\n * @example\n * ```typescript\n * const headers: CommandRequestHeaders = {\n *   ...commandHeaders({ ownerId: 'user-1', requestId }),\n *   ...waitStrategy({ stage: CommandStage.SNAPSHOT, timeoutMs: 10_000 }),\n * };\n * ```\n */\nexport interface CommandRequestHeaders extends RequestHeaders {\n  /** Tenant of the command, when the route has no tenant path segment */\n  [CommandHeaders.TENANT_ID]?: string;\n  /** Owner of the command, when the route has no owner path segment */\n  [CommandHeaders.OWNER_ID]?: string;\n  /** Space of the command, `Wow-Space-Id` */\n  [CommandHeaders.SPACE_ID]?: string;\n  /** Aggregate the command targets, when the route has no id path segment */\n  [CommandHeaders.AGGREGATE_ID]?: string;\n  /** The aggregate version the command expects, an integer */\n  [CommandHeaders.AGGREGATE_VERSION]?: `${number}`;\n  /** How long the server waits, in whole milliseconds */\n  [CommandHeaders.WAIT_TIME_OUT]?: `${number}`;\n  /** The stage to wait for; `PROCESSED` when absent */\n  [CommandHeaders.WAIT_STAGE]?: CommandStageName;\n  /** The bounded context the wait stage refers to */\n  [CommandHeaders.WAIT_CONTEXT]?: string;\n  /** The processor the wait stage refers to */\n  [CommandHeaders.WAIT_PROCESSOR]?: string;\n  /** The function the wait stage refers to */\n  [CommandHeaders.WAIT_FUNCTION]?: string;\n  /** The stage of the wait-chain tail; only with a `SAGA_HANDLED` wait stage */\n  [CommandHeaders.WAIT_TAIL_STAGE]?: CommandStageName;\n  /** The bounded context of the wait-chain tail */\n  [CommandHeaders.WAIT_TAIL_CONTEXT]?: string;\n  /** The processor of the wait-chain tail */\n  [CommandHeaders.WAIT_TAIL_PROCESSOR]?: string;\n  /** The function of the wait-chain tail */\n  [CommandHeaders.WAIT_TAIL_FUNCTION]?: string;\n  /** Idempotency key of the command */\n  [CommandHeaders.REQUEST_ID]?: string;\n  /** Whether the server may process the command locally */\n  [CommandHeaders.LOCAL_FIRST]?: 'true' | 'false';\n  /** Bounded context of the aggregate, for `/wow/command/send` */\n  [CommandHeaders.COMMAND_AGGREGATE_CONTEXT]?: string;\n  /** Name of the aggregate, for `/wow/command/send` */\n  [CommandHeaders.COMMAND_AGGREGATE_NAME]?: string;\n  /** Fully qualified command type, for `/wow/command/send` */\n  [CommandHeaders.COMMAND_TYPE]?: string;\n}\n\n/** Who a command is for; each option sets one command header. */\nexport interface CommandHeaderOptions {\n  /** The tenant, `Command-Tenant-Id`; for a route without a tenant segment. */\n  tenantId?: string;\n  /** The owner, `Command-Owner-Id`; for a route without an owner segment. */\n  ownerId?: string;\n  /**\n   * The space, `Wow-Space-Id`; the tenant's default space when absent. Only a\n   * spaced aggregate reads it.\n   */\n  spaceId?: string;\n  /**\n   * The target aggregate, `Command-Aggregate-Id`; for a route without an id\n   * segment.\n   */\n  aggregateId?: string;\n  /** The aggregate version the command expects: a non-negative integer. */\n  aggregateVersion?: number;\n  /** Idempotency key; the server refuses a repeated one. */\n  requestId?: string;\n  /**\n   * Whether the server may process the command in its own process when it\n   * hosts the aggregate, `Command-Local-First`; it does unless this is `false`.\n   */\n  localFirst?: boolean;\n}\n\n/** The processing a wait stage refers to; blank means any. */\nexport interface WaitFunction {\n  context?: string;\n  processor?: string;\n  function?: string;\n}\n\n/** Wait for one stage of the command. */\nexport interface WaitStageOptions extends WaitFunction {\n  /** The stage to wait for. The server waits for `PROCESSED` when absent. */\n  stage?: CommandStageName;\n  /** How long the server waits, in whole milliseconds. */\n  timeoutMs?: number;\n  tail?: never;\n}\n\n/**\n * Wait for a saga to handle the command's events, and then for the command\n * that saga sends to reach `tail.stage` — Wow's wait chain.\n */\nexport interface WaitChainOptions extends WaitFunction {\n  stage: CommandStage.SAGA_HANDLED | 'SAGA_HANDLED';\n  tail: WaitFunction & { stage: CommandStageName };\n  /** How long the server waits, in whole milliseconds. */\n  timeoutMs?: number;\n}\n\n/** What {@link waitStrategy} takes: one stage, or a wait chain. */\nexport type WaitStrategyOptions = WaitStageOptions | WaitChainOptions;\n\nconst STAGES: ReadonlySet<string> = new Set(Object.values(CommandStage));\n\nfunction stageName(label: string, stage: string): CommandStageName {\n  if (!STAGES.has(stage)) {\n    throw new TypeError(\n      `${label} must be one of ${[...STAGES].join(', ')}, got [${stage}].`,\n    );\n  }\n  return stage as CommandStageName;\n}\n\nfunction integer(label: string, value: number, minimum: number): `${number}` {\n  if (!Number.isSafeInteger(value) || value < minimum) {\n    throw new TypeError(\n      `${label} must be an integer of at least ${minimum}, got [${value}].`,\n    );\n  }\n  return `${value}`;\n}\n\nfunction put(\n  headers: CommandRequestHeaders,\n  name: keyof CommandRequestHeaders,\n  value: string | undefined,\n): void {\n  if (value !== undefined) headers[name] = value as never;\n}\n\n/**\n * Builds the headers that say who a command is for. Options left out send\n * no header.\n *\n * @throws TypeError when `aggregateVersion` is not a non-negative integer.\n *\n * @example\n * ```typescript\n * await commandClient.send({\n *   path: 'owner/{ownerId}/cart/add_cart_item',\n *   method: 'POST',\n *   headers: commandHeaders({ spaceId: 'store-1', requestId: crypto.randomUUID() }),\n *   body: { productId: 'p-1', quantity: 1 },\n * });\n * ```\n */\nexport function commandHeaders(\n  options: CommandHeaderOptions,\n): CommandRequestHeaders {\n  const headers: CommandRequestHeaders = {};\n  put(headers, CommandHeaders.TENANT_ID, options.tenantId);\n  put(headers, CommandHeaders.OWNER_ID, options.ownerId);\n  put(headers, CommandHeaders.SPACE_ID, options.spaceId);\n  put(headers, CommandHeaders.AGGREGATE_ID, options.aggregateId);\n  if (options.aggregateVersion !== undefined) {\n    headers[CommandHeaders.AGGREGATE_VERSION] = integer(\n      'aggregateVersion',\n      options.aggregateVersion,\n      0,\n    );\n  }\n  put(headers, CommandHeaders.REQUEST_ID, options.requestId);\n  if (options.localFirst !== undefined) {\n    headers[CommandHeaders.LOCAL_FIRST] = options.localFirst ? 'true' : 'false';\n  }\n  return headers;\n}\n\n/**\n * Builds the headers that say how long, and for what, the server waits\n * before it answers a command — Kotlin's `WaitingFor`. Options left out send\n * no header, and the server's defaults apply: `PROCESSED` in the command's own\n * bounded context.\n *\n * @throws TypeError when a stage is not a `CommandStage`, when `timeoutMs` is\n *   not a positive integer, or when a `tail` is given with a stage other than\n *   `SAGA_HANDLED` (the server ignores the tail then).\n *\n * @example\n * ```typescript\n * // Answer once the snapshot is written, or after five seconds.\n * waitStrategy({ stage: CommandStage.SNAPSHOT, timeoutMs: 5_000 });\n *\n * // Answer once the saga's command has been processed.\n * waitStrategy({\n *   stage: 'SAGA_HANDLED',\n *   processor: 'TransferSaga',\n *   tail: { stage: 'PROCESSED', context: 'account' },\n * });\n * ```\n */\nexport function waitStrategy(\n  options: WaitStrategyOptions,\n): CommandRequestHeaders {\n  const headers: CommandRequestHeaders = {};\n  if (options.stage !== undefined) {\n    headers[CommandHeaders.WAIT_STAGE] = stageName('stage', options.stage);\n  }\n  put(headers, CommandHeaders.WAIT_CONTEXT, options.context);\n  put(headers, CommandHeaders.WAIT_PROCESSOR, options.processor);\n  put(headers, CommandHeaders.WAIT_FUNCTION, options.function);\n  if (options.tail !== undefined) {\n    if (options.stage !== CommandStage.SAGA_HANDLED) {\n      throw new TypeError('A wait tail needs the SAGA_HANDLED stage.');\n    }\n    headers[CommandHeaders.WAIT_TAIL_STAGE] = stageName(\n      'tail.stage',\n      options.tail.stage,\n    );\n    put(headers, CommandHeaders.WAIT_TAIL_CONTEXT, options.tail.context);\n    put(headers, CommandHeaders.WAIT_TAIL_PROCESSOR, options.tail.processor);\n    put(headers, CommandHeaders.WAIT_TAIL_FUNCTION, options.tail.function);\n  }\n  if (options.timeoutMs !== undefined) {\n    headers[CommandHeaders.WAIT_TIME_OUT] = integer(\n      'timeoutMs',\n      options.timeoutMs,\n      1,\n    );\n  }\n  return headers;\n}\n\n/**\n * The URL parameters of a {@link CommandRequest}: the values of the route's\n * path variables. A command takes no query string.\n */\nexport interface CommandUrlParams extends Omit<UrlParams, 'path' | 'query'> {\n  /** The path variables, such as `{ ownerId, id }`. */\n  path?: UrlPathParams;\n}\n\n/**\n * A command request: the path of the command route, its URL parameters, its\n * typed headers and its body.\n */\nexport interface CommandRequest<\n  C extends object = object,\n> extends ParameterRequest<CommandBody<C>> {\n  urlParams?: CommandUrlParams;\n  headers?: CommandRequestHeaders;\n  /**\n   * The body of the command request.\n   */\n  body?: CommandBody<C>;\n}\n"],"mappings":"6EA0IA,IAAMI,EAA8B,IAAI,IAAI,OAAO,OAAOJ,EAAAA,YAAY,CAAC,EAEvE,SAASK,EAAU,EAAe,EAAiC,CACjE,GAAI,CAACD,EAAO,IAAIE,CAAK,EACnB,MAAU,UACR,GAAGC,EAAM,kBAAkB,CAAC,GAAGH,CAAM,CAAC,CAAC,KAAK,IAAI,EAAE,SAASE,EAAM,GACnE,EAEF,OAAOA,CACT,CAEA,SAASE,EAAQ,EAAe,EAAe,EAA8B,CAC3E,GAAI,CAAC,OAAO,cAAcC,CAAK,GAAKA,EAAQC,EAC1C,MAAU,UACR,GAAGH,EAAM,kCAAkCG,EAAQ,SAASD,EAAM,GACpE,EAEF,MAAO,GAAGA,GACZ,CAEA,SAASE,EACP,EACA,EACA,EACM,CACFF,IAAU,IAAA,KAAW,EAAQG,GAAQH,EAC3C,CAkBA,SAAgBI,EACd,EACuB,CACvB,IAAMC,EAAiC,CAAC,EAgBxC,OAfAH,EAAIG,EAASb,EAAAA,eAAe,UAAWc,EAAQ,QAAQ,EACvDJ,EAAIG,EAASb,EAAAA,eAAe,SAAUc,EAAQ,OAAO,EACrDJ,EAAIG,EAASb,EAAAA,eAAe,SAAUc,EAAQ,OAAO,EACrDJ,EAAIG,EAASb,EAAAA,eAAe,aAAcc,EAAQ,WAAW,EACzDA,EAAQ,mBAAqB,IAAA,KAC/B,EAAQd,EAAAA,eAAe,mBAAqBO,EAC1C,mBACAO,EAAQ,iBACR,CACF,GAEFJ,EAAIG,EAASb,EAAAA,eAAe,WAAYc,EAAQ,SAAS,EACrDA,EAAQ,aAAe,IAAA,KACzB,EAAQd,EAAAA,eAAe,aAAec,EAAQ,WAAa,OAAS,SAE/DD,CACT,CAyBA,SAAgBE,EACd,EACuB,CACvB,IAAMF,EAAiC,CAAC,EAOxC,GANIC,EAAQ,QAAU,IAAA,KACpB,EAAQd,EAAAA,eAAe,YAAcI,EAAU,QAASU,EAAQ,KAAK,GAEvEJ,EAAIG,EAASb,EAAAA,eAAe,aAAcc,EAAQ,OAAO,EACzDJ,EAAIG,EAASb,EAAAA,eAAe,eAAgBc,EAAQ,SAAS,EAC7DJ,EAAIG,EAASb,EAAAA,eAAe,cAAec,EAAQ,QAAQ,EACvDA,EAAQ,OAAS,IAAA,GAAW,CAC9B,GAAIA,EAAQ,QAAUf,EAAAA,aAAa,aACjC,MAAU,UAAU,2CAA2C,EAEjE,EAAQC,EAAAA,eAAe,iBAAmBI,EACxC,aACAU,EAAQ,KAAK,KACf,EACAJ,EAAIG,EAASb,EAAAA,eAAe,kBAAmBc,EAAQ,KAAK,OAAO,EACnEJ,EAAIG,EAASb,EAAAA,eAAe,oBAAqBc,EAAQ,KAAK,SAAS,EACvEJ,EAAIG,EAASb,EAAAA,eAAe,mBAAoBc,EAAQ,KAAK,QAAQ,CACvE,CAQA,OAPIA,EAAQ,YAAc,IAAA,KACxB,EAAQd,EAAAA,eAAe,eAAiBO,EACtC,YACAO,EAAQ,UACR,CACF,GAEKD,CACT"}

package/dist/client/command/commandRequest.d.cts

@@ -0,0 +1,180 @@
+import { RequestHeaders, UrlParams } from '@ahoo-wang/fetcher';
+import { CommandHeaders } from './commandHeaders.cjs';
+import { UrlPathParams } from '../routing.cjs';
+import { ParameterRequest } from '@ahoo-wang/fetcher-decorator';
+import { CommandStage } from '../../model/index.cjs';
+import { CommandBody } from './types.cjs';
+/** A command stage, as the enum member or as its name. */
+export type CommandStageName = CommandStage | `${CommandStage}`;
+/**
+ * The headers of a command request.
+ *
+ * Every command header is optional and typed by what the server parses:
+ * a stage is a {@link CommandStage}, a version or a timeout is an integer,
+ * `Local-First` is a boolean. Any other header (`Authorization`, a
+ * `Command-Header-*` extension, …) is still allowed as a string. Build these
+ * with {@link commandHeaders} and {@link waitStrategy} rather than by hand.
+ *
+ * @example
+ * ```typescript
+ * const headers: CommandRequestHeaders = {
+ *   ...commandHeaders({ ownerId: 'user-1', requestId }),
+ *   ...waitStrategy({ stage: CommandStage.SNAPSHOT, timeoutMs: 10_000 }),
+ * };
+ * ```
+ */
+export interface CommandRequestHeaders extends RequestHeaders {
+    /** Tenant of the command, when the route has no tenant path segment */
+    [CommandHeaders.TENANT_ID]?: string;
+    /** Owner of the command, when the route has no owner path segment */
+    [CommandHeaders.OWNER_ID]?: string;
+    /** Space of the command, `Wow-Space-Id` */
+    [CommandHeaders.SPACE_ID]?: string;
+    /** Aggregate the command targets, when the route has no id path segment */
+    [CommandHeaders.AGGREGATE_ID]?: string;
+    /** The aggregate version the command expects, an integer */
+    [CommandHeaders.AGGREGATE_VERSION]?: `${number}`;
+    /** How long the server waits, in whole milliseconds */
+    [CommandHeaders.WAIT_TIME_OUT]?: `${number}`;
+    /** The stage to wait for; `PROCESSED` when absent */
+    [CommandHeaders.WAIT_STAGE]?: CommandStageName;
+    /** The bounded context the wait stage refers to */
+    [CommandHeaders.WAIT_CONTEXT]?: string;
+    /** The processor the wait stage refers to */
+    [CommandHeaders.WAIT_PROCESSOR]?: string;
+    /** The function the wait stage refers to */
+    [CommandHeaders.WAIT_FUNCTION]?: string;
+    /** The stage of the wait-chain tail; only with a `SAGA_HANDLED` wait stage */
+    [CommandHeaders.WAIT_TAIL_STAGE]?: CommandStageName;
+    /** The bounded context of the wait-chain tail */
+    [CommandHeaders.WAIT_TAIL_CONTEXT]?: string;
+    /** The processor of the wait-chain tail */
+    [CommandHeaders.WAIT_TAIL_PROCESSOR]?: string;
+    /** The function of the wait-chain tail */
+    [CommandHeaders.WAIT_TAIL_FUNCTION]?: string;
+    /** Idempotency key of the command */
+    [CommandHeaders.REQUEST_ID]?: string;
+    /** Whether the server may process the command locally */
+    [CommandHeaders.LOCAL_FIRST]?: 'true' | 'false';
+    /** Bounded context of the aggregate, for `/wow/command/send` */
+    [CommandHeaders.COMMAND_AGGREGATE_CONTEXT]?: string;
+    /** Name of the aggregate, for `/wow/command/send` */
+    [CommandHeaders.COMMAND_AGGREGATE_NAME]?: string;
+    /** Fully qualified command type, for `/wow/command/send` */
+    [CommandHeaders.COMMAND_TYPE]?: string;
+}
+/** Who a command is for; each option sets one command header. */
+export interface CommandHeaderOptions {
+    /** The tenant, `Command-Tenant-Id`; for a route without a tenant segment. */
+    tenantId?: string;
+    /** The owner, `Command-Owner-Id`; for a route without an owner segment. */
+    ownerId?: string;
+    /**
+     * The space, `Wow-Space-Id`; the tenant's default space when absent. Only a
+     * spaced aggregate reads it.
+     */
+    spaceId?: string;
+    /**
+     * The target aggregate, `Command-Aggregate-Id`; for a route without an id
+     * segment.
+     */
+    aggregateId?: string;
+    /** The aggregate version the command expects: a non-negative integer. */
+    aggregateVersion?: number;
+    /** Idempotency key; the server refuses a repeated one. */
+    requestId?: string;
+    /**
+     * Whether the server may process the command in its own process when it
+     * hosts the aggregate, `Command-Local-First`; it does unless this is `false`.
+     */
+    localFirst?: boolean;
+}
+/** The processing a wait stage refers to; blank means any. */
+export interface WaitFunction {
+    context?: string;
+    processor?: string;
+    function?: string;
+}
+/** Wait for one stage of the command. */
+export interface WaitStageOptions extends WaitFunction {
+    /** The stage to wait for. The server waits for `PROCESSED` when absent. */
+    stage?: CommandStageName;
+    /** How long the server waits, in whole milliseconds. */
+    timeoutMs?: number;
+    tail?: never;
+}
+/**
+ * Wait for a saga to handle the command's events, and then for the command
+ * that saga sends to reach `tail.stage` — Wow's wait chain.
+ */
+export interface WaitChainOptions extends WaitFunction {
+    stage: CommandStage.SAGA_HANDLED | 'SAGA_HANDLED';
+    tail: WaitFunction & {
+        stage: CommandStageName;
+    };
+    /** How long the server waits, in whole milliseconds. */
+    timeoutMs?: number;
+}
+/** What {@link waitStrategy} takes: one stage, or a wait chain. */
+export type WaitStrategyOptions = WaitStageOptions | WaitChainOptions;
+/**
+ * Builds the headers that say who a command is for. Options left out send
+ * no header.
+ *
+ * @throws TypeError when `aggregateVersion` is not a non-negative integer.
+ *
+ * @example
+ * ```typescript
+ * await commandClient.send({
+ *   path: 'owner/{ownerId}/cart/add_cart_item',
+ *   method: 'POST',
+ *   headers: commandHeaders({ spaceId: 'store-1', requestId: crypto.randomUUID() }),
+ *   body: { productId: 'p-1', quantity: 1 },
+ * });
+ * ```
+ */
+export declare function commandHeaders(options: CommandHeaderOptions): CommandRequestHeaders;
+/**
+ * Builds the headers that say how long, and for what, the server waits
+ * before it answers a command — Kotlin's `WaitingFor`. Options left out send
+ * no header, and the server's defaults apply: `PROCESSED` in the command's own
+ * bounded context.
+ *
+ * @throws TypeError when a stage is not a `CommandStage`, when `timeoutMs` is
+ *   not a positive integer, or when a `tail` is given with a stage other than
+ *   `SAGA_HANDLED` (the server ignores the tail then).
+ *
+ * @example
+ * ```typescript
+ * // Answer once the snapshot is written, or after five seconds.
+ * waitStrategy({ stage: CommandStage.SNAPSHOT, timeoutMs: 5_000 });
+ *
+ * // Answer once the saga's command has been processed.
+ * waitStrategy({
+ *   stage: 'SAGA_HANDLED',
+ *   processor: 'TransferSaga',
+ *   tail: { stage: 'PROCESSED', context: 'account' },
+ * });
+ * ```
+ */
+export declare function waitStrategy(options: WaitStrategyOptions): CommandRequestHeaders;
+/**
+ * The URL parameters of a {@link CommandRequest}: the values of the route's
+ * path variables. A command takes no query string.
+ */
+export interface CommandUrlParams extends Omit<UrlParams, 'path' | 'query'> {
+    /** The path variables, such as `{ ownerId, id }`. */
+    path?: UrlPathParams;
+}
+/**
+ * A command request: the path of the command route, its URL parameters, its
+ * typed headers and its body.
+ */
+export interface CommandRequest<C extends object = object> extends ParameterRequest<CommandBody<C>> {
+    urlParams?: CommandUrlParams;
+    headers?: CommandRequestHeaders;
+    /**
+     * The body of the command request.
+     */
+    body?: CommandBody<C>;
+}

package/dist/client/command/commandRequest.d.ts

@@ -0,0 +1,180 @@
+import { RequestHeaders, UrlParams } from '@ahoo-wang/fetcher';
+import { CommandHeaders } from './commandHeaders.js';
+import { UrlPathParams } from '../routing.js';
+import { ParameterRequest } from '@ahoo-wang/fetcher-decorator';
+import { CommandStage } from '../../model/index.js';
+import { CommandBody } from './types.js';
+/** A command stage, as the enum member or as its name. */
+export type CommandStageName = CommandStage | `${CommandStage}`;
+/**
+ * The headers of a command request.
+ *
+ * Every command header is optional and typed by what the server parses:
+ * a stage is a {@link CommandStage}, a version or a timeout is an integer,
+ * `Local-First` is a boolean. Any other header (`Authorization`, a
+ * `Command-Header-*` extension, …) is still allowed as a string. Build these
+ * with {@link commandHeaders} and {@link waitStrategy} rather than by hand.
+ *
+ * @example
+ * ```typescript
+ * const headers: CommandRequestHeaders = {
+ *   ...commandHeaders({ ownerId: 'user-1', requestId }),
+ *   ...waitStrategy({ stage: CommandStage.SNAPSHOT, timeoutMs: 10_000 }),
+ * };
+ * ```
+ */
+export interface CommandRequestHeaders extends RequestHeaders {
+    /** Tenant of the command, when the route has no tenant path segment */
+    [CommandHeaders.TENANT_ID]?: string;
+    /** Owner of the command, when the route has no owner path segment */
+    [CommandHeaders.OWNER_ID]?: string;
+    /** Space of the command, `Wow-Space-Id` */
+    [CommandHeaders.SPACE_ID]?: string;
+    /** Aggregate the command targets, when the route has no id path segment */
+    [CommandHeaders.AGGREGATE_ID]?: string;
+    /** The aggregate version the command expects, an integer */
+    [CommandHeaders.AGGREGATE_VERSION]?: `${number}`;
+    /** How long the server waits, in whole milliseconds */
+    [CommandHeaders.WAIT_TIME_OUT]?: `${number}`;
+    /** The stage to wait for; `PROCESSED` when absent */
+    [CommandHeaders.WAIT_STAGE]?: CommandStageName;
+    /** The bounded context the wait stage refers to */
+    [CommandHeaders.WAIT_CONTEXT]?: string;
+    /** The processor the wait stage refers to */
+    [CommandHeaders.WAIT_PROCESSOR]?: string;
+    /** The function the wait stage refers to */
+    [CommandHeaders.WAIT_FUNCTION]?: string;
+    /** The stage of the wait-chain tail; only with a `SAGA_HANDLED` wait stage */
+    [CommandHeaders.WAIT_TAIL_STAGE]?: CommandStageName;
+    /** The bounded context of the wait-chain tail */
+    [CommandHeaders.WAIT_TAIL_CONTEXT]?: string;
+    /** The processor of the wait-chain tail */
+    [CommandHeaders.WAIT_TAIL_PROCESSOR]?: string;
+    /** The function of the wait-chain tail */
+    [CommandHeaders.WAIT_TAIL_FUNCTION]?: string;
+    /** Idempotency key of the command */
+    [CommandHeaders.REQUEST_ID]?: string;
+    /** Whether the server may process the command locally */
+    [CommandHeaders.LOCAL_FIRST]?: 'true' | 'false';
+    /** Bounded context of the aggregate, for `/wow/command/send` */
+    [CommandHeaders.COMMAND_AGGREGATE_CONTEXT]?: string;
+    /** Name of the aggregate, for `/wow/command/send` */
+    [CommandHeaders.COMMAND_AGGREGATE_NAME]?: string;
+    /** Fully qualified command type, for `/wow/command/send` */
+    [CommandHeaders.COMMAND_TYPE]?: string;
+}
+/** Who a command is for; each option sets one command header. */
+export interface CommandHeaderOptions {
+    /** The tenant, `Command-Tenant-Id`; for a route without a tenant segment. */
+    tenantId?: string;
+    /** The owner, `Command-Owner-Id`; for a route without an owner segment. */
+    ownerId?: string;
+    /**
+     * The space, `Wow-Space-Id`; the tenant's default space when absent. Only a
+     * spaced aggregate reads it.
+     */
+    spaceId?: string;
+    /**
+     * The target aggregate, `Command-Aggregate-Id`; for a route without an id
+     * segment.
+     */
+    aggregateId?: string;
+    /** The aggregate version the command expects: a non-negative integer. */
+    aggregateVersion?: number;
+    /** Idempotency key; the server refuses a repeated one. */
+    requestId?: string;
+    /**
+     * Whether the server may process the command in its own process when it
+     * hosts the aggregate, `Command-Local-First`; it does unless this is `false`.
+     */
+    localFirst?: boolean;
+}
+/** The processing a wait stage refers to; blank means any. */
+export interface WaitFunction {
+    context?: string;
+    processor?: string;
+    function?: string;
+}
+/** Wait for one stage of the command. */
+export interface WaitStageOptions extends WaitFunction {
+    /** The stage to wait for. The server waits for `PROCESSED` when absent. */
+    stage?: CommandStageName;
+    /** How long the server waits, in whole milliseconds. */
+    timeoutMs?: number;
+    tail?: never;
+}
+/**
+ * Wait for a saga to handle the command's events, and then for the command
+ * that saga sends to reach `tail.stage` — Wow's wait chain.
+ */
+export interface WaitChainOptions extends WaitFunction {
+    stage: CommandStage.SAGA_HANDLED | 'SAGA_HANDLED';
+    tail: WaitFunction & {
+        stage: CommandStageName;
+    };
+    /** How long the server waits, in whole milliseconds. */
+    timeoutMs?: number;
+}
+/** What {@link waitStrategy} takes: one stage, or a wait chain. */
+export type WaitStrategyOptions = WaitStageOptions | WaitChainOptions;
+/**
+ * Builds the headers that say who a command is for. Options left out send
+ * no header.
+ *
+ * @throws TypeError when `aggregateVersion` is not a non-negative integer.
+ *
+ * @example
+ * ```typescript
+ * await commandClient.send({
+ *   path: 'owner/{ownerId}/cart/add_cart_item',
+ *   method: 'POST',
+ *   headers: commandHeaders({ spaceId: 'store-1', requestId: crypto.randomUUID() }),
+ *   body: { productId: 'p-1', quantity: 1 },
+ * });
+ * ```
+ */
+export declare function commandHeaders(options: CommandHeaderOptions): CommandRequestHeaders;
+/**
+ * Builds the headers that say how long, and for what, the server waits
+ * before it answers a command — Kotlin's `WaitingFor`. Options left out send
+ * no header, and the server's defaults apply: `PROCESSED` in the command's own
+ * bounded context.
+ *
+ * @throws TypeError when a stage is not a `CommandStage`, when `timeoutMs` is
+ *   not a positive integer, or when a `tail` is given with a stage other than
+ *   `SAGA_HANDLED` (the server ignores the tail then).
+ *
+ * @example
+ * ```typescript
+ * // Answer once the snapshot is written, or after five seconds.
+ * waitStrategy({ stage: CommandStage.SNAPSHOT, timeoutMs: 5_000 });
+ *
+ * // Answer once the saga's command has been processed.
+ * waitStrategy({
+ *   stage: 'SAGA_HANDLED',
+ *   processor: 'TransferSaga',
+ *   tail: { stage: 'PROCESSED', context: 'account' },
+ * });
+ * ```
+ */
+export declare function waitStrategy(options: WaitStrategyOptions): CommandRequestHeaders;
+/**
+ * The URL parameters of a {@link CommandRequest}: the values of the route's
+ * path variables. A command takes no query string.
+ */
+export interface CommandUrlParams extends Omit<UrlParams, 'path' | 'query'> {
+    /** The path variables, such as `{ ownerId, id }`. */
+    path?: UrlPathParams;
+}
+/**
+ * A command request: the path of the command route, its URL parameters, its
+ * typed headers and its body.
+ */
+export interface CommandRequest<C extends object = object> extends ParameterRequest<CommandBody<C>> {
+    urlParams?: CommandUrlParams;
+    headers?: CommandRequestHeaders;
+    /**
+     * The body of the command request.
+     */
+    body?: CommandBody<C>;
+}

package/dist/client/command/commandRequest.es.js

@@ -0,0 +1,31 @@
+import { CommandStage as e } from "../../model/command.es.js";
+import { CommandHeaders as t } from "./commandHeaders.es.js";
+//#region src/client/command/commandRequest.ts
+var n = new Set(Object.values(e));
+function r(e, t) {
+	if (!n.has(t)) throw TypeError(`${e} must be one of ${[...n].join(", ")}, got [${t}].`);
+	return t;
+}
+function i(e, t, n) {
+	if (!Number.isSafeInteger(t) || t < n) throw TypeError(`${e} must be an integer of at least ${n}, got [${t}].`);
+	return `${t}`;
+}
+function a(e, t, n) {
+	n !== void 0 && (e[t] = n);
+}
+function o(e) {
+	let n = {};
+	return a(n, t.TENANT_ID, e.tenantId), a(n, t.OWNER_ID, e.ownerId), a(n, t.SPACE_ID, e.spaceId), a(n, t.AGGREGATE_ID, e.aggregateId), e.aggregateVersion !== void 0 && (n[t.AGGREGATE_VERSION] = i("aggregateVersion", e.aggregateVersion, 0)), a(n, t.REQUEST_ID, e.requestId), e.localFirst !== void 0 && (n[t.LOCAL_FIRST] = e.localFirst ? "true" : "false"), n;
+}
+function s(n) {
+	let o = {};
+	if (n.stage !== void 0 && (o[t.WAIT_STAGE] = r("stage", n.stage)), a(o, t.WAIT_CONTEXT, n.context), a(o, t.WAIT_PROCESSOR, n.processor), a(o, t.WAIT_FUNCTION, n.function), n.tail !== void 0) {
+		if (n.stage !== e.SAGA_HANDLED) throw TypeError("A wait tail needs the SAGA_HANDLED stage.");
+		o[t.WAIT_TAIL_STAGE] = r("tail.stage", n.tail.stage), a(o, t.WAIT_TAIL_CONTEXT, n.tail.context), a(o, t.WAIT_TAIL_PROCESSOR, n.tail.processor), a(o, t.WAIT_TAIL_FUNCTION, n.tail.function);
+	}
+	return n.timeoutMs !== void 0 && (o[t.WAIT_TIME_OUT] = i("timeoutMs", n.timeoutMs, 1)), o;
+}
+//#endregion
+export { o as commandHeaders, s as waitStrategy };
+
+//# sourceMappingURL=commandRequest.es.js.map