foldkit-entity 0.12.0 → 0.13.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.
@@ -42,6 +42,45 @@ const Collation = {
42
42
  */
43
43
  foldAscii: (text) => text.replace(/[A-Z]+/g, (upper) => upper.toLowerCase())
44
44
  };
45
+ // src/shape.ts
46
+ const isNullish = (ast) => SchemaAST.isNull(ast) || SchemaAST.isUndefined(ast);
47
+ const isText = (ast) => SchemaAST.isString(ast) || SchemaAST.isTemplateLiteral(ast) || SchemaAST.isLiteral(ast) && typeof ast.literal === "string" || SchemaAST.isUnion(ast) && ast.types.length > 0 && ast.types.every(isText);
48
+ /** Whether any of these checks is `Schema.isInt`, alone or inside a group (`isInt32`). */
49
+ const checksInteger = (checks) => checks.some((check) => Match.value(check).pipe(Match.tagsExhaustive({
50
+ Filter: (filter) => filter.annotations?.representation?.id === "effect/schema/isInt",
51
+ FilterGroup: (group) => checksInteger(group.checks)
52
+ })));
53
+ /** What a schema's AST holds, read through Effect's own guards. */
54
+ const SchemaShape = {
55
+ /** True for the `null` and `undefined` members that make a schema optional. */
56
+ isNullish,
57
+ /**
58
+ * The members of a schema with `null` and `undefined` set aside, so optional
59
+ * text is still text; a schema that is not a union is its one member.
60
+ */
61
+ present: (ast) => SchemaAST.isUnion(ast) ? ast.types.filter((member) => !isNullish(member)) : [ast],
62
+ /** True when every value the schema admits is a string. */
63
+ isText,
64
+ /**
65
+ * True when the AST is checked to hold integers (`Schema.isInt`, alone or in
66
+ * a group such as `isInt32`). Read it from a schema's encoded side to ask
67
+ * what the store holds.
68
+ */
69
+ holdsIntegers: (ast) => checksInteger(ast.checks ?? [])
70
+ };
71
+ // src/jsonSchema.ts
72
+ /**
73
+ * A schema's JSON Schema, of what it encodes to as JSON carries it, its
74
+ * definitions kept under `$defs` so a `$ref` in it resolves. Not exported from
75
+ * the package.
76
+ */
77
+ const jsonSchemaOf = (schema) => {
78
+ const document = Schema.toJsonSchemaDocument(schema);
79
+ return Object.keys(document.definitions).length === 0 ? document.schema : {
80
+ ...document.schema,
81
+ $defs: document.definitions
82
+ };
83
+ };
45
84
  // src/law.ts
46
85
  /**
47
86
  * Laws an operator declares (expr-operations-DESIGN §10): equations every
@@ -51,6 +90,16 @@ const Collation = {
51
90
  */
52
91
  const Laws = Data.taggedEnum();
53
92
  const unnarrowed = { domain: Option.none() };
93
+ /**
94
+ * A law as JSON says it: what `Operators.describe` lists and evidence names.
95
+ * Its witnesses are values as stored and operators by name; its domain is a
96
+ * JSON Schema, or `null` for the operator's whole input.
97
+ */
98
+ const LawDescription = Schema.Struct({
99
+ kind: Schema.String,
100
+ witnesses: Schema.Record(Schema.String, Schema.Unknown),
101
+ domain: Schema.Unknown
102
+ });
54
103
  /** An operator by its id, and its version when that is not the first. */
55
104
  const nameOf$1 = (operator) => operator.descriptor.version === 1 ? operator.descriptor.id : `${operator.descriptor.id}@${operator.descriptor.version}`;
56
105
  const Law = {
@@ -97,6 +146,12 @@ const Law = {
97
146
  domain: Option.some(domain)
98
147
  }),
99
148
  $match: Laws.$match,
149
+ /**
150
+ * The operators a law, as JSON, calls besides its own (`inverse`'s and
151
+ * `distributes`' witnesses), by name: evidence of it is of their
152
+ * implementations too, and goes when one of them is replaced.
153
+ */
154
+ witnessesNamed: (law) => [law.witnesses["other"], law.witnesses["over"]].filter((name) => typeof name === "string"),
100
155
  /** The law as JSON: its kind, its witnesses (operators by name) and its domain's JSON Schema. */
