foldkit-entity 0.11.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.
package/README.md CHANGED
@@ -372,14 +372,39 @@ key, a number; negative takes away) to the stored `stock`, in the statement that
372
372
  writes, so no concurrent change is lost. A retry must not add twice, so either it
373
373
  expects a revision (a retry of a write that landed is then a conflict), or its
374
374
  writer keeps a ledger, which answers the retry from its record and lets two
375
- concurrent increments both land. `RemoteServer.write` refuses one with neither. The field must
376
- be stored as a number, and may not be the id, the revision, or set by another
377
- key. `Write.bind` gives the amounts apart from the values (`increments`), so a
375
+ concurrent increments both land. `RemoteServer.write` refuses one with neither,
376
+ and one of a real number with no revision even under a ledger: floating-point
377
+ addition does not associate, so two concurrent sums could land as two results.
378
+ The field must be stored as a number, and may not be the id, the revision, or
379
+ set by another key. `Write.bind` gives the amounts apart from the values (`increments`), so a
378
380
  client can add them to the value it holds as it reads it (Remote does), never
379
381
  fixing a sum over a row that may since have moved. `Write.reads(write)` is what a write
380
- reads from its row: what its `when` reads, each field it increments, and the
381
- revision. How a declaration, its guard, its writer and the client fit together is
382
- the [declared writes guide](../../docs/declared-writes.md).
382
+ reads from its row: what its `when` reads, each field it increments, what its
383
+ assignments read, and the revision. How a declaration, its guard, its writer and
384
+ the client fit together is the [declared writes guide](../../docs/declared-writes.md).
385
+
386
+ An update may also compute a field from the row before it and the input:
387
+ `compute: { label: ({ row, input }) => concat(input.prefix, row.name) }`, with an
388
+ operator such as the `concat` [below](#operators-each-interpreter-implements). It
389
+ reads neither the row after the write nor another Entity, so assignments never
390
+ depend on each other, and is refused where it is declared for a field another
391
+ key writes or a value of a kind the field does not store. A defined operator in
392
+ it is expanded there, so `Write.bind` carries it as data (`assignments`, each a
393
+ `Computation`: fields by key, values encoded, operators by name), which a writer
394
+ compiles into the statement and a client predicts by its own table. A
395
+ computation does not repeat without effect, so a retry of one is held to it as
396
+ an increment's is; without a revision it lands only under a ledger, and there
397
+ only where the writer pins the row it read (a guarded writer with a `revision`)
398
+ or by an operator whose commutativity and associativity are tested over every
399
+ value for each implementation the writer runs (`Conformance.laws` in memory,
400
+ `Conformance.lawsBy` in SQL).
401
+
402
+ `Write.apply(row, bound, { operators })` is the row a bound write leaves over
403
+ the row before it: values set, amounts added (a null stays null, as in SQL),
404
+ assignments computed. It is the one computation of that row: a guard judges
405
+ it, a writer explains a miss by it, a client predicts it. `unknown` names each
406
+ field it could not work out (one the row lacks, or an operator the table lacks),
407
+ which keeps what the row holds.
383
408
 
384
409
  ## What every row and change must hold: invariants
385
410
 
@@ -708,10 +733,11 @@ Query.placement(byName, {}) // { _tag: 'Placeable' }
708
733
  never by a client.
709
734
 
710
735
  A term overrides its field's: `Order.asc(field, { collation })`.
711
- `Query.placement(query, input)` says whether a client can order the rows exactly
712
- as the server does: every term over a number or a boolean (a row may lack it), or over text with a
713
- portable collation. A body with no order, text with none declared, or a locale
714
- is `NotPlaceable`, with the reason.
736
+ `Query.placement(query, input, { operators })` says whether a client can order the rows exactly
737
+ as the server does: every term over a number or a boolean (a row may lack it), over text with a
738
+ portable collation, or a call whose primitive operators the client's table runs. A body with no
739
+ order, text with none declared, a locale, or an operator the table lacks is `NotPlaceable`, with
740
+ the reason.
715
741
  `foldkit-crud`'s `Sort.make(['title', 'id']).Schema` is such a sort.
716
742
 
717
743
  The list of predicates **is** the conjunction: a query wanting three
@@ -719,7 +745,7 @@ conditions writes three `where`s. `Expr.and` is for a conjunction inside
719
745
  something else, and `Expr.or` and `Expr.not` are the other two connectives:
720
746
 
721
747
  ```ts
722
- // A search over two fields: the registry finds a product by description or UPC.
748
+ // A search over two fields: a product whose description or UPC holds the text.
723
749
  Expr.or(
724
750
  Expr.contains(Product.fields.description, input.search),
725
751
  Expr.contains(Product.fields.upc, input.search),
@@ -784,6 +810,249 @@ matters is that it refuses rather than skipping the operation — an interpreter
784
810
  that quietly drops a `contains` it cannot compile answers a different question
785
811
  in full confidence, and every test it does support still passes.
786
812
 
813
+ ### Naming a question: operators
814
+
815
+ What operators make possible, end to end (a rule named once, search and order
816
+ the kernel lacks, writes that compute, one meaning checked across
817
+ interpreters), is the [operators guide](../../docs/operators.md); this section
818
+ and the next three are the reference.
819
+
820
+ A predicate an application asks in many places (in a public query, a
821
+ visitor's Read rule, an invariant) can be given a name. `Expr.operator`
822
+ declares one by what a call of it means:
823
+
824
+ ```ts
825
+ import { Schema } from 'effect'
826
+ import { Entity, Expr, Query } from 'foldkit-entity'
827
+
828
+ const Story = Entity.define(
829
+ 'Story',
830
+ Schema.Struct({ id: Schema.String, publishedAt: Schema.NullOr(Schema.String) }),
831
+ )
832
+
833
+ const published = Expr.operator('acme.published', {
834
+ input: [Schema.Unknown],
835
+ output: Schema.Boolean,
836
+ definedAs: publishedAt => Expr.isNotNull(publishedAt),
837
+ })
838
+
839
+ const PublicStories = Query.from(Story).pipe(Query.where(published(Story.fields.publishedAt)))
840
+ Query.show(PublicStories)
841
+ // FROM Story
842
+ // WHERE acme.published(Story.publishedAt)
843
+ ```
844
+
845
+ - **It computes nothing of its own.** `definedAs` builds an expression from a
846
+ call's arguments, once per call, and every interpreter runs that expression
847
+ (`Expr.expanded` writes a predicate's calls out), so the operator needs no
848
+ SQL, no evaluator, and no support list. The SQL a body compiles to is the SQL
849
+ of the body written out by hand.
850
+ - **What it adds is a name.** `Query.show` prints the call, and
851
+ `Query.dependencies(body).operators` lists each operator a body uses.
852
+ - **It reads only its arguments.** A `definedAs` that closes over a field or an
853
+ input, instead of taking it, is refused when called: nothing asking what the
854
+ call reads (Guard's checks, Remote's matching) would see it.
855
+ - **Arguments are checked by their stored form**, at compile time and when
856
+ called: a field, scalar or plain value of the input's stored type, or a
857
+ predicate where it takes a boolean. A boolean `output` makes a call a
858
+ predicate, usable in `and`, `or`, `not`, a guard or an invariant with no cast;
859
+ any other makes it a scalar of that type.
860
+ - **Ids are namespaced** (`acme.published`), and `foldkit.` is reserved.
861
+ `version` (default 1) changes when what it means does; a call prints it after
862
+ the first (`acme.published@2(…)`).
863
+
864
+ `foldkit-cms` declares one over its `published` role: `Cms.published(entity)`.
865
+
866
+ ### Operators each interpreter implements
867
+
868
+ Without `definedAs`, an operator is **primitive**: it means what each
869
+ interpreter's implementation does, and every implementation is held to the
870
+ same statement of it. The kernel ships one, `Text.startsWith`; an application
871
+ declares its own and implements it, here for the in-memory interpreter:
872
+
873
+ ```ts
874
+ import { Schema } from 'effect'
875
+ import { Collation, Entity, Expr, Operators, Query, Text, evaluate } from 'foldkit-entity'
876
+
877
+ const Product = Entity.define(
878
+ 'Product',
879
+ Schema.Struct({ id: Schema.String, upc: Schema.String, label: Schema.String }),
880
+ ).pipe(Entity.annotateMembers({ upc: Collation.of(Collation.binary) }))
881
+ const search = Expr.input('search', Schema.String)
882
+
883
+ // The UPC declares `binary`, so it compares exactly; the label declares nothing,
884
+ // so this call is given a collation.
885
+ const ByCode = Query.from(Product).pipe(Query.where(Text.startsWith(Product.fields.upc, search)))
886
+ Text.startsWith(Product.fields.label, search, { collation: Collation.asciiFold })
887
+
888
+ const joined = Expr.operator('acme.joined', {
889
+ input: [Schema.String, Schema.String],
890
+ output: Schema.String,
891
+ collation: 'operands',
892
+ })
893
+ const operators = Operators.merge(
894
+ Operators.kernel,
895
+ Operators.memory(Operators.implement(joined, (left, right) => `${left}${right}`)),
896
+ )
897
+ evaluate(ByCode, { search: '012' }, [{ id: 'p1', upc: '0123', label: 'Bolt' }], { operators })
898
+ // [{ id: 'p1', upc: '0123', label: 'Bolt' }]
899
+ ```
900
+
901
+ `startsWith` compares under its text's collation (`binary` exactly, `asciiFold`
902
+ folding ASCII letters on both sides), is unknown when either side is null, and
903
+ holds for the empty prefix; text with no collation, or a backend's locale, is
904
+ refused where it is written.
905
+
906
+ - **A table is a value.** `Operators.memory` refuses one operator implemented
907
+ twice, or two under one name; `merge` refuses an overlap, and `override`
908
+ replaces on purpose. `Operators.checked(table)` checks each answer against
909
+ the operator's output schema, for tests. Nothing registers globally:
910
+ `evaluate`, `evaluateEach`, `decided`, `truthOver`, `Entity.judge`, `Entity.judgeInput` and
911
+ `Entity.check(entity, { operators })` each take the table, `Operators.kernel`
912
+ by default.
913
+ - **Null is strict by default.** A null argument gives null (unknown for a
914
+ predicate) and the implementation never sees one. `nulls: 'handled'`
915
+ operators are implemented with `Operators.implementHandlingNulls` and answer
916
+ for null themselves; a predicate answers `null` for unknown.
917
+ - **Text has a collation or no comparison.** `collation: 'operands'` makes a
918
+ text result carry the collation its text arguments share, so
919
+ `Expr.lt(joined(a, b), x)` compares under it; `'required'` (as
920
+ `startsWith`) refuses text with none. A call may be given one:
921
+ `op(a, b, { collation })`.
922
+ - **A call orders when its result does.** `Order.asc(joined(Product.fields.upc, '!'))`
923
+ orders by the call's text under the collation it carries, and a call giving a
924
+ number orders as one; anything else, text with no collation included, is
925
+ refused where the term or `Order.chosen` alternative is written. `evaluate`
926
+ runs it per row by its table, and `compareRows(terms, a, b, query, { input,
927
+ operators })` compares two rows the same way.
928
+ - **What a table lacks is refused by name.** `Query.unsupported(body,
929
+ supported, operators)` and `Expr.unsupported(nodes, { operations,
930
+ operators })` name each operation and operator missing; `evaluate` refuses
931
+ such a body. An invariant calling an operator its judge's table lacks is
932
+ `Undecided` with that operator in `operators`, which a form passes and a
933
+ server refuses to start without.
934
+ - **One refusing row refuses the run, unless each row is judged alone.**
935
+ `evaluate` refuses a run when any row holds what no interpreter answers for
936
+ (text with a NUL). `evaluateEach(body, input, rows, { operators })` sets such
937
+ a row aside in `refused` and still answers the others, in order; what no one
938
+ row causes (an operator the table lacks, an input the body reads holding a
939
+ NUL, order keys of different kinds) still refuses it. A client judging the
940
+ rows it holds wants the second.
941
+ - **NUL is refused** in any text argument, and an implementation that throws
942
+ is reported as a `QueryEvaluateError` naming its operator.
943
+
944
+ ### Laws, and holding an implementation to them
945
+
946
+ An operator may declare the equations every implementation of it keeps. A law
947
+ describes: nothing rewrites a body by one. `Conformance.laws` tests an
948
+ implementation against them, and what it finds is evidence its table records.
949
+
950
+ ```ts
951
+ import { Schema } from 'effect'
952
+ import { Expr, Law, Operators } from 'foldkit-entity'
953
+ import { Conformance } from 'foldkit-entity/conformance'
954
+
955
+ const concat = Expr.operator('acme.concat', {
956
+ input: [Schema.String, Schema.String],
957
+ output: Schema.String,
958
+ collation: 'operands',
959
+ laws: [Law.associative, Law.identity(''), Law.preservesCollation],
960
+ })
961
+ const table = Operators.memory(Operators.implement(concat, (left, right) => `${left}${right}`))
962
+
963
+ const verdict = Conformance.laws(concat, table) // { _tag: 'Holds', evidence: [...] }
964
+ const recorded =
965
+ verdict._tag === 'Holds' ? Operators.withEvidence(table, verdict.evidence) : table
966
+ Operators.describeTable(recorded) // [{ name: 'acme.concat', …, laws, evidence }]
967
+ ```
968
+
969
+ - **A law is checked where it is declared.** `Law.commutative`, `associative`,
970
+ `idempotent`, `identity(value, side?)`, `absorbing(value, side?)`,
971
+ `inverse(other, identity)` and `distributes(over)` are laws of an operator of
972
+ two arguments; `monotonic(direction, position)` names an argument it has, and
973
+ `preservesCollation` needs `collation: 'operands'`. A witness that is not a
974
+ value the argument's schema stores is refused.
975
+ - **Its domain** is every non-null value of the input schemas, narrowed with
976
+ `Law.within(law, schema)` where a law holds of less (a square is increasing
977
+ over the non-negative numbers only). Strict null makes both sides null, so no
978
+ law needs a null case.
979
+ - **Testing is sampling, seeded.** Cases come from a fixed sample of each kind
980
+ (the empty string, mixed case, non-ASCII and astral text; zero, negatives, a
981
+ fraction), kept where the schemas decode them, up to `cases` (200) a law
982
+ chosen by `seed` (0), under each of `binary` and `asciiFold` where the
983
+ operator or a witness its law calls compares text (so a record of such a law
984
+ counts twice the cases). The verdict is `Holds` with one `Tested` record a law, or the
985
+ first `Counterexample` with both sides and its collation: declaring `concat` commutative
986
+ finds `"a"` and `"A"`, which give `"aA"` and `"Aa"`.
987
+ - **Evidence is an implementation's.** `Operators.withEvidence` refuses a record
988
+ of an operator the table lacks or a law it does not declare, and a `Tested`
989
+ record `Conformance.laws` did not make of this table's own implementation
990
+ (`Operators.testedOn(record)` names the one it did); `override` drops a
991
+ replaced implementation's records, and those of a law that called it as a
992
+ witness (`inverse`, `distributes`); `merge` keeps both tables'. An SQL table
993
+ (`DrizzleOperators.withEvidence`) takes only records `Conformance.lawsBy`
994
+ made (`Operators.testedByRunner`): not one built by hand, copied, or tested
995
+ in memory. Which runner made it, the database's or another, is the caller's
996
+ word, so run it over the table's own SQL (`compileCall`). `Evidence.Proven`
997
+ records a proof made elsewhere, never checked here. A law's domain is
998
+ described as a JSON Schema with the definitions it refers to.
999
+ - **A defined operator's laws describe it; nothing records them.** It has no
1000
+ implementation to hold evidence. A write computing through it is expanded
1001
+ first, so it commutes by the primitive operator it calls, by that one's
1002
+ evidence.
1003
+
1004
+ `Conformance.operator(op, { implementations })` runs one set of calls through
1005
+ every implementation given and reports where they disagree, a refusal included:
1006
+ generated from each argument's samples, null where its schema admits one, and
1007
+ text holding NUL, under `binary` and `asciiFold` where the operator compares
1008
+ text. `Conformance.memory(table)` is the reference interpreter's runner; a
1009
+ defined operator's expansion runs beside the others. `foldkit-remote-drizzle`
1010
+ runs the kernel's operators and an application's through it on SQLite and
1011
+ Postgres.
1012
+
1013
+ ### One operator, from declaration to description
1014
+
1015
+ The `concat` above, as an application ships it: declared once, implemented for
1016
+ each interpreter that runs it, held to itself, and described for whoever asks
1017
+ what a server runs.
1018
+
1019
+ ```ts
1020
+ import { sql } from 'drizzle-orm'
1021
+ import { Operators } from 'foldkit-entity'
1022
+ import { Conformance } from 'foldkit-entity/conformance'
1023
+ import { DrizzleOperators } from 'foldkit-remote-drizzle'
1024
+
1025
+ // In memory, as above; in SQL, for a binding (`bind(…, { operators: { memory, sql } })`).
1026
+ const memory = Operators.memory(Operators.implement(concat, (left, right) => `${left}${right}`))
1027
+ const sqlTable = DrizzleOperators.make(
1028
+ DrizzleOperators.implement(concat, ({ args: [left, right] }) => sql`(${left} || ${right})`),
1029
+ )
1030
+
1031
+ // Its laws, against the memory implementation.
1032
+ const held = Conformance.laws(concat, memory)
1033
+
1034
+ // The two implementations against each other: an SQL runner selects
1035
+ // `compileCall(call, binding, name)` from a database (foldkit-remote-drizzle's
1036
+ // test/operatorConformance.test.ts has one); here the memory one alone.
1037
+ const report = await Conformance.operator(concat, {
1038
+ implementations: { memory: Conformance.memory(memory) },
1039
+ })
1040
+
1041
+ // Its signature as JSON: name, version, each argument and the result as a JSON
1042
+ // Schema of what is stored, its null and collation rules, its laws.
1043
+ Operators.describe(concat)
1044
+ ```
1045
+
1046
+ `Operators.describe` gives an `OperatorDescription`, a Schema whose decoder
1047
+ checks a description another server publishes; it says what an operator takes
1048
+ and keeps, never a defined operator's body. `Operators.describeTable(table)`
1049
+ lists each operator a table implements so, with its evidence, and
1050
+ `Query.operators(body)` names each operator a body calls (a defined one and the
1051
+ primitive ones it calls). A version is part of an operator's name: a table
1052
+ holding `acme.slug` does not answer a body calling `acme.slug@2`, and the
1053
+ refusal names both (`acme.slug@2 (this table has acme.slug)`), so a client and a
1054
+ server on different deploys see which side is behind.
1055
+
787
1056
  ### Reading one back
788
1057
 
789
1058
  `Query.show(query)` renders a body as text, one clause per line:
@@ -822,7 +1091,9 @@ from queries, not from what a database could express.
822
1091
  | `Entity.page(selection, { first, after } or { last, before })` | In a Selection, a `many` relation read as a page: `items`, `hasNext`, `hasPrevious`. |
823
1092
  | `Entity.fields(entity, ...keys)` | The schemas of those fields, by key, to spread into an input's struct. |
824
1093
  | `Write.update(input, { id, expect?, when?, increment? })` | A declared update of one row: every key the input maps to a field, but the id and the expected revision; `when`, what the row must hold for it to land; `increment`, the number fields it moves by an input amount. |
825
- | `Write.reads(write)` | The fields a write reads from its row: its `when`'s, each it increments, the revision. |
1094
+ | `Write.reads(write)` | The fields a write reads from its row: its `when`'s, each it increments, its assignments', the revision. |
1095
+ | `Write.update(input, { …, compute })` / `Computation` | A field computed from the row before the write and the input, carried as data. |
1096
+ | `Write.apply(row, bound, { operators })` / `Write.boundReads(bound)` | The row a bound write leaves, and what of the row before it that needs. |
826
1097
  | `Write.writes(write)` / `Write.bind(write, value, keys?)` | The fields it may change; the row and values one input writes, encoded as the store holds them. |
827
1098
  | `Entity.input(entity, struct, mapping?)` | Experimental. Which member each key of an operation's input writes. |
828
1099
  | `Relation.nested(relation, input)` | In an input mapping: the key holds the target itself, written through `input`. |
@@ -837,20 +1108,30 @@ from queries, not from what a database could express.
837
1108
  | `Entity.is(value)` | Whether a value is an Entity descriptor. |
838
1109
  | `Expr.eq(left, right)` | Two values are the same: a field (or an expression) on the left, and the value on the right, which is typed from it; a predicate may stand where a boolean is wanted. A plain value on the left is a compile error that says so. |
839
1110
  | `Expr.isNull(field)` / `Expr.isNotNull(field)` | Whether a value is absent; one node, with the answer absence gives flipped. |
840
- | `Expr.contains(field, search)` | Whether text contains text, over a text or nullable-text operand only. Containing the empty string is everything, but a null contains nothing. |
1111
+ | `Expr.contains(field, search)` | Whether text contains a value or an input's text, over a text or nullable-text operand only. Containing the empty string is everything, but a null contains nothing. |
841
1112
  | `Expr.in(field, among)` | Whether a value is one of a list (written out, or an input), each compared as `eq` compares; SQL's `in`, an empty list matching nothing. |
842
1113
  | `Expr.and(a, b, …)` / `Expr.or(a, b, …)` | Every operand holds / at least one does, as SQL's three-valued `and` and `or`. At least one operand; a nested one of the same kind is flattened in. |
843
1114
  | `Expr.not(predicate)` | The predicate does not hold; an unknown stays unknown, so a null matches neither side. |
844
1115
  | `Expr.lt` / `lte` / `gt` / `gte(left, right, { collation? })` | One value orders before or after the other. Numbers as numbers; text only under `binary` or `asciiFold` (the field's declared collation, or the one given), and only against a field. |
845
1116
  | `Expr.whenGiven(input, given => predicate)` | A filter applying only when a nullable input is given: `or(isNull(input), predicate)`, the predicate seeing the input as never null. |
1117
+ | `Expr.operator(id, { input, output, definedAs?, version?, description?, nulls?, collation?, laws? })` | An operator: defined by what a call means (`definedAs`, whose expansion every interpreter runs) or primitive (each interpreter's table implements it). Calling it builds a `Test` predicate (a boolean output) or a `Call` scalar. |
1118
+ | `Expr.unsupported(nodes, { operations, operators })` | What these expressions need that an interpreter lacks: operations, then primitive operators by name. |
1119
+ | `Text.startsWith(text, prefix, { collation? })` | Whether text begins with a prefix, under its collation; the kernel's primitive operator. |
1120
+ | `Operators.memory(...)` / `implement` / `implementHandlingNulls` / `merge` / `override` / `checked` / `kernel` | Tables of in-memory implementations of primitive operators, passed to `evaluate` and every judge. |
1121
+ | `Law.associative` / `commutative` / `idempotent` / `identity` / `absorbing` / `inverse` / `distributes` / `monotonic` / `preservesCollation` / `within` / `describe` | Laws an operator declares (`Expr.operator(id, { laws })`), checked where declared, described as JSON. |
1122
+ | `Operators.withEvidence(table, evidence)` / `describeTable(table)` / `Evidence.Proven` | What is known of a table's implementations' laws, and the table as JSON. |
1123
+ | `Conformance.laws(op, table)` / `lawsBy(op, runner)` / `operator(op, { implementations })` / `memory(table)` (`foldkit-entity/conformance`) | Test an implementation's laws, in memory or through any runner; run one set of calls through several implementations. |
1124
+ | `Operators.describe(op)` / `OperatorDescription` / `Query.operators(body)` | An operator's signature as JSON, the Schema it keeps, and the operators a body calls, by name. |
1125
+ | `valueOfOperand(node, { operators })` | What an operand, a call of literals say, comes to over no row. |
1126
+ | `Expr.expanded(predicate)` | The predicate with every call of a defined operator written out as what it means, deeply; what an interpreter compiles. |
846
1127
  | `Expr.field(field)` | One field of one Entity, as a scalar. |
847
1128
  | `Expr.input(key, schema)` | A value the query is given when it runs, as a placeholder. |
848
1129
  | `Expr.literal(value)` | A constant. Comparisons coerce one, so this is rarely written. |
849
1130
  | `Order.asc(expr, { nulls? })` / `Order.desc(expr, { nulls? })` | One term of an ordering, over a field or a scalar. Rows without a value go last ascending and first descending unless `nulls` says otherwise; every interpreter is told, since databases disagree when it is unsaid. |
850
1131
  | `Collation.binary` / `.asciiFold` / `.locale(name)` / `.of(collation)` | How a text field orders, as member metadata; see above. |
851
1132
  | `ReadFilter.of(members)` / `.members(metadata)` | Entity metadata: the members a server filters rows by under a rule the client does not run (an authorization rule; `foldkit-guard` attaches it). A client placing rows in a list fetches the list instead when one changes. Annotations add up. |
852
- | `Query.placement(query, input)` | `Placeable`, or `NotPlaceable` with why: whether a client can order as the server does. |
853
- | `Order.chosen(sort, choices)` | The field an input's sort names (`{ by, direction }`, or `null` for none), among `choices`. |
1133
+ | `Query.placement(query, input, { operators })` | `Placeable`, or `NotPlaceable` with why: whether a client running `operators` can order as the server does. |
1134
+ | `Order.chosen(sort, choices)` | The field or call an input's sort names (`{ by, direction }`, or `null` for none), among `choices`. |
854
1135
  | `dependenciesOf(...nodes)` | The distinct fields, inputs, and operations those expressions use. |
855
1136
  | `Query.from(entity)` | Every row of an Entity: the query each step narrows. |
856
1137
  | `Query.where(...predicates)` | Pipe step keeping the rows those hold for; conjoins with what is there. |
@@ -1,6 +1,216 @@
1
- import { ft as AnyQuery, s as Entity } from "../index-BhI_DA2S.mjs";
2
- import { Schema } from "effect";
3
- //#region src/conformance/index.d.ts
1
+ import { $t as Operator, At as AnyQuery, Ct as MemoryOperators, Dt as TestedEvidence, En as Collation, Zt as Operandish, s as Entity, wn as LawDescription } from "../index-hu8IYlNc.mjs";
2
+ import { Data, Option, Schema } from "effect";
3
+ /** What an implementation said of one call: a value, or that it refused it. */
4
+ export type Outcome = Data.TaggedEnum<{
5
+ Value: {
6
+ readonly value: unknown;
7
+ };
8
+ Refused: {
9
+ readonly reason: string;
10
+ };
11
+ }>;
12
+ export declare const Outcome: {
13
+ readonly $is: <Tag extends "Refused" | "Value">(tag: Tag) => (u: unknown) => u is Extract<{
14
+ readonly _tag: "Refused";
15
+ readonly reason: string;
16
+ }, {
17
+ readonly _tag: Tag;
18
+ }> | Extract<{
19
+ readonly _tag: "Value";
20
+ readonly value: unknown;
21
+ }, {
22
+ readonly _tag: Tag;
23
+ }>;
24
+ readonly $match: {
25
+ <Cases extends { readonly [Tag in "Refused" | "Value"]: (args: Extract<{
26
+ readonly _tag: "Refused";
27
+ readonly reason: string;
28
+ } | {
29
+ readonly _tag: "Value";
30
+ readonly value: unknown;
31
+ }, {
32
+ readonly _tag: Tag;
33
+ }>) => any; }>(cases: Cases): (value: {
34
+ readonly _tag: "Refused";
35
+ readonly reason: string;
36
+ } | {
37
+ readonly _tag: "Value";
38
+ readonly value: unknown;
39
+ }) => import("effect/Unify").Unify<ReturnType<Cases["Refused" | "Value"]>>;
40
+ <Cases extends { readonly [Tag in "Refused" | "Value"]: (args: Extract<{
41
+ readonly _tag: "Refused";
42
+ readonly reason: string;
43
+ } | {
44
+ readonly _tag: "Value";
45
+ readonly value: unknown;
46
+ }, {
47
+ readonly _tag: Tag;
48
+ }>) => any; }>(value: {
49
+ readonly _tag: "Refused";
50
+ readonly reason: string;
51
+ } | {
52
+ readonly _tag: "Value";
53
+ readonly value: unknown;
54
+ }, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Refused" | "Value"]>>;
55
+ };
56
+ readonly Refused: Data.TaggedEnum.ConstructorFrom<{
57
+ readonly _tag: "Refused";
58
+ readonly reason: string;
59
+ }, "_tag">;
60
+ readonly Value: Data.TaggedEnum.ConstructorFrom<{
61
+ readonly _tag: "Value";
62
+ readonly value: unknown;
63
+ }, "_tag">;
64
+ };
65
+ /** What `Conformance.laws` found: every law held, with the evidence, or the first case one did not. */
66
+ export type LawsVerdict = Data.TaggedEnum<{
67
+ Holds: {
68
+ readonly evidence: ReadonlyArray<TestedEvidence>;
69
+ };
70
+ Counterexample: {
71
+ readonly law: LawDescription;
72
+ readonly args: ReadonlyArray<unknown>;
73
+ /** The collation the calls were made under, for an operator that compares text. */
74
+ readonly collation: Option.Option<Collation>;
75
+ readonly left: Outcome;
76
+ readonly right: Outcome;
77
+ };
78
+ }>;
79
+ export declare const LawsVerdict: {
80
+ readonly $is: <Tag extends "Counterexample" | "Holds">(tag: Tag) => (u: unknown) => u is Extract<{
81
+ readonly _tag: "Counterexample";
82
+ readonly law: LawDescription;
83
+ readonly args: ReadonlyArray<unknown>;
84
+ readonly collation: Option.Option<Collation>;
85
+ readonly left: Outcome;
86
+ readonly right: Outcome;
87
+ }, {
88
+ readonly _tag: Tag;
89
+ }> | Extract<{
90
+ readonly _tag: "Holds";
91
+ readonly evidence: ReadonlyArray<TestedEvidence>;
92
+ }, {
93
+ readonly _tag: Tag;
94
+ }>;
95
+ readonly $match: {
96
+ <Cases extends { readonly [Tag in "Counterexample" | "Holds"]: (args: Extract<{
97
+ readonly _tag: "Counterexample";
98
+ readonly law: LawDescription;
99
+ readonly args: ReadonlyArray<unknown>;
100
+ readonly collation: Option.Option<Collation>;
101
+ readonly left: Outcome;
102
+ readonly right: Outcome;
103
+ } | {
104
+ readonly _tag: "Holds";
105
+ readonly evidence: ReadonlyArray<TestedEvidence>;
106
+ }, {
107
+ readonly _tag: Tag;
108
+ }>) => any; }>(cases: Cases): (value: {
109
+ readonly _tag: "Counterexample";
110
+ readonly law: LawDescription;
111
+ readonly args: ReadonlyArray<unknown>;
112
+ readonly collation: Option.Option<Collation>;
113
+ readonly left: Outcome;
114
+ readonly right: Outcome;
115
+ } | {
116
+ readonly _tag: "Holds";
117
+ readonly evidence: ReadonlyArray<TestedEvidence>;
118
+ }) => import("effect/Unify").Unify<ReturnType<Cases["Counterexample" | "Holds"]>>;
119
+ <Cases extends { readonly [Tag in "Counterexample" | "Holds"]: (args: Extract<{
120
+ readonly _tag: "Counterexample";
121
+ readonly law: LawDescription;
122
+ readonly args: ReadonlyArray<unknown>;
123
+ readonly collation: Option.Option<Collation>;
124
+ readonly left: Outcome;
125
+ readonly right: Outcome;
126
+ } | {
127
+ readonly _tag: "Holds";
128
+ readonly evidence: ReadonlyArray<TestedEvidence>;
129
+ }, {
130
+ readonly _tag: Tag;
131
+ }>) => any; }>(value: {
132
+ readonly _tag: "Counterexample";
133
+ readonly law: LawDescription;
134
+ readonly args: ReadonlyArray<unknown>;
135
+ readonly collation: Option.Option<Collation>;
136
+ readonly left: Outcome;
137
+ readonly right: Outcome;
138
+ } | {
139
+ readonly _tag: "Holds";
140
+ readonly evidence: ReadonlyArray<TestedEvidence>;
141
+ }, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Counterexample" | "Holds"]>>;
142
+ };
143
+ readonly Counterexample: Data.TaggedEnum.ConstructorFrom<{
144
+ readonly _tag: "Counterexample";
145
+ readonly law: LawDescription;
146
+ readonly args: ReadonlyArray<unknown>;
147
+ readonly collation: Option.Option<Collation>;
148
+ readonly left: Outcome;
149
+ readonly right: Outcome;
150
+ }, "_tag">;
151
+ readonly Holds: Data.TaggedEnum.ConstructorFrom<{
152
+ readonly _tag: "Holds";
153
+ readonly evidence: ReadonlyArray<TestedEvidence>;
154
+ }, "_tag">;
155
+ };
156
+ /**
157
+ * One way to run a call: its value, or a throw for a call it refuses. A call
158
+ * of a predicate answers its truth, unknown as `null`.
159
+ */
160
+ export type Runner = (call: Operandish) => unknown;
161
+ /** A call the implementations did not agree on, with what each said. */
162
+ export interface Disagreement {
163
+ readonly args: ReadonlyArray<unknown>;
164
+ readonly collation: Option.Option<Collation>;
165
+ readonly outcomes: Readonly<Record<string, Outcome>>;
166
+ }
167
+ export interface OperatorReport {
168
+ /** How many calls ran, each through every implementation. */
169
+ readonly cases: number;
170
+ readonly disagreements: ReadonlyArray<Disagreement>;
171
+ }
172
+ export declare const Conformance: {
173
+ /** A runner of calls through a memory table: `Conformance.operator`'s for the in-memory interpreter. */
174
+ memory: (operators: MemoryOperators) => Runner;
175
+ /**
176
+ * Tests every law `op` declares against `operators`' implementation of it,
177
+ * up to `cases` tuples a law (200 by default), chosen by `seed` (0); a law
178
+ * of both sides checks each tuple from each. Holds with a `Tested` record a
179
+ * law, which `Operators.withEvidence` keeps; or the first case a law fails,
180
+ * with both sides.
181
+ */
182
+ laws: <In extends ReadonlyArray<Schema.Top>, Out extends Schema.Top>(op: Operator<In, Out>, operators: MemoryOperators, options?: {
183
+ readonly implementation?: string | undefined;
184
+ readonly cases?: number | undefined;
185
+ readonly seed?: number | undefined;
186
+ }) => LawsVerdict;
187
+ /**
188
+ * As `laws`, each call run by `run` instead of a memory table: an SQL
189
+ * implementation selected from a database, say, whose evidence a binding's
190
+ * SQL table records. A throw is a refusal.
191
+ */
192
+ lawsBy: <In extends ReadonlyArray<Schema.Top>, Out extends Schema.Top>(op: Operator<In, Out>, run: Runner, options: {
193
+ readonly implementation: string;
194
+ readonly cases?: number | undefined;
195
+ readonly seed?: number | undefined;
196
+ }) => Promise<LawsVerdict>;
197
+ /**
198
+ * Runs one set of calls of `op` through every implementation and compares
199
+ * what each answered or refused. The calls are `cases` (argument tuples, as
200
+ * stored), or generated: each argument a sample of its kind, null where its
201
+ * schema admits one, and text holding NUL, under `binary` and `asciiFold` where the operator compares
202
+ * text, up to `limit` (300) chosen by `seed` (0). A defined operator's
203
+ * expansion is run beside the others, as `expansion`, by `expansionTable`
204
+ * (the kernel's when not given).
205
+ */
206
+ operator: <In extends ReadonlyArray<Schema.Top>, Out extends Schema.Top>(op: Operator<In, Out>, options: {
207
+ readonly implementations: Readonly<Record<string, Runner>>;
208
+ readonly cases?: ReadonlyArray<ReadonlyArray<unknown>> | undefined;
209
+ readonly limit?: number | undefined;
210
+ readonly seed?: number | undefined;
211
+ readonly expansionTable?: MemoryOperators | undefined;
212
+ }) => Promise<OperatorReport>;
213
+ };
4
214
  /** The one Entity every case reads, with a column of each kind that matters. */
5
215
  export declare const Subject: Entity<"Subject", {
6
216
  readonly id: Schema.String;
@@ -42,6 +252,12 @@ export interface ConformanceCase {
42
252
  readonly expected: ReadonlyArray<string>;
43
253
  }
44
254
  export declare const cases: ReadonlyArray<ConformanceCase>;
255
+ /**
256
+ * Bodies calling the kernel's primitive operators (`Text.startsWith`). An
257
+ * interpreter runs these once it implements them: the in-memory one through
258
+ * `Operators.kernel`, a compiler through its own table.
259
+ */
260
+ export declare const primitiveCases: ReadonlyArray<ConformanceCase>;
45
261
  /**
46
262
  * A body whose answer no two interpreters agree on, so every interpreter must
47
263
  * refuse it rather than answer. Run each through yours and expect a failure.
@@ -53,5 +269,6 @@ export interface ConformanceRefusal {
53
269
  readonly input: Readonly<Record<string, unknown>>;
54
270
  }
55
271
  export declare const refusals: ReadonlyArray<ConformanceRefusal>;
56
- //#endregion
272
+ /** As `refusals`, for bodies calling the kernel's primitive operators. */
273
+ export declare const primitiveRefusals: ReadonlyArray<ConformanceRefusal>;
57
274
  //# sourceMappingURL=index.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.mts","names":[],"sources":["../../src/conformance/index.ts"],"mappings":";;;;qBA4Ca,SAAO;;;;;;;;;;;;;;;iBAmBH;WACN;WACA;WACA;WACA;;WAEA;YACC;;qBAGC,MAAM,cAAc;iBAQhB;;WAEN;WACA,MAAM;;;;;;;WAON,OAAO,SAAS;;WAEhB,UAAU;;qBA6BR,OAAO,cAAc;;;;;iBAudjB;WACN;WACA,MAAM;;WAEN,OAAO,SAAS;;qBAKd,UAAU,cAAc"}
1
+ {"version":3,"file":"index.d.mts","names":[],"sources":["../../src/conformance/operator.ts","../../src/conformance/index.ts"],"mappings":";;;YA+BY,UAAU,KAAK;EACzB;aAAkB;;EAClB;aAAoB;;;qBAET;;;aAFiB;;;;;aADH;;;;;;;eACG;;;eADH;;;;;;;;;;;;eACG;;;eADH;;;;;;;;;;;;;aACG;;;;aADH;;;;YAMf,cAAc,KAAK;EAC7B;aAAkB,UAAU,cAAc;;EAC1C;aACW,KAAK;aACL,MAAM;;aAEN,WAAW,OAAO,OAAO;aACzB,MAAM;aACN,OAAO;;;qBAGP;;;aARK,KAAA;aACC,MAAA;aAEK,WAAA,OAAO,OAAO;aACnB,MAAA;aACC,OAAA;;;;;aAPU,UAAA,cAAc;;;;;;;eAE1B,KAAA;eACC,MAAA;eAEK,WAAA,OAAO,OAAO;eACnB,MAAA;eACC,OAAA;;;eAPU,UAAA,cAAc;;;;;;;;;;;;;;;;eAE1B,KAAA;eACC,MAAA;eAEK,WAAA,OAAO,OAAO;eACnB,MAAA;eACC,OAAA;;;eAPU,UAAA,cAAc;;;;;;;;;;;;;;;;;aAE1B,KAAA;aACC,MAAA;aAEK,WAAA,OAAO,OAAO;aACnB,MAAA;aACC,OAAA;;;;aAPU,UAAA,cAAc;;;;;;;YAgBhC,UAAU,MAAM;;iBAGX;WACN,MAAM;WACN,WAAW,OAAO,OAAO;WACzB,UAAU,SAAS,eAAe;;iBAG5B;;WAEN;WACA,eAAe,cAAc;;qBAqV3B;;EAEX,SAAM,WACQ,oBAAkB;;;;;;;;EAWhC,OAAO,WAAW,cAAc,OAAO,MAAM,YAAY,OAAO,KAAG,IAC7D,SAAS,IAAI,MAAI,WACV,iBAAe;aAEf;aACA;aACA;QAEV;;;;;;EA4BH,SAAe,WAAW,cAAc,OAAO,MAAM,YAAY,OAAO,KAAG,IACrE,SAAS,IAAI,MAAI,KAChB,QAAM;aAEA;aACA;aACA;QAEV,QAAQ;;;;;;;;;;EAkCX,WAAiB,WAAW,cAAc,OAAO,MAAM,YAAY,OAAO,KAAG,IACvE,SAAS,IAAI,MAAI;aAEV,iBAAiB,SAAS,eAAe;aACzC,QAAQ,cAAc;aACtB;aACA;aACA,iBAAiB;QAE3B,QAAQ;;;qBCjdA,SAAO;;;;;;;;;;;;;;;iBAmBH;WACN;WACA;WACA;WACA;;WAEA;YACC;;qBAGC,MAAM,cAAc;iBAQhB;;WAEN;WACA,MAAM;;;;;;;WAON,OAAO,SAAS;;WAEhB,UAAU;;qBAwCR,OAAO,cAAc;;;;;;qBAqfrB,gBAAgB,cAAc;;;;;iBA0D1B;WACN;WACA,MAAM;;WAEN,OAAO,SAAS;;qBAKd,UAAU,cAAc;;qBAuBxB,mBAAmB,cAAc"}