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

package/dist/error/errorInfo.d.ts

@@ -0,0 +1,139 @@
+import { QueryErrorCode } from './queryErrorCodes.js';
+/**
+ * Enumerates the types of recoverability for errors or operations, allowing for classification and handling based on whether an error is transient and can be resolved by retrying.
+ *
+ * The [RecoverableType] enum provides a way to categorize errors into three distinct categories: [RECOVERABLE], [UNRECOVERABLE], and [UNKNOWN].
+ * This categorization is essential for implementing robust error handling and retry mechanisms in applications,
+ * ensuring that temporary issues are retried while permanent or unknown issues are handled appropriately.
+ *
+ */
+export declare enum RecoverableType {
+    /**
+     * Represents an error type that indicates the operation or error can be retried.
+     *
+     * This enum value is used to classify errors in a way that allows for the implementation of retry logic. When an error
+     * is marked as [RECOVERABLE], it signifies that the error condition is temporary and might be resolved upon retrying the
+     * operation. This is particularly useful in scenarios where network issues, transient server errors, or other temporary
+     * conditions may cause an operation to fail, but with a high likelihood of success on subsequent attempts.
+     */
+    RECOVERABLE = "RECOVERABLE",
+    /**
+     * Represents an unknown type of recoverability for an error or operation.
+     * This is used when the recoverability of an error cannot be determined or is not specified.
+     */
+    UNKNOWN = "UNKNOWN",
+    /**
+     * Represents an error type that indicates the operation or error cannot be retried.
+     *
+     * This enum value is used to classify errors in a way that signifies the error condition is permanent and retrying the operation will not resolve the issue. It is particularly
+     *  useful for handling errors where the underlying problem is fundamental and cannot be resolved by simply retrying, such as invalid input, resource exhaustion, or other non-transient
+     *  issues.
+     */
+    UNRECOVERABLE = "UNRECOVERABLE"
+}
+/**
+ * Represents an error that occurs during the binding process, typically when data is being mapped to or from an object.
+ * This class extends the [Named] interface, inheriting the `name` property which can be used to identify the source or context of the error.
+ *
+ * @param name The name or identifier for the context in which the error occurred.
+ * @param msg A message describing the error.
+ * @param code A stable, machine-readable code of the failed rule, when the server states one.
+ */
+export interface BindingError {
+    name: string;
+    msg: string;
+    /**
+     * A stable, machine-readable code of the rule that failed, when the server
+     * states one: a rejected query carries one of {@link QueryErrorCodes}.
+     * Absent otherwise, as for a command's validation errors.
+     */
+    code?: QueryErrorCode;
+}
+/**
+ * Represents the information about an error, including whether the operation succeeded, the error code, and any associated messages or binding errors.
+ *
+ * This interface is designed to provide a standardized way of handling and representing errors across different parts of an application. It includes methods to check if the operation was successful, retrieve the error code
+ * , and access any additional error details such as messages or binding errors.
+ */
+export interface ErrorInfo {
+    /**
+     * Represents the error code associated with an error. This value is used to identify the type of error that has occurred,
+     * which can be useful for debugging, logging, and handling errors in a standardized way.
+     */
+    errorCode: ErrorCode;
+    /**
+     * Represents the message associated with an error. This message provides a human-readable description of the error, which can be used for logging, debugging, or displaying to the user
+     * .
+     */
+    errorMsg: string;
+    /**
+     * Provides a list of [BindingError] instances that occurred during the binding process.
+     * Each [BindingError] contains information about the error, including its name and a message describing the issue.
+     * This property returns an empty list if no binding errors are present.
+     */
+    bindingErrors?: BindingError[];
+}
+/**
+ * The error codes Wow itself answers with, as `ErrorInfo.errorCode`, as the
+ * `Wow-Error-Code` response header, and as the event name of an error in a
+ * server-sent event stream.
+ *
+ * Mirrors `ErrorCodes` in `wow-core/src/main/kotlin/me/ahoo/wow/exception/ErrorCodes.kt`
+ * and the query schema and batch codes the server registers beside it.
+ * Applications add their own codes; {@link ErrorCode} admits those too.
+ */
+export declare const ErrorCodes: Readonly<{
+    /** The request succeeded. */
+    readonly SUCCEEDED: "Ok";
+    /** The requested resource does not exist (HTTP 404). */
+    readonly NOT_FOUND: "NotFound";
+    /** The request is malformed (HTTP 400). */
+    readonly BAD_REQUEST: "BadRequest";
+    /** An argument is invalid (HTTP 400). */
+    readonly ILLEGAL_ARGUMENT: "IllegalArgument";
+    /** The aggregate is in a state that refuses the command (HTTP 400). */
+    readonly ILLEGAL_STATE: "IllegalState";
+    /** The wait timed out (HTTP 408). */
+    readonly REQUEST_TIMEOUT: "RequestTimeout";
+    /** The server is rate limiting (HTTP 429). */
+    readonly TOO_MANY_REQUESTS: "TooManyRequests";
+    /** The command's request id was used before (HTTP 400). */
+    readonly DUPLICATE_REQUEST_ID: "DuplicateRequestId";
+    /** The command failed validation (HTTP 400); see `bindingErrors`. */
+    readonly COMMAND_VALIDATION: "CommandValidation";
+    /** A command rewriter produced no command. */
+    readonly REWRITE_NO_COMMAND: "RewriteNoCommand";
+    /** Another command changed the aggregate first (HTTP 409). */
+    readonly EVENT_VERSION_CONFLICT: "EventVersionConflict";
+    /** The aggregate id already exists (HTTP 400). */
+    readonly DUPLICATE_AGGREGATE_ID: "DuplicateAggregateId";
+    /** The aggregate is not at the version the command expected (HTTP 409). */
+    readonly COMMAND_EXPECT_VERSION_CONFLICT: "CommandExpectVersionConflict";
+    /** The event stream is not at the version sourcing expected (HTTP 409). */
+    readonly SOURCING_VERSION_CONFLICT: "SourcingVersionConflict";
+    /** The aggregate is deleted (HTTP 410). */
+    readonly ILLEGAL_ACCESS_DELETED_AGGREGATE: "IllegalAccessDeletedAggregate";
+    /** The aggregate belongs to another owner (HTTP 403). */
+    readonly ILLEGAL_ACCESS_OWNER_AGGREGATE: "IllegalAccessOwnerAggregate";
+    /** The aggregate belongs to another space. */
+    readonly ILLEGAL_ACCESS_SPACE_AGGREGATE: "IllegalAccessSpaceAggregate";
+    /** A query lacks the authenticated tenant scope the server requires (HTTP 403). */
+    readonly ILLEGAL_ACCESS_QUERY_SCOPE: "IllegalAccessQueryScope";
+    /** An unexpected server failure (HTTP 500). */
+    readonly INTERNAL_SERVER_ERROR: "InternalServerError";
+    /** A query does not fit the aggregate's query schema (HTTP 400). */
+    readonly QUERY_SCHEMA_VALIDATION: "QuerySchemaValidation";
+    /** The query schema conflicts with the stored one (HTTP 500). */
+    readonly QUERY_SCHEMA_CONFLICT: "QuerySchemaConflict";
+    /** The query schema is not available yet (HTTP 503). */
+    readonly QUERY_SCHEMA_UNAVAILABLE: "QuerySchemaUnavailable";
+    /** A batch task failed. */
+    readonly BATCH_TASK_ERROR: "BatchTaskError";
+}>;
+/** One of the error codes Wow itself defines; see {@link ErrorCodes}. */
+export type WowErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+ * An error code: one of Wow's own, which editors complete, or any other an
+ * application defines.
+ */
+export type ErrorCode = WowErrorCode | (string & {});

