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/schema.d.mts CHANGED
@@ -1,6 +1,6 @@
1
1
  // Hand-written declarations for cli/schema.mjs. Keep in step with the JSDoc there.
2
2
 
3
- /** A JSON column's parsed TYPE (docs/adr/0078); `Column.shape` holds its printed form. */
3
+ /** A JSON column's parsed TYPE (docs/adr/0236); `Column.shape` holds its printed form. */
4
4
  export type { Shape } from "./shape.d.mts";
5
5
  import type { IntegrityChange } from "./types.d.mts";
6
6
 
@@ -22,20 +22,20 @@ export type Column = {
22
22
  required: boolean;
23
23
  ref: string | null;
24
24
  values: string[] | null;
25
- /** `INTEGER SEQUENCE` (docs/adr/0046): numbered per Table by the platform; present only when declared. */
25
+ /** `INTEGER SEQUENCE` (docs/adr/0217): numbered per Table by the platform; present only when declared. */
26
26
  sequence?: true;
27
- /** `JSON TYPE '<shape>'` (docs/adr/0078): the printed shape; present only when declared. */
27
+ /** `JSON TYPE '<shape>'` (docs/adr/0236): the printed shape; present only when declared. */
28
28
  shape?: string;
29
- /** `DEFAULT <value>` (docs/adr/0097): what an insert omitting the column stores; present only when declared. */
29
+ /** `DEFAULT <value>` (docs/adr/0224): what an insert omitting the column stores; present only when declared. */
30
30
  default?: ColumnDefault;
31
- /** `REFERENCES <table> ON DELETE RESTRICT` (docs/adr/0109): the referenced row cannot be deleted while referenced. */
31
+ /** `REFERENCES <table> ON DELETE RESTRICT` (docs/adr/0222): the referenced row cannot be deleted while referenced. */
32
32
  onDelete?: "restrict";
33
- /** `LABEL '<label>'` (docs/adr/0109): how forms and lists name the column; present only when declared. */
33
+ /** `LABEL '<label>'` (docs/adr/0222): how forms and lists name the column; present only when declared. */
34
34
  label?: string;
35
- /** The comment on the column's line (docs/adr/0109); present only when written. */
35
+ /** The comment on the column's line (docs/adr/0222); present only when written. */
36
36
  doc?: string;
37
37
  };
38
- /** A declared default (docs/adr/0097): a literal, the insert's time, or the inserting Member. */
38
+ /** A declared default (docs/adr/0224): a literal, the insert's time, or the inserting Member. */
39
39
  export type ColumnDefault =
40
40
  | { kind: "value"; value: string | number | boolean }
41
41
  | { kind: "now" }
