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

package/dist/client/query/event/eventStreamQueryClient.es.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventStreamQueryClient.es.js","names":["_decorate","_decorateParam","_decorateMetadata","__decorateMetadata","__decorateParam","__decorate","EventStreamQueryClient","apiMetadata","bindMethods","autoGeneratedError","query","attributes","abort","filter","listQuery","pagedQuery","id","headVersion","tailVersion","post","EventStreamQueryEndpointPaths","body","attribute","QUERY_STREAM_ENDPOINT","get","path","api"],"sources":["../../../../src/client/query/event/eventStreamQueryClient.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 { EventStreamQueryApi } from './eventStreamQueryApi.js';\nimport { EventStreamQueryEndpointPaths } from './endpointPaths.js';\nimport type { AggregationQuery } from '../../../dsl/aggregation/index.js';\nimport type { FilterExpression } from '../../../dsl/filter/index.js';\nimport type {\n  Condition,\n  ListQueryRequest,\n  PagedQueryRequest,\n} from '../requests.js';\nimport type { PagedList } from '../../../dsl/queryable.js';\nimport type { DomainEventStream } from './domainEventStream.js';\nimport type { DynamicDocument } from '../../../dsl/documents.js';\nimport { QUERY_STREAM_ENDPOINT } from '../../../transport/endpoints.js';\nimport type { CursorPage, CursorQuery } from '../../../dsl/cursorQuery.js';\n\nimport type {\n  ApiMetadata,\n  ApiMetadataCapable,\n} from '@ahoo-wang/fetcher-decorator';\nimport {\n  api,\n  attribute,\n  autoGeneratedError,\n  body,\n  get,\n  path,\n  post,\n} from '@ahoo-wang/fetcher-decorator';\nimport { bindMethods } from '../../bindMethods.js';\n\n/**\n * Client for querying event streams through HTTP endpoints.\n * Implements EventStreamQueryApi to provide methods\n * for querying domain event streams with different query patterns.\n * This client supports counting, listing, streaming, and paging operations on event streams.\n *\n * @example\n * ```typescript\n * // Create client options configuration\n * const clientOptions: ApiMetadata = {\n *   fetcher: new Fetcher({ baseURL: 'http://localhost:8080/' }),\n *   basePath: 'owner/{ownerId}/cart'\n * };\n *\n * // Create an event stream query client instance\n * const eventStreamQueryClient = new EventStreamQueryClient(clientOptions);\n *\n * // Count event streams\n * const count = await eventStreamQueryClient.count(filter.matchAll());\n *\n * // List event streams\n * const listQuery: FilterListQuery = {\n *   filter: filter.matchAll()\n * };\n * const list = await eventStreamQueryClient.list(listQuery);\n *\n * // List event streams as stream\n * const listStream = await eventStreamQueryClient.listStream(listQuery);\n * for await (const domainEventStream of listStream) {\n *   console.log('Received:', domainEventStream);\n * }\n *\n * // Paged event streams\n * const pagedQuery: FilterPagedQuery = {\n *   filter: filter.matchAll()\n * };\n * const paged = await eventStreamQueryClient.paged(pagedQuery);\n * ```\n */\n@api()\nexport class EventStreamQueryClient<\n  DomainEventBody = unknown,\n  FIELDS extends string = string,\n>\n  implements EventStreamQueryApi<DomainEventBody, FIELDS>, ApiMetadataCapable\n{\n  /**\n   * Creates a new EventStreamQueryClient instance.\n   */\n  constructor(public readonly apiMetadata?: ApiMetadata) {\n    bindMethods(this);\n  }\n\n  /** Runs an event stream aggregation and returns all result rows. */\n  @post(EventStreamQueryEndpointPaths.AGGREGATION)\n  /* v8 ignore start */\n  aggregate<\n    Row extends object = DynamicDocument,\n    AGGREGATION_FIELDS extends string = string,\n  >(\n    @body() query: AggregationQuery<FIELDS, AGGREGATION_FIELDS>,\n    @attribute() attributes?: Record<string, unknown>,\n    abort?: AbortController | AbortSignal,\n  ): Promise<Row[]> {\n    throw autoGeneratedError(query, attributes, abort);\n  }\n  /* v8 ignore stop */\n\n  /** Runs an event stream aggregation and streams the result rows, one per server-sent event. */\n  @post(EventStreamQueryEndpointPaths.AGGREGATION, QUERY_STREAM_ENDPOINT)\n  /* v8 ignore start */\n  aggregateStream<\n    Row extends object = DynamicDocument,\n    AGGREGATION_FIELDS extends string = string,\n  >(\n    @body() query: AggregationQuery<FIELDS, AGGREGATION_FIELDS>,\n    @attribute() attributes?: Record<string, unknown>,\n    abort?: AbortController | AbortSignal,\n  ): Promise<ReadableStream<Row>> {\n    throw autoGeneratedError(query, attributes, abort);\n  }\n  /* v8 ignore stop */\n\n  /** Retrieves the next cursor page of domain event streams. */\n  @post(EventStreamQueryEndpointPaths.CURSOR)\n  /* v8 ignore start */\n  cursor<\n    T extends Partial<DomainEventStream<DomainEventBody>> =\n      DomainEventStream<DomainEventBody>,\n  >(\n    @body() query: CursorQuery<FIELDS>,\n    @attribute() attributes?: Record<string, unknown>,\n    abort?: AbortController | AbortSignal,\n  ): Promise<CursorPage<T>> {\n    throw autoGeneratedError(query, attributes, abort);\n  }\n  /* v8 ignore stop */\n\n  /**\n   * Counts the number of domain event streams that match the given filter.\n   *\n   * @param filter - The filter expression or legacy condition\n   * @param attributes - Optional shared attributes that can be accessed by interceptors\n   *                     throughout the request lifecycle. These attributes allow passing\n   *                     custom data between different interceptors.\n   * @param abort - Cancels the request: an `AbortController`, or an `AbortSignal` such as `AbortSignal.timeout(ms)` or the `signal` a data-fetching library passes.\n   * @returns A promise that resolves to the count of matching event streams\n   *\n   * @example\n   * ```typescript\n   * const controller = new AbortController();\n   * const count = await eventStreamQueryClient.count(filter.matchAll(), undefined, controller);\n   * console.log('Total event streams:', count);\n   *\n   * // Cancel the request if needed\n   * controller.abort();\n   * ```\n   */\n  @post(EventStreamQueryEndpointPaths.COUNT)\n  /* v8 ignore start */\n  count(\n    // compat(wow<9): accepts the deprecated Condition, which Wow < 8.11 needs; narrow to FilterExpression in v10.\n    @body() filter: FilterExpression<FIELDS> | Condition<FIELDS>,\n    @attribute() attributes?: Record<string, unknown>,\n    abort?: AbortController | AbortSignal,\n  ): Promise<number> {\n    throw autoGeneratedError(filter, attributes, abort);\n  }\n  /* v8 ignore stop */\n\n  /**\n   * Retrieves a list of domain event streams based on the provided query parameters.\n   *\n   * @param listQuery - The query parameters for listing event streams\n   * @param attributes - Optional shared attributes that can be accessed by interceptors\n   *                     throughout the request lifecycle. These attributes allow passing\n   *                     custom data between different interceptors.\n   * @param abort - Cancels the request: an `AbortController`, or an `AbortSignal` such as `AbortSignal.timeout(ms)` or the `signal` a data-fetching library passes.\n   * @returns A promise that resolves to an array of partial domain event streams\n   *\n   * @example\n   * ```typescript\n   * const controller = new AbortController();\n   * const listQuery: FilterListQuery = {\n   *   filter: filter.matchAll()\n   * };\n   * const list = await eventStreamQueryClient.list(listQuery, undefined, controller);\n   * for (const domainEventStream of list) {\n   *   console.log('Event stream:', domainEventStream);\n   * }\n   *\n   * // Cancel the request if needed\n   * controller.abort();\n   * ```\n   */\n  @post(EventStreamQueryEndpointPaths.LIST)\n  /* v8 ignore start */\n  list<\n    T extends Partial<DomainEventStream<DomainEventBody>> =\n      DomainEventStream<DomainEventBody>,\n  >(\n    @body() listQuery: ListQueryRequest<FIELDS>,\n    @attribute() attributes?: Record<string, unknown>,\n    abort?: AbortController | AbortSignal,\n  ): Promise<T[]> {\n    throw autoGeneratedError(listQuery, attributes, abort);\n  }\n  /* v8 ignore stop */\n\n  /**\n   * Retrieves a stream of domain event streams based on the provided query parameters.\n   * Sets the Accept header to text/event-stream to indicate that the response should be streamed.\n   *\n   * @param listQuery - The query parameters for listing event streams\n   * @param attributes - Optional shared attributes that can be accessed by interceptors\n   *                     throughout the request lifecycle. These attributes allow passing\n   *                     custom data between different interceptors.\n   * @param abort - Cancels the request: an `AbortController`, or an `AbortSignal` such as `AbortSignal.timeout(ms)` or the `signal` a data-fetching library passes.\n   * @returns A promise that resolves to a readable stream of partial domain event streams\n   *\n   * @example\n   * ```typescript\n   * const controller = new AbortController();\n   * const listQuery: FilterListQuery = {\n   *   filter: filter.matchAll()\n   * };\n   * const listStream = await eventStreamQueryClient.listStream(listQuery, undefined, controller);\n   * for await (const domainEventStream of listStream) {\n   *   console.log('Received event stream:', domainEventStream);\n   * }\n   *\n   * // Cancel the request if needed\n   * controller.abort();\n   * ```\n   */\n  @post(EventStreamQueryEndpointPaths.LIST, QUERY_STREAM_ENDPOINT)\n  /* v8 ignore start */\n  listStream<\n    T extends Partial<DomainEventStream<DomainEventBody>> =\n      DomainEventStream<DomainEventBody>,\n  >(\n    @body() listQuery: ListQueryRequest<FIELDS>,\n    @attribute() attributes?: Record<string, unknown>,\n    abort?: AbortController | AbortSignal,\n  ): Promise<ReadableStream<T>> {\n    throw autoGeneratedError(listQuery, attributes, abort);\n  }\n  /* v8 ignore stop */\n\n  /**\n   * Retrieves a paged list of domain event streams based on the provided query parameters.\n   *\n   * @param pagedQuery - The query parameters for paging event streams\n   * @param attributes - Optional shared attributes that can be accessed by interceptors\n   *                     throughout the request lifecycle. These attributes allow passing\n   *                     custom data between different interceptors.\n   * @param abort - Cancels the request: an `AbortController`, or an `AbortSignal` such as `AbortSignal.timeout(ms)` or the `signal` a data-fetching library passes.\n   * @returns A promise that resolves to a paged list of partial domain event streams\n   *\n   * @example\n   * ```typescript\n   * const controller = new AbortController();\n   * const pagedQuery: FilterPagedQuery = {\n   *   filter: filter.matchAll(),\n   *   pagination: { index: 1, size: 10 }\n   * };\n   * const paged = await eventStreamQueryClient.paged(pagedQuery, undefined, controller);\n   * console.log('Total:', paged.total);\n   * for (const domainEventStream of paged.list) {\n   *   console.log('Event stream:', domainEventStream);\n   * }\n   *\n   * // Cancel the request if needed\n   * controller.abort();\n   * ```\n   */\n  @post(EventStreamQueryEndpointPaths.PAGED)\n  /* v8 ignore start */\n  paged<\n    T extends Partial<DomainEventStream<DomainEventBody>> =\n      DomainEventStream<DomainEventBody>,\n  >(\n    @body() pagedQuery: PagedQueryRequest<FIELDS>,\n    @attribute() attributes?: Record<string, unknown>,\n    abort?: AbortController | AbortSignal,\n  ): Promise<PagedList<T>> {\n    throw autoGeneratedError(pagedQuery, attributes, abort);\n  }\n  /* v8 ignore stop */\n\n  /**\n   * Loads one aggregate's event streams from `headVersion` to `tailVersion`,\n   * both inclusive, in version order — how an audit trail or an event\n   * sourcing view replays an aggregate. `GET {id}/event/{headVersion}/{tailVersion}`.\n   *\n   * The server treats the range as a list query: more than its maximum list\n   * size (1000 by default) is refused. The route carries a tenant segment by\n   * default but no owner segment, like the load-state routes.\n   *\n   * @param id - The aggregate id\n   * @param headVersion - The first version, from 1\n   * @param tailVersion - The last version\n   * @param attributes - Optional shared attributes for the interceptors\n   * @param abort - Cancels the request: an `AbortController`, or an `AbortSignal` such as `AbortSignal.timeout(ms)` or the `signal` a data-fetching library passes.\n   * @returns The event streams of versions `headVersion` to `tailVersion`\n   *\n   * @example\n   * ```typescript\n   * const firstTen = await eventStreamQueryClient.load(cartId, 1, 10);\n   * ```\n   */\n  @get(EventStreamQueryEndpointPaths.LOAD)\n  /* v8 ignore start */\n  load<\n    T extends Partial<DomainEventStream<DomainEventBody>> =\n      DomainEventStream<DomainEventBody>,\n  >(\n    @path('id') id: string,\n    @path('headVersion') headVersion: number,\n    @path('tailVersion') tailVersion: number,\n    @attribute() attributes?: Record<string, unknown>,\n    abort?: AbortController | AbortSignal,\n  ): Promise<T[]> {\n    throw autoGeneratedError(id, headVersion, tailVersion, attributes, abort);\n  }\n  /* v8 ignore stop */\n\n  /**\n   * {@link load} as a stream, one event stream per server-sent event.\n   * The stream errors with a `WowError` if the server fails midway.\n   */\n  @get(EventStreamQueryEndpointPaths.LOAD, QUERY_STREAM_ENDPOINT)\n  /* v8 ignore start */\n  loadStream<\n    T extends Partial<DomainEventStream<DomainEventBody>> =\n      DomainEventStream<DomainEventBody>,\n  >(\n    @path('id') id: string,\n    @path('headVersion') headVersion: number,\n    @path('tailVersion') tailVersion: number,\n    @attribute() attributes?: Record<string, unknown>,\n    abort?: AbortController | AbortSignal,\n  ): Promise<ReadableStream<T>> {\n    throw autoGeneratedError(id, headVersion, tailVersion, attributes, abort);\n  }\n  /* v8 ignore stop */\n}\n"],"mappings":";;;;;;;;AAmFO,IAAMM,IAAN,MAKP;CAIE,YAAY,GAA2C;EACrD,AAD0B,KAAA,cAAAC,GAC1BC,EAAY,IAAI;CAClB;CAGA,UAME,GACA,GACA,GACgB;EAChB,MAAMC,EAAmBC,GAAOC,GAAYC,CAAK;CACnD;;CAIA,gBAME,GACA,GACA,GAC8B;EAC9B,MAAMH,EAAmBC,GAAOC,GAAYC,CAAK;CACnD;;CAIA,OAME,GACA,GACA,GACwB;EACxB,MAAMH,EAAmBC,GAAOC,GAAYC,CAAK;CACnD;;CAuBA,MAIE,GACA,GACA,GACiB;EACjB,MAAMH,EAAmBI,GAAQF,GAAYC,CAAK;CACpD;;CA4BA,KAME,GACA,GACA,GACc;EACd,MAAMH,EAAmBK,GAAWH,GAAYC,CAAK;CACvD;;CA6BA,WAME,GACA,GACA,GAC4B;EAC5B,MAAMH,EAAmBK,GAAWH,GAAYC,CAAK;CACvD;;CA8BA,MAME,GACA,GACA,GACuB;EACvB,MAAMH,EAAmBM,GAAYJ,GAAYC,CAAK;CACxD;;CAwBA,KAME,GACA,GACA,GACA,GACA,GACc;EACd,MAAMH,EAAmBO,GAAIC,GAAaC,GAAaP,GAAYC,CAAK;CAC1E;;CAOA,WAME,GACA,GACA,GACA,GACA,GAC4B;EAC5B,MAAMH,EAAmBO,GAAIC,GAAaC,GAAaP,GAAYC,CAAK;CAC1E;AAEF;;CA5PGO,EAAKC,EAA8B,WAAW;CAM5CnB,EAAA,GAAAoB,EAAK,CAAA;CACLpB,EAAA,GAAAqB,EAAU,CAAA;;;;;;;;;CAQZH,EAAKC,EAA8B,aAAaG,CAAqB;CAMnEtB,EAAA,GAAAoB,EAAK,CAAA;CACLpB,EAAA,GAAAqB,EAAU,CAAA;;;;;;;;;CAQZH,EAAKC,EAA8B,MAAM;CAMvCnB,EAAA,GAAAoB,EAAK,CAAA;CACLpB,EAAA,GAAAqB,EAAU,CAAA;;;;;;;;;CA2BZH,EAAKC,EAA8B,KAAK;CAItCnB,EAAA,GAAAoB,EAAK,CAAA;CACLpB,EAAA,GAAAqB,EAAU,CAAA;;;;;;;;;CAgCZH,EAAKC,EAA8B,IAAI;CAMrCnB,EAAA,GAAAoB,EAAK,CAAA;CACLpB,EAAA,GAAAqB,EAAU,CAAA;;;;;;;;;CAiCZH,EAAKC,EAA8B,MAAMG,CAAqB;CAM5DtB,EAAA,GAAAoB,EAAK,CAAA;CACLpB,EAAA,GAAAqB,EAAU,CAAA;;;;;;;;;CAkCZH,EAAKC,EAA8B,KAAK;CAMtCnB,EAAA,GAAAoB,EAAK,CAAA;CACLpB,EAAA,GAAAqB,EAAU,CAAA;;;;;;;;;CA4BZE,EAAIJ,EAA8B,IAAI;CAMpCnB,EAAA,GAAAwB,EAAK,IAAI,CAAA;CACTxB,EAAA,GAAAwB,EAAK,aAAa,CAAA;CAClBxB,EAAA,GAAAwB,EAAK,aAAa,CAAA;CAClBxB,EAAA,GAAAqB,EAAU,CAAA;;;;;;;;;;;CAWZE,EAAIJ,EAA8B,MAAMG,CAAqB;CAM3DtB,EAAA,GAAAwB,EAAK,IAAI,CAAA;CACTxB,EAAA,GAAAwB,EAAK,aAAa,CAAA;CAClBxB,EAAA,GAAAwB,EAAK,aAAa,CAAA;CAClBxB,EAAA,GAAAqB,EAAU,CAAA;;;;;;;;;;qCArQd,IAAAtB,EAAA,CAAA0B,EAAI,GAAAxB,EAAA,qBAAA,CAAA,MAAA,CAAA,CAAA,GAAAI,CAAA"}

package/dist/client/query/event/index.d.cts

@@ -0,0 +1,3 @@
+export * from './domainEventStream.cjs';
+export * from './eventStreamQueryApi.cjs';
+export * from './eventStreamQueryClient.cjs';

package/dist/client/query/event/index.d.ts

@@ -0,0 +1,3 @@
+export * from './domainEventStream.js';
+export * from './eventStreamQueryApi.js';
+export * from './eventStreamQueryClient.js';

package/dist/client/query/factory.cjs

@@ -0,0 +1,2 @@
+const e=require("./event/eventStreamQueryClient.cjs"),t=require("./snapshot/snapshotQueryClient.cjs"),n=require("./state/loadStateAggregateClient.cjs"),r=require("./state/loadOwnerStateAggregateClient.cjs"),i=require("./descriptor/queryDescriptorClient.cjs");let a=require("@ahoo-wang/fetcher");function o(e,t,n=!0){let{contextAlias:r,resourceAttribution:i,aggregateName:a,...o}={...e,...t};return{...o,basePath:t?.basePath??e.basePath??s(r,n?i:void 0,a)}}function s(e,t,n){let r=(0,a.combineURLs)(t??``,n??``);return e?(0,a.combineURLs)(e,r):r}var c=class{constructor(e){this.defaultOptions=e}createSnapshotQueryClient(e){return new t.SnapshotQueryClient(o(this.defaultOptions,e))}createLoadStateAggregateClient(e){return new n.LoadStateAggregateClient(o(this.defaultOptions,e))}createLoadOwnerStateAggregateClient(e){return new r.LoadOwnerStateAggregateClient(o(this.defaultOptions,e))}createEventStreamQueryClient(t){return new e.EventStreamQueryClient(o(this.defaultOptions,t))}createQueryDescriptorClient(e){return new i.QueryDescriptorClient(o(this.defaultOptions,e,!1))}};exports.QueryClientFactory=c;
+//# sourceMappingURL=factory.cjs.map

package/dist/client/query/factory.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.cjs","names":["combineURLs","SnapshotQueryClient","LoadStateAggregateClient","LoadOwnerStateAggregateClient","EventStreamQueryClient","QueryDescriptorClient","require_eventStreamQueryClient","require_snapshotQueryClient","require_loadStateAggregateClient","require_loadOwnerStateAggregateClient","require_queryDescriptorClient","_ahoo_wang_fetcher","queryApiMetadata","apiMetadata","defaults","options","routePath","contextAlias","attributed","resourceAttribution","aggregateName","path","QueryClientFactory","defaultOptions"],"sources":["../../../src/client/query/factory.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 { PartialBy } from '@ahoo-wang/fetcher';\nimport { combineURLs } from '@ahoo-wang/fetcher';\nimport type { ApiMetadata } from '@ahoo-wang/fetcher-decorator';\nimport type {\n  AggregateNameCapable,\n  AliasBoundedContext,\n} from '../../model/index.js';\nimport type { ResourceAttributionPathSpec } from '../routing.js';\nimport { SnapshotQueryClient } from './snapshot/index.js';\nimport { EventStreamQueryClient } from './event/index.js';\nimport { LoadStateAggregateClient } from './state/index.js';\nimport { LoadOwnerStateAggregateClient } from './state/index.js';\nimport { QueryDescriptorClient } from './descriptor/index.js';\n\n/**\n * Configuration options for query clients: the client's `ApiMetadata`\n * (`fetcher`, `headers`, `urlParams`, …, with `basePath` optional), plus\n * three keys only {@link QueryClientFactory} reads to build the base path:\n * `contextAlias`, `resourceAttribution` and `aggregateName`.\n *\n * The base path is `basePath` when one is given, and then the three keys\n * are not used. Otherwise it is\n * `{contextAlias}{resourceAttribution}/{aggregateName}`, each part left out\n * when absent. The three keys are not passed on to the client.\n */\nexport interface QueryClientOptions\n  extends\n    PartialBy<ApiMetadata, 'basePath'>,\n    Partial<AliasBoundedContext>,\n    Partial<AggregateNameCapable> {\n  contextAlias?: string;\n  resourceAttribution?: ResourceAttributionPathSpec;\n}\n\n/**\n * The `ApiMetadata` a factory gives a client: `options` over the factory's\n * `defaults`, the base path resolved, and the keys only the factory reads\n * left out. `attributed: false` leaves the resource attribution out of the\n * base path, for routes that have no tenant or owner segment.\n */\nfunction queryApiMetadata(\n  defaults: QueryClientOptions,\n  options?: QueryClientOptions,\n  attributed = true,\n): ApiMetadata {\n  const { contextAlias, resourceAttribution, aggregateName, ...apiMetadata } = {\n    ...defaults,\n    ...options,\n  };\n  return {\n    ...apiMetadata,\n    basePath:\n      options?.basePath ??\n      defaults.basePath ??\n      routePath(\n        contextAlias,\n        attributed ? resourceAttribution : undefined,\n        aggregateName,\n      ),\n  };\n}\n\n/** `{contextAlias}{resourceAttribution}/{aggregateName}`. */\nfunction routePath(\n  contextAlias: string | undefined,\n  resourceAttribution: ResourceAttributionPathSpec | undefined,\n  aggregateName: string | undefined,\n): string {\n  const path = combineURLs(resourceAttribution ?? '', aggregateName ?? '');\n  return contextAlias ? combineURLs(contextAlias, path) : path;\n}\n\n/**\n * Creates the query clients of one aggregate from shared defaults: its\n * snapshot, event stream, load-state and query descriptor clients. Each `create*` call may\n * override the defaults; see {@link QueryClientOptions} for how the base path\n * is built. Generated code creates one factory per aggregate.\n *\n * @template S - The type of the aggregate state\n * @template FIELDS - The field paths snapshot queries may name\n * @template DomainEventBody - The type of the aggregate's event bodies\n */\nexport class QueryClientFactory<\n  S,\n  FIELDS extends string = string,\n  DomainEventBody = unknown,\n> {\n  /**\n   * Creates a new QueryClientFactory instance with the specified default options.\n   *\n   * @param defaultOptions - The default options to be used for all query clients created by this factory\n   *\n   * @example\n   * ```typescript\n   * import { QueryClientFactory, ResourceAttributionPathSpec } from '@ahoo-wang/wow-client';\n   *\n   * const factory = new QueryClientFactory({\n   *   contextAlias: 'example',\n   *   aggregateName: 'cart',\n   *   resourceAttribution: ResourceAttributionPathSpec.OWNER,\n   * });\n   * ```\n   */\n  constructor(private readonly defaultOptions: QueryClientOptions) {}\n\n  /**\n   * Creates a snapshot query client for querying aggregate snapshots.\n   *\n   * This method merges the provided options with the factory's default options,\n   * then creates API metadata and instantiates a SnapshotQueryClient.\n   *\n   * @param options - The query client options used to configure the snapshot query client\n   * @returns A new instance of SnapshotQueryClient\n   *\n   * @example\n   * ```typescript\n   * const snapshotClient = factory.createSnapshotQueryClient({\n   *   aggregateName: 'cart',\n   * });\n   *\n   * const cartState = await snapshotClient.singleState(singleQuery());\n   * ```\n   */\n  createSnapshotQueryClient(\n    options?: QueryClientOptions,\n  ): SnapshotQueryClient<S, FIELDS> {\n    return new SnapshotQueryClient(\n      queryApiMetadata(this.defaultOptions, options),\n    );\n  }\n\n  /**\n   * Creates a client for loading aggregate state by ID.\n   *\n   * This method merges the provided options with the factory's default options,\n   * then creates API metadata and instantiates a LoadStateAggregateClient.\n   * The client supports loading current state, versioned state, and time-based state.\n   *\n   * @param options - The query client options used to configure the state aggregate client\n   * @returns A new instance of LoadStateAggregateClient\n   *\n   * @example\n   * ```typescript\n   * const stateClient = factory.createLoadStateAggregateClient({\n   *   aggregateName: 'cart',\n   * });\n   *\n   * // Load current state\n   * const currentState = await stateClient.load('cart-123');\n   *\n   * // Load specific version\n   * const versionedState = await stateClient.loadVersioned('cart-123', 5);\n   *\n   * // Load state at specific time\n   * const timeBasedState = await stateClient.loadTimeBased('cart-123', Date.now());\n   * ```\n   */\n  createLoadStateAggregateClient(\n    options?: QueryClientOptions,\n  ): LoadStateAggregateClient<S> {\n    return new LoadStateAggregateClient(\n      queryApiMetadata(this.defaultOptions, options),\n    );\n  }\n\n  /**\n   * Creates a client for loading owner-specific aggregate state.\n   *\n   * This method merges the provided options with the factory's default options,\n   * then creates API metadata and instantiates a LoadOwnerStateAggregateClient.\n   * Unlike the standard state client, this client loads state for the current owner\n   * without requiring an explicit ID parameter.\n   *\n   * @param options - The query client options used to configure the owner state aggregate client\n   * @returns A new instance of LoadOwnerStateAggregateClient\n   *\n   * @example\n   * ```typescript\n   * const ownerStateClient = factory.createLoadOwnerStateAggregateClient({\n   *   aggregateName: 'cart',\n   *   resourceAttribution: ResourceAttributionPathSpec.OWNER,\n   * });\n   *\n   * // Load current owner's state\n   * const currentState = await ownerStateClient.load();\n   *\n   * // Load specific version of owner's state\n   * const versionedState = await ownerStateClient.loadVersioned(5);\n   *\n   * // Load owner's state at specific time\n   * const timeBasedState = await ownerStateClient.loadTimeBased(Date.now());\n   * ```\n   */\n  createLoadOwnerStateAggregateClient(\n    options?: QueryClientOptions,\n  ): LoadOwnerStateAggregateClient<S> {\n    return new LoadOwnerStateAggregateClient(\n      queryApiMetadata(this.defaultOptions, options),\n    );\n  }\n\n  /**\n   * Creates an event stream query client for querying domain event streams.\n   *\n   * This method merges the provided options with the factory's default options,\n   * then creates API metadata and instantiates an EventStreamQueryClient.\n   *\n   * @param options - The query client options used to configure the event stream query client\n   * @returns A new instance of EventStreamQueryClient\n   *\n   * @example\n   * ```typescript\n   * const eventClient = factory.createEventStreamQueryClient({\n   *   aggregateName: 'cart',\n   * });\n   *\n   * const events = await eventClient.list(listQuery());\n   * ```\n   */\n  createEventStreamQueryClient<EVENT_FIELDS extends string = string>(\n    options?: QueryClientOptions,\n  ): EventStreamQueryClient<DomainEventBody, EVENT_FIELDS> {\n    return new EventStreamQueryClient(\n      queryApiMetadata(this.defaultOptions, options),\n    );\n  }\n\n  /**\n   * Creates a client that reads the aggregate's query capability\n   * descriptors (`{aggregate}/snapshot/schema`, `{aggregate}/event/schema`).\n   *\n   * Its base path is `basePath` when one is given, as for the other clients;\n   * otherwise `{contextAlias}/{aggregateName}` without the\n   * `resourceAttribution`: the schema routes have no tenant or owner segment.\n   *\n   * @param options - Overrides the factory's defaults, as for the other clients\n   * @returns A new instance of QueryDescriptorClient\n   *\n   * @example\n   * ```typescript\n   * const descriptors = factory.createQueryDescriptorClient();\n   * const snapshot = await descriptors.describeSnapshot();\n   * ```\n   */\n  createQueryDescriptorClient(\n    options?: QueryClientOptions,\n  ): QueryDescriptorClient {\n    return new QueryDescriptorClient(\n      queryApiMetadata(this.defaultOptions, options, false),\n    );\n  }\n}\n"],"mappings":"uSAqDA,SAASY,EACP,EACA,EACA,EAAa,GACA,CACb,GAAM,CAAE,eAAc,sBAAqB,gBAAe,GAAGC,GAAgB,CAC3E,GAAGC,EACH,GAAGC,CACL,EACA,MAAO,CACL,GAAGF,EACH,SACEE,GAAS,UACTD,EAAS,UACTE,EACEC,EACAC,EAAaC,EAAsB,IAAA,GACnCC,CACF,CACJ,CACF,CAGA,SAASJ,EACP,EACA,EACA,EACQ,CACR,IAAMK,GAAA,EAAOrB,EAAAA,YAAAA,CAAYmB,GAAuB,GAAIC,GAAiB,EAAE,EACvE,OAAOH,GAAA,EAAejB,EAAAA,YAAAA,CAAYiB,EAAcI,CAAI,EAAIA,CAC1D,CAYA,IAAaC,EAAb,KAIE,CAiBA,YAAY,EAAqD,CAApC,KAAA,eAAAC,CAAqC,CAoBlE,0BACE,EACgC,CAChC,OAAO,IAAItB,EAAAA,oBACTW,EAAiB,KAAK,eAAgBG,CAAO,CAC/C,CACF,CA4BA,+BACE,EAC6B,CAC7B,OAAO,IAAIb,EAAAA,yBACTU,EAAiB,KAAK,eAAgBG,CAAO,CAC/C,CACF,CA8BA,oCACE,EACkC,CAClC,OAAO,IAAIZ,EAAAA,8BACTS,EAAiB,KAAK,eAAgBG,CAAO,CAC/C,CACF,CAoBA,6BACE,EACuD,CACvD,OAAO,IAAIX,EAAAA,uBACTQ,EAAiB,KAAK,eAAgBG,CAAO,CAC/C,CACF,CAmBA,4BACE,EACuB,CACvB,OAAO,IAAIV,EAAAA,sBACTO,EAAiB,KAAK,eAAgBG,EAAS,EAAK,CACtD,CACF,CACF"}

package/dist/client/query/factory.d.cts

@@ -0,0 +1,165 @@
+import { PartialBy } from '@ahoo-wang/fetcher';
+import { ApiMetadata } from '@ahoo-wang/fetcher-decorator';
+import { AggregateNameCapable, AliasBoundedContext } from '../../model/index.cjs';
+import { ResourceAttributionPathSpec } from '../routing.cjs';
+import { SnapshotQueryClient } from './snapshot/index.cjs';
+import { EventStreamQueryClient } from './event/index.cjs';
+import { LoadStateAggregateClient, LoadOwnerStateAggregateClient } from './state/index.cjs';
+import { QueryDescriptorClient } from './descriptor/index.cjs';
+/**
+ * Configuration options for query clients: the client's `ApiMetadata`
+ * (`fetcher`, `headers`, `urlParams`, …, with `basePath` optional), plus
+ * three keys only {@link QueryClientFactory} reads to build the base path:
+ * `contextAlias`, `resourceAttribution` and `aggregateName`.
+ *
+ * The base path is `basePath` when one is given, and then the three keys
+ * are not used. Otherwise it is
+ * `{contextAlias}{resourceAttribution}/{aggregateName}`, each part left out
+ * when absent. The three keys are not passed on to the client.
+ */
+export interface QueryClientOptions extends PartialBy<ApiMetadata, 'basePath'>, Partial<AliasBoundedContext>, Partial<AggregateNameCapable> {
+    contextAlias?: string;
+    resourceAttribution?: ResourceAttributionPathSpec;
+}
+/**
+ * Creates the query clients of one aggregate from shared defaults: its
+ * snapshot, event stream, load-state and query descriptor clients. Each `create*` call may
+ * override the defaults; see {@link QueryClientOptions} for how the base path
+ * is built. Generated code creates one factory per aggregate.
+ *
+ * @template S - The type of the aggregate state
+ * @template FIELDS - The field paths snapshot queries may name
+ * @template DomainEventBody - The type of the aggregate's event bodies
+ */
+export declare class QueryClientFactory<S, FIELDS extends string = string, DomainEventBody = unknown> {
+    private readonly defaultOptions;
+    /**
+     * Creates a new QueryClientFactory instance with the specified default options.
+     *
+     * @param defaultOptions - The default options to be used for all query clients created by this factory
+     *
+     * @example
+     * ```typescript
+     * import { QueryClientFactory, ResourceAttributionPathSpec } from '@ahoo-wang/wow-client';
+     *
+     * const factory = new QueryClientFactory({
+     *   contextAlias: 'example',
+     *   aggregateName: 'cart',
+     *   resourceAttribution: ResourceAttributionPathSpec.OWNER,
+     * });
+     * ```
+     */
+    constructor(defaultOptions: QueryClientOptions);
+    /**
+     * Creates a snapshot query client for querying aggregate snapshots.
+     *
+     * This method merges the provided options with the factory's default options,
+     * then creates API metadata and instantiates a SnapshotQueryClient.
+     *
+     * @param options - The query client options used to configure the snapshot query client
+     * @returns A new instance of SnapshotQueryClient
+     *
+     * @example
+     * ```typescript
+     * const snapshotClient = factory.createSnapshotQueryClient({
+     *   aggregateName: 'cart',
+     * });
+     *
+     * const cartState = await snapshotClient.singleState(singleQuery());
+     * ```
+     */
+    createSnapshotQueryClient(options?: QueryClientOptions): SnapshotQueryClient<S, FIELDS>;
+    /**
+     * Creates a client for loading aggregate state by ID.
+     *
+     * This method merges the provided options with the factory's default options,
+     * then creates API metadata and instantiates a LoadStateAggregateClient.
+     * The client supports loading current state, versioned state, and time-based state.
+     *
+     * @param options - The query client options used to configure the state aggregate client
+     * @returns A new instance of LoadStateAggregateClient
+     *
+     * @example
+     * ```typescript
+     * const stateClient = factory.createLoadStateAggregateClient({
+     *   aggregateName: 'cart',
+     * });
+     *
+     * // Load current state
+     * const currentState = await stateClient.load('cart-123');
+     *
+     * // Load specific version
+     * const versionedState = await stateClient.loadVersioned('cart-123', 5);
+     *
+     * // Load state at specific time
+     * const timeBasedState = await stateClient.loadTimeBased('cart-123', Date.now());
+     * ```
+     */
+    createLoadStateAggregateClient(options?: QueryClientOptions): LoadStateAggregateClient<S>;
+    /**
+     * Creates a client for loading owner-specific aggregate state.
+     *
+     * This method merges the provided options with the factory's default options,
+     * then creates API metadata and instantiates a LoadOwnerStateAggregateClient.
+     * Unlike the standard state client, this client loads state for the current owner
+     * without requiring an explicit ID parameter.
+     *
+     * @param options - The query client options used to configure the owner state aggregate client
+     * @returns A new instance of LoadOwnerStateAggregateClient
+     *
+     * @example
+     * ```typescript
+     * const ownerStateClient = factory.createLoadOwnerStateAggregateClient({
+     *   aggregateName: 'cart',
+     *   resourceAttribution: ResourceAttributionPathSpec.OWNER,
+     * });
+     *
+     * // Load current owner's state
+     * const currentState = await ownerStateClient.load();
+     *
+     * // Load specific version of owner's state
+     * const versionedState = await ownerStateClient.loadVersioned(5);
+     *
+     * // Load owner's state at specific time
+     * const timeBasedState = await ownerStateClient.loadTimeBased(Date.now());
+     * ```
+     */
+    createLoadOwnerStateAggregateClient(options?: QueryClientOptions): LoadOwnerStateAggregateClient<S>;
+    /**
+     * Creates an event stream query client for querying domain event streams.
+     *
+     * This method merges the provided options with the factory's default options,
+     * then creates API metadata and instantiates an EventStreamQueryClient.
+     *
+     * @param options - The query client options used to configure the event stream query client
+     * @returns A new instance of EventStreamQueryClient
+     *
+     * @example
+     * ```typescript
+     * const eventClient = factory.createEventStreamQueryClient({
+     *   aggregateName: 'cart',
+     * });
+     *
+     * const events = await eventClient.list(listQuery());
+     * ```
+     */
+    createEventStreamQueryClient<EVENT_FIELDS extends string = string>(options?: QueryClientOptions): EventStreamQueryClient<DomainEventBody, EVENT_FIELDS>;
+    /**
+     * Creates a client that reads the aggregate's query capability
+     * descriptors (`{aggregate}/snapshot/schema`, `{aggregate}/event/schema`).
+     *
+     * Its base path is `basePath` when one is given, as for the other clients;
+     * otherwise `{contextAlias}/{aggregateName}` without the
+     * `resourceAttribution`: the schema routes have no tenant or owner segment.
+     *
+     * @param options - Overrides the factory's defaults, as for the other clients
+     * @returns A new instance of QueryDescriptorClient
+     *
+     * @example
+     * ```typescript
+     * const descriptors = factory.createQueryDescriptorClient();
+     * const snapshot = await descriptors.describeSnapshot();
+     * ```
+     */
+    createQueryDescriptorClient(options?: QueryClientOptions): QueryDescriptorClient;
+}

package/dist/client/query/factory.d.ts

@@ -0,0 +1,165 @@
+import { PartialBy } from '@ahoo-wang/fetcher';
+import { ApiMetadata } from '@ahoo-wang/fetcher-decorator';
+import { AggregateNameCapable, AliasBoundedContext } from '../../model/index.js';
+import { ResourceAttributionPathSpec } from '../routing.js';
+import { SnapshotQueryClient } from './snapshot/index.js';
+import { EventStreamQueryClient } from './event/index.js';
+import { LoadStateAggregateClient, LoadOwnerStateAggregateClient } from './state/index.js';
+import { QueryDescriptorClient } from './descriptor/index.js';
+/**
+ * Configuration options for query clients: the client's `ApiMetadata`
+ * (`fetcher`, `headers`, `urlParams`, …, with `basePath` optional), plus
+ * three keys only {@link QueryClientFactory} reads to build the base path:
+ * `contextAlias`, `resourceAttribution` and `aggregateName`.
+ *
+ * The base path is `basePath` when one is given, and then the three keys
+ * are not used. Otherwise it is
+ * `{contextAlias}{resourceAttribution}/{aggregateName}`, each part left out
+ * when absent. The three keys are not passed on to the client.
+ */
+export interface QueryClientOptions extends PartialBy<ApiMetadata, 'basePath'>, Partial<AliasBoundedContext>, Partial<AggregateNameCapable> {
+    contextAlias?: string;
+    resourceAttribution?: ResourceAttributionPathSpec;
+}
+/**
+ * Creates the query clients of one aggregate from shared defaults: its
+ * snapshot, event stream, load-state and query descriptor clients. Each `create*` call may
+ * override the defaults; see {@link QueryClientOptions} for how the base path
+ * is built. Generated code creates one factory per aggregate.
+ *
+ * @template S - The type of the aggregate state
+ * @template FIELDS - The field paths snapshot queries may name
+ * @template DomainEventBody - The type of the aggregate's event bodies
+ */
+export declare class QueryClientFactory<S, FIELDS extends string = string, DomainEventBody = unknown> {
+    private readonly defaultOptions;
+    /**
+     * Creates a new QueryClientFactory instance with the specified default options.
+     *
+     * @param defaultOptions - The default options to be used for all query clients created by this factory
+     *
+     * @example
+     * ```typescript
+     * import { QueryClientFactory, ResourceAttributionPathSpec } from '@ahoo-wang/wow-client';
+     *
+     * const factory = new QueryClientFactory({
+     *   contextAlias: 'example',
+     *   aggregateName: 'cart',
+     *   resourceAttribution: ResourceAttributionPathSpec.OWNER,
+     * });
+     * ```
+     */
+    constructor(defaultOptions: QueryClientOptions);
+    /**
+     * Creates a snapshot query client for querying aggregate snapshots.
+     *
+     * This method merges the provided options with the factory's default options,
+     * then creates API metadata and instantiates a SnapshotQueryClient.
+     *
+     * @param options - The query client options used to configure the snapshot query client
+     * @returns A new instance of SnapshotQueryClient
+     *
+     * @example
+     * ```typescript
+     * const snapshotClient = factory.createSnapshotQueryClient({
+     *   aggregateName: 'cart',
+     * });
+     *
+     * const cartState = await snapshotClient.singleState(singleQuery());
+     * ```
+     */
+    createSnapshotQueryClient(options?: QueryClientOptions): SnapshotQueryClient<S, FIELDS>;
+    /**
+     * Creates a client for loading aggregate state by ID.
+     *
+     * This method merges the provided options with the factory's default options,
+     * then creates API metadata and instantiates a LoadStateAggregateClient.
+     * The client supports loading current state, versioned state, and time-based state.
+     *
+     * @param options - The query client options used to configure the state aggregate client
+     * @returns A new instance of LoadStateAggregateClient
+     *
+     * @example
+     * ```typescript
+     * const stateClient = factory.createLoadStateAggregateClient({
+     *   aggregateName: 'cart',
+     * });
+     *
+     * // Load current state
+     * const currentState = await stateClient.load('cart-123');
+     *
+     * // Load specific version
+     * const versionedState = await stateClient.loadVersioned('cart-123', 5);
+     *
+     * // Load state at specific time
+     * const timeBasedState = await stateClient.loadTimeBased('cart-123', Date.now());
+     * ```
+     */
+    createLoadStateAggregateClient(options?: QueryClientOptions): LoadStateAggregateClient<S>;
+    /**
+     * Creates a client for loading owner-specific aggregate state.
+     *
+     * This method merges the provided options with the factory's default options,
+     * then creates API metadata and instantiates a LoadOwnerStateAggregateClient.
+     * Unlike the standard state client, this client loads state for the current owner
+     * without requiring an explicit ID parameter.
+     *
+     * @param options - The query client options used to configure the owner state aggregate client
+     * @returns A new instance of LoadOwnerStateAggregateClient
+     *
+     * @example
+     * ```typescript
+     * const ownerStateClient = factory.createLoadOwnerStateAggregateClient({
+     *   aggregateName: 'cart',
+     *   resourceAttribution: ResourceAttributionPathSpec.OWNER,
+     * });
+     *
+     * // Load current owner's state
+     * const currentState = await ownerStateClient.load();
+     *
+     * // Load specific version of owner's state
+     * const versionedState = await ownerStateClient.loadVersioned(5);
+     *
+     * // Load owner's state at specific time
+     * const timeBasedState = await ownerStateClient.loadTimeBased(Date.now());
+     * ```
+     */
+    createLoadOwnerStateAggregateClient(options?: QueryClientOptions): LoadOwnerStateAggregateClient<S>;
+    /**
+     * Creates an event stream query client for querying domain event streams.
+     *
+     * This method merges the provided options with the factory's default options,
+     * then creates API metadata and instantiates an EventStreamQueryClient.
+     *
+     * @param options - The query client options used to configure the event stream query client
+     * @returns A new instance of EventStreamQueryClient
+     *
+     * @example
+     * ```typescript
+     * const eventClient = factory.createEventStreamQueryClient({
+     *   aggregateName: 'cart',
+     * });
+     *
+     * const events = await eventClient.list(listQuery());
+     * ```
+     */
+    createEventStreamQueryClient<EVENT_FIELDS extends string = string>(options?: QueryClientOptions): EventStreamQueryClient<DomainEventBody, EVENT_FIELDS>;
+    /**
+     * Creates a client that reads the aggregate's query capability
+     * descriptors (`{aggregate}/snapshot/schema`, `{aggregate}/event/schema`).
+     *
+     * Its base path is `basePath` when one is given, as for the other clients;
+     * otherwise `{contextAlias}/{aggregateName}` without the
+     * `resourceAttribution`: the schema routes have no tenant or owner segment.
+     *
+     * @param options - Overrides the factory's defaults, as for the other clients
+     * @returns A new instance of QueryDescriptorClient
+     *
+     * @example
+     * ```typescript
+     * const descriptors = factory.createQueryDescriptorClient();
+     * const snapshot = await descriptors.describeSnapshot();
+     * ```
+     */
+    createQueryDescriptorClient(options?: QueryClientOptions): QueryDescriptorClient;
+}

package/dist/client/query/factory.es.js

@@ -0,0 +1,45 @@
+import { EventStreamQueryClient as e } from "./event/eventStreamQueryClient.es.js";
+import { SnapshotQueryClient as t } from "./snapshot/snapshotQueryClient.es.js";
+import { LoadStateAggregateClient as n } from "./state/loadStateAggregateClient.es.js";
+import { LoadOwnerStateAggregateClient as r } from "./state/loadOwnerStateAggregateClient.es.js";
+import { QueryDescriptorClient as i } from "./descriptor/queryDescriptorClient.es.js";
+import { combineURLs as a } from "@ahoo-wang/fetcher";
+//#region src/client/query/factory.ts
+function o(e, t, n = !0) {
+	let { contextAlias: r, resourceAttribution: i, aggregateName: a, ...o } = {
+		...e,
+		...t
+	};
+	return {
+		...o,
+		basePath: t?.basePath ?? e.basePath ?? s(r, n ? i : void 0, a)
+	};
+}
+function s(e, t, n) {
+	let r = a(t ?? "", n ?? "");
+	return e ? a(e, r) : r;
+}
+var c = class {
+	constructor(e) {
+		this.defaultOptions = e;
+	}
+	createSnapshotQueryClient(e) {
+		return new t(o(this.defaultOptions, e));
+	}
+	createLoadStateAggregateClient(e) {
+		return new n(o(this.defaultOptions, e));
+	}
+	createLoadOwnerStateAggregateClient(e) {
+		return new r(o(this.defaultOptions, e));
+	}
+	createEventStreamQueryClient(t) {
+		return new e(o(this.defaultOptions, t));
+	}
+	createQueryDescriptorClient(e) {
+		return new i(o(this.defaultOptions, e, !1));
+	}
+};
+//#endregion
+export { c as QueryClientFactory };
+
+//# sourceMappingURL=factory.es.js.map

package/dist/client/query/factory.es.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.es.js","names":["queryApiMetadata","apiMetadata","defaults","options","routePath","contextAlias","attributed","resourceAttribution","aggregateName","path","combineURLs","QueryClientFactory","defaultOptions","SnapshotQueryClient","LoadStateAggregateClient","LoadOwnerStateAggregateClient","EventStreamQueryClient","QueryDescriptorClient"],"sources":["../../../src/client/query/factory.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 { PartialBy } from '@ahoo-wang/fetcher';\nimport { combineURLs } from '@ahoo-wang/fetcher';\nimport type { ApiMetadata } from '@ahoo-wang/fetcher-decorator';\nimport type {\n  AggregateNameCapable,\n  AliasBoundedContext,\n} from '../../model/index.js';\nimport type { ResourceAttributionPathSpec } from '../routing.js';\nimport { SnapshotQueryClient } from './snapshot/index.js';\nimport { EventStreamQueryClient } from './event/index.js';\nimport { LoadStateAggregateClient } from './state/index.js';\nimport { LoadOwnerStateAggregateClient } from './state/index.js';\nimport { QueryDescriptorClient } from './descriptor/index.js';\n\n/**\n * Configuration options for query clients: the client's `ApiMetadata`\n * (`fetcher`, `headers`, `urlParams`, …, with `basePath` optional), plus\n * three keys only {@link QueryClientFactory} reads to build the base path:\n * `contextAlias`, `resourceAttribution` and `aggregateName`.\n *\n * The base path is `basePath` when one is given, and then the three keys\n * are not used. Otherwise it is\n * `{contextAlias}{resourceAttribution}/{aggregateName}`, each part left out\n * when absent. The three keys are not passed on to the client.\n */\nexport interface QueryClientOptions\n  extends\n    PartialBy<ApiMetadata, 'basePath'>,\n    Partial<AliasBoundedContext>,\n    Partial<AggregateNameCapable> {\n  contextAlias?: string;\n  resourceAttribution?: ResourceAttributionPathSpec;\n}\n\n/**\n * The `ApiMetadata` a factory gives a client: `options` over the factory's\n * `defaults`, the base path resolved, and the keys only the factory reads\n * left out. `attributed: false` leaves the resource attribution out of the\n * base path, for routes that have no tenant or owner segment.\n */\nfunction queryApiMetadata(\n  defaults: QueryClientOptions,\n  options?: QueryClientOptions,\n  attributed = true,\n): ApiMetadata {\n  const { contextAlias, resourceAttribution, aggregateName, ...apiMetadata } = {\n    ...defaults,\n    ...options,\n  };\n  return {\n    ...apiMetadata,\n    basePath:\n      options?.basePath ??\n      defaults.basePath ??\n      routePath(\n        contextAlias,\n        attributed ? resourceAttribution : undefined,\n        aggregateName,\n      ),\n  };\n}\n\n/** `{contextAlias}{resourceAttribution}/{aggregateName}`. */\nfunction routePath(\n  contextAlias: string | undefined,\n  resourceAttribution: ResourceAttributionPathSpec | undefined,\n  aggregateName: string | undefined,\n): string {\n  const path = combineURLs(resourceAttribution ?? '', aggregateName ?? '');\n  return contextAlias ? combineURLs(contextAlias, path) : path;\n}\n\n/**\n * Creates the query clients of one aggregate from shared defaults: its\n * snapshot, event stream, load-state and query descriptor clients. Each `create*` call may\n * override the defaults; see {@link QueryClientOptions} for how the base path\n * is built. Generated code creates one factory per aggregate.\n *\n * @template S - The type of the aggregate state\n * @template FIELDS - The field paths snapshot queries may name\n * @template DomainEventBody - The type of the aggregate's event bodies\n */\nexport class QueryClientFactory<\n  S,\n  FIELDS extends string = string,\n  DomainEventBody = unknown,\n> {\n  /**\n   * Creates a new QueryClientFactory instance with the specified default options.\n   *\n   * @param defaultOptions - The default options to be used for all query clients created by this factory\n   *\n   * @example\n   * ```typescript\n   * import { QueryClientFactory, ResourceAttributionPathSpec } from '@ahoo-wang/wow-client';\n   *\n   * const factory = new QueryClientFactory({\n   *   contextAlias: 'example',\n   *   aggregateName: 'cart',\n   *   resourceAttribution: ResourceAttributionPathSpec.OWNER,\n   * });\n   * ```\n   */\n  constructor(private readonly defaultOptions: QueryClientOptions) {}\n\n  /**\n   * Creates a snapshot query client for querying aggregate snapshots.\n   *\n   * This method merges the provided options with the factory's default options,\n   * then creates API metadata and instantiates a SnapshotQueryClient.\n   *\n   * @param options - The query client options used to configure the snapshot query client\n   * @returns A new instance of SnapshotQueryClient\n   *\n   * @example\n   * ```typescript\n   * const snapshotClient = factory.createSnapshotQueryClient({\n   *   aggregateName: 'cart',\n   * });\n   *\n   * const cartState = await snapshotClient.singleState(singleQuery());\n   * ```\n   */\n  createSnapshotQueryClient(\n    options?: QueryClientOptions,\n  ): SnapshotQueryClient<S, FIELDS> {\n    return new SnapshotQueryClient(\n      queryApiMetadata(this.defaultOptions, options),\n    );\n  }\n\n  /**\n   * Creates a client for loading aggregate state by ID.\n   *\n   * This method merges the provided options with the factory's default options,\n   * then creates API metadata and instantiates a LoadStateAggregateClient.\n   * The client supports loading current state, versioned state, and time-based state.\n   *\n   * @param options - The query client options used to configure the state aggregate client\n   * @returns A new instance of LoadStateAggregateClient\n   *\n   * @example\n   * ```typescript\n   * const stateClient = factory.createLoadStateAggregateClient({\n   *   aggregateName: 'cart',\n   * });\n   *\n   * // Load current state\n   * const currentState = await stateClient.load('cart-123');\n   *\n   * // Load specific version\n   * const versionedState = await stateClient.loadVersioned('cart-123', 5);\n   *\n   * // Load state at specific time\n   * const timeBasedState = await stateClient.loadTimeBased('cart-123', Date.now());\n   * ```\n   */\n  createLoadStateAggregateClient(\n    options?: QueryClientOptions,\n  ): LoadStateAggregateClient<S> {\n    return new LoadStateAggregateClient(\n      queryApiMetadata(this.defaultOptions, options),\n    );\n  }\n\n  /**\n   * Creates a client for loading owner-specific aggregate state.\n   *\n   * This method merges the provided options with the factory's default options,\n   * then creates API metadata and instantiates a LoadOwnerStateAggregateClient.\n   * Unlike the standard state client, this client loads state for the current owner\n   * without requiring an explicit ID parameter.\n   *\n   * @param options - The query client options used to configure the owner state aggregate client\n   * @returns A new instance of LoadOwnerStateAggregateClient\n   *\n   * @example\n   * ```typescript\n   * const ownerStateClient = factory.createLoadOwnerStateAggregateClient({\n   *   aggregateName: 'cart',\n   *   resourceAttribution: ResourceAttributionPathSpec.OWNER,\n   * });\n   *\n   * // Load current owner's state\n   * const currentState = await ownerStateClient.load();\n   *\n   * // Load specific version of owner's state\n   * const versionedState = await ownerStateClient.loadVersioned(5);\n   *\n   * // Load owner's state at specific time\n   * const timeBasedState = await ownerStateClient.loadTimeBased(Date.now());\n   * ```\n   */\n  createLoadOwnerStateAggregateClient(\n    options?: QueryClientOptions,\n  ): LoadOwnerStateAggregateClient<S> {\n    return new LoadOwnerStateAggregateClient(\n      queryApiMetadata(this.defaultOptions, options),\n    );\n  }\n\n  /**\n   * Creates an event stream query client for querying domain event streams.\n   *\n   * This method merges the provided options with the factory's default options,\n   * then creates API metadata and instantiates an EventStreamQueryClient.\n   *\n   * @param options - The query client options used to configure the event stream query client\n   * @returns A new instance of EventStreamQueryClient\n   *\n   * @example\n   * ```typescript\n   * const eventClient = factory.createEventStreamQueryClient({\n   *   aggregateName: 'cart',\n   * });\n   *\n   * const events = await eventClient.list(listQuery());\n   * ```\n   */\n  createEventStreamQueryClient<EVENT_FIELDS extends string = string>(\n    options?: QueryClientOptions,\n  ): EventStreamQueryClient<DomainEventBody, EVENT_FIELDS> {\n    return new EventStreamQueryClient(\n      queryApiMetadata(this.defaultOptions, options),\n    );\n  }\n\n  /**\n   * Creates a client that reads the aggregate's query capability\n   * descriptors (`{aggregate}/snapshot/schema`, `{aggregate}/event/schema`).\n   *\n   * Its base path is `basePath` when one is given, as for the other clients;\n   * otherwise `{contextAlias}/{aggregateName}` without the\n   * `resourceAttribution`: the schema routes have no tenant or owner segment.\n   *\n   * @param options - Overrides the factory's defaults, as for the other clients\n   * @returns A new instance of QueryDescriptorClient\n   *\n   * @example\n   * ```typescript\n   * const descriptors = factory.createQueryDescriptorClient();\n   * const snapshot = await descriptors.describeSnapshot();\n   * ```\n   */\n  createQueryDescriptorClient(\n    options?: QueryClientOptions,\n  ): QueryDescriptorClient {\n    return new QueryDescriptorClient(\n      queryApiMetadata(this.defaultOptions, options, false),\n    );\n  }\n}\n"],"mappings":";;;;;;;AAqDA,SAASA,EACP,GACA,GACA,IAAa,IACA;CACb,IAAM,EAAE,iBAAc,wBAAqB,kBAAe,GAAGC,MAAgB;EAC3E,GAAGC;EACH,GAAGC;CACL;CACA,OAAO;EACL,GAAGF;EACH,UACEE,GAAS,YACTD,EAAS,YACTE,EACEC,GACAC,IAAaC,IAAsB,KAAA,GACnCC,CACF;CACJ;AACF;AAGA,SAASJ,EACP,GACA,GACA,GACQ;CACR,IAAMK,IAAOC,EAAYH,KAAuB,IAAIC,KAAiB,EAAE;CACvE,OAAOH,IAAeK,EAAYL,GAAcI,CAAI,IAAIA;AAC1D;AAYA,IAAaE,IAAb,MAIE;CAiBA,YAAY,GAAqD;EAApC,KAAA,iBAAAC;CAAqC;CAoBlE,0BACE,GACgC;EAChC,OAAO,IAAIC,EACTb,EAAiB,KAAK,gBAAgBG,CAAO,CAC/C;CACF;CA4BA,+BACE,GAC6B;EAC7B,OAAO,IAAIW,EACTd,EAAiB,KAAK,gBAAgBG,CAAO,CAC/C;CACF;CA8BA,oCACE,GACkC;EAClC,OAAO,IAAIY,EACTf,EAAiB,KAAK,gBAAgBG,CAAO,CAC/C;CACF;CAoBA,6BACE,GACuD;EACvD,OAAO,IAAIa,EACThB,EAAiB,KAAK,gBAAgBG,CAAO,CAC/C;CACF;CAmBA,4BACE,GACuB;EACvB,OAAO,IAAIc,EACTjB,EAAiB,KAAK,gBAAgBG,GAAS,EAAK,CACtD;CACF;AACF"}

package/dist/client/query/index.d.cts

@@ -0,0 +1,6 @@
+export * from './queryApi.cjs';
+export * from './event/index.cjs';
+export * from './snapshot/index.cjs';
+export * from './state/index.cjs';
+export * from './descriptor/index.cjs';
+export * from './factory.cjs';

package/dist/client/query/index.d.ts

@@ -0,0 +1,6 @@
+export * from './queryApi.js';
+export * from './event/index.js';
+export * from './snapshot/index.js';
+export * from './state/index.js';
+export * from './descriptor/index.js';
+export * from './factory.js';

package/dist/client/query/queryApi.d.cts

@@ -0,0 +1,68 @@
+import { Condition, ListQueryRequest, PagedQueryRequest, SingleQueryRequest } from './requests.cjs';
+import { PagedList } from '../../dsl/queryable.cjs';
+import { AggregationQuery } from '../../dsl/aggregation/index.cjs';
+import { FilterExpression } from '../../dsl/filter/index.cjs';
+import { DynamicDocument } from '../../dsl/documents.cjs';
+import { CursorPage, CursorQuery } from '../../dsl/cursorQuery.cjs';
+/**
+ * Interface for generic query API operations.
+ * Provides methods for querying resources in different ways including single item retrieval,
+ * list retrieval, streaming lists, paged retrieval, and counting.
+ *
+ * @see {@link EventStreamQueryApi}
+ * @see {@link SnapshotQueryApi}
+ * @template R - The type of resource being queried
+ */
+export interface QueryApi<R, FIELDS extends string = string> {
+    /** Retrieves the next forward-only cursor page. */
+    cursor<T extends Partial<R> = R>(query: CursorQuery<FIELDS>, attributes?: Record<string, unknown>, abort?: AbortController | AbortSignal): Promise<CursorPage<T>>;
+    /** Runs an aggregation and returns all result rows. */
+    aggregate<Row extends object = DynamicDocument, AGGREGATION_FIELDS extends string = string>(query: AggregationQuery<FIELDS, AGGREGATION_FIELDS>, attributes?: Record<string, unknown>, abort?: AbortController | AbortSignal): Promise<Row[]>;
+    /** Runs an aggregation and streams the result rows, one per server-sent event. */
+    aggregateStream<Row extends object = DynamicDocument, AGGREGATION_FIELDS extends string = string>(query: AggregationQuery<FIELDS, AGGREGATION_FIELDS>, attributes?: Record<string, unknown>, abort?: AbortController | AbortSignal): Promise<ReadableStream<Row>>;
+    /**
+     * Retrieves a single resource based on the provided query parameters.
+     * @param singleQuery - The query parameters for retrieving a single resource
+     * @param attributes - Optional shared attributes that can be accessed by interceptors
+     *                     throughout the request lifecycle. These attributes allow passing
+     *                     custom data between different interceptors.
+     * @returns A promise that resolves to a partial resource
+     */
+    single<T extends Partial<R> = R>(singleQuery: SingleQueryRequest<FIELDS>, attributes?: Record<string, unknown>, abort?: AbortController | AbortSignal): Promise<T>;
+    /**
+     * Retrieves a list of resources based on the provided query parameters.
+     * @param listQuery - The query parameters for listing resources
+     * @param attributes - Optional shared attributes that can be accessed by interceptors
+     *                     throughout the request lifecycle. These attributes allow passing
+     *                     custom data between different interceptors.
+     * @returns A promise that resolves to an array of partial resources
+     */
+    list<T extends Partial<R> = R>(listQuery: ListQueryRequest<FIELDS>, attributes?: Record<string, unknown>, abort?: AbortController | AbortSignal): Promise<T[]>;
+    /**
+     * Retrieves a stream of resources based on the provided query parameters.
+     * @param listQuery - The query parameters for listing resources
+     * @param attributes - Optional shared attributes that can be accessed by interceptors
+     *                     throughout the request lifecycle. These attributes allow passing
+     *                     custom data between different interceptors.
+     * @returns A promise that resolves to a readable stream of partial resources
+     */
+    listStream<T extends Partial<R> = R>(listQuery: ListQueryRequest<FIELDS>, attributes?: Record<string, unknown>, abort?: AbortController | AbortSignal): Promise<ReadableStream<T>>;
+    /**
+     * Retrieves a paged list of resources based on the provided query parameters.
+     * @param pagedQuery - The query parameters for paging resources
+     * @param attributes - Optional shared attributes that can be accessed by interceptors
+     *                     throughout the request lifecycle. These attributes allow passing
+     *                     custom data between different interceptors.
+     * @returns A promise that resolves to a paged list of partial resources
+     */
+    paged<T extends Partial<R> = R>(pagedQuery: PagedQueryRequest<FIELDS>, attributes?: Record<string, unknown>, abort?: AbortController | AbortSignal): Promise<PagedList<T>>;
+    /**
+     * Counts the number of resources that match the given filter or legacy condition.
+     * @param filter - The filter expression or legacy condition
+     * @param attributes - Optional shared attributes that can be accessed by interceptors
+     *                     throughout the request lifecycle. These attributes allow passing
+     *                     custom data between different interceptors.
+     * @returns A promise that resolves to the count of matching resources
+     */
+    count(filter: FilterExpression<FIELDS> | Condition<FIELDS>, attributes?: Record<string, unknown>, abort?: AbortController | AbortSignal): Promise<number>;
+}