package/dist/error/errorInfo.es.js

@@ -0,0 +1,32 @@
+//#region src/error/errorInfo.ts
+var e = /* @__PURE__ */ function(e) {
+	return e.RECOVERABLE = "RECOVERABLE", e.UNKNOWN = "UNKNOWN", e.UNRECOVERABLE = "UNRECOVERABLE", e;
+}({}), t = Object.freeze({
+	SUCCEEDED: "Ok",
+	NOT_FOUND: "NotFound",
+	BAD_REQUEST: "BadRequest",
+	ILLEGAL_ARGUMENT: "IllegalArgument",
+	ILLEGAL_STATE: "IllegalState",
+	REQUEST_TIMEOUT: "RequestTimeout",
+	TOO_MANY_REQUESTS: "TooManyRequests",
+	DUPLICATE_REQUEST_ID: "DuplicateRequestId",
+	COMMAND_VALIDATION: "CommandValidation",
+	REWRITE_NO_COMMAND: "RewriteNoCommand",
+	EVENT_VERSION_CONFLICT: "EventVersionConflict",
+	DUPLICATE_AGGREGATE_ID: "DuplicateAggregateId",
+	COMMAND_EXPECT_VERSION_CONFLICT: "CommandExpectVersionConflict",
+	SOURCING_VERSION_CONFLICT: "SourcingVersionConflict",
+	ILLEGAL_ACCESS_DELETED_AGGREGATE: "IllegalAccessDeletedAggregate",
+	ILLEGAL_ACCESS_OWNER_AGGREGATE: "IllegalAccessOwnerAggregate",
+	ILLEGAL_ACCESS_SPACE_AGGREGATE: "IllegalAccessSpaceAggregate",
+	ILLEGAL_ACCESS_QUERY_SCOPE: "IllegalAccessQueryScope",
+	INTERNAL_SERVER_ERROR: "InternalServerError",
+	QUERY_SCHEMA_VALIDATION: "QuerySchemaValidation",
+	QUERY_SCHEMA_CONFLICT: "QuerySchemaConflict",
+	QUERY_SCHEMA_UNAVAILABLE: "QuerySchemaUnavailable",
+	BATCH_TASK_ERROR: "BatchTaskError"
+});
+//#endregion
+export { t as ErrorCodes, e as RecoverableType };
+
+//# sourceMappingURL=errorInfo.es.js.map

