@celobus/sdk 0.0.0-stage → 0.1.0

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 (48) hide show
  1. package/LICENSE +91 -0
  2. package/README.md +38 -2
  3. package/dist/access.d.ts +141 -0
  4. package/dist/access.js +232 -0
  5. package/dist/codec.d.ts +29 -0
  6. package/dist/codec.js +361 -0
  7. package/dist/cron.d.ts +2 -0
  8. package/dist/cron.js +113 -0
  9. package/dist/ctx.d.ts +644 -0
  10. package/dist/ctx.js +657 -0
  11. package/dist/db.d.ts +234 -0
  12. package/dist/db.js +495 -0
  13. package/dist/decimal.d.ts +39 -0
  14. package/dist/decimal.js +158 -0
  15. package/dist/declare.d.ts +311 -0
  16. package/dist/declare.js +78 -0
  17. package/dist/descriptor.d.ts +229 -0
  18. package/dist/descriptor.js +899 -0
  19. package/dist/errors.d.ts +65 -0
  20. package/dist/errors.js +114 -0
  21. package/dist/index.d.ts +17 -0
  22. package/dist/index.js +34 -0
  23. package/dist/log.d.ts +39 -0
  24. package/dist/log.js +101 -0
  25. package/dist/names.d.ts +12 -0
  26. package/dist/names.js +41 -0
  27. package/dist/notify.d.ts +185 -0
  28. package/dist/notify.js +234 -0
  29. package/dist/platform.d.ts +61 -0
  30. package/dist/platform.js +47 -0
  31. package/dist/plugin.d.ts +43 -0
  32. package/dist/plugin.js +117 -0
  33. package/dist/query.d.ts +326 -0
  34. package/dist/query.js +794 -0
  35. package/dist/remote.d.ts +8 -0
  36. package/dist/remote.js +19 -0
  37. package/dist/schema.d.ts +487 -0
  38. package/dist/schema.js +405 -0
  39. package/dist/serve.d.ts +63 -0
  40. package/dist/serve.js +411 -0
  41. package/dist/sql.d.ts +13 -0
  42. package/dist/sql.js +33 -0
  43. package/dist/ui.d.ts +1867 -0
  44. package/dist/ui.js +3964 -0
  45. package/dist/viz-kinds.d.ts +12 -0
  46. package/dist/viz-kinds.js +14 -0
  47. package/package.json +33 -4
  48. package/proto/plugin.proto +994 -0