@@ -50,22 +50,22 @@ export type DefaultChange = {
50
50
  export type Table = {
51
51
  columns: Record<string, Column>;
52
52
  indexes: string[][];
53
- /** `CREATE UNIQUE INDEX` column lists (docs/adr/0046); absent in Declarations that predate it. */
53
+ /** `CREATE UNIQUE INDEX` column lists (docs/adr/0217); absent in Declarations that predate it. */
54
54
  unique?: string[][];
55
55
  read?: Policy;
56
56
  write?: Policy;
57
- /** Set on a History Table (docs/adr/0040): the Table it records. Never declared. */
57
+ /** Set on a History Table (docs/adr/0218): the Table it records. Never declared. */
58
58
  history?: string;
59
59
  /** Built-in read surface; never accepted in an authored schema. */
60
60
  view?: "actors";
61
- /** `LABEL '<singular>' ['<plural>']` (docs/adr/0109): how a row and the Table are named. */
61
+ /** `LABEL '<singular>' ['<plural>']` (docs/adr/0222): how a row and the Table are named. */
62
62
  label?: string;
63
63
  plural?: string;
64
- /** `DISPLAY (<columns>)` (docs/adr/0109): the one or two columns a reference to a row reads by. */
64
+ /** `DISPLAY (<columns>)` (docs/adr/0222): the one or two columns a reference to a row reads by. */
65
65
  display?: string[];
66
- /** `SINGLETON` (docs/adr/0109): at most one row, enforced by the Host for every writer. */
66
+ /** `SINGLETON` (docs/adr/0222): at most one row, enforced by the Host for every writer. */
67
67
  singleton?: true;
68
- /** `EXACTLY ONE OF (<columns>)` (docs/adr/0109): every row sets exactly one of these columns. */
68
+ /** `EXACTLY ONE OF (<columns>)` (docs/adr/0222): every row sets exactly one of these columns. */
69
69
  exactlyOne?: string[];
70
70
  };
71
71
  /** The parsed schema captured by a Site or Preview from global/db/schema.sql. */
@@ -85,15 +85,15 @@ export const DATABASE_OPERATIONS: Readonly<
85
85
  >;
86
86
  /** One of `DATABASE_OPERATIONS`: a method every `db` has, in a page and on the Host. */
87
87
  export type DatabaseOperation = keyof typeof DATABASE_OPERATIONS;
88
- /** What server code's `db` has beyond `DATABASE_OPERATIONS` (docs/adr/0104), with the argument counts it accepts. */
88
+ /** What server code's `db` has beyond `DATABASE_OPERATIONS` (docs/adr/0228), with the argument counts it accepts. */
89
89
  export const SERVER_DATABASE_OPERATIONS: Readonly<
90
90
  Record<"insertMany" | "updateMany" | "deleteMany", readonly number[]>
91
91
  >;
92
92
  /** One of `SERVER_DATABASE_OPERATIONS`: many rows in one database operation. */
93
93
  export type ServerDatabaseOperation = keyof typeof SERVER_DATABASE_OPERATIONS;
94
- /** The most rows one many-row operation writes (docs/adr/0104). */
94
+ /** The most rows one many-row operation writes (docs/adr/0228). */
95
95
  export const MANY_ROWS: 1000;
96
- /** The longest Push message and write reason (docs/adr/0093), in characters. */
96
+ /** The longest Push message and write reason (docs/adr/0211), in characters. */
97
97
  export const MAX_MESSAGE_CHARS: 500;
98
98
  /** A Push message or write reason as stored: trimmed, null when absent or blank. */
99
99
  export function messageText(
@@ -101,7 +101,7 @@ export function messageText(
101
101
  what: string,
102
102
  ): { text: string | null } | { error: string };
103
103
  export const SYSTEM_COLUMNS: readonly string[];
104
- /** Table History (docs/adr/0040). */
104
+ /** Table History (docs/adr/0218). */
105
105
  export const HISTORY_SUFFIX: "_history";
106
106
  export const HISTORY_OPEN: 253402300799999;
107
107
  export const HISTORY_OPS: readonly ["seed", "insert", "update", "delete"];
@@ -112,15 +112,15 @@ export function historyName(table: string): string;
112
112
  export function historyParent(name: string, names: readonly string[]): string | null;
113
113
  export const NAME_RE: RegExp;
114
114
  export const VALUE_RE: RegExp;
115
- /** What a FILE column holds (docs/adr/0047): an Attachment id. */
115
+ /** What a FILE column holds (docs/adr/0221): an Attachment id. */
116
116
  export const ATTACHMENT_ID_RE: RegExp;
117
- /** What a MEMBER column holds (docs/adr/0098): `user:<id>`. */
117
+ /** What a MEMBER column holds (docs/adr/0225): `user:<id>`. */
118
118
  export const MEMBER_ID_RE: RegExp;
119
- /** A Member group's name (docs/adr/0098). */
119
+ /** A Member group's name (docs/adr/0225). */
120
120
  export const GROUP_RE: RegExp;
121
- /** The most distinct groups an Instance's roster holds (docs/adr/0098). */
121
+ /** The most distinct groups an Instance's roster holds (docs/adr/0225). */
122
122
  export const MAX_GROUPS: 50;
123
- /** The Host's groups (docs/adr/0110): held through the Builder roster, never assigned or declared. */
123
+ /** The Host's groups (docs/adr/0225): held through the Builder roster, never assigned or declared. */
124
124
  export const RESERVED_GROUPS: readonly ["ez-admin", "ez-builder"];
125
125
  /** Whether a group name is the Host's (`ez-` prefixed): no one assigns or declares it. */
126
126
  export function isReservedGroup(name: string): boolean;
@@ -128,19 +128,21 @@ export const RULES: {
128
128
  types: Record<ColumnType, StorageType>;
129
129
  policies: readonly Policy[];
130
130
  refused: Record<string, string>;
131
+ /** Standard SQL read as the Declaration's own form (docs/adr/0204): the spelling, and what it means. */
132
+ accepted: Record<string, string>;
131
133
  reservedNames: readonly string[];
132
134
  limits: { tablesPerInstance: number; columnsPerTable: number; valuesPerCheck: number };
133
135
  };
134
136
 
135
137
  export function parseSchema(sql: string): Declaration | ParseError;
136
- /** Authored global schemas exclude NOT NULL; parseSchema also reads retained legacy declarations. */
138
+ /** The Global Workspace's db/schema.sql, as parseSchema reads it. */
137
139
  export function parseGlobalSchema(sql: string): Declaration | ParseError;
138
140
  export function schemaChangeError(previous: Declaration, next: Declaration): string | null;
139
141
 
140
142
  export type LiveTable = {
141
143
  columns: Record<string, StorageType>;
142
144
  indexes: string[][];
143
- /** The unique indexes' column lists (docs/adr/0046). */
145
+ /** The unique indexes' column lists (docs/adr/0217). */
144
146
  unique?: string[][];
145
147
  };
146
148
  /** GET /api/i/:instance/db/schema: what exists, and every Site's registered Declaration. */
@@ -196,16 +198,6 @@ export function sequenceTriggerStatements(
196
198
  table: string,
197
199
  column: string,
198
200
  ): string[];
199
- export function seedHistoryStatement(
200
- instance: string,
201
- table: string,
202
- columns: Record<string, StorageType>,
203
- ): string;
204
- export function installHistoryStatements(
205
- instance: string,
206
- table: string,
207
- columns: Record<string, StorageType>,
208
- ): string[];
209
201
  export function checkTriggerStatements(
210
202
  instance: string,
211
203
  table: string,
@@ -220,25 +212,29 @@ export function planSchema(
220
212
  schema: LiveSchema,
221
213
  mine: Declaration,
222
214
  instance: string,
223
- siteId: string,
215
+ /** Unused: every Site plans the one published Declaration. */
216
+ siteId?: string,
224
217
  ): Plan | { error: string };
225
218
 
226
219
  export type WhereOp = "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "like";
227
220
  export type Where =
221
+ /** `ne` passes NULL, as `!==` would (docs/adr/0219); the ordering operators and `like` never do. */
228
222
  | { column: string; op: WhereOp; value: string | number }
229
- /** An empty list matches nothing (docs/adr/0102). */
223
+ /** The text itself, `%` and `_` literal; ASCII case is ignored as for `like` (docs/adr/0219). */
224
+ | { column: string; op: "contains" | "startsWith" | "endsWith"; value: string }
225
+ /** An empty list matches nothing (docs/adr/0219). */
230
226
  | { column: string; op: "in"; value: (string | number)[] }
231
- /** None of the values, NULL included; an empty list matches every row (docs/adr/0115). */
227
+ /** None of the values, NULL included; an empty list matches every row (docs/adr/0219). */
232
228
  | { column: string; op: "nin"; value: (string | number)[] }
233
229
  | { column: string; op: "null"; value: boolean }
234
- /** An id list or JSON string[] column holding the value (docs/adr/0102). */
230
+ /** An id list or JSON string[] column holding the value (docs/adr/0219). */
235
231
  | { column: string; op: "has"; value: string }
236
232
  /** Any branch passes; each branch is an AND of its items. */
237
233
  | { op: "or"; items: Where[][] }
238
234
  /** The row `column` references (any of them, for an id list: `many`) passes `where` in `table`. */
239
235
  | { column: string; op: "via"; table: string; many: boolean; where: Where[] };
240
236
  /**
241
- * One include (docs/adr/0102): `row` and `rows` follow the row's `column` (a reference, an id list), `actor`
237
+ * One include (docs/adr/0219): `row` and `rows` follow the row's `column` (a reference, an id list), `actor`
242
238
  * a MEMBER column or created_by/updated_by to `actors`, `children` the rows of `table` whose `column`
243
239
  * references this one. `columns` null is every column; `id` always comes. Lands on the row as `field`.
244
240
  */
@@ -255,7 +251,7 @@ export type Query = {
255
251
  order: [string, "asc" | "desc", ("first" | "last")?][];
256
252
  limit: number;
257
253
  offset: number;
258
- /** `scope: false` (docs/adr/0098): past the active scope. */
254
+ /** `scope: false` (docs/adr/0225): past the active scope. */
259
255
  unscoped?: true;
260
256
  include?: Include[];
261
257
  };
@@ -279,9 +275,9 @@ export function checkQuery(
279
275
  table: Table,
280
276
  tables?: Record<string, Table>,
281
277
  ): Query | { error: string };
282
- /** The Tables a query reads besides its own (docs/adr/0102). */
278
+ /** The Tables a query reads besides its own (docs/adr/0219). */
283
279
  export function queryTables(q: Query): string[];
284
- /** Where an include lands on a row of `table` (docs/adr/0102). */
280
+ /** Where an include lands on a row of `table` (docs/adr/0219). */
285
281
  export function includeField(table: Table, key: string, kind: Include["kind"]): string;
286
282
  /** The children a reverse include brings per row, at most. */
287
283
  export const MAX_CHILDREN: 100;
@@ -309,7 +305,7 @@ export function renderSchema(schema: LiveSchema): string;
309
305
  export const TYPES_HEADER: string;
310
306
  export function aliasName(table: string): string;
311
307
 
312
- /** One column as the record components see it (docs/adr/0109). */
308
+ /** One column as the record components see it (docs/adr/0222). */
313
309
  export type ColumnInfo = {
314
310
  name: string;
315
311
  type: ColumnType;
@@ -326,7 +322,7 @@ export type ColumnInfo = {
326
322
  /** `ON DELETE RESTRICT`. */
327
323
  restrict?: true;
328
324
  };
329
- /** One Table as the record components see it (docs/adr/0109). */
325
+ /** One Table as the record components see it (docs/adr/0222). */
330
326
  export type TableInfo = {
331
327
  name: string;
332
328
  /** How one row is named ("Dealer"), and the Table ("Dealers"). */
@@ -344,19 +340,19 @@ export type TableInfo = {
344
340
  };
345
341
  export type SchemaDescriptor = { tables: Record<string, TableInfo> };
346
342
  export function describeSchema(decl: Declaration): SchemaDescriptor;
347
- /** The SINGLETON, EXACTLY ONE OF and ON DELETE RESTRICT a Push adds or removes (docs/adr/0109). */
343
+ /** The SINGLETON, EXACTLY ONE OF and ON DELETE RESTRICT a Push adds or removes (docs/adr/0222). */
348
344
  export function integrityChanges(previous: Declaration, next: Declaration): IntegrityChange[];
349
345
  export function humanize(name: string): string;
350
346
  export function pluralLabel(label: string): string;
351
347
  /**
352
- * `db/types.d.ts` for a declaration. `workflows` (docs/adr/0103), read from `workflows/<table>.ts` files,
348
+ * `db/types.d.ts` for a declaration. `workflows` (docs/adr/0227), read from `workflows/<table>.ts` files,
353
349
  * type each workflow's column as its states, never null, and declare `Workflows`.
354
350
  */
355
351
  export function generateTypes(
356
352
  declaration: Declaration,
357
353
  workflows?: Record<string, { column: string; states: string[]; actions: string[] }>,
358
354
  ): string;
359
- /** Why a stored value fails the column's DATE or JSON TYPE rule, or null (docs/adr/0078). */
355
+ /** Why a stored value fails the column's DATE or JSON TYPE rule, or null (docs/adr/0236). */
360
356
  export function storedValueError(column: Column, stored: unknown, name: string): string | null;
361
357
  /** New TEXT columns named status, type or *_type without a CHECK list (schema-untyped-enum). */
362
358
  export function untypedEnums(
@@ -364,7 +360,7 @@ export function untypedEnums(
364
360
  previous: Declaration,
365
361
  sql: string,
366
362
  ): { table: string; column: string; line: number }[];
367
- /** New REAL columns named like money (price, amount_due) and not a ratio of it (schema-real-money, ADR 0107). */
363
+ /** New REAL columns named like money (price, amount_due) and not a ratio of it (schema-real-money, ADR 0217). */
368
364
  export function realMoney(
369
365
  next: Declaration,
370
366
  previous: Declaration,