package/dist/error/errorInfo.es.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorInfo.es.js","names":["RecoverableType","\"RECOVERABLE\"","\"UNKNOWN\"","\"UNRECOVERABLE\"","ErrorCodes"],"sources":["../../src/error/errorInfo.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 { QueryErrorCode } from './queryErrorCodes.js';\n\n/**\n * Enumerates the types of recoverability for errors or operations, allowing for classification and handling based on whether an error is transient and can be resolved by retrying.\n *\n * The [RecoverableType] enum provides a way to categorize errors into three distinct categories: [RECOVERABLE], [UNRECOVERABLE], and [UNKNOWN].\n * This categorization is essential for implementing robust error handling and retry mechanisms in applications,\n * ensuring that temporary issues are retried while permanent or unknown issues are handled appropriately.\n *\n */\nexport enum RecoverableType {\n  /**\n   * Represents an error type that indicates the operation or error can be retried.\n   *\n   * This enum value is used to classify errors in a way that allows for the implementation of retry logic. When an error\n   * is marked as [RECOVERABLE], it signifies that the error condition is temporary and might be resolved upon retrying the\n   * operation. This is particularly useful in scenarios where network issues, transient server errors, or other temporary\n   * conditions may cause an operation to fail, but with a high likelihood of success on subsequent attempts.\n   */\n  RECOVERABLE = 'RECOVERABLE',\n  /**\n   * Represents an unknown type of recoverability for an error or operation.\n   * This is used when the recoverability of an error cannot be determined or is not specified.\n   */\n  UNKNOWN = 'UNKNOWN',\n\n  /**\n   * Represents an error type that indicates the operation or error cannot be retried.\n   *\n   * This enum value is used to classify errors in a way that signifies the error condition is permanent and retrying the operation will not resolve the issue. It is particularly\n   *  useful for handling errors where the underlying problem is fundamental and cannot be resolved by simply retrying, such as invalid input, resource exhaustion, or other non-transient\n   *  issues.\n   */\n  UNRECOVERABLE = 'UNRECOVERABLE',\n}\n\n/**\n * Represents an error that occurs during the binding process, typically when data is being mapped to or from an object.\n * This class extends the [Named] interface, inheriting the `name` property which can be used to identify the source or context of the error.\n *\n * @param name The name or identifier for the context in which the error occurred.\n * @param msg A message describing the error.\n * @param code A stable, machine-readable code of the failed rule, when the server states one.\n */\nexport interface BindingError {\n  name: string;\n  msg: string;\n  /**\n   * A stable, machine-readable code of the rule that failed, when the server\n   * states one: a rejected query carries one of {@link QueryErrorCodes}.\n   * Absent otherwise, as for a command's validation errors.\n   */\n  code?: QueryErrorCode;\n}\n\n/**\n * Represents the information about an error, including whether the operation succeeded, the error code, and any associated messages or binding errors.\n *\n * This interface is designed to provide a standardized way of handling and representing errors across different parts of an application. It includes methods to check if the operation was successful, retrieve the error code\n * , and access any additional error details such as messages or binding errors.\n */\nexport interface ErrorInfo {\n  /**\n   * Represents the error code associated with an error. This value is used to identify the type of error that has occurred,\n   * which can be useful for debugging, logging, and handling errors in a standardized way.\n   */\n  errorCode: ErrorCode;\n  /**\n   * Represents the message associated with an error. This message provides a human-readable description of the error, which can be used for logging, debugging, or displaying to the user\n   * .\n   */\n  errorMsg: string;\n  /**\n   * Provides a list of [BindingError] instances that occurred during the binding process.\n   * Each [BindingError] contains information about the error, including its name and a message describing the issue.\n   * This property returns an empty list if no binding errors are present.\n   */\n  bindingErrors?: BindingError[];\n}\n\n/**\n * The error codes Wow itself answers with, as `ErrorInfo.errorCode`, as the\n * `Wow-Error-Code` response header, and as the event name of an error in a\n * server-sent event stream.\n *\n * Mirrors `ErrorCodes` in `wow-core/src/main/kotlin/me/ahoo/wow/exception/ErrorCodes.kt`\n * and the query schema and batch codes the server registers beside it.\n * Applications add their own codes; {@link ErrorCode} admits those too.\n */\nexport const ErrorCodes = Object.freeze({\n  /** The request succeeded. */\n  SUCCEEDED: 'Ok',\n  /** The requested resource does not exist (HTTP 404). */\n  NOT_FOUND: 'NotFound',\n  /** The request is malformed (HTTP 400). */\n  BAD_REQUEST: 'BadRequest',\n  /** An argument is invalid (HTTP 400). */\n  ILLEGAL_ARGUMENT: 'IllegalArgument',\n  /** The aggregate is in a state that refuses the command (HTTP 400). */\n  ILLEGAL_STATE: 'IllegalState',\n  /** The wait timed out (HTTP 408). */\n  REQUEST_TIMEOUT: 'RequestTimeout',\n  /** The server is rate limiting (HTTP 429). */\n  TOO_MANY_REQUESTS: 'TooManyRequests',\n  /** The command's request id was used before (HTTP 400). */\n  DUPLICATE_REQUEST_ID: 'DuplicateRequestId',\n  /** The command failed validation (HTTP 400); see `bindingErrors`. */\n  COMMAND_VALIDATION: 'CommandValidation',\n  /** A command rewriter produced no command. */\n  REWRITE_NO_COMMAND: 'RewriteNoCommand',\n  /** Another command changed the aggregate first (HTTP 409). */\n  EVENT_VERSION_CONFLICT: 'EventVersionConflict',\n  /** The aggregate id already exists (HTTP 400). */\n  DUPLICATE_AGGREGATE_ID: 'DuplicateAggregateId',\n  /** The aggregate is not at the version the command expected (HTTP 409). */\n  COMMAND_EXPECT_VERSION_CONFLICT: 'CommandExpectVersionConflict',\n  /** The event stream is not at the version sourcing expected (HTTP 409). */\n  SOURCING_VERSION_CONFLICT: 'SourcingVersionConflict',\n  /** The aggregate is deleted (HTTP 410). */\n  ILLEGAL_ACCESS_DELETED_AGGREGATE: 'IllegalAccessDeletedAggregate',\n  /** The aggregate belongs to another owner (HTTP 403). */\n  ILLEGAL_ACCESS_OWNER_AGGREGATE: 'IllegalAccessOwnerAggregate',\n  /** The aggregate belongs to another space. */\n  ILLEGAL_ACCESS_SPACE_AGGREGATE: 'IllegalAccessSpaceAggregate',\n  /** A query lacks the authenticated tenant scope the server requires (HTTP 403). */\n  ILLEGAL_ACCESS_QUERY_SCOPE: 'IllegalAccessQueryScope',\n  /** An unexpected server failure (HTTP 500). */\n  INTERNAL_SERVER_ERROR: 'InternalServerError',\n  /** A query does not fit the aggregate's query schema (HTTP 400). */\n  QUERY_SCHEMA_VALIDATION: 'QuerySchemaValidation',\n  /** The query schema conflicts with the stored one (HTTP 500). */\n  QUERY_SCHEMA_CONFLICT: 'QuerySchemaConflict',\n  /** The query schema is not available yet (HTTP 503). */\n  QUERY_SCHEMA_UNAVAILABLE: 'QuerySchemaUnavailable',\n  /** A batch task failed. */\n  BATCH_TASK_ERROR: 'BatchTaskError',\n} as const);\n\n/** One of the error codes Wow itself defines; see {@link ErrorCodes}. */\nexport type WowErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];\n\n/**\n * An error code: one of Wow's own, which editors complete, or any other an\n * application defines.\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type\nexport type ErrorCode = WowErrorCode | (string & {});\n"],"mappings":";AAuBA,IAAYA,IAAL,yBAAA,GAAA;QASL,EAAAC,cAAA,eAKA,EAAAC,UAAA,WASA,EAAAC,gBAAA;AACF,EAAA,CAAA,CAAA,GAuDaC,IAAa,OAAO,OAAO;CAEtC,WAAW;CAEX,WAAW;CAEX,aAAa;CAEb,kBAAkB;CAElB,eAAe;CAEf,iBAAiB;CAEjB,mBAAmB;CAEnB,sBAAsB;CAEtB,oBAAoB;CAEpB,oBAAoB;CAEpB,wBAAwB;CAExB,wBAAwB;CAExB,iCAAiC;CAEjC,2BAA2B;CAE3B,kCAAkC;CAElC,gCAAgC;CAEhC,gCAAgC;CAEhC,4BAA4B;CAE5B,uBAAuB;CAEvB,yBAAyB;CAEzB,uBAAuB;CAEvB,0BAA0B;CAE1B,kBAAkB;AACpB,CAAU"}

package/dist/error/headers.cjs

@@ -0,0 +1,2 @@
+var e=Object.freeze({WOW_HEADERS_PREFIX:`Wow-`,SPACE_ID:`Wow-Space-Id`,ERROR_CODE:`Wow-Error-Code`});exports.WowHeaders=e;
+//# sourceMappingURL=headers.cjs.map

package/dist/error/headers.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.cjs","names":["WowHeaders"],"sources":["../../src/error/headers.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\n/**\n * HTTP headers the Wow server shares across commands and queries.\n *\n * Mirrors `CommonComponent.Header` in\n * `wow-openapi/src/main/kotlin/me/ahoo/wow/openapi/CommonComponent.kt`.\n * These headers carry the `Wow-` prefix, not the `Command-` prefix of\n * {@link CommandHeaders}. Each value is a string literal type, so a header\n * object keyed by it is checked like one keyed by the literal.\n *\n * @example\n * ```typescript\n * // Send a command into a space\n * await commandClient.send({\n *   method: HttpMethod.POST,\n *   headers: { [WowHeaders.SPACE_ID]: 'store-1' },\n *   body: { ... },\n * });\n * ```\n */\nexport const WowHeaders = Object.freeze({\n  /**\n   * Prefix of the headers shared across commands and queries\n   */\n  WOW_HEADERS_PREFIX: 'Wow-',\n\n  /**\n   * Space identifier request header.\n   *\n   * On a command route it sets the command's space; on a query route it adds\n   * a space filter. It is routing data, not proof that the caller may use\n   * that space. The server ignores a blank value.\n   */\n  SPACE_ID: 'Wow-Space-Id',\n\n  /**\n   * Error code response header, `Ok` when the request succeeded. A failed\n   * request carries the `errorCode` of its `ErrorInfo` body here too.\n   */\n  ERROR_CODE: 'Wow-Error-Code',\n} as const);\n"],"mappings":"AAgCA,IAAaA,EAAa,OAAO,OAAO,CAItC,mBAAoB,OASpB,SAAU,eAMV,WAAY,gBACd,CAAU"}

package/dist/error/headers.d.cts