package/LICENSE ADDED
@@ -0,0 +1,91 @@
1
+ Required Notice: Copyright Celobus (https://celobus.com)
2
+
3
+ # PolyForm Shield License 1.0.0
4
+
5
+ <https://polyformproject.org/licenses/shield/1.0.0>
6
+
7
+ ## Acceptance
8
+
9
+ In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
10
+
11
+ ## Copyright License
12
+
13
+ The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
14
+
15
+ ## Distribution License
16
+
17
+ The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
18
+
19
+ ## Notices
20
+
21
+ You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
22
+
23
+ > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
24
+
25
+ ## Changes and New Works License
26
+
27
+ The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
28
+
29
+ ## Patent License
30
+
31
+ The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
32
+
33
+ ## Noncompete
34
+
35
+ Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
36
+
37
+ ## Competition
38
+
39
+ Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms. Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures. Goods and services compete even when provided free of charge. If you market a product as a practical substitute for the software or another product, it definitely competes.
40
+
41
+ ## New Products
42
+
43
+ If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
44
+
45
+ ## Discontinued Products
46
+
47
+ You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business. For example:
48
+
49
+ > Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
50
+
51
+ ## Sales of Business
52
+
53
+ If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce [Noncompete](#noncompete) for that product.
54
+
55
+ ## Fair Use
56
+
57
+ You may have "fair use" rights for the software under the law. These terms do not limit them.
58
+
59
+ ## No Other Rights
60
+
61
+ These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
62
+
63
+ ## Patent Defense
64
+
65
+ If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
66
+
67
+ ## Violations
68
+
69
+ The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
70
+
71
+ ## No Liability
72
+
73
+ ***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
74
+
75
+ ## Definitions
76
+
77
+ The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
78
+
79
+ A **product** can be a good or service, or a combination of them.
80
+
81
+ **You** refers to the individual or entity agreeing to these terms.
82
+
83
+ **Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
84
+
85
+ **Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
86
+
87
+ **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
88
+
89
+ **Your licenses** are all the licenses granted to you for the software under these terms.
90
+
91
+ **Use** means anything you do with the software requiring one of your licenses.
package/README.md CHANGED
@@ -1,3 +1,39 @@
1
- # Temporary Holding Version
1
+ # @celobus/sdk
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The [Celobus](https://celobus.com) plugin SDK for Node.js (TypeScript): a plugin's identity, endpoints, entities,
4
+ screens, agents and jobs declared in code, the descriptor it prints for `--describe`, and its session with the
5
+ platform. Node.js 22 or later.
6
+
7
+ ```sh
8
+ npm install @celobus/sdk
9
+ ```
10
+
11
+ ```ts
12
+ // src/index.ts
13
+ import { endpoint, plugin, role, t } from '@celobus/sdk';
14
+
15
+ const clerk = role({ title: 'Order clerk' });
16
+
17
+ export default plugin({
18
+ id: 'hello', title: 'Hello', roles: { clerk },
19
+ endpoints: {
20
+ hello: endpoint({
21
+ input: t.message('HelloRequest', { name: t.text() }),
22
+ output: t.message('HelloReply', { text: t.text() }),
23
+ roles: [clerk],
24
+ async handler(ctx, { name }) { return { text: `Hello, ${name}!` }; },
25
+ }),
26
+ },
27
+ });
28
+ ```
29
+
30
+ ```ts
31
+ // src/main.ts: `node dist/main.js --describe` prints the descriptor; otherwise it serves
32
+ import plugin from './index.js';
33
+
34
+ await plugin.serve();
35
+ ```
36
+
37
+ The SDKs for Rust and C# and the plugin contract: <https://github.com/celobus/sdk>.
38
+
39
+ Source-available under the PolyForm Shield License 1.0.0 (`LICENSE`).
@@ -0,0 +1,141 @@
1
+ import type { RoleDef } from "./declare.js";
2
+ import type { EntityDef, Shape } from "./schema.js";
3
+ /** A role as a grant: a plugin role, or `workspace.admin` and the other base roles. */
4
+ export type RoleLike = RoleDef | string;
5
+ /** @internal What a grant needs when it is described: the names of the plugin's roles and entities. */
6
+ export interface Resolve {
7
+ role(r: RoleLike): string | undefined;
8
+ /** An entity's name: its own (one of the plugin's), `<plugin>.<name>` (a dependency's), undefined (not declared). */
9
+ entity?(e: EntityDef<any>): string | undefined;
10
+ /** A problem of the rules (`code`: `E_ACCESS_ROLE_UNKNOWN` unless named). */
11
+ error(message: string, code?: string): void;
12
+ }
13
+ /** A grant: who passes. */
14
+ export declare class Grant {
15
+ readonly build: (r: Resolve) => unknown;
16
+ constructor(/** @internal */ build: (r: Resolve) => unknown);
17
+ /**
18
+ * This grant, on the rows whose own fields equal these values (a list: any of them; `null`: none; `a.ne(v)`: not
19
+ * `v`; `a.isNotNull()`: any value).
20
+ */
21
+ when(filter: Record<string, unknown>): Grant;
22
+ }
23
+ /** A test of a field in `when` other than an equality: `a.ne(v)`, `a.isNotNull()`. */
24
+ export declare class WhenTest {
25
+ /** @internal */ readonly op: "ne" | "is_not_null";
26
+ /** @internal */ readonly value: unknown;
27
+ constructor(
28
+ /** @internal */ op: "ne" | "is_not_null",
29
+ /** @internal */ value: unknown);
30
+ }
31
+ /** A relation of the entity's rows: a grant by itself, or `.via(perm)` for a relation to a row. */
32
+ export declare class Relation extends Grant {
33
+ readonly name: string;
34
+ constructor(name: string);
35
+ /** The caller holds `perm` (`read`, `update`, `delete` or an action) on the row this relation points to. */
36
+ via(perm: string): Grant;
37
+ }
38
+ /** What a relation names: a column of a person or a row, a list of people, a group, the rows of a junction. */
39
+ export interface Rel {
40
+ kind: "column" | "group" | "rows";
41
+ field: string;
42
+ /** @internal `rows`: the junction, its column that points to the row, the filter on its rows. */
43
+ rows?: {
44
+ entity: EntityDef<any>;
45
+ target: string;
46
+ filter: unknown[];
47
+ };
48
+ }
49
+ /**
50
+ * A relation through the rows of a junction entity (`a.rows(channelMember, 'channelId', 'userId')`); `.when(filter)`
51
+ * counts only the junction rows whose own fields match.
52
+ */
53
+ export declare class RowsRel implements Rel {
54
+ readonly kind: "rows";
55
+ readonly field: string;
56
+ /** @internal */ readonly rows: {
57
+ entity: EntityDef<any>;
58
+ target: string;
59
+ filter: unknown[];
60
+ };
61
+ constructor(entity: EntityDef<any>, target: string, subject: string, filter?: unknown[]);
62
+ /** Only the junction rows whose own fields match (as `Grant.when`: a value, a list, `null`, `a.ne(v)`, `a.isNotNull()`). */
63
+ when(filter: Record<string, unknown>): RowsRel;
64
+ }
65
+ export type GrantLike = Grant | RoleLike;
66
+ /** The rules of a guard: `.to(value, ...grants)`, `.toAny(...grants)`. */
67
+ export declare class Guard {
68
+ readonly fields: string[];
69
+ /** @internal */ readonly rules: {
70
+ value: unknown;
71
+ grant: Grant;
72
+ }[];
73
+ constructor(/** @internal */ fields: string[]);
74
+ /** To `value`, by whoever the grants admit (evaluated on the row as it was). */
75
+ to(value: unknown, ...grants: GrantLike[]): this;
76
+ /** To any value. */
77
+ toAny(...grants: GrantLike[]): this;
78
+ }
79
+ /** What `access: (a) => ..` declares with. */
80
+ export declare class AccessBuilder {
81
+ /** @internal */ readonly relations: (Rel & {
82
+ name: string;
83
+ })[];
84
+ /** @internal */ readonly grants: Partial<Record<"read" | "create" | "update" | "delete", Grant>>;
85
+ /** @internal */ readonly permits: {
86
+ action: string;
87
+ grant: Grant;
88
+ }[];
89
+ /** @internal */ readonly guards: Guard[];
90
+ /** @internal */ readonly masks: {
91
+ field: string;
92
+ roles: RoleLike[];
93
+ }[];
94
+ /** @internal */ readonly exports: string[];
95
+ /** @internal */ admin: boolean;
96
+ /** A column naming a person, or a row of an entity whose permissions `via` inherits. */
97
+ column(key: string): Rel;
98
+ /** A group: its members. */
99
+ group(key: string): Rel;
100
+ /**
101
+ * The rows of the junction entity `junction` (one of this plugin's) whose `target` column points to the row: each
102
+ * makes the person (`t.ref(platform.user)`) or the group (`t.ref(platform.group)`: its members) its `subject` column
103
+ * names a subject of the relation, as the junction's rows are when the statement runs.
104
+ */
105
+ rows<C extends Shape>(junction: EntityDef<C>, target: keyof C & string, subject: keyof C & string): RowsRel;
106
+ relation(name: string, rel: Rel): Relation;
107
+ read(...grants: GrantLike[]): void;
108
+ /** Checks the new row (an owner relation must name the caller). */
109
+ create(...grants: GrantLike[]): void;
110
+ /** Checks the row as it was; the row as it becomes must stay readable to the writer. */
111
+ update(...grants: GrantLike[]): void;
112
+ delete(...grants: GrantLike[]): void;
113
+ /** A custom action (`publish`) and its grant: what `holds` names. */
114
+ permit(action: string, ...grants: GrantLike[]): void;
115
+ /** All of the grants. */
116
+ all(...grants: GrantLike[]): Grant;
117
+ /** Any of the grants (what several grants given together mean). */
118
+ any(...grants: GrantLike[]): Grant;
119
+ /** Not the grant. */
120
+ not(grant: GrantLike): Grant;
121
+ /** In `when`: the field is not `value` (a null is not equal to a value). */
122
+ ne(value: unknown): WhenTest;
123
+ /** In `when`: the field has a value. */
124
+ isNotNull(): WhenTest;
125
+ /** Whoever the grant of a custom action admits. */
126
+ holds(action: string): Grant;
127
+ /** Everyone, members or not. */
128
+ public(): Grant;
129
+ /** Every member. */
130
+ authenticated(): Grant;
131
+ /** Who may change a column (or any of several), on update. */
132
+ guard(fields: string | string[]): Guard;
133
+ /** Only these roles read the column (an optional one: others read it as absent). */
134
+ mask(field: string, roles: RoleLike[]): void;
135
+ /** Permissions other plugins may inherit with `via`. */
136
+ export(perms: string[]): void;
137
+ /** `workspace.admin` stands in for the roles that are not strict (the default); `false` for rows admins must not see. */
138
+ adminBypass(yes: boolean): void;
139
+ }
140
+ /** @internal The rules as the descriptor carries them. */
141
+ export declare function describeAccess(declare: (a: AccessBuilder) => void, r: Resolve): Record<string, unknown>;
package/dist/access.js ADDED
@@ -0,0 +1,232 @@
1
+ import { snake } from "./names.js";
2
+ /** A `when` filter as access conditions. */
3
+ function conditions(filter) {
4
+ return Object.entries(filter).map(([k, v]) => v instanceof WhenTest
5
+ ? { field: snake(k), op: v.op, value: v.value }
6
+ : v === null
7
+ ? { field: snake(k), op: "is_null", value: null }
8
+ : Array.isArray(v)
9
+ ? { field: snake(k), op: "in", value: v }
10
+ : { field: snake(k), op: "eq", value: v });
11
+ }
12
+ /** A grant: who passes. */
13
+ export class Grant {
14
+ build;
15
+ constructor(/** @internal */ build) {
16
+ this.build = build;
17
+ }
18
+ /**
19
+ * This grant, on the rows whose own fields equal these values (a list: any of them; `null`: none; `a.ne(v)`: not
20
+ * `v`; `a.isNotNull()`: any value).
21
+ */
22
+ when(filter) {
23
+ return new Grant((r) => ({ when: { grant: this.build(r), filter: conditions(filter) } }));
24
+ }
25
+ }
26
+ /** A test of a field in `when` other than an equality: `a.ne(v)`, `a.isNotNull()`. */
27
+ export class WhenTest {
28
+ op;
29
+ value;
30
+ constructor(
31
+ /** @internal */ op,
32
+ /** @internal */ value) {
33
+ this.op = op;
34
+ this.value = value;
35
+ }
36
+ }
37
+ /** A relation of the entity's rows: a grant by itself, or `.via(perm)` for a relation to a row. */
38
+ export class Relation extends Grant {
39
+ name;
40
+ constructor(name) {
41
+ super(() => ({ rel: name }));
42
+ this.name = name;
43
+ }
44
+ /** The caller holds `perm` (`read`, `update`, `delete` or an action) on the row this relation points to. */
45
+ via(perm) {
46
+ return new Grant(() => ({ via: { rel: this.name, perm } }));
47
+ }
48
+ }
49
+ /**
50
+ * A relation through the rows of a junction entity (`a.rows(channelMember, 'channelId', 'userId')`); `.when(filter)`
51
+ * counts only the junction rows whose own fields match.
52
+ */
53
+ export class RowsRel {
54
+ kind = "rows";
55
+ field;
56
+ /** @internal */ rows;
57
+ constructor(entity, target, subject, filter = []) {
58
+ this.field = snake(subject);
59
+ this.rows = { entity, target: snake(target), filter };
60
+ }
61
+ /** Only the junction rows whose own fields match (as `Grant.when`: a value, a list, `null`, `a.ne(v)`, `a.isNotNull()`). */
62
+ when(filter) {
63
+ return new RowsRel(this.rows.entity, this.rows.target, this.field, [...this.rows.filter, ...conditions(filter)]);
64
+ }
65
+ }
66
+ function grantOf(g) {
67
+ if (g instanceof Grant)
68
+ return g;
69
+ return new Grant((r) => {
70
+ const name = r.role(g);
71
+ if (name === undefined)
72
+ r.error("a role of the rules is not in plugin({ roles })");
73
+ return { role: name ?? "" };
74
+ });
75
+ }
76
+ function anyOf(grants) {
77
+ if (grants.length === 1)
78
+ return grantOf(grants[0]);
79
+ return new Grant((r) => ({ any: grants.map((g) => grantOf(g).build(r)) }));
80
+ }
81
+ /** The rules of a guard: `.to(value, ...grants)`, `.toAny(...grants)`. */
82
+ export class Guard {
83
+ fields;
84
+ /** @internal */ rules = [];
85
+ constructor(/** @internal */ fields) {
86
+ this.fields = fields;
87
+ }
88
+ /** To `value`, by whoever the grants admit (evaluated on the row as it was). */
89
+ to(value, ...grants) {
90
+ this.rules.push({ value, grant: anyOf(grants) });
91
+ return this;
92
+ }
93
+ /** To any value. */
94
+ toAny(...grants) {
95
+ this.rules.push({ value: null, grant: anyOf(grants) });
96
+ return this;
97
+ }
98
+ }
99
+ /** What `access: (a) => ..` declares with. */
100
+ export class AccessBuilder {
101
+ /** @internal */ relations = [];
102
+ /** @internal */ grants = {};
103
+ /** @internal */ permits = [];
104
+ /** @internal */ guards = [];
105
+ /** @internal */ masks = [];
106
+ /** @internal */ exports = [];
107
+ /** @internal */ admin = true;
108
+ /** A column naming a person, or a row of an entity whose permissions `via` inherits. */
109
+ column(key) {
110
+ return { kind: "column", field: snake(key) };
111
+ }
112
+ /** A group: its members. */
113
+ group(key) {
114
+ return { kind: "group", field: snake(key) };
115
+ }
116
+ /**
117
+ * The rows of the junction entity `junction` (one of this plugin's) whose `target` column points to the row: each
118
+ * makes the person (`t.ref(platform.user)`) or the group (`t.ref(platform.group)`: its members) its `subject` column
119
+ * names a subject of the relation, as the junction's rows are when the statement runs.
120
+ */
121
+ rows(junction, target, subject) {
122
+ return new RowsRel(junction, target, subject);
123
+ }
124
+ relation(name, rel) {
125
+ this.relations.push({ name, kind: rel.kind, field: rel.field, ...(rel.rows ? { rows: rel.rows } : {}) });
126
+ return new Relation(name);
127
+ }
128
+ read(...grants) {
129
+ this.grants.read = anyOf(grants);
130
+ }
131
+ /** Checks the new row (an owner relation must name the caller). */
132
+ create(...grants) {
133
+ this.grants.create = anyOf(grants);
134
+ }
135
+ /** Checks the row as it was; the row as it becomes must stay readable to the writer. */
136
+ update(...grants) {
137
+ this.grants.update = anyOf(grants);
138
+ }
139
+ delete(...grants) {
140
+ this.grants.delete = anyOf(grants);
141
+ }
142
+ /** A custom action (`publish`) and its grant: what `holds` names. */
143
+ permit(action, ...grants) {
144
+ this.permits.push({ action, grant: anyOf(grants) });
145
+ }
146
+ /** All of the grants. */
147
+ all(...grants) {
148
+ return new Grant((r) => ({ all: grants.map((g) => grantOf(g).build(r)) }));
149
+ }
150
+ /** Any of the grants (what several grants given together mean). */
151
+ any(...grants) {
152
+ return new Grant((r) => ({ any: grants.map((g) => grantOf(g).build(r)) }));
153
+ }
154
+ /** Not the grant. */
155
+ not(grant) {
156
+ return new Grant((r) => ({ not: grantOf(grant).build(r) }));
157
+ }
158
+ /** In `when`: the field is not `value` (a null is not equal to a value). */
159
+ ne(value) {
160
+ return new WhenTest("ne", value);
161
+ }
162
+ /** In `when`: the field has a value. */
163
+ isNotNull() {
164
+ return new WhenTest("is_not_null", null);
165
+ }
166
+ /** Whoever the grant of a custom action admits. */
167
+ holds(action) {
168
+ return new Grant(() => ({ holds: action }));
169
+ }
170
+ /** Everyone, members or not. */
171
+ public() {
172
+ return new Grant(() => "public");
173
+ }
174
+ /** Every member. */
175
+ authenticated() {
176
+ return new Grant(() => "authenticated");
177
+ }
178
+ /** Who may change a column (or any of several), on update. */
179
+ guard(fields) {
180
+ const g = new Guard((Array.isArray(fields) ? fields : [fields]).map(snake));
181
+ this.guards.push(g);
182
+ return g;
183
+ }
184
+ /** Only these roles read the column (an optional one: others read it as absent). */
185
+ mask(field, roles) {
186
+ this.masks.push({ field: snake(field), roles });
187
+ }
188
+ /** Permissions other plugins may inherit with `via`. */
189
+ export(perms) {
190
+ this.exports.push(...perms);
191
+ }
192
+ /** `workspace.admin` stands in for the roles that are not strict (the default); `false` for rows admins must not see. */
193
+ adminBypass(yes) {
194
+ this.admin = yes;
195
+ }
196
+ }
197
+ /** @internal The rules as the descriptor carries them. */
198
+ export function describeAccess(declare, r) {
199
+ const a = new AccessBuilder();
200
+ declare(a);
201
+ const grant = (g) => (g ? g.build(r) : null);
202
+ return {
203
+ relations: a.relations.map((x) => {
204
+ const out = { name: x.name, kind: x.kind, field: x.field };
205
+ if (x.rows) {
206
+ const entity = r.entity?.(x.rows.entity);
207
+ if (entity === undefined) {
208
+ r.error(`the junction of relation ${x.name} is not an entity of the plugin`, "E_ACCESS_ROWS_PLUGIN");
209
+ }
210
+ out.rows = { entity: entity ?? "", target: x.rows.target, filter: x.rows.filter };
211
+ }
212
+ return out;
213
+ }),
214
+ read: grant(a.grants.read),
215
+ create: grant(a.grants.create),
216
+ update: grant(a.grants.update),
217
+ delete: grant(a.grants.delete),
218
+ permits: a.permits.map((p) => ({ action: p.action, grant: p.grant.build(r) })),
219
+ guards: a.guards.map((g) => ({ fields: g.fields, rules: g.rules.map((x) => ({ value: x.value, grant: x.grant.build(r) })) })),
220
+ masks: a.masks.map((m) => ({
221
+ field: m.field,
222
+ roles: m.roles.map((x) => {
223
+ const name = r.role(x);
224
+ if (name === undefined)
225
+ r.error("a role of a mask is not in plugin({ roles })");
226
+ return name ?? "";
227
+ }),
228
+ })),
229
+ export: a.exports,
230
+ admin: a.admin,
231
+ };
232
+ }
@@ -0,0 +1,29 @@
1
+ import { EntityDef, MessageDef, type AnyField, type KeyType, type RefTarget } from "./schema.js";
2
+ /** One field of a message as the codec sees it. */
3
+ export interface CodecField {
4
+ key: string;
5
+ name: string;
6
+ json: string;
7
+ field: AnyField;
8
+ }
9
+ /** The fields of a message, or of an entity's message (`id` first, then the columns). */
10
+ export declare function messageFields(source: MessageDef<any> | EntityDef<any>): CodecField[];
11
+ /** The key type of a ref's target; `undefined` for the directory and other plugins' entities. */
12
+ export declare function refKey(target: RefTarget): KeyType | undefined;
13
+ /** Collects input errors by path, as `details.fields` of a 400 `invalid`. */
14
+ export type FieldErrors = Record<string, string>;
15
+ /** Decodes a JSON object into a message's TypeScript value; problems go to `errors`. */
16
+ export declare function decodeMessage(source: MessageDef<any> | EntityDef<any>, json: unknown, path: string, errors: FieldErrors): Record<string, unknown>;
17
+ /** One value of a (single) field: `undefined` for a JSON null or nothing. */
18
+ export declare function decodeFieldValue(field: AnyField, raw: unknown, path: string, errors: FieldErrors): unknown;
19
+ /** A handler answered something that does not fit its output type: a 500 for the caller, logged with the path. */
20
+ export declare class OutputError extends Error {
21
+ readonly path: string;
22
+ constructor(path: string, message: string);
23
+ }
24
+ /** Encodes a handler's output value as a JSON object. */
25
+ export declare function encodeMessage(source: MessageDef<any> | EntityDef<any>, value: unknown, path?: string): Record<string, unknown>;
26
+ /** @internal One value of a field in the protobuf JSON mapping (for filters and patches). */
27
+ export declare function encodeFieldValue(field: AnyField, v: unknown, path: string): unknown;
28
+ /** JSON.stringify that writes a bigint as a string (for raw calls and logs). */
29
+ export declare function stringify(value: unknown): string;