ezship 0.1.15 → 0.1.17

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,7 +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
- /** The longest Push message and write reason (docs/adr/0093), in characters. */
88
+ /** What server code's `db` has beyond `DATABASE_OPERATIONS` (docs/adr/0228), with the argument counts it accepts. */
89
+ export const SERVER_DATABASE_OPERATIONS: Readonly<
90
+ Record<"insertMany" | "updateMany" | "deleteMany", readonly number[]>
91
+ >;
92
+ /** One of `SERVER_DATABASE_OPERATIONS`: many rows in one database operation. */
93
+ export type ServerDatabaseOperation = keyof typeof SERVER_DATABASE_OPERATIONS;
94
+ /** The most rows one many-row operation writes (docs/adr/0228). */
95
+ export const MANY_ROWS: 1000;
96
+ /** The longest Push message and write reason (docs/adr/0211), in characters. */
89
97
  export const MAX_MESSAGE_CHARS: 500;
90
98
  /** A Push message or write reason as stored: trimmed, null when absent or blank. */
91
99
  export function messageText(
@@ -93,7 +101,7 @@ export function messageText(
93
101
  what: string,
94
102
  ): { text: string | null } | { error: string };
95
103
  export const SYSTEM_COLUMNS: readonly string[];
96
- /** Table History (docs/adr/0040). */
104
+ /** Table History (docs/adr/0218). */
97
105
  export const HISTORY_SUFFIX: "_history";
98
106
  export const HISTORY_OPEN: 253402300799999;
99
107
  export const HISTORY_OPS: readonly ["seed", "insert", "update", "delete"];
@@ -104,15 +112,15 @@ export function historyName(table: string): string;
104
112
  export function historyParent(name: string, names: readonly string[]): string | null;
105
113
  export const NAME_RE: RegExp;
106
114
  export const VALUE_RE: RegExp;
107
- /** What a FILE column holds (docs/adr/0047): an Attachment id. */
115
+ /** What a FILE column holds (docs/adr/0221): an Attachment id. */
108
116
  export const ATTACHMENT_ID_RE: RegExp;
109
- /** What a MEMBER column holds (docs/adr/0098): `user:<id>`. */
117
+ /** What a MEMBER column holds (docs/adr/0225): `user:<id>`. */
110
118
  export const MEMBER_ID_RE: RegExp;
111
- /** A Member group's name (docs/adr/0098). */
119
+ /** A Member group's name (docs/adr/0225). */
112
120
  export const GROUP_RE: RegExp;
113
- /** 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). */
114
122
  export const MAX_GROUPS: 50;
115
- /** 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. */
116
124
  export const RESERVED_GROUPS: readonly ["ez-admin", "ez-builder"];
117
125
  /** Whether a group name is the Host's (`ez-` prefixed): no one assigns or declares it. */
118
126
  export function isReservedGroup(name: string): boolean;
@@ -120,19 +128,21 @@ export const RULES: {
120
128
  types: Record<ColumnType, StorageType>;
121
129
  policies: readonly Policy[];
122
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>;
123
133
  reservedNames: readonly string[];
124
134
  limits: { tablesPerInstance: number; columnsPerTable: number; valuesPerCheck: number };
125
135
  };
126
136
 
127
137
  export function parseSchema(sql: string): Declaration | ParseError;
128
- /** Authored global schemas exclude NOT NULL; parseSchema also reads retained legacy declarations. */
138
+ /** The Global Workspace's db/schema.sql, as parseSchema reads it. */
129
139
  export function parseGlobalSchema(sql: string): Declaration | ParseError;
130
140
  export function schemaChangeError(previous: Declaration, next: Declaration): string | null;
131
141
 
132
142
  export type LiveTable = {
133
143
  columns: Record<string, StorageType>;
134
144
  indexes: string[][];
135
- /** The unique indexes' column lists (docs/adr/0046). */
145
+ /** The unique indexes' column lists (docs/adr/0217). */
136
146
  unique?: string[][];
137
147
  };
138
148
  /** GET /api/i/:instance/db/schema: what exists, and every Site's registered Declaration. */
@@ -188,16 +198,6 @@ export function sequenceTriggerStatements(
188
198
  table: string,
189
199
  column: string,
190
200
  ): string[];
191
- export function seedHistoryStatement(
192
- instance: string,
193
- table: string,
194
- columns: Record<string, StorageType>,
195
- ): string;
196
- export function installHistoryStatements(
197
- instance: string,
198
- table: string,
199
- columns: Record<string, StorageType>,
200
- ): string[];
201
201
  export function checkTriggerStatements(
202
202
  instance: string,
203
203
  table: string,
@@ -212,25 +212,29 @@ export function planSchema(
212
212
  schema: LiveSchema,
213
213
  mine: Declaration,
214
214
  instance: string,
215
- siteId: string,
215
+ /** Unused: every Site plans the one published Declaration. */
216
+ siteId?: string,
216
217
  ): Plan | { error: string };
217
218
 
218
219
  export type WhereOp = "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "like";
219
220
  export type Where =
221
+ /** `ne` passes NULL, as `!==` would (docs/adr/0219); the ordering operators and `like` never do. */
220
222
  | { column: string; op: WhereOp; value: string | number }
221
- /** 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). */
222
226
  | { column: string; op: "in"; value: (string | number)[] }
223
- /** 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). */
224
228
  | { column: string; op: "nin"; value: (string | number)[] }
225
229
  | { column: string; op: "null"; value: boolean }
226
- /** 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). */
227
231
  | { column: string; op: "has"; value: string }
228
232
  /** Any branch passes; each branch is an AND of its items. */
229
233
  | { op: "or"; items: Where[][] }
230
234
  /** The row `column` references (any of them, for an id list: `many`) passes `where` in `table`. */
231
235
  | { column: string; op: "via"; table: string; many: boolean; where: Where[] };
232
236
  /**
233
- * 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`
234
238
  * a MEMBER column or created_by/updated_by to `actors`, `children` the rows of `table` whose `column`
235
239
  * references this one. `columns` null is every column; `id` always comes. Lands on the row as `field`.
236
240
  */
@@ -247,7 +251,7 @@ export type Query = {
247
251
  order: [string, "asc" | "desc", ("first" | "last")?][];
248
252
  limit: number;
249
253
  offset: number;
250
- /** `scope: false` (docs/adr/0098): past the active scope. */
254
+ /** `scope: false` (docs/adr/0225): past the active scope. */
251
255
  unscoped?: true;
252
256
  include?: Include[];
253
257
  };
@@ -271,9 +275,9 @@ export function checkQuery(
271
275
  table: Table,
272
276
  tables?: Record<string, Table>,
273
277
  ): Query | { error: string };
274
- /** The Tables a query reads besides its own (docs/adr/0102). */
278
+ /** The Tables a query reads besides its own (docs/adr/0219). */
275
279
  export function queryTables(q: Query): string[];
276
- /** 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). */
277
281
  export function includeField(table: Table, key: string, kind: Include["kind"]): string;
278
282
  /** The children a reverse include brings per row, at most. */
279
283
  export const MAX_CHILDREN: 100;
@@ -301,7 +305,7 @@ export function renderSchema(schema: LiveSchema): string;
301
305
  export const TYPES_HEADER: string;
302
306
  export function aliasName(table: string): string;
303
307
 
304
- /** One column as the record components see it (docs/adr/0109). */
308
+ /** One column as the record components see it (docs/adr/0222). */
305
309
  export type ColumnInfo = {
306
310
  name: string;
307
311
  type: ColumnType;
@@ -318,7 +322,7 @@ export type ColumnInfo = {
318
322
  /** `ON DELETE RESTRICT`. */
319
323
  restrict?: true;
320
324
  };
321
- /** One Table as the record components see it (docs/adr/0109). */
325
+ /** One Table as the record components see it (docs/adr/0222). */
322
326
  export type TableInfo = {
323
327
  name: string;
324
328
  /** How one row is named ("Dealer"), and the Table ("Dealers"). */
@@ -336,19 +340,19 @@ export type TableInfo = {
336
340
  };
337
341
  export type SchemaDescriptor = { tables: Record<string, TableInfo> };
338
342
  export function describeSchema(decl: Declaration): SchemaDescriptor;
339
- /** 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). */
340
344
  export function integrityChanges(previous: Declaration, next: Declaration): IntegrityChange[];
341
345
  export function humanize(name: string): string;
342
346
  export function pluralLabel(label: string): string;
343
347
  /**
344
- * `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,
345
349
  * type each workflow's column as its states, never null, and declare `Workflows`.
346
350
  */
347
351
  export function generateTypes(
348
352
  declaration: Declaration,
349
353
  workflows?: Record<string, { column: string; states: string[]; actions: string[] }>,
350
354
  ): string;
351
- /** 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). */
352
356
  export function storedValueError(column: Column, stored: unknown, name: string): string | null;
353
357
  /** New TEXT columns named status, type or *_type without a CHECK list (schema-untyped-enum). */
354
358
  export function untypedEnums(
@@ -356,7 +360,7 @@ export function untypedEnums(
356
360
  previous: Declaration,
357
361
  sql: string,
358
362
  ): { table: string; column: string; line: number }[];
359
- /** 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). */
360
364
  export function realMoney(
361
365
  next: Declaration,
362
366
  previous: Declaration,