@ahoo-wang/wow-view-store 9.9.0 → 10.0.0-alpha.4

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 (31) hide show
  1. package/README.md +84 -82
  2. package/README.zh-CN.md +61 -66
  3. package/dist/datasetWordings.d.ts +24 -25
  4. package/dist/errors.d.ts +54 -73
  5. package/dist/generated/index.d.ts +1 -0
  6. package/dist/generated/view-store/boundedContext.d.ts +36 -0
  7. package/dist/generated/view-store/dataset_wording/aggregate.d.ts +17 -0
  8. package/dist/generated/view-store/dataset_wording/commandClient.d.ts +32 -0
  9. package/dist/generated/view-store/dataset_wording/index.d.ts +3 -0
  10. package/dist/generated/view-store/dataset_wording/queryClient.d.ts +18 -0
  11. package/dist/generated/view-store/index.d.ts +5 -0
  12. package/dist/generated/view-store/types.d.ts +175 -0
  13. package/dist/generated/view-store/view/aggregate.d.ts +17 -0
  14. package/dist/generated/view-store/view/commandClient.d.ts +65 -0
  15. package/dist/generated/view-store/view/index.d.ts +3 -0
  16. package/dist/generated/view-store/view/queryClient.d.ts +18 -0
  17. package/dist/generated/view-store/view_preferences/aggregate.d.ts +17 -0
  18. package/dist/generated/view-store/view_preferences/commandClient.d.ts +22 -0
  19. package/dist/generated/view-store/view_preferences/index.d.ts +3 -0
  20. package/dist/generated/view-store/view_preferences/queryClient.d.ts +18 -0
  21. package/dist/index.d.ts +4 -2
  22. package/dist/index.es.js +567 -490
  23. package/dist/index.es.js.map +1 -1
  24. package/dist/paths.d.ts +0 -32
  25. package/dist/remembered.d.ts +9 -0
  26. package/dist/source.d.ts +47 -0
  27. package/dist/systemViews.d.ts +21 -0
  28. package/dist/views.d.ts +49 -0
  29. package/dist/wire.d.ts +20 -73
  30. package/dist/wowViewStore.d.ts +111 -159
  31. package/package.json +7 -7
package/README.md CHANGED
@@ -2,127 +2,129 @@
2
2
 
3
3
  [简体中文](./README.zh-CN.md)
4
4
 
5
- The view engine's `ViewStore` on a Wow server: the saved views and preferences
6
- of [`@ahoo-wang/wow-view-engine`](../wow-view-engine/README.md), kept by the
7
- [view store](../../view-store/README.md) — two Wow aggregates, served by the
8
- standalone `wow-view-store-server` or by any Wow service that embeds
9
- `wow-view-store-starter`.
5
+ The view engine's `ViewStore` on the Wow view store service: the saved views
6
+ and preferences of [`@ahoo-wang/wow-view-engine`](../wow-view-engine/README.md),
7
+ kept by the view store service (`platform/view-store` in the Wow repository) —
8
+ two Wow aggregates, reached through the clients generated from the service's
9
+ Manifest — and the view engine's sources over a Wow service's query routes.
10
10
 
11
11
  Released with Wow, from the same tag and with the same version, together
12
- with the view engine and the view store's server modules.
12
+ with the view engine.
13
13
 
