@ahoo-wang/wow-client 10.0.0-alpha.5 → 10.0.0-alpha.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (198) hide show
  1. package/README.md +76 -23
  2. package/README.zh-CN.md +66 -19
  3. package/dist/commands.cjs +1 -1
  4. package/dist/commands.cjs.map +1 -1
  5. package/dist/commands.d.cts +131 -61
  6. package/dist/commands.d.ts +131 -61
  7. package/dist/commands.es.js +117 -59
  8. package/dist/commands.es.js.map +1 -1
  9. package/dist/developmentCaller.cjs +2 -0
  10. package/dist/developmentCaller.cjs.map +1 -0
  11. package/dist/developmentCaller.d.cts +61 -0
  12. package/dist/developmentCaller.d.ts +61 -0
  13. package/dist/developmentCaller.es.js +26 -0
  14. package/dist/developmentCaller.es.js.map +1 -0
  15. package/dist/dsl/aggregation/admit.cjs +1 -1
  16. package/dist/dsl/aggregation/admit.cjs.map +1 -1
  17. package/dist/dsl/aggregation/admit.es.js +93 -93
  18. package/dist/dsl/aggregation/admit.es.js.map +1 -1
  19. package/dist/dsl/aggregation/builders.cjs +1 -1
  20. package/dist/dsl/aggregation/builders.cjs.map +1 -1
  21. package/dist/dsl/aggregation/builders.d.cts +20 -20
  22. package/dist/dsl/aggregation/builders.d.ts +20 -20
  23. package/dist/dsl/aggregation/builders.es.js +88 -88
  24. package/dist/dsl/aggregation/builders.es.js.map +1 -1
  25. package/dist/dsl/aggregation/derived.cjs.map +1 -1
  26. package/dist/dsl/aggregation/derived.d.cts +8 -8
  27. package/dist/dsl/aggregation/derived.d.ts +8 -8
  28. package/dist/dsl/aggregation/derived.es.js +1 -2
  29. package/dist/dsl/aggregation/derived.es.js.map +1 -1
  30. package/dist/dsl/aggregation/expressionTrees.cjs.map +1 -1
  31. package/dist/dsl/aggregation/expressionTrees.es.js +1 -2
  32. package/dist/dsl/aggregation/having.cjs +1 -1
  33. package/dist/dsl/aggregation/having.cjs.map +1 -1
  34. package/dist/dsl/aggregation/having.d.cts +12 -12
  35. package/dist/dsl/aggregation/having.d.ts +12 -12
  36. package/dist/dsl/aggregation/having.es.js +33 -33
  37. package/dist/dsl/aggregation/having.es.js.map +1 -1
  38. package/dist/dsl/aggregation/sort.cjs.map +1 -1
  39. package/dist/dsl/aggregation/sort.es.js +1 -2
  40. package/dist/dsl/aggregation/types.cjs +1 -1
  41. package/dist/dsl/aggregation/types.cjs.map +1 -1
  42. package/dist/dsl/aggregation/types.d.cts +69 -69
  43. package/dist/dsl/aggregation/types.d.ts +69 -69
  44. package/dist/dsl/aggregation/types.es.js +15 -16
  45. package/dist/dsl/aggregation/types.es.js.map +1 -1
  46. package/dist/dsl/constantName.cjs +2 -0
  47. package/dist/dsl/constantName.cjs.map +1 -0
  48. package/dist/dsl/constantName.d.cts +9 -0
  49. package/dist/dsl/constantName.d.ts +9 -0
  50. package/dist/dsl/constantName.es.js +7 -0
  51. package/dist/dsl/constantName.es.js.map +1 -0
  52. package/dist/dsl/cursorQuery.cjs.map +1 -1
  53. package/dist/dsl/cursorQuery.es.js +1 -2
  54. package/dist/dsl/deletionState.cjs +1 -1
  55. package/dist/dsl/deletionState.cjs.map +1 -1
  56. package/dist/dsl/deletionState.d.cts +3 -3
  57. package/dist/dsl/deletionState.d.ts +3 -3
  58. package/dist/dsl/deletionState.es.js +2 -3
  59. package/dist/dsl/deletionState.es.js.map +1 -1
  60. package/dist/dsl/descriptor.cjs +1 -1
  61. package/dist/dsl/descriptor.cjs.map +1 -1
  62. package/dist/dsl/descriptor.d.cts +92 -42
  63. package/dist/dsl/descriptor.d.ts +92 -42
  64. package/dist/dsl/descriptor.es.js +36 -29
  65. package/dist/dsl/descriptor.es.js.map +1 -1
  66. package/dist/dsl/field.cjs.map +1 -1
  67. package/dist/dsl/field.es.js +1 -2
  68. package/dist/dsl/filter/builders.cjs +1 -1
  69. package/dist/dsl/filter/builders.cjs.map +1 -1
  70. package/dist/dsl/filter/builders.d.cts +53 -53
  71. package/dist/dsl/filter/builders.d.ts +53 -53
  72. package/dist/dsl/filter/builders.es.js +111 -111
  73. package/dist/dsl/filter/builders.es.js.map +1 -1
  74. package/dist/dsl/filter/datePattern.cjs.map +1 -1
  75. package/dist/dsl/filter/datePattern.es.js +1 -2
  76. package/dist/dsl/filter/operator.cjs +1 -1
  77. package/dist/dsl/filter/operator.cjs.map +1 -1
  78. package/dist/dsl/filter/operator.d.cts +57 -57
  79. package/dist/dsl/filter/operator.d.ts +57 -57
  80. package/dist/dsl/filter/operator.es.js +4 -5
  81. package/dist/dsl/filter/operator.es.js.map +1 -1
  82. package/dist/dsl/filter/scope.cjs +1 -1
  83. package/dist/dsl/filter/scope.cjs.map +1 -1
  84. package/dist/dsl/filter/scope.es.js +12 -12
  85. package/dist/dsl/filter/scope.es.js.map +1 -1
  86. package/dist/dsl/filter/validate.cjs +1 -1
  87. package/dist/dsl/filter/validate.cjs.map +1 -1
  88. package/dist/dsl/filter/validate.es.js +23 -23
  89. package/dist/dsl/filter/validate.es.js.map +1 -1
  90. package/dist/dsl/pagination.cjs.map +1 -1
  91. package/dist/dsl/pagination.es.js +1 -2
  92. package/dist/dsl/projection.cjs.map +1 -1
  93. package/dist/dsl/projection.d.cts +1 -1
  94. package/dist/dsl/projection.d.ts +1 -1
  95. package/dist/dsl/projection.es.js +1 -2
  96. package/dist/dsl/projection.es.js.map +1 -1
  97. package/dist/dsl/queryErrorCodes.cjs +1 -1
  98. package/dist/dsl/queryErrorCodes.cjs.map +1 -1
  99. package/dist/dsl/queryErrorCodes.d.cts +59 -48
  100. package/dist/dsl/queryErrorCodes.d.ts +59 -48
  101. package/dist/dsl/queryErrorCodes.es.js +51 -50
  102. package/dist/dsl/queryErrorCodes.es.js.map +1 -1
  103. package/dist/dsl/queryable.cjs +1 -1
  104. package/dist/dsl/queryable.cjs.map +1 -1
  105. package/dist/dsl/queryable.d.cts +25 -21
  106. package/dist/dsl/queryable.d.ts +25 -21
  107. package/dist/dsl/queryable.es.js +5 -5
  108. package/dist/dsl/queryable.es.js.map +1 -1
  109. package/dist/dsl/sort.cjs +1 -1
  110. package/dist/dsl/sort.cjs.map +1 -1
  111. package/dist/dsl/sort.d.cts +2 -2
  112. package/dist/dsl/sort.d.ts +2 -2
  113. package/dist/dsl/sort.es.js +4 -5
  114. package/dist/dsl/sort.es.js.map +1 -1
  115. package/dist/dsl.cjs +1 -1
  116. package/dist/dsl.es.js +3 -3
  117. package/dist/exactJson.cjs.map +1 -1
  118. package/dist/exactJson.d.cts +4 -4
  119. package/dist/exactJson.d.ts +4 -4
  120. package/dist/exactJson.es.js +1 -2
  121. package/dist/exactJson.es.js.map +1 -1
  122. package/dist/frameworkErrors.cjs +2 -0
  123. package/dist/frameworkErrors.cjs.map +1 -0
  124. package/dist/frameworkErrors.d.cts +121 -0
  125. package/dist/frameworkErrors.d.ts +121 -0
  126. package/dist/frameworkErrors.es.js +95 -0
  127. package/dist/frameworkErrors.es.js.map +1 -0
  128. package/dist/http.cjs +1 -1
  129. package/dist/http.cjs.map +1 -1
  130. package/dist/http.d.cts +4 -7
  131. package/dist/http.d.ts +4 -7
  132. package/dist/http.es.js +12 -20
  133. package/dist/http.es.js.map +1 -1
  134. package/dist/index.cjs +1 -1
  135. package/dist/index.d.cts +9 -7
  136. package/dist/index.d.ts +9 -7
  137. package/dist/index.es.js +11 -9
  138. package/dist/manifest.cjs +1 -1
  139. package/dist/manifest.cjs.map +1 -1
  140. package/dist/manifest.d.cts +33 -95
  141. package/dist/manifest.d.ts +33 -95
  142. package/dist/manifest.es.js +12 -7
  143. package/dist/manifest.es.js.map +1 -1
  144. package/dist/manifestTypes.d.cts +193 -0
  145. package/dist/manifestTypes.d.ts +193 -0
  146. package/dist/problem.cjs +1 -1
  147. package/dist/problem.cjs.map +1 -1
  148. package/dist/problem.d.cts +76 -111
  149. package/dist/problem.d.ts +76 -111
  150. package/dist/problem.es.js +45 -78
  151. package/dist/problem.es.js.map +1 -1
  152. package/dist/queries.cjs +1 -1
  153. package/dist/queries.cjs.map +1 -1
  154. package/dist/queries.d.cts +28 -51
  155. package/dist/queries.d.ts +28 -51
  156. package/dist/queries.es.js +49 -40
  157. package/dist/queries.es.js.map +1 -1
  158. package/dist/routes.cjs +2 -0
  159. package/dist/routes.cjs.map +1 -0
  160. package/dist/routes.d.cts +49 -0
  161. package/dist/routes.d.ts +49 -0
  162. package/dist/routes.es.js +33 -0
  163. package/dist/routes.es.js.map +1 -0
  164. package/dist/state.cjs +1 -1
  165. package/dist/state.cjs.map +1 -1
  166. package/dist/state.d.cts +56 -11
  167. package/dist/state.d.ts +56 -11
  168. package/dist/state.es.js +56 -21
  169. package/dist/state.es.js.map +1 -1
  170. package/dist/streams.cjs +1 -1
  171. package/dist/streams.cjs.map +1 -1
  172. package/dist/streams.d.cts +17 -13
  173. package/dist/streams.d.ts +17 -13
  174. package/dist/streams.es.js +50 -50
  175. package/dist/streams.es.js.map +1 -1
  176. package/dist/testing/wire.cjs +2 -0
  177. package/dist/testing/wire.cjs.map +1 -0
  178. package/dist/testing/wire.d.cts +29 -0
  179. package/dist/testing/wire.d.ts +29 -0
  180. package/dist/testing/wire.es.js +88 -0
  181. package/dist/testing/wire.es.js.map +1 -0
  182. package/dist/testing.cjs +1 -0
  183. package/dist/testing.d.cts +12 -0
  184. package/dist/testing.d.ts +12 -0
  185. package/dist/testing.es.js +3 -0
  186. package/dist/wait.cjs +1 -1
  187. package/dist/wait.cjs.map +1 -1
  188. package/dist/wait.d.cts +67 -18
  189. package/dist/wait.d.ts +67 -18
  190. package/dist/wait.es.js +59 -12
  191. package/dist/wait.es.js.map +1 -1
  192. package/dist/wire.cjs +1 -1
  193. package/dist/wire.cjs.map +1 -1
  194. package/dist/wire.d.cts +100 -50
  195. package/dist/wire.d.ts +100 -50
  196. package/dist/wire.es.js +17 -6
  197. package/dist/wire.es.js.map +1 -1
  198. package/package.json +26 -7
