ezship 0.1.16 → 0.1.18
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.
- package/README.md +60 -56
- package/access.d.mts +4 -4
- package/access.mjs +13 -13
- package/account.mjs +9 -8
- package/bindings.mjs +9 -27
- package/commands.d.mts +65 -67
- package/commands.mjs +1274 -535
- package/connections.d.mts +2 -3
- package/connections.mjs +10 -22
- package/cron.d.mts +1 -1
- package/cron.mjs +1 -1
- package/documents.d.mts +1 -1
- package/documents.mjs +1 -1
- package/editor-types.json.gz +0 -0
- package/editor.mjs +22 -56
- package/ez.mjs +48 -133
- package/package.json +7 -1
- package/paths.d.mts +24 -0
- package/paths.mjs +103 -0
- package/schema.d.mts +45 -49
- package/schema.mjs +364 -219
- package/session.d.mts +2 -3
- package/session.mjs +3 -5
- package/shape.d.mts +2 -2
- package/shape.mjs +1 -1
- package/signup.mjs +2 -2
- package/types.d.mts +73 -73
- package/update-check.mjs +1 -1
- package/workflow.d.mts +8 -2
- package/workflow.mjs +88 -21
package/session.d.mts
CHANGED
|
@@ -1,9 +1,8 @@
|
|
|
1
|
-
// Hand-written declarations for cli/session.mjs: Session State (docs/adr/
|
|
1
|
+
// Hand-written declarations for cli/session.mjs: Session State (docs/adr/0214).
|
|
2
2
|
import type { Shape } from "./shape.d.mts";
|
|
3
3
|
|
|
4
4
|
export const SESSION_FILE: "session.ts";
|
|
5
|
-
export
|
|
6
|
-
export const SESSION_VERSION_KEY: "~session";
|
|
5
|
+
export { SESSION_PATH, SESSION_VERSION_KEY } from "./paths.d.mts";
|
|
7
6
|
export const SESSION_LIMITS: Readonly<{ keys: number; valueBytes: number }>;
|
|
8
7
|
|
|
9
8
|
/** `saved` survives sign-out and devices; `signedIn` ends with the sign-in. */
|
package/session.mjs
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// Session State (docs/adr/
|
|
1
|
+
// Session State (docs/adr/0214): typed per-viewer values an Instance declares in `global/session.ts`. The
|
|
2
2
|
// file is TypeScript the Pipeline compiles, but its `Saved` and `SignedIn` types are written in the JSON TYPE
|
|
3
3
|
// subset (shape.mjs), so the Host can read them without a compiler and check every write. Pure and
|
|
4
4
|
// zero-dependency, like the rest of the contract.
|
|
@@ -9,10 +9,8 @@ import { parseShape, shapeError } from "./shape.mjs";
|
|
|
9
9
|
|
|
10
10
|
/** The Global Workspace file that declares Provided values and Session State. */
|
|
11
11
|
export const SESSION_FILE = "session.ts";
|
|
12
|
-
|
|
13
|
-
export
|
|
14
|
-
/** The viewer's own counter in the live version map (docs/adr/0053); no Table can have this name. */
|
|
15
|
-
export const SESSION_VERSION_KEY = "~session";
|
|
12
|
+
// The page's path and the viewer's counter in the live version map are in paths.mjs (docs/adr/0216).
|
|
13
|
+
export { SESSION_PATH, SESSION_VERSION_KEY } from "./paths.mjs";
|
|
16
14
|
/** At most this many keys per Instance, each value at most this many bytes of JSON. */
|
|
17
15
|
export const SESSION_LIMITS = Object.freeze({ keys: 32, valueBytes: 4096 });
|
|
18
16
|
|
package/shape.d.mts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// Hand-written declarations for cli/shape.mjs: a JSON column's declared TYPE (docs/adr/
|
|
1
|
+
// Hand-written declarations for cli/shape.mjs: a JSON column's declared TYPE (docs/adr/0236).
|
|
2
2
|
|
|
3
3
|
export type Shape =
|
|
4
4
|
| { kind: "string" | "number" | "boolean" | "null" | "unknown" | "date" | "epoch" | "cents" }
|
|
@@ -8,7 +8,7 @@ export type Shape =
|
|
|
8
8
|
| { kind: "union"; of: Shape[] };
|
|
9
9
|
|
|
10
10
|
export function isCalendarDate(value: unknown): value is string;
|
|
11
|
-
/** `maxLength` defaults to a column's 2,000 characters; Session State (ADR
|
|
11
|
+
/** `maxLength` defaults to a column's 2,000 characters; Session State (ADR 0214) declares a whole object. */
|
|
12
12
|
export function parseShape(text: string, maxLength?: number): { shape: Shape } | { error: string };
|
|
13
13
|
export function printShape(shape: Shape): string;
|
|
14
14
|
export function shapeError(shape: Shape, value: unknown, path: string): string | null;
|
package/shape.mjs
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// A JSON column's declared shape (docs/adr/
|
|
1
|
+
// A JSON column's declared shape (docs/adr/0236): `<col> JSON TYPE '<shape>'` in db/schema.sql, written in a
|
|
2
2
|
// small TypeScript subset. The same parse gives the generated TypeScript type and the validator every page and
|
|
3
3
|
// function write passes through. Pure and zero-dependency, like the rest of the contract.
|
|
4
4
|
//
|
package/signup.mjs
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
/** The public bootstrap exception (
|
|
1
|
+
/** The public bootstrap exception (ADR 0245). Provisioning has one destination: the trial Host. */
|
|
2
2
|
export const TRIAL_HOST = "https://api.ezship.dev";
|
|
3
3
|
export const TRIAL_STATUS_PATH = "/api/trial";
|
|
4
4
|
export const SIGNUP_ROUTES = Object.freeze({
|
|
5
5
|
start: "/cli/signup/start",
|
|
6
6
|
complete: "/cli/signup/complete",
|
|
7
7
|
});
|
|
8
|
-
/** ADR
|
|
8
|
+
/** ADR 0245: the verification email's Studio button opens `<studio>/#signup=<link>`. */
|
|
9
9
|
export const SIGNUP_LINK_RE = /^[A-Za-z0-9]{43}$/;
|
|
10
10
|
|
|
11
11
|
/**
|
package/types.d.mts
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
export type { Conflict, Declaration, LiveSchema, Plan, PlanSummary, Table } from "./schema.d.mts";
|
|
7
7
|
|
|
8
8
|
/**
|
|
9
|
-
* A Builder's role in one Instance (docs/adr/
|
|
9
|
+
* A Builder's role in one Instance (docs/adr/0202). `limited` edits and deploys Sites and invites Members;
|
|
10
10
|
* `builder` additionally pushes the Global Workspace and creates Sites; `admin` additionally archives and
|
|
11
11
|
* restricts Sites, manages Builders and roles, and changes the Instance's settings and assets.
|
|
12
12
|
*/
|
|
@@ -17,15 +17,15 @@ export type Version = {
|
|
|
17
17
|
n: number;
|
|
18
18
|
by: string | null;
|
|
19
19
|
at: number | null;
|
|
20
|
-
/** The Push's message (docs/adr/
|
|
20
|
+
/** The Push's message (docs/adr/0211), where the Version comes from a retained Version: versions, pull --version, push. */
|
|
21
21
|
message?: string | null;
|
|
22
|
-
/** `ez versions` of a Site (docs/adr/
|
|
22
|
+
/** `ez versions` of a Site (docs/adr/0211): when a deploy last shipped this Version, null when none has. */
|
|
23
23
|
deployedAt?: number | null;
|
|
24
24
|
/** `ez versions` of a Site: this is the Version the Site's latest deploy shipped, what Members see now. */
|
|
25
25
|
live?: boolean;
|
|
26
26
|
};
|
|
27
27
|
|
|
28
|
-
/** Credential-free Instance connection information, served at /.well-known/ezship (ADR
|
|
28
|
+
/** Credential-free Instance connection information, served at /.well-known/ezship (ADR 0202). */
|
|
29
29
|
export type InstanceDiscovery = {
|
|
30
30
|
version: 1;
|
|
31
31
|
uid: string;
|
|
@@ -38,9 +38,9 @@ export type InstanceDiscovery = {
|
|
|
38
38
|
/** Email-verified, demo-Host-only bootstrap; never a general lifecycle API. */
|
|
39
39
|
export type SignupInput = { email: string; name: string; source: "cli" | "plugin" | "web" };
|
|
40
40
|
export type SignupChallenge = { receipt: string; expiresAt: number };
|
|
41
|
-
/** `studio` is the trial's Studio address; the verification email's button opens it signed in (ADR
|
|
41
|
+
/** `studio` is the trial's Studio address; the verification email's button opens it signed in (ADR 0245). */
|
|
42
42
|
export type SignupResult = { connection: InstanceDiscovery; token: string; studio: string };
|
|
43
|
-
/** Credential-free facts about an active signup trial on its own API origin (ADR
|
|
43
|
+
/** Credential-free facts about an active signup trial on its own API origin (ADR 0245). */
|
|
44
44
|
export type SignupTrialStatus = { uid: string; instance: string; expiresAt: number };
|
|
45
45
|
|
|
46
46
|
/** An Instance's settings (the `instances` row). One Instance == one customer == the unit of tenancy. */
|
|
@@ -83,14 +83,14 @@ export type WorkspaceInfo = Site & {
|
|
|
83
83
|
appUrl: string | null;
|
|
84
84
|
role: BuilderRole;
|
|
85
85
|
/**
|
|
86
|
-
* The Global Workspace's Version the Site's latest deploy compiled in (docs/adr/
|
|
87
|
-
* pushed then), null when the Site has no recorded deploy.
|
|
86
|
+
* The Global Workspace's Version the Site's latest deploy compiled in (docs/adr/0211; 0 when Global was never
|
|
87
|
+
* pushed then), null when the Site has no recorded deploy.
|
|
88
88
|
*/
|
|
89
|
-
deployedGlobal
|
|
89
|
+
deployedGlobal: number | null;
|
|
90
90
|
};
|
|
91
91
|
|
|
92
92
|
/**
|
|
93
|
-
* What a Site's next deploy brings in from the Global Workspace (`ez status`, docs/adr/
|
|
93
|
+
* What a Site's next deploy brings in from the Global Workspace (`ez status`, docs/adr/0211): the Version its
|
|
94
94
|
* live app was built with, the newest pushed one, and the files changed between them that reach an app only at
|
|
95
95
|
* a deploy (`pinnedGlobalPath`). `paths` is null when the live one is no longer retained.
|
|
96
96
|
*/
|
|
@@ -101,7 +101,7 @@ export type GlobalSinceDeploy = {
|
|
|
101
101
|
};
|
|
102
102
|
|
|
103
103
|
/**
|
|
104
|
-
* What a push did (Workspace.pushAll). A Global push also lists its Live changes (docs/adr/
|
|
104
|
+
* What a push did (Workspace.pushAll). A Global push also lists its Live changes (docs/adr/0224), which took
|
|
105
105
|
* effect for every deployed Site at once; everything else reaches a Site at its next Preview or Deploy.
|
|
106
106
|
*/
|
|
107
107
|
export type PushResult = {
|
|
@@ -109,16 +109,16 @@ export type PushResult = {
|
|
|
109
109
|
written: string[];
|
|
110
110
|
deleted: string[];
|
|
111
111
|
live?: LiveChange[];
|
|
112
|
-
/** What changed access rules do to Members' rows (docs/adr/
|
|
112
|
+
/** What changed access rules do to Members' rows (docs/adr/0225); present when a READ or WRITE changed. */
|
|
113
113
|
report?: AccessReport[];
|
|
114
|
-
/** What the pushed guards would have done to the last 7 days of writes (docs/adr/
|
|
114
|
+
/** What the pushed guards would have done to the last 7 days of writes (docs/adr/0226). */
|
|
115
115
|
rulesReport?: RulesReport[];
|
|
116
116
|
/** `ez global push --dry-run`: checked and reported, nothing saved; `version` is the current one. */
|
|
117
117
|
dryRun?: true;
|
|
118
118
|
};
|
|
119
119
|
|
|
120
120
|
/**
|
|
121
|
-
* One guard's replay (docs/adr/
|
|
121
|
+
* One guard's replay (docs/adr/0226): of `replayed` recent writes to `table`, how many it would have
|
|
122
122
|
* refused, by whom (History actor ids), with a few of its messages.
|
|
123
123
|
*/
|
|
124
124
|
export type RulesReport = {
|
|
@@ -130,7 +130,7 @@ export type RulesReport = {
|
|
|
130
130
|
};
|
|
131
131
|
|
|
132
132
|
/**
|
|
133
|
-
* One changed rule's effect (docs/adr/
|
|
133
|
+
* One changed rule's effect (docs/adr/0225): per Member, how many rows they may read (or write) after the
|
|
134
134
|
* Push, and how many they gain and lose. Only Members whose rows change are listed; `sampled` of the
|
|
135
135
|
* Instance's `total` active Members were compared (at most 200).
|
|
136
136
|
*/
|
|
@@ -143,7 +143,7 @@ export type AccessReport = {
|
|
|
143
143
|
};
|
|
144
144
|
|
|
145
145
|
/**
|
|
146
|
-
* One Live change of a Global push (docs/adr/
|
|
146
|
+
* One Live change of a Global push (docs/adr/0224). A default (docs/adr/0224) is printed as declared, null
|
|
147
147
|
* for none; `nulls` counts the existing rows a new default does not fill.
|
|
148
148
|
*/
|
|
149
149
|
export type LiveChange =
|
|
@@ -157,18 +157,18 @@ export type LiveChange =
|
|
|
157
157
|
}
|
|
158
158
|
| { kind: "access"; table: string; op: "read" | "write"; from: string; to: string }
|
|
159
159
|
| { kind: "scope"; from: string | null; to: string | null }
|
|
160
|
-
/** The GROUP statements (docs/adr/
|
|
160
|
+
/** The GROUP statements (docs/adr/0225), normalized; null for none. */
|
|
161
161
|
| { kind: "groups"; from: string | null; to: string | null }
|
|
162
|
-
/** Table rules (docs/adr/
|
|
162
|
+
/** Table rules (docs/adr/0226): the Tables whose rules this Push compiled, empty when it removed them all. */
|
|
163
163
|
| { kind: "rules"; tables: string[] }
|
|
164
|
-
/** Workflows (docs/adr/
|
|
164
|
+
/** Workflows (docs/adr/0227): the Tables whose workflow this Push added, changed or removed. */
|
|
165
165
|
| { kind: "workflows"; tables: string[] }
|
|
166
|
-
/** Schedules (ADR
|
|
166
|
+
/** Schedules (ADR 0230): the schedules.json entries this Push added, changed or removed. */
|
|
167
167
|
| { kind: "schedules"; names: string[] }
|
|
168
|
-
/** Jobs (ADR
|
|
168
|
+
/** Jobs (ADR 0230): the jobs/ files this Push added, changed or removed. */
|
|
169
169
|
| { kind: "jobs"; names: string[] }
|
|
170
170
|
/**
|
|
171
|
-
* An integrity constraint added or removed (docs/adr/
|
|
171
|
+
* An integrity constraint added or removed (docs/adr/0222): SINGLETON, EXACTLY ONE OF (its columns) or
|
|
172
172
|
* ON DELETE RESTRICT (the referencing column, of `table`).
|
|
173
173
|
*/
|
|
174
174
|
| IntegrityChange
|
|
@@ -182,7 +182,7 @@ export type IntegrityChange = {
|
|
|
182
182
|
added: boolean;
|
|
183
183
|
};
|
|
184
184
|
|
|
185
|
-
/** What a deploy did (Workspace.deploy), including what it did to the App Database (docs/adr/
|
|
185
|
+
/** What a deploy did (Workspace.deploy), including what it did to the App Database (docs/adr/0217). */
|
|
186
186
|
export type DeployResult = {
|
|
187
187
|
deployedAt: number;
|
|
188
188
|
files: string[];
|
|
@@ -190,11 +190,11 @@ export type DeployResult = {
|
|
|
190
190
|
schema: { created: string[]; added: string[]; indexed: string[] };
|
|
191
191
|
/** The Global Workspace's Version compiled into this deploy (0 when it has never been pushed). */
|
|
192
192
|
global: number;
|
|
193
|
-
/** What deployed but will not work yet, such as an Integration the Instance has not set (ADR
|
|
193
|
+
/** What deployed but will not work yet, such as an Integration the Instance has not set (ADR 0231). */
|
|
194
194
|
warnings?: string[];
|
|
195
195
|
};
|
|
196
196
|
|
|
197
|
-
// ---- hosted Previews (docs/adr/
|
|
197
|
+
// ---- hosted Previews (docs/adr/0212) ----
|
|
198
198
|
|
|
199
199
|
/** Where a Preview's files came from. */
|
|
200
200
|
export type PreviewSource = { kind: "upload" } | { kind: "version"; n: number };
|
|
@@ -225,7 +225,7 @@ export type PreviewRow = {
|
|
|
225
225
|
activeAt: number;
|
|
226
226
|
};
|
|
227
227
|
/**
|
|
228
|
-
* Another Builder's Preview of this Site, as `ez preview ls --others` lists it (docs/adr/
|
|
228
|
+
* Another Builder's Preview of this Site, as `ez preview ls --others` lists it (docs/adr/0211): who holds it
|
|
229
229
|
* and when it was last uploaded to or opened, never its URL or diagnostics, which stay its owner's.
|
|
230
230
|
*/
|
|
231
231
|
export type OtherPreview = {
|
|
@@ -240,13 +240,13 @@ export type OtherPreview = {
|
|
|
240
240
|
export type PreviewResult = PreviewRow & { schema: DeployResult["schema"] };
|
|
241
241
|
|
|
242
242
|
/**
|
|
243
|
-
* `ez link` (docs/adr/
|
|
243
|
+
* `ez link` (docs/adr/0203): an address that opens the Site's app, or one of the caller's Previews, signed in
|
|
244
244
|
* as the caller's own Member identity. The token is in the fragment; it works once, until `expiresAt`.
|
|
245
245
|
*/
|
|
246
246
|
export type AppLink = { url: string; expiresAt: number };
|
|
247
247
|
|
|
248
248
|
/**
|
|
249
|
-
* `ez support` (docs/adr/
|
|
249
|
+
* `ez support` (docs/adr/0208): a Builder's request to the Host's Developers. `site` is the Site the client
|
|
250
250
|
* was bound to, or null; `diagnostics` are what the Host recorded with it (its build, the client's contract,
|
|
251
251
|
* the opening request's id); `resolution` is the Developer's note on closing, if any.
|
|
252
252
|
*/
|
|
@@ -265,7 +265,7 @@ export type SupportRequest = {
|
|
|
265
265
|
};
|
|
266
266
|
|
|
267
267
|
/**
|
|
268
|
-
* Integrations (docs/adr/
|
|
268
|
+
* Integrations (docs/adr/0231, 0252): an Instance's named external service. Nobody reads a
|
|
269
269
|
* credential back: the wire carries its type, its header or parameter name and its last four characters
|
|
270
270
|
* (`hint`, empty for a value under 8 characters).
|
|
271
271
|
*/
|
|
@@ -274,12 +274,12 @@ export type IntegrationCredentialInfo =
|
|
|
274
274
|
| { type: "query"; param: string; hint: string }
|
|
275
275
|
| { type: "basic"; user: string; hint: string }
|
|
276
276
|
| IntegrationOAuthInfo;
|
|
277
|
-
/** How an OAuth client gets its token (docs/adr/
|
|
277
|
+
/** How an OAuth client gets its token (docs/adr/0252, a draft: only the configuration is built). */
|
|
278
278
|
export type OAuthGrant = "client-credentials" | "password" | "authorization-code";
|
|
279
279
|
/** How the client authenticates at the token endpoint: HTTP Basic, or its id and secret in the form. */
|
|
280
280
|
export type OAuthClientAuth = "basic" | "post";
|
|
281
281
|
/**
|
|
282
|
-
* Whether the Host holds a grant for a binding. Until ADR
|
|
282
|
+
* Whether the Host holds a grant for a binding. Until ADR 0231's flows are built every OAuth binding is
|
|
283
283
|
* `not connected` and its calls are refused `grant`.
|
|
284
284
|
*/
|
|
285
285
|
export type OAuthStatus = "not connected" | "connected" | "needs-reconnect";
|
|
@@ -304,7 +304,7 @@ export type IntegrationOAuthInfo = {
|
|
|
304
304
|
connection: Record<string, string>;
|
|
305
305
|
};
|
|
306
306
|
/**
|
|
307
|
-
* A header or query parameter the Host adds to every request a binding makes (docs/adr/
|
|
307
|
+
* A header or query parameter the Host adds to every request a binding makes (docs/adr/0231). Code can
|
|
308
308
|
* neither set nor override it. A plain one is shown in full; a secret one only by its hint.
|
|
309
309
|
*/
|
|
310
310
|
export type IntegrationValueInfo =
|
|
@@ -331,7 +331,7 @@ export type Integration = {
|
|
|
331
331
|
updatedBy: string;
|
|
332
332
|
/**
|
|
333
333
|
* What `ez integration set` or `preview` removed: the secret values of a binding whose origin changed
|
|
334
|
-
* (docs/adr/
|
|
334
|
+
* (docs/adr/0231). Only on the answer to that command.
|
|
335
335
|
*/
|
|
336
336
|
removedValues?: string[];
|
|
337
337
|
};
|
|
@@ -382,7 +382,7 @@ export type IntegrationPreviewInput =
|
|
|
382
382
|
| { origin: string; credential: IntegrationCredential | null }
|
|
383
383
|
| { production: true }
|
|
384
384
|
| { none: true };
|
|
385
|
-
/** ADR
|
|
385
|
+
/** ADR 0231's refusal categories for an Integration call. */
|
|
386
386
|
export type IntegrationRefusal =
|
|
387
387
|
| "address"
|
|
388
388
|
| "origin"
|
|
@@ -431,7 +431,7 @@ export type IntegrationTest = { path: string; method?: string; preview?: boolean
|
|
|
431
431
|
* A Builder as listed for an Instance (`ez builders`). `role` is their role in *that* Instance; `lastSignInAt`
|
|
432
432
|
* is null until they first sign in anywhere (an unclaimed invite), and `invitedAt` is when they were last
|
|
433
433
|
* invited anywhere: together they say whether the invite is still claimable (`inviteStatus` in the contract,
|
|
434
|
-
* docs/adr/
|
|
434
|
+
* docs/adr/0202). `protected` marks a PROTECTED_ADMINS address.
|
|
435
435
|
*/
|
|
436
436
|
export type BuilderRow = {
|
|
437
437
|
id: string;
|
|
@@ -454,7 +454,7 @@ export type MemberRow = {
|
|
|
454
454
|
memberSince: number;
|
|
455
455
|
lastSignInAt: number | null;
|
|
456
456
|
invitedAt: number | null;
|
|
457
|
-
/** The Member's groups on the roster (docs/adr/
|
|
457
|
+
/** The Member's groups on the roster (docs/adr/0225), sorted. */
|
|
458
458
|
groups: string[];
|
|
459
459
|
};
|
|
460
460
|
|
|
@@ -462,7 +462,7 @@ export type MemberRow = {
|
|
|
462
462
|
export type PersonRow = { id: string; email: string; name: string | null };
|
|
463
463
|
|
|
464
464
|
/** Who may open a Site (`ez site access`): the restricted flag and both allow-lists (empty when unrestricted). */
|
|
465
|
-
/** Who may open a Restricted Site: its Builders, its Members, and the Members of its groups (docs/adr/
|
|
465
|
+
/** Who may open a Restricted Site: its Builders, its Members, and the Members of its groups (docs/adr/0225). */
|
|
466
466
|
export type SiteAccess = {
|
|
467
467
|
restricted: boolean;
|
|
468
468
|
builders: PersonRow[];
|
|
@@ -510,22 +510,22 @@ export type Me = {
|
|
|
510
510
|
/** One entry per Table in the Instance's App Database (`ez db tables`). */
|
|
511
511
|
export type TableInfo = {
|
|
512
512
|
name: string;
|
|
513
|
-
/** column -> description as declared ("TEXT
|
|
513
|
+
/** column -> description as declared ("TEXT REFERENCES people"), or the storage type if nobody declares it */
|
|
514
514
|
columns: Record<string, string>;
|
|
515
515
|
indexes: string[][];
|
|
516
|
-
/** the unique indexes' column lists (docs/adr/
|
|
517
|
-
unique
|
|
516
|
+
/** the unique indexes' column lists (docs/adr/0217); a sequence column has one */
|
|
517
|
+
unique: string[][];
|
|
518
518
|
rows: number;
|
|
519
519
|
/** the Sites of this Instance whose Declaration includes this table */
|
|
520
520
|
sites: string[];
|
|
521
|
-
/** the Table this is the History of (docs/adr/
|
|
521
|
+
/** the Table this is the History of (docs/adr/0218), or null for a Table */
|
|
522
522
|
history: string | null;
|
|
523
523
|
};
|
|
524
524
|
/** `ez db sql`: rows for a read (capped, `truncated` says so), changed-row count for a write. */
|
|
525
525
|
export type SqlResult =
|
|
526
526
|
| { rows: Record<string, unknown>[]; truncated: boolean }
|
|
527
527
|
| { changed: number };
|
|
528
|
-
/** `ez db redact` (docs/adr/
|
|
528
|
+
/** `ez db redact` (docs/adr/0218): declared columns of a Table to blank in its rows and their History. */
|
|
529
529
|
export type RedactInput = {
|
|
530
530
|
table: string;
|
|
531
531
|
columns: string[];
|
|
@@ -538,7 +538,7 @@ export type RedactInput = {
|
|
|
538
538
|
/** Current rows changed, and History rows blanked. */
|
|
539
539
|
export type RedactResult = { changed: number; history: number };
|
|
540
540
|
|
|
541
|
-
/** An Instance asset (`ez asset ls`, docs/adr/
|
|
541
|
+
/** An Instance asset (`ez asset ls`, docs/adr/0213): a name, an immutable object, a frozen URL. */
|
|
542
542
|
export type AssetRow = {
|
|
543
543
|
id: string;
|
|
544
544
|
name: string;
|
|
@@ -551,7 +551,7 @@ export type AssetRow = {
|
|
|
551
551
|
url: string;
|
|
552
552
|
};
|
|
553
553
|
/**
|
|
554
|
-
* An App Attachment (docs/adr/
|
|
554
|
+
* An App Attachment (docs/adr/0221): a file on one FILE column of one row. `row` is null until a row write
|
|
555
555
|
* binds it. `url` is Site-relative: `_ez/attachments/<id>` under any Site's prefix.
|
|
556
556
|
*/
|
|
557
557
|
export type AttachmentRow = {
|
|
@@ -585,7 +585,7 @@ export type UploadTicket = {
|
|
|
585
585
|
upload: { method: "PUT"; url: string; headers: Record<string, string> };
|
|
586
586
|
};
|
|
587
587
|
|
|
588
|
-
// ---- the Builder's wire (docs/adr/
|
|
588
|
+
// ---- the Builder's wire (docs/adr/0209) ----
|
|
589
589
|
|
|
590
590
|
import type { Diagnostic } from "./commands.d.mts";
|
|
591
591
|
export type { Diagnostic };
|
|
@@ -594,13 +594,13 @@ export type { Diagnostic };
|
|
|
594
594
|
export type BuildInput = {
|
|
595
595
|
files: Record<string, string>;
|
|
596
596
|
global?: Record<string, string>;
|
|
597
|
-
/** `types` stops after the Rules and the type check: a Global check's look at each Site (docs/adr/
|
|
598
|
-
* `format` formats the `.ts`/`.tsx` files and answers only the changed ones as `files` (docs/adr/
|
|
597
|
+
/** `types` stops after the Rules and the type check: a Global check's look at each Site (docs/adr/0236).
|
|
598
|
+
* `format` formats the `.ts`/`.tsx` files and answers only the changed ones as `files` (docs/adr/0237).
|
|
599
599
|
* `rules` checks a Global Working Copy with `files` as a stand-in Site and answers its Table rules
|
|
600
|
-
* artifact (docs/adr/
|
|
600
|
+
* artifact (docs/adr/0226) as `files[RULES_ARTIFACT]`. */
|
|
601
601
|
mode: "check" | "build" | "types" | "format" | "rules";
|
|
602
602
|
title?: string;
|
|
603
|
-
/** A Preview build: stamps source locations for the Studio's inspector (docs/adr/
|
|
603
|
+
/** A Preview build: stamps source locations for the Studio's inspector (docs/adr/0212). */
|
|
604
604
|
preview?: boolean;
|
|
605
605
|
};
|
|
606
606
|
export type BuildManifest = { entry: "index.html"; files: string[] };
|
|
@@ -609,20 +609,20 @@ export type FunctionArtifact = {
|
|
|
609
609
|
id: string;
|
|
610
610
|
names: string[];
|
|
611
611
|
/**
|
|
612
|
-
* The functions whose options say `{ api: true }` (docs/adr/
|
|
612
|
+
* The functions whose options say `{ api: true }` (docs/adr/0232): the only ones an API Key may call. The
|
|
613
613
|
* artifact's `__api` entry describes their inputs.
|
|
614
614
|
*/
|
|
615
615
|
api?: string[];
|
|
616
616
|
/**
|
|
617
|
-
* Scheduled jobs (
|
|
617
|
+
* Scheduled jobs (ADR 0230), reached only by a run: an invocation whose context carries `run`. Only
|
|
618
618
|
* the Instance's job artifact, compiled at Global Push, has them.
|
|
619
619
|
*/
|
|
620
620
|
jobs?: string[];
|
|
621
621
|
/**
|
|
622
|
-
* The Integration names each entry's code can reach (ADR
|
|
622
|
+
* The Integration names each entry's code can reach (ADR 0231), following its imports of sibling
|
|
623
623
|
* functions; the Host refuses any other name, and Deploy and Preview check the Integrations' Sites.
|
|
624
624
|
*/
|
|
625
|
-
/** Listeners (docs/adr/
|
|
625
|
+
/** Listeners (docs/adr/0231), reached only by an event: an invocation whose context carries `event`. */
|
|
626
626
|
listeners?: string[];
|
|
627
627
|
integrations?: {
|
|
628
628
|
functions: Record<string, string[]>;
|
|
@@ -631,14 +631,14 @@ export type FunctionArtifact = {
|
|
|
631
631
|
};
|
|
632
632
|
code: string;
|
|
633
633
|
/**
|
|
634
|
-
* A rules artifact's (docs/adr/
|
|
634
|
+
* A rules artifact's (docs/adr/0226, 0227) code per name: a Table's rules or `workflow:<table>`, so a call
|
|
635
635
|
* evaluates that alone. `code` holds them all, and answers any name without a part.
|
|
636
636
|
*/
|
|
637
637
|
parts?: Record<string, string>;
|
|
638
638
|
};
|
|
639
639
|
export type FunctionResult = { result: unknown; artifact: string };
|
|
640
640
|
/**
|
|
641
|
-
* One listeners.json entry (docs/adr/
|
|
641
|
+
* One listeners.json entry (docs/adr/0231): `listeners/<name>.ts`, its events' source and how a delivery is
|
|
642
642
|
* verified. `header` and `idHeader` are the `token` scheme's.
|
|
643
643
|
*/
|
|
644
644
|
export type ListenerEntry = {
|
|
@@ -683,7 +683,7 @@ export type ListenerEvent = {
|
|
|
683
683
|
body?: string;
|
|
684
684
|
};
|
|
685
685
|
/**
|
|
686
|
-
* An API Key as `ez key list` shows it (docs/adr/
|
|
686
|
+
* An API Key as `ez key list` shows it (docs/adr/0232): never the key, only its first characters.
|
|
687
687
|
* `actor` is what History records its writes as; `sites` is whose `{ api: true }` functions it may call.
|
|
688
688
|
*/
|
|
689
689
|
export type ApiKey = {
|
|
@@ -707,7 +707,7 @@ export type ApiKeyInput = {
|
|
|
707
707
|
};
|
|
708
708
|
/** A new API Key: `key` is shown this once and never stored. `url` is the Data API's door. */
|
|
709
709
|
export type CreatedApiKey = { apiKey: ApiKey; key: string; url: string };
|
|
710
|
-
/** One global/schedules.json entry (
|
|
710
|
+
/** One global/schedules.json entry (ADR 0230): run `global/jobs/<job>.ts` with `input` on a UTC `cron`. */
|
|
711
711
|
export type ScheduleEntry = {
|
|
712
712
|
name: string;
|
|
713
713
|
cron: string;
|
|
@@ -715,8 +715,8 @@ export type ScheduleEntry = {
|
|
|
715
715
|
input: Record<string, unknown>;
|
|
716
716
|
};
|
|
717
717
|
/**
|
|
718
|
-
* One of the Instance's schedules (
|
|
719
|
-
* due time by its cron, its latest run, and when and by whom it was paused, or null (ADR
|
|
718
|
+
* One of the Instance's schedules (ADR 0230): its entry, when it last changed or was resumed, its next
|
|
719
|
+
* due time by its cron, its latest run, and when and by whom it was paused, or null (ADR 0230).
|
|
720
720
|
*/
|
|
721
721
|
export type Schedule = ScheduleEntry & {
|
|
722
722
|
since: number;
|
|
@@ -724,7 +724,7 @@ export type Schedule = ScheduleEntry & {
|
|
|
724
724
|
last: ScheduleRun | null;
|
|
725
725
|
paused: { at: number; by: string } | null;
|
|
726
726
|
};
|
|
727
|
-
/** What a scheduled job's context carries as `run` (ADR
|
|
727
|
+
/** What a scheduled job's context carries as `run` (ADR 0230); `due` is ISO, UTC. */
|
|
728
728
|
export type JobRun = { schedule: string; due: string; trigger: "schedule" | "manual" };
|
|
729
729
|
/** One run of a schedule: `due` and the times are ms since the epoch. */
|
|
730
730
|
export type ScheduleRun = {
|
|
@@ -738,16 +738,16 @@ export type ScheduleRun = {
|
|
|
738
738
|
finishedAt: number | null;
|
|
739
739
|
};
|
|
740
740
|
/**
|
|
741
|
-
* What ezship Desktop's preload exposes as `window.ezDesktop` (ADR
|
|
741
|
+
* What ezship Desktop's preload exposes as `window.ezDesktop` (ADR 0235); absent in a browser. `call` runs
|
|
742
742
|
* one local function of the Site under `prefix` from the artifact with that build id and answers its result.
|
|
743
743
|
*/
|
|
744
|
-
/** What the Desktop hands a local function (ADR
|
|
744
|
+
/** What the Desktop hands a local function (ADR 0235): the Member, the Site and this computer's folder for it. */
|
|
745
745
|
export type LocalContext = {
|
|
746
746
|
user: Readonly<{ id: string; email: string; name: string | null }>;
|
|
747
747
|
site: Readonly<{ instance: string; id: string; prefix: string }>;
|
|
748
748
|
desktop: Readonly<{ version: string; dataDir: string }>;
|
|
749
749
|
};
|
|
750
|
-
/** One published Desktop release file (ADR
|
|
750
|
+
/** One published Desktop release file (ADR 0235), as the operator API lists it. */
|
|
751
751
|
export type DesktopFile = {
|
|
752
752
|
filename: string;
|
|
753
753
|
contentType: string;
|
|
@@ -758,7 +758,7 @@ export type DesktopBridge = {
|
|
|
758
758
|
version: string;
|
|
759
759
|
call(prefix: string, artifact: string, name: string, input: unknown): Promise<unknown>;
|
|
760
760
|
};
|
|
761
|
-
/** Private build output (docs/adr/
|
|
761
|
+
/** Private build output (docs/adr/0233): every Global Document of the build's snapshot, compiled for QuickJS. */
|
|
762
762
|
export type DocumentArtifact = { id: string; names: string[]; code: string };
|
|
763
763
|
/** One element of a rendered Document, as the template stage returns it and the renderer reads it. */
|
|
764
764
|
export type DocumentNode = { t: string; p: Record<string, unknown>; c: (DocumentNode | string)[] };
|
|
@@ -775,7 +775,7 @@ export type RenderRequest = RenderOptions & {
|
|
|
775
775
|
preview?: string;
|
|
776
776
|
files?: Record<string, string>;
|
|
777
777
|
};
|
|
778
|
-
/** A Render (docs/adr/
|
|
778
|
+
/** A Render (docs/adr/0233). `file` is its Document File's id once ready; `url` its app-host path. */
|
|
779
779
|
export type RenderRow = {
|
|
780
780
|
id: string;
|
|
781
781
|
site: string;
|
|
@@ -793,7 +793,7 @@ export type RenderRow = {
|
|
|
793
793
|
finishedAt: number | null;
|
|
794
794
|
};
|
|
795
795
|
/**
|
|
796
|
-
* An Email (docs/adr/
|
|
796
|
+
* An Email (docs/adr/0234): `queued` until the runner hands it on, `sending` while it does; `sent` (the mail
|
|
797
797
|
* service accepted it) and `logged` (a Host whose transport is the log) are delivered; `failed` was refused or
|
|
798
798
|
* never delivered within a day; `uncertain` was handed on but its answer was lost, and is never retried;
|
|
799
799
|
* `dropped` was never sent, `reason` says why.
|
|
@@ -840,11 +840,11 @@ export type BuildResult =
|
|
|
840
840
|
ok: true;
|
|
841
841
|
manifest: BuildManifest;
|
|
842
842
|
files: Record<string, string>;
|
|
843
|
-
/** Warnings (severity 2) the build passed with (docs/adr/
|
|
843
|
+
/** Warnings (severity 2) the build passed with (docs/adr/0236); present only when there are some. */
|
|
844
844
|
warnings?: Diagnostic[];
|
|
845
845
|
};
|
|
846
846
|
|
|
847
|
-
/** `ez format` (docs/adr/
|
|
847
|
+
/** `ez format` (docs/adr/0237): the files whose text the formatter changed, or why it could not run. */
|
|
848
848
|
export type FormatResult = { files: Record<string, string>; diagnostics: Diagnostic[] };
|
|
849
849
|
|
|
850
850
|
/** A single-use initial password setup link, returned only to an Admin. */
|
|
@@ -863,7 +863,7 @@ export type DataQuery = {
|
|
|
863
863
|
order?: string[];
|
|
864
864
|
limit?: number;
|
|
865
865
|
offset?: number;
|
|
866
|
-
/** false: past the active scope (docs/adr/
|
|
866
|
+
/** false: past the active scope (docs/adr/0225). */
|
|
867
867
|
scope?: false;
|
|
868
868
|
};
|
|
869
869
|
export type AggregateQuery = {
|
|
@@ -884,21 +884,21 @@ export type DataResult<R = Record<string, unknown>> = {
|
|
|
884
884
|
version: number;
|
|
885
885
|
truncated: boolean;
|
|
886
886
|
/**
|
|
887
|
-
* The version of every Table the query read (docs/adr/
|
|
887
|
+
* The version of every Table the query read (docs/adr/0219): its own, the ones it included and those its
|
|
888
888
|
* where went through. A live query reruns when any of them moves.
|
|
889
889
|
*/
|
|
890
890
|
versions?: Record<string, number>;
|
|
891
|
-
/** Some row's reverse include held more children than it brought (docs/adr/
|
|
891
|
+
/** Some row's reverse include held more children than it brought (docs/adr/0219). */
|
|
892
892
|
truncatedChildren?: true;
|
|
893
893
|
};
|
|
894
894
|
/**
|
|
895
|
-
* The viewer's Session State (docs/adr/
|
|
895
|
+
* The viewer's Session State (docs/adr/0214): what `GET <prefix>/_ez/session` answers and the page config
|
|
896
896
|
* carries. `values` holds only what the viewer stored and the declaration still accepts; defaults fill the rest.
|
|
897
897
|
*/
|
|
898
898
|
export type SessionState = { values: Record<string, unknown>; version: number };
|
|
899
899
|
export type ActorRow = {
|
|
900
900
|
id: string;
|
|
901
|
-
/** Listeners and schedules (docs/adr/
|
|
901
|
+
/** Listeners and schedules (docs/adr/0231, 0230) write as `listener:<site>/<name>`, `schedule:<name>`. */
|
|
902
902
|
kind: "builder" | "user" | "listener" | "schedule";
|
|
903
903
|
name: string;
|
|
904
904
|
email: string;
|
package/update-check.mjs
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// Whether a newer `ez` is on npm (docs/adr/
|
|
1
|
+
// Whether a newer `ez` is on npm (docs/adr/0206): at most one registry request a day, remembered in
|
|
2
2
|
// `~/.ez/update-check.json`, and a one-line notice on standard error at most once a day while one is. Nothing
|
|
3
3
|
// here ever fails a command: an offline machine, a slow registry or an unreadable file mean no notice.
|
|
4
4
|
// Zero dependencies, Node 20+.
|
package/workflow.d.mts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { Declaration } from "./schema.d.mts";
|
|
2
2
|
|
|
3
|
-
/** An action's `from` that lets an insert start with it (docs/adr/
|
|
3
|
+
/** An action's `from` that lets an insert start with it (docs/adr/0227). */
|
|
4
4
|
export const WORKFLOW_NEW: "@new";
|
|
5
5
|
/** An action's `to` that returns the row to the state it had before its current one, from its History. */
|
|
6
6
|
export const WORKFLOW_PREVIOUS: "@previous";
|
|
@@ -44,7 +44,7 @@ export type WorkflowAction = {
|
|
|
44
44
|
/** An automatic action's children: child Table -> its column that references this Table. */
|
|
45
45
|
children?: Record<string, string>;
|
|
46
46
|
};
|
|
47
|
-
/** A Table's workflow (docs/adr/
|
|
47
|
+
/** A Table's workflow (docs/adr/0227) as the Host enforces it, checked at Push. */
|
|
48
48
|
export type WorkflowMeta = {
|
|
49
49
|
column: string;
|
|
50
50
|
initial: string;
|
|
@@ -57,6 +57,12 @@ export function checkWorkflow(
|
|
|
57
57
|
raw: unknown,
|
|
58
58
|
schema: Declaration,
|
|
59
59
|
): { workflow: WorkflowMeta } | { error: string };
|
|
60
|
+
/** What a workflow's written names break of the schema and the naming rule, as a Push would say it; null when none. */
|
|
61
|
+
export function checkWorkflowNames(
|
|
62
|
+
table: string,
|
|
63
|
+
shape: WorkflowShape,
|
|
64
|
+
schema: Declaration,
|
|
65
|
+
): string | null;
|
|
60
66
|
/** Whether the names a file declares are the ones its compiled form describes. */
|
|
61
67
|
export function sameNames(shape: WorkflowShape, meta: WorkflowMeta): boolean;
|
|
62
68
|
/** A name spaced and capitalised: the default label. */
|