101
156
  describe: (law) => {
102
157
  const witnesses = Laws.$match(law, {
@@ -127,7 +182,7 @@ const Law = {
127
182
  witnesses,
128
183
  domain: Option.match(law.domain, {
129
184
  onNone: () => null,
130
- onSome: (domain) => Schema.toJsonSchemaDocument(domain).schema
185
+ onSome: jsonSchemaOf
131
186
  })
132
187
  };
133
188
  }
@@ -147,7 +202,22 @@ const Law = {
147
202
  * from queries, not from what a database could express.
148
203
  */
149
204
  /** A table implementing nothing: every primitive operator is unsupported by it. */
150
- const noOperators = Object.freeze({ has: () => false });
205
+ const noOperators = Object.freeze({
206
+ has: () => false,
207
+ versions: () => []
208
+ });
209
+ /**
210
+ * An operator `operators` does not implement, by name, with the versions of it
211
+ * the table does implement: `acme.slug@2 (this table has acme.slug)`.
212
+ */
213
+ const missingName = (operator, operators) => {
214
+ const held = operators.versions(operator.id);
215
+ if (held.includes(operator.version)) return `${operatorName$1(operator)} (this table has another declaration of it; declare an operator once and import it)`;
216
+ return held.length === 0 ? operatorName$1(operator) : `${operatorName$1(operator)} (this table has ${held.map((version) => operatorName$1({
217
+ ...operator,
218
+ version
219
+ })).join(", ")})`;
220
+ };
151
221
  const tagOf = (value) => typeof value === "object" && value !== null && "_tag" in value ? value._tag : void 0;
152
222
  /**
153
223
  * An Entity's field and a `FieldExpr` are the same three members under the same
@@ -192,6 +262,7 @@ const isPredicate = (value) => predicateTags.has(tagOf(value));
192
262
  */
193
263
  const toOperand = (value) => {
194
264
  const tag = tagOf(value);
265
+ if (tag === "Field" && !Object.hasOwn(value, "metadata")) return value;
195
266
  if (tag === "Field") return fieldExpr(value);
196
267
  if (tag === "Literal" || tag === "Input" || tag === "Next" || tag === "Call" || predicateTags.has(tag)) return value;
197
268
  return literal(value);
@@ -320,7 +391,7 @@ const callOptionsOf = (id, value) => {
320
391
  /** A collation a call was given: one its operator compares by, and portable where required. */
321
392
  const givenCollation = (id, descriptor, collation) => {
322
393
  if (Option.isSome(descriptor.definedAs) || descriptor.collation === "none") throw new Error(`[foldkit-entity] ${id}: takes no collation; it compares no text of its own`);
323
- if (descriptor.collation === "required" && collation._tag === "Locale") throw new Error(`[foldkit-entity] ${id}: compares by the backend's "${collation.locale}" collation, which only that backend has`);
394
+ if (collation._tag === "Locale") throw new Error(`[foldkit-entity] ${id}: compares by the backend's "${collation.locale}" collation, which only that backend has`);
324
395
  return Option.some(collation);
325
396
  };
326
397
  /** Namespaced, lower camel case: `cms.published`, `text.startsWith`. */
@@ -350,6 +421,23 @@ const lawProblem = (law, input, output, collation) => {
350
421
  };
351
422
  /** Whether a schema's stored form is a boolean, which makes its operator a predicate. */
352
423
  const storedAsBoolean = (schema) => SchemaAST.isBoolean(Schema.toEncoded(schema).ast);
424
+ /** What a schema stores, null aside: one kind an argument is checked by, or `other`. */
425
+ const storedKindOf = (schema) => {
426
+ const present = SchemaShape.present(Schema.toEncoded(schema).ast);
427
+ if (present.length === 0) return "other";
428
+ if (present.every(SchemaAST.isNumber)) return "number";
429
+ if (present.every(SchemaShape.isText)) return "text";
430
+ if (present.every(SchemaAST.isBoolean)) return "boolean";
431
+ return "other";
432
+ };
433
+ /** The schema a scalar's values are stored by. */
434
+ const scalarSchema = (scalar) => Match.value(scalar).pipe(Match.tagsExhaustive({
435
+ Field: (field) => field.schema,
436
+ Next: ({ field }) => field.schema,
437
+ Input: (input) => input.schema,
438
+ Literal: () => Schema.Unknown,
439
+ Call: ({ operator }) => operator.output
440
+ }));
353
441
  /** Every field, field after a write, and input an expression reads, as keys to compare. */
354
442
  const readKeys = (...nodes) => {
355
443
  const read = dependenciesOf(...nodes);
@@ -374,9 +462,9 @@ const argumentFor = (id, position, schema, value) => {
374
462
  if (!Schema.is(Schema.toEncoded(schema))(arg.value)) fail(`is ${JSON.stringify(arg.value)}, which the operator's input schema does not admit`);
375
463
  return arg;
376
464
  }
377
- const wanted = orderKindOf(Schema.toEncoded(schema).ast);
378
- const given = sideKind(arg);
379
- if (wanted !== "none" && (given === "number" || given === "text") && given !== wanted) fail(`is stored as ${given}, but the operator takes ${wanted}`);
465
+ const wanted = storedKindOf(schema);
466
+ const given = storedKindOf(scalarSchema(arg));
467
+ if (wanted !== "other" && given !== "other" && given !== wanted) fail(`is stored as ${given}, but the operator takes ${wanted}`);
380
468
  return arg;
381
469
  };
382
470
  /** A scalar's collation: a field's declared one, or a call's. */
@@ -398,17 +486,17 @@ const callCollation = (id, rule, args) => {
398
486
  throw new Error(`[foldkit-entity] ${id}: ${what}`);
399
487
  };
400
488
  const voters = args.flatMap((arg) => isPredicate(arg) || arg._tag === "Literal" || arg._tag === "Input" || sideKind(arg) !== "text" ? [] : [{
401
- name: showExpr(arg),
489
+ arg,
402
490
  collation: collationOf(arg)
403
491
  }]);
404
- const collations = voters.flatMap(({ name, collation }) => Option.match(collation, {
492
+ const collations = voters.flatMap(({ arg, collation }) => Option.match(collation, {
405
493
  onSome: (each) => [each],
406
- onNone: () => rule === "required" ? fail(`${name} is text with no declared collation, so backends would compare it differently; declare Collation.binary or Collation.asciiFold on it`) : []
494
+ onNone: () => rule === "required" ? fail(`${showExpr(arg)} is text with no declared collation, so backends would compare it differently; declare Collation.binary or Collation.asciiFold on it`) : []
407
495
  }));
408
496
  const [shared] = collations;
409
497
  if (shared === void 0) return rule === "required" ? fail("compares text with no field or call holding a collation") : Option.none();
410
- if (collations.some((each) => each._tag !== shared._tag)) fail(`${voters.map((voter) => voter.name).join(" and ")} declare different collations`);
411
- if (rule === "required" && shared._tag === "Locale") fail(`compares by the backend's "${shared.locale}" collation, which only that backend has`);
498
+ if (collations.some((each) => each._tag !== shared._tag)) fail(`${voters.map((voter) => showExpr(voter.arg)).join(" and ")} declare different collations`);
499
+ if (shared._tag === "Locale") fail(`compares by the backend's "${shared.locale}" collation, which a call cannot carry`);
412
500
  return Option.some(shared);
413
501
  };
414
502
  /** Builds an operator: checks what it is given once, then each call. */
@@ -595,6 +683,22 @@ const Expr = {
595
683
  * out. A call with no definition stays, for the interpreter to run or refuse
596
684
  * by name.
597
685
  */
686
+ /**
687
+ * Whether a constant written in these expressions is text holding a NUL, or
688
+ * a list holding one: SQL refuses such a parameter wherever it compiles, so
689
+ * an interpreter refuses the run, not one row.
690
+ */
691
+ givesNul: (...nodes) => {
692
+ const seen = /* @__PURE__ */ new Set();
693
+ const nul = (value) => typeof value === "string" && value.includes(String.fromCharCode(0));
694
+ const walk = (node) => {
695
+ if (seen.has(node)) return false;
696
+ seen.add(node);
697
+ if (node._tag === "Literal") return Array.isArray(node.value) ? node.value.some(nul) : nul(node.value);
698
+ return childrenOf(node).some(walk);
699
+ };
700
+ return nodes.some(walk);
701
+ },
598
702
  expanded: (node) => isPredicate(node) ? expandedPredicate(node) : expandedScalar(node),
599
703
  /**
600
704
  * What these expressions need that an interpreter lacks, as `Query.unsupported`
@@ -672,11 +776,15 @@ const Expr = {
672
776
  * nullable column that should match everything on an empty search says so:
673
777
  * `Expr.or(Expr.isNull(field), Expr.contains(field, input.search))`.
674
778
  */
675
- contains: (value, search) => node({
676
- _tag: "Contains",
677
- value: toExpr(value, "contains"),
678
- search: toOperand(search)
679
- }),
779
+ contains: (value, search) => {
780
+ const operand = toOperand(search);
781
+ if (operand._tag !== "Literal" && operand._tag !== "Input") throw new Error(`[foldkit-entity] Expr.contains: the search is ${showExpr(operand)}; search for a value or an input`);
782
+ return node({
783
+ _tag: "Contains",
784
+ value: toExpr(value, "contains"),
785
+ search: operand
786
+ });
787
+ },
680
788
  /**
681
789
  * Whether a value is one of `among`: a list written out, or an input whose
682
790
  * value is one. Each element is compared as `eq` compares.
@@ -826,7 +934,9 @@ const substituted = (predicate, rewrite) => {
826
934
  };
827
935
  /** A term, its nulls placed by `options` or by the direction's default. */
828
936
  const term = (direction, expr, options = {}) => {
829
- const collation = Option.orElse(Option.fromUndefinedOr(options.collation), () => Match.value(expr).pipe(Match.tag("Field", (field) => field.collation), Match.tag("Call", (call) => call.collation), Match.orElse(() => Option.none())));
937
+ const number = sideKind(expr) === "number";
938
+ if (number && options.collation !== void 0) throw new Error(`[foldkit-entity] Order: ${showExpr(expr)} is a number, which needs no collation; a collation orders text`);
939
+ const collation = number ? Option.none() : Option.orElse(Option.fromUndefinedOr(options.collation), () => Match.value(expr).pipe(Match.tag("Field", (field) => field.collation), Match.tag("Call", (call) => call.collation), Match.orElse(() => Option.none())));
830
940
  if (expr._tag === "Call") orderableCall(expr, collation);
831
941
  return node({
832
942
  _tag: "Term",
@@ -1160,6 +1270,19 @@ const query = (entity, where, orderBy) => Object.freeze(Object.assign(Object.cre
1160
1270
  where: Object.freeze(where),
1161
1271
  orderBy: Object.freeze(orderBy)
1162
1272
  }));
1273
+ /**
1274
+ * Refuses a query whose predicates and order terms (every chosen alternative
1275
+ * among them) expand past `maxQueryNodes`, counting a shared node on every
1276
+ * path that reaches it: what an interpreter walks, and SQL writes out.
1277
+ */
1278
+ const checkSize = (step, where, orderBy) => {
1279
+ const sizes = /* @__PURE__ */ new Map();
1280
+ const terms = orderBy.flatMap((ordering) => Match.valueTags(ordering, {
1281
+ Term: ({ expr }) => [expr],
1282
+ Chosen: ({ choices }) => Object.values(choices)
1283
+ }));
1284
+ if ([...where, ...terms].reduce((sum, each) => sum + expandedSize(each, sizes), 0) > 1e3) throw new Error(`[foldkit-entity] Query.${step}: the query expands to more than ${maxQueryNodes} nodes, counting a shared node on every path that reaches it`);
1285
+ };
1163
1286
  const Query = {
1164
1287
  /** Every row of an Entity: the query each transformation narrows. */
1165
1288
  from: (entity) => query(entity, [], []),
@@ -1177,8 +1300,7 @@ const Query = {
1177
1300
  if (predicates.length === 0) return self;
1178
1301
  checkOwnership("where", "a predicate", self.entity, predicates);
1179
1302
  const where = [...self.where, ...predicates];
1180
- const sizes = /* @__PURE__ */ new Map();
1181
- if (where.reduce((sum, predicate) => sum + expandedSize(predicate, sizes), 0) > 1e3) throw new Error(`[foldkit-entity] Query.where: the predicates expand to more than ${maxQueryNodes} nodes, counting a shared node on every path that reaches it`);
1303
+ checkSize("where", where, self.orderBy);
1182
1304
  return query(self.entity, where, self.orderBy);
1183
1305
  },
1184
1306
  /**
@@ -1189,7 +1311,9 @@ const Query = {
1189
1311
  orderBy: (...terms) => (self) => {
1190
1312
  if (terms.length === 0) return self;
1191
1313
  checkOwnership("orderBy", "a term", self.entity, terms);
1192
- return query(self.entity, self.where, [...self.orderBy, ...terms]);
1314
+ const orderBy = [...self.orderBy, ...terms];
1315
+ checkSize("orderBy", self.where, orderBy);
1316
+ return query(self.entity, self.where, orderBy);
1193
1317
  },
1194
1318
  /**
1195
1319
  * The fixed terms this query orders by for one input: each chosen order
@@ -1223,6 +1347,12 @@ const Query = {
1223
1347
  return placeable;
1224
1348
  },
1225
1349
  /**
1350
+ * Each operator the body calls, by name (`id`, or `id@version` past the
1351
+ * first), in the order it first calls them: a defined one, and each
1352
+ * primitive one its expansion calls.
1353
+ */
1354
+ operators: (self) => Query.dependencies(self).operators.map(operatorName$1),
1355
+ /**
1226
1356
  * What the whole query reads: the fields and inputs of every predicate and
1227
1357
  * every ordering term, and the operations it uses, with the fields also
1228
1358
  * split by role.
@@ -1324,7 +1454,7 @@ const unsupportedIn = (nodes, supported, operators) => {
1324
1454
  * The primitive operators among `read` that `operators` does not implement, by
1325
1455
  * name. A defined one needs nothing: what it means was walked into `read`.
1326
1456
  */
1327
- const missingFrom = (read, operators) => read.filter((operator) => Option.isNone(operator.definedAs) && !operators.has(operator)).map(operatorName$1);
1457
+ const missingFrom = (read, operators) => read.filter((operator) => Option.isNone(operator.definedAs) && !operators.has(operator)).map((operator) => missingName(operator, operators));
1328
1458
  /** An operator by its id, and its version when that is not the first. */
1329
1459
  const operatorName$1 = (operator) => operator.version === 1 ? operator.id : `${operator.id}@${operator.version}`;
1330
1460
  const symbols = {
@@ -1339,6 +1469,25 @@ const showConnected = (node) => Match.value(node).pipe(Match.tags({
1339
1469
  Or: () => `(${showExpr(node)})`
1340
1470
  }), Match.orElse(() => showExpr(node)));
1341
1471
  const showOperand = (node) => isPredicate(node) ? `(${showExpr(node)})` : showExpr(node);
1472
+ // src/tested.ts
1473
+ /**
1474
+ * What made each `Tested` record: `Conformance.laws` over one memory
1475
+ * implementation, or `Conformance.lawsBy` through a runner. A table records
1476
+ * only evidence of its own kind, so a record built by hand, copied, or tested
1477
+ * on another implementation is refused. Kept beside the records rather than in
1478
+ * them: a record is JSON a server publishes, and an implementation is a
1479
+ * function. Not exported from the package.
1480
+ */
1481
+ const testedOn = /* @__PURE__ */ new WeakMap();
1482
+ const ranByRunner = /* @__PURE__ */ new WeakSet();
1483
+ const stampTested = (record, implementation) => {
1484
+ testedOn.set(record, implementation);
1485
+ };
1486
+ const stampRun = (record) => {
1487
+ ranByRunner.add(record);
1488
+ };
1489
+ const implementationTested = (record) => Option.fromUndefinedOr(testedOn.get(record));
1490
+ const testedByRunner = (record) => ranByRunner.has(record);
1342
1491
  // src/text.ts
1343
1492
  /**
1344
1493
  * The kernel's text operators: primitive, so each interpreter implements them,
@@ -1354,9 +1503,11 @@ const Text = {
1354
1503
  * | the prefix is `''` | true |
1355
1504
  * | otherwise | whether it begins so, compared under the collation |
1356
1505
  *
1357
- * The collation is the text's: a field's declared one, or a call's. `binary`
1358
- * compares exactly; `asciiFold` folds ASCII letters on both sides. Text with
1359
- * none, or with a backend's locale, is refused where the call is written.
1506
+ * The collation is the one its text operands share (a field's declared one,
1507
+ * or a call's), or one given to the call. `binary` compares exactly;
1508
+ * `asciiFold` folds ASCII letters on both sides. Operands declaring
1509
+ * different collations, text with none, or a backend's locale are refused
1510
+ * where the call is written.
1360
1511
  * Prefixes are by character, so non-ASCII and astral text begin as they read.
1361
1512
  *
1362
1513
  * ```ts
@@ -1377,6 +1528,43 @@ startsWith: Expr.operator("text.startsWith", {
1377
1528
  * globally. See `docs/design/expr-operations-DESIGN.md` §5.4.
1378
1529
  */
1379
1530
  const Evidence = Data.taggedEnum();
1531
+ /** A JSON Schema document's root: an object (`$defs` holds what it refers to). */
1532
+ const JsonSchema = Schema.Record(Schema.String, Schema.Unknown);
1533
+ /**
1534
+ * An operator as JSON, by its signature and never its body (a defined
1535
+ * operator says `defined`, not what it means): what a server can publish of
1536
+ * what a body may call, and a client compare with what it runs. Its schemas
1537
+ * are each argument's and the result's stored side, as JSON Schemas.
1538
+ */
1539
+ const OperatorDescription = Schema.Struct({
1540
+ /** By id, and `@version` past the first: what tables, evidence and refusals name. */
1541
+ name: Schema.String,
1542
+ id: Schema.String,
1543
+ version: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)),
1544
+ description: Schema.NullOr(Schema.String),
1545
+ input: Schema.Array(JsonSchema),
1546
+ output: JsonSchema,
1547
+ nulls: Schema.Literals(["strict", "handled"]),
1548
+ collation: Schema.Literals([
1549
+ "none",
1550
+ "operands",
1551
+ "required"
1552
+ ]),
1553
+ laws: Schema.Array(LawDescription),
1554
+ defined: Schema.Boolean
1555
+ });
1556
+ const described = (operator) => ({
1557
+ name: nameOf(operator),
1558
+ id: operator.id,
1559
+ version: operator.version,
1560
+ description: Option.getOrNull(operator.description),
1561
+ input: operator.input.map(jsonSchemaOf),
1562
+ output: jsonSchemaOf(operator.output),
1563
+ nulls: operator.nulls,
1564
+ collation: operator.collation,
1565
+ laws: operator.laws.map(Law.describe),
1566
+ defined: Option.isSome(operator.definedAs)
1567
+ });
1380
1568
  /** An operator by its id, and its version when that is not the first. */
1381
1569
  const nameOf = (operator) => operator.version === 1 ? operator.id : `${operator.id}@${operator.version}`;
1382
1570
  const fail$3 = (what) => {
@@ -1395,7 +1583,9 @@ const table = (implementations, checked, evidence) => {
1395
1583
  return Object.freeze({
1396
1584
  _tag: "MemoryOperators",
1397
1585
  has: (operator) => byOperator.has(operator),
1586
+ versions: (id) => implementations.filter(({ operator }) => operator.id === id).map(({ operator }) => operator.version),
1398
1587
  get: (operator) => Option.fromUndefinedOr(byOperator.get(operator)),
1588
+ named: (name) => Option.fromUndefinedOr(byName.get(name)),
1399
1589
  checked,
1400
1590
  implementations: Object.freeze([...implementations]),
1401
1591
  evidence: Object.freeze([...evidence])
@@ -1405,6 +1595,7 @@ const table = (implementations, checked, evidence) => {
1405
1595
  const sameLaw = (left, right) => JSON.stringify(left) === JSON.stringify(right);
1406
1596
  /** An implementation, its operator's null rule checked against the function chosen for it. */
1407
1597
  const implementation = (operator, nulls, run) => {
1598
+ if (Option.isSome(operator.definedAs)) fail$3(`${nameOf(operator)} is defined by an expression, which every interpreter runs; it takes no implementation`);
1408
1599
  if (operator.nulls !== nulls) fail$3(nulls === "strict" ? `${nameOf(operator)} handles null itself; implement it with Operators.implementHandlingNulls` : `${nameOf(operator)} is strict about null; implement it with Operators.implement`);
1409
1600
  return Object.freeze({
1410
1601
  operator,
@@ -1443,30 +1634,53 @@ const Operators = {
1443
1634
  override: (base, ...implementations) => {
1444
1635
  const replaced = new Set(implementations.map(({ operator }) => operator));
1445
1636
  const names = new Set([...replaced].map(nameOf));
1446
- return table([...base.implementations.filter(({ operator }) => !replaced.has(operator)), ...implementations], base.checked, base.evidence.filter(({ operator }) => !names.has(operator)));
1637
+ return table([...base.implementations.filter(({ operator }) => !replaced.has(operator)), ...implementations], base.checked, base.evidence.filter(({ operator, law }) => !names.has(operator) && !Law.witnessesNamed(law).some((name) => names.has(name))));
1447
1638
  },
1448
1639
  /**
1449
1640
  * The table with what is known of its implementations' laws recorded: each
1450
1641
  * record of an operator it implements and a law that operator declares.
1451
- * `Conformance.laws` gives `Tested` records; `Evidence.Proven` says a proof
1452
- * elsewhere covers one.
1642
+ * `Conformance.laws` gives `Tested` records, each of the implementation it
1643
+ * ran, and a table takes only those of its own; `Evidence.Proven` says a
1644
+ * proof elsewhere covers one.
1453
1645
  */
1454
1646
  withEvidence: (base, evidence) => {
1455
- const declared = new Map(base.implementations.map(({ operator }) => [nameOf(operator), operator.laws.map(Law.describe)]));
1456
- for (const record of evidence) if (!(declared.get(record.operator) ?? fail$3(`evidence names ${record.operator}, which this table does not implement`)).some((law) => sameLaw(law, record.law))) fail$3(`evidence names a law of ${record.operator} it does not declare (${record.law.kind})`);
1647
+ const own = new Map(base.implementations.map((each) => [nameOf(each.operator), each]));
1648
+ for (const record of evidence) {
1649
+ const implemented = own.get(record.operator) ?? fail$3(`evidence names ${record.operator}, which this table does not implement`);
1650
+ if (!implemented.operator.laws.map(Law.describe).some((law) => sameLaw(law, record.law))) fail$3(`evidence names a law of ${record.operator} it does not declare (${record.law.kind})`);
1651
+ if (record._tag === "Tested" && !Option.exists(implementationTested(record), (tested) => tested === implemented)) fail$3(`evidence of ${record.operator}'s ${record.law.kind} law was not tested on this table's implementation; test it with Conformance.laws(op, table)`);
1652
+ }
1457
1653
  return table(base.implementations, base.checked, [...base.evidence, ...evidence]);
1458
1654
  },
1459
1655
  /**
1656
+ * The memory implementation `Conformance.laws` tested a record on; none for
1657
+ * a record of a runner (`Conformance.lawsBy`) or a proof.
1658
+ */
1659
+ testedOn: (record) => implementationTested(record),
1660
+ /**
1661
+ * Whether `Conformance.lawsBy` made a record, through a runner: what an SQL
1662
+ * table takes. Which runner it was, the database's or another, is the
1663
+ * caller's word; a record built by hand, copied, or tested in memory is not.
1664
+ */
1665
+ testedByRunner,
1666
+ /**
1460
1667
  * Each operator the table implements, by name, with the laws it declares and
1461
1668
  * the evidence the table records of them: what a server can publish of how
1462
1669
  * it runs a body. JSON as it is.
1463
1670
  */
1464
1671
  describeTable: (base) => base.implementations.map(({ operator }) => ({
1465
- operator: nameOf(operator),
1466
- laws: operator.laws.map(Law.describe),
1672
+ ...described(operator),
1467
1673
  evidence: base.evidence.filter((record) => record.operator === nameOf(operator))
1468
1674
  })),
1469
1675
  /**
1676
+ * An operator as JSON (`OperatorDescription`): its name, version and
1677
+ * description, each argument's and its result's stored side as a JSON
1678
+ * Schema (as JSON carries it: a number also admits the strings `"Infinity"`,
1679
+ * `"-Infinity"` and `"NaN"`), its null and collation rules, its laws, and
1680
+ * whether it is defined. Its signature, never its body.
1681
+ */
1682
+ describe: (operator) => described(operator.descriptor),
1683
+ /**
1470
1684
  * The table, checking every answer against its operator's output schema, so
1471
1685
  * an implementation that answers the wrong kind fails where it answered. For
1472
1686
  * tests: it costs a decode per call.
@@ -1518,8 +1732,9 @@ var OperatorMissingError = class extends QueryEvaluateError {
1518
1732
  operator;
1519
1733
  /** The operator by its id, and its version past the first. */
1520
1734
  named;
1521
- constructor(operator) {
1522
- super(`this interpreter does not run the operator "${operatorName(operator)}"`);
1735
+ /** `operators`, the table that lacks it, names the versions of it that it does hold. */
1736
+ constructor(operator, operators = noOperators) {
1737
+ super(`this interpreter does not run the operator "${missingName(operator, operators)}"`);
1523
1738
  this.name = "OperatorMissingError";
1524
1739
  this.operator = operator;
1525
1740
  this.named = operatorName(operator);
@@ -1539,42 +1754,52 @@ const valueOf = (node, scope) => {
1539
1754
  };
1540
1755
  /**
1541
1756
  * What a call comes to, as a value (a predicate's truth as SQL's, unknown as
1542
- * null). The table's implementation when it has one; else, for a defined
1543
- * operator, what it means; else it is refused by name.
1757
+ * null). A defined operator's is what it means, as SQL compiles it; a
1758
+ * primitive one's is the table's implementation, or it is refused by name.
1544
1759
  */
1545
1760
  const called = (call, scope) => {
1546
1761
  const expansion = call.expansion;
1547
- return Option.match(scope.operators.get(call.operator), {
1548
- onSome: (run) => ran(call, run, scope),
1549
- onNone: () => Option.match(expansion, {
1550
- onSome: (body) => sideOf(body, scope),
1762
+ return Option.match(expansion, {
1763
+ onSome: (body) => sideOf(body, scope),
1764
+ onNone: () => Option.match(scope.operators.get(call.operator), {
1765
+ onSome: (run) => ran(call, run, scope),
1551
1766
  onNone: () => {
1552
- throw new OperatorMissingError(call.operator);
1767
+ throw new OperatorMissingError(call.operator, scope.operators);
1553
1768
  }
1554
1769
  })
1555
1770
  });
1556
1771
  };
1772
+ /** A call of a primitive operator run, its arguments worked out over the scope. */
1773
+ const ran = (call, run, scope) => runWith(call.operator, run, call.args.map((arg) => sideOf(arg, scope)), call.collation, call._tag === "Test", scope.operators.checked);
1557
1774
  /**
1558
- * A primitive operator run: strict about null and NUL before it is asked, a
1559
- * throw it makes named as its own, and, in a checked table, its answer held to
1560
- * its output schema.
1775
+ * A primitive operator run over values: strict about null and NUL before it
1776
+ * is asked, a throw it makes named as its own, and, in a checked table, its
1777
+ * answer held to its output schema (a predicate's null is its unknown).
1561
1778
  */
1562
- const ran = (call, run, scope) => {
1563
- const { operator } = call;
1564
- const values = call.args.map((arg) => sideOf(arg, scope));
1779
+ const runWith = (operator, run, values, collation, predicate, checked) => {
1565
1780
  if (values.some(holdsNul)) throw new QueryEvaluateError(`the operator "${operatorName(operator)}" was given text holding a NUL character, which SQL text cannot hold portably`);
1566
1781
  if (operator.nulls === "strict" && values.some(isNull)) return null;
1567
1782
  let answer;
1568
1783
  try {
1569
- answer = run(values, { collation: call.collation });
1784
+ answer = run(values.map((value) => value === void 0 ? null : value), { collation });
1570
1785
  } catch (error) {
1571
1786
  if (error instanceof QueryEvaluateError) throw error;
1572
1787
  throw new QueryEvaluateError(`the operator "${operatorName(operator)}" failed: ${error instanceof Error ? error.message : String(error)}`);
1573
1788
  }
1574
- const unknownTruth = call._tag === "Test" && answer === null;
1575
- if (scope.operators.checked && !unknownTruth && !Schema.is(Schema.toEncoded(operator.output))(answer)) throw new QueryEvaluateError(`the operator "${operatorName(operator)}" answered ${JSON.stringify(answer)}, which its output schema does not admit`);
1789
+ if (checked && !(predicate && answer === null) && !Schema.is(Schema.toEncoded(operator.output))(answer)) throw new QueryEvaluateError(`the operator "${operatorName(operator)}" answered ${JSON.stringify(answer)}, which its output schema does not admit`);
1576
1790
  return answer;
1577
1791
  };
1792
+ /**
1793
+ * A primitive operator over stored values, as a call of it is run: what a
1794
+ * computed assignment comes to (`Write.apply`). Refused, as a call is, when
1795
+ * `operators` does not implement it.
1796
+ */
1797
+ const applyOperator = (operator, values, options) => Option.match(options.operators.get(operator), {
1798
+ onNone: () => {
1799
+ throw new OperatorMissingError(operator, options.operators);
1800
+ },
1801
+ onSome: (run) => runWith(operator, run, values, options.collation, SchemaAST.isBoolean(Schema.toEncoded(operator.output).ast), options.operators.checked)
1802
+ });
1578
1803
  /** A predicate operator's answer as a truth: null is unknown, anything but a boolean refused. */
1579
1804
  const truthOf = (call, answer) => {
1580
1805
  if (answer === null || answer === void 0) return "unknown";
@@ -1605,6 +1830,15 @@ const valueOfOperand = (node, options = {}) => sideOf(node, {
1605
1830
  operators: options.operators ?? Operators.kernel
1606
1831
  });
1607
1832
  /**
1833
+ * Refuses a value the query was given (a literal or an input) holding a NUL,
1834
+ * before any null beside it can answer: SQL refuses such a parameter where it
1835
+ * compiles, whatever the row holds. A NUL stored in a row is refused after,
1836
+ * as SQL meets it only beside a value that is not null.
1837
+ */
1838
+ const refuseGivenNul = (message, sides) => {
1839
+ if (sides.some(([side, value]) => !isPredicate(side) && (side._tag === "Literal" || side._tag === "Input") && holdsNul(value))) throw new QueryEvaluateError(message);
1840
+ };
1841
+ /**
1608
1842
  * A predicate compared as a value. SQL's unknown is null there too, so an
1609
1843
  * unknown compared to anything stays unknown rather than becoming false.
1610
1844
  */
@@ -1615,14 +1849,17 @@ const holds = (node, scope) => {
1615
1849
  case "Eq": {
1616
1850
  const left = sideOf(node.left, scope);
1617
1851
  const right = sideOf(node.right, scope);
1852
+ const nul = "an equality was given text holding a NUL character, which SQL text cannot hold portably";
1853
+ refuseGivenNul(nul, [[node.left, left], [node.right, right]]);
1618
1854
  if (isNull(left) || isNull(right)) return "unknown";
1619
- if (holdsNul(left) || holdsNul(right)) throw new QueryEvaluateError("an equality was given text holding a NUL character, which SQL text cannot hold portably");
1855
+ if (holdsNul(left) || holdsNul(right)) throw new QueryEvaluateError(nul);
1620
1856
  return left === right;
1621
1857
  }
1622
1858
  case "Null": return isNull(valueOf(node.operand, scope)) !== node.present;
1623
1859
  case "Contains": {
1624
1860
  const value = valueOf(node.value, scope);
1625
1861
  const search = sideOf(node.search, scope);
1862
+ refuseGivenNul("a containment test was given text holding a NUL character, which SQL text cannot hold portably", [[node.search, search], [node.value, value]]);
1626
1863
  if (isNull(value) || isNull(search)) return "unknown";
1627
1864
  if (typeof value !== "string" || typeof search !== "string") throw new QueryEvaluateError("a containment test was given something that is not text");
1628
1865
  if (holdsNul(value) || holdsNul(search)) throw new QueryEvaluateError("a containment test was given text holding a NUL character, which SQL text cannot hold portably");
@@ -1655,8 +1892,10 @@ const holds = (node, scope) => {
1655
1892
  case "Compare": {
1656
1893
  const left = valueOf(node.left, scope);
1657
1894
  const right = valueOf(node.right, scope);
1895
+ const nul = "a comparison was given text holding a NUL character, which SQL text cannot hold portably";
1896
+ refuseGivenNul(nul, [[node.left, left], [node.right, right]]);
1658
1897
  if (isNull(left) || isNull(right)) return "unknown";
1659
- if (holdsNul(left) || holdsNul(right)) throw new QueryEvaluateError("a comparison was given text holding a NUL character, which SQL text cannot hold portably");
1898
+ if (holdsNul(left) || holdsNul(right)) throw new QueryEvaluateError(nul);
1660
1899
  const kind = typeof left;
1661
1900
  if (kind !== typeof right || kind !== "number" && kind !== "string") throw new QueryEvaluateError("a comparison was given values that do not order together");
1662
1901
  const order = compare(left, right, node.collation);
@@ -1771,7 +2010,7 @@ const byTerms = (terms, left, right) => {
1771
2010
  return 0;
1772
2011
  };
1773
2012
  const ordered = (rows, terms, query, scope) => {
1774
- if (terms.length === 0 || rows.length < 2) return [...rows];
2013
+ if (terms.length === 0) return [...rows];
1775
2014
  const keyed = rows.map((row) => ({
1776
2015
  row,
1777
2016
  keys: keysOf(row, terms, scope)
@@ -1839,6 +2078,47 @@ const evaluate = (body, input, rows, options = {}) => {
1839
2078
  operators
1840
2079
  });
1841
2080
  };
2081
+ /**
2082
+ * As `evaluate`, with each row judged alone: a row whose own values are
2083
+ * refused (text holding a NUL, a value an operator fails on) is set aside in
2084
+ * `refused` and the others are still answered. A client judging the rows it
2085
+ * holds wants this, since one bad stored row says nothing about the rest.
2086
+ *
2087
+ * What no single row causes still refuses the run: an operation or operator
2088
+ * the table lacks, an order by a locale collation, an input the body reads
2089
+ * holding a NUL (every row would refuse, and no row is the cause), and order
2090
+ * keys of different kinds across rows.
2091
+ */
2092
+ const evaluateEach = (body, input, rows, options = {}) => {
2093
+ const operators = options.operators ?? Operators.kernel;
2094
+ assertSupported(body, operators);
2095
+ const terms = Query.orderFor(body, input);
2096
+ const scope = {
2097
+ input,
2098
+ operators
2099
+ };
2100
+ const keyed = [];
2101
+ const refused = [];
2102
+ for (const row of rows) try {
2103
+ if (matches(body, row, input, operators)) keyed.push({
2104
+ row,
2105
+ keys: keysOf(row, terms, scope)
2106
+ });
2107
+ } catch (error) {
2108
+ if (!(error instanceof QueryEvaluateError) || givenNul(body, terms, input)) throw error;
2109
+ refused.push(row);
2110
+ }
2111
+ checkOrder(keyed.map(({ keys }) => keys), terms, body.entity.name);
2112
+ return {
2113
+ matched: keyed.sort((left, right) => byTerms(terms, left.keys, right.keys)).map(({ row }) => row),
2114
+ refused
2115
+ };
2116
+ };
2117
+ /** Whether a constant or an input the body reads is text holding a NUL, or a list holding one. */
2118
+ const givenNul = (body, terms, input) => Expr.givesNul(...body.where, ...terms.map((term) => term.expr)) || Query.dependencies(body).inputs.some((key) => {
2119
+ const value = input[key];
2120
+ return Array.isArray(value) ? value.some(holdsNul) : holdsNul(value);
2121
+ });
1842
2122
  // src/invariant.ts
1843
2123
  /**
1844
2124
  * Invariants: what every stored row of an Entity must hold, and what every
@@ -1974,32 +2254,6 @@ const check = (entity, options = {}) => Schema.makeFilter((value) => {
1974
2254
  issue: failure.message
1975
2255
  })));
1976
2256
  });
1977
- // src/shape.ts
1978
- const isNullish = (ast) => SchemaAST.isNull(ast) || SchemaAST.isUndefined(ast);
1979
- const isText = (ast) => SchemaAST.isString(ast) || SchemaAST.isTemplateLiteral(ast) || SchemaAST.isLiteral(ast) && typeof ast.literal === "string" || SchemaAST.isUnion(ast) && ast.types.length > 0 && ast.types.every(isText);
1980
- /** Whether any of these checks is `Schema.isInt`, alone or inside a group (`isInt32`). */
1981
- const checksInteger = (checks) => checks.some((check) => Match.value(check).pipe(Match.tagsExhaustive({
1982
- Filter: (filter) => filter.annotations?.representation?.id === "effect/schema/isInt",
1983
- FilterGroup: (group) => checksInteger(group.checks)
1984
- })));
1985
- /** What a schema's AST holds, read through Effect's own guards. */
1986
- const SchemaShape = {
1987
- /** True for the `null` and `undefined` members that make a schema optional. */
1988
- isNullish,
1989
- /**
1990
- * The members of a schema with `null` and `undefined` set aside, so optional
1991
- * text is still text; a schema that is not a union is its one member.
1992
- */
1993
- present: (ast) => SchemaAST.isUnion(ast) ? ast.types.filter((member) => !isNullish(member)) : [ast],
1994
- /** True when every value the schema admits is a string. */
1995
- isText,
1996
- /**
1997
- * True when the AST is checked to hold integers (`Schema.isInt`, alone or in
1998
- * a group such as `isInt32`). Read it from a schema's encoded side to ask
1999
- * what the store holds.
2000
- */
2001
- holdsIntegers: (ast) => checksInteger(ast.checks ?? [])
2002
- };
2003
2257
  // src/readFilter.ts
2004
2258
  /**
2005
2259
  * The members a server filters an Entity's rows by under a rule the client
@@ -2053,6 +2307,7 @@ of: (schema) => {
2053
2307
  * It is authority someone declared, never something derived from an Entity: an
2054
2308
  * Entity having a field does not mean anyone may set it.
2055
2309
  */
2310
+ const Computation = Data.taggedEnum();
2056
2311
  const update = (input, options) => settingSomething(declared("Update", input, options));
2057
2312
  const remove = (input, options) => {
2058
2313
  const write = declared("Delete", input, options);
@@ -2118,15 +2373,25 @@ const declared = (kind, input, options) => {
2118
2373
  case "NestedInput": fail$1(input, `"${key}" writes a nested row; a write writes its own row only`);
2119
2374
  }
2120
2375
  }
2376
+ const placeholders = Object.create(null);
2377
+ for (const [key, schema] of Object.entries(input.schema.fields)) placeholders[key] = Expr.input(key, schema);
2121
2378
  const when = Option.map(Option.fromUndefinedOr(options.when), (condition) => {
2122
- const placeholders = Object.create(null);
2123
- for (const [key, schema] of Object.entries(input.schema.fields)) placeholders[key] = Expr.input(key, schema);
2124
2379
  return Query.from(input.entity).pipe(Query.where(condition({ input: placeholders })));
2125
2380
  });
2126
2381
  const increments = Object.entries(options.increment ?? {}).flatMap(([fieldKey, key]) => key === void 0 ? [] : [incrementOf(input, fieldKey, key, {
2127
2382
  expect,
2128
2383
  sets
2129
2384
  })]);
2385
+ const fields = input.entity.fields;
2386
+ const row = Object.fromEntries(Object.entries(fields).map(([key, field]) => [key, Expr.field(field)]));
2387
+ const assignments = Object.entries(options.compute ?? {}).flatMap(([fieldKey, compute]) => compute === void 0 ? [] : [assignmentOf(input, fieldKey, () => compute({
2388
+ row,
2389
+ input: placeholders
2390
+ }), {
2391
+ expect,
2392
+ sets,
2393
+ increments
2394
+ })]);
2130
2395
  return Object.freeze({
2131
2396
  _tag: kind,
2132
2397
  input,
@@ -2138,9 +2403,94 @@ const declared = (kind, input, options) => {
2138
2403
  when,
2139
2404
  sets: Object.freeze(sets),
2140
2405
  increments: Object.freeze(increments),
2406
+ assignments: Object.freeze(assignments),
2141
2407
  links: Object.freeze(links)
2142
2408
  });
2143
2409
  };
2410
+ /** The kind of one stored form, as far as an assignment must agree with its field. */
2411
+ const storedKind = (ast) => {
2412
+ if (SchemaAST.isNull(ast)) return "null";
2413
+ const literal = SchemaAST.isLiteral(ast) ? typeof ast.literal : void 0;
2414
+ if (SchemaAST.isNumber(ast) || literal === "number") return "number";
2415
+ if (SchemaAST.isString(ast) || SchemaAST.isTemplateLiteral(ast) || literal === "string") return "text";
2416
+ if (SchemaAST.isBoolean(ast) || literal === "boolean") return "boolean";
2417
+ return "other";
2418
+ };
2419
+ /** Every kind a stored form may hold: a union's members' kinds. */
2420
+ const storedKinds = (ast) => new Set(SchemaAST.isUnion(ast) ? ast.types.flatMap((member) => [...storedKinds(member)]) : [storedKind(ast)]);
2421
+ /** The stored kinds a scalar may come to, by what it is. */
2422
+ const kindsOf = (expr) => {
2423
+ switch (expr._tag) {
2424
+ case "Field": return storedKinds(Schema.toEncoded(expr.schema).ast);
2425
+ case "Next": return storedKinds(Schema.toEncoded(expr.field.schema).ast);
2426
+ case "Input": return storedKinds(Schema.toEncoded(expr.schema).ast);
2427
+ case "Literal": return /* @__PURE__ */ new Set([expr.value === null ? "null" : typeof expr.value === "string" ? "text" : typeof expr.value]);
2428
+ case "Call": return storedKinds(Schema.toEncoded(expr.operator.output).ast);
2429
+ }
2430
+ };
2431
+ /**
2432
+ * Whether `expr` may come to null: a nullable field or input, a null literal,
2433
+ * an operator answering one, or a strict operator given an argument that may
2434
+ * be null, which it answers with null.
2435
+ */
2436
+ const mayBeNull = (expr) => kindsOf(expr).has("null") || expr._tag === "Call" && expr.operator.nulls === "strict" && expr.args.some((arg) => !isPredicate(arg) && mayBeNull(arg));
2437
+ /** Whether a predicate is anywhere in `expr`, which data carries only as a value. */
2438
+ const holdsPredicate = (expr) => isPredicate(expr) || expr._tag === "Call" && expr.args.some(holdsPredicate);
2439
+ /**
2440
+ * One computed field, checked: a field of the Entity written by nothing else,
2441
+ * computed from this Entity's row before the write and the input alone
2442
+ * (never `Next`, so assignments do not depend on each other), to a value of
2443
+ * the field's stored kind, with no predicate in it.
2444
+ */
2445
+ const assignmentOf = (input, fieldKey, compute, declared) => {
2446
+ const fields = input.entity.fields;
2447
+ const field = Object.hasOwn(fields, fieldKey) ? fields[fieldKey] : void 0;
2448
+ if (field === void 0) return fail$1(input, `computes "${fieldKey}", which is not a field`);
2449
+ if (fieldKey === "id") return fail$1(input, "computes the id");
2450
+ if (declared.expect?.field.key === fieldKey) return fail$1(input, `computes "${fieldKey}", the revision it expects`);
2451
+ if (declared.sets.some((set) => set.field.key === fieldKey) || declared.increments.some((increment) => increment.field.key === fieldKey)) return fail$1(input, `computes "${fieldKey}", which the write also sets`);
2452
+ const operand = compute();
2453
+ const expr = isPredicate(operand) ? operand : Expr.expanded(operand);
2454
+ if (isPredicate(expr) || holdsPredicate(expr)) return fail$1(input, `computes "${fieldKey}" with a predicate, which an assignment carries only as a value`);
2455
+ const reads = dependenciesOf(expr);
2456
+ if (reads.next.length > 0) return fail$1(input, `computes "${fieldKey}" from the row after the write, which an assignment never reads`);
2457
+ const stranger = reads.fields.find((read) => read.owner.name !== input.entity.name);
2458
+ if (stranger !== void 0) return fail$1(input, `computes "${fieldKey}" from ${stranger.owner.name}.${stranger.key}, another Entity's field`);
2459
+ const stored = storedKinds(Schema.toEncoded(field.schema).ast);
2460
+ const comes = [...kindsOf(expr)].filter((kind) => kind !== "null" && !stored.has(kind));
2461
+ if (comes.length > 0) return fail$1(input, `computes "${fieldKey}" as ${comes.join(" or ")}, which it does not store`);
2462
+ if (!stored.has("null") && mayBeNull(expr)) return fail$1(input, `computes "${fieldKey}" as possibly null, which it does not store`);
2463
+ return Object.freeze({
2464
+ field,
2465
+ expr
2466
+ });
2467
+ };
2468
+ /** An assignment's expression, bound to one input, as data. */
2469
+ const computationOf = (write, expr, input) => {
2470
+ switch (expr._tag) {
2471
+ case "Field":
2472
+ case "Next": return Computation.Field({ key: expr._tag === "Field" ? expr.key : expr.field.key });
2473
+ case "Literal": return Computation.Value({ value: expr.value });
2474
+ case "Input": return Computation.Value({ value: Schema.encodeUnknownSync(write.input.schema.fields[expr.key])(input[expr.key]) });
2475
+ case "Call": return Computation.Call({
2476
+ operator: expr.operator.version === 1 ? expr.operator.id : `${expr.operator.id}@${expr.operator.version}`,
2477
+ args: expr.args.map((arg) => computationOf(write, arg, input)),
2478
+ collation: Option.getOrNull(expr.collation)
2479
+ });
2480
+ }
2481
+ };
2482
+ /**
2483
+ * What a computation comes to over `row`, the row before the write: none when
2484
+ * the row lacks a field it reads, or `operators` lacks an operator it calls.
2485
+ */
2486
+ const computed = (computation, row, operators) => Computation.$match(computation, {
2487
+ Field: ({ key }) => Object.hasOwn(row, key) ? Option.some(row[key]) : Option.none(),
2488
+ Value: ({ value }) => Option.some(value),
2489
+ Call: ({ operator, args, collation }) => Option.flatMap(operators.named(operator), (descriptor) => Option.map(Option.all(args.map((arg) => computed(arg, row, operators))), (values) => applyOperator(descriptor, values, {
2490
+ collation: Option.fromNullOr(collation),
2491
+ operators
2492
+ })))
2493
+ });
2144
2494
  /** Whether a value's stored form is a plain number. */
2145
2495
  const storedAsNumber = (schema) => SchemaAST.isNumber(Schema.toEncoded(schema).ast);
2146
2496
  /** Whether a value's stored form is checked to be an integer. */
@@ -2172,7 +2522,7 @@ const incrementOf = (input, fieldKey, key, declared) => {
2172
2522
  });
2173
2523
  };
2174
2524
  /** An update or an insert that would write nothing is refused where it is declared. */
2175
- const settingSomething = (write) => write.sets.length === 0 && write.links.length === 0 && write.increments.length === 0 ? fail$1(write.input, "it sets no field") : write;
2525
+ const settingSomething = (write) => write.sets.length === 0 && write.links.length === 0 && write.increments.length === 0 && write.assignments.length === 0 ? fail$1(write.input, "it sets no field") : write;
2176
2526
  const Write = {
2177
2527
  /**
2178
2528
  * Sets, on the row whose id is the input's `id` key, every field the input
@@ -2191,6 +2541,12 @@ const Write = {
2191
2541
  * `when` is what the row must hold for the update to land, checked where it
2192
2542
  * commits (`({ input }) => Expr.eq(Post.fields.status, 'draft')`); a row it
2193
2543
  * does not hold of is refused as unmet.
2544
+ *
2545
+ * `compute` sets a field to what an expression comes to over the row before
2546
+ * the write and the input, run where it commits
2547
+ * (`{ label: ({ row }) => concat(row.title, ' draft') }`). It is refused for
2548
+ * a field another key writes, an expression over the row after the write or
2549
+ * another Entity, or one of a kind the field does not store.
2194
2550
  */
2195
2551
  update,
2196
2552
  /**
@@ -2222,18 +2578,21 @@ const Write = {
2222
2578
  writes: (write) => [
2223
2579
  ...write.sets.map((set) => set.field),
2224
2580
  ...write.increments.map((increment) => increment.field),
2581
+ ...write.assignments.map((assignment) => assignment.field),
2225
2582
  ...write.links.map((link) => link.relation)
2226
2583
  ],
2227
2584
  /**
2228
2585
  * The fields a write reads from the row it writes: those its `when` reads,
2229
- * each it increments, and the revision it expects. What an interpreter
2230
- * must read, and what a startup check judges it could disclose.
2586
+ * each it increments, each its assignments read, and the revision it
2587
+ * expects. What an interpreter must read, and what a startup check judges
2588
+ * it could disclose.
2231
2589
  */
2232
2590
  reads: (write) => {
2233
2591
  const fields = /* @__PURE__ */ new Map();
2234
2592
  const add = (field) => fields.set(field.key, field);
2235
2593
  Option.map(write.when, (body) => Query.dependencies(body).predicate.forEach((field) => add(field)));
2236
2594
  write.increments.forEach((increment) => add(increment.field));
2595
+ write.assignments.forEach((assignment) => dependenciesOf(assignment.expr).fields.forEach((field) => add(field)));
2237
2596
  if (write.expect !== void 0) add(write.expect.field);
2238
2597
  return [...fields.values()];
2239
2598
  },
@@ -2271,12 +2630,61 @@ const Write = {
2271
2630
  increments[field.key] = Schema.encodeUnknownSync(schema)(held);
2272
2631
  });
2273
2632
  }
2633
+ const assignments = {};
2634
+ for (const { field, expr } of write.assignments) assignments[field.key] = computationOf(write, expr, input);
2274
2635
  return {
2275
2636
  entity: write.input.entity.name,
2276
2637
  id: String(encoded(write.id.field, input[write.id.key])),
2277
2638
  values,
2278
2639
  links,
2279
- increments
2640
+ increments,
2641
+ assignments
2642
+ };
2643
+ },
2644
+ /**
2645
+ * The fields of the row before it that a bound write's amounts and
2646
+ * assignments read: what to read to work out the row it leaves.
2647
+ */
2648
+ boundReads: (bound) => {
2649
+ const keys = new Set(Object.keys(bound.increments));
2650
+ const walk = (computation) => Computation.$match(computation, {
2651
+ Field: ({ key }) => void keys.add(key),
2652
+ Value: () => void 0,
2653
+ Call: ({ args }) => args.forEach(walk)
2654
+ });
2655
+ Object.values(bound.assignments).forEach(walk);
2656
+ return [...keys];
2657
+ },
2658
+ /**
2659
+ * The row a bound write leaves over `row`, the row before it: its values
2660
+ * set, each amount added (a null stays null, as in SQL), and each
2661
+ * assignment computed by `operators` over the row before. `unknown` names
2662
+ * each field it could not work out: one `row` lacks, or holds as no number
2663
+ * for an amount, or an assignment calling an operator the table lacks. That
2664
+ * field keeps what `row` holds. The one computation of this row: a guard
2665
+ * judges it, a writer explains a miss with it, a client predicts it.
2666
+ */
2667
+ apply: (row, bound, options) => {
2668
+ const after = {
2669
+ ...row,
2670
+ ...bound.values
2671
+ };
2672
+ const unknown = [];
2673
+ for (const [field, amount] of Object.entries(bound.increments)) {
2674
+ const held = Object.hasOwn(row, field) ? row[field] : void 0;
2675
+ if (held === null) after[field] = null;
2676
+ else if (typeof held === "number") after[field] = held + amount;
2677
+ else unknown.push(field);
2678
+ }
2679
+ for (const [field, computation] of Object.entries(bound.assignments)) Option.match(computed(computation, row, options.operators), {
2680
+ onNone: () => unknown.push(field),
2681
+ onSome: (value) => {
2682
+ after[field] = value;
2683
+ }
2684
+ });
2685
+ return {
2686
+ row: after,
2687
+ unknown
2280
2688
  };
2281
2689
  }
2282
2690
  };
@@ -2648,6 +3056,6 @@ const Relation = {
2648
3056
  })
2649
3057
  };
2650
3058
  const Derived = { make: (schema) => ({ schema }) };
2651
- export { Law as A, Expr as C, isPredicate as D, dependenciesOf as E, maxQueryNodes as O, Text as S, Query as T, supported as _, SelectionPageTypeId as a, Evidence as b, Words as c, OperatorMissingError as d, QueryEvaluateError as f, evaluate as g, decided as h, Relation as i, Collation as j, noOperators as k, ReadFilter as l, compareRows as m, Entity as n, SelectionTypeId as o, assertSupported as p, EntityTypeId as r, Write as s, Derived as t, SchemaShape as u, truthOver as v, Order as w, Operators as x, valueOfOperand as y };
3059
+ export { Query as A, OperatorDescription as C, stampTested as D, stampRun as E, noOperators as F, Law as I, LawDescription as L, isPredicate as M, maxQueryNodes as N, Expr as O, missingName as P, SchemaShape as R, Evidence as S, Text as T, evaluate as _, SelectionPageTypeId as a, truthOver as b, Write as c, OperatorMissingError as d, QueryEvaluateError as f, decided as g, compareRows as h, Relation as i, dependenciesOf as j, Order as k, Words as l, assertSupported as m, Entity as n, SelectionTypeId as o, applyOperator as p, EntityTypeId as r, Computation as s, Derived as t, ReadFilter as u, evaluateEach as v, Operators as w, valueOfOperand as x, supported as y, Collation as z };
2652
3060
 
2653
- //# sourceMappingURL=src-CSxcKUv6.mjs.map
3061
+ //# sourceMappingURL=src-DBAilaDV.mjs.map