@@ -2,25 +2,18 @@ import { AggregationQuery } from './dsl/aggregation/index.cjs';
2
2
  import { CursorPage, CursorQuery } from './dsl/cursorQuery.cjs';
3
3
  import { Projected } from './dsl/projection.cjs';
4
4
  import { TextNumbers } from './exactJson.cjs';
5
- import { QueryModelDescriptor } from './dsl/descriptor.cjs';
5
+ import { DescriptorResult } from './dsl/descriptor.cjs';
6
6
  import { FilterCapable } from './dsl/filter/index.cjs';
7
- import { FilterListQuery, FilterPagedQuery, FilterSingleQuery } from './dsl/queryable.cjs';
7
+ import { FilterListQuery, FilterSingleQuery, PagedQuery, PagedList } from './dsl/queryable.cjs';
8
8
  import { RequestOptions, WowClientOptions } from './http.cjs';
9
- import { AggregateType, DatasetEntry, EventStreamField, EventStreamRecord, EventView, SnapshotRecord, SnapshotSystemField } from './wire.cjs';
10
- import { StreamedRow, StreamResumeOptions } from './streams.cjs';
9
+ import { AggregateType, DatasetEntry, EventStreamField, EventStream, CommittedEvent, Snapshot, SnapshotSystemField } from './wire.cjs';
10
+ import { Positioned, StreamResumeOptions } from './streams.cjs';
11
11
  /** How a list is streamed: the request's options, and how it resumes. */