@@ -0,0 +1,38 @@
+/**
+ * HTTP headers the Wow server shares across commands and queries.
+ *
+ * Mirrors `CommonComponent.Header` in
+ * `wow-openapi/src/main/kotlin/me/ahoo/wow/openapi/CommonComponent.kt`.
+ * These headers carry the `Wow-` prefix, not the `Command-` prefix of
+ * {@link CommandHeaders}. Each value is a string literal type, so a header
+ * object keyed by it is checked like one keyed by the literal.
+ *
+ * @example
+ * ```typescript
+ * // Send a command into a space
+ * await commandClient.send({
+ *   method: HttpMethod.POST,
+ *   headers: { [WowHeaders.SPACE_ID]: 'store-1' },
+ *   body: { ... },
+ * });
+ * ```
+ */
+export declare const WowHeaders: Readonly<{
+    /**
+     * Prefix of the headers shared across commands and queries
+     */
+    readonly WOW_HEADERS_PREFIX: "Wow-";
+    /**
+     * Space identifier request header.
+     *
+     * On a command route it sets the command's space; on a query route it adds
+     * a space filter. It is routing data, not proof that the caller may use
+     * that space. The server ignores a blank value.
+     */
+    readonly SPACE_ID: "Wow-Space-Id";
+    /**
+     * Error code response header, `Ok` when the request succeeded. A failed
+     * request carries the `errorCode` of its `ErrorInfo` body here too.
+     */
+    readonly ERROR_CODE: "Wow-Error-Code";
+}>;

package/dist/error/headers.d.ts

@@ -0,0 +1,38 @@
+/**
+ * HTTP headers the Wow server shares across commands and queries.
+ *
+ * Mirrors `CommonComponent.Header` in
+ * `wow-openapi/src/main/kotlin/me/ahoo/wow/openapi/CommonComponent.kt`.
+ * These headers carry the `Wow-` prefix, not the `Command-` prefix of
+ * {@link CommandHeaders}. Each value is a string literal type, so a header
+ * object keyed by it is checked like one keyed by the literal.
+ *
+ * @example
+ * ```typescript
+ * // Send a command into a space
+ * await commandClient.send({
+ *   method: HttpMethod.POST,
+ *   headers: { [WowHeaders.SPACE_ID]: 'store-1' },
+ *   body: { ... },
+ * });
+ * ```
+ */
+export declare const WowHeaders: Readonly<{
+    /**
+     * Prefix of the headers shared across commands and queries
+     */
+    readonly WOW_HEADERS_PREFIX: "Wow-";
+    /**
+     * Space identifier request header.
+     *
+     * On a command route it sets the command's space; on a query route it adds
+     * a space filter. It is routing data, not proof that the caller may use
+     * that space. The server ignores a blank value.
+     */
+    readonly SPACE_ID: "Wow-Space-Id";
+    /**
+     * Error code response header, `Ok` when the request succeeded. A failed
+     * request carries the `errorCode` of its `ErrorInfo` body here too.
+     */
+    readonly ERROR_CODE: "Wow-Error-Code";
+}>;

package/dist/error/headers.es.js

@@ -0,0 +1,10 @@
+//#region src/error/headers.ts
+var e = Object.freeze({
+	WOW_HEADERS_PREFIX: "Wow-",
+	SPACE_ID: "Wow-Space-Id",
+	ERROR_CODE: "Wow-Error-Code"
+});
+//#endregion
+export { e as WowHeaders };
+
+//# sourceMappingURL=headers.es.js.map

package/dist/error/headers.es.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.es.js","names":["WowHeaders"],"sources":["../../src/error/headers.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\n/**\n * HTTP headers the Wow server shares across commands and queries.\n *\n * Mirrors `CommonComponent.Header` in\n * `wow-openapi/src/main/kotlin/me/ahoo/wow/openapi/CommonComponent.kt`.\n * These headers carry the `Wow-` prefix, not the `Command-` prefix of\n * {@link CommandHeaders}. Each value is a string literal type, so a header\n * object keyed by it is checked like one keyed by the literal.\n *\n * @example\n * ```typescript\n * // Send a command into a space\n * await commandClient.send({\n *   method: HttpMethod.POST,\n *   headers: { [WowHeaders.SPACE_ID]: 'store-1' },\n *   body: { ... },\n * });\n * ```\n */\nexport const WowHeaders = Object.freeze({\n  /**\n   * Prefix of the headers shared across commands and queries\n   */\n  WOW_HEADERS_PREFIX: 'Wow-',\n\n  /**\n   * Space identifier request header.\n   *\n   * On a command route it sets the command's space; on a query route it adds\n   * a space filter. It is routing data, not proof that the caller may use\n   * that space. The server ignores a blank value.\n   */\n  SPACE_ID: 'Wow-Space-Id',\n\n  /**\n   * Error code response header, `Ok` when the request succeeded. A failed\n   * request carries the `errorCode` of its `ErrorInfo` body here too.\n   */\n  ERROR_CODE: 'Wow-Error-Code',\n} as const);\n"],"mappings":";AAgCA,IAAaA,IAAa,OAAO,OAAO;CAItC,oBAAoB;CASpB,UAAU;CAMV,YAAY;AACd,CAAU"}

package/dist/error/index.d.cts

@@ -0,0 +1,21 @@
+/**
+ * The one shape a Wow server's error takes in an application: `WowError`,
+ * carrying the server's `ErrorInfo` (`errorCode`, `errorMsg`,
+ * `bindingErrors`) and the HTTP status.
+ *
+ * It arrives two ways, which meet in `toWowError`:
+ * - a server-sent event stream errors with a `WowError` itself when the
+ *   server sends an error event midway (the extractors of `transport/`);
+ * - any other failed request rejects with the fetcher's `ExchangeError`,
+ *   because the fetcher validates the status before a result extractor runs;
+ *   `toWowError(error)` reads the `ErrorInfo` body, or the `Wow-Error-Code`
+ *   header, from a clone of its response.
+ *
+ * `toWowError` accepts both, so an application handles every server error
+ * after one `await toWowError(error)`. Nothing here imports a fetcher
+ * package: `toWowError` reads the fetcher error by its shape.
+ */
+export * from './errorInfo.cjs';
+export * from './queryErrorCodes.cjs';
+export * from './wowError.cjs';
+export * from './headers.cjs';

package/dist/error/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The one shape a Wow server's error takes in an application: `WowError`,
+ * carrying the server's `ErrorInfo` (`errorCode`, `errorMsg`,
+ * `bindingErrors`) and the HTTP status.
+ *
+ * It arrives two ways, which meet in `toWowError`:
+ * - a server-sent event stream errors with a `WowError` itself when the
+ *   server sends an error event midway (the extractors of `transport/`);
+ * - any other failed request rejects with the fetcher's `ExchangeError`,
+ *   because the fetcher validates the status before a result extractor runs;
+ *   `toWowError(error)` reads the `ErrorInfo` body, or the `Wow-Error-Code`
+ *   header, from a clone of its response.
+ *
+ * `toWowError` accepts both, so an application handles every server error
+ * after one `await toWowError(error)`. Nothing here imports a fetcher
+ * package: `toWowError` reads the fetcher error by its shape.
+ */
+export * from './errorInfo.js';
+export * from './queryErrorCodes.js';
+export * from './wowError.js';
+export * from './headers.js';

package/dist/error/queryErrorCodes.cjs