14
- > **Compatibility.** From 9.2.0 on, a patch release never breaks the public
15
- > surface (the exports of the entry and the error codes); a minor release may,
16
- > and its release notes list every break with the steps to follow. Keep the Wow
17
- > packages on one minor, as [version ranges](https://wow.ahoo.me/guide/typescript/compatibility#version-ranges)
14
+ > **Compatibility.** A patch release never breaks the public surface (the
15
+ > exports of the entry and the error codes); a minor release may, and its
16
+ > release notes list every break with the steps to follow. Keep the Wow
17
+ > packages on one minor, as [version ranges](https://wow.ahoo.me/typescript/compatibility#version-ranges)
18
18
  > explains.
19
19
 
20
20
  ## Use
21
21
 
22
22
  Peer dependencies: `@ahoo-wang/fetcher`, `@ahoo-wang/wow-client` and
23
23
  `@ahoo-wang/wow-view-engine`, and the peers those declare, which a host installs
24
- with them: `@ahoo-wang/fetcher-decorator` and `@ahoo-wang/fetcher-eventstream`
25
- (wow-client's), and the view engine's optional `react`, `react-dom`,
26
- `react-router` and `mingo` where its own entries need them. Node `>=22.12.0` or
27
- a current browser; TypeScript 6 or later.
24
+ with them: `@ahoo-wang/fetcher-eventstream` (wow-client's), and the view
25
+ engine's optional `react`, `react-dom`, `react-router` and `mingo` where its
26
+ own entries need them. Node `>=22.12.0` or a current browser; TypeScript 6 or
27
+ later.
28
28
 
29
29
  `WowViewStore` takes a fetcher and, optionally, the permissions that drive the
30
- buttons. It takes no tenant, user or application: the fetcher's interceptors
31
- carry who is asking, as they do for every other Wow request of the host.
30
+ buttons. It takes no tenant, user or application: the service takes them from
31
+ the principal, which the fetcher's interceptors carry as they do for every
32
+ other Wow request of the host. `viewSourceOf` puts a definition on a query
33
+ route, `datasetCatalogOf` the service's datasets, and `WowDatasetWordings`
34
+ keeps the tenant's wording over them.
32
35
 
33
36
  <!-- typecheck-context
34
- import type { QueryApi } from '@ahoo-wang/wow-client';
35
37
  import type { ViewDefinition, ViewPermissions } from '@ahoo-wang/wow-view-engine';
36
38
  declare const orders: ViewDefinition;
37
- declare const ordersSource: Pick<QueryApi<any>, 'paged' | 'cursor' | 'aggregate'>;
38
- declare const tokenStorage: TokenStorage;
39
39
  declare const permissionsFromRoles: (definitionId: string) => ViewPermissions;
40
40
  -->
41
41
 
42
42
  ```ts
43
43
  import { Fetcher } from '@ahoo-wang/fetcher';
44
+ import { DatasetClient, SnapshotQueryClient } from '@ahoo-wang/wow-client';
45
+ import { DatasetResources, ViewEngine } from '@ahoo-wang/wow-view-engine';
44
46
  import {
45
- ResourceAttributionRequestInterceptor,
46
- type TokenStorage,
47
- } from '@ahoo-wang/fetcher-cosec';
48
- import { ViewEngine } from '@ahoo-wang/wow-view-engine';
49
- import { WowViewStore } from '@ahoo-wang/wow-view-store';
50
-
51
- // The gateway in front of the view store. In a host, the fetcher already
52
- // carries CoSec's interceptors: the authorization, `CoSec-App-Id`
53
- // (CoSecRequestInterceptor) and the path's {tenantId} and {ownerId}
54
- // (ResourceAttributionRequestInterceptor, from the token).
47
+ WowDatasetWordings,
48
+ WowViewStore,
49
+ datasetCatalogOf,
50
+ viewSourceOf,
51
+ } from '@ahoo-wang/wow-view-store';
52
+
53
+ // The fetcher's interceptors send the authorization and `CoSec-App-Id`; no
54
+ // path names the tenant or the owner.
55
55
  const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });
56
- fetcher.interceptors.request.use(
57
- new ResourceAttributionRequestInterceptor({ tokenStorage }),
58
- );
59
56
 
60
57
  const engine = new ViewEngine({
61
58
  store: new WowViewStore({ fetcher, permissions: permissionsFromRoles }),
62
- resources: [{ definition: orders, source: ordersSource }],
59
+ resources: [
60
+ {
61
+ definition: orders,
62
+ // Any query route: a generated `…SnapshotQueryClient` fits too.
63
+ source: viewSourceOf(
64
+ new SnapshotQueryClient(
65
+ { context: 'sales', name: 'order' },
66
+ { fetcher },
67
+ ),
68
+ ),
69
+ },
70
+ ],
63
71
  });
64
- ```
65
-
66
- `permissions` decides which buttons are enabled, never what a write may do: the
67
- server trusts its paths, and the CoSec gateway decides who may use which. Give
68
- `createShared` and `changeAudience` by the role that may write
69
- `owner/(shared)` — creating a shared view, claiming one and sharing a personal
70
- one all need it. Left out, everything is allowed — but the engine's
71
- `editSystem` (publishing, editing and unpublishing stored system views) is
72
- off unless the host's answer says `true`: give it by the role the gateway
73
- admits to `tenant/(platform)/owner/(system)` (`view-store/README.md`, 「System views」).
74
72
 
75
- ### Dataset wording
76
-
77
- `WowDatasetWordings` keeps a tenant's wording over its datasets (the view
78
- engine's dataset overrides: title, record noun, field labels, order and
79
- narrowing) under `owner/(shared)`, one per dataset and application, keyed by
80
- the dataset's definition id. Hand it to the datasets as their store of
81
- wording: `DatasetResources` reads it before each refresh, registers each
82
- dataset in its stored words, and gives the view manager its wording tab
83
- where the host grants `editDatasetWording`:
84
-
85
- ```ts
86
- import type { Fetcher } from '@ahoo-wang/fetcher';
87
- import {
88
- DatasetDirectoryClient,
89
- DatasetQueryClient,
90
- } from '@ahoo-wang/wow-client';
91
- import { DatasetResources, type ViewEngine } from '@ahoo-wang/wow-view-engine';
92
- import { WowDatasetWordings } from '@ahoo-wang/wow-view-store';
93
-
94
- declare const engine: ViewEngine;
95
- declare const fetcher: Fetcher;
96
-
97
- const directory = new DatasetDirectoryClient();
73
+ // The service's datasets (`GET /wow/dataset`), worded by the tenant.
98
74
  const datasets = new DatasetResources(engine, {
99
- list: () => directory.list(),
100
- source: entry =>
101
- new DatasetQueryClient({ context: entry.contextName, dataset: entry.name }),
75
+ ...datasetCatalogOf(new DatasetClient({ fetcher })),
102
76
  wordings: new WowDatasetWordings({ fetcher }),
103
77
  });
104
78
  await datasets.refresh();
105
79
  ```
106
80
 
81
+ `permissions` decides which buttons are enabled, never what a write may do:
82
+ the service authorizes each write. Give `createShared` and `changeAudience` by
83
+ the role that writes the reserved owner `(shared)` (`view-store.shared-writer`
84
+ as shipped) — creating a shared view, claiming one and sharing a personal one
85
+ all need it. Left out, everything is allowed — but the engine's `editSystem`
86
+ (publishing, editing and unpublishing stored system views) is off unless the
87
+ host's answer says `true`: give it by the role that writes `(system)` of
88
+ `(platform)`.
89
+
90
+ `WowDatasetWordings` keeps a tenant's wording over its datasets (the view
91
+ engine's dataset overrides: title, record noun, field labels, order and
92
+ narrowing), one per dataset and application. `DatasetResources` reads it
93
+ before each refresh, registers each dataset in its stored words, and gives the
94
+ view manager its wording tab where the host grants `editDatasetWording`.
107
95
  `set(dataset, wording, revision, { requestId })` writes one whole at the
108
- expected revision (`'0'` for one never written) and `clear` removes it; the
109
- gateway decides who may, by the role it admits to
110
- `…/owner/(shared)/datasets/{dataset}/wording`.
96
+ expected revision (`'0'` for one never written) and `clear` removes it.
97
+
98
+ ### How the store talks to the service
99
+
100
+ - **Who is asking** comes from the principal; a shared view is written as
101
+ the reserved owner `(shared)` and a stored system view as `(system)` of
102
+ `(platform)`, which the store says itself with `Wow-Scope`.
103
+ - **Writes** carry the port's request id as `Wow-Request-Id` and its revision
104
+ as `If-Match`; the service deduplicates every write by its request id,
105
+ creates included, so a retry from any tab is answered with the first
106
+ outcome. Setting a view shared or personal waits for the service's saga
107
+ that moves it to its new owner.
108
+ - **Errors** are read by the problem's `code`: a `ViewStoreError` carries it
109
+ as `detail.code` (`WowViewStoreErrorCodes` lists the view store's own), and
110
+ a route the service does not serve (`404` without a code) is `UNSUPPORTED`.
111
+ - **A page's total** is the service's default `BOUNDED` count: the service
112
+ refuses an exact total over HTTP.
111
113
 
112
114
  ## Documentation
113
115
 
114
- | To | Read |
115
- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
116
- | Choose where views live, wire `WowViewStore`, give permissions, serve a host nobody signs in to | [Where views live](https://wow.ahoo.me/guide/typescript/view-engine-storage#wowviewstore-views-on-a-wow-service) |
117
- | The exports, the contract, every request the port sends and how server errors map to the port | [wow-view-store reference](https://wow.ahoo.me/reference/typescript/wow-view-store/) |
118
- | Run the view store server, its configuration and the gateway rules | [View store](https://wow.ahoo.me/guide/extensions/view-store) |
116
+ | To | Read |
117
+ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
118
+ | Choose where views live, wire `WowViewStore`, give permissions, serve a host nobody signs in to | [Saved views](https://wow.ahoo.me/typescript/view-engine/storage#wowviewstore-views-on-a-wow-service) |
119
+ | The exports, the contract, every request the port sends and how server errors map to the port | [wow-view-store reference](https://wow.ahoo.me/reference/typescript/wow-view-store/) |
119
120
 
120
121
  ## Testing
121
122
 
122
- - `pnpm --filter @ahoo-wang/wow-view-store test` — unit tests against a fake
123
- server, the public surface and the API report.
124
- - The port's conformance suite runs over `WowViewStore` against a view store
125
- server in `typescript/integration-test` (`test/view-store/`), with the tenant
126
- and application isolation.
123
+ - `pnpm --filter @ahoo-wang/wow-view-store test` — unit tests against the
124
+ service in memory, the public surface and the API report.
125
+ - The port's conformance suite runs over `WowViewStore` against the view store
126
+ service, which `pnpm --dir typescript/integration-test test` starts on
127
+ ports bound to 0 (`test/view-store/`), with the tenant and application
128
+ isolation.
127
129
 
128
130
  Licensed under the Apache License, Version 2.0.
package/README.zh-CN.md CHANGED
@@ -2,105 +2,100 @@
2
2
 
3
3
  [English](./README.md)
4
4
 
5
- 视图引擎的 `ViewStore` 落在 Wow 服务端上:[`@ahoo-wang/wow-view-engine`](../wow-view-engine/README.zh-CN.md)
6
- 保存的视图与偏好,由[视图存储](../../view-store/README.md)保管——两个 Wow 聚合,由独立的
7
- `wow-view-store-server` 提供,或由任何引入了 `wow-view-store-starter` 的 Wow 服务提供。
5
+ 视图引擎的 `ViewStore` 落在 Wow 视图存储服务上:[`@ahoo-wang/wow-view-engine`](../wow-view-engine/README.zh-CN.md)
6
+ 保存的视图与偏好,由视图存储服务(Wow 仓库中的 `platform/view-store`)保管——两个 Wow 聚合,经由从服务
7
+ Manifest 生成的客户端访问;另有视图引擎在 Wow 服务查询路由上的数据源。
8
8
 
9
- 随 Wow 发布,与 Wow 同一个 tag、同一个版本号,与视图引擎和视图存储的服务端模块一起发布。
9
+ 随 Wow 发布,与 Wow 同一个 tag、同一个版本号,与视图引擎一起发布。
10
10
 
11
- > **兼容性。** 从 9.2.0 起,补丁版本不破坏公开面(入口的导出与错误码);次版本可以破坏,它的发布说明
12
- > 逐条列出每个破坏与迁移步骤。Wow 包请停在同一个次版本上,见[版本范围](https://wow.ahoo.me/zh/guide/typescript/compatibility#版本范围)。
11
+ > **兼容性。** 补丁版本不破坏公开面(入口的导出与错误码);次版本可以破坏,它的发布说明
12
+ > 逐条列出每个破坏与迁移步骤。Wow 包请停在同一个次版本上,见[版本范围](https://wow.ahoo.me/zh/typescript/compatibility#版本范围)。
13
13
 
14
14
  ## 使用
15
15
 
16
- 对等依赖:`@ahoo-wang/fetcher`、`@ahoo-wang/wow-client` 与 `@ahoo-wang/wow-view-engine`,以及它们自己声明、
17
- 宿主要一并安装的对等依赖:wow-client 的 `@ahoo-wang/fetcher-decorator` 与 `@ahoo-wang/fetcher-eventstream`,
18
- 视图引擎的可选依赖 `react`、`react-dom`、`react-router` 与 `mingo`(用到它对应的入口时)。Node `>=22.12.0`
19
- 或当前的浏览器;TypeScript 6 及以上。
16
+ peer 依赖:`@ahoo-wang/fetcher`、`@ahoo-wang/wow-client` 与 `@ahoo-wang/wow-view-engine`,以及它们声明的
17
+ peer,由宿主一并安装:`@ahoo-wang/fetcher-eventstream`(wow-client 的),以及视图引擎自己的入口需要时的可选
18
+ `react`、`react-dom`、`react-router` 与 `mingo`。Node `>=22.12.0` 或当前的浏览器;TypeScript 6 或更高。
20
19
 
21
- `WowViewStore` 接收一个 fetcher,以及可选的、决定按钮是否可用的权限。它不收租户、用户或应用:
22
- 是谁在请求由 fetcher 的拦截器带上,与宿主的其他 Wow 请求一样。
20
+ `WowViewStore` 接收一个 fetcher,以及可选的、决定按钮的权限。它不接收租户、用户或应用:服务从主体
21
+ (principal)取得它们,fetcher 的拦截器像宿主的其他 Wow 请求一样带上它们。`viewSourceOf` 把一个定义放到
22
+ 查询路由上,`datasetCatalogOf` 放上服务的数据集,`WowDatasetWordings` 保存租户对它们的措辞。
23
23
 
24
24
  <!-- typecheck-context
25
- import type { QueryApi } from '@ahoo-wang/wow-client';
26
25
  import type { ViewDefinition, ViewPermissions } from '@ahoo-wang/wow-view-engine';
27
26
  declare const orders: ViewDefinition;
28
- declare const ordersSource: Pick<QueryApi<any>, 'paged' | 'cursor' | 'aggregate'>;
29
- declare const tokenStorage: TokenStorage;
30
27
  declare const permissionsFromRoles: (definitionId: string) => ViewPermissions;
31
28
  -->
32
29
 
33
30
  ```ts
34
31
  import { Fetcher } from '@ahoo-wang/fetcher';
32
+ import { DatasetClient, SnapshotQueryClient } from '@ahoo-wang/wow-client';
33
+ import { DatasetResources, ViewEngine } from '@ahoo-wang/wow-view-engine';
35
34
  import {
36
- ResourceAttributionRequestInterceptor,
37
- type TokenStorage,
38
- } from '@ahoo-wang/fetcher-cosec';
39
- import { ViewEngine } from '@ahoo-wang/wow-view-engine';
40
- import { WowViewStore } from '@ahoo-wang/wow-view-store';
41
-
42
- // 视图存储前面的网关。宿主里这个 fetcher 已经带着 CoSec 的拦截器:认证、
43
- // `CoSec-App-Id`(CoSecRequestInterceptor),以及路径里的 {tenantId} 与 {ownerId}
44
- // (ResourceAttributionRequestInterceptor,取自令牌)。
35
+ WowDatasetWordings,
36
+ WowViewStore,
37
+ datasetCatalogOf,
38
+ viewSourceOf,
39
+ } from '@ahoo-wang/wow-view-store';
40
+
41
+ // fetcher 的拦截器带上授权与 `CoSec-App-Id`;路径里不出现租户与 owner。
45
42
  const fetcher = new Fetcher({ baseURL: 'https://api.example.com' });
46
- fetcher.interceptors.request.use(
47
- new ResourceAttributionRequestInterceptor({ tokenStorage }),
48
- );
49
43
 
50
44
  const engine = new ViewEngine({
51
45
  store: new WowViewStore({ fetcher, permissions: permissionsFromRoles }),
52
- resources: [{ definition: orders, source: ordersSource }],
46
+ resources: [
47
+ {
48
+ definition: orders,
49
+ // 任何查询路由都可以:生成的 `…SnapshotQueryClient` 同样适用。
50
+ source: viewSourceOf(
51
+ new SnapshotQueryClient(
52
+ { context: 'sales', name: 'order' },
53
+ { fetcher },
54
+ ),
55
+ ),
56
+ },
57
+ ],
53
58
  });
54
- ```
55
-
56
- `permissions` 只决定哪些按钮可用,从不决定一次写入能不能做:服务端信任路径,谁能用哪条路径由 CoSec
57
- 网关决定。`createShared` 与 `changeAudience` 按能写 `owner/(shared)` 的角色给——新建共享视图、收为个人、设为共享都需要它。不给则全部允许——
58
- 但引擎的 `editSystem`(发布、编辑、取消发布存储的系统视图)只在宿主明确答 `true` 时打开:按网关放行
59
- `tenant/(platform)/owner/(system)` 的角色给(`view-store/README.md`「System views」)。
60
-
61
- ### 数据集措辞
62
-
63
- `WowDatasetWordings` 在 `owner/(shared)` 下存租户给数据集写的措辞(视图引擎的数据集覆盖:标题、名词、字段的
64
- 口径、次序与收窄),每个应用、每个数据集一份,按数据集的定义 id 存。把它交给数据集作措辞存储:`DatasetResources`
65
- 每次刷新前读它,按存着的措辞登记每个数据集,并在宿主给了 `editDatasetWording` 时给视图管理器一个「措辞」页签:
66
-
67
- ```ts
68
- import type { Fetcher } from '@ahoo-wang/fetcher';
69
- import {
70
- DatasetDirectoryClient,
71
- DatasetQueryClient,
72
- } from '@ahoo-wang/wow-client';
73
- import { DatasetResources, type ViewEngine } from '@ahoo-wang/wow-view-engine';
74
- import { WowDatasetWordings } from '@ahoo-wang/wow-view-store';
75
-
76
- declare const engine: ViewEngine;
77
- declare const fetcher: Fetcher;
78
59
 
79
- const directory = new DatasetDirectoryClient();
60
+ // 服务的数据集(`GET /wow/dataset`),按租户的措辞注册。
80
61
  const datasets = new DatasetResources(engine, {
81
- list: () => directory.list(),
82
- source: entry =>
83
- new DatasetQueryClient({ context: entry.contextName, dataset: entry.name }),
62
+ ...datasetCatalogOf(new DatasetClient({ fetcher })),
84
63
  wordings: new WowDatasetWordings({ fetcher }),
85
64
  });
86
65
  await datasets.refresh();
87
66
  ```
88
67
 
89
- `set(dataset, wording, revision, { requestId })` 按期望版本整份写入(从没写过的是 `'0'`),`clear` 清掉;谁能写由网关
90
- 按放行 `…/owner/(shared)/datasets/{dataset}/wording` 的角色决定。
68
+ `permissions` 只决定按钮是否可用,从不决定写入能做什么:每次写入由服务授权。`createShared` 与
69
+ `changeAudience` 按能写保留 owner `(shared)` 的角色给出(出厂为 `view-store.shared-writer`)——新建共享视图、
70
+ 认领共享视图和共享个人视图都需要它。不给时一切都允许——但引擎的 `editSystem`(发布、编辑与撤下存储的系统视图)
71
+ 除非宿主明确答 `true`,否则关闭:按能写 `(platform)` 下 `(system)` 的角色给出。
72
+
73
+ `WowDatasetWordings` 保存租户对数据集的措辞(视图引擎的数据集覆盖:标题、记录名词、字段标签、顺序与收窄),
74
+ 每个数据集、每个应用一份。`DatasetResources` 每次刷新前读取它,按存储的措辞注册每个数据集,并在宿主授予
75
+ `editDatasetWording` 时给视图管理器加上措辞页。`set(dataset, wording, revision, { requestId })` 在期望的
76
+ 修订号上整体写入一份(从未写过的为 `'0'`),`clear` 删除它。
77
+
78
+ ### 存储怎样与服务交互
79
+
80
+ - **谁在请求**来自主体;共享视图以保留 owner `(shared)` 写入,存储的系统视图以 `(platform)` 下的 `(system)`
81
+ 写入,由存储自己用 `Wow-Scope` 说明。
82
+ - **写入**以 `Wow-Request-Id` 带上端口的请求 id,以 `If-Match` 带上修订号;服务按请求 id 对每次写入去重,
83
+ 创建也一样,所以任何标签页的重试都得到第一次的结果。把视图设为共享或个人时,会等服务把它移到新 owner 的 saga。
84
+ - **错误**按 problem 的 `code` 读取:`ViewStoreError` 以 `detail.code` 带着它(`WowViewStoreErrorCodes`
85
+ 列出视图存储自己的码),服务不提供的路由(没有码的 `404`)是 `UNSUPPORTED`。
86
+ - **一页的总数**是服务默认的 `BOUNDED` 计数:服务经 HTTP 拒绝精确总数。
91
87
 
92
88
  ## 文档
93
89
 
94
- | 想做的事 | 读 |
95
- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
96
- | 选择视图放在哪里、接入 `WowViewStore`、给出权限、服务不登录的宿主 | [视图存放在哪里](https://wow.ahoo.me/zh/guide/typescript/view-engine-storage#wowviewstore-视图存在-wow-服务上) |
97
- | 导出、合同、端口发出的每个请求,以及服务端错误怎样映射到端口 | [wow-view-store 参考](https://wow.ahoo.me/zh/reference/typescript/wow-view-store/) |
98
- | 运行视图存储服务端、它的配置与网关规则 | [视图存储](https://wow.ahoo.me/zh/guide/extensions/view-store) |
90
+ | 想做的事 | 读 |
91
+ | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
92
+ | 选择视图放在哪里、接入 `WowViewStore`、给出权限、服务不登录的宿主 | [视图存在哪里](https://wow.ahoo.me/zh/typescript/view-engine/storage#wowviewstore-views-on-a-wow-service) |
93
+ | 导出、合同、端口发出的每个请求,以及服务端错误怎样映射到端口 | [wow-view-store 参考](https://wow.ahoo.me/zh/reference/typescript/wow-view-store/) |
99
94
 
100
95
  ## 测试
101
96
 
102
- - `pnpm --filter @ahoo-wang/wow-view-store test`——对着假服务端的单元测试、公开面与 API 报告。
103
- - 端口的一致性测试套件在 `typescript/integration-test`(`test/view-store/`)里对着视图存储服务端跑
104
- `WowViewStore`,另有租户与应用的隔离测试。
97
+ - `pnpm --filter @ahoo-wang/wow-view-store test`——对着内存中的服务的单元测试、公开面与 API 报告。
98
+ - 端口的一致性测试套件对着视图存储服务跑 `WowViewStore`,另有租户与应用的隔离测试;
99
+ `pnpm --dir typescript/integration-test test` 把服务起在绑定 0 的端口上(`test/view-store/`)。
105
100
 
106
101
  以 Apache License 2.0 许可。
@@ -1,39 +1,36 @@
1
1
  import { Fetcher } from '@ahoo-wang/fetcher';
2
2
  import { DatasetOverrides, DatasetWordingStore, StoredDatasetWording, WriteContext } from '@ahoo-wang/wow-view-engine';
3
- /** How a {@link WowDatasetWordings} reaches the view store: as a `WowViewStore` does. */
3
+ /** How a V10 {@link WowDatasetWordings} reaches the view store service: as a V10 `WowViewStore` does. */
4
4
  export interface WowDatasetWordingsOptions {
5
5
  /**
6
- * The fetcher every request goes through, as {@link WowViewStoreOptions.fetcher}:
7
- * its interceptors fill `{tenantId}` and send `CoSec-App-Id`. The
8
- * wording is the tenant's, so the store always names the owner `(shared)`.
6
+ * The fetcher every request goes through, as the V10
7
+ * `WowViewStoreOptions.fetcher`: its interceptors carry the caller and
8
+ * `CoSec-App-Id`. The wording is the tenant's (an aggregate of the tenant,
9
+ * not of an owner), so no request names a scope.
9
10
  */
10
11
  fetcher: Fetcher;
11
12
  }
12
13
  /**
13
- * The wording a tenant's administrators keep over its datasets in the Wow
14
+ * The wording a tenant's administrators keep over its datasets in the V10
14
15
  * view store (view engine D86): one per dataset of the caller's tenant and
15
- * application, under `owner/(shared)`. The gateway decides who may write it.
16
+ * application, the id derived by the service from the two. Every reader of
17
+ * the tenant reads it; the service decides who writes it (the role that
18
+ * writes the owner `(shared)`, `view-store.shared-writer` as shipped).
16
19
  *
17
20
  * A host hands it to the datasets it registers as their store of wording
18
- * (`DatasetCatalog.wordings`, D91): `DatasetResources` reads it before each
19
- * refresh, registers each dataset in its stored words, and gives the view
20
- * manager an editor of them. The key is the dataset's definition id,
21
- * `{context}.{dataset}`.
22
- *
23
- * ```ts
24
- * const resources = new DatasetResources(engine, {
25
- * list: () => directory.list(),
26
- * source: entry => directory.source(entry),
27
- * wordings: new WowDatasetWordings({ fetcher }),
28
- * });
29
- * ```
30
- *
31
- * Every rejection is a `ViewStoreError`, read as a `WowViewStore`'s are.
21
+ * (`DatasetCatalog.wordings`, D91). The key is the dataset's definition id,
22
+ * `{context}.{dataset}`. Every rejection is a `ViewStoreError`, read as a
23
+ * V10 `WowViewStore`'s are.
32
24
  */
33
25
  export declare class WowDatasetWordings implements DatasetWordingStore {
34
- private readonly fetcher;
26
+ private readonly commands;
27
+ private readonly snapshots;
35
28
  constructor(options: WowDatasetWordingsOptions);
36
- /** Every dataset's wording of the caller's tenant and application, by dataset. */
29
+ /**
30
+ * Every dataset's wording of the caller's tenant and application, by
31
+ * dataset. A cleared one is listed too, saying nothing: its revision is
32
+ * what the next write expects.
33
+ */
37
34
  list(signal?: AbortSignal): Promise<ReadonlyMap<string, StoredDatasetWording>>;
38
35
  /**
39
36
  * Writes a dataset's wording at the expected `revision` (`'0'` for one never
@@ -41,7 +38,9 @@ export declare class WowDatasetWordings implements DatasetWordingStore {
41
38
  * revision.
42
39
  */
43
40
  set(dataset: string, wording: DatasetOverrides, revision: string, context: WriteContext): Promise<string>;
44
- /** Clears a dataset's wording at the expected `revision`: its derived words stand again. */
45
- clear(dataset: string, revision: string, context: WriteContext): Promise<void>;
46
- private send;
41
+ /**
42
+ * Clears a dataset's wording at the expected `revision`: its derived words
43
+ * stand again. Answers the new revision.
44
+ */
45
+ clear(dataset: string, revision: string, context: WriteContext): Promise<string>;
47
46
  }
package/dist/errors.d.ts CHANGED
@@ -1,82 +1,62 @@
1
- import { BindingError, WowError } from '@ahoo-wang/wow-client';
1
+ import { WowProblemError } from '@ahoo-wang/wow-client';
2
2
  import { ViewStoreError, ViewStoreErrorCode } from '@ahoo-wang/wow-view-engine';
3
3
  /**
4
- * The view store's own error codes, beside Wow's (`ErrorCodes` of
5
- * `@ahoo-wang/wow-client`).
4
+ * The V10 view store's own problem codes (`ViewStoreRejections` of
5
+ * `platform/view-store`), beside the framework's (`FrameworkErrorCodes` of
6
+ * `@ahoo-wang/wow-client`): generated from the service's Manifest.
6
7
  *
7
- * Named apart from the engine's `ViewStoreErrorCode` (the port's six codes): these
8
- * are the server's `errorCode` strings, which a `ViewStoreError` carries as
9
- * `detail.code`. Mirrors `ViewStoreErrorCodes` in
10
- * `view-store/wow-view-store-api/src/main/kotlin/me/ahoo/wow/viewstore/api/ViewStoreErrorCodes.kt`.
8
+ * Named apart from the engine's `ViewStoreErrorCode` (the port's codes):
9
+ * these are the `code` of the server's problems, which a `ViewStoreError`
10
+ * carries as `detail.code`.
11
11
  */
12
- export declare const WowViewStoreErrorCodes: Readonly<{
13
- /** A write that is not a valid view or preferences write (HTTP 400). */
14
- readonly VIEW_INVALID: "ViewInvalid";
15
- /** The request carries no `CoSec-App-Id` (HTTP 400). */
16
- readonly VIEW_APP_REQUIRED: "ViewAppRequired";
17
- /** A system view is read-only (HTTP 403). */
18
- readonly SYSTEM_VIEW_READ_ONLY: "SystemViewReadOnly";
19
- /** The path's tenant or owner is missing, blank or invisible (HTTP 400). */
20
- readonly VIEW_SCOPE_REQUIRED: "ViewScopeRequired";
21
- /** The view store's event streams are closed to HTTP queries (HTTP 403). */
22
- readonly VIEW_EVENT_STREAM_CLOSED: "ViewEventStreamClosed";
23
- }>;
12
+ export declare const WowViewStoreErrorCodes: {
13
+ readonly APP_REQUIRED: "view-store.app-required";
14
+ readonly INVALID: "view-store.invalid";
15
+ readonly NOT_FOUND: "view-store.not-found";
16
+ readonly OWNER_REQUIRED: "view-store.owner-required";
17
+ readonly REFERENCED_BY_SHARED_DASHBOARD: "view-store.referenced-by-shared-dashboard";
18
+ readonly SYSTEM_VIEW_READ_ONLY: "view-store.system-view-read-only";
19
+ };
24
20
  /**
25
- * The binding error code a claim refusal names each shared dashboard with
26
- * (`View.REFERENCED_BY_SHARED_DASHBOARD`): the board's id as `name`, its
27
- * title as `msg`.
28
- */
29
- export declare const REFERENCED_BY_SHARED_DASHBOARD = "referenced-by-shared-dashboard";
30
- /**
31
- * A request that did not succeed, as the store reads it: the server's error,
32
- * when the server answered with one, and the HTTP status, when a response
33
- * came back at all.
21
+ * A request that did not succeed, as the store reads it: the server's
22
+ * problem when it answered with one, else what the request threw.
34
23
  */
35
24
  export declare class Failure {
36
25
  /** What the request threw. */
37
26
  readonly cause: unknown;
38
- /** The server's error, read from the failed response. */
39
- readonly wow?: WowError | undefined;
40
- /** The status of the failed response; absent when none came back. */
41
- readonly status?: number | undefined;
27
+ /** The server's problem, when a response came back. */
28
+ readonly problem?: WowProblemError | undefined;
42
29
  constructor(
43
30
  /** What the request threw. */
44
31
  cause: unknown,
45
- /** The server's error, read from the failed response. */
46
- wow?: WowError | undefined,
47
- /** The status of the failed response; absent when none came back. */
48
- status?: number | undefined);
49
- /** The server's error code, if it answered with one. */
50
- get errorCode(): string | undefined;
51
- get bindingErrors(): readonly BindingError[];
52
- /**
53
- * The path variable the fetcher's interceptors never filled, when that is
54
- * why the request was never sent: the host's set-up is wrong, not the
55
- * network.
56
- */
57
- get unfilled(): string | undefined;
32
+ /** The server's problem, when a response came back. */
33
+ problem?: WowProblemError | undefined);
34
+ /** The problem's code: a framework code (`wow.*`) or the view store's. */
35
+ get problemCode(): string | undefined;
58
36
  /**
59
- * The port's code for it (see {@link portCodeOf}). A path variable the
60
- * interceptors never filled is `INVALID`, as the server's own
61
- * `ViewScopeRequired` is: the request is wrong as built and a retry sends
62
- * the same — not `UNAVAILABLE`, which would offer one.
37
+ * The port's code, **by the problem's code first**: one HTTP status
38
+ * carries several decisions (a `400` is a bad title and a missing
39
+ * application alike). Only an answer without a code the store knows — a
40
+ * gateway's own page, a proxy, a code a later server adds — falls back to
41
+ * the status; a problem the service says a retry may get past is
42
+ * `UNAVAILABLE` whatever its status. A `404` without a code is a route the server does not serve:
43
+ * no view store there (or, on the memory backend, no snapshot query), so
44
+ * `UNSUPPORTED`. No answer at all is `UNAVAILABLE`: the outcome is
45
+ * unknown, and a retry under the same request id is safe, since the
46
+ * server deduplicates it.
63
47
  */
64
48
  get code(): ViewStoreErrorCode;
65
- /**
66
- * Whether the server (or something in front of it) answered at all: a
67
- * response came back. An `UNAVAILABLE` that was answered is the server's
68
- * own error — a 5xx, a timeout it reported — and not the network.
69
- */
49
+ /** Whether the server (or something in front of it) answered at all. */
70
50
  get reached(): boolean;
71
51
  get message(): string;
52
+ /** The port's error, holding what it was read from. */
53
+ toStoreError(): ViewStoreError;
72
54
  /**
73
- * The port's error, holding what it was read from: the request's own
74
- * failure as `cause`, the server's error code as `detail` (a host tells
75
- * `ViewAppRequired` from `ViewInvalid` by it), and for `UNAVAILABLE`
76
- * whether the server answered (`reachable`).
55
+ * What {@link toStoreError} holds, for an error of another code: the
56
+ * request's own failure as `cause`, the problem's code as `detail` (a
57
+ * host tells `view-store.app-required` from `view-store.invalid` by it),
58
+ * and for `UNAVAILABLE` whether the server answered (`reachable`).
77
59
  */
78
- toStoreError(): ViewStoreError;
79
- /** {@link toStoreError} with another code: the same failure, read further. */
80
60
  held(): {
81
61
  cause: unknown;
82
62
  detail?: {
@@ -85,18 +65,19 @@ export declare class Failure {
85
65
  reachable?: true;
86
66
  };
87
67
  }
88
- /** Whether the request id of a write was used before. */
89
- export declare function isDuplicateRequest(failure: Failure): boolean;
90
- /**
91
- * The port's code for a server's answer, **by Wow's error code first**: the
92
- * code says what the server decided, where one HTTP status carries several
93
- * decisions (a `400` is a stale version on no server, but a bad title and a
94
- * missing application alike). Only an answer without a code the store knows
95
- * — a gateway's own page, a proxy, a code a later server adds — falls back to
96
- * the status, and no answer at all (a network failure, a timeout, an abort)
97
- * is `UNAVAILABLE`: the outcome is unknown, and a retry under the same
98
- * `requestId` is what the port expects.
99
- */
100
- export declare function portCodeOf(errorCode: string | undefined, status: number | undefined): ViewStoreErrorCode;
101
68
  /** What a failed request threw, read as a {@link Failure}. */
102
69
  export declare function failureOf(error: unknown): Promise<Failure>;
70
+ /**
71
+ * The titles of the shared dashboards a claim refusal names: the problem's
72
+ * `boards` extension member, a list of `{ id, title }` (decision D211). A
73
+ * board without a title is named by its id; anything else is skipped.
74
+ */
75
+ export declare function boardTitles(extensions: Readonly<Record<string, unknown>> | undefined): string[];
76
+ /**
77
+ * Runs one of the port's methods, so that everything it rejects with is a
78
+ * `ViewStoreError`: a failed request as its code says, anything else — a
79
+ * body that did not parse — as `UNAVAILABLE`, the outcome unknown.
80
+ */
81
+ export declare function guard<T>(run: () => Promise<T>): Promise<T>;
82
+ /** Runs one request, so that what it throws is a {@link Failure}. */
83
+ export declare function request<T>(run: () => Promise<T>): Promise<T>;
@@ -0,0 +1 @@
1
+ export * from './view-store/index.js';