12
- export interface ListStreamOptions extends RequestOptions {
12
+ export interface StreamOptions extends RequestOptions {
13
13
  /** How the stream resumes (decision D253); `false` never resumes it. */
14
14
  readonly resume?: StreamResumeOptions | false;
15
15
  }
16
- /** How a paged query counts its total (`TotalMode`, decision D150). */
17
- export type TotalMode = 'EXACT' | 'BOUNDED' | 'NONE';
18
- /** A paged query of a query route: a page, and how its total is counted. */
19
- export interface PagedQuery<FIELDS extends string = string> extends FilterPagedQuery<FIELDS> {
20
- /** `BOUNDED` (the server's default) counts up to the budget's limit. */
21
- total?: TotalMode;
22
- }
23
- /** A count of a query route (decision D150). */
16
+ /** A count of a query route. */
24
17
  export interface CountQuery<FIELDS extends string = string> extends FilterCapable<FIELDS> {
25
18
  /** The most matches to count; the budget's default when absent. */
26
19
  limit?: number;
@@ -30,31 +23,10 @@ export interface CountResult {
30
23
  readonly count: number;
31
24
  readonly exact: boolean;
32
25
  }
33
- /**
34
- * A page of a paged query: `total` is exact when `exact`, a lower bound
35
- * otherwise, and null for `TotalMode.NONE`.
36
- */
37
- export interface PagedResult<T> {
38
- readonly total: number | null;
39
- readonly exact: boolean;
40
- readonly list: readonly T[];
41
- }
42
- /**
43
- * A query model's capability descriptor and its version, the `ETag` of
44
- * `GET …/query`; `notModified` when the version given is still current.
45
- */
46
- export type DescriptorResult = {
47
- readonly notModified: false;
48
- readonly version?: string;
49
- readonly descriptor: QueryModelDescriptor;
50
- } | {
51
- readonly notModified: true;
52
- readonly version: string;
53
- };
54
26
  /**
55
27
  * Queries one query model of a Wow service: `POST {path}` with a body
56
28
  * whose `kind` names the operation, `GET {path}` for the capability
57
- * descriptor (decisions D127, D145). A query written with literal `include`
29
+ * descriptor. A query written with literal `include`
58
30
  * paths answers records narrowed to them ({@link Projected}, review R4-Q,
59
31
  * Q-14).
60
32
  *
@@ -87,25 +59,30 @@ export declare class QueryModelClient<R, FIELDS extends string = string> {
87
59
  * problem: see {@link StreamResumeOptions}. A `limit` counts every record
88
60
  * read, resumed or not.
89
61
  */
90
- listStream<const INCLUDE extends FIELDS>(query: Including<FilterListQuery<FIELDS>, INCLUDE>, options?: ListStreamOptions): Promise<ReadableStream<Projected<R, INCLUDE>>>;
91
- listStream(query: FilterListQuery<FIELDS>, options?: ListStreamOptions): Promise<ReadableStream<R>>;
62
+ stream<const INCLUDE extends FIELDS>(query: Including<FilterListQuery<FIELDS>, INCLUDE>, options?: StreamOptions): Promise<ReadableStream<Projected<R, INCLUDE>>>;
63
+ stream(query: FilterListQuery<FIELDS>, options?: StreamOptions): Promise<ReadableStream<R>>;
92
64
  /**
93
- * The records that match as {@link listStream} reads them, each with its
65
+ * The records that match as {@link stream} reads them, each with its
94
66
  * position: keep the last one read to resume the stream later
95
67
  * ({@link StreamResumeOptions.lastEventId}), on another page or after a
96
- * restart.
68
+ * restart. Kotlin's `RowQueries.stream` answers these rows (`Positioned`).
97
69
  */
98
- listStreamRows<const INCLUDE extends FIELDS>(query: Including<FilterListQuery<FIELDS>, INCLUDE>, options?: ListStreamOptions): Promise<ReadableStream<StreamedRow<Projected<R, INCLUDE>>>>;
99
- listStreamRows(query: FilterListQuery<FIELDS>, options?: ListStreamOptions): Promise<ReadableStream<StreamedRow<R>>>;
70
+ streamRows<const INCLUDE extends FIELDS>(query: Including<FilterListQuery<FIELDS>, INCLUDE>, options?: StreamOptions): Promise<ReadableStream<Positioned<Projected<R, INCLUDE>>>>;
71
+ streamRows(query: FilterListQuery<FIELDS>, options?: StreamOptions): Promise<ReadableStream<Positioned<R>>>;
100
72
  /** One page of the records that match, and their total. */
101
- paged<const INCLUDE extends FIELDS>(query: Including<PagedQuery<FIELDS>, INCLUDE>, options?: RequestOptions): Promise<PagedResult<Projected<R, INCLUDE>>>;
102
- paged(query: PagedQuery<FIELDS>, options?: RequestOptions): Promise<PagedResult<R>>;
73
+ paged<const INCLUDE extends FIELDS>(query: Including<PagedQuery<FIELDS>, INCLUDE>, options?: RequestOptions): Promise<PagedList<Projected<R, INCLUDE>>>;
74
+ paged(query: PagedQuery<FIELDS>, options?: RequestOptions): Promise<PagedList<R>>;
103
75
  /** One page of a forward-only cursor over the records that match. */
104
76
  cursor<const INCLUDE extends FIELDS>(query: Including<CursorQuery<FIELDS>, INCLUDE>, options?: RequestOptions): Promise<CursorPage<Projected<R, INCLUDE>>>;
105
77
  cursor(query: CursorQuery<FIELDS>, options?: RequestOptions): Promise<CursorPage<R>>;
106
- /** The first record that matches; rejects with 404 `wow.query.not-found` when none does. */
107
- single<const INCLUDE extends FIELDS>(query: Including<FilterSingleQuery<FIELDS>, INCLUDE>, options?: RequestOptions): Promise<Projected<R, INCLUDE>>;
108
- single(query: FilterSingleQuery<FIELDS>, options?: RequestOptions): Promise<R>;
78
+ /**
79
+ * The first record that matches, or `undefined` when none does: the
80
+ * service's 404 `wow.query.not-found`, as Kotlin's `QueryApi.single`
81
+ * answers `null`. Any other 404, of a dataset or a route that does not
82
+ * exist, still rejects.
83
+ */
84
+ single<const INCLUDE extends FIELDS>(query: Including<FilterSingleQuery<FIELDS>, INCLUDE>, options?: RequestOptions): Promise<Projected<R, INCLUDE> | undefined>;
85
+ single(query: FilterSingleQuery<FIELDS>, options?: RequestOptions): Promise<R | undefined>;
109
86
  /** How many records match, bounded by the count's limit. */
110
87
  count(query: CountQuery<FIELDS>, options?: RequestOptions): Promise<CountResult>;
111
88
  /** The groups and metrics of an aggregation, one row per group. */
@@ -129,13 +106,13 @@ export type Including<Q, INCLUDE extends string> = Q & {
129
106
  /** The query route of a model of an aggregate type. */
130
107
  export declare function queryPath(type: AggregateType, model: string): string;
131
108
  /**
132
- * Queries an aggregate type's snapshots (decision D128), the default read
109
+ * Queries an aggregate type's snapshots, the default read
133
110
  * model; only where the aggregate keeps them.
134
111
  *
135
112
  * @typeParam S - The state's type.
136
113
  * @typeParam STATE_FIELDS - The `state.*` paths of the state.
137
114
  */
138
- export declare class SnapshotQueryClient<S = unknown, STATE_FIELDS extends string = `state.${string}`> extends QueryModelClient<SnapshotRecord<S>, SnapshotSystemField | STATE_FIELDS> {
115
+ export declare class SnapshotQueryClient<S = unknown, STATE_FIELDS extends string = `state.${string}`> extends QueryModelClient<Snapshot<S>, SnapshotSystemField | STATE_FIELDS> {
139
116
  readonly type: AggregateType;
140
117
  /**
141
118
  * @param type - The aggregate type
@@ -144,7 +121,7 @@ export declare class SnapshotQueryClient<S = unknown, STATE_FIELDS extends strin
144
121
  constructor(type: AggregateType, client?: WowClientOptions);
145
122
  }
146
123
  /**
147
- * Queries an aggregate type's event streams (decision D235) on the same
124
+ * Queries an aggregate type's event streams on the same
148
125
  * engine as its snapshots: one record per commit, `count` counts commits, a
149
126
  * condition on an event is an `elementMatch` on `events`, and per-event
150
127
  * analytics expand `events` in an aggregation (`elements`). A filter need
@@ -153,7 +130,7 @@ export declare class SnapshotQueryClient<S = unknown, STATE_FIELDS extends strin
153
130
  *
154
131
  * @typeParam E - The events' type.
155
132
  */
156
- export declare class EventQueryClient<E extends EventView = EventView> extends QueryModelClient<EventStreamRecord<E>, EventStreamField> {
133
+ export declare class EventQueryClient<E extends CommittedEvent = CommittedEvent> extends QueryModelClient<EventStream<E>, EventStreamField> {
157
134
  readonly type: AggregateType;
158
135
  /**
159
136
  * @param type - The aggregate type
@@ -162,7 +139,7 @@ export declare class EventQueryClient<E extends EventView = EventView> extends Q
162
139
  constructor(type: AggregateType, client?: WowClientOptions);
163
140
  }
164
141
  /**
165
- * The datasets of a Wow service (decisions D75, D145): registered at run
142
+ * The datasets of a Wow service: registered at run
166
143
  * time, so not in the Manifest. Lists those the caller sees and queries
167
144
  * each as a snapshot model is queried.
168
145
  */
package/dist/queries.d.ts CHANGED
@@ -2,25 +2,18 @@ import { AggregationQuery } from './dsl/aggregation/index.js';
2
2
  import { CursorPage, CursorQuery } from './dsl/cursorQuery.js';
3
3
  import { Projected } from './dsl/projection.js';
4
4
  import { TextNumbers } from './exactJson.js';
5
- import { QueryModelDescriptor } from './dsl/descriptor.js';
5
+ import { DescriptorResult } from './dsl/descriptor.js';
6
6
  import { FilterCapable } from './dsl/filter/index.js';
7
- import { FilterListQuery, FilterPagedQuery, FilterSingleQuery } from './dsl/queryable.js';
7
+ import { FilterListQuery, FilterSingleQuery, PagedQuery, PagedList } from './dsl/queryable.js';
8
8
  import { RequestOptions, WowClientOptions } from './http.js';
9
- import { AggregateType, DatasetEntry, EventStreamField, EventStreamRecord, EventView, SnapshotRecord, SnapshotSystemField } from './wire.js';
10
- import { StreamedRow, StreamResumeOptions } from './streams.js';
9
+ import { AggregateType, DatasetEntry, EventStreamField, EventStream, CommittedEvent, Snapshot, SnapshotSystemField } from './wire.js';
10
+ import { Positioned, StreamResumeOptions } from './streams.js';
11
11
  /** How a list is streamed: the request's options, and how it resumes. */
12
- export interface ListStreamOptions extends RequestOptions {
12
+ export interface StreamOptions extends RequestOptions {
13
13
  /** How the stream resumes (decision D253); `false` never resumes it. */
14
14
  readonly resume?: StreamResumeOptions | false;
15
15
  }
16
- /** How a paged query counts its total (`TotalMode`, decision D150). */
17
- export type TotalMode = 'EXACT' | 'BOUNDED' | 'NONE';
18
- /** A paged query of a query route: a page, and how its total is counted. */
19
- export interface PagedQuery<FIELDS extends string = string> extends FilterPagedQuery<FIELDS> {
20
- /** `BOUNDED` (the server's default) counts up to the budget's limit. */
21
- total?: TotalMode;
22
- }
23
- /** A count of a query route (decision D150). */
16
+ /** A count of a query route. */
24
17
  export interface CountQuery<FIELDS extends string = string> extends FilterCapable<FIELDS> {
25
18
  /** The most matches to count; the budget's default when absent. */
26
19
  limit?: number;
@@ -30,31 +23,10 @@ export interface CountResult {
30
23
  readonly count: number;
31
24
  readonly exact: boolean;
32
25
  }
33
- /**
34
- * A page of a paged query: `total` is exact when `exact`, a lower bound
35
- * otherwise, and null for `TotalMode.NONE`.
36
- */
37
- export interface PagedResult<T> {
38
- readonly total: number | null;
39
- readonly exact: boolean;
40
- readonly list: readonly T[];
41
- }
42
- /**
43
- * A query model's capability descriptor and its version, the `ETag` of
44
- * `GET …/query`; `notModified` when the version given is still current.
45
- */
46
- export type DescriptorResult = {
47
- readonly notModified: false;
48
- readonly version?: string;
49
- readonly descriptor: QueryModelDescriptor;
50
- } | {
51
- readonly notModified: true;
52
- readonly version: string;
53
- };
54
26
  /**
55
27
  * Queries one query model of a Wow service: `POST {path}` with a body
56
28
  * whose `kind` names the operation, `GET {path}` for the capability
57
- * descriptor (decisions D127, D145). A query written with literal `include`
29
+ * descriptor. A query written with literal `include`
58
30
  * paths answers records narrowed to them ({@link Projected}, review R4-Q,
59
31
  * Q-14).
60
32
  *
@@ -87,25 +59,30 @@ export declare class QueryModelClient<R, FIELDS extends string = string> {
87
59
  * problem: see {@link StreamResumeOptions}. A `limit` counts every record
88
60
  * read, resumed or not.
89
61
  */
90
- listStream<const INCLUDE extends FIELDS>(query: Including<FilterListQuery<FIELDS>, INCLUDE>, options?: ListStreamOptions): Promise<ReadableStream<Projected<R, INCLUDE>>>;
91
- listStream(query: FilterListQuery<FIELDS>, options?: ListStreamOptions): Promise<ReadableStream<R>>;
62
+ stream<const INCLUDE extends FIELDS>(query: Including<FilterListQuery<FIELDS>, INCLUDE>, options?: StreamOptions): Promise<ReadableStream<Projected<R, INCLUDE>>>;
63
+ stream(query: FilterListQuery<FIELDS>, options?: StreamOptions): Promise<ReadableStream<R>>;
92
64
  /**
93
- * The records that match as {@link listStream} reads them, each with its
65
+ * The records that match as {@link stream} reads them, each with its
94
66
  * position: keep the last one read to resume the stream later
95
67
  * ({@link StreamResumeOptions.lastEventId}), on another page or after a
96
- * restart.
68
+ * restart. Kotlin's `RowQueries.stream` answers these rows (`Positioned`).
97
69
  */
98
- listStreamRows<const INCLUDE extends FIELDS>(query: Including<FilterListQuery<FIELDS>, INCLUDE>, options?: ListStreamOptions): Promise<ReadableStream<StreamedRow<Projected<R, INCLUDE>>>>;
99
- listStreamRows(query: FilterListQuery<FIELDS>, options?: ListStreamOptions): Promise<ReadableStream<StreamedRow<R>>>;
70
+ streamRows<const INCLUDE extends FIELDS>(query: Including<FilterListQuery<FIELDS>, INCLUDE>, options?: StreamOptions): Promise<ReadableStream<Positioned<Projected<R, INCLUDE>>>>;
71
+ streamRows(query: FilterListQuery<FIELDS>, options?: StreamOptions): Promise<ReadableStream<Positioned<R>>>;
100
72
  /** One page of the records that match, and their total. */
101
- paged<const INCLUDE extends FIELDS>(query: Including<PagedQuery<FIELDS>, INCLUDE>, options?: RequestOptions): Promise<PagedResult<Projected<R, INCLUDE>>>;
102
- paged(query: PagedQuery<FIELDS>, options?: RequestOptions): Promise<PagedResult<R>>;
73
+ paged<const INCLUDE extends FIELDS>(query: Including<PagedQuery<FIELDS>, INCLUDE>, options?: RequestOptions): Promise<PagedList<Projected<R, INCLUDE>>>;
74
+ paged(query: PagedQuery<FIELDS>, options?: RequestOptions): Promise<PagedList<R>>;
103
75
  /** One page of a forward-only cursor over the records that match. */
104
76
  cursor<const INCLUDE extends FIELDS>(query: Including<CursorQuery<FIELDS>, INCLUDE>, options?: RequestOptions): Promise<CursorPage<Projected<R, INCLUDE>>>;
105
77
  cursor(query: CursorQuery<FIELDS>, options?: RequestOptions): Promise<CursorPage<R>>;
106
- /** The first record that matches; rejects with 404 `wow.query.not-found` when none does. */
107
- single<const INCLUDE extends FIELDS>(query: Including<FilterSingleQuery<FIELDS>, INCLUDE>, options?: RequestOptions): Promise<Projected<R, INCLUDE>>;
108
- single(query: FilterSingleQuery<FIELDS>, options?: RequestOptions): Promise<R>;
78
+ /**
79
+ * The first record that matches, or `undefined` when none does: the
80
+ * service's 404 `wow.query.not-found`, as Kotlin's `QueryApi.single`
81
+ * answers `null`. Any other 404, of a dataset or a route that does not
82
+ * exist, still rejects.
83
+ */
84
+ single<const INCLUDE extends FIELDS>(query: Including<FilterSingleQuery<FIELDS>, INCLUDE>, options?: RequestOptions): Promise<Projected<R, INCLUDE> | undefined>;
85
+ single(query: FilterSingleQuery<FIELDS>, options?: RequestOptions): Promise<R | undefined>;
109
86
  /** How many records match, bounded by the count's limit. */
110
87
  count(query: CountQuery<FIELDS>, options?: RequestOptions): Promise<CountResult>;
111
88
  /** The groups and metrics of an aggregation, one row per group. */
@@ -129,13 +106,13 @@ export type Including<Q, INCLUDE extends string> = Q & {
129
106
  /** The query route of a model of an aggregate type. */
130
107
  export declare function queryPath(type: AggregateType, model: string): string;
131
108
  /**
132
- * Queries an aggregate type's snapshots (decision D128), the default read
109
+ * Queries an aggregate type's snapshots, the default read
133
110
  * model; only where the aggregate keeps them.
134
111
  *
135
112
  * @typeParam S - The state's type.
136
113
  * @typeParam STATE_FIELDS - The `state.*` paths of the state.
137
114
  */
138
- export declare class SnapshotQueryClient<S = unknown, STATE_FIELDS extends string = `state.${string}`> extends QueryModelClient<SnapshotRecord<S>, SnapshotSystemField | STATE_FIELDS> {
115
+ export declare class SnapshotQueryClient<S = unknown, STATE_FIELDS extends string = `state.${string}`> extends QueryModelClient<Snapshot<S>, SnapshotSystemField | STATE_FIELDS> {
139
116
  readonly type: AggregateType;
140
117
  /**
141
118
  * @param type - The aggregate type
@@ -144,7 +121,7 @@ export declare class SnapshotQueryClient<S = unknown, STATE_FIELDS extends strin
144
121
  constructor(type: AggregateType, client?: WowClientOptions);
145
122
  }
146
123
  /**
147
- * Queries an aggregate type's event streams (decision D235) on the same
124
+ * Queries an aggregate type's event streams on the same
148
125
  * engine as its snapshots: one record per commit, `count` counts commits, a
149
126
  * condition on an event is an `elementMatch` on `events`, and per-event
150
127
  * analytics expand `events` in an aggregation (`elements`). A filter need
@@ -153,7 +130,7 @@ export declare class SnapshotQueryClient<S = unknown, STATE_FIELDS extends strin
153
130
  *
154
131
  * @typeParam E - The events' type.
155
132
  */
156
- export declare class EventQueryClient<E extends EventView = EventView> extends QueryModelClient<EventStreamRecord<E>, EventStreamField> {
133
+ export declare class EventQueryClient<E extends CommittedEvent = CommittedEvent> extends QueryModelClient<EventStream<E>, EventStreamField> {
157
134
  readonly type: AggregateType;
158
135
  /**
159
136
  * @param type - The aggregate type
@@ -162,7 +139,7 @@ export declare class EventQueryClient<E extends EventView = EventView> extends Q
162
139
  constructor(type: AggregateType, client?: WowClientOptions);
163
140
  }
164
141
  /**
165
- * The datasets of a Wow service (decisions D75, D145): registered at run
142
+ * The datasets of a Wow service: registered at run
166
143
  * time, so not in the Manifest. Lists those the caller sees and queries
167
144
  * each as a snapshot model is queried.
168
145
  */
@@ -1,8 +1,10 @@
1
1
  import { eventNumbers as e } from "./exactJson.es.js";
2
- import { WowHeaders as t, entityTag as n, json as r, send as i } from "./http.es.js";
3
- import { resumableQueryRows as a } from "./streams.es.js";
4
- //#region src/queries.ts
5
- var o = class {
2
+ import { FrameworkErrorCodes as t } from "./frameworkErrors.es.js";
3
+ import { WowProblemError as n } from "./problem.es.js";
4
+ import { WowHeaders as r, entityTag as i, json as a, send as o } from "./http.es.js";
5
+ import { resumableQueryRows as s } from "./streams.es.js";
6
+ // src/queries.ts
7
+ var c = class {
6
8
  constructor(e, t = {}, n) {
7
9
  this.path = e, this.client = t, this.numbers = n;
8
10
  }
@@ -13,100 +15,107 @@ var o = class {
13
15
  return this.numbers === void 0 ? void 0 : { list: { "*": this.numbers } };
14
16
  }
15
17
  async list(e, t) {
16
- return r(await this.post("list", e, t), this.listNumbers);
18
+ return a(await this.post("list", e, t), this.listNumbers);
17
19
  }
18
- async listStream(e, t) {
19
- return (await this.listStreamRows(e, t)).pipeThrough(new TransformStream({ transform(e, t) {
20
- t.enqueue(e.record);
20
+ async stream(e, t) {
21
+ return (await this.streamRows(e, t)).pipeThrough(new TransformStream({ transform(e, t) {
22
+ t.enqueue(e.row);
21
23
  } }));
22
24
  }
23
- async listStreamRows(e, t = {}) {
24
- let n = t.resume === !1 ? { maxRetries: 0 } : t.resume, r = e.limit ?? 0, i = (n, i) => this.post("list", r > 0 ? {
25
+ async streamRows(e, t = {}) {
26
+ let n = t.resume === !1 ? { maxRetries: 0 } : t.resume, r = e.limit, i = (n, i) => this.post("list", r === void 0 ? e : {
25
27
  ...e,
26
28
  limit: r - i
27
- } : e, t, "text/event-stream", n), o = await i(n?.lastEventId, 0);
28
- return a(o, (e, t) => r > 0 && t >= r ? Promise.resolve(void 0) : i(e, t), {
29
+ }, t, "text/event-stream", n), a = await i(n?.lastEventId, 0);
30
+ return s(a, (e, t) => r !== void 0 && t >= r ? Promise.resolve(void 0) : i(e, t), {
29
31
  ...n,
30
32
  ...t.signal === void 0 ? {} : { signal: t.signal },
31
33
  ...this.numbers === void 0 ? {} : { numbers: this.numbers }
32
34
  });
33
35
  }
34
36
  async paged(e, t) {
35
- return r(await this.post("paged", e, t), this.pageNumbers);
37
+ return a(await this.post("paged", e, t), this.pageNumbers);
36
38
  }
37
39
  async cursor(e, t) {
38
- return r(await this.post("cursor", e, t), this.pageNumbers);
40
+ return a(await this.post("cursor", e, t), this.pageNumbers);
39
41
  }
40
42
  async single(e, t) {
41
- return r(await this.post("single", e, t), this.numbers);
43
+ try {
44
+ return a(await this.post("single", e, t), this.numbers);
45
+ } catch (e) {
46
+ if (l(e)) return;
47
+ throw e;
48
+ }
42
49
  }
43
50
  async count(e, t) {
44
- return r(await this.post("count", e, t));
51
+ return a(await this.post("count", e, t));
45
52
  }
46
53
  async aggregate(e, t) {
47
- return r(await this.post("aggregate", e, t));
54
+ return a(await this.post("aggregate", e, t));
48
55
  }
49
- async describe(e, a) {
50
- let o = await i(this.client, {
56
+ async describe(e, t) {
57
+ let n = await o(this.client, {
51
58
  method: "GET",
52
59
  path: this.path,
53
- headers: { [t.IF_NONE_MATCH]: e === void 0 ? void 0 : `"${e}"` },
54
- options: a,
60
+ headers: { [r.IF_NONE_MATCH]: e === void 0 ? void 0 : `"${e}"` },
61
+ options: t,
55
62
  notModified: !0
56
- }), s = n(o);
57
- return o.status === 304 ? {
63
+ }), s = i(n);
64
+ return n.status === 304 ? {
58
65
  notModified: !0,
59
66
  version: s ?? e ?? ""
60
67
  } : {
61
68
  notModified: !1,
62
69
  ...s === void 0 ? {} : { version: s },
63
- descriptor: await r(o)
70
+ descriptor: await a(n)
64
71
  };
65
72
  }
66
- post(e, n, r, a, o) {
67
- return i(this.client, {
73
+ post(e, t, n, i, a) {
74
+ return o(this.client, {
68
75
  method: "POST",
69
76
  path: this.path,
70
77
  headers: {
71
- Accept: a,
72
- [t.LAST_EVENT_ID]: o
78
+ Accept: i,
79
+ [r.LAST_EVENT_ID]: a
73
80
  },
74
81
  body: {
75
- ...n,
82
+ ...t,
76
83
  kind: e
77
84
  },
78
- options: r
85
+ options: n
79
86
  });
80
87
  }
81
88
  };
82
- function s(e, t) {
89
+ function l(e) {
90
+ return e instanceof n && e.status === 404 && (e.code === t.QUERY_NOT_FOUND || e.code === t.AGGREGATE_NOT_FOUND);
91
+ }
92
+ function u(e, t) {
83
93
  return `/${e.context}/${e.name}/${t}/query`;
84
94
  }
85
- var c = class extends o {
95
+ var d = class extends c {
86
96
  constructor(e, t) {
87
- super(s(e, "snapshot"), t, e.textNumbers?.state === void 0 ? void 0 : { state: e.textNumbers.state }), this.type = e;
97
+ super(u(e, "snapshot"), t, e.textNumbers?.state === void 0 ? void 0 : { state: e.textNumbers.state }), this.type = e;
88
98
  }
89
- }, l = class extends o {
99
+ }, f = class extends c {
90
100
  constructor(t, n) {
91
101
  let r = e(t);
92
- super(s(t, "events"), n, r === void 0 ? void 0 : { events: { "*": r } }), this.type = t;
102
+ super(u(t, "events"), n, r === void 0 ? void 0 : { events: { "*": r } }), this.type = t;
93
103
  }
94
- }, u = class {
104
+ }, p = class {
95
105
  constructor(e = {}) {
96
106
  this.client = e;
97
107
  }
98
108
  async list(e) {
99
- return r(await i(this.client, {
109
+ return a(await o(this.client, {
100
110
  method: "GET",
101
111
  path: "/wow/dataset",
102
112
  options: e
103
113
  }));
104
114
  }
105
115
  dataset(e, t) {
106
- return new o(`/wow/dataset/${encodeURIComponent(e)}/${encodeURIComponent(t)}/query`, this.client);
116
+ return new c(`/wow/dataset/${encodeURIComponent(e)}/${encodeURIComponent(t)}/query`, this.client);
107
117
  }
108
118
  };
109
- //#endregion
110
- export { u as DatasetClient, l as EventQueryClient, o as QueryModelClient, c as SnapshotQueryClient, s as queryPath };
119
+ export { p as DatasetClient, f as EventQueryClient, c as QueryModelClient, d as SnapshotQueryClient, u as queryPath };
111
120
 
112
121
  //# sourceMappingURL=queries.es.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"queries.es.js","names":["QueryModelClient","path","client","numbers","json","query","options","row","resume","limit","open","received","lastEventId","first","resumableQueryRows","response","send","WowHeaders","version","tag","entityTag","accept","queryPath","type","model","SnapshotQueryClient","EventQueryClient","events","eventNumbers","DatasetClient","context","dataset"],"sources":["../src/queries.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 { AggregationQuery } from './dsl/aggregation/index.js';\nimport type { CursorPage, CursorQuery } from './dsl/cursorQuery.js';\nimport type { Projected } from './dsl/projection.js';\nimport { eventNumbers, type TextNumbers } from './exactJson.js';\nimport type { QueryModelDescriptor } from './dsl/descriptor.js';\nimport type { FilterCapable } from './dsl/filter/index.js';\nimport type {\n FilterListQuery,\n FilterPagedQuery,\n FilterSingleQuery,\n} from './dsl/queryable.js';\nimport {\n entityTag,\n json,\n type RequestOptions,\n send,\n type WowClientOptions,\n WowHeaders,\n} from './http.js';\nimport type {\n AggregateType,\n DatasetEntry,\n EventStreamField,\n EventStreamRecord,\n EventView,\n SnapshotRecord,\n SnapshotSystemField,\n} from './wire.js';\nimport {\n resumableQueryRows,\n type StreamedRow,\n type StreamResumeOptions,\n} from './streams.js';\n\n/** How a list is streamed: the request's options, and how it resumes. */\nexport interface ListStreamOptions extends RequestOptions {\n /** How the stream resumes (decision D253); `false` never resumes it. */\n readonly resume?: StreamResumeOptions | false;\n}\n\n/** How a paged query counts its total (`TotalMode`, decision D150). */\nexport type TotalMode = 'EXACT' | 'BOUNDED' | 'NONE';\n\n/** A paged query of a query route: a page, and how its total is counted. */\nexport interface PagedQuery<\n FIELDS extends string = string,\n> extends FilterPagedQuery<FIELDS> {\n /** `BOUNDED` (the server's default) counts up to the budget's limit. */\n total?: TotalMode;\n}\n\n/** A count of a query route (decision D150). */\nexport interface CountQuery<\n FIELDS extends string = string,\n> extends FilterCapable<FIELDS> {\n /** The most matches to count; the budget's default when absent. */\n limit?: number;\n}\n\n/** What a count answers: exact below its limit, else the limit itself. */\nexport interface CountResult {\n readonly count: number;\n readonly exact: boolean;\n}\n\n/**\n * A page of a paged query: `total` is exact when `exact`, a lower bound\n * otherwise, and null for `TotalMode.NONE`.\n */\nexport interface PagedResult<T> {\n readonly total: number | null;\n readonly exact: boolean;\n readonly list: readonly T[];\n}\n\n/**\n * A query model's capability descriptor and its version, the `ETag` of\n * `GET …/query`; `notModified` when the version given is still current.\n */\nexport type DescriptorResult =\n | {\n readonly notModified: false;\n readonly version?: string;\n readonly descriptor: QueryModelDescriptor;\n }\n | { readonly notModified: true; readonly version: string };\n\n/**\n * Queries one query model of a Wow service: `POST {path}` with a body\n * whose `kind` names the operation, `GET {path}` for the capability\n * descriptor (decisions D127, D145). A query written with literal `include`\n * paths answers records narrowed to them ({@link Projected}, review R4-Q,\n * Q-14).\n *\n * @typeParam R - The record's type.\n * @typeParam FIELDS - The field paths a filter, sort or projection takes.\n */\nexport class QueryModelClient<R, FIELDS extends string = string> {\n /**\n * @param path - The query route, `/{context}/{aggregate}/{model}/query`\n * @param client - How the service is reached\n * @param numbers - The numbers of each record read as their exact text\n * (review R4-Q, Q-9)\n */\n constructor(\n readonly path: string,\n readonly client: WowClientOptions = {},\n readonly numbers?: TextNumbers,\n ) {}\n\n /** The marks of a list of records. */\n private get listNumbers(): TextNumbers | undefined {\n return this.numbers === undefined ? undefined : { '*': this.numbers };\n }\n\n /** The marks of a page of records. */\n private get pageNumbers(): TextNumbers | undefined {\n return this.numbers === undefined\n ? undefined\n : { list: { '*': this.numbers } };\n }\n\n /** The records that match, at most `limit` (the server's default when absent). */\n list<const INCLUDE extends FIELDS>(\n query: Including<FilterListQuery<FIELDS>, INCLUDE>,\n options?: RequestOptions,\n ): Promise<Projected<R, INCLUDE>[]>;\n list(query: FilterListQuery<FIELDS>, options?: RequestOptions): Promise<R[]>;\n async list(\n query: FilterListQuery<FIELDS>,\n options?: RequestOptions,\n ): Promise<unknown> {\n return json<R[]>(await this.post('list', query, options), this.listNumbers);\n }\n\n /**\n * The records that match, as server-sent events read one at a time; a\n * failure after the first record errors the stream with its problem. The\n * stream resumes where it stopped (decision D253) when the server ends it\n * to be resumed, when it is cut off and when it fails with a retryable\n * problem: see {@link StreamResumeOptions}. A `limit` counts every record\n * read, resumed or not.\n */\n listStream<const INCLUDE extends FIELDS>(\n query: Including<FilterListQuery<FIELDS>, INCLUDE>,\n options?: ListStreamOptions,\n ): Promise<ReadableStream<Projected<R, INCLUDE>>>;\n listStream(\n query: FilterListQuery<FIELDS>,\n options?: ListStreamOptions,\n ): Promise<ReadableStream<R>>;\n async listStream(\n query: FilterListQuery<FIELDS>,\n options?: ListStreamOptions,\n ): Promise<unknown> {\n return (await this.listStreamRows(query, options)).pipeThrough(\n new TransformStream<StreamedRow<R>, R>({\n transform(row, controller) {\n controller.enqueue(row.record);\n },\n }),\n );\n }\n\n /**\n * The records that match as {@link listStream} reads them, each with its\n * position: keep the last one read to resume the stream later\n * ({@link StreamResumeOptions.lastEventId}), on another page or after a\n * restart.\n */\n listStreamRows<const INCLUDE extends FIELDS>(\n query: Including<FilterListQuery<FIELDS>, INCLUDE>,\n options?: ListStreamOptions,\n ): Promise<ReadableStream<StreamedRow<Projected<R, INCLUDE>>>>;\n listStreamRows(\n query: FilterListQuery<FIELDS>,\n options?: ListStreamOptions,\n ): Promise<ReadableStream<StreamedRow<R>>>;\n async listStreamRows(\n query: FilterListQuery<FIELDS>,\n options: ListStreamOptions = {},\n ): Promise<ReadableStream<StreamedRow<R>>> {\n const resume =\n options.resume === false ? { maxRetries: 0 } : options.resume;\n const limit = query.limit ?? 0;\n const open = (lastEventId: string | undefined, received: number) => {\n return this.post(\n 'list',\n limit > 0 ? { ...query, limit: limit - received } : query,\n options,\n 'text/event-stream',\n lastEventId,\n );\n };\n const first = await open(resume?.lastEventId, 0);\n return resumableQueryRows<R>(\n first,\n (lastEventId, received) =>\n limit > 0 && received >= limit\n ? Promise.resolve(undefined)\n : open(lastEventId, received),\n {\n ...resume,\n ...(options.signal === undefined ? {} : { signal: options.signal }),\n ...(this.numbers === undefined ? {} : { numbers: this.numbers }),\n },\n );\n }\n\n /** One page of the records that match, and their total. */\n paged<const INCLUDE extends FIELDS>(\n query: Including<PagedQuery<FIELDS>, INCLUDE>,\n options?: RequestOptions,\n ): Promise<PagedResult<Projected<R, INCLUDE>>>;\n paged(\n query: PagedQuery<FIELDS>,\n options?: RequestOptions,\n ): Promise<PagedResult<R>>;\n async paged(\n query: PagedQuery<FIELDS>,\n options?: RequestOptions,\n ): Promise<unknown> {\n return json<PagedResult<R>>(\n await this.post('paged', query, options),\n this.pageNumbers,\n );\n }\n\n /** One page of a forward-only cursor over the records that match. */\n cursor<const INCLUDE extends FIELDS>(\n query: Including<CursorQuery<FIELDS>, INCLUDE>,\n options?: RequestOptions,\n ): Promise<CursorPage<Projected<R, INCLUDE>>>;\n cursor(\n query: CursorQuery<FIELDS>,\n options?: RequestOptions,\n ): Promise<CursorPage<R>>;\n async cursor(\n query: CursorQuery<FIELDS>,\n options?: RequestOptions,\n ): Promise<unknown> {\n return json<CursorPage<R>>(\n await this.post('cursor', query, options),\n this.pageNumbers,\n );\n }\n\n /** The first record that matches; rejects with 404 `wow.query.not-found` when none does. */\n single<const INCLUDE extends FIELDS>(\n query: Including<FilterSingleQuery<FIELDS>, INCLUDE>,\n options?: RequestOptions,\n ): Promise<Projected<R, INCLUDE>>;\n single(\n query: FilterSingleQuery<FIELDS>,\n options?: RequestOptions,\n ): Promise<R>;\n async single(\n query: FilterSingleQuery<FIELDS>,\n options?: RequestOptions,\n ): Promise<unknown> {\n return json<R>(await this.post('single', query, options), this.numbers);\n }\n\n /** How many records match, bounded by the count's limit. */\n async count(\n query: CountQuery<FIELDS>,\n options?: RequestOptions,\n ): Promise<CountResult> {\n return json<CountResult>(await this.post('count', query, options));\n }\n\n /** The groups and metrics of an aggregation, one row per group. */\n async aggregate<ROW = Record<string, unknown>>(\n query: AggregationQuery<FIELDS, string>,\n options?: RequestOptions,\n ): Promise<ROW[]> {\n return json<ROW[]>(await this.post('aggregate', query, options));\n }\n\n /**\n * The model's capability descriptor; with the `version` already held, a\n * 304 answers `notModified`.\n */\n async describe(\n version?: string,\n options?: RequestOptions,\n ): Promise<DescriptorResult> {\n const response = await send(this.client, {\n method: 'GET',\n path: this.path,\n headers: {\n [WowHeaders.IF_NONE_MATCH]:\n version === undefined ? undefined : `\"${version}\"`,\n },\n options,\n notModified: true,\n });\n const tag = entityTag(response);\n if (response.status === 304) {\n return { notModified: true, version: tag ?? version ?? '' };\n }\n return {\n notModified: false,\n ...(tag === undefined ? {} : { version: tag }),\n descriptor: await json<QueryModelDescriptor>(response),\n };\n }\n\n private post(\n kind: string,\n query: object,\n options?: RequestOptions,\n accept?: string,\n lastEventId?: string,\n ): Promise<Response> {\n return send(this.client, {\n method: 'POST',\n path: this.path,\n headers: { Accept: accept, [WowHeaders.LAST_EVENT_ID]: lastEventId },\n body: { ...query, kind },\n options,\n });\n }\n}\n\n/**\n * A query whose projection includes the literal paths `INCLUDE`: a query\n * client narrows its records to them ({@link Projected}).\n */\nexport type Including<Q, INCLUDE extends string> = Q & {\n readonly projection: { readonly include: readonly INCLUDE[] };\n};\n\n/** The query route of a model of an aggregate type. */\nexport function queryPath(type: AggregateType, model: string): string {\n return `/${type.context}/${type.name}/${model}/query`;\n}\n\n/**\n * Queries an aggregate type's snapshots (decision D128), the default read\n * model; only where the aggregate keeps them.\n *\n * @typeParam S - The state's type.\n * @typeParam STATE_FIELDS - The `state.*` paths of the state.\n */\nexport class SnapshotQueryClient<\n S = unknown,\n STATE_FIELDS extends string = `state.${string}`,\n> extends QueryModelClient<\n SnapshotRecord<S>,\n SnapshotSystemField | STATE_FIELDS\n> {\n /**\n * @param type - The aggregate type\n * @param client - How the service is reached\n */\n constructor(\n readonly type: AggregateType,\n client?: WowClientOptions,\n ) {\n super(\n queryPath(type, 'snapshot'),\n client,\n type.textNumbers?.state === undefined\n ? undefined\n : { state: type.textNumbers.state },\n );\n }\n}\n\n/**\n * Queries an aggregate type's event streams (decision D235) on the same\n * engine as its snapshots: one record per commit, `count` counts commits, a\n * condition on an event is an `elementMatch` on `events`, and per-event\n * analytics expand `events` in an aggregation (`elements`). A filter need\n * not name the aggregate, but one that does not reads the log the service\n * appends to: the budget bounds it.\n *\n * @typeParam E - The events' type.\n */\nexport class EventQueryClient<\n E extends EventView = EventView,\n> extends QueryModelClient<EventStreamRecord<E>, EventStreamField> {\n /**\n * @param type - The aggregate type\n * @param client - How the service is reached\n */\n constructor(\n readonly type: AggregateType,\n client?: WowClientOptions,\n ) {\n const events = eventNumbers(type);\n super(\n queryPath(type, 'events'),\n client,\n events === undefined ? undefined : { events: { '*': events } },\n );\n }\n}\n\n/**\n * The datasets of a Wow service (decisions D75, D145): registered at run\n * time, so not in the Manifest. Lists those the caller sees and queries\n * each as a snapshot model is queried.\n */\nexport class DatasetClient {\n /** @param client - How the service is reached */\n constructor(readonly client: WowClientOptions = {}) {}\n\n /** The datasets the caller sees, by name. */\n async list(options?: RequestOptions): Promise<DatasetEntry[]> {\n return json<DatasetEntry[]>(\n await send(this.client, { method: 'GET', path: '/wow/dataset', options }),\n );\n }\n\n /**\n * The query client of the dataset `context.dataset`.\n *\n * @typeParam R - The row's type.\n * @typeParam FIELDS - The dataset's field paths.\n */\n dataset<R = Record<string, unknown>, FIELDS extends string = string>(\n context: string,\n dataset: string,\n ): QueryModelClient<R, FIELDS> {\n return new QueryModelClient<R, FIELDS>(\n `/wow/dataset/${encodeURIComponent(context)}/${encodeURIComponent(dataset)}/query`,\n this.client,\n );\n }\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"queries.es.js","names":["QueryModelClient","path","client","numbers","json","query","options","positioned","resume","limit","open","received","lastEventId","first","resumableQueryRows","error","isNoMatch","response","send","WowHeaders","version","tag","entityTag","accept","WowProblemError","FrameworkErrorCodes","queryPath","type","model","SnapshotQueryClient","EventQueryClient","events","eventNumbers","DatasetClient","context","dataset"],"sources":["../src/queries.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 { AggregationQuery } from './dsl/aggregation/index.js';\nimport type { CursorPage, CursorQuery } from './dsl/cursorQuery.js';\nimport type { Projected } from './dsl/projection.js';\nimport { eventNumbers, type TextNumbers } from './exactJson.js';\nimport type {\n DescriptorResult,\n QueryModelDescriptor,\n} from './dsl/descriptor.js';\nimport type { FilterCapable } from './dsl/filter/index.js';\nimport { FrameworkErrorCodes, WowProblemError } from './problem.js';\nimport type {\n FilterListQuery,\n FilterSingleQuery,\n PagedQuery,\n PagedList,\n} from './dsl/queryable.js';\nimport {\n entityTag,\n json,\n type RequestOptions,\n send,\n type WowClientOptions,\n WowHeaders,\n} from './http.js';\nimport type {\n AggregateType,\n DatasetEntry,\n EventStreamField,\n EventStream,\n CommittedEvent,\n Snapshot,\n SnapshotSystemField,\n} from './wire.js';\nimport {\n resumableQueryRows,\n type Positioned,\n type StreamResumeOptions,\n} from './streams.js';\n\n/** How a list is streamed: the request's options, and how it resumes. */\nexport interface StreamOptions extends RequestOptions {\n /** How the stream resumes (decision D253); `false` never resumes it. */\n readonly resume?: StreamResumeOptions | false;\n}\n\n/** A count of a query route. */\nexport interface CountQuery<\n FIELDS extends string = string,\n> extends FilterCapable<FIELDS> {\n /** The most matches to count; the budget's default when absent. */\n limit?: number;\n}\n\n/** What a count answers: exact below its limit, else the limit itself. */\nexport interface CountResult {\n readonly count: number;\n readonly exact: boolean;\n}\n\n/**\n * Queries one query model of a Wow service: `POST {path}` with a body\n * whose `kind` names the operation, `GET {path}` for the capability\n * descriptor. A query written with literal `include`\n * paths answers records narrowed to them ({@link Projected}, review R4-Q,\n * Q-14).\n *\n * @typeParam R - The record's type.\n * @typeParam FIELDS - The field paths a filter, sort or projection takes.\n */\nexport class QueryModelClient<R, FIELDS extends string = string> {\n /**\n * @param path - The query route, `/{context}/{aggregate}/{model}/query`\n * @param client - How the service is reached\n * @param numbers - The numbers of each record read as their exact text\n * (review R4-Q, Q-9)\n */\n constructor(\n readonly path: string,\n readonly client: WowClientOptions = {},\n readonly numbers?: TextNumbers,\n ) {}\n\n /** The marks of a list of records. */\n private get listNumbers(): TextNumbers | undefined {\n return this.numbers === undefined ? undefined : { '*': this.numbers };\n }\n\n /** The marks of a page of records. */\n private get pageNumbers(): TextNumbers | undefined {\n return this.numbers === undefined\n ? undefined\n : { list: { '*': this.numbers } };\n }\n\n /** The records that match, at most `limit` (the server's default when absent). */\n list<const INCLUDE extends FIELDS>(\n query: Including<FilterListQuery<FIELDS>, INCLUDE>,\n options?: RequestOptions,\n ): Promise<Projected<R, INCLUDE>[]>;\n list(query: FilterListQuery<FIELDS>, options?: RequestOptions): Promise<R[]>;\n async list(\n query: FilterListQuery<FIELDS>,\n options?: RequestOptions,\n ): Promise<unknown> {\n return json<R[]>(await this.post('list', query, options), this.listNumbers);\n }\n\n /**\n * The records that match, as server-sent events read one at a time; a\n * failure after the first record errors the stream with its problem. The\n * stream resumes where it stopped (decision D253) when the server ends it\n * to be resumed, when it is cut off and when it fails with a retryable\n * problem: see {@link StreamResumeOptions}. A `limit` counts every record\n * read, resumed or not.\n */\n stream<const INCLUDE extends FIELDS>(\n query: Including<FilterListQuery<FIELDS>, INCLUDE>,\n options?: StreamOptions,\n ): Promise<ReadableStream<Projected<R, INCLUDE>>>;\n stream(\n query: FilterListQuery<FIELDS>,\n options?: StreamOptions,\n ): Promise<ReadableStream<R>>;\n async stream(\n query: FilterListQuery<FIELDS>,\n options?: StreamOptions,\n ): Promise<unknown> {\n return (await this.streamRows(query, options)).pipeThrough(\n new TransformStream<Positioned<R>, R>({\n transform(positioned, controller) {\n controller.enqueue(positioned.row);\n },\n }),\n );\n }\n\n /**\n * The records that match as {@link stream} reads them, each with its\n * position: keep the last one read to resume the stream later\n * ({@link StreamResumeOptions.lastEventId}), on another page or after a\n * restart. Kotlin's `RowQueries.stream` answers these rows (`Positioned`).\n */\n streamRows<const INCLUDE extends FIELDS>(\n query: Including<FilterListQuery<FIELDS>, INCLUDE>,\n options?: StreamOptions,\n ): Promise<ReadableStream<Positioned<Projected<R, INCLUDE>>>>;\n streamRows(\n query: FilterListQuery<FIELDS>,\n options?: StreamOptions,\n ): Promise<ReadableStream<Positioned<R>>>;\n async streamRows(\n query: FilterListQuery<FIELDS>,\n options: StreamOptions = {},\n ): Promise<ReadableStream<Positioned<R>>> {\n const resume =\n options.resume === false ? { maxRetries: 0 } : options.resume;\n const limit = query.limit;\n const open = (lastEventId: string | undefined, received: number) => {\n return this.post(\n 'list',\n limit === undefined ? query : { ...query, limit: limit - received },\n options,\n 'text/event-stream',\n lastEventId,\n );\n };\n const first = await open(resume?.lastEventId, 0);\n return resumableQueryRows<R>(\n first,\n (lastEventId, received) =>\n limit !== undefined && received >= limit\n ? Promise.resolve(undefined)\n : open(lastEventId, received),\n {\n ...resume,\n ...(options.signal === undefined ? {} : { signal: options.signal }),\n ...(this.numbers === undefined ? {} : { numbers: this.numbers }),\n },\n );\n }\n\n /** One page of the records that match, and their total. */\n paged<const INCLUDE extends FIELDS>(\n query: Including<PagedQuery<FIELDS>, INCLUDE>,\n options?: RequestOptions,\n ): Promise<PagedList<Projected<R, INCLUDE>>>;\n paged(\n query: PagedQuery<FIELDS>,\n options?: RequestOptions,\n ): Promise<PagedList<R>>;\n async paged(\n query: PagedQuery<FIELDS>,\n options?: RequestOptions,\n ): Promise<unknown> {\n return json<PagedList<R>>(\n await this.post('paged', query, options),\n this.pageNumbers,\n );\n }\n\n /** One page of a forward-only cursor over the records that match. */\n cursor<const INCLUDE extends FIELDS>(\n query: Including<CursorQuery<FIELDS>, INCLUDE>,\n options?: RequestOptions,\n ): Promise<CursorPage<Projected<R, INCLUDE>>>;\n cursor(\n query: CursorQuery<FIELDS>,\n options?: RequestOptions,\n ): Promise<CursorPage<R>>;\n async cursor(\n query: CursorQuery<FIELDS>,\n options?: RequestOptions,\n ): Promise<unknown> {\n return json<CursorPage<R>>(\n await this.post('cursor', query, options),\n this.pageNumbers,\n );\n }\n\n /**\n * The first record that matches, or `undefined` when none does: the\n * service's 404 `wow.query.not-found`, as Kotlin's `QueryApi.single`\n * answers `null`. Any other 404, of a dataset or a route that does not\n * exist, still rejects.\n */\n single<const INCLUDE extends FIELDS>(\n query: Including<FilterSingleQuery<FIELDS>, INCLUDE>,\n options?: RequestOptions,\n ): Promise<Projected<R, INCLUDE> | undefined>;\n single(\n query: FilterSingleQuery<FIELDS>,\n options?: RequestOptions,\n ): Promise<R | undefined>;\n async single(\n query: FilterSingleQuery<FIELDS>,\n options?: RequestOptions,\n ): Promise<unknown> {\n try {\n return json<R>(await this.post('single', query, options), this.numbers);\n } catch (error) {\n if (isNoMatch(error)) return undefined;\n throw error;\n }\n }\n\n /** How many records match, bounded by the count's limit. */\n async count(\n query: CountQuery<FIELDS>,\n options?: RequestOptions,\n ): Promise<CountResult> {\n return json<CountResult>(await this.post('count', query, options));\n }\n\n /** The groups and metrics of an aggregation, one row per group. */\n async aggregate<ROW = Record<string, unknown>>(\n query: AggregationQuery<FIELDS, string>,\n options?: RequestOptions,\n ): Promise<ROW[]> {\n return json<ROW[]>(await this.post('aggregate', query, options));\n }\n\n /**\n * The model's capability descriptor; with the `version` already held, a\n * 304 answers `notModified`.\n */\n async describe(\n version?: string,\n options?: RequestOptions,\n ): Promise<DescriptorResult> {\n const response = await send(this.client, {\n method: 'GET',\n path: this.path,\n headers: {\n [WowHeaders.IF_NONE_MATCH]:\n version === undefined ? undefined : `\"${version}\"`,\n },\n options,\n notModified: true,\n });\n const tag = entityTag(response);\n if (response.status === 304) {\n return { notModified: true, version: tag ?? version ?? '' };\n }\n return {\n notModified: false,\n ...(tag === undefined ? {} : { version: tag }),\n descriptor: await json<QueryModelDescriptor>(response),\n };\n }\n\n private post(\n kind: string,\n query: object,\n options?: RequestOptions,\n accept?: string,\n lastEventId?: string,\n ): Promise<Response> {\n return send(this.client, {\n method: 'POST',\n path: this.path,\n headers: { Accept: accept, [WowHeaders.LAST_EVENT_ID]: lastEventId },\n body: { ...query, kind },\n options,\n });\n }\n}\n\n/**\n * Whether `error` is a 404 that answers \"no match\": a query that found no\n * record, or an aggregate that does not exist. A 404 of another code, or of\n * none (a route that does not exist), is a mistake the caller must hear of.\n */\nfunction isNoMatch(error: unknown): boolean {\n return (\n error instanceof WowProblemError &&\n error.status === 404 &&\n (error.code === FrameworkErrorCodes.QUERY_NOT_FOUND ||\n error.code === FrameworkErrorCodes.AGGREGATE_NOT_FOUND)\n );\n}\n\n/**\n * A query whose projection includes the literal paths `INCLUDE`: a query\n * client narrows its records to them ({@link Projected}).\n */\nexport type Including<Q, INCLUDE extends string> = Q & {\n readonly projection: { readonly include: readonly INCLUDE[] };\n};\n\n/** The query route of a model of an aggregate type. */\nexport function queryPath(type: AggregateType, model: string): string {\n return `/${type.context}/${type.name}/${model}/query`;\n}\n\n/**\n * Queries an aggregate type's snapshots, the default read\n * model; only where the aggregate keeps them.\n *\n * @typeParam S - The state's type.\n * @typeParam STATE_FIELDS - The `state.*` paths of the state.\n */\nexport class SnapshotQueryClient<\n S = unknown,\n STATE_FIELDS extends string = `state.${string}`,\n> extends QueryModelClient<Snapshot<S>, SnapshotSystemField | STATE_FIELDS> {\n /**\n * @param type - The aggregate type\n * @param client - How the service is reached\n */\n constructor(\n readonly type: AggregateType,\n client?: WowClientOptions,\n ) {\n super(\n queryPath(type, 'snapshot'),\n client,\n type.textNumbers?.state === undefined\n ? undefined\n : { state: type.textNumbers.state },\n );\n }\n}\n\n/**\n * Queries an aggregate type's event streams on the same\n * engine as its snapshots: one record per commit, `count` counts commits, a\n * condition on an event is an `elementMatch` on `events`, and per-event\n * analytics expand `events` in an aggregation (`elements`). A filter need\n * not name the aggregate, but one that does not reads the log the service\n * appends to: the budget bounds it.\n *\n * @typeParam E - The events' type.\n */\nexport class EventQueryClient<\n E extends CommittedEvent = CommittedEvent,\n> extends QueryModelClient<EventStream<E>, EventStreamField> {\n /**\n * @param type - The aggregate type\n * @param client - How the service is reached\n */\n constructor(\n readonly type: AggregateType,\n client?: WowClientOptions,\n ) {\n const events = eventNumbers(type);\n super(\n queryPath(type, 'events'),\n client,\n events === undefined ? undefined : { events: { '*': events } },\n );\n }\n}\n\n/**\n * The datasets of a Wow service: registered at run\n * time, so not in the Manifest. Lists those the caller sees and queries\n * each as a snapshot model is queried.\n */\nexport class DatasetClient {\n /** @param client - How the service is reached */\n constructor(readonly client: WowClientOptions = {}) {}\n\n /** The datasets the caller sees, by name. */\n async list(options?: RequestOptions): Promise<DatasetEntry[]> {\n return json<DatasetEntry[]>(\n await send(this.client, { method: 'GET', path: '/wow/dataset', options }),\n );\n }\n\n /**\n * The query client of the dataset `context.dataset`.\n *\n * @typeParam R - The row's type.\n * @typeParam FIELDS - The dataset's field paths.\n */\n dataset<R = Record<string, unknown>, FIELDS extends string = string>(\n context: string,\n dataset: string,\n ): QueryModelClient<R, FIELDS> {\n return new QueryModelClient<R, FIELDS>(\n `/wow/dataset/${encodeURIComponent(context)}/${encodeURIComponent(dataset)}/query`,\n this.client,\n );\n }\n}\n"],"mappings":"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"}
@@ -0,0 +1,2 @@
1
+ Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./http.cjs"),t=require("./manifest.cjs");var n=/\{([A-Za-z][A-Za-z0-9]*)}/g,r=class{constructor(e={},n={}){this.client=e,this.manifest=n.manifest===void 0?void 0:Promise.resolve(t.checkManifest(n.manifest))}async call(t,r,i={},a={}){let o=(await this.manifestOf()).contexts.find(e=>e.name===t)?.routes?.find(e=>e.name===r)?.route;if(o===void 0)throw TypeError(`The Manifest lists no service route ${r} of ${t}.`);let s=o.path.replace(n,(e,n)=>{let a=i.path?.[n];if(a===void 0)throw TypeError(`The service route ${t}.${r} needs its path variable ${n}.`);return encodeURIComponent(String(a))}),c=i.query?Object.fromEntries(Object.entries(i.query).map(([e,t])=>[e,t===void 0?void 0:String(t)])):void 0,l=await e.send(this.client,{method:o.method,path:s,...c===void 0?{}:{query:c},...i.body===void 0?{}:{body:i.body},...i.requestId===void 0?{}:{headers:{[e.WowHeaders.REQUEST_ID]:i.requestId}},options:a});return l.status===204?void 0:e.json(l)}manifestOf(){return this.manifest??=t.fetchManifest(this.client).catch(e=>{throw this.manifest=void 0,e}),this.manifest}};exports.ServiceRoutes=r;
2
+ //# sourceMappingURL=routes.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"routes.cjs","names":["checkManifest","send","WowHeaders","json","fetchManifest","require_http","require_manifest","VARIABLE","ServiceRoutes","client","options","route","item","context","name","path","value","call","variable","query","key","response","error"],"sources":["../src/routes.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 client of a service's own routes: routes whose handler is the service's\n * code, neither a command nor a query, listed in its Manifest with their\n * parameters and schemas. A generated client (`routes.ts`) calls each by its\n * name with typed parameters; a hand-written one calls {@link ServiceRoutes.call}.\n *\n * @packageDocumentation\n */\n\nimport {\n type Call,\n type RequestOptions,\n send,\n json,\n WowHeaders,\n type WowClientOptions,\n} from './http.js';\nimport {\n checkManifest,\n fetchManifest,\n type RoutingManifest,\n} from './manifest.js';\n\n/** What a call of a service route sends, besides its route. */\nexport interface ServiceRouteCall {\n /** The path's variables, by name: each of the route's `{name}`. */\n readonly path?: Readonly<Record<string, string | number | boolean>>;\n /** The query parameters, by name; one left undefined is not sent. */\n readonly query?: Readonly<\n Record<string, string | number | boolean | undefined>\n >;\n /** The body, for a route that takes one. */\n readonly body?: unknown;\n /** The request's id (`Wow-Request-Id`); the service makes one without it. */\n readonly requestId?: string;\n}\n\n/** Options of a {@link ServiceRoutes}. */\nexport interface ServiceRoutesOptions {\n /**\n * The service's Manifest, or the part of it that lists the routes; without\n * it the client reads the service's (`GET /wow/manifest`) once.\n */\n readonly manifest?: RoutingManifest;\n}\n\nconst VARIABLE = /\\{([A-Za-z][A-Za-z0-9]*)}/g;\n\n/**\n * Calls a service's routes by the names its Manifest gives them. The answer\n * is the route's JSON, `undefined` for one that answers `204 No Content`; a\n * refusal rejects with the {@link WowProblemError} of its code, a parameter\n * that does not read with `wow.route.malformed`.\n */\nexport class ServiceRoutes {\n private manifest: Promise<RoutingManifest> | undefined;\n\n /**\n * @param client - How the service is reached\n * @param options - The service's Manifest\n */\n constructor(\n readonly client: WowClientOptions = {},\n options: ServiceRoutesOptions = {},\n ) {\n this.manifest =\n options.manifest === undefined\n ? undefined\n : Promise.resolve(checkManifest(options.manifest));\n }\n\n /**\n * Calls the route `name` of `context` and answers what it answers.\n *\n * @param context - The bounded context whose route it is\n * @param name - The route's name in the Manifest\n * @param call - Its path variables, query parameters and body\n * @param options - The scope or space to act in, headers and cancellation\n * @throws TypeError when the Manifest lists no such route, or a path\n * variable is missing\n */\n async call<T = unknown>(\n context: string,\n name: string,\n call: ServiceRouteCall = {},\n options: RequestOptions = {},\n ): Promise<T | undefined> {\n const route = (await this.manifestOf()).contexts\n .find(item => item.name === context)\n ?.routes?.find(item => item.name === name)?.route;\n if (route === undefined) {\n throw new TypeError(\n `The Manifest lists no service route ${name} of ${context}.`,\n );\n }\n const path = route.path.replace(VARIABLE, (_, variable: string) => {\n const value = call.path?.[variable];\n if (value === undefined) {\n throw new TypeError(\n `The service route ${context}.${name} needs its path variable ${variable}.`,\n );\n }\n return encodeURIComponent(String(value));\n });\n const query = call.query\n ? Object.fromEntries(\n Object.entries(call.query).map(([key, value]) => [\n key,\n value === undefined ? undefined : String(value),\n ]),\n )\n : undefined;\n const response = await send(this.client, {\n method: route.method as Call['method'],\n path,\n ...(query === undefined ? {} : { query }),\n ...(call.body === undefined ? {} : { body: call.body }),\n ...(call.requestId === undefined\n ? {}\n : { headers: { [WowHeaders.REQUEST_ID]: call.requestId } }),\n options,\n });\n return response.status === 204 ? undefined : json<T>(response);\n }\n\n /** The Manifest given, or the service's, fetched once (again after a failure). */\n private manifestOf(): Promise<RoutingManifest> {\n this.manifest ??= fetchManifest(this.client).catch((error: unknown) => {\n this.manifest = undefined;\n throw error;\n });\n return this.manifest;\n }\n}\n"],"mappings":"A,6HA2DA,IAAMO,EAAW,6BAQJC,EAAb,KAA2B,CAOzB,YACE,EAAoC,CAAC,EACrC,EAAgC,CAAC,EACjC,CAFS,KAAA,OAAAC,EAGT,KAAK,SACHC,EAAQ,WAAa,IAAA,GACjB,IAAA,GACA,QAAQ,QAAQV,EAAAA,cAAcU,EAAQ,QAAQ,CAAC,CACvD,CAYA,MAAM,KACJ,EACA,EACA,EAAyB,CAAC,EAC1B,EAA0B,CAAC,EACH,CACxB,IAAMC,GAAS,MAAM,KAAK,WAAW,EAAA,CAAG,SACrC,KAAK,GAAQC,EAAK,OAASC,CAAO,CAAC,EAClC,QAAQ,KAAK,GAAQD,EAAK,OAASE,CAAI,CAAC,EAAE,MAC9C,GAAIH,IAAU,IAAA,GACZ,MAAU,UACR,uCAAuCG,EAAK,MAAMD,EAAQ,EAC5D,EAEF,IAAME,EAAOJ,EAAM,KAAK,QAAQJ,GAAW,EAAG,IAAqB,CACjE,IAAMS,EAAQC,EAAK,OAAOC,GAC1B,GAAIF,IAAU,IAAA,GACZ,MAAU,UACR,qBAAqBH,EAAQ,GAAGC,EAAK,2BAA2BI,EAAS,EAC3E,EAEF,OAAO,mBAAmB,OAAOF,CAAK,CAAC,CACzC,CAAC,EACKG,EAAQF,EAAK,MACf,OAAO,YACL,OAAO,QAAQA,EAAK,KAAK,CAAC,CAAC,KAAK,CAACG,EAAKJ,KAAW,CAC/CI,EACAJ,IAAU,IAAA,GAAY,IAAA,GAAY,OAAOA,CAAK,CAChD,CAAC,CACH,EACA,IAAA,GACEK,EAAW,MAAMpB,EAAAA,KAAK,KAAK,OAAQ,CACvC,OAAQU,EAAM,OACd,OACA,GAAIQ,IAAU,IAAA,GAAY,CAAC,EAAI,CAAE,OAAM,EACvC,GAAIF,EAAK,OAAS,IAAA,GAAY,CAAC,EAAI,CAAE,KAAMA,EAAK,IAAK,EACrD,GAAIA,EAAK,YAAc,IAAA,GACnB,CAAC,EACD,CAAE,QAAS,EAAGf,EAAAA,WAAW,YAAae,EAAK,SAAU,CAAE,EAC3D,SACF,CAAC,EACD,OAAOI,EAAS,SAAW,IAAM,IAAA,GAAYlB,EAAAA,KAAQkB,CAAQ,CAC/D,CAGA,YAA+C,CAK7C,MAJA,MAAK,WAAajB,EAAAA,cAAc,KAAK,MAAM,CAAC,CAAC,MAAO,GAAmB,CAErE,KADA,MAAK,SAAW,IAAA,GACVkB,CACR,CAAC,EACM,KAAK,QACd,CACF,E"}
@@ -0,0 +1,49 @@
1
+ import { RequestOptions, WowClientOptions } from './http.cjs';
2
+ import { RoutingManifest } from './manifest.cjs';
3
+ /** What a call of a service route sends, besides its route. */
4
+ export interface ServiceRouteCall {
5
+ /** The path's variables, by name: each of the route's `{name}`. */
6
+ readonly path?: Readonly<Record<string, string | number | boolean>>;
7
+ /** The query parameters, by name; one left undefined is not sent. */
8
+ readonly query?: Readonly<Record<string, string | number | boolean | undefined>>;
9
+ /** The body, for a route that takes one. */
10
+ readonly body?: unknown;
11
+ /** The request's id (`Wow-Request-Id`); the service makes one without it. */
12
+ readonly requestId?: string;
13
+ }
14
+ /** Options of a {@link ServiceRoutes}. */
15
+ export interface ServiceRoutesOptions {
16
+ /**
17
+ * The service's Manifest, or the part of it that lists the routes; without
18
+ * it the client reads the service's (`GET /wow/manifest`) once.
19
+ */
20
+ readonly manifest?: RoutingManifest;
21
+ }
22
+ /**
23
+ * Calls a service's routes by the names its Manifest gives them. The answer
24
+ * is the route's JSON, `undefined` for one that answers `204 No Content`; a
25
+ * refusal rejects with the {@link WowProblemError} of its code, a parameter
26
+ * that does not read with `wow.route.malformed`.
27
+ */
28
+ export declare class ServiceRoutes {
29
+ readonly client: WowClientOptions;
30
+ private manifest;
31
+ /**
32
+ * @param client - How the service is reached
33
+ * @param options - The service's Manifest
34
+ */
35
+ constructor(client?: WowClientOptions, options?: ServiceRoutesOptions);
36
+ /**
37
+ * Calls the route `name` of `context` and answers what it answers.
38
+ *
39
+ * @param context - The bounded context whose route it is
40
+ * @param name - The route's name in the Manifest
41
+ * @param call - Its path variables, query parameters and body
42
+ * @param options - The scope or space to act in, headers and cancellation
43
+ * @throws TypeError when the Manifest lists no such route, or a path
44
+ * variable is missing
45
+ */
46
+ call<T = unknown>(context: string, name: string, call?: ServiceRouteCall, options?: RequestOptions): Promise<T | undefined>;
47
+ /** The Manifest given, or the service's, fetched once (again after a failure). */
48
+ private manifestOf;
49
+ }