@@ -0,0 +1,2 @@
+var e=Object.freeze({INVALID_JSON:`INVALID_JSON`,BODY_NOT_OBJECT:`BODY_NOT_OBJECT`,EMPTY_BODY:`EMPTY_BODY`,UNKNOWN_PROPERTY:`UNKNOWN_PROPERTY`,UNKNOWN_TYPE:`UNKNOWN_TYPE`,UNKNOWN_VALUE:`UNKNOWN_VALUE`,INVALID_VALUE:`INVALID_VALUE`,INVALID_REQUEST:`INVALID_REQUEST`,CURSOR_SORT_DUPLICATE:`CURSOR_SORT_DUPLICATE`,CURSOR_SORT_TOO_MANY:`CURSOR_SORT_TOO_MANY`,INVALID_CURSOR:`INVALID_CURSOR`,SIZE_OUT_OF_RANGE:`SIZE_OUT_OF_RANGE`,FILTER_TOO_LARGE:`FILTER_TOO_LARGE`,EXPENSIVE_OPERATOR_DISABLED:`EXPENSIVE_OPERATOR_DISABLED`,COUNT_REQUIRES_FILTER:`COUNT_REQUIRES_FILTER`,RESIDUAL_GROUPS_EXCEEDED:`RESIDUAL_GROUPS_EXCEEDED`,EXPLICIT_ENTRY_REQUIRED:`EXPLICIT_ENTRY_REQUIRED`,UNKNOWN_FIELD:`UNKNOWN_FIELD`,UNSUPPORTED_CAPABILITY:`UNSUPPORTED_CAPABILITY`,ELEMENT_SCOPE_REQUIRED:`ELEMENT_SCOPE_REQUIRED`,VALUE_MISMATCH:`VALUE_MISMATCH`,NOT_COLLECTION:`NOT_COLLECTION`,NOT_SINGLE_STRING:`NOT_SINGLE_STRING`,MODEL_SEARCH_UNSUPPORTED:`MODEL_SEARCH_UNSUPPORTED`,CURSOR_NOT_ALLOWED:`CURSOR_NOT_ALLOWED`,PROTECTED_AGGREGATION:`PROTECTED_AGGREGATION`,PROTECTED_COMPARISON:`PROTECTED_COMPARISON`,MISSING_KEY_REQUIRES_STRING:`MISSING_KEY_REQUIRES_STRING`,ANY_REQUIRES_SINGLE_VALUE:`ANY_REQUIRES_SINGLE_VALUE`,INCOMPLETE_PROJECTION:`INCOMPLETE_PROJECTION`,METRIC_FILTER_SEARCH:`METRIC_FILTER_SEARCH`,METRIC_FILTER_ELEMENT_MATCH:`METRIC_FILTER_ELEMENT_MATCH`,METRIC_FILTER_ARRAY_FIELD:`METRIC_FILTER_ARRAY_FIELD`,NOT_PROJECTABLE:`NOT_PROJECTABLE`,EVENT_PROJECTION_TYPE_REQUIRED:`EVENT_PROJECTION_TYPE_REQUIRED`,TEMPORAL_REPRESENTATION_REQUIRED:`TEMPORAL_REPRESENTATION_REQUIRED`,TEMPORAL_CONFIGURATION_CONFLICT:`TEMPORAL_CONFIGURATION_CONFLICT`,PARALLEL_ARRAY_SORT:`PARALLEL_ARRAY_SORT`,ARRAY_EQUALITY:`ARRAY_EQUALITY`,FIRST_LAST_REQUIRES_SINGLE_VALUE:`FIRST_LAST_REQUIRES_SINGLE_VALUE`,FIRST_LAST_REQUIRES_ORDER_BY:`FIRST_LAST_REQUIRES_ORDER_BY`,TEMPORAL_AGGREGATION_UNSUPPORTED:`TEMPORAL_AGGREGATION_UNSUPPORTED`,SORT_TOO_MANY:`SORT_TOO_MANY`,SORT_FIELD_DUPLICATE:`SORT_FIELD_DUPLICATE`,IDENTITY_UNDEFINED:`IDENTITY_UNDEFINED`,STORAGE_UNSUPPORTED:`STORAGE_UNSUPPORTED`});exports.QueryErrorCodes=e;
+//# sourceMappingURL=queryErrorCodes.cjs.map

