foldkit-entity 0.11.0 → 0.12.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 +191 -7
- package/dist/conformance/index.d.mts +203 -4
- package/dist/conformance/index.d.mts.map +1 -1
- package/dist/conformance/index.mjs +351 -5
- package/dist/conformance/index.mjs.map +1 -1
- package/dist/{index-BhI_DA2S.d.mts → index-B9fbDo_-.d.mts} +727 -46
- package/dist/index-B9fbDo_-.d.mts.map +1 -0
- package/dist/index.d.mts +2 -2
- package/dist/index.mjs +1 -1
- package/dist/{src-DwKdHZDu.mjs → src-CSxcKUv6.mjs} +861 -120
- package/dist/src-CSxcKUv6.mjs.map +1 -0
- package/package.json +1 -1
- package/dist/index-BhI_DA2S.d.mts.map +0 -1
- package/dist/src-DwKdHZDu.mjs.map +0 -1
package/README.md
CHANGED
|
@@ -708,10 +708,11 @@ Query.placement(byName, {}) // { _tag: 'Placeable' }
|
|
|
708
708
|
never by a client.
|
|
709
709
|
|
|
710
710
|
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),
|
|
713
|
-
portable collation
|
|
714
|
-
is `NotPlaceable`, with
|
|
711
|
+
`Query.placement(query, input, { operators })` 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), over text with a
|
|
713
|
+
portable collation, or a call whose primitive operators the client's table runs. A body with no
|
|
714
|
+
order, text with none declared, a locale, or an operator the table lacks is `NotPlaceable`, with
|
|
715
|
+
the reason.
|
|
715
716
|
`foldkit-crud`'s `Sort.make(['title', 'id']).Schema` is such a sort.
|
|
716
717
|
|
|
717
718
|
The list of predicates **is** the conjunction: a query wanting three
|
|
@@ -719,7 +720,7 @@ conditions writes three `where`s. `Expr.and` is for a conjunction inside
|
|
|
719
720
|
something else, and `Expr.or` and `Expr.not` are the other two connectives:
|
|
720
721
|
|
|
721
722
|
```ts
|
|
722
|
-
// A search over two fields:
|
|
723
|
+
// A search over two fields: a product whose description or UPC holds the text.
|
|
723
724
|
Expr.or(
|
|
724
725
|
Expr.contains(Product.fields.description, input.search),
|
|
725
726
|
Expr.contains(Product.fields.upc, input.search),
|
|
@@ -784,6 +785,180 @@ matters is that it refuses rather than skipping the operation — an interpreter
|
|
|
784
785
|
that quietly drops a `contains` it cannot compile answers a different question
|
|
785
786
|
in full confidence, and every test it does support still passes.
|
|
786
787
|
|
|
788
|
+
### Naming a question: operators
|
|
789
|
+
|
|
790
|
+
A predicate an application asks in many places (in a public query, a
|
|
791
|
+
visitor's Read rule, an invariant) can be given a name. `Expr.operator`
|
|
792
|
+
declares one by what a call of it means:
|
|
793
|
+
|
|
794
|
+
```ts
|
|
795
|
+
import { Schema } from 'effect'
|
|
796
|
+
import { Entity, Expr, Query } from 'foldkit-entity'
|
|
797
|
+
|
|
798
|
+
const Story = Entity.define(
|
|
799
|
+
'Story',
|
|
800
|
+
Schema.Struct({ id: Schema.String, publishedAt: Schema.NullOr(Schema.String) }),
|
|
801
|
+
)
|
|
802
|
+
|
|
803
|
+
const published = Expr.operator('acme.published', {
|
|
804
|
+
input: [Schema.Unknown],
|
|
805
|
+
output: Schema.Boolean,
|
|
806
|
+
definedAs: publishedAt => Expr.isNotNull(publishedAt),
|
|
807
|
+
})
|
|
808
|
+
|
|
809
|
+
const PublicStories = Query.from(Story).pipe(Query.where(published(Story.fields.publishedAt)))
|
|
810
|
+
Query.show(PublicStories)
|
|
811
|
+
// FROM Story
|
|
812
|
+
// WHERE acme.published(Story.publishedAt)
|
|
813
|
+
```
|
|
814
|
+
|
|
815
|
+
- **It computes nothing of its own.** `definedAs` builds an expression from a
|
|
816
|
+
call's arguments, once per call, and every interpreter runs that expression
|
|
817
|
+
(`Expr.expanded` writes a predicate's calls out), so the operator needs no
|
|
818
|
+
SQL, no evaluator, and no support list. The SQL a body compiles to is the SQL
|
|
819
|
+
of the body written out by hand.
|
|
820
|
+
- **What it adds is a name.** `Query.show` prints the call, and
|
|
821
|
+
`Query.dependencies(body).operators` lists each operator a body uses.
|
|
822
|
+
- **It reads only its arguments.** A `definedAs` that closes over a field or an
|
|
823
|
+
input, instead of taking it, is refused when called: nothing asking what the
|
|
824
|
+
call reads (Guard's checks, Remote's matching) would see it.
|
|
825
|
+
- **Arguments are checked by their stored form**, at compile time and when
|
|
826
|
+
called: a field, scalar or plain value of the input's stored type, or a
|
|
827
|
+
predicate where it takes a boolean. A boolean `output` makes a call a
|
|
828
|
+
predicate, usable in `and`, `or`, `not`, a guard or an invariant with no cast;
|
|
829
|
+
any other makes it a scalar of that type.
|
|
830
|
+
- **Ids are namespaced** (`acme.published`), and `foldkit.` is reserved.
|
|
831
|
+
`version` (default 1) changes when what it means does; a call prints it after
|
|
832
|
+
the first (`acme.published@2(…)`).
|
|
833
|
+
|
|
834
|
+
`foldkit-cms` declares one over its `published` role: `Cms.published(entity)`.
|
|
835
|
+
|
|
836
|
+
### Operators each interpreter implements
|
|
837
|
+
|
|
838
|
+
Without `definedAs`, an operator is **primitive**: it means what each
|
|
839
|
+
interpreter's implementation does, and every implementation is held to the
|
|
840
|
+
same statement of it. The kernel ships one, `Text.startsWith`; an application
|
|
841
|
+
declares its own and implements it, here for the in-memory interpreter:
|
|
842
|
+
|
|
843
|
+
```ts
|
|
844
|
+
import { Schema } from 'effect'
|
|
845
|
+
import { Collation, Entity, Expr, Operators, Query, Text, evaluate } from 'foldkit-entity'
|
|
846
|
+
|
|
847
|
+
const Product = Entity.define(
|
|
848
|
+
'Product',
|
|
849
|
+
Schema.Struct({ id: Schema.String, upc: Schema.String, label: Schema.String }),
|
|
850
|
+
).pipe(Entity.annotateMembers({ upc: Collation.of(Collation.binary) }))
|
|
851
|
+
const search = Expr.input('search', Schema.String)
|
|
852
|
+
|
|
853
|
+
// The UPC declares `binary`, so it compares exactly; the label declares nothing,
|
|
854
|
+
// so this call is given a collation.
|
|
855
|
+
const ByCode = Query.from(Product).pipe(Query.where(Text.startsWith(Product.fields.upc, search)))
|
|
856
|
+
Text.startsWith(Product.fields.label, search, { collation: Collation.asciiFold })
|
|
857
|
+
|
|
858
|
+
const joined = Expr.operator('acme.joined', {
|
|
859
|
+
input: [Schema.String, Schema.String],
|
|
860
|
+
output: Schema.String,
|
|
861
|
+
collation: 'operands',
|
|
862
|
+
})
|
|
863
|
+
const operators = Operators.merge(
|
|
864
|
+
Operators.kernel,
|
|
865
|
+
Operators.memory(Operators.implement(joined, (left, right) => `${left}${right}`)),
|
|
866
|
+
)
|
|
867
|
+
evaluate(ByCode, { search: '012' }, [{ id: 'p1', upc: '0123', label: 'Bolt' }], { operators })
|
|
868
|
+
// [{ id: 'p1', upc: '0123', label: 'Bolt' }]
|
|
869
|
+
```
|
|
870
|
+
|
|
871
|
+
`startsWith` compares under its text's collation (`binary` exactly, `asciiFold`
|
|
872
|
+
folding ASCII letters on both sides), is unknown when either side is null, and
|
|
873
|
+
holds for the empty prefix; text with no collation, or a backend's locale, is
|
|
874
|
+
refused where it is written.
|
|
875
|
+
|
|
876
|
+
- **A table is a value.** `Operators.memory` refuses one operator implemented
|
|
877
|
+
twice, or two under one name; `merge` refuses an overlap, and `override`
|
|
878
|
+
replaces on purpose. `Operators.checked(table)` checks each answer against
|
|
879
|
+
the operator's output schema, for tests. Nothing registers globally:
|
|
880
|
+
`evaluate`, `decided`, `truthOver`, `Entity.judge`, `Entity.judgeInput` and
|
|
881
|
+
`Entity.check(entity, { operators })` each take the table, `Operators.kernel`
|
|
882
|
+
by default.
|
|
883
|
+
- **Null is strict by default.** A null argument gives null (unknown for a
|
|
884
|
+
predicate) and the implementation never sees one. `nulls: 'handled'`
|
|
885
|
+
operators are implemented with `Operators.implementHandlingNulls` and answer
|
|
886
|
+
for null themselves; a predicate answers `null` for unknown.
|
|
887
|
+
- **Text has a collation or no comparison.** `collation: 'operands'` makes a
|
|
888
|
+
text result carry the collation its text arguments share, so
|
|
889
|
+
`Expr.lt(joined(a, b), x)` compares under it; `'required'` (as
|
|
890
|
+
`startsWith`) refuses text with none. A call may be given one:
|
|
891
|
+
`op(a, b, { collation })`.
|
|
892
|
+
- **A call orders when its result does.** `Order.asc(joined(Product.fields.upc, '!'))`
|
|
893
|
+
orders by the call's text under the collation it carries, and a call giving a
|
|
894
|
+
number orders as one; anything else, text with no collation included, is
|
|
895
|
+
refused where the term or `Order.chosen` alternative is written. `evaluate`
|
|
896
|
+
runs it per row by its table, and `compareRows(terms, a, b, query, { input,
|
|
897
|
+
operators })` compares two rows the same way.
|
|
898
|
+
- **What a table lacks is refused by name.** `Query.unsupported(body,
|
|
899
|
+
supported, operators)` and `Expr.unsupported(nodes, { operations,
|
|
900
|
+
operators })` name each operation and operator missing; `evaluate` refuses
|
|
901
|
+
such a body. An invariant calling an operator its judge's table lacks is
|
|
902
|
+
`Undecided` with that operator in `operators`, which a form passes and a
|
|
903
|
+
server refuses to start without.
|
|
904
|
+
- **NUL is refused** in any text argument, and an implementation that throws
|
|
905
|
+
is reported as a `QueryEvaluateError` naming its operator.
|
|
906
|
+
|
|
907
|
+
### Laws, and holding an implementation to them
|
|
908
|
+
|
|
909
|
+
An operator may declare the equations every implementation of it keeps. A law
|
|
910
|
+
describes: nothing rewrites a body by one. `Conformance.laws` tests an
|
|
911
|
+
implementation against them, and what it finds is evidence its table records.
|
|
912
|
+
|
|
913
|
+
```ts
|
|
914
|
+
import { Schema } from 'effect'
|
|
915
|
+
import { Expr, Law, Operators } from 'foldkit-entity'
|
|
916
|
+
import { Conformance } from 'foldkit-entity/conformance'
|
|
917
|
+
|
|
918
|
+
const concat = Expr.operator('acme.concat', {
|
|
919
|
+
input: [Schema.String, Schema.String],
|
|
920
|
+
output: Schema.String,
|
|
921
|
+
collation: 'operands',
|
|
922
|
+
laws: [Law.associative, Law.identity(''), Law.preservesCollation],
|
|
923
|
+
})
|
|
924
|
+
const table = Operators.memory(Operators.implement(concat, (left, right) => `${left}${right}`))
|
|
925
|
+
|
|
926
|
+
const verdict = Conformance.laws(concat, table) // { _tag: 'Holds', evidence: [...] }
|
|
927
|
+
const recorded =
|
|
928
|
+
verdict._tag === 'Holds' ? Operators.withEvidence(table, verdict.evidence) : table
|
|
929
|
+
Operators.describeTable(recorded) // [{ operator: 'acme.concat', laws, evidence }]
|
|
930
|
+
```
|
|
931
|
+
|
|
932
|
+
- **A law is checked where it is declared.** `Law.commutative`, `associative`,
|
|
933
|
+
`idempotent`, `identity(value, side?)`, `absorbing(value, side?)`,
|
|
934
|
+
`inverse(other, identity)` and `distributes(over)` are laws of an operator of
|
|
935
|
+
two arguments; `monotonic(direction, position)` names an argument it has, and
|
|
936
|
+
`preservesCollation` needs `collation: 'operands'`. A witness that is not a
|
|
937
|
+
value the argument's schema stores is refused.
|
|
938
|
+
- **Its domain** is every non-null value of the input schemas, narrowed with
|
|
939
|
+
`Law.within(law, schema)` where a law holds of less (a square is increasing
|
|
940
|
+
over the non-negative numbers only). Strict null makes both sides null, so no
|
|
941
|
+
law needs a null case.
|
|
942
|
+
- **Testing is sampling, seeded.** Cases come from a fixed sample of each kind
|
|
943
|
+
(the empty string, mixed case, non-ASCII and astral text; zero, negatives, a
|
|
944
|
+
fraction), kept where the schemas decode them, up to `cases` (200) a law
|
|
945
|
+
chosen by `seed` (0). The verdict is `Holds` with one `Tested` record a law,
|
|
946
|
+
or the first `Counterexample` with both sides: declaring `concat` commutative
|
|
947
|
+
finds `"a"` and `"A"`, which give `"aA"` and `"Aa"`.
|
|
948
|
+
- **Evidence is an implementation's.** `Operators.withEvidence` refuses a record
|
|
949
|
+
of an operator the table lacks or a law it does not declare; `override` drops
|
|
950
|
+
a replaced implementation's records, `merge` keeps both tables'.
|
|
951
|
+
`Evidence.Proven` records a proof made elsewhere, never checked here.
|
|
952
|
+
|
|
953
|
+
`Conformance.operator(op, { implementations })` runs one set of calls through
|
|
954
|
+
every implementation given and reports where they disagree, a refusal included:
|
|
955
|
+
generated from each argument's samples, null where its schema admits one, and
|
|
956
|
+
text holding NUL, under `binary` and `asciiFold` where the operator compares
|
|
957
|
+
text. `Conformance.memory(table)` is the reference interpreter's runner; a
|
|
958
|
+
defined operator's expansion runs beside the others. `foldkit-remote-drizzle`
|
|
959
|
+
runs the kernel's operators and an application's through it on SQLite and
|
|
960
|
+
Postgres.
|
|
961
|
+
|
|
787
962
|
### Reading one back
|
|
788
963
|
|
|
789
964
|
`Query.show(query)` renders a body as text, one clause per line:
|
|
@@ -843,14 +1018,23 @@ from queries, not from what a database could express.
|
|
|
843
1018
|
| `Expr.not(predicate)` | The predicate does not hold; an unknown stays unknown, so a null matches neither side. |
|
|
844
1019
|
| `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
1020
|
| `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. |
|
|
1021
|
+
| `Expr.operator(id, { input, output, definedAs, version?, description? })` | An operator defined by what a call means; calling it builds a `Test` predicate (a boolean output) or a `Call` scalar, whose expansion every interpreter runs. |
|
|
1022
|
+
| `Expr.unsupported(nodes, { operations, operators })` | What these expressions need that an interpreter lacks: operations, then primitive operators by name. |
|
|
1023
|
+
| `Text.startsWith(text, prefix, { collation? })` | Whether text begins with a prefix, under its collation; the kernel's primitive operator. |
|
|
1024
|
+
| `Operators.memory(...)` / `implement` / `implementHandlingNulls` / `merge` / `override` / `checked` / `kernel` | Tables of in-memory implementations of primitive operators, passed to `evaluate` and every judge. |
|
|
1025
|
+
| `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. |
|
|
1026
|
+
| `Operators.withEvidence(table, evidence)` / `describeTable(table)` / `Evidence.Proven` | What is known of a table's implementations' laws, and the table as JSON. |
|
|
1027
|
+
| `Conformance.laws(op, table)` / `operator(op, { implementations })` / `memory(table)` (`foldkit-entity/conformance`) | Test an implementation's laws; run one set of calls through several implementations. |
|
|
1028
|
+
| `valueOfOperand(node, { operators })` | What an operand, a call of literals say, comes to over no row. |
|
|
1029
|
+
| `Expr.expanded(predicate)` | The predicate with every call of a defined operator written out as what it means, deeply; what an interpreter compiles. |
|
|
846
1030
|
| `Expr.field(field)` | One field of one Entity, as a scalar. |
|
|
847
1031
|
| `Expr.input(key, schema)` | A value the query is given when it runs, as a placeholder. |
|
|
848
1032
|
| `Expr.literal(value)` | A constant. Comparisons coerce one, so this is rarely written. |
|
|
849
1033
|
| `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
1034
|
| `Collation.binary` / `.asciiFold` / `.locale(name)` / `.of(collation)` | How a text field orders, as member metadata; see above. |
|
|
851
1035
|
| `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`. |
|
|
1036
|
+
| `Query.placement(query, input, { operators })` | `Placeable`, or `NotPlaceable` with why: whether a client running `operators` can order as the server does. |
|
|
1037
|
+
| `Order.chosen(sort, choices)` | The field or call an input's sort names (`{ by, direction }`, or `null` for none), among `choices`. |
|
|
854
1038
|
| `dependenciesOf(...nodes)` | The distinct fields, inputs, and operations those expressions use. |
|
|
855
1039
|
| `Query.from(entity)` | Every row of an Entity: the query each step narrows. |
|
|
856
1040
|
| `Query.where(...predicates)` | Pipe step keeping the rows those hold for; conjoins with what is there. |
|
|
@@ -1,6 +1,198 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { Schema } from "effect";
|
|
3
|
-
|
|
1
|
+
import { Ct as AnyQuery, Kt as Operator, Wt as Operandish, _t as MemoryOperators, bt as TestedEvidence, gn as LawDescription, s as Entity, vn as Collation } from "../index-B9fbDo_-.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
|
+
readonly left: Outcome;
|
|
74
|
+
readonly right: Outcome;
|
|
75
|
+
};
|
|
76
|
+
}>;
|
|
77
|
+
export declare const LawsVerdict: {
|
|
78
|
+
readonly $is: <Tag extends "Counterexample" | "Holds">(tag: Tag) => (u: unknown) => u is Extract<{
|
|
79
|
+
readonly _tag: "Counterexample";
|
|
80
|
+
readonly law: LawDescription;
|
|
81
|
+
readonly args: ReadonlyArray<unknown>;
|
|
82
|
+
readonly left: Outcome;
|
|
83
|
+
readonly right: Outcome;
|
|
84
|
+
}, {
|
|
85
|
+
readonly _tag: Tag;
|
|
86
|
+
}> | Extract<{
|
|
87
|
+
readonly _tag: "Holds";
|
|
88
|
+
readonly evidence: ReadonlyArray<TestedEvidence>;
|
|
89
|
+
}, {
|
|
90
|
+
readonly _tag: Tag;
|
|
91
|
+
}>;
|
|
92
|
+
readonly $match: {
|
|
93
|
+
<Cases extends { readonly [Tag in "Counterexample" | "Holds"]: (args: Extract<{
|
|
94
|
+
readonly _tag: "Counterexample";
|
|
95
|
+
readonly law: LawDescription;
|
|
96
|
+
readonly args: ReadonlyArray<unknown>;
|
|
97
|
+
readonly left: Outcome;
|
|
98
|
+
readonly right: Outcome;
|
|
99
|
+
} | {
|
|
100
|
+
readonly _tag: "Holds";
|
|
101
|
+
readonly evidence: ReadonlyArray<TestedEvidence>;
|
|
102
|
+
}, {
|
|
103
|
+
readonly _tag: Tag;
|
|
104
|
+
}>) => any; }>(cases: Cases): (value: {
|
|
105
|
+
readonly _tag: "Counterexample";
|
|
106
|
+
readonly law: LawDescription;
|
|
107
|
+
readonly args: ReadonlyArray<unknown>;
|
|
108
|
+
readonly left: Outcome;
|
|
109
|
+
readonly right: Outcome;
|
|
110
|
+
} | {
|
|
111
|
+
readonly _tag: "Holds";
|
|
112
|
+
readonly evidence: ReadonlyArray<TestedEvidence>;
|
|
113
|
+
}) => import("effect/Unify").Unify<ReturnType<Cases["Counterexample" | "Holds"]>>;
|
|
114
|
+
<Cases extends { readonly [Tag in "Counterexample" | "Holds"]: (args: Extract<{
|
|
115
|
+
readonly _tag: "Counterexample";
|
|
116
|
+
readonly law: LawDescription;
|
|
117
|
+
readonly args: ReadonlyArray<unknown>;
|
|
118
|
+
readonly left: Outcome;
|
|
119
|
+
readonly right: Outcome;
|
|
120
|
+
} | {
|
|
121
|
+
readonly _tag: "Holds";
|
|
122
|
+
readonly evidence: ReadonlyArray<TestedEvidence>;
|
|
123
|
+
}, {
|
|
124
|
+
readonly _tag: Tag;
|
|
125
|
+
}>) => any; }>(value: {
|
|
126
|
+
readonly _tag: "Counterexample";
|
|
127
|
+
readonly law: LawDescription;
|
|
128
|
+
readonly args: ReadonlyArray<unknown>;
|
|
129
|
+
readonly left: Outcome;
|
|
130
|
+
readonly right: Outcome;
|
|
131
|
+
} | {
|
|
132
|
+
readonly _tag: "Holds";
|
|
133
|
+
readonly evidence: ReadonlyArray<TestedEvidence>;
|
|
134
|
+
}, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Counterexample" | "Holds"]>>;
|
|
135
|
+
};
|
|
136
|
+
readonly Counterexample: Data.TaggedEnum.ConstructorFrom<{
|
|
137
|
+
readonly _tag: "Counterexample";
|
|
138
|
+
readonly law: LawDescription;
|
|
139
|
+
readonly args: ReadonlyArray<unknown>;
|
|
140
|
+
readonly left: Outcome;
|
|
141
|
+
readonly right: Outcome;
|
|
142
|
+
}, "_tag">;
|
|
143
|
+
readonly Holds: Data.TaggedEnum.ConstructorFrom<{
|
|
144
|
+
readonly _tag: "Holds";
|
|
145
|
+
readonly evidence: ReadonlyArray<TestedEvidence>;
|
|
146
|
+
}, "_tag">;
|
|
147
|
+
};
|
|
148
|
+
/**
|
|
149
|
+
* One way to run a call: its value, or a throw for a call it refuses. A call
|
|
150
|
+
* of a predicate answers its truth, unknown as `null`.
|
|
151
|
+
*/
|
|
152
|
+
export type Runner = (call: Operandish) => unknown;
|
|
153
|
+
/** A call the implementations did not agree on, with what each said. */
|
|
154
|
+
export interface Disagreement {
|
|
155
|
+
readonly args: ReadonlyArray<unknown>;
|
|
156
|
+
readonly collation: Option.Option<Collation>;
|
|
157
|
+
readonly outcomes: Readonly<Record<string, Outcome>>;
|
|
158
|
+
}
|
|
159
|
+
export interface OperatorReport {
|
|
160
|
+
/** How many calls ran, each through every implementation. */
|
|
161
|
+
readonly cases: number;
|
|
162
|
+
readonly disagreements: ReadonlyArray<Disagreement>;
|
|
163
|
+
}
|
|
164
|
+
export declare const Conformance: {
|
|
165
|
+
/** A runner of calls through a memory table: `Conformance.operator`'s for the in-memory interpreter. */
|
|
166
|
+
memory: (operators: MemoryOperators) => Runner;
|
|
167
|
+
/**
|
|
168
|
+
* Tests every law `op` declares against `operators`' implementation of it,
|
|
169
|
+
* up to `cases` tuples a law (200 by default), chosen by `seed` (0); a law
|
|
170
|
+
* of both sides checks each tuple from each. Holds
|
|
171
|
+
* with a `Tested` record a law, which `Operators.withEvidence` keeps; or the
|
|
172
|
+
* first case a law fails, with both sides.
|
|
173
|
+
*/
|
|
174
|
+
laws: <In extends ReadonlyArray<Schema.Top>, Out extends Schema.Top>(op: Operator<In, Out>, operators: MemoryOperators, options?: {
|
|
175
|
+
readonly implementation?: string | undefined;
|
|
176
|
+
readonly cases?: number | undefined;
|
|
177
|
+
readonly seed?: number | undefined;
|
|
178
|
+
}) => LawsVerdict;
|
|
179
|
+
/**
|
|
180
|
+
* Runs one set of calls of `op` through every implementation and compares
|
|
181
|
+
* what each answered or refused. The calls are `cases` (argument tuples, as
|
|
182
|
+
* stored), or generated: each argument a sample of its kind, null where its
|
|
183
|
+
* schema admits one, and text holding NUL, under `binary` and `asciiFold` where the operator compares
|
|
184
|
+
* text, up to `limit` (300) chosen by `seed` (0). A defined operator's
|
|
185
|
+
* expansion is run beside the others, as `expansion`, by `expansionTable`
|
|
186
|
+
* (the kernel's when not given).
|
|
187
|
+
*/
|
|
188
|
+
operator: <In extends ReadonlyArray<Schema.Top>, Out extends Schema.Top>(op: Operator<In, Out>, options: {
|
|
189
|
+
readonly implementations: Readonly<Record<string, Runner>>;
|
|
190
|
+
readonly cases?: ReadonlyArray<ReadonlyArray<unknown>> | undefined;
|
|
191
|
+
readonly limit?: number | undefined;
|
|
192
|
+
readonly seed?: number | undefined;
|
|
193
|
+
readonly expansionTable?: MemoryOperators | undefined;
|
|
194
|
+
}) => Promise<OperatorReport>;
|
|
195
|
+
};
|
|
4
196
|
/** The one Entity every case reads, with a column of each kind that matters. */
|
|
5
197
|
export declare const Subject: Entity<"Subject", {
|
|
6
198
|
readonly id: Schema.String;
|
|
@@ -42,6 +234,12 @@ export interface ConformanceCase {
|
|
|
42
234
|
readonly expected: ReadonlyArray<string>;
|
|
43
235
|
}
|
|
44
236
|
export declare const cases: ReadonlyArray<ConformanceCase>;
|
|
237
|
+
/**
|
|
238
|
+
* Bodies calling the kernel's primitive operators (`Text.startsWith`). An
|
|
239
|
+
* interpreter runs these once it implements them: the in-memory one through
|
|
240
|
+
* `Operators.kernel`, a compiler through its own table.
|
|
241
|
+
*/
|
|
242
|
+
export declare const primitiveCases: ReadonlyArray<ConformanceCase>;
|
|
45
243
|
/**
|
|
46
244
|
* A body whose answer no two interpreters agree on, so every interpreter must
|
|
47
245
|
* refuse it rather than answer. Run each through yours and expect a failure.
|
|
@@ -53,5 +251,6 @@ export interface ConformanceRefusal {
|
|
|
53
251
|
readonly input: Readonly<Record<string, unknown>>;
|
|
54
252
|
}
|
|
55
253
|
export declare const refusals: ReadonlyArray<ConformanceRefusal>;
|
|
56
|
-
|
|
254
|
+
/** As `refusals`, for bodies calling the kernel's primitive operators. */
|
|
255
|
+
export declare const primitiveRefusals: ReadonlyArray<ConformanceRefusal>;
|
|
57
256
|
//# sourceMappingURL=index.d.mts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/conformance/index.ts"],"mappings":";;;;
|
|
1
|
+
{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/conformance/operator.ts","../../src/conformance/index.ts"],"mappings":";;;YA8BY,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;aACN,MAAM;aACN,OAAO;;;qBAGP;;;aANK,KAAA;aACC,MAAA;aACA,MAAA;aACC,OAAA;;;;;aALU,UAAA,cAAc;;;;;;;eAE1B,KAAA;eACC,MAAA;eACA,MAAA;eACC,OAAA;;;eALU,UAAA,cAAc;;;;;;;;;;;;;;;eAE1B,KAAA;eACC,MAAA;eACA,MAAA;eACC,OAAA;;;eALU,UAAA,cAAc;;;;;;;;;;;;;;;;aAE1B,KAAA;aACC,MAAA;aACA,MAAA;aACC,OAAA;;;;aALU,UAAA,cAAc;;;;;;;YAchC,UAAU,MAAM;;iBAGX;WACN,MAAM;WACN,WAAW,OAAO,OAAO;WACzB,UAAU,SAAS,eAAe;;iBAG5B;;WAEN;WACA,eAAe,cAAc;;qBA0G3B;;EAEX,SAAM,WACQ,oBAAkB;;;;;;;;EAWhC,OAAO,WAAW,cAAc,OAAO,MAAM,YAAY,OAAO,KAAG,IAC7D,SAAS,IAAI,MAAI,WACV,iBAAe;aAEf;aACA;aACA;QAEV;;;;;;;;;;EAwIH,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;;;qBCrSA,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"}
|