package/dist/error/queryErrorCodes.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryErrorCodes.cjs","names":["QueryErrorCodes"],"sources":["../../src/error/queryErrorCodes.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\n/**\n * The codes a rejected query carries as `BindingError.code`: which rule the\n * request broke, stable where the human text (`errorMsg`) is not.\n *\n * Mirrors `QueryErrorCodes` in\n * `wow-api/src/main/kotlin/me/ahoo/wow/api/query/QueryErrorCodes.kt`, which the\n * server also publishes as the `BindingError.code` enum of its OpenAPI\n * document. The list is open: Wow adds codes and never renames or reuses one,\n * so a client treats a code it does not know as a generic rejection and shows\n * `errorMsg`. {@link QueryErrorCode} admits those codes too.\n *\n * Three groups, which `BindingError.name` locates differently:\n * - decoding the request body (`errorCode` `IllegalArgument`): `name` is the\n *   JSON path of the offending value, such as `filter.state` or `metrics[0]`,\n *   or `body` for the body as a whole;\n * - the entry's budget and gates (`errorCode` `IllegalArgument`): `name` is\n *   the part of the request the rule bounds, such as `limit` or `filter`;\n * - admission against the query model (`errorCode` `QuerySchemaValidation`):\n *   `name` is the absolute logical field path, such as `state.items.sku`, or\n *   `''` when the rule is about the model rather than one field.\n *\n * Budget and gate rejections carry a code from Wow 9.2 on; an older server\n * answers them with text alone (`HTTP list query limit[...] must be …`). A\n * failure of the server itself is no rejection: it answers HTTP 500\n * `InternalServerError` without a binding error.\n */\nexport const QueryErrorCodes = Object.freeze({\n  /** The body is not valid JSON. */\n  INVALID_JSON: 'INVALID_JSON',\n  /** The body is JSON but not an object. */\n  BODY_NOT_OBJECT: 'BODY_NOT_OBJECT',\n  /** The body is empty. */\n  EMPTY_BODY: 'EMPTY_BODY',\n  /** The body has a property the query type does not declare. */\n  UNKNOWN_PROPERTY: 'UNKNOWN_PROPERTY',\n  /** An `op`, metric or other type discriminator names no known type. */\n  UNKNOWN_TYPE: 'UNKNOWN_TYPE',\n  /** An enum value is not one the server knows. */\n  UNKNOWN_VALUE: 'UNKNOWN_VALUE',\n  /** A value is missing or has the wrong JSON type. */\n  INVALID_VALUE: 'INVALID_VALUE',\n  /** Any other request rule; the message names it. */\n  INVALID_REQUEST: 'INVALID_REQUEST',\n  /** A cursor sort names a field twice; `path` is the repeated field. */\n  CURSOR_SORT_DUPLICATE: 'CURSOR_SORT_DUPLICATE',\n  /** A cursor sort has too many fields once the identity tie-breaker is appended. */\n  CURSOR_SORT_TOO_MANY: 'CURSOR_SORT_TOO_MANY',\n  /**\n   * The cursor token was not issued for this model and effective sort, or\n   * does not decode; `path` is `cursor`. Start again from the first page.\n   */\n  INVALID_CURSOR: 'INVALID_CURSOR',\n  /**\n   * The entry's budget: a list or aggregation `limit`, a page's index, size,\n   * window or offset, or a cursor page's `size` is out of range; `path` names\n   * which (`limit`, `pagination.size`, `size`, …).\n   */\n  SIZE_OUT_OF_RANGE: 'SIZE_OUT_OF_RANGE',\n  /**\n   * The entry's budget: the filter or `having` has too many nodes or values;\n   * `path` is `filter` or `having`.\n   */\n  FILTER_TOO_LARGE: 'FILTER_TOO_LARGE',\n  /**\n   * The entry does not allow expensive operators, and the query uses one: an\n   * operator, an element expansion, a metric sort, an arithmetic or\n   * expression group, a date part, a dense fill or FIRST / LAST; `path` names\n   * the part (`filter`, `elements`, `sort`, `metrics`, `groupBy`).\n   */\n  EXPENSIVE_OPERATOR_DISABLED: 'EXPENSIVE_OPERATOR_DISABLED',\n  /**\n   * A counting query (count, or a paged query's total) would match every\n   * record, which the entry refuses; `path` is `filter`.\n   */\n  COUNT_REQUIRES_FILTER: 'COUNT_REQUIRES_FILTER',\n  /**\n   * A `having` or metric sort the storage evaluates after grouping read more\n   * groups than the server allows; `path` is `body`. It may end a stream\n   * partway through.\n   */\n  RESIDUAL_GROUPS_EXCEEDED: 'RESIDUAL_GROUPS_EXCEEDED',\n  /**\n   * An in-process query named no entry where one is required. Never\n   * answered over HTTP; listed so the mirror stays complete.\n   */\n  EXPLICIT_ENTRY_REQUIRED: 'EXPLICIT_ENTRY_REQUIRED',\n  /** The model has no such logical field. */\n  UNKNOWN_FIELD: 'UNKNOWN_FIELD',\n  /** The field does not offer the capability the query uses (sort, range, …). */\n  UNSUPPORTED_CAPABILITY: 'UNSUPPORTED_CAPABILITY',\n  /** The field is an element field and must be queried inside its element scope. */\n  ELEMENT_SCOPE_REQUIRED: 'ELEMENT_SCOPE_REQUIRED',\n  /** A filter value falls outside the field's declared domain. */\n  VALUE_MISMATCH: 'VALUE_MISMATCH',\n  /** The field is not a known collection (for example under `isEmpty`). */\n  NOT_COLLECTION: 'NOT_COLLECTION',\n  /** The field is not a single string. */\n  NOT_SINGLE_STRING: 'NOT_SINGLE_STRING',\n  /** The model does not support search. */\n  MODEL_SEARCH_UNSUPPORTED: 'MODEL_SEARCH_UNSUPPORTED',\n  /** The field cannot be used for a cursor. */\n  CURSOR_NOT_ALLOWED: 'CURSOR_NOT_ALLOWED',\n  /** The field is protected and cannot be aggregated. */\n  PROTECTED_AGGREGATION: 'PROTECTED_AGGREGATION',\n  /**\n   * The field is protected and cannot be filtered or sorted: its descriptor\n   * says `sensitivity.comparable: false`. A search that names it is refused\n   * the same way.\n   */\n  PROTECTED_COMPARISON: 'PROTECTED_COMPARISON',\n  /** A terms group's `missingKey` needs a single-valued string field. */\n  MISSING_KEY_REQUIRES_STRING: 'MISSING_KEY_REQUIRES_STRING',\n  /** `ANY` needs a single value. */\n  ANY_REQUIRES_SINGLE_VALUE: 'ANY_REQUIRES_SINGLE_VALUE',\n  /** The storage cannot deliver a complete projection; select fields explicitly. */\n  INCOMPLETE_PROJECTION: 'INCOMPLETE_PROJECTION',\n  /** A metric filter uses a search filter. */\n  METRIC_FILTER_SEARCH: 'METRIC_FILTER_SEARCH',\n  /** A metric filter uses `ELEMENT_MATCH`. */\n  METRIC_FILTER_ELEMENT_MATCH: 'METRIC_FILTER_ELEMENT_MATCH',\n  /** A metric filter names an array field; it must be scalar. */\n  METRIC_FILTER_ARRAY_FIELD: 'METRIC_FILTER_ARRAY_FIELD',\n  /** The field cannot be projected. */\n  NOT_PROJECTABLE: 'NOT_PROJECTABLE',\n  /** An event projection that keeps payloads must keep their `bodyType`. */\n  EVENT_PROJECTION_TYPE_REQUIRED: 'EVENT_PROJECTION_TYPE_REQUIRED',\n  /** A relative-time filter needs a field with a known temporal representation. */\n  TEMPORAL_REPRESENTATION_REQUIRED: 'TEMPORAL_REPRESENTATION_REQUIRED',\n  /** A relative-time filter's zone, pattern or unit conflicts with the field's definition. */\n  TEMPORAL_CONFIGURATION_CONFLICT: 'TEMPORAL_CONFIGURATION_CONFLICT',\n  /**\n   * A sort names two array fields on independent arrays, which the storage\n   * cannot order by together; `path` is the second of them. The descriptor\n   * lists such fields under a `PARALLEL_ARRAY_SORT` constraint.\n   */\n  PARALLEL_ARRAY_SORT: 'PARALLEL_ARRAY_SORT',\n  /**\n   * An `EQ` or `NE` compares the field to an array, which the storage cannot\n   * do: it takes only a scalar operand. The descriptor says so with an\n   * `ARRAY_EQUALITY` constraint.\n   */\n  ARRAY_EQUALITY: 'ARRAY_EQUALITY',\n  /**\n   * A `FIRST` or `LAST` metric names a field that may hold several values;\n   * it needs a single-valued one (`aggregate.firstLast` in the descriptor).\n   */\n  FIRST_LAST_REQUIRES_SINGLE_VALUE: 'FIRST_LAST_REQUIRES_SINGLE_VALUE',\n  /**\n   * A `FIRST` or `LAST` metric names no `orderBy` where there is no event\n   * time to order by, such as inside an element or on a model whose\n   * descriptor has no `analysis.firstLastOrderBy`; `path` is its field.\n   */\n  FIRST_LAST_REQUIRES_ORDER_BY: 'FIRST_LAST_REQUIRES_ORDER_BY',\n  /**\n   * A date group or date difference names a field that stores neither a\n   * date nor an epoch (a formatted string, say), so it cannot be aggregated\n   * by time.\n   */\n  TEMPORAL_AGGREGATION_UNSUPPORTED: 'TEMPORAL_AGGREGATION_UNSUPPORTED',\n  /** The sort has more fields than the protocol allows; `path` is `''`. */\n  SORT_TOO_MANY: 'SORT_TOO_MANY',\n  /** Two sort fields name the same stored field; `path` is the second. */\n  SORT_FIELD_DUPLICATE: 'SORT_FIELD_DUPLICATE',\n  /**\n   * An identity filter or a cursor on a model that defines no record\n   * identity; `path` is `''`.\n   */\n  IDENTITY_UNDEFINED: 'IDENTITY_UNDEFINED',\n  /**\n   * The storage does not support the feature the query uses, or its native\n   * query language cannot express it (a MongoDB PHRASE search with a quote,\n   * say); `path` is the field, or `''`.\n   */\n  STORAGE_UNSUPPORTED: 'STORAGE_UNSUPPORTED',\n} as const);\n\n/** One of the codes this package knows; see {@link QueryErrorCodes}. */\nexport type KnownQueryErrorCode =\n  (typeof QueryErrorCodes)[keyof typeof QueryErrorCodes];\n\n/**\n * The code of a rejected query: one this package knows, which editors\n * complete, or one a newer server added.\n */\nexport type QueryErrorCode = KnownQueryErrorCode | (string & {});\n\n/**\n * Why the server rejected a request, read from its first binding error that\n * carries a code: which rule failed, where, and the server's words.\n */\nexport interface QueryViolation {\n  /** Which rule failed; switch on it against {@link QueryErrorCodes}. */\n  code: QueryErrorCode;\n  /**\n   * Where: the JSON path of the offending value for a decoding error\n   * (`filter.state`, `metrics[0]`, `body`), the absolute logical field path\n   * for an admission error (`state.items.sku`), or `''` when the rule is about\n   * the model rather than a field.\n   */\n  path: string;\n  /** The server's words, the same as the error's `errorMsg`. */\n  message: string;\n}\n"],"mappings":"AAuCA,IAAaA,EAAkB,OAAO,OAAO,CAE3C,aAAc,eAEd,gBAAiB,kBAEjB,WAAY,aAEZ,iBAAkB,mBAElB,aAAc,eAEd,cAAe,gBAEf,cAAe,gBAEf,gBAAiB,kBAEjB,sBAAuB,wBAEvB,qBAAsB,uBAKtB,eAAgB,iBAMhB,kBAAmB,oBAKnB,iBAAkB,mBAOlB,4BAA6B,8BAK7B,sBAAuB,wBAMvB,yBAA0B,2BAK1B,wBAAyB,0BAEzB,cAAe,gBAEf,uBAAwB,yBAExB,uBAAwB,yBAExB,eAAgB,iBAEhB,eAAgB,iBAEhB,kBAAmB,oBAEnB,yBAA0B,2BAE1B,mBAAoB,qBAEpB,sBAAuB,wBAMvB,qBAAsB,uBAEtB,4BAA6B,8BAE7B,0BAA2B,4BAE3B,sBAAuB,wBAEvB,qBAAsB,uBAEtB,4BAA6B,8BAE7B,0BAA2B,4BAE3B,gBAAiB,kBAEjB,+BAAgC,iCAEhC,iCAAkC,mCAElC,gCAAiC,kCAMjC,oBAAqB,sBAMrB,eAAgB,iBAKhB,iCAAkC,mCAMlC,6BAA8B,+BAM9B,iCAAkC,mCAElC,cAAe,gBAEf,qBAAsB,uBAKtB,mBAAoB,qBAMpB,oBAAqB,qBACvB,CAAU"}

package/dist/error/queryErrorCodes.d.cts

@@ -0,0 +1,199 @@
+/**
+ * The codes a rejected query carries as `BindingError.code`: which rule the
+ * request broke, stable where the human text (`errorMsg`) is not.
+ *
+ * Mirrors `QueryErrorCodes` in
+ * `wow-api/src/main/kotlin/me/ahoo/wow/api/query/QueryErrorCodes.kt`, which the
+ * server also publishes as the `BindingError.code` enum of its OpenAPI
+ * document. The list is open: Wow adds codes and never renames or reuses one,
+ * so a client treats a code it does not know as a generic rejection and shows
+ * `errorMsg`. {@link QueryErrorCode} admits those codes too.
+ *
+ * Three groups, which `BindingError.name` locates differently:
+ * - decoding the request body (`errorCode` `IllegalArgument`): `name` is the
+ *   JSON path of the offending value, such as `filter.state` or `metrics[0]`,
+ *   or `body` for the body as a whole;
+ * - the entry's budget and gates (`errorCode` `IllegalArgument`): `name` is
+ *   the part of the request the rule bounds, such as `limit` or `filter`;
+ * - admission against the query model (`errorCode` `QuerySchemaValidation`):
+ *   `name` is the absolute logical field path, such as `state.items.sku`, or
+ *   `''` when the rule is about the model rather than one field.
+ *
+ * Budget and gate rejections carry a code from Wow 9.2 on; an older server
+ * answers them with text alone (`HTTP list query limit[...] must be …`). A
+ * failure of the server itself is no rejection: it answers HTTP 500
+ * `InternalServerError` without a binding error.
+ */
+export declare const QueryErrorCodes: Readonly<{
+    /** The body is not valid JSON. */
+    readonly INVALID_JSON: "INVALID_JSON";
+    /** The body is JSON but not an object. */
+    readonly BODY_NOT_OBJECT: "BODY_NOT_OBJECT";
+    /** The body is empty. */
+    readonly EMPTY_BODY: "EMPTY_BODY";
+    /** The body has a property the query type does not declare. */
+    readonly UNKNOWN_PROPERTY: "UNKNOWN_PROPERTY";
+    /** An `op`, metric or other type discriminator names no known type. */
+    readonly UNKNOWN_TYPE: "UNKNOWN_TYPE";
+    /** An enum value is not one the server knows. */
+    readonly UNKNOWN_VALUE: "UNKNOWN_VALUE";
+    /** A value is missing or has the wrong JSON type. */
+    readonly INVALID_VALUE: "INVALID_VALUE";
+    /** Any other request rule; the message names it. */
+    readonly INVALID_REQUEST: "INVALID_REQUEST";
+    /** A cursor sort names a field twice; `path` is the repeated field. */
+    readonly CURSOR_SORT_DUPLICATE: "CURSOR_SORT_DUPLICATE";
+    /** A cursor sort has too many fields once the identity tie-breaker is appended. */
+    readonly CURSOR_SORT_TOO_MANY: "CURSOR_SORT_TOO_MANY";
+    /**
+     * The cursor token was not issued for this model and effective sort, or
+     * does not decode; `path` is `cursor`. Start again from the first page.
+     */
+    readonly INVALID_CURSOR: "INVALID_CURSOR";
+    /**
+     * The entry's budget: a list or aggregation `limit`, a page's index, size,
+     * window or offset, or a cursor page's `size` is out of range; `path` names
+     * which (`limit`, `pagination.size`, `size`, …).
+     */
+    readonly SIZE_OUT_OF_RANGE: "SIZE_OUT_OF_RANGE";
+    /**
+     * The entry's budget: the filter or `having` has too many nodes or values;
+     * `path` is `filter` or `having`.
+     */
+    readonly FILTER_TOO_LARGE: "FILTER_TOO_LARGE";
+    /**
+     * The entry does not allow expensive operators, and the query uses one: an
+     * operator, an element expansion, a metric sort, an arithmetic or
+     * expression group, a date part, a dense fill or FIRST / LAST; `path` names
+     * the part (`filter`, `elements`, `sort`, `metrics`, `groupBy`).
+     */
+    readonly EXPENSIVE_OPERATOR_DISABLED: "EXPENSIVE_OPERATOR_DISABLED";
+    /**
+     * A counting query (count, or a paged query's total) would match every
+     * record, which the entry refuses; `path` is `filter`.
+     */
+    readonly COUNT_REQUIRES_FILTER: "COUNT_REQUIRES_FILTER";
+    /**
+     * A `having` or metric sort the storage evaluates after grouping read more
+     * groups than the server allows; `path` is `body`. It may end a stream
+     * partway through.
+     */
+    readonly RESIDUAL_GROUPS_EXCEEDED: "RESIDUAL_GROUPS_EXCEEDED";
+    /**
+     * An in-process query named no entry where one is required. Never
+     * answered over HTTP; listed so the mirror stays complete.
+     */
+    readonly EXPLICIT_ENTRY_REQUIRED: "EXPLICIT_ENTRY_REQUIRED";
+    /** The model has no such logical field. */
+    readonly UNKNOWN_FIELD: "UNKNOWN_FIELD";
+    /** The field does not offer the capability the query uses (sort, range, …). */
+    readonly UNSUPPORTED_CAPABILITY: "UNSUPPORTED_CAPABILITY";
+    /** The field is an element field and must be queried inside its element scope. */
+    readonly ELEMENT_SCOPE_REQUIRED: "ELEMENT_SCOPE_REQUIRED";
+    /** A filter value falls outside the field's declared domain. */
+    readonly VALUE_MISMATCH: "VALUE_MISMATCH";
+    /** The field is not a known collection (for example under `isEmpty`). */
+    readonly NOT_COLLECTION: "NOT_COLLECTION";
+    /** The field is not a single string. */
+    readonly NOT_SINGLE_STRING: "NOT_SINGLE_STRING";
+    /** The model does not support search. */
+    readonly MODEL_SEARCH_UNSUPPORTED: "MODEL_SEARCH_UNSUPPORTED";
+    /** The field cannot be used for a cursor. */
+    readonly CURSOR_NOT_ALLOWED: "CURSOR_NOT_ALLOWED";
+    /** The field is protected and cannot be aggregated. */
+    readonly PROTECTED_AGGREGATION: "PROTECTED_AGGREGATION";
+    /**
+     * The field is protected and cannot be filtered or sorted: its descriptor
+     * says `sensitivity.comparable: false`. A search that names it is refused
+     * the same way.
+     */
+    readonly PROTECTED_COMPARISON: "PROTECTED_COMPARISON";
+    /** A terms group's `missingKey` needs a single-valued string field. */
+    readonly MISSING_KEY_REQUIRES_STRING: "MISSING_KEY_REQUIRES_STRING";
+    /** `ANY` needs a single value. */
+    readonly ANY_REQUIRES_SINGLE_VALUE: "ANY_REQUIRES_SINGLE_VALUE";
+    /** The storage cannot deliver a complete projection; select fields explicitly. */
+    readonly INCOMPLETE_PROJECTION: "INCOMPLETE_PROJECTION";
+    /** A metric filter uses a search filter. */
+    readonly METRIC_FILTER_SEARCH: "METRIC_FILTER_SEARCH";
+    /** A metric filter uses `ELEMENT_MATCH`. */
+    readonly METRIC_FILTER_ELEMENT_MATCH: "METRIC_FILTER_ELEMENT_MATCH";
+    /** A metric filter names an array field; it must be scalar. */
+    readonly METRIC_FILTER_ARRAY_FIELD: "METRIC_FILTER_ARRAY_FIELD";
+    /** The field cannot be projected. */
+    readonly NOT_PROJECTABLE: "NOT_PROJECTABLE";
+    /** An event projection that keeps payloads must keep their `bodyType`. */
+    readonly EVENT_PROJECTION_TYPE_REQUIRED: "EVENT_PROJECTION_TYPE_REQUIRED";
+    /** A relative-time filter needs a field with a known temporal representation. */
+    readonly TEMPORAL_REPRESENTATION_REQUIRED: "TEMPORAL_REPRESENTATION_REQUIRED";
+    /** A relative-time filter's zone, pattern or unit conflicts with the field's definition. */
+    readonly TEMPORAL_CONFIGURATION_CONFLICT: "TEMPORAL_CONFIGURATION_CONFLICT";
+    /**
+     * A sort names two array fields on independent arrays, which the storage
+     * cannot order by together; `path` is the second of them. The descriptor
+     * lists such fields under a `PARALLEL_ARRAY_SORT` constraint.
+     */
+    readonly PARALLEL_ARRAY_SORT: "PARALLEL_ARRAY_SORT";
+    /**
+     * An `EQ` or `NE` compares the field to an array, which the storage cannot
+     * do: it takes only a scalar operand. The descriptor says so with an
+     * `ARRAY_EQUALITY` constraint.
+     */
+    readonly ARRAY_EQUALITY: "ARRAY_EQUALITY";
+    /**
+     * A `FIRST` or `LAST` metric names a field that may hold several values;
+     * it needs a single-valued one (`aggregate.firstLast` in the descriptor).
+     */
+    readonly FIRST_LAST_REQUIRES_SINGLE_VALUE: "FIRST_LAST_REQUIRES_SINGLE_VALUE";
+    /**
+     * A `FIRST` or `LAST` metric names no `orderBy` where there is no event
+     * time to order by, such as inside an element or on a model whose
+     * descriptor has no `analysis.firstLastOrderBy`; `path` is its field.
+     */
+    readonly FIRST_LAST_REQUIRES_ORDER_BY: "FIRST_LAST_REQUIRES_ORDER_BY";
+    /**
+     * A date group or date difference names a field that stores neither a
+     * date nor an epoch (a formatted string, say), so it cannot be aggregated
+     * by time.
+     */
+    readonly TEMPORAL_AGGREGATION_UNSUPPORTED: "TEMPORAL_AGGREGATION_UNSUPPORTED";
+    /** The sort has more fields than the protocol allows; `path` is `''`. */
+    readonly SORT_TOO_MANY: "SORT_TOO_MANY";
+    /** Two sort fields name the same stored field; `path` is the second. */
+    readonly SORT_FIELD_DUPLICATE: "SORT_FIELD_DUPLICATE";
+    /**
+     * An identity filter or a cursor on a model that defines no record
+     * identity; `path` is `''`.
+     */
+    readonly IDENTITY_UNDEFINED: "IDENTITY_UNDEFINED";
+    /**
+     * The storage does not support the feature the query uses, or its native
+     * query language cannot express it (a MongoDB PHRASE search with a quote,
+     * say); `path` is the field, or `''`.
+     */
+    readonly STORAGE_UNSUPPORTED: "STORAGE_UNSUPPORTED";
+}>;
+/** One of the codes this package knows; see {@link QueryErrorCodes}. */
+export type KnownQueryErrorCode = (typeof QueryErrorCodes)[keyof typeof QueryErrorCodes];
+/**
+ * The code of a rejected query: one this package knows, which editors
+ * complete, or one a newer server added.
+ */
+export type QueryErrorCode = KnownQueryErrorCode | (string & {});
+/**
+ * Why the server rejected a request, read from its first binding error that
+ * carries a code: which rule failed, where, and the server's words.
+ */
+export interface QueryViolation {
+    /** Which rule failed; switch on it against {@link QueryErrorCodes}. */
+    code: QueryErrorCode;
+    /**
+     * Where: the JSON path of the offending value for a decoding error
+     * (`filter.state`, `metrics[0]`, `body`), the absolute logical field path
+     * for an admission error (`state.items.sku`), or `''` when the rule is about
+     * the model rather than a field.
+     */
+    path: string;
+    /** The server's words, the same as the error's `errorMsg`. */
+    message: string;
+}