foldkit-entity 0.16.0 → 0.17.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 +121 -18
- package/dist/conformance/index.d.ts.map +1 -1
- package/dist/conformance/index.js +20 -0
- package/dist/conformance/index.js.map +1 -1
- package/dist/conformance/operator.d.ts.map +1 -1
- package/dist/conformance/operator.js +13 -4
- package/dist/conformance/operator.js.map +1 -1
- package/dist/entity.d.ts +13 -1
- package/dist/entity.d.ts.map +1 -1
- package/dist/entity.js +40 -12
- package/dist/entity.js.map +1 -1
- package/dist/evaluate.d.ts +1 -1
- package/dist/evaluate.d.ts.map +1 -1
- package/dist/evaluate.js +22 -18
- package/dist/evaluate.js.map +1 -1
- package/dist/expr.d.ts +70 -20
- package/dist/expr.d.ts.map +1 -1
- package/dist/expr.js +67 -47
- package/dist/expr.js.map +1 -1
- package/dist/held.js +11 -3
- package/dist/held.js.map +1 -1
- package/dist/index.d.ts +16 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -3
- package/dist/index.js.map +1 -1
- package/dist/invariant.d.ts.map +1 -1
- package/dist/invariant.js +25 -19
- package/dist/invariant.js.map +1 -1
- package/dist/law.d.ts.map +1 -1
- package/dist/law.js +3 -9
- package/dist/law.js.map +1 -1
- package/dist/lawCore.d.ts +42 -0
- package/dist/lawCore.d.ts.map +1 -0
- package/dist/lawCore.js +12 -0
- package/dist/lawCore.js.map +1 -0
- package/dist/memoryTable.d.ts +11 -0
- package/dist/memoryTable.d.ts.map +1 -0
- package/dist/memoryTable.js +69 -0
- package/dist/memoryTable.js.map +1 -0
- package/dist/operators.d.ts.map +1 -1
- package/dist/operators.js +2 -66
- package/dist/operators.js.map +1 -1
- package/dist/sets.js.map +1 -1
- package/dist/write.d.ts +1 -1
- package/dist/write.d.ts.map +1 -1
- package/dist/write.js +40 -18
- package/dist/write.js.map +1 -1
- package/package.json +1 -1
package/dist/held.js
CHANGED
|
@@ -57,8 +57,11 @@ const rowsOf = (tables) => {
|
|
|
57
57
|
let missing = from.complete ? Option.none() : Option.some(`not every ${relation.owner.name} is held`);
|
|
58
58
|
for (const each of from.views) {
|
|
59
59
|
const link = each.field(relation.key);
|
|
60
|
-
if (link._tag === "Unheld")
|
|
61
|
-
|
|
60
|
+
if (link._tag === "Unheld") {
|
|
61
|
+
missing = Option.orElse(missing, () => Option.some(link.reason));
|
|
62
|
+
continue;
|
|
63
|
+
}
|
|
64
|
+
if (link.value === id) rows.push(each);
|
|
62
65
|
}
|
|
63
66
|
return {
|
|
64
67
|
rows,
|
|
@@ -144,7 +147,12 @@ const Held = {
|
|
|
144
147
|
of: held,
|
|
145
148
|
/** A value the holder does not have, and why. */
|
|
146
149
|
unheld,
|
|
147
|
-
match: (value, cases) =>
|
|
150
|
+
match: (value, cases) => {
|
|
151
|
+
switch (value._tag) {
|
|
152
|
+
case "Held": return cases.onHeld(value.value);
|
|
153
|
+
case "Unheld": return cases.onUnheld(value.reason);
|
|
154
|
+
}
|
|
155
|
+
},
|
|
148
156
|
/** Rows held as plain records; see `HeldTable`. */
|
|
149
157
|
rows: rowsOf,
|
|
150
158
|
fromRefs,
|
package/dist/held.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"held.js","names":[],"sources":["../src/held.ts"],"sourcesContent":["/**\n * What a holder of rows has: the world `Judge` reads an `Expr` over.\n *\n * A server's database holds every row, so whatever an expression asks has an\n * answer there. A client holds what it was sent: some rows, some fields of\n * them, and none it may not see. `HeldRow` is how a holder says which, so an\n * interpreter can tell \"this field is null\" from \"I do not have this field\",\n * which a plain record cannot: both read as a missing key.\n */\nimport { Option } from 'effect'\nimport { relationsOf } from './descriptor.js'\nimport { Query, type AnyQuery, type OneRelation } from './expr.js'\nimport type { AnyEntity, EntityIdentity, EntityMember } from './index.js'\nimport { own, put } from './record.js'\n\n/** A value a holder has, or why it does not have it. */\nexport type Held<A> =\n | { readonly _tag: 'Held'; readonly value: A }\n | { readonly _tag: 'Unheld'; readonly reason: string }\n\n/** The rows pointing at one row through a relation, as far as a holder has them. */\nexport interface Pointing {\n readonly rows: ReadonlyArray<HeldRow>\n /**\n * Why a row pointing here may be missing from `rows`; none when it holds\n * every one whose fields hold the values `pinned` names.\n */\n readonly missing: Option.Option<string>\n}\n\n/**\n * The values an exists' filter fixes on the rows it counts, by field key (a\n * link as the id it points at): a row with another value in one of them is\n * not counted, so a holder holding every pointing row with these values holds\n * every one that counts (`Judge.pins`).\n */\nexport type Pinned = ReadonlyMap<string, unknown>\n\n/**\n * One row as a holder has it. Values are **encoded**, as a store keeps them\n * and as `evaluate` reads a row.\n */\nexport interface HeldRow {\n /** A field's value; unheld when the holder lacks it or may not see it. */\n readonly field: (key: string) => Held<unknown>\n /**\n * The row a `one` relation of this row points at: none for a null link, or\n * a row the reader may not see when the holder knows it holds every row it may.\n */\n readonly follow: (relation: OneRelation) => Held<Option.Option<HeldRow>>\n /**\n * The rows pointing at this one through `relation`, a `one` relation of\n * another Entity, for an exists whose filter fixes `pinned`.\n */\n readonly pointing: (relation: OneRelation, pinned: Pinned) => Pointing\n}\n\n/** One Entity's rows, as `Held.rows` takes them. */\nexport interface HeldTable {\n readonly entity: AnyEntity\n /**\n * Each row's values by key, encoded; a `one` relation's under its own key,\n * as the id of the row it points at or null. A key a row lacks is unheld.\n */\n readonly rows: ReadonlyArray<Readonly<Record<string, unknown>>>\n /**\n * Whether these are every row of the Entity the reader may see, so a row\n * not among them is known absent. True when not given.\n */\n readonly complete?: boolean | undefined\n /** Keys the reader may not see on any of these rows. */\n readonly hidden?: ReadonlyArray<string> | undefined\n}\n\n/** The rows `Held.rows` holds, by Entity. */\nexport interface HeldRows {\n /** The row of `entity` with this id, when it is held. */\n readonly row: (entity: AnyEntity, id: unknown) => Option.Option<HeldRow>\n /** Every held row of `entity`. */\n readonly rows: (entity: AnyEntity) => ReadonlyArray<HeldRow>\n /**\n * The row of `entity` with this id as the holder can say: none when it\n * knows there is no such row it may see, unheld when it cannot tell.\n */\n readonly find: (entity: AnyEntity, id: unknown) => Held<Option.Option<HeldRow>>\n}\n\nconst held = <A>(value: A): Held<A> => ({ _tag: 'Held', value })\nconst unheld = <A = never>(reason: string): Held<A> => ({ _tag: 'Unheld', reason })\n\n/**\n * Rows held as plain records: each table complete or not, with keys hidden.\n * What a test, a conformance check or a server that has the rows in hand\n * judges over.\n */\nconst rowsOf = (tables: ReadonlyArray<HeldTable>): HeldRows => {\n interface Table {\n readonly entity: AnyEntity\n readonly complete: boolean\n readonly hidden: ReadonlySet<string>\n readonly byId: ReadonlyMap<unknown, HeldRow>\n readonly views: ReadonlyArray<HeldRow>\n }\n const byToken = new Map<symbol, Table>()\n const tableOf = (identity: EntityIdentity<string>) =>\n Option.fromUndefinedOr(byToken.get(identity.token))\n const find = (target: AnyEntity, id: unknown): Held<Option.Option<HeldRow>> =>\n Option.match(tableOf(target.identity), {\n onNone: () => unheld(`no ${target.name} is held`),\n onSome: reached =>\n Option.match(Option.fromUndefinedOr(reached.byId.get(id)), {\n onSome: row => held(Option.some(row)),\n onNone: () =>\n reached.complete\n ? held(Option.none<HeldRow>())\n : unheld(`${target.name} ${String(id)} is not held`),\n }),\n })\n\n const view = (table: Table, record: Readonly<Record<string, unknown>>): HeldRow => {\n const read = (key: string): Held<unknown> =>\n table.hidden.has(key)\n ? unheld(`${table.entity.name}.${key} is hidden from this reader`)\n : Object.hasOwn(record, key)\n ? held(record[key])\n : unheld(`${table.entity.name}.${key} is not held`)\n return {\n field: read,\n follow: relation => {\n const link = read(relation.key)\n if (link._tag === 'Unheld') return link\n if (link.value === null || link.value === undefined) return held(Option.none())\n return find(relation.target(), link.value)\n },\n pointing: relation =>\n Option.match(tableOf(relation.owner), {\n onNone: () => ({\n rows: [],\n missing: Option.some(`no ${relation.owner.name} is held`),\n }),\n onSome: from => {\n const id = record.id\n const named = `${relation.owner.name}.${relation.key}`\n const rows: Array<HeldRow> = []\n let missing = from.complete\n ? Option.none<string>()\n : Option.some(`not every ${relation.owner.name} is held`)\n for (const each of from.views) {\n const link = each.field(relation.key)\n if (link._tag === 'Unheld') {\n missing = Option.orElse(missing, () => Option.some(link.reason))\n } else if (link.value === id) {\n rows.push(each)\n }\n }\n return { rows, missing: Option.map(missing, reason => `${named}: ${reason}`) }\n },\n }),\n }\n }\n\n for (const given of tables) {\n const views: Array<HeldRow> = []\n const byId = new Map<unknown, HeldRow>()\n const table: Table = {\n entity: given.entity,\n complete: given.complete ?? true,\n hidden: new Set(given.hidden ?? []),\n byId,\n views,\n }\n for (const record of given.rows) {\n const each = view(table, record)\n views.push(each)\n byId.set(record.id, each)\n }\n byToken.set(given.entity.identity.token, table)\n }\n\n return {\n row: (entity, id) =>\n Option.flatMap(tableOf(entity.identity), table => Option.fromUndefinedOr(table.byId.get(id))),\n rows: entity =>\n Option.match(tableOf(entity.identity), { onNone: () => [], onSome: table => table.views }),\n find,\n }\n}\n\nconst linksRead = new WeakMap<AnyQuery, ReadonlyArray<string>>()\n\n/**\n * The links a query reads on its own row: each relation of its Entity it\n * reads (a body reads only a `one` relation as a value). A relation it reads\n * existed when it was built, so what it reads is known once.\n */\nconst linksOf = (query: AnyQuery): ReadonlyArray<string> => {\n const known = linksRead.get(query)\n if (known !== undefined) return known\n const relations: Readonly<Record<string, EntityMember>> = query.entity.relations\n const links = Query.dependencies(query)\n .fields.filter(\n field =>\n field.owner.token === query.entity.identity.token && Object.hasOwn(relations, field.key),\n )\n .map(field => field.key)\n linksRead.set(query, links)\n return links\n}\n\n/**\n * A row as a Source answers it and a Remote store keeps it, each `one`\n * relation as its ref key (`'User:ada'`), given as an interpreter reads it:\n * each link `query` reads as the id it points at. The row itself when the\n * query reads no link.\n */\nconst fromRefs = (\n query: AnyQuery,\n row: Readonly<Record<string, unknown>>,\n): Readonly<Record<string, unknown>> => {\n const links = linksOf(query)\n if (links.length === 0) return row\n const read: Record<string, unknown> = { ...row }\n for (const key of links) {\n const ref = own(row, key)\n if (ref !== null && ref !== undefined)\n put(read, key, idOfRef(ref, `${query.entity.name}.${key}`))\n }\n return read\n}\n\n/**\n * Whether `key` is a `one` relation of the Entity `owner` names: what a\n * ref-keyed holder reads as the id it points at on a row it knows only by\n * identity, as a row pointing through `HeldRow.pointing`'s relation is.\n */\nconst isLink = (owner: EntityIdentity<string>, key: string): boolean => {\n const member = own(relationsOf(owner), key)\n return member?._tag === 'Relation' && member.cardinality === 'one'\n}\n\n/** The id a ref key (`'User:ada'`) names, refusing what is none, as `where` holds it. */\nexport const idOfRef = (ref: unknown, where: string): string => {\n const separator = typeof ref === 'string' ? ref.indexOf(':') : -1\n if (separator === -1) {\n throw new Error(\n `[foldkit-entity] ${where} holds ${JSON.stringify(ref)}, which is no ref key (\"Entity:id\")`,\n )\n }\n return (ref as string).slice(separator + 1)\n}\n\nexport const Held = {\n /** A value the holder has. */\n of: held,\n /** A value the holder does not have, and why. */\n unheld,\n match: <A, B>(\n value: Held<A>,\n cases: { readonly onHeld: (value: A) => B; readonly onUnheld: (reason: string) => B },\n ): B => (value._tag === 'Held' ? cases.onHeld(value.value) : cases.onUnheld(value.reason)),\n /** Rows held as plain records; see `HeldTable`. */\n rows: rowsOf,\n fromRefs,\n isLink,\n}\n"],"mappings":";;;;;;;;;;;;;;AAuFA,MAAM,QAAW,WAAuB;CAAE,MAAM;CAAQ;AAAM;AAC9D,MAAM,UAAqB,YAA6B;CAAE,MAAM;CAAU;AAAO;;;;;;AAOjF,MAAM,UAAU,WAA+C;CAQ7D,MAAM,0BAAU,IAAI,IAAmB;CACvC,MAAM,WAAW,aACf,OAAO,gBAAgB,QAAQ,IAAI,SAAS,KAAK,CAAC;CACpD,MAAM,QAAQ,QAAmB,OAC/B,OAAO,MAAM,QAAQ,OAAO,QAAQ,GAAG;EACrC,cAAc,OAAO,MAAM,OAAO,KAAK,SAAS;EAChD,SAAQ,YACN,OAAO,MAAM,OAAO,gBAAgB,QAAQ,KAAK,IAAI,EAAE,CAAC,GAAG;GACzD,SAAQ,QAAO,KAAK,OAAO,KAAK,GAAG,CAAC;GACpC,cACE,QAAQ,WACJ,KAAK,OAAO,KAAc,CAAC,IAC3B,OAAO,GAAG,OAAO,KAAK,GAAG,OAAO,EAAE,EAAE,aAAa;EACzD,CAAC;CACL,CAAC;CAEH,MAAM,QAAQ,OAAc,WAAuD;EACjF,MAAM,QAAQ,QACZ,MAAM,OAAO,IAAI,GAAG,IAChB,OAAO,GAAG,MAAM,OAAO,KAAK,GAAG,IAAI,4BAA4B,IAC/D,OAAO,OAAO,QAAQ,GAAG,IACvB,KAAK,OAAO,IAAI,IAChB,OAAO,GAAG,MAAM,OAAO,KAAK,GAAG,IAAI,aAAa;EACxD,OAAO;GACL,OAAO;GACP,SAAQ,aAAY;IAClB,MAAM,OAAO,KAAK,SAAS,GAAG;IAC9B,IAAI,KAAK,SAAS,UAAU,OAAO;IACnC,IAAI,KAAK,UAAU,QAAQ,KAAK,UAAU,KAAA,GAAW,OAAO,KAAK,OAAO,KAAK,CAAC;IAC9E,OAAO,KAAK,SAAS,OAAO,GAAG,KAAK,KAAK;GAC3C;GACA,WAAU,aACR,OAAO,MAAM,QAAQ,SAAS,KAAK,GAAG;IACpC,eAAe;KACb,MAAM,CAAC;KACP,SAAS,OAAO,KAAK,MAAM,SAAS,MAAM,KAAK,SAAS;IAC1D;IACA,SAAQ,SAAQ;KACd,MAAM,KAAK,OAAO;KAClB,MAAM,QAAQ,GAAG,SAAS,MAAM,KAAK,GAAG,SAAS;KACjD,MAAM,OAAuB,CAAC;KAC9B,IAAI,UAAU,KAAK,WACf,OAAO,KAAa,IACpB,OAAO,KAAK,aAAa,SAAS,MAAM,KAAK,SAAS;KAC1D,KAAK,MAAM,QAAQ,KAAK,OAAO;MAC7B,MAAM,OAAO,KAAK,MAAM,SAAS,GAAG;MACpC,IAAI,KAAK,SAAS,UAChB,UAAU,OAAO,OAAO,eAAe,OAAO,KAAK,KAAK,MAAM,CAAC;WAC1D,IAAI,KAAK,UAAU,IACxB,KAAK,KAAK,IAAI;KAElB;KACA,OAAO;MAAE;MAAM,SAAS,OAAO,IAAI,UAAS,WAAU,GAAG,MAAM,IAAI,QAAQ;KAAE;IAC/E;GACF,CAAC;EACL;CACF;CAEA,KAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,QAAwB,CAAC;EAC/B,MAAM,uBAAO,IAAI,IAAsB;EACvC,MAAM,QAAe;GACnB,QAAQ,MAAM;GACd,UAAU,MAAM,YAAY;GAC5B,QAAQ,IAAI,IAAI,MAAM,UAAU,CAAC,CAAC;GAClC;GACA;EACF;EACA,KAAK,MAAM,UAAU,MAAM,MAAM;GAC/B,MAAM,OAAO,KAAK,OAAO,MAAM;GAC/B,MAAM,KAAK,IAAI;GACf,KAAK,IAAI,OAAO,IAAI,IAAI;EAC1B;EACA,QAAQ,IAAI,MAAM,OAAO,SAAS,OAAO,KAAK;CAChD;CAEA,OAAO;EACL,MAAM,QAAQ,OACZ,OAAO,QAAQ,QAAQ,OAAO,QAAQ,IAAG,UAAS,OAAO,gBAAgB,MAAM,KAAK,IAAI,EAAE,CAAC,CAAC;EAC9F,OAAM,WACJ,OAAO,MAAM,QAAQ,OAAO,QAAQ,GAAG;GAAE,cAAc,CAAC;GAAG,SAAQ,UAAS,MAAM;EAAM,CAAC;EAC3F;CACF;AACF;AAEA,MAAM,4BAAY,IAAI,QAAyC;;;;;;AAO/D,MAAM,WAAW,UAA2C;CAC1D,MAAM,QAAQ,UAAU,IAAI,KAAK;CACjC,IAAI,UAAU,KAAA,GAAW,OAAO;CAChC,MAAM,YAAoD,MAAM,OAAO;CACvE,MAAM,QAAQ,MAAM,aAAa,KAAK,CAAC,CACpC,OAAO,QACN,UACE,MAAM,MAAM,UAAU,MAAM,OAAO,SAAS,SAAS,OAAO,OAAO,WAAW,MAAM,GAAG,CAC3F,CAAC,CACA,KAAI,UAAS,MAAM,GAAG;CACzB,UAAU,IAAI,OAAO,KAAK;CAC1B,OAAO;AACT;;;;;;;AAQA,MAAM,YACJ,OACA,QACsC;CACtC,MAAM,QAAQ,QAAQ,KAAK;CAC3B,IAAI,MAAM,WAAW,GAAG,OAAO;CAC/B,MAAM,OAAgC,EAAE,GAAG,IAAI;CAC/C,KAAK,MAAM,OAAO,OAAO;EACvB,MAAM,MAAM,IAAI,KAAK,GAAG;EACxB,IAAI,QAAQ,QAAQ,QAAQ,KAAA,GAC1B,IAAI,MAAM,KAAK,QAAQ,KAAK,GAAG,MAAM,OAAO,KAAK,GAAG,KAAK,CAAC;CAC9D;CACA,OAAO;AACT;;;;;;AAOA,MAAM,UAAU,OAA+B,QAAyB;CACtE,MAAM,SAAS,IAAI,YAAY,KAAK,GAAG,GAAG;CAC1C,OAAO,QAAQ,SAAS,cAAc,OAAO,gBAAgB;AAC/D;;AAGA,MAAa,WAAW,KAAc,UAA0B;CAC9D,MAAM,YAAY,OAAO,QAAQ,WAAW,IAAI,QAAQ,GAAG,IAAI;CAC/D,IAAI,cAAc,IAChB,MAAM,IAAI,MACR,oBAAoB,MAAM,SAAS,KAAK,UAAU,GAAG,EAAE,oCACzD;CAEF,OAAQ,IAAe,MAAM,YAAY,CAAC;AAC5C;AAEA,MAAa,OAAO;;CAElB,IAAI;;CAEJ;CACA,QACE,OACA,UACO,MAAM,SAAS,SAAS,MAAM,OAAO,MAAM,KAAK,IAAI,MAAM,SAAS,MAAM,MAAM;;CAExF,MAAM;CACN;CACA;AACF"}
|
|
1
|
+
{"version":3,"file":"held.js","names":[],"sources":["../src/held.ts"],"sourcesContent":["/**\n * What a holder of rows has: the world `Judge` reads an `Expr` over.\n *\n * A server's database holds every row, so whatever an expression asks has an\n * answer there. A client holds what it was sent: some rows, some fields of\n * them, and none it may not see. `HeldRow` is how a holder says which, so an\n * interpreter can tell \"this field is null\" from \"I do not have this field\",\n * which a plain record cannot: both read as a missing key.\n */\nimport { Option } from 'effect'\nimport { relationsOf } from './descriptor.js'\nimport { Query, type AnyQuery, type OneRelation } from './expr.js'\nimport type { AnyEntity, EntityIdentity, EntityMember } from './index.js'\nimport { own, put } from './record.js'\n\n/** A value a holder has, or why it does not have it. */\nexport type Held<A> =\n | { readonly _tag: 'Held'; readonly value: A }\n | { readonly _tag: 'Unheld'; readonly reason: string }\n\n/** The rows pointing at one row through a relation, as far as a holder has them. */\nexport interface Pointing {\n readonly rows: ReadonlyArray<HeldRow>\n /**\n * Why a row pointing here may be missing from `rows`; none when it holds\n * every one whose fields hold the values `pinned` names.\n */\n readonly missing: Option.Option<string>\n}\n\n/**\n * The values an exists' filter fixes on the rows it counts, by field key (a\n * link as the id it points at): a row with another value in one of them is\n * not counted, so a holder holding every pointing row with these values holds\n * every one that counts (`Judge.pins`).\n */\nexport type Pinned = ReadonlyMap<string, unknown>\n\n/**\n * One row as a holder has it. Values are **encoded**, as a store keeps them\n * and as `evaluate` reads a row.\n */\nexport interface HeldRow {\n /** A field's value; unheld when the holder lacks it or may not see it. */\n readonly field: (key: string) => Held<unknown>\n /**\n * The row a `one` relation of this row points at: none for a null link, or\n * a row the reader may not see when the holder knows it holds every row it may.\n */\n readonly follow: (relation: OneRelation) => Held<Option.Option<HeldRow>>\n /**\n * The rows pointing at this one through `relation`, a `one` relation of\n * another Entity, for an exists whose filter fixes `pinned`.\n */\n readonly pointing: (relation: OneRelation, pinned: Pinned) => Pointing\n}\n\n/** One Entity's rows, as `Held.rows` takes them. */\nexport interface HeldTable {\n readonly entity: AnyEntity\n /**\n * Each row's values by key, encoded; a `one` relation's under its own key,\n * as the id of the row it points at or null. A key a row lacks is unheld.\n */\n readonly rows: ReadonlyArray<Readonly<Record<string, unknown>>>\n /**\n * Whether these are every row of the Entity the reader may see, so a row\n * not among them is known absent. True when not given.\n */\n readonly complete?: boolean | undefined\n /** Keys the reader may not see on any of these rows. */\n readonly hidden?: ReadonlyArray<string> | undefined\n}\n\n/** The rows `Held.rows` holds, by Entity. */\nexport interface HeldRows {\n /** The row of `entity` with this id, when it is held. */\n readonly row: (entity: AnyEntity, id: unknown) => Option.Option<HeldRow>\n /** Every held row of `entity`. */\n readonly rows: (entity: AnyEntity) => ReadonlyArray<HeldRow>\n /**\n * The row of `entity` with this id as the holder can say: none when it\n * knows there is no such row it may see, unheld when it cannot tell.\n */\n readonly find: (entity: AnyEntity, id: unknown) => Held<Option.Option<HeldRow>>\n}\n\nconst held = <A>(value: A): Held<A> => ({ _tag: 'Held', value })\nconst unheld = <A = never>(reason: string): Held<A> => ({ _tag: 'Unheld', reason })\n\n/**\n * Rows held as plain records: each table complete or not, with keys hidden.\n * What a test, a conformance check or a server that has the rows in hand\n * judges over.\n */\nconst rowsOf = (tables: ReadonlyArray<HeldTable>): HeldRows => {\n interface Table {\n readonly entity: AnyEntity\n readonly complete: boolean\n readonly hidden: ReadonlySet<string>\n readonly byId: ReadonlyMap<unknown, HeldRow>\n readonly views: ReadonlyArray<HeldRow>\n }\n const byToken = new Map<symbol, Table>()\n const tableOf = (identity: EntityIdentity<string>) =>\n Option.fromUndefinedOr(byToken.get(identity.token))\n const find = (target: AnyEntity, id: unknown): Held<Option.Option<HeldRow>> =>\n Option.match(tableOf(target.identity), {\n onNone: () => unheld(`no ${target.name} is held`),\n onSome: reached =>\n Option.match(Option.fromUndefinedOr(reached.byId.get(id)), {\n onSome: row => held(Option.some(row)),\n onNone: () =>\n reached.complete\n ? held(Option.none<HeldRow>())\n : unheld(`${target.name} ${String(id)} is not held`),\n }),\n })\n\n const view = (table: Table, record: Readonly<Record<string, unknown>>): HeldRow => {\n const read = (key: string): Held<unknown> =>\n table.hidden.has(key)\n ? unheld(`${table.entity.name}.${key} is hidden from this reader`)\n : Object.hasOwn(record, key)\n ? held(record[key])\n : unheld(`${table.entity.name}.${key} is not held`)\n return {\n field: read,\n follow: relation => {\n const link = read(relation.key)\n if (link._tag === 'Unheld') return link\n if (link.value === null || link.value === undefined) return held(Option.none())\n return find(relation.target(), link.value)\n },\n pointing: relation =>\n Option.match(tableOf(relation.owner), {\n onNone: () => ({\n rows: [],\n missing: Option.some(`no ${relation.owner.name} is held`),\n }),\n onSome: from => {\n const id = record.id\n const named = `${relation.owner.name}.${relation.key}`\n const rows: Array<HeldRow> = []\n let missing = from.complete\n ? Option.none<string>()\n : Option.some(`not every ${relation.owner.name} is held`)\n for (const each of from.views) {\n const link = each.field(relation.key)\n if (link._tag === 'Unheld') {\n missing = Option.orElse(missing, () => Option.some(link.reason))\n continue\n }\n if (link.value === id) rows.push(each)\n }\n return { rows, missing: Option.map(missing, reason => `${named}: ${reason}`) }\n },\n }),\n }\n }\n\n for (const given of tables) {\n const views: Array<HeldRow> = []\n const byId = new Map<unknown, HeldRow>()\n const table: Table = {\n entity: given.entity,\n complete: given.complete ?? true,\n hidden: new Set(given.hidden ?? []),\n byId,\n views,\n }\n for (const record of given.rows) {\n const each = view(table, record)\n views.push(each)\n byId.set(record.id, each)\n }\n byToken.set(given.entity.identity.token, table)\n }\n\n return {\n row: (entity, id) =>\n Option.flatMap(tableOf(entity.identity), table => Option.fromUndefinedOr(table.byId.get(id))),\n rows: entity =>\n Option.match(tableOf(entity.identity), { onNone: () => [], onSome: table => table.views }),\n find,\n }\n}\n\nconst linksRead = new WeakMap<AnyQuery, ReadonlyArray<string>>()\n\n/**\n * The links a query reads on its own row: each relation of its Entity it\n * reads (a body reads only a `one` relation as a value). A relation it reads\n * existed when it was built, so what it reads is known once.\n */\nconst linksOf = (query: AnyQuery): ReadonlyArray<string> => {\n const known = linksRead.get(query)\n if (known !== undefined) return known\n const relations: Readonly<Record<string, EntityMember>> = query.entity.relations\n const links = Query.dependencies(query)\n .fields.filter(\n field =>\n field.owner.token === query.entity.identity.token && Object.hasOwn(relations, field.key),\n )\n .map(field => field.key)\n linksRead.set(query, links)\n return links\n}\n\n/**\n * A row as a Source answers it and a Remote store keeps it, each `one`\n * relation as its ref key (`'User:ada'`), given as an interpreter reads it:\n * each link `query` reads as the id it points at. The row itself when the\n * query reads no link.\n */\nconst fromRefs = (\n query: AnyQuery,\n row: Readonly<Record<string, unknown>>,\n): Readonly<Record<string, unknown>> => {\n const links = linksOf(query)\n if (links.length === 0) return row\n const read: Record<string, unknown> = { ...row }\n for (const key of links) {\n const ref = own(row, key)\n if (ref !== null && ref !== undefined)\n put(read, key, idOfRef(ref, `${query.entity.name}.${key}`))\n }\n return read\n}\n\n/**\n * Whether `key` is a `one` relation of the Entity `owner` names: what a\n * ref-keyed holder reads as the id it points at on a row it knows only by\n * identity, as a row pointing through `HeldRow.pointing`'s relation is.\n */\nconst isLink = (owner: EntityIdentity<string>, key: string): boolean => {\n const member = own(relationsOf(owner), key)\n return member?._tag === 'Relation' && member.cardinality === 'one'\n}\n\n/** The id a ref key (`'User:ada'`) names, refusing what is none, as `where` holds it. */\nexport const idOfRef = (ref: unknown, where: string): string => {\n const separator = typeof ref === 'string' ? ref.indexOf(':') : -1\n if (separator === -1) {\n throw new Error(\n `[foldkit-entity] ${where} holds ${JSON.stringify(ref)}, which is no ref key (\"Entity:id\")`,\n )\n }\n return (ref as string).slice(separator + 1)\n}\n\nexport const Held = {\n /** A value the holder has. */\n of: held,\n /** A value the holder does not have, and why. */\n unheld,\n match: <A, B>(\n value: Held<A>,\n cases: { readonly onHeld: (value: A) => B; readonly onUnheld: (reason: string) => B },\n ): B => {\n switch (value._tag) {\n case 'Held':\n return cases.onHeld(value.value)\n case 'Unheld':\n return cases.onUnheld(value.reason)\n }\n },\n /** Rows held as plain records; see `HeldTable`. */\n rows: rowsOf,\n fromRefs,\n isLink,\n}\n"],"mappings":"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"}
|
package/dist/index.d.ts
CHANGED
|
@@ -40,9 +40,12 @@ export type Cardinality = 'one' | 'many';
|
|
|
40
40
|
/**
|
|
41
41
|
* What happens to a row when the row its `one` relation points at is deleted
|
|
42
42
|
* (`Relation.one(Post, { onDelete: 'cascade' })`): `cascade`, it is deleted
|
|
43
|
-
* with it, by the server in the write that deletes, and foreseen by a client
|
|
43
|
+
* with it, by the server in the write that deletes, and foreseen by a client;
|
|
44
|
+
* `restrict`, the delete is refused while any row points there (#467), naming
|
|
45
|
+
* the relation and none of the rows; `setNull`, an optional link is cleared,
|
|
46
|
+
* an update of the row held to its own `Update` rules.
|
|
44
47
|
*/
|
|
45
|
-
export type OnDelete = 'cascade';
|
|
48
|
+
export type OnDelete = 'cascade' | 'restrict' | 'setNull';
|
|
46
49
|
/**
|
|
47
50
|
* Who may let a cascade take a row (#348). `child`, the default: the row's own
|
|
48
51
|
* `Delete` rule, judged for whoever deletes the row it points at, so a delete
|
|
@@ -77,7 +80,7 @@ export interface EntityRelation<Name extends string, Key extends string, Target
|
|
|
77
80
|
* deleted; none for a `many`, and for a `one` declared with nothing.
|
|
78
81
|
*/
|
|
79
82
|
readonly onDelete: Option.Option<OnDelete>;
|
|
80
|
-
/** Who may let a cascade through it take this row: some exactly where `onDelete` is
|
|
83
|
+
/** Who may let a cascade through it take this row: some exactly where `onDelete` is `cascade`. */
|
|
81
84
|
readonly authorizedBy: Option.Option<AuthorizedBy>;
|
|
82
85
|
readonly metadata: Metadata;
|
|
83
86
|
}
|
|
@@ -327,9 +330,18 @@ export type OneOptions<Optional extends boolean> = {
|
|
|
327
330
|
readonly authorizedBy?: undefined;
|
|
328
331
|
} | {
|
|
329
332
|
/** `cascade`: a row pointing here is deleted with the row it points at. */
|
|
330
|
-
readonly onDelete:
|
|
333
|
+
readonly onDelete: 'cascade';
|
|
331
334
|
/** Whose `Delete` rule lets the cascade take this row: its own (`child`), or the parent's. */
|
|
332
335
|
readonly authorizedBy?: AuthorizedBy;
|
|
336
|
+
} | {
|
|
337
|
+
/** `restrict`: the row it points at cannot be deleted while this row points there. */
|
|
338
|
+
readonly onDelete: 'restrict';
|
|
339
|
+
readonly authorizedBy?: undefined;
|
|
340
|
+
} | {
|
|
341
|
+
/** `setNull`: this row stays and points nowhere; only a link that may point nowhere can. */
|
|
342
|
+
readonly onDelete: 'setNull';
|
|
343
|
+
readonly optional: true;
|
|
344
|
+
readonly authorizedBy?: undefined;
|
|
333
345
|
});
|
|
334
346
|
declare function one<Target extends AnyEntity>(target: Target): RelationSpec<Target, 'one', false>;
|
|
335
347
|
declare function one<Target extends AnyEntity, const Optional extends boolean>(target: Target, options: OneOptions<Optional> & {
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","names":["ExprContext","EntityTypeId","EntitySet","AnyVariantUnion","NowExpr","ViewerExpr","ViewerPathExpr","SelectionTypeId","SelectionPageTypeId"],"sources":["../src/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;iBA2BiB,eAAe;WACrB,MAAM;;WAEN;;;iBAIM,YAAY,qBAAqB,oBAAoB,UAAU,OAAO;WAC5E;WACA,OAAO,eAAe;WACtB,KAAK;WACL,QAAQ;WACR,UAAU;;YAGT
|
|
1
|
+
{"version":3,"file":"index.d.ts","names":["ExprContext","EntityTypeId","EntitySet","AnyVariantUnion","NowExpr","ViewerExpr","ViewerPathExpr","SelectionTypeId","SelectionPageTypeId"],"sources":["../src/index.ts"],"mappings":"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"}
|
package/dist/index.js
CHANGED
|
@@ -27,15 +27,16 @@ const Derivation = Data.taggedEnum();
|
|
|
27
27
|
function one(target, options) {
|
|
28
28
|
const onDelete = options?.onDelete;
|
|
29
29
|
const authorizedBy = options?.authorizedBy;
|
|
30
|
-
if (onDelete !== void 0 && onDelete !== "cascade") throw new Error(`[foldkit-entity] Relation.one(${target.name}): onDelete is 'cascade'; ${String(onDelete)} is not one`);
|
|
30
|
+
if (onDelete !== void 0 && onDelete !== "cascade" && onDelete !== "restrict" && onDelete !== "setNull") throw new Error(`[foldkit-entity] Relation.one(${target.name}): onDelete is 'cascade', 'restrict' or 'setNull'; ${String(onDelete)} is not one`);
|
|
31
|
+
if (onDelete === "setNull" && options?.optional !== true) throw new Error(`[foldkit-entity] Relation.one(${target.name}): onDelete: 'setNull' clears the link, so it needs optional: true`);
|
|
31
32
|
if (authorizedBy !== void 0 && authorizedBy !== "child" && authorizedBy !== "parent") throw new Error(`[foldkit-entity] Relation.one(${target.name}): authorizedBy is 'child' or 'parent'; ${String(authorizedBy)} is not one`);
|
|
32
|
-
if (authorizedBy !== void 0 && onDelete
|
|
33
|
+
if (authorizedBy !== void 0 && onDelete !== "cascade") throw new Error(`[foldkit-entity] Relation.one(${target.name}): authorizedBy says who lets a cascade take the row, so it needs onDelete: 'cascade'`);
|
|
33
34
|
return {
|
|
34
35
|
target,
|
|
35
36
|
cardinality: "one",
|
|
36
37
|
optional: options?.optional ?? false,
|
|
37
38
|
onDelete: Option.fromUndefinedOr(onDelete),
|
|
38
|
-
authorizedBy: onDelete ===
|
|
39
|
+
authorizedBy: onDelete === "cascade" ? Option.some(authorizedBy ?? "child") : Option.none()
|
|
39
40
|
};
|
|
40
41
|
}
|
|
41
42
|
/** What the owner sees: one or many of `target`. Used inside `Entity.relate`. */
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `foldkit-entity` — domain structure as typed values.\n *\n * An Entity names its intrinsic Fields (one `Schema.Struct`), its Relations\n * (navigation edges to other Entities, declared with `Entity.relate`), and its Derived members (readable\n * values an interpreter supplies). It describes; it fetches, stores, and\n * renders nothing. Remote, Drizzle, and form packages interpret it and attach\n * what they need as `foldkit-metadata`.\n */\nimport { Data, Option, type Pipeable, Schema } from 'effect'\nimport type { Metadata } from 'foldkit-metadata'\nimport type { ExprContext, NowExpr, ViewerExpr, ViewerPathExpr } from './context.js'\nimport type { HeldRow, HeldRows } from './held.js'\nimport { EntityTypeId, SelectionPageTypeId, SelectionTypeId } from './ids.js'\nimport type { EntitySet } from './sets.js'\n// The members of `Entity`, a namespace rather than an object so a page keeps only\n// those it calls (#378). Exported under the interface's name; `export * as`\n// would make each `Entity` type here a reference the declaration emitter refuses.\nimport * as EntityMembers from './entity.js'\nimport type { AnyVariantUnion } from './variants.js'\n\nexport { EntityTypeId, SelectionPageTypeId, SelectionTypeId } from './ids.js'\n\n/**\n * What makes two descriptors the same Entity. A pipe step returns a new\n * descriptor with the same identity, so compare `identity`, never the objects.\n */\nexport interface EntityIdentity<Name extends string> {\n readonly name: Name\n /** Distinguishes two Entities that were defined with the same name. */\n readonly token: symbol\n}\n\n/** An intrinsic value of the Entity: one property of `entity.schema`. */\nexport interface EntityField<Name extends string, Key extends string, S extends Schema.Constraint> {\n readonly _tag: 'Field'\n readonly owner: EntityIdentity<Name>\n readonly key: Key\n readonly schema: S\n readonly metadata: Metadata\n}\n\nexport type Cardinality = 'one' | 'many'\n\n/**\n * What happens to a row when the row its `one` relation points at is deleted\n * (`Relation.one(Post, { onDelete: 'cascade' })`): `cascade`, it is deleted\n * with it, by the server in the write that deletes, and foreseen by a client.\n */\nexport type OnDelete = 'cascade'\n\n/**\n * Who may let a cascade take a row (#348). `child`, the default: the row's own\n * `Delete` rule, judged for whoever deletes the row it points at, so a delete\n * that would take a row they may not delete is refused whole. `parent`: whoever\n * may delete the row it points at may take it too (a post's author removing\n * the likes under it), declared on the relation so it is never a default.\n */\nexport type AuthorizedBy = 'child' | 'parent'\n\n/** What `Relation.one` / `Relation.many` return, before `Entity.relate` binds it to an owner. */\nexport interface RelationSpec<\n Target extends AnyEntity,\n C extends Cardinality,\n Optional extends boolean,\n> {\n readonly target: Target\n readonly cardinality: C\n readonly optional: Optional\n readonly onDelete: Option.Option<OnDelete>\n readonly authorizedBy: Option.Option<AuthorizedBy>\n}\n\n/**\n * A navigation edge as its owner sees it: one or many of `target`. How the edge\n * is stored (a foreign key, a join table, a nested document) is the\n * interpreter's concern.\n */\nexport interface EntityRelation<\n Name extends string,\n Key extends string,\n Target extends AnyEntity,\n C extends Cardinality,\n Optional extends boolean,\n> {\n readonly _tag: 'Relation'\n readonly owner: EntityIdentity<Name>\n readonly key: Key\n /** The target as `Entity.relate` returned it, so its own relations can be followed. */\n readonly target: () => Target\n readonly cardinality: C\n readonly optional: Optional\n /**\n * What happens to this row when the row a `one` relation points at is\n * deleted; none for a `many`, and for a `one` declared with nothing.\n */\n readonly onDelete: Option.Option<OnDelete>\n /** Who may let a cascade through it take this row: some exactly where `onDelete` is. */\n readonly authorizedBy: Option.Option<AuthorizedBy>\n readonly metadata: Metadata\n}\n\ntype OneRelation = EntityRelation<string, string, AnyEntity, 'one', boolean>\n\n/**\n * What a derived member is. `Supplied` (`Derived.make`): an interpreter\n * supplies it, and nothing else can say what it is. `Count`\n * (`Derived.count`): how many rows point at this one through `relation`, a\n * `one` relation of the counted Entity. `Exists` (`Derived.exists`): the id of\n * a row pointing here through `relation` whose `viewer` relation points at\n * whoever reads it, or none. A client predicts both from the rows it writes,\n * and a server compiles both from the relations' storage.\n */\nexport type Derivation = Data.TaggedEnum<{\n /**\n * `predict`: how a client foresees it for a row it writes; none, it waits\n * for the server. `forbids`: which write to the row its value refuses, so a\n * client holding it refuses that write where it is made.\n */\n Supplied: { readonly predict: Option.Option<Predict>; readonly forbids: Option.Option<Forbids> }\n Count: { readonly relation: OneRelation }\n Exists: { readonly relation: OneRelation; readonly viewer: OneRelation }\n}>\nexport const Derivation = Data.taggedEnum<Derivation>()\n\n/** What a supplied member's prediction is given: the row a write leaves, as its holder has it. */\nexport interface Predicting {\n /** The Entity written, as the write declared it. */\n readonly entity: AnyEntity\n readonly row: HeldRow\n /** The holder's other rows, where a rule's path reads. */\n readonly rows: HeldRows\n /** The operation's context: who asks, and the write's time. */\n readonly context: ExprContext\n}\n\n/**\n * A supplied member foreseen: its value **encoded**, as the store holds it, or\n * none where the holder cannot know it, so nothing is shown before the answer.\n */\nexport type Predict = (predicting: Predicting) => Option.Option<unknown>\n\n/**\n * What a write does to a row it finds, as a supplied member's `forbids` is\n * asked: an update's members and the relations it points, or a delete.\n */\nexport interface WriteSurface {\n readonly kind: 'Update' | 'Delete'\n /** The members it sets, moves or computes, relations not among them. */\n readonly members: ReadonlyArray<string>\n /** Each relation it points: at a row (`Link`), or at none (`Unlink`). */\n readonly relations: ReadonlyArray<{\n readonly relation: string\n readonly interaction: 'Link' | 'Unlink'\n }>\n}\n\n/**\n * Whether a supplied member's value, **encoded** as the store holds it,\n * refuses `surface`, with the reader's words for why when there are any; none\n * where it does not say so for certain. Only a definite refusal: a client\n * refuses the write unseen, and its server would refuse it too.\n */\nexport type Forbids = (\n value: unknown,\n surface: WriteSurface,\n) => Option.Option<{ readonly reason: Option.Option<string> }>\n\n/** What `Derived.make`, `Derived.count` or `Derived.exists` returns, before an Entity owns it. */\nexport interface DerivedSpec<S extends Schema.Constraint, D extends Derivation = Derivation> {\n readonly schema: S\n readonly derives: D\n}\n\n/** A value consumers may read that is not part of `entity.schema`, and what it derives. */\nexport interface EntityDerived<\n Name extends string,\n Key extends string,\n S extends Schema.Constraint,\n D extends Derivation = Derivation,\n> {\n readonly _tag: 'Derived'\n readonly owner: EntityIdentity<Name>\n readonly key: Key\n readonly schema: S\n readonly derives: D\n readonly metadata: Metadata\n}\n\nexport type EntityMember =\n | EntityField<string, string, Schema.Constraint>\n | EntityRelation<string, string, AnyEntity, Cardinality, boolean>\n | EntityDerived<string, string, Schema.Constraint>\n\nexport type RelationSpecs = Readonly<Record<string, RelationSpec<AnyEntity, Cardinality, boolean>>>\nexport type DerivedSpecs = Readonly<Record<string, DerivedSpec<Schema.Constraint>>>\n\ntype FieldsOf<Name extends string, Fields extends Schema.Struct.Fields> = {\n readonly [K in keyof Fields & string]: EntityField<Name, K, Fields[K]>\n}\ntype RelationsOf<Name extends string, Relations extends RelationSpecs> = {\n readonly [K in keyof Relations & string]: Relations[K] extends RelationSpec<\n infer Target,\n infer C,\n infer Optional\n >\n ? EntityRelation<Name, K, Target, C, Optional>\n : never\n}\ntype DerivedOf<Name extends string, Derived extends DerivedSpecs> = {\n readonly [K in keyof Derived & string]: EntityDerived<\n Name,\n K,\n Derived[K]['schema'],\n Derived[K]['derives']\n >\n}\n\nexport interface Entity<\n Name extends string,\n Fields extends Schema.Struct.Fields,\n Relations extends RelationSpecs = {},\n Derived extends DerivedSpecs = {},\n>\n extends Pipeable.Pipeable {\n readonly [EntityTypeId]: EntityTypeId\n readonly identity: EntityIdentity<Name>\n readonly name: Name\n /** The intrinsic value only: no relations, no derived members. */\n readonly schema: Schema.Struct<Fields>\n readonly fields: FieldsOf<Name, Fields>\n readonly relations: RelationsOf<Name, Relations>\n readonly derived: DerivedOf<Name, Derived>\n /** Every readable member under one namespace; keys never collide. */\n readonly members: FieldsOf<Name, Fields> & RelationsOf<Name, Relations> & DerivedOf<Name, Derived>\n /** The members whose value is the write's context, never its input (`Entity.sets`), by key. */\n readonly sets: Readonly<Record<string, EntitySet>>\n readonly metadata: Metadata\n}\n\nexport type AnyEntity = Entity<string, any, any, any>\n\n/**\n * An Entity whose rows are one of several shapes (`Entity.defineVariants`).\n * `variants` is Effect's tagged union of them, read with its own `match`;\n * `fields` and `schema` are the stored row, which every case shares.\n */\nexport interface VariantEntity<\n Name extends string,\n Fields extends Schema.Struct.Fields,\n Relations extends RelationSpecs = {},\n Derived extends DerivedSpecs = {},\n Union extends AnyVariantUnion = AnyVariantUnion,\n> extends Entity<Name, Fields, Relations, Derived> {\n readonly variants: Union\n}\n\nexport type AnyVariantEntity = VariantEntity<string, any, any, any, any>\n\n/** The keys of an Entity's `one` relations. */\ntype OneRelationKeys<E extends AnyEntity> = {\n [K in keyof E['relations'] & string]: E['relations'][K]['cardinality'] extends 'one' ? K : never\n}[keyof E['relations'] & string]\n\n/**\n * What a field holding `T` may be set to: the time where it holds a number,\n * the viewer's id where text, and what a path from the viewer reads where it\n * holds that.\n */\ntype ContextValueFor<T> =\n | (number extends T ? NowExpr<number> : never)\n | (T extends string ? ViewerExpr<T> : never)\n | ViewerPathExpr<T | null>\n\n/** The name of the Entity the `one` relation `K` points at. */\ntype TargetName<E extends AnyEntity, K extends keyof E['relations']> = ReturnType<\n E['relations'][K]['target']\n>['name']\n\n/**\n * What `Entity.sets` takes, by member: a field the value of the write's\n * context it can hold, a `one` relation `Expr.viewer` of its target.\n */\nexport type EntitySets<E extends AnyEntity> = {\n readonly [K in Exclude<keyof E['fields'] & string, 'id'>]?: ContextValueFor<\n Schema.Schema.Type<E['fields'][K]['schema']>\n >\n} & {\n readonly [K in OneRelationKeys<E>]?: ViewerExpr<unknown, TargetName<E, K>>\n}\n\nexport type Entities = Readonly<Record<string, AnyEntity>>\nexport type RelationMap<Es extends Entities> = { readonly [K in keyof Es]?: RelationSpecs }\n\n/** The key in `Es` of the Entity a spec targets, matched by name. */\nexport type TargetKey<Es extends Entities, Target extends AnyEntity> = {\n [K in keyof Es]: [Es[K]['name'], Target['name']] extends [Target['name'], Es[K]['name']]\n ? K\n : never\n}[keyof Es]\n\nexport type RelatedSpecs<Es extends Entities, Rs extends RelationMap<Es>, K extends keyof Es> = {\n readonly [R in keyof Rs[K]]: Rs[K][R] extends RelationSpec<infer Target, infer C, infer Optional>\n ? RelationSpec<Related<Es, Rs, TargetKey<Es, Target>>, C, Optional>\n : never\n}\n\n/**\n * One Entity of an `Entity.relate` result. A relation's target is again a\n * `Related`, so relations can be followed through a cycle; the recursion goes\n * through type arguments, which TypeScript resolves only when asked.\n */\nexport type Related<Es extends Entities, Rs extends RelationMap<Es>, K extends keyof Es> =\n Es[K] extends VariantEntity<infer Name, infer Fields, infer R, infer D, infer U>\n ? VariantEntity<Name, Fields, R & RelatedSpecs<Es, Rs, K>, D, U>\n : Es[K] extends Entity<infer Name, infer Fields, infer R, infer D>\n ? Entity<Name, Fields, R & RelatedSpecs<Es, Rs, K>, D>\n : never\n\n/**\n * The schema that identifies one of an Entity: its `id` field when that is text\n * (a plain string, a brand, a pattern), and plain text otherwise. An id is text\n * because a ref travels and is stored as text; an Entity keyed by a number still\n * has refs, and their ids are the number as text.\n */\nexport type IdSchemaOf<E> = E extends {\n readonly fields: { readonly id: { readonly schema: infer S } }\n}\n ? S extends Schema.Constraint\n ? [S['Type']] extends [string]\n ? S\n : Schema.String\n : Schema.String\n : Schema.String\n\n/** What identifies one of an Entity: `IdOf<typeof Blog.Post>` is `PostId` when its `id` field is one. */\nexport type IdOf<E> = IdSchemaOf<E>['Type']\n\n/**\n * What a relation selected with `true` yields: which Entity, and which one. `Id`\n * is the target's own id type, so a ref to an Author cannot be used as a Post's.\n */\nexport interface EntityRef<Name extends string = string, Id extends string = string> {\n readonly entity: Name\n readonly id: Id\n}\n\n/**\n * A view of the Entity graph: which members to read, and the schema of the\n * value that results. It says nothing about where the value comes from.\n */\nexport interface Selection<\n Name extends string,\n Members,\n S extends Schema.Constraint,\n Id extends string = string,\n> {\n readonly [SelectionTypeId]: SelectionTypeId\n /** Type-only: the id type of the Entity selected, so a reader can ask for the right one. Never set. */\n readonly Id?: Id\n readonly entity: Entity<Name, any, any, any>\n /** What was selected, by member key: `true`, or a relation's nested Selection. */\n readonly members: Members\n readonly schema: S\n}\n\n/** The value a Selection reads: `Selected<typeof PostCard>` is one card's fields. */\nexport type Selected<S extends Selection<string, unknown, Schema.Constraint>> = S['schema']['Type']\n\n/**\n * Which part of a `many` relation to read: the first or last so many, from a\n * cursor or from the end. A cursor is whatever the interpreter handed out with an\n * earlier page; nothing here looks inside it.\n */\nexport interface PageWindow {\n readonly first?: number | undefined\n readonly last?: number | undefined\n readonly after?: string | undefined\n readonly before?: string | undefined\n}\n\n/** A Selection of a `many` relation's target, read a page at a time. */\nexport interface SelectionPage<Name extends string, S extends Schema.Constraint> {\n readonly [SelectionPageTypeId]: SelectionPageTypeId\n readonly selection: Selection<Name, any, S>\n readonly window: PageWindow\n}\n\n/** An input key that carries a relation's target: the id of a `one`, the ids of a `many`. */\nexport interface RelationInput<R extends EntityRelation<any, any, any, any, any>> {\n readonly _tag: 'RelationInput'\n readonly relation: R\n}\n\n/**\n * An input key that carries the relation's target itself, written through an\n * input of its own: a post created with a new author, an order with its lines.\n * A `one` holds that input's value, a `many` a list of them.\n */\nexport interface NestedInput<\n R extends EntityRelation<any, any, any, any, any>,\n I extends EntityInput<any, any, any>,\n> {\n readonly _tag: 'NestedInput'\n readonly relation: R\n readonly input: I\n}\n\n/** An input key that is about the operation, not the Entity: a reason, a flag, a confirmation. */\nexport interface Unmapped {\n readonly _tag: 'Unmapped'\n}\n\n/** What one key of an operation's input means in terms of the Entity. */\nexport type InputMember =\n | EntityField<string, string, Schema.Constraint>\n | RelationInput<EntityRelation<string, string, AnyEntity, Cardinality, boolean>>\n | NestedInput<\n EntityRelation<string, string, AnyEntity, Cardinality, boolean>,\n EntityInput<AnyEntity, any, any>\n >\n | Unmapped\n\n/**\n * An operation's input read against an Entity: which member each input key\n * writes. The operation decides what may be submitted; the Entity only says\n * what each submitted key means.\n */\nexport interface EntityInput<E extends AnyEntity, Fields extends Schema.Struct.Fields, Members> {\n readonly entity: E\n readonly schema: Schema.Struct<Fields>\n readonly members: Members\n}\n\nexport type { InputMembers, WrittenAs, WrittenKey, WrittenSpec } from './entity.js'\nexport { EntityMembers as Entity }\n\n/**\n * How a `one` relation is declared: whether it may point nowhere, and what a\n * delete of its target does. `authorizedBy` is said only beside `onDelete`.\n */\nexport type OneOptions<Optional extends boolean> = {\n readonly optional?: Optional\n} & (\n | { readonly onDelete?: undefined; readonly authorizedBy?: undefined }\n | {\n /** `cascade`: a row pointing here is deleted with the row it points at. */\n readonly onDelete: OnDelete\n /** Whose `Delete` rule lets the cascade take this row: its own (`child`), or the parent's. */\n readonly authorizedBy?: AuthorizedBy\n }\n)\n\nfunction one<Target extends AnyEntity>(target: Target): RelationSpec<Target, 'one', false>\nfunction one<Target extends AnyEntity, const Optional extends boolean>(\n target: Target,\n options: OneOptions<Optional> & { readonly optional: Optional },\n): RelationSpec<Target, 'one', Optional>\nfunction one<Target extends AnyEntity>(\n target: Target,\n options: OneOptions<false>,\n): RelationSpec<Target, 'one', false>\nfunction one(\n target: AnyEntity,\n options?: OneOptions<boolean>,\n): RelationSpec<AnyEntity, 'one', boolean> {\n const onDelete = options?.onDelete\n const authorizedBy = options?.authorizedBy\n if (onDelete !== undefined && onDelete !== 'cascade')\n throw new Error(\n `[foldkit-entity] Relation.one(${target.name}): onDelete is 'cascade'; ${String(onDelete)} is not one`,\n )\n if (authorizedBy !== undefined && authorizedBy !== 'child' && authorizedBy !== 'parent')\n throw new Error(\n `[foldkit-entity] Relation.one(${target.name}): authorizedBy is 'child' or 'parent'; ${String(authorizedBy)} is not one`,\n )\n if (authorizedBy !== undefined && onDelete === undefined)\n throw new Error(\n `[foldkit-entity] Relation.one(${target.name}): authorizedBy says who lets a cascade take the row, so it needs onDelete`,\n )\n return {\n target,\n cardinality: 'one',\n optional: options?.optional ?? false,\n onDelete: Option.fromUndefinedOr(onDelete),\n authorizedBy: onDelete === undefined ? Option.none() : Option.some(authorizedBy ?? 'child'),\n }\n}\n\n/** What the owner sees: one or many of `target`. Used inside `Entity.relate`. */\nexport const Relation = {\n one,\n\n /** For `Entity.input`: the input key holds this relation's target id, or ids for a `many`. */\n input: <R extends EntityRelation<any, any, any, any, any>>(relation: R): RelationInput<R> =>\n Object.freeze({ _tag: 'RelationInput', relation }),\n\n /**\n * For `Entity.input`: the input key holds the relation's target itself, written\n * through `input`, an `Entity.input` of the target. A `many` holds a list.\n */\n nested: <R extends EntityRelation<any, any, any, any, any>, I extends EntityInput<any, any, any>>(\n relation: R,\n input: I,\n ): NestedInput<R, I> => Object.freeze({ _tag: 'NestedInput', relation, input }),\n\n many: <Target extends AnyEntity>(target: Target): RelationSpec<Target, 'many', false> => ({\n target,\n cardinality: 'many',\n optional: false,\n onDelete: Option.none(),\n authorizedBy: Option.none(),\n }),\n}\n\n/** A count: never negative, never a fraction. */\nconst CountSchema = Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0))\n\n/** The id of the row an exists found, as every Remote id is held: text, or none. */\nconst WitnessSchema = Schema.OptionFromNullOr(Schema.String)\n\ntype OwnerName<R> = R extends EntityRelation<infer Name, any, any, any, any> ? Name : never\n\nexport const Derived = {\n /**\n * A member only an interpreter can compute, of type `schema`: it supplies the\n * value. `predict` says how a client foresees it for a row it writes (Guard's\n * `may`); without it the row reads as missing the member until the answer.\n * `forbids` says which write to the row its value refuses (Guard's `may`\n * again), so a client holding it refuses that write where it is made.\n */\n make: <S extends Schema.Constraint>(\n schema: S,\n options: {\n readonly predict?: Predict | undefined\n readonly forbids?: Forbids | undefined\n } = {},\n ): DerivedSpec<S, Extract<Derivation, { readonly _tag: 'Supplied' }>> => ({\n schema,\n derives: Derivation.Supplied({\n predict: Option.fromUndefinedOr(options.predict),\n forbids: Option.fromUndefinedOr(options.forbids),\n }),\n }),\n\n /**\n * How many rows point at this one through `relation`, a `one` relation of\n * the counted Entity: `likeCount: Derived.count(Like.relations.post)` on\n * Post. Added after `Entity.relate`, which makes the relation. A server\n * compiles it from the relation's storage, and a client predicts it from\n * the rows a pending write inserts, deletes or points elsewhere.\n */\n count: <R extends EntityRelation<string, string, AnyEntity, 'one', boolean>>(\n relation: R,\n ): DerivedSpec<typeof CountSchema, { readonly _tag: 'Count'; readonly relation: R }> => ({\n schema: CountSchema,\n derives: Derivation.Count({ relation }) as { readonly _tag: 'Count'; readonly relation: R },\n }),\n\n /**\n * Whether a row points at this one through `relation` and at whoever reads\n * it through `viewer`, another `one` relation of the same pointing Entity:\n * `liked: Derived.exists(Like.relations.post, { viewer: Like.relations.user })`\n * on Post. Its value is that row's id as the store holds it, or none, so the\n * reader can take it back (`Write.delete` by that id). It depends on who\n * reads it: a server answers it for the principal it reads as, and a client\n * predicts it for the viewer it is told of.\n */\n exists: <\n R extends OneRelation,\n V extends EntityRelation<OwnerName<R>, string, AnyEntity, 'one', boolean>,\n >(\n relation: R,\n options: { readonly viewer: V },\n ): DerivedSpec<\n typeof WitnessSchema,\n { readonly _tag: 'Exists'; readonly relation: R; readonly viewer: V }\n > => ({\n schema: WitnessSchema,\n derives: Derivation.Exists({ relation, viewer: options.viewer }) as {\n readonly _tag: 'Exists'\n readonly relation: R\n readonly viewer: V\n },\n }),\n}\n\nexport * from './expr.js'\nexport {\n contextValue,\n viewerIdOf,\n type ExprContext,\n type NowExpr,\n type ViewerExpr,\n type ViewerPathExpr,\n} from './context.js'\nexport * from './collation.js'\nexport * from './operators.js'\nexport * from './law.js'\nexport * from './text.js'\nexport * from './readFilter.js'\nexport * from './words.js'\nexport * from './shape.js'\nexport type {\n AnyVariantUnion,\n CheckCases,\n EntityVariants,\n StoredFields,\n VariantCases,\n VariantUnion,\n} from './variants.js'\n// The reference semantics of the IR above. The conformance suite that proves\n// an interpreter agrees with it is `foldkit-entity/conformance`, kept out of\n// this entry because it is fixture data every form and admin screen would\n// otherwise carry.\nexport * from './evaluate.js'\nexport * from './held.js'\nexport type {\n AfterRow,\n BeforeRow,\n Change,\n DeclaredInvariant,\n Invariant,\n Judgement,\n} from './invariant.js'\nexport type { ContextValue, EntitySet, SetOn } from './sets.js'\nexport {\n Write,\n type AnyWrite,\n type BoundWrite,\n type ConditionedWrite,\n Computation,\n type WriteAssignment,\n type WriteComputations,\n type WriteCondition,\n type WriteIncrement,\n type WriteKind,\n type WriteLink,\n type WriteSet,\n type ContextSet,\n type ContextRead,\n type ContextValues,\n} from './write.js'\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AA2HA,MAAa,aAAa,KAAK,WAAuB;AAmVtD,SAAS,IACP,QACA,SACyC;CACzC,MAAM,WAAW,SAAS;CAC1B,MAAM,eAAe,SAAS;CAC9B,IAAI,aAAa,KAAA,KAAa,aAAa,WACzC,MAAM,IAAI,MACR,iCAAiC,OAAO,KAAK,4BAA4B,OAAO,QAAQ,EAAE,YAC5F;CACF,IAAI,iBAAiB,KAAA,KAAa,iBAAiB,WAAW,iBAAiB,UAC7E,MAAM,IAAI,MACR,iCAAiC,OAAO,KAAK,0CAA0C,OAAO,YAAY,EAAE,YAC9G;CACF,IAAI,iBAAiB,KAAA,KAAa,aAAa,KAAA,GAC7C,MAAM,IAAI,MACR,iCAAiC,OAAO,KAAK,2EAC/C;CACF,OAAO;EACL;EACA,aAAa;EACb,UAAU,SAAS,YAAY;EAC/B,UAAU,OAAO,gBAAgB,QAAQ;EACzC,cAAc,aAAa,KAAA,IAAY,OAAO,KAAK,IAAI,OAAO,KAAK,gBAAgB,OAAO;CAC5F;AACF;;AAGA,MAAa,WAAW;CACtB;;CAGA,QAA2D,aACzD,OAAO,OAAO;EAAE,MAAM;EAAiB;CAAS,CAAC;;;;;CAMnD,SACE,UACA,UACsB,OAAO,OAAO;EAAE,MAAM;EAAe;EAAU;CAAM,CAAC;CAE9E,OAAiC,YAAyD;EACxF;EACA,aAAa;EACb,UAAU;EACV,UAAU,OAAO,KAAK;EACtB,cAAc,OAAO,KAAK;CAC5B;AACF;;AAGA,MAAM,cAAc,OAAO,OAAO,MAAM,OAAO,MAAM,GAAG,OAAO,uBAAuB,CAAC,CAAC;;AAGxF,MAAM,gBAAgB,OAAO,iBAAiB,OAAO,MAAM;AAI3D,MAAa,UAAU;;;;;;;;CAQrB,OACE,QACA,UAGI,CAAC,OACmE;EACxE;EACA,SAAS,WAAW,SAAS;GAC3B,SAAS,OAAO,gBAAgB,QAAQ,OAAO;GAC/C,SAAS,OAAO,gBAAgB,QAAQ,OAAO;EACjD,CAAC;CACH;;;;;;;;CASA,QACE,cACuF;EACvF,QAAQ;EACR,SAAS,WAAW,MAAM,EAAE,SAAS,CAAC;CACxC;;;;;;;;;;CAWA,SAIE,UACA,aAII;EACJ,QAAQ;EACR,SAAS,WAAW,OAAO;GAAE;GAAU,QAAQ,QAAQ;EAAO,CAAC;CAKjE;AACF"}
|
|
1
|
+
{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `foldkit-entity` — domain structure as typed values.\n *\n * An Entity names its intrinsic Fields (one `Schema.Struct`), its Relations\n * (navigation edges to other Entities, declared with `Entity.relate`), and its Derived members (readable\n * values an interpreter supplies). It describes; it fetches, stores, and\n * renders nothing. Remote, Drizzle, and form packages interpret it and attach\n * what they need as `foldkit-metadata`.\n */\nimport { Data, Option, type Pipeable, Schema } from 'effect'\nimport type { Metadata } from 'foldkit-metadata'\nimport type { ExprContext, NowExpr, ViewerExpr, ViewerPathExpr } from './context.js'\nimport type { HeldRow, HeldRows } from './held.js'\nimport { EntityTypeId, SelectionPageTypeId, SelectionTypeId } from './ids.js'\nimport type { EntitySet } from './sets.js'\n// The members of `Entity`, a namespace rather than an object so a page keeps only\n// those it calls (#378). Exported under the interface's name; `export * as`\n// would make each `Entity` type here a reference the declaration emitter refuses.\nimport * as EntityMembers from './entity.js'\nimport type { AnyVariantUnion } from './variants.js'\n\nexport { EntityTypeId, SelectionPageTypeId, SelectionTypeId } from './ids.js'\n\n/**\n * What makes two descriptors the same Entity. A pipe step returns a new\n * descriptor with the same identity, so compare `identity`, never the objects.\n */\nexport interface EntityIdentity<Name extends string> {\n readonly name: Name\n /** Distinguishes two Entities that were defined with the same name. */\n readonly token: symbol\n}\n\n/** An intrinsic value of the Entity: one property of `entity.schema`. */\nexport interface EntityField<Name extends string, Key extends string, S extends Schema.Constraint> {\n readonly _tag: 'Field'\n readonly owner: EntityIdentity<Name>\n readonly key: Key\n readonly schema: S\n readonly metadata: Metadata\n}\n\nexport type Cardinality = 'one' | 'many'\n\n/**\n * What happens to a row when the row its `one` relation points at is deleted\n * (`Relation.one(Post, { onDelete: 'cascade' })`): `cascade`, it is deleted\n * with it, by the server in the write that deletes, and foreseen by a client;\n * `restrict`, the delete is refused while any row points there (#467), naming\n * the relation and none of the rows; `setNull`, an optional link is cleared,\n * an update of the row held to its own `Update` rules.\n */\nexport type OnDelete = 'cascade' | 'restrict' | 'setNull'\n\n/**\n * Who may let a cascade take a row (#348). `child`, the default: the row's own\n * `Delete` rule, judged for whoever deletes the row it points at, so a delete\n * that would take a row they may not delete is refused whole. `parent`: whoever\n * may delete the row it points at may take it too (a post's author removing\n * the likes under it), declared on the relation so it is never a default.\n */\nexport type AuthorizedBy = 'child' | 'parent'\n\n/** What `Relation.one` / `Relation.many` return, before `Entity.relate` binds it to an owner. */\nexport interface RelationSpec<\n Target extends AnyEntity,\n C extends Cardinality,\n Optional extends boolean,\n> {\n readonly target: Target\n readonly cardinality: C\n readonly optional: Optional\n readonly onDelete: Option.Option<OnDelete>\n readonly authorizedBy: Option.Option<AuthorizedBy>\n}\n\n/**\n * A navigation edge as its owner sees it: one or many of `target`. How the edge\n * is stored (a foreign key, a join table, a nested document) is the\n * interpreter's concern.\n */\nexport interface EntityRelation<\n Name extends string,\n Key extends string,\n Target extends AnyEntity,\n C extends Cardinality,\n Optional extends boolean,\n> {\n readonly _tag: 'Relation'\n readonly owner: EntityIdentity<Name>\n readonly key: Key\n /** The target as `Entity.relate` returned it, so its own relations can be followed. */\n readonly target: () => Target\n readonly cardinality: C\n readonly optional: Optional\n /**\n * What happens to this row when the row a `one` relation points at is\n * deleted; none for a `many`, and for a `one` declared with nothing.\n */\n readonly onDelete: Option.Option<OnDelete>\n /** Who may let a cascade through it take this row: some exactly where `onDelete` is `cascade`. */\n readonly authorizedBy: Option.Option<AuthorizedBy>\n readonly metadata: Metadata\n}\n\ntype OneRelation = EntityRelation<string, string, AnyEntity, 'one', boolean>\n\n/**\n * What a derived member is. `Supplied` (`Derived.make`): an interpreter\n * supplies it, and nothing else can say what it is. `Count`\n * (`Derived.count`): how many rows point at this one through `relation`, a\n * `one` relation of the counted Entity. `Exists` (`Derived.exists`): the id of\n * a row pointing here through `relation` whose `viewer` relation points at\n * whoever reads it, or none. A client predicts both from the rows it writes,\n * and a server compiles both from the relations' storage.\n */\nexport type Derivation = Data.TaggedEnum<{\n /**\n * `predict`: how a client foresees it for a row it writes; none, it waits\n * for the server. `forbids`: which write to the row its value refuses, so a\n * client holding it refuses that write where it is made.\n */\n Supplied: { readonly predict: Option.Option<Predict>; readonly forbids: Option.Option<Forbids> }\n Count: { readonly relation: OneRelation }\n Exists: { readonly relation: OneRelation; readonly viewer: OneRelation }\n}>\nexport const Derivation = Data.taggedEnum<Derivation>()\n\n/** What a supplied member's prediction is given: the row a write leaves, as its holder has it. */\nexport interface Predicting {\n /** The Entity written, as the write declared it. */\n readonly entity: AnyEntity\n readonly row: HeldRow\n /** The holder's other rows, where a rule's path reads. */\n readonly rows: HeldRows\n /** The operation's context: who asks, and the write's time. */\n readonly context: ExprContext\n}\n\n/**\n * A supplied member foreseen: its value **encoded**, as the store holds it, or\n * none where the holder cannot know it, so nothing is shown before the answer.\n */\nexport type Predict = (predicting: Predicting) => Option.Option<unknown>\n\n/**\n * What a write does to a row it finds, as a supplied member's `forbids` is\n * asked: an update's members and the relations it points, or a delete.\n */\nexport interface WriteSurface {\n readonly kind: 'Update' | 'Delete'\n /** The members it sets, moves or computes, relations not among them. */\n readonly members: ReadonlyArray<string>\n /** Each relation it points: at a row (`Link`), or at none (`Unlink`). */\n readonly relations: ReadonlyArray<{\n readonly relation: string\n readonly interaction: 'Link' | 'Unlink'\n }>\n}\n\n/**\n * Whether a supplied member's value, **encoded** as the store holds it,\n * refuses `surface`, with the reader's words for why when there are any; none\n * where it does not say so for certain. Only a definite refusal: a client\n * refuses the write unseen, and its server would refuse it too.\n */\nexport type Forbids = (\n value: unknown,\n surface: WriteSurface,\n) => Option.Option<{ readonly reason: Option.Option<string> }>\n\n/** What `Derived.make`, `Derived.count` or `Derived.exists` returns, before an Entity owns it. */\nexport interface DerivedSpec<S extends Schema.Constraint, D extends Derivation = Derivation> {\n readonly schema: S\n readonly derives: D\n}\n\n/** A value consumers may read that is not part of `entity.schema`, and what it derives. */\nexport interface EntityDerived<\n Name extends string,\n Key extends string,\n S extends Schema.Constraint,\n D extends Derivation = Derivation,\n> {\n readonly _tag: 'Derived'\n readonly owner: EntityIdentity<Name>\n readonly key: Key\n readonly schema: S\n readonly derives: D\n readonly metadata: Metadata\n}\n\nexport type EntityMember =\n | EntityField<string, string, Schema.Constraint>\n | EntityRelation<string, string, AnyEntity, Cardinality, boolean>\n | EntityDerived<string, string, Schema.Constraint>\n\nexport type RelationSpecs = Readonly<Record<string, RelationSpec<AnyEntity, Cardinality, boolean>>>\nexport type DerivedSpecs = Readonly<Record<string, DerivedSpec<Schema.Constraint>>>\n\ntype FieldsOf<Name extends string, Fields extends Schema.Struct.Fields> = {\n readonly [K in keyof Fields & string]: EntityField<Name, K, Fields[K]>\n}\ntype RelationsOf<Name extends string, Relations extends RelationSpecs> = {\n readonly [K in keyof Relations & string]: Relations[K] extends RelationSpec<\n infer Target,\n infer C,\n infer Optional\n >\n ? EntityRelation<Name, K, Target, C, Optional>\n : never\n}\ntype DerivedOf<Name extends string, Derived extends DerivedSpecs> = {\n readonly [K in keyof Derived & string]: EntityDerived<\n Name,\n K,\n Derived[K]['schema'],\n Derived[K]['derives']\n >\n}\n\nexport interface Entity<\n Name extends string,\n Fields extends Schema.Struct.Fields,\n Relations extends RelationSpecs = {},\n Derived extends DerivedSpecs = {},\n>\n extends Pipeable.Pipeable {\n readonly [EntityTypeId]: EntityTypeId\n readonly identity: EntityIdentity<Name>\n readonly name: Name\n /** The intrinsic value only: no relations, no derived members. */\n readonly schema: Schema.Struct<Fields>\n readonly fields: FieldsOf<Name, Fields>\n readonly relations: RelationsOf<Name, Relations>\n readonly derived: DerivedOf<Name, Derived>\n /** Every readable member under one namespace; keys never collide. */\n readonly members: FieldsOf<Name, Fields> & RelationsOf<Name, Relations> & DerivedOf<Name, Derived>\n /** The members whose value is the write's context, never its input (`Entity.sets`), by key. */\n readonly sets: Readonly<Record<string, EntitySet>>\n readonly metadata: Metadata\n}\n\nexport type AnyEntity = Entity<string, any, any, any>\n\n/**\n * An Entity whose rows are one of several shapes (`Entity.defineVariants`).\n * `variants` is Effect's tagged union of them, read with its own `match`;\n * `fields` and `schema` are the stored row, which every case shares.\n */\nexport interface VariantEntity<\n Name extends string,\n Fields extends Schema.Struct.Fields,\n Relations extends RelationSpecs = {},\n Derived extends DerivedSpecs = {},\n Union extends AnyVariantUnion = AnyVariantUnion,\n> extends Entity<Name, Fields, Relations, Derived> {\n readonly variants: Union\n}\n\nexport type AnyVariantEntity = VariantEntity<string, any, any, any, any>\n\n/** The keys of an Entity's `one` relations. */\ntype OneRelationKeys<E extends AnyEntity> = {\n [K in keyof E['relations'] & string]: E['relations'][K]['cardinality'] extends 'one' ? K : never\n}[keyof E['relations'] & string]\n\n/**\n * What a field holding `T` may be set to: the time where it holds a number,\n * the viewer's id where text, and what a path from the viewer reads where it\n * holds that.\n */\ntype ContextValueFor<T> =\n | (number extends T ? NowExpr<number> : never)\n | (T extends string ? ViewerExpr<T> : never)\n | ViewerPathExpr<T | null>\n\n/** The name of the Entity the `one` relation `K` points at. */\ntype TargetName<E extends AnyEntity, K extends keyof E['relations']> = ReturnType<\n E['relations'][K]['target']\n>['name']\n\n/**\n * What `Entity.sets` takes, by member: a field the value of the write's\n * context it can hold, a `one` relation `Expr.viewer` of its target.\n */\nexport type EntitySets<E extends AnyEntity> = {\n readonly [K in Exclude<keyof E['fields'] & string, 'id'>]?: ContextValueFor<\n Schema.Schema.Type<E['fields'][K]['schema']>\n >\n} & {\n readonly [K in OneRelationKeys<E>]?: ViewerExpr<unknown, TargetName<E, K>>\n}\n\nexport type Entities = Readonly<Record<string, AnyEntity>>\nexport type RelationMap<Es extends Entities> = { readonly [K in keyof Es]?: RelationSpecs }\n\n/** The key in `Es` of the Entity a spec targets, matched by name. */\nexport type TargetKey<Es extends Entities, Target extends AnyEntity> = {\n [K in keyof Es]: [Es[K]['name'], Target['name']] extends [Target['name'], Es[K]['name']]\n ? K\n : never\n}[keyof Es]\n\nexport type RelatedSpecs<Es extends Entities, Rs extends RelationMap<Es>, K extends keyof Es> = {\n readonly [R in keyof Rs[K]]: Rs[K][R] extends RelationSpec<infer Target, infer C, infer Optional>\n ? RelationSpec<Related<Es, Rs, TargetKey<Es, Target>>, C, Optional>\n : never\n}\n\n/**\n * One Entity of an `Entity.relate` result. A relation's target is again a\n * `Related`, so relations can be followed through a cycle; the recursion goes\n * through type arguments, which TypeScript resolves only when asked.\n */\nexport type Related<Es extends Entities, Rs extends RelationMap<Es>, K extends keyof Es> =\n Es[K] extends VariantEntity<infer Name, infer Fields, infer R, infer D, infer U>\n ? VariantEntity<Name, Fields, R & RelatedSpecs<Es, Rs, K>, D, U>\n : Es[K] extends Entity<infer Name, infer Fields, infer R, infer D>\n ? Entity<Name, Fields, R & RelatedSpecs<Es, Rs, K>, D>\n : never\n\n/**\n * The schema that identifies one of an Entity: its `id` field when that is text\n * (a plain string, a brand, a pattern), and plain text otherwise. An id is text\n * because a ref travels and is stored as text; an Entity keyed by a number still\n * has refs, and their ids are the number as text.\n */\nexport type IdSchemaOf<E> = E extends {\n readonly fields: { readonly id: { readonly schema: infer S } }\n}\n ? S extends Schema.Constraint\n ? [S['Type']] extends [string]\n ? S\n : Schema.String\n : Schema.String\n : Schema.String\n\n/** What identifies one of an Entity: `IdOf<typeof Blog.Post>` is `PostId` when its `id` field is one. */\nexport type IdOf<E> = IdSchemaOf<E>['Type']\n\n/**\n * What a relation selected with `true` yields: which Entity, and which one. `Id`\n * is the target's own id type, so a ref to an Author cannot be used as a Post's.\n */\nexport interface EntityRef<Name extends string = string, Id extends string = string> {\n readonly entity: Name\n readonly id: Id\n}\n\n/**\n * A view of the Entity graph: which members to read, and the schema of the\n * value that results. It says nothing about where the value comes from.\n */\nexport interface Selection<\n Name extends string,\n Members,\n S extends Schema.Constraint,\n Id extends string = string,\n> {\n readonly [SelectionTypeId]: SelectionTypeId\n /** Type-only: the id type of the Entity selected, so a reader can ask for the right one. Never set. */\n readonly Id?: Id\n readonly entity: Entity<Name, any, any, any>\n /** What was selected, by member key: `true`, or a relation's nested Selection. */\n readonly members: Members\n readonly schema: S\n}\n\n/** The value a Selection reads: `Selected<typeof PostCard>` is one card's fields. */\nexport type Selected<S extends Selection<string, unknown, Schema.Constraint>> = S['schema']['Type']\n\n/**\n * Which part of a `many` relation to read: the first or last so many, from a\n * cursor or from the end. A cursor is whatever the interpreter handed out with an\n * earlier page; nothing here looks inside it.\n */\nexport interface PageWindow {\n readonly first?: number | undefined\n readonly last?: number | undefined\n readonly after?: string | undefined\n readonly before?: string | undefined\n}\n\n/** A Selection of a `many` relation's target, read a page at a time. */\nexport interface SelectionPage<Name extends string, S extends Schema.Constraint> {\n readonly [SelectionPageTypeId]: SelectionPageTypeId\n readonly selection: Selection<Name, any, S>\n readonly window: PageWindow\n}\n\n/** An input key that carries a relation's target: the id of a `one`, the ids of a `many`. */\nexport interface RelationInput<R extends EntityRelation<any, any, any, any, any>> {\n readonly _tag: 'RelationInput'\n readonly relation: R\n}\n\n/**\n * An input key that carries the relation's target itself, written through an\n * input of its own: a post created with a new author, an order with its lines.\n * A `one` holds that input's value, a `many` a list of them.\n */\nexport interface NestedInput<\n R extends EntityRelation<any, any, any, any, any>,\n I extends EntityInput<any, any, any>,\n> {\n readonly _tag: 'NestedInput'\n readonly relation: R\n readonly input: I\n}\n\n/** An input key that is about the operation, not the Entity: a reason, a flag, a confirmation. */\nexport interface Unmapped {\n readonly _tag: 'Unmapped'\n}\n\n/** What one key of an operation's input means in terms of the Entity. */\nexport type InputMember =\n | EntityField<string, string, Schema.Constraint>\n | RelationInput<EntityRelation<string, string, AnyEntity, Cardinality, boolean>>\n | NestedInput<\n EntityRelation<string, string, AnyEntity, Cardinality, boolean>,\n EntityInput<AnyEntity, any, any>\n >\n | Unmapped\n\n/**\n * An operation's input read against an Entity: which member each input key\n * writes. The operation decides what may be submitted; the Entity only says\n * what each submitted key means.\n */\nexport interface EntityInput<E extends AnyEntity, Fields extends Schema.Struct.Fields, Members> {\n readonly entity: E\n readonly schema: Schema.Struct<Fields>\n readonly members: Members\n}\n\nexport type { InputMembers, WrittenAs, WrittenKey, WrittenSpec } from './entity.js'\nexport { EntityMembers as Entity }\n\n/**\n * How a `one` relation is declared: whether it may point nowhere, and what a\n * delete of its target does. `authorizedBy` is said only beside `onDelete`.\n */\nexport type OneOptions<Optional extends boolean> = {\n readonly optional?: Optional\n} & (\n | { readonly onDelete?: undefined; readonly authorizedBy?: undefined }\n | {\n /** `cascade`: a row pointing here is deleted with the row it points at. */\n readonly onDelete: 'cascade'\n /** Whose `Delete` rule lets the cascade take this row: its own (`child`), or the parent's. */\n readonly authorizedBy?: AuthorizedBy\n }\n | {\n /** `restrict`: the row it points at cannot be deleted while this row points there. */\n readonly onDelete: 'restrict'\n readonly authorizedBy?: undefined\n }\n | {\n /** `setNull`: this row stays and points nowhere; only a link that may point nowhere can. */\n readonly onDelete: 'setNull'\n readonly optional: true\n readonly authorizedBy?: undefined\n }\n)\n\nfunction one<Target extends AnyEntity>(target: Target): RelationSpec<Target, 'one', false>\nfunction one<Target extends AnyEntity, const Optional extends boolean>(\n target: Target,\n options: OneOptions<Optional> & { readonly optional: Optional },\n): RelationSpec<Target, 'one', Optional>\nfunction one<Target extends AnyEntity>(\n target: Target,\n options: OneOptions<false>,\n): RelationSpec<Target, 'one', false>\nfunction one(\n target: AnyEntity,\n options?: OneOptions<boolean>,\n): RelationSpec<AnyEntity, 'one', boolean> {\n const onDelete = options?.onDelete\n const authorizedBy = options?.authorizedBy\n if (\n onDelete !== undefined &&\n onDelete !== 'cascade' &&\n onDelete !== 'restrict' &&\n onDelete !== 'setNull'\n )\n throw new Error(\n `[foldkit-entity] Relation.one(${target.name}): onDelete is 'cascade', 'restrict' or 'setNull'; ${String(onDelete)} is not one`,\n )\n if (onDelete === 'setNull' && options?.optional !== true)\n throw new Error(\n `[foldkit-entity] Relation.one(${target.name}): onDelete: 'setNull' clears the link, so it needs optional: true`,\n )\n if (authorizedBy !== undefined && authorizedBy !== 'child' && authorizedBy !== 'parent')\n throw new Error(\n `[foldkit-entity] Relation.one(${target.name}): authorizedBy is 'child' or 'parent'; ${String(authorizedBy)} is not one`,\n )\n if (authorizedBy !== undefined && onDelete !== 'cascade')\n throw new Error(\n `[foldkit-entity] Relation.one(${target.name}): authorizedBy says who lets a cascade take the row, so it needs onDelete: 'cascade'`,\n )\n return {\n target,\n cardinality: 'one',\n optional: options?.optional ?? false,\n onDelete: Option.fromUndefinedOr(onDelete),\n authorizedBy: onDelete === 'cascade' ? Option.some(authorizedBy ?? 'child') : Option.none(),\n }\n}\n\n/** What the owner sees: one or many of `target`. Used inside `Entity.relate`. */\nexport const Relation = {\n one,\n\n /** For `Entity.input`: the input key holds this relation's target id, or ids for a `many`. */\n input: <R extends EntityRelation<any, any, any, any, any>>(relation: R): RelationInput<R> =>\n Object.freeze({ _tag: 'RelationInput', relation }),\n\n /**\n * For `Entity.input`: the input key holds the relation's target itself, written\n * through `input`, an `Entity.input` of the target. A `many` holds a list.\n */\n nested: <R extends EntityRelation<any, any, any, any, any>, I extends EntityInput<any, any, any>>(\n relation: R,\n input: I,\n ): NestedInput<R, I> => Object.freeze({ _tag: 'NestedInput', relation, input }),\n\n many: <Target extends AnyEntity>(target: Target): RelationSpec<Target, 'many', false> => ({\n target,\n cardinality: 'many',\n optional: false,\n onDelete: Option.none(),\n authorizedBy: Option.none(),\n }),\n}\n\n/** A count: never negative, never a fraction. */\nconst CountSchema = Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0))\n\n/** The id of the row an exists found, as every Remote id is held: text, or none. */\nconst WitnessSchema = Schema.OptionFromNullOr(Schema.String)\n\ntype OwnerName<R> = R extends EntityRelation<infer Name, any, any, any, any> ? Name : never\n\nexport const Derived = {\n /**\n * A member only an interpreter can compute, of type `schema`: it supplies the\n * value. `predict` says how a client foresees it for a row it writes (Guard's\n * `may`); without it the row reads as missing the member until the answer.\n * `forbids` says which write to the row its value refuses (Guard's `may`\n * again), so a client holding it refuses that write where it is made.\n */\n make: <S extends Schema.Constraint>(\n schema: S,\n options: {\n readonly predict?: Predict | undefined\n readonly forbids?: Forbids | undefined\n } = {},\n ): DerivedSpec<S, Extract<Derivation, { readonly _tag: 'Supplied' }>> => ({\n schema,\n derives: Derivation.Supplied({\n predict: Option.fromUndefinedOr(options.predict),\n forbids: Option.fromUndefinedOr(options.forbids),\n }),\n }),\n\n /**\n * How many rows point at this one through `relation`, a `one` relation of\n * the counted Entity: `likeCount: Derived.count(Like.relations.post)` on\n * Post. Added after `Entity.relate`, which makes the relation. A server\n * compiles it from the relation's storage, and a client predicts it from\n * the rows a pending write inserts, deletes or points elsewhere.\n */\n count: <R extends EntityRelation<string, string, AnyEntity, 'one', boolean>>(\n relation: R,\n ): DerivedSpec<typeof CountSchema, { readonly _tag: 'Count'; readonly relation: R }> => ({\n schema: CountSchema,\n derives: Derivation.Count({ relation }) as { readonly _tag: 'Count'; readonly relation: R },\n }),\n\n /**\n * Whether a row points at this one through `relation` and at whoever reads\n * it through `viewer`, another `one` relation of the same pointing Entity:\n * `liked: Derived.exists(Like.relations.post, { viewer: Like.relations.user })`\n * on Post. Its value is that row's id as the store holds it, or none, so the\n * reader can take it back (`Write.delete` by that id). It depends on who\n * reads it: a server answers it for the principal it reads as, and a client\n * predicts it for the viewer it is told of.\n */\n exists: <\n R extends OneRelation,\n V extends EntityRelation<OwnerName<R>, string, AnyEntity, 'one', boolean>,\n >(\n relation: R,\n options: { readonly viewer: V },\n ): DerivedSpec<\n typeof WitnessSchema,\n { readonly _tag: 'Exists'; readonly relation: R; readonly viewer: V }\n > => ({\n schema: WitnessSchema,\n derives: Derivation.Exists({ relation, viewer: options.viewer }) as {\n readonly _tag: 'Exists'\n readonly relation: R\n readonly viewer: V\n },\n }),\n}\n\nexport * from './expr.js'\nexport {\n contextValue,\n viewerIdOf,\n type ExprContext,\n type NowExpr,\n type ViewerExpr,\n type ViewerPathExpr,\n} from './context.js'\nexport * from './collation.js'\nexport * from './operators.js'\nexport * from './law.js'\nexport * from './text.js'\nexport * from './readFilter.js'\nexport * from './words.js'\nexport * from './shape.js'\nexport type {\n AnyVariantUnion,\n CheckCases,\n EntityVariants,\n StoredFields,\n VariantCases,\n VariantUnion,\n} from './variants.js'\n// The reference semantics of the IR above. The conformance suite that proves\n// an interpreter agrees with it is `foldkit-entity/conformance`, kept out of\n// this entry because it is fixture data every form and admin screen would\n// otherwise carry.\nexport * from './evaluate.js'\nexport * from './held.js'\nexport type {\n AfterRow,\n BeforeRow,\n Change,\n DeclaredInvariant,\n Invariant,\n Judgement,\n} from './invariant.js'\nexport type { ContextValue, EntitySet, SetOn } from './sets.js'\nexport {\n Write,\n type AnyWrite,\n type BoundWrite,\n type ConditionedWrite,\n Computation,\n type WriteAssignment,\n type WriteComputations,\n type WriteCondition,\n type WriteIncrement,\n type WriteKind,\n type WriteLink,\n type WriteSet,\n type ContextSet,\n type ContextRead,\n type ContextValues,\n} from './write.js'\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AA8HA,MAAa,aAAa,KAAK,WAAuB;AA8VtD,SAAS,IACP,QACA,SACyC;CACzC,MAAM,WAAW,SAAS;CAC1B,MAAM,eAAe,SAAS;CAC9B,IACE,aAAa,KAAA,KACb,aAAa,aACb,aAAa,cACb,aAAa,WAEb,MAAM,IAAI,MACR,iCAAiC,OAAO,KAAK,qDAAqD,OAAO,QAAQ,EAAE,YACrH;CACF,IAAI,aAAa,aAAa,SAAS,aAAa,MAClD,MAAM,IAAI,MACR,iCAAiC,OAAO,KAAK,mEAC/C;CACF,IAAI,iBAAiB,KAAA,KAAa,iBAAiB,WAAW,iBAAiB,UAC7E,MAAM,IAAI,MACR,iCAAiC,OAAO,KAAK,0CAA0C,OAAO,YAAY,EAAE,YAC9G;CACF,IAAI,iBAAiB,KAAA,KAAa,aAAa,WAC7C,MAAM,IAAI,MACR,iCAAiC,OAAO,KAAK,sFAC/C;CACF,OAAO;EACL;EACA,aAAa;EACb,UAAU,SAAS,YAAY;EAC/B,UAAU,OAAO,gBAAgB,QAAQ;EACzC,cAAc,aAAa,YAAY,OAAO,KAAK,gBAAgB,OAAO,IAAI,OAAO,KAAK;CAC5F;AACF;;AAGA,MAAa,WAAW;CACtB;;CAGA,QAA2D,aACzD,OAAO,OAAO;EAAE,MAAM;EAAiB;CAAS,CAAC;;;;;CAMnD,SACE,UACA,UACsB,OAAO,OAAO;EAAE,MAAM;EAAe;EAAU;CAAM,CAAC;CAE9E,OAAiC,YAAyD;EACxF;EACA,aAAa;EACb,UAAU;EACV,UAAU,OAAO,KAAK;EACtB,cAAc,OAAO,KAAK;CAC5B;AACF;;AAGA,MAAM,cAAc,OAAO,OAAO,MAAM,OAAO,MAAM,GAAG,OAAO,uBAAuB,CAAC,CAAC;;AAGxF,MAAM,gBAAgB,OAAO,iBAAiB,OAAO,MAAM;AAI3D,MAAa,UAAU;;;;;;;;CAQrB,OACE,QACA,UAGI,CAAC,OACmE;EACxE;EACA,SAAS,WAAW,SAAS;GAC3B,SAAS,OAAO,gBAAgB,QAAQ,OAAO;GAC/C,SAAS,OAAO,gBAAgB,QAAQ,OAAO;EACjD,CAAC;CACH;;;;;;;;CASA,QACE,cACuF;EACvF,QAAQ;EACR,SAAS,WAAW,MAAM,EAAE,SAAS,CAAC;CACxC;;;;;;;;;;CAWA,SAIE,UACA,aAII;EACJ,QAAQ;EACR,SAAS,WAAW,OAAO;GAAE;GAAU,QAAQ,QAAQ;EAAO,CAAC;CAKjE;AACF"}
|
package/dist/invariant.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"invariant.d.ts","names":["MemoryOperators"],"sources":["../src/invariant.ts"],"mappings":";;;;;;
|
|
1
|
+
{"version":3,"file":"invariant.d.ts","names":["MemoryOperators"],"sources":["../src/invariant.ts"],"mappings":";;;;;;iBAiDiB;;WAEN;;WAEA;WACA,WAAW;;WAEX;;WAEA,MAAM;;WAEN,QAAQ;;WAER,OAAO;;;KAIb,SAAS,UAAU,gBACrB,WAAW,0BAA0B,eAAe,kCAAkC,mBACjF;;KAGH,OACH,UAAU,WACV,gBAAgB,kBACd,eAAe;;;;;;;YAQP,UAAU,UAAU,yBACpB,WAAW,uBAAuB,UAC1C,OAAO,MAAM,QAAQ,YAAY,iBAEjC,MAAM,4BACM,KAAK,SAAS,KAAK,UAAU,OAAO,GAAG,MAAM,MAAM;;YAGvD,SAAS,UAAU,yBACnB,WAAW,uBAAuB,SAC1C,OAAO,MAAM,QAAQ,YAAY,iBAEjC,MAAM,4BACM,KAAK,SAAS,KAAK,SAAS,OAAO,GAAG,MAAM,MAAM;;iBAGjD;WACN,OAAO;;WAEP,SAAS;;;YAUR;WACG;;WACA;WAA0B,UAAU,cAAc;;;;;;;WAMlD;WACA,QAAQ;WACR,WAAW;;;qBAIb,cAAW,MAAU;;;;;;;;;iBAUjB,kBAAkB,UAAU;GAC1C,QAAQ,IAAI;WACJ;WACA;;;KAQN,MAAM,UAAU,cAAc;WACxB,QAAQ,UAAU;WAClB,OAAO,SAAS;MACrB,YAAY,MAAM;UAEd,QAAQ,UAAU;WACjB;WACA,OAAO,qBAAqB,wBAAwB,SAAS;;;;;;;;;;;qBAiE3D,YAAa,UAAU,WAAS,YACjC,OACH,MAAM,IAAE,SACN,QAAQ,OAChB,kBAAkB;;qBAkFR,eAAY,QAAY,cAAY,cAAc;;qBAOlD,eAAY,YACX,cAAc,YAAU,QAC5B,QAAM,YACHA,sBACV;;;;;;;;qBAyCU,QAAK,QACR,WAAS,QACT,QAAM,YACHA,sBACV;;;;;;;;;qBAUU,aAAU,OACd,YAAY,sBAAoB,OAChC,SAAS,0BAAwB,YAC7BA,sBACV;;;;;;;;qBAsCU,QAAS,UAAU,WAAS,QAC/B,GAAC;WACW,YAAYA;MAC/B,UAAU,OAAO,OAAO,OAAO,KAAK"}
|
package/dist/invariant.js
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
import { Option, Schema } from "effect";
|
|
1
|
+
import { Match, Option, Schema } from "effect";
|
|
2
2
|
import { Metadata } from "foldkit-metadata";
|
|
3
3
|
import { put } from "./record.js";
|
|
4
4
|
import { storesNull, variantsOf } from "./variants.js";
|
|
5
5
|
import { remake, variantBases } from "./descriptor.js";
|
|
6
6
|
import { Expr, Query, dependenciesOf } from "./expr.js";
|
|
7
|
-
import {
|
|
7
|
+
import { kernelOperators } from "./memoryTable.js";
|
|
8
8
|
import { OperatorMissingError, truthOver } from "./evaluate.js";
|
|
9
9
|
// src/invariant.ts
|
|
10
10
|
/**
|
|
@@ -32,14 +32,17 @@ const Invariants = Metadata.key("foldkit-entity/invariants", {
|
|
|
32
32
|
});
|
|
33
33
|
/** Whether an invariant reads the row before a write: judged on updates only, and no CHECK. */
|
|
34
34
|
const readsBefore = (held) => held.before.length > 0;
|
|
35
|
-
const fail = (entity, message) => {
|
|
35
|
+
const fail$1 = (entity, message) => {
|
|
36
36
|
throw new Error(`[foldkit-entity] Entity.invariant on ${entity.name}: ${message}`);
|
|
37
37
|
};
|
|
38
38
|
/** The invariant `build` declares over `entity`'s rows, refused where it could judge nothing. */
|
|
39
39
|
const declareOn = (entity, id, build, options) => {
|
|
40
40
|
const fields = entity.fields;
|
|
41
41
|
const relations = entity.relations;
|
|
42
|
-
const links = Object.values(relations).flatMap((member) =>
|
|
42
|
+
const links = Object.values(relations).flatMap((member) => {
|
|
43
|
+
if (member._tag !== "Relation" || member.cardinality !== "one") return [];
|
|
44
|
+
return [member];
|
|
45
|
+
});
|
|
43
46
|
const nexts = [...Object.entries(fields).map(([key, field]) => [key, Expr.next(field)]), ...links.map((link) => [link.key, Expr.next(link)])];
|
|
44
47
|
const after = Object.fromEntries(nexts);
|
|
45
48
|
const predicate = build({
|
|
@@ -48,12 +51,12 @@ const declareOn = (entity, id, build, options) => {
|
|
|
48
51
|
});
|
|
49
52
|
const body = Query.from(entity).pipe(Query.where(predicate));
|
|
50
53
|
const dependencies = Query.dependencies(body);
|
|
51
|
-
if (dependencies.inputs.length > 0) fail(entity, `"${id}" reads the input ${dependencies.inputs.join(", ")}; it judges stored rows`);
|
|
54
|
+
if (dependencies.inputs.length > 0) fail$1(entity, `"${id}" reads the input ${dependencies.inputs.join(", ")}; it judges stored rows`);
|
|
52
55
|
const beforeReads = dependencies.predicate.map((field) => field.key);
|
|
53
56
|
const afterReads = dependencies.next.map((field) => field.key);
|
|
54
|
-
if (afterReads.length === 0) fail(entity, `"${id}" reads no field of \`after\`; what a write may start from is its \`when\``);
|
|
57
|
+
if (afterReads.length === 0) fail$1(entity, `"${id}" reads no field of \`after\`; what a write may start from is its \`when\``);
|
|
55
58
|
const path = options.path ?? [.../* @__PURE__ */ new Set([...afterReads, ...beforeReads])];
|
|
56
|
-
for (const key of path) if (!Object.hasOwn(fields, key) && !links.some((link) => link.key === key)) fail(entity, `"${id}"'s path names "${key}", neither a field nor a one relation`);
|
|
59
|
+
for (const key of path) if (!Object.hasOwn(fields, key) && !links.some((link) => link.key === key)) fail$1(entity, `"${id}"'s path names "${key}", neither a field nor a one relation`);
|
|
57
60
|
return Object.freeze({
|
|
58
61
|
id,
|
|
59
62
|
entity: entity.name,
|
|
@@ -76,9 +79,9 @@ const declareOn = (entity, id, build, options) => {
|
|
|
76
79
|
const invariant = (id, build, options) => {
|
|
77
80
|
let attached;
|
|
78
81
|
const declared = (entity) => {
|
|
79
|
-
if (id.length === 0) fail(entity, "an invariant needs an id");
|
|
80
|
-
if (attached !== void 0 && attached !== entity.name) fail(entity, `"${id}" is declared on ${attached} already: declare it again for this Entity`);
|
|
81
|
-
if (invariantsOf(entity).some((held) => held.id === id)) fail(entity, `"${id}" is declared twice`);
|
|
82
|
+
if (id.length === 0) fail$1(entity, "an invariant needs an id");
|
|
83
|
+
if (attached !== void 0 && attached !== entity.name) fail$1(entity, `"${id}" is declared on ${attached} already: declare it again for this Entity`);
|
|
84
|
+
if (invariantsOf(entity).some((held) => held.id === id)) fail$1(entity, `"${id}" is declared twice`);
|
|
82
85
|
const held = declareOn(entity, id, build, options);
|
|
83
86
|
attached = entity.name;
|
|
84
87
|
return remake(entity, { metadata: Metadata.combine([entity.metadata, Invariants.of(held)]) });
|
|
@@ -136,7 +139,7 @@ const invariantsOf = (entity) => {
|
|
|
136
139
|
return cases.length === 0 ? declared : [...cases, ...declared];
|
|
137
140
|
};
|
|
138
141
|
/** `Entity.judge` against invariants already read, such as those a database binding keeps. */
|
|
139
|
-
const judgeAgainst = (invariants, change, operators =
|
|
142
|
+
const judgeAgainst = (invariants, change, operators = kernelOperators) => {
|
|
140
143
|
const missing = /* @__PURE__ */ new Set();
|
|
141
144
|
const unrun = /* @__PURE__ */ new Set();
|
|
142
145
|
const failures = [];
|
|
@@ -170,7 +173,7 @@ const judgeAgainst = (invariants, change, operators = Operators.kernel) => {
|
|
|
170
173
|
* undecided, never valid. Without `before` (a create), transition invariants
|
|
171
174
|
* are not judged.
|
|
172
175
|
*/
|
|
173
|
-
const judge = (entity, change, operators =
|
|
176
|
+
const judge = (entity, change, operators = kernelOperators) => judgeAgainst(invariantsOf(entity), change, operators);
|
|
174
177
|
/**
|
|
175
178
|
* The row an input's value describes, judged under its Entity's state
|
|
176
179
|
* invariants: each key mapped to a field, encoded as the store holds it, and
|
|
@@ -179,7 +182,7 @@ const judge = (entity, change, operators = Operators.kernel) => judgeAgainst(inv
|
|
|
179
182
|
* key left out) is undecided, so a partial input is never called valid on its
|
|
180
183
|
* account. It has no row before, so it judges no transition.
|
|
181
184
|
*/
|
|
182
|
-
const judgeInput = (input, value, operators =
|
|
185
|
+
const judgeInput = (input, value, operators = kernelOperators) => {
|
|
183
186
|
const invariants = invariantsOf(input.entity);
|
|
184
187
|
if (invariants.length === 0) return { _tag: "Valid" };
|
|
185
188
|
const members = input.members;
|
|
@@ -212,7 +215,7 @@ const check = (entity, options = {}) => {
|
|
|
212
215
|
const predicates = invariantsOf(entity).map((held) => held.predicate);
|
|
213
216
|
const missing = Expr.unsupported(predicates, {
|
|
214
217
|
operations: dependenciesOf(...predicates).operations,
|
|
215
|
-
operators: options.operators ??
|
|
218
|
+
operators: options.operators ?? kernelOperators
|
|
216
219
|
});
|
|
217
220
|
if (missing.length > 0) throw new Error(`[foldkit-entity] Entity.check of ${entity.name}: its invariants call ${missing.join(", ")}, which the operator table does not run; pass one that does as \`operators\``);
|
|
218
221
|
return Schema.makeFilter((value) => {
|
|
@@ -224,11 +227,14 @@ const check = (entity, options = {}) => {
|
|
|
224
227
|
put(row, key, Schema.encodeUnknownSync(field.schema)(decoded[key]));
|
|
225
228
|
}
|
|
226
229
|
const judged = judge(entity, { after: row }, options.operators);
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
230
|
+
return Match.valueTags(judged, {
|
|
231
|
+
Invalid: ({ failures }) => failures.flatMap((failure) => failure.path.length === 0 ? [failure.message] : failure.path.map((key) => ({
|
|
232
|
+
path: [key],
|
|
233
|
+
issue: failure.message
|
|
234
|
+
}))),
|
|
235
|
+
Valid: () => void 0,
|
|
236
|
+
Undecided: () => void 0
|
|
237
|
+
});
|
|
232
238
|
});
|
|
233
239
|
};
|
|
234
240
|
export { check, invariant, invariantsOf, judge, judgeAgainst, judgeInput, readsBefore };
|
package/dist/invariant.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"invariant.js","names":[],"sources":["../src/invariant.ts"],"sourcesContent":["/**\n * Invariants: what every stored row of an Entity must hold, and what every\n * change of one must, declared once on the Entity through its metadata and read\n * from there by each interpreter: the reference judge here, a Schema check, a\n * form, a server's writer.\n *\n * One is built over the row before a write (`before`, each field as `Expr.field`) and\n * the row after it (`after`, each field as `Expr.next`); each `one` relation is\n * there too, as the id it points at, so a judged row holds it as that id. What\n * it reads decides when it is judged:\n *\n * ```text\n * reads `after` only -> a state invariant: every create and update, a CHECK constraint\n * reads `before` too -> a transition invariant: every update, which has a row before\n * ```\n *\n * It reads no input and no principal. Who may write is a guard's; whether a\n * write applies now is its `when`'s.\n */\nimport { Metadata } from 'foldkit-metadata'\nimport { Option, Schema, type SchemaAST } from 'effect'\nimport { OperatorMissingError, truthOver, type Row } from './evaluate.js'\nimport { Operators, type MemoryOperators } from './operators.js'\nimport { put } from './record.js'\nimport {\n Expr,\n Query,\n dependenciesOf,\n type FieldExpr,\n type NextExpr,\n type OneRelation,\n type Predicate,\n type Reads,\n} from './expr.js'\nimport { remake, variantBases } from './descriptor.js'\nimport type {\n AnyEntity,\n EntityField,\n EntityIdentity,\n EntityInput,\n EntityMember,\n InputMember,\n} from './index.js'\nimport { storesNull, variantsOf } from './variants.js'\n\ntype AnyField = EntityField<string, string, Schema.Constraint>\n\n/** One invariant of an Entity, as its interpreters read it. */\nexport interface Invariant {\n /** Stable, unique within its Entity: what a refusal names, and forms and logs key on. */\n readonly id: string\n /** The Entity it is declared on: ids are unique only within one, so a refusal names both. */\n readonly entity: string\n readonly predicate: Predicate\n /** What someone the rules let write is told when a write would break it. */\n readonly message: string\n /** The members a form shows the failure beside. */\n readonly path: ReadonlyArray<string>\n /** The members it reads of the row before a write (fields, `one` relations); none for a state invariant. */\n readonly before: ReadonlyArray<string>\n /** The members it reads of the row after. */\n readonly after: ReadonlyArray<string>\n}\n\n/** The keys of an Entity's `one` relations: what a row holds as the id each points at. */\ntype LinkKeys<E extends AnyEntity> = {\n [K in keyof E['relations'] & string]: E['relations'][K]['cardinality'] extends 'one' ? K : never\n}[keyof E['relations'] & string]\n\n/** The id a `one` relation points at, as a row holds it: null for an optional one pointing nowhere. */\ntype LinkOf<\n E extends AnyEntity,\n K extends keyof E['relations'],\n> = E['relations'][K]['optional'] extends true ? string | null : string\n\n/**\n * Each field as the row before a write holds it, and each `one` relation as\n * the id it points at: what an invariant reads as `before`. Encoded, as the\n * store holds it and the judge reads it, so a literal is written so too (a\n * date as its ISO text).\n */\nexport type BeforeRow<E extends AnyEntity> = {\n readonly [K in keyof E['fields'] & string]: FieldExpr<\n Schema.Codec.Encoded<E['fields'][K]['schema']>\n > &\n Reads<E['name']>\n} & { readonly [K in LinkKeys<E>]: FieldExpr<LinkOf<E, K>> & Reads<E['name']> }\n\n/** Each field, and each `one` relation's id, as the row after a write holds it: `after`. */\nexport type AfterRow<E extends AnyEntity> = {\n readonly [K in keyof E['fields'] & string]: NextExpr<\n Schema.Codec.Encoded<E['fields'][K]['schema']>\n > &\n Reads<E['name']>\n} & { readonly [K in LinkKeys<E>]: NextExpr<LinkOf<E, K>> & Reads<E['name']> }\n\n/** A row, or a change from one row to another, as an invariant is judged over it. */\nexport interface Change {\n readonly after: Row\n /** The row before an update; none for a create, which judges no transition invariant. */\n readonly before?: Row\n}\n\nconst Invariants = Metadata.key<Invariant>('foldkit-entity/invariants', {\n // The same invariant reached twice (two annotated copies combined) is one.\n merge: values => [...new Set(values)],\n summarize: invariant => invariant.id,\n})\n\n/** What a row, or a change, comes to under an Entity's invariants. */\nexport type Judgement =\n | { readonly _tag: 'Valid' }\n | { readonly _tag: 'Invalid'; readonly failures: ReadonlyArray<Invariant> }\n /**\n * Validity is not known: some invariant reads a field the row does not have\n * (`fields`), or calls an operator the table does not run (`operators`, by name).\n */\n | {\n readonly _tag: 'Undecided'\n readonly fields: ReadonlyArray<string>\n readonly operators: ReadonlyArray<string>\n }\n\n/** Whether an invariant reads the row before a write: judged on updates only, and no CHECK. */\nexport const readsBefore = (held: Invariant): boolean => held.before.length > 0\n\n/**\n * An invariant as declared: the step that attaches it to its Entity, carrying\n * its id and, once attached, that Entity's name, so a refusal is matched\n * against the declaration rather than a string spelled again\n * (`Refusal.isInvalidBy(refusal, reservedWithinQuantity)`). An id is unique\n * only within an Entity, so the name is part of what a refusal names; reading\n * it before the declaration is attached throws.\n */\nexport interface DeclaredInvariant<E extends AnyEntity> {\n (entity: E): E\n readonly id: string\n readonly entity: string\n}\n\nconst fail = (entity: AnyEntity, message: string): never => {\n throw new Error(`[foldkit-entity] Entity.invariant on ${entity.name}: ${message}`)\n}\n\n/** How an invariant is declared: what `build` returns over the rows, and what a failure says. */\ntype Build<E extends AnyEntity> = (rows: {\n readonly before: BeforeRow<E>\n readonly after: AfterRow<E>\n}) => Predicate & Reads<E['name']>\n\ninterface Options<E extends AnyEntity> {\n readonly message: string\n readonly path?: ReadonlyArray<(keyof E['fields'] & string) | LinkKeys<E>>\n}\n\n/** The invariant `build` declares over `entity`'s rows, refused where it could judge nothing. */\nconst declareOn = <E extends AnyEntity>(\n entity: E,\n id: string,\n build: Build<E>,\n options: Options<E>,\n): Invariant => {\n const fields = entity.fields as Readonly<Record<string, E['fields'][string]>>\n const relations = entity.relations as Readonly<Record<string, EntityMember>>\n // A `one` relation reads as the id it points at; a `many` holds no one value.\n const links = Object.values(relations).flatMap(member =>\n member._tag === 'Relation' && member.cardinality === 'one' ? [member as OneRelation] : [],\n )\n const nexts = [\n ...Object.entries(fields).map(([key, field]) => [key, Expr.next(field)] as const),\n ...links.map(link => [link.key, Expr.next(link)] as const),\n ]\n const after = Object.fromEntries(nexts) as unknown as AfterRow<E>\n // Before a write, each is what its `after` reads after it: the same operand, unmoved.\n const before = Object.fromEntries(\n nexts.map(([key, next]) => [key, next.field]),\n ) as unknown as BeforeRow<E>\n const predicate = build({ before, after }) as Predicate\n // `where` refuses a predicate over another Entity, which the type allows when it is unmarked.\n const body = Query.from(entity).pipe(Query.where(predicate))\n const dependencies = Query.dependencies(body)\n if (dependencies.inputs.length > 0) {\n fail(entity, `\"${id}\" reads the input ${dependencies.inputs.join(', ')}; it judges stored rows`)\n }\n const beforeReads = dependencies.predicate.map(field => field.key)\n const afterReads = dependencies.next.map(field => field.key)\n // Reading the row before alone, it says which rows a write may start from: a write's `when`.\n // Judged as an invariant, a create would skip it and a repair would be refused by it.\n if (afterReads.length === 0) {\n fail(entity, `\"${id}\" reads no field of \\`after\\`; what a write may start from is its \\`when\\``)\n }\n const path = options.path ?? [...new Set([...afterReads, ...beforeReads])]\n for (const key of path) {\n if (!Object.hasOwn(fields, key) && !links.some(link => link.key === key))\n fail(entity, `\"${id}\"'s path names \"${key}\", neither a field nor a one relation`)\n }\n return Object.freeze({\n id,\n entity: entity.name,\n predicate,\n message: options.message,\n path: Object.freeze([...path]),\n before: Object.freeze(beforeReads),\n after: Object.freeze(afterReads),\n })\n}\n\n/**\n * Declares what every stored row, or every change of one, must hold:\n * `Entity.invariant('reservedWithinQuantity', ({ after }) =>\n * Expr.lte(after.reserved, after.quantity), { message })` over the row a\n * write leaves, or with `before` too over the change an update makes.\n * Refused where it is declared: an id declared twice, a predicate over another\n * Entity, one reading an input or nothing of `after` (that is a `when`), a path\n * naming no field.\n */\nexport const invariant = <E extends AnyEntity>(\n id: string,\n build: Build<E>,\n options: Options<E>,\n): DeclaredInvariant<E> => {\n let attached: string | undefined\n const declared = (entity: E): E => {\n if (id.length === 0) fail(entity, 'an invariant needs an id')\n if (attached !== undefined && attached !== entity.name)\n fail(entity, `\"${id}\" is declared on ${attached} already: declare it again for this Entity`)\n if (invariantsOf(entity).some(held => held.id === id)) fail(entity, `\"${id}\" is declared twice`)\n const held = declareOn(entity, id, build, options)\n attached = entity.name\n return remake(entity, {\n metadata: Metadata.combine([entity.metadata, Invariants.of(held)]),\n }) as E\n }\n return Object.defineProperties(declared, {\n id: { value: id, enumerable: true },\n entity: {\n enumerable: true,\n get: () => {\n if (attached === undefined) {\n throw new Error(\n `[foldkit-entity] Entity.invariant \"${id}\" names no Entity until it is attached to one`,\n )\n }\n return attached\n },\n },\n }) as DeclaredInvariant<E>\n}\n\nconst ofCases = new WeakMap<EntityIdentity<string>, ReadonlyArray<Invariant>>()\n\n/**\n * Each case's invariant of a variant Entity (`variant_Available`): a field\n * of its own is held, and one of another case is null. Built when first\n * read, so declaring variants reaches no expression code.\n */\nconst caseInvariants = (identity: EntityIdentity<string>): ReadonlyArray<Invariant> => {\n const base = variantBases.get(identity)\n if (base === undefined) return []\n const known = ofCases.get(identity)\n if (known !== undefined) return known\n const variants = Option.getOrThrow(variantsOf(identity))\n const { name } = base\n const separate = Object.keys(base.fields).filter(\n key => key !== '_tag' && variants.tags.some(tag => !Object.hasOwn(variants.cases[tag]!, key)),\n )\n const built = variants.tags.flatMap(tag => {\n const own = variants.cases[tag]!\n const reads = separate.filter(key => !Object.hasOwn(own, key) || !storesNull(own[key]!))\n if (reads.length === 0) return []\n const held = reads.filter(key => Object.hasOwn(own, key))\n const foreign = reads.filter(key => !Object.hasOwn(own, key))\n return [\n declareOn<AnyEntity>(\n base,\n `variant_${tag}`,\n ({ after }) => {\n const row = after as Readonly<Record<string, NextExpr<unknown>>>\n const checks = [\n ...held.map(key => Expr.isNotNull(row[key]!)),\n ...foreign.map(key => Expr.isNull(row[key]!)),\n ]\n return Expr.or(\n Expr.not(Expr.eq(row._tag!, tag)),\n Expr.and(checks[0]!, ...checks.slice(1)),\n )\n },\n {\n message: `A ${name} that is ${tag} ${[\n ...(held.length > 0 ? [`holds ${held.join(', ')}`] : []),\n ...(foreign.length > 0 ? [`holds none of ${foreign.join(', ')}`] : []),\n ].join(' and ')}`,\n path: reads,\n },\n ),\n ]\n })\n ofCases.set(identity, built)\n return built\n}\n\n/** The Entity's invariants, in the order they were declared. */\nexport const invariantsOf = (entity: AnyEntity): ReadonlyArray<Invariant> => {\n const cases = caseInvariants(entity.identity)\n const declared = Invariants.get(entity.metadata)\n return cases.length === 0 ? declared : [...cases, ...declared]\n}\n\n/** `Entity.judge` against invariants already read, such as those a database binding keeps. */\nexport const judgeAgainst = (\n invariants: ReadonlyArray<Invariant>,\n change: Change,\n operators: MemoryOperators = Operators.kernel,\n): Judgement => {\n const missing = new Set<string>()\n const unrun = new Set<string>()\n const failures: Array<Invariant> = []\n const { after, before } = change\n for (const held of invariants) {\n // A create has no row before, so a transition invariant has nothing to judge.\n if (readsBefore(held) && before === undefined) continue\n const absent = [\n ...held.after.filter(key => !Object.hasOwn(after, key)),\n ...held.before.filter(key => !Object.hasOwn(before ?? {}, key)),\n ]\n if (absent.length > 0) absent.forEach(key => missing.add(key))\n else {\n try {\n if (truthOver(held.predicate, before ?? {}, {}, after, operators) !== true) {\n failures.push(held)\n }\n } catch (error) {\n // An operator this table does not run is a judgement it cannot make, as a\n // field the row lacks is: a form passes it, and a server's checks refuse to\n // start without the operator (expr-operations-DESIGN §5.6).\n if (!(error instanceof OperatorMissingError)) throw error\n unrun.add(error.named)\n }\n }\n }\n if (failures.length > 0) return { _tag: 'Invalid', failures }\n if (missing.size > 0 || unrun.size > 0) {\n return { _tag: 'Undecided', fields: [...missing], operators: [...unrun] }\n }\n return { _tag: 'Valid' }\n}\n\n/**\n * A row, or a change, under every invariant (each row as the store holds it,\n * encoded): valid only when each is true. SQL's unknown, from a null, fails\n * one, as a `WHERE` drops the row; a field a row does not have leaves it\n * undecided, never valid. Without `before` (a create), transition invariants\n * are not judged.\n */\nexport const judge = (\n entity: AnyEntity,\n change: Change,\n operators: MemoryOperators = Operators.kernel,\n): Judgement => judgeAgainst(invariantsOf(entity), change, operators)\n\n/**\n * The row an input's value describes, judged under its Entity's state\n * invariants: each key mapped to a field, encoded as the store holds it, and\n * each mapped to a `one` relation as the id it points at. An\n * invariant over a field the input does not set (an `Option` holding nothing, a\n * key left out) is undecided, so a partial input is never called valid on its\n * account. It has no row before, so it judges no transition.\n */\nexport const judgeInput = (\n input: EntityInput<AnyEntity, any, any>,\n value: Readonly<Record<string, unknown>>,\n operators: MemoryOperators = Operators.kernel,\n): Judgement => {\n const invariants = invariantsOf(input.entity)\n if (invariants.length === 0) return { _tag: 'Valid' }\n const members = input.members as Readonly<Record<string, InputMember>>\n const row: Record<string, unknown> = {}\n for (const [key, member] of Object.entries(members)) {\n if (!Object.hasOwn(value, key)) continue\n // A `one` relation's key holds the id it points at: the row holds that id, or null.\n if (member._tag === 'RelationInput' && member.relation.cardinality === 'one') {\n const given = value[key]\n const id = Option.isOption(given) ? Option.getOrUndefined(given) : given\n if (id === null || typeof id === 'string') put(row, member.relation.key, id)\n continue\n }\n if (member._tag !== 'Field') continue\n const encode = Schema.encodeUnknownOption(\n member.schema as unknown as Schema.Codec<unknown, unknown>,\n )\n const given = value[key]\n const held = Option.isOption(given) ? given : Option.fromUndefinedOr(given)\n // The value as the field holds it: itself for a field typed `Option`, else what it holds.\n // One the field cannot hold is no row the store would keep, so it decides nothing here.\n const stored = Option.orElse(encode(given), () => Option.flatMap(held, encode))\n Option.map(\n Option.flatMap(held, () => stored),\n encoded => put(row, member.key, encoded),\n )\n }\n return judgeAgainst(invariants, { after: row }, operators)\n}\n\n/**\n * The Entity's state invariants as an Effect Schema check over its row type:\n * each failure at its path, with its message. The value is encoded first,\n * field by field, so it is judged as the store would hold it. Refused where it\n * is made when an invariant calls an operator `operators` does not run: such a\n * check would pass every value.\n */\nexport const check = <E extends AnyEntity>(\n entity: E,\n options: { readonly operators?: MemoryOperators | undefined } = {},\n): SchemaAST.Filter<Schema.Schema.Type<E['schema']>> => {\n const predicates = invariantsOf(entity).map(held => held.predicate)\n // The judge runs every operation an invariant reads; an operator alone can be missing.\n const missing = Expr.unsupported(predicates, {\n operations: dependenciesOf(...predicates).operations,\n operators: options.operators ?? Operators.kernel,\n })\n if (missing.length > 0) {\n throw new Error(\n `[foldkit-entity] Entity.check of ${entity.name}: its invariants call ${missing.join(', ')}, which the operator table does not run; pass one that does as \\`operators\\``,\n )\n }\n return Schema.makeFilter(value => {\n const fields = entity.fields as Readonly<Record<string, AnyField>>\n const decoded = value as Readonly<Record<string, unknown>>\n const row: Record<string, unknown> = {}\n for (const [key, field] of Object.entries(fields)) {\n if (!Object.hasOwn(decoded, key)) continue\n put(\n row,\n key,\n Schema.encodeUnknownSync(field.schema as unknown as Schema.Codec<unknown, unknown>)(\n decoded[key],\n ),\n )\n }\n const judged = judge(entity, { after: row }, options.operators)\n if (judged._tag !== 'Invalid') return undefined\n return judged.failures.flatMap((failure): ReadonlyArray<Schema.FilterIssue> =>\n failure.path.length === 0\n ? [failure.message]\n : failure.path.map(key => ({ path: [key], issue: failure.message })),\n )\n })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuGA,MAAM,aAAa,SAAS,IAAe,6BAA6B;CAEtE,QAAO,WAAU,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC;CACpC,YAAW,cAAa,UAAU;AACpC,CAAC;;AAiBD,MAAa,eAAe,SAA6B,KAAK,OAAO,SAAS;AAgB9E,MAAM,QAAQ,QAAmB,YAA2B;CAC1D,MAAM,IAAI,MAAM,wCAAwC,OAAO,KAAK,IAAI,SAAS;AACnF;;AAcA,MAAM,aACJ,QACA,IACA,OACA,YACc;CACd,MAAM,SAAS,OAAO;CACtB,MAAM,YAAY,OAAO;CAEzB,MAAM,QAAQ,OAAO,OAAO,SAAS,CAAC,CAAC,SAAQ,WAC7C,OAAO,SAAS,cAAc,OAAO,gBAAgB,QAAQ,CAAC,MAAqB,IAAI,CAAC,CAC1F;CACA,MAAM,QAAQ,CACZ,GAAG,OAAO,QAAQ,MAAM,CAAC,CAAC,KAAK,CAAC,KAAK,WAAW,CAAC,KAAK,KAAK,KAAK,KAAK,CAAC,CAAU,GAChF,GAAG,MAAM,KAAI,SAAQ,CAAC,KAAK,KAAK,KAAK,KAAK,IAAI,CAAC,CAAU,CAC3D;CACA,MAAM,QAAQ,OAAO,YAAY,KAAK;CAKtC,MAAM,YAAY,MAAM;EAAE,QAHX,OAAO,YACpB,MAAM,KAAK,CAAC,KAAK,UAAU,CAAC,KAAK,KAAK,KAAK,CAAC,CAEf;EAAG;CAAM,CAAC;CAEzC,MAAM,OAAO,MAAM,KAAK,MAAM,CAAC,CAAC,KAAK,MAAM,MAAM,SAAS,CAAC;CAC3D,MAAM,eAAe,MAAM,aAAa,IAAI;CAC5C,IAAI,aAAa,OAAO,SAAS,GAC/B,KAAK,QAAQ,IAAI,GAAG,oBAAoB,aAAa,OAAO,KAAK,IAAI,EAAE,wBAAwB;CAEjG,MAAM,cAAc,aAAa,UAAU,KAAI,UAAS,MAAM,GAAG;CACjE,MAAM,aAAa,aAAa,KAAK,KAAI,UAAS,MAAM,GAAG;CAG3D,IAAI,WAAW,WAAW,GACxB,KAAK,QAAQ,IAAI,GAAG,2EAA2E;CAEjG,MAAM,OAAO,QAAQ,QAAQ,CAAC,mBAAG,IAAI,IAAI,CAAC,GAAG,YAAY,GAAG,WAAW,CAAC,CAAC;CACzE,KAAK,MAAM,OAAO,MAChB,IAAI,CAAC,OAAO,OAAO,QAAQ,GAAG,KAAK,CAAC,MAAM,MAAK,SAAQ,KAAK,QAAQ,GAAG,GACrE,KAAK,QAAQ,IAAI,GAAG,kBAAkB,IAAI,sCAAsC;CAEpF,OAAO,OAAO,OAAO;EACnB;EACA,QAAQ,OAAO;EACf;EACA,SAAS,QAAQ;EACjB,MAAM,OAAO,OAAO,CAAC,GAAG,IAAI,CAAC;EAC7B,QAAQ,OAAO,OAAO,WAAW;EACjC,OAAO,OAAO,OAAO,UAAU;CACjC,CAAC;AACH;;;;;;;;;;AAWA,MAAa,aACX,IACA,OACA,YACyB;CACzB,IAAI;CACJ,MAAM,YAAY,WAAiB;EACjC,IAAI,GAAG,WAAW,GAAG,KAAK,QAAQ,0BAA0B;EAC5D,IAAI,aAAa,KAAA,KAAa,aAAa,OAAO,MAChD,KAAK,QAAQ,IAAI,GAAG,mBAAmB,SAAS,2CAA2C;EAC7F,IAAI,aAAa,MAAM,CAAC,CAAC,MAAK,SAAQ,KAAK,OAAO,EAAE,GAAG,KAAK,QAAQ,IAAI,GAAG,oBAAoB;EAC/F,MAAM,OAAO,UAAU,QAAQ,IAAI,OAAO,OAAO;EACjD,WAAW,OAAO;EAClB,OAAO,OAAO,QAAQ,EACpB,UAAU,SAAS,QAAQ,CAAC,OAAO,UAAU,WAAW,GAAG,IAAI,CAAC,CAAC,EACnE,CAAC;CACH;CACA,OAAO,OAAO,iBAAiB,UAAU;EACvC,IAAI;GAAE,OAAO;GAAI,YAAY;EAAK;EAClC,QAAQ;GACN,YAAY;GACZ,WAAW;IACT,IAAI,aAAa,KAAA,GACf,MAAM,IAAI,MACR,sCAAsC,GAAG,8CAC3C;IAEF,OAAO;GACT;EACF;CACF,CAAC;AACH;AAEA,MAAM,0BAAU,IAAI,QAA0D;;;;;;AAO9E,MAAM,kBAAkB,aAA+D;CACrF,MAAM,OAAO,aAAa,IAAI,QAAQ;CACtC,IAAI,SAAS,KAAA,GAAW,OAAO,CAAC;CAChC,MAAM,QAAQ,QAAQ,IAAI,QAAQ;CAClC,IAAI,UAAU,KAAA,GAAW,OAAO;CAChC,MAAM,WAAW,OAAO,WAAW,WAAW,QAAQ,CAAC;CACvD,MAAM,EAAE,SAAS;CACjB,MAAM,WAAW,OAAO,KAAK,KAAK,MAAM,CAAC,CAAC,QACxC,QAAO,QAAQ,UAAU,SAAS,KAAK,MAAK,QAAO,CAAC,OAAO,OAAO,SAAS,MAAM,MAAO,GAAG,CAAC,CAC9F;CACA,MAAM,QAAQ,SAAS,KAAK,SAAQ,QAAO;EACzC,MAAM,MAAM,SAAS,MAAM;EAC3B,MAAM,QAAQ,SAAS,QAAO,QAAO,CAAC,OAAO,OAAO,KAAK,GAAG,KAAK,CAAC,WAAW,IAAI,IAAK,CAAC;EACvF,IAAI,MAAM,WAAW,GAAG,OAAO,CAAC;EAChC,MAAM,OAAO,MAAM,QAAO,QAAO,OAAO,OAAO,KAAK,GAAG,CAAC;EACxD,MAAM,UAAU,MAAM,QAAO,QAAO,CAAC,OAAO,OAAO,KAAK,GAAG,CAAC;EAC5D,OAAO,CACL,UACE,MACA,WAAW,QACV,EAAE,YAAY;GACb,MAAM,MAAM;GACZ,MAAM,SAAS,CACb,GAAG,KAAK,KAAI,QAAO,KAAK,UAAU,IAAI,IAAK,CAAC,GAC5C,GAAG,QAAQ,KAAI,QAAO,KAAK,OAAO,IAAI,IAAK,CAAC,CAC9C;GACA,OAAO,KAAK,GACV,KAAK,IAAI,KAAK,GAAG,IAAI,MAAO,GAAG,CAAC,GAChC,KAAK,IAAI,OAAO,IAAK,GAAG,OAAO,MAAM,CAAC,CAAC,CACzC;EACF,GACA;GACE,SAAS,KAAK,KAAK,WAAW,IAAI,GAAG,CACnC,GAAI,KAAK,SAAS,IAAI,CAAC,SAAS,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC,GACtD,GAAI,QAAQ,SAAS,IAAI,CAAC,iBAAiB,QAAQ,KAAK,IAAI,GAAG,IAAI,CAAC,CACtE,CAAC,CAAC,KAAK,OAAO;GACd,MAAM;EACR,CACF,CACF;CACF,CAAC;CACD,QAAQ,IAAI,UAAU,KAAK;CAC3B,OAAO;AACT;;AAGA,MAAa,gBAAgB,WAAgD;CAC3E,MAAM,QAAQ,eAAe,OAAO,QAAQ;CAC5C,MAAM,WAAW,WAAW,IAAI,OAAO,QAAQ;CAC/C,OAAO,MAAM,WAAW,IAAI,WAAW,CAAC,GAAG,OAAO,GAAG,QAAQ;AAC/D;;AAGA,MAAa,gBACX,YACA,QACA,YAA6B,UAAU,WACzB;CACd,MAAM,0BAAU,IAAI,IAAY;CAChC,MAAM,wBAAQ,IAAI,IAAY;CAC9B,MAAM,WAA6B,CAAC;CACpC,MAAM,EAAE,OAAO,WAAW;CAC1B,KAAK,MAAM,QAAQ,YAAY;EAE7B,IAAI,YAAY,IAAI,KAAK,WAAW,KAAA,GAAW;EAC/C,MAAM,SAAS,CACb,GAAG,KAAK,MAAM,QAAO,QAAO,CAAC,OAAO,OAAO,OAAO,GAAG,CAAC,GACtD,GAAG,KAAK,OAAO,QAAO,QAAO,CAAC,OAAO,OAAO,UAAU,CAAC,GAAG,GAAG,CAAC,CAChE;EACA,IAAI,OAAO,SAAS,GAAG,OAAO,SAAQ,QAAO,QAAQ,IAAI,GAAG,CAAC;OAE3D,IAAI;GACF,IAAI,UAAU,KAAK,WAAW,UAAU,CAAC,GAAG,CAAC,GAAG,OAAO,SAAS,MAAM,MACpE,SAAS,KAAK,IAAI;EAEtB,SAAS,OAAO;GAId,IAAI,EAAE,iBAAiB,uBAAuB,MAAM;GACpD,MAAM,IAAI,MAAM,KAAK;EACvB;CAEJ;CACA,IAAI,SAAS,SAAS,GAAG,OAAO;EAAE,MAAM;EAAW;CAAS;CAC5D,IAAI,QAAQ,OAAO,KAAK,MAAM,OAAO,GACnC,OAAO;EAAE,MAAM;EAAa,QAAQ,CAAC,GAAG,OAAO;EAAG,WAAW,CAAC,GAAG,KAAK;CAAE;CAE1E,OAAO,EAAE,MAAM,QAAQ;AACzB;;;;;;;;AASA,MAAa,SACX,QACA,QACA,YAA6B,UAAU,WACzB,aAAa,aAAa,MAAM,GAAG,QAAQ,SAAS;;;;;;;;;AAUpE,MAAa,cACX,OACA,OACA,YAA6B,UAAU,WACzB;CACd,MAAM,aAAa,aAAa,MAAM,MAAM;CAC5C,IAAI,WAAW,WAAW,GAAG,OAAO,EAAE,MAAM,QAAQ;CACpD,MAAM,UAAU,MAAM;CACtB,MAAM,MAA+B,CAAC;CACtC,KAAK,MAAM,CAAC,KAAK,WAAW,OAAO,QAAQ,OAAO,GAAG;EACnD,IAAI,CAAC,OAAO,OAAO,OAAO,GAAG,GAAG;EAEhC,IAAI,OAAO,SAAS,mBAAmB,OAAO,SAAS,gBAAgB,OAAO;GAC5E,MAAM,QAAQ,MAAM;GACpB,MAAM,KAAK,OAAO,SAAS,KAAK,IAAI,OAAO,eAAe,KAAK,IAAI;GACnE,IAAI,OAAO,QAAQ,OAAO,OAAO,UAAU,IAAI,KAAK,OAAO,SAAS,KAAK,EAAE;GAC3E;EACF;EACA,IAAI,OAAO,SAAS,SAAS;EAC7B,MAAM,SAAS,OAAO,oBACpB,OAAO,MACT;EACA,MAAM,QAAQ,MAAM;EACpB,MAAM,OAAO,OAAO,SAAS,KAAK,IAAI,QAAQ,OAAO,gBAAgB,KAAK;EAG1E,MAAM,SAAS,OAAO,OAAO,OAAO,KAAK,SAAS,OAAO,QAAQ,MAAM,MAAM,CAAC;EAC9E,OAAO,IACL,OAAO,QAAQ,YAAY,MAAM,IACjC,YAAW,IAAI,KAAK,OAAO,KAAK,OAAO,CACzC;CACF;CACA,OAAO,aAAa,YAAY,EAAE,OAAO,IAAI,GAAG,SAAS;AAC3D;;;;;;;;AASA,MAAa,SACX,QACA,UAAgE,CAAC,MACX;CACtD,MAAM,aAAa,aAAa,MAAM,CAAC,CAAC,KAAI,SAAQ,KAAK,SAAS;CAElE,MAAM,UAAU,KAAK,YAAY,YAAY;EAC3C,YAAY,eAAe,GAAG,UAAU,CAAC,CAAC;EAC1C,WAAW,QAAQ,aAAa,UAAU;CAC5C,CAAC;CACD,IAAI,QAAQ,SAAS,GACnB,MAAM,IAAI,MACR,oCAAoC,OAAO,KAAK,wBAAwB,QAAQ,KAAK,IAAI,EAAE,6EAC7F;CAEF,OAAO,OAAO,YAAW,UAAS;EAChC,MAAM,SAAS,OAAO;EACtB,MAAM,UAAU;EAChB,MAAM,MAA+B,CAAC;EACtC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,MAAM,GAAG;GACjD,IAAI,CAAC,OAAO,OAAO,SAAS,GAAG,GAAG;GAClC,IACE,KACA,KACA,OAAO,kBAAkB,MAAM,MAAmD,CAAC,CACjF,QAAQ,IACV,CACF;EACF;EACA,MAAM,SAAS,MAAM,QAAQ,EAAE,OAAO,IAAI,GAAG,QAAQ,SAAS;EAC9D,IAAI,OAAO,SAAS,WAAW,OAAO,KAAA;EACtC,OAAO,OAAO,SAAS,SAAS,YAC9B,QAAQ,KAAK,WAAW,IACpB,CAAC,QAAQ,OAAO,IAChB,QAAQ,KAAK,KAAI,SAAQ;GAAE,MAAM,CAAC,GAAG;GAAG,OAAO,QAAQ;EAAQ,EAAE,CACvE;CACF,CAAC;AACH"}
|
|
1
|
+
{"version":3,"file":"invariant.js","names":["fail"],"sources":["../src/invariant.ts"],"sourcesContent":["/**\n * Invariants: what every stored row of an Entity must hold, and what every\n * change of one must, declared once on the Entity through its metadata and read\n * from there by each interpreter: the reference judge here, a Schema check, a\n * form, a server's writer.\n *\n * One is built over the row before a write (`before`, each field as `Expr.field`) and\n * the row after it (`after`, each field as `Expr.next`); each `one` relation is\n * there too, as the id it points at, so a judged row holds it as that id. What\n * it reads decides when it is judged:\n *\n * ```text\n * reads `after` only -> a state invariant: every create and update, a CHECK constraint\n * reads `before` too -> a transition invariant: every update, which has a row before\n * ```\n *\n * It reads no input and no principal. Who may write is a guard's; whether a\n * write applies now is its `when`'s.\n */\nimport { Metadata } from 'foldkit-metadata'\nimport { Match, Option, Schema, type SchemaAST } from 'effect'\nimport { OperatorMissingError, truthOver, type Row } from './evaluate.js'\nimport { kernelOperators } from './memoryTable.js'\nimport type { MemoryOperators } from './operators.js'\nimport { put } from './record.js'\nimport {\n Expr,\n Query,\n dependenciesOf,\n type FieldExpr,\n type NextExpr,\n type OneRelation,\n type Predicate,\n type Reads,\n} from './expr.js'\nimport { remake, variantBases } from './descriptor.js'\nimport type {\n AnyEntity,\n EntityField,\n EntityIdentity,\n EntityInput,\n EntityMember,\n InputMember,\n} from './index.js'\nimport { storesNull, variantsOf } from './variants.js'\n\ntype AnyField = EntityField<string, string, Schema.Constraint>\n\n/** One invariant of an Entity, as its interpreters read it. */\nexport interface Invariant {\n /** Stable, unique within its Entity: what a refusal names, and forms and logs key on. */\n readonly id: string\n /** The Entity it is declared on: ids are unique only within one, so a refusal names both. */\n readonly entity: string\n readonly predicate: Predicate\n /** What someone the rules let write is told when a write would break it. */\n readonly message: string\n /** The members a form shows the failure beside. */\n readonly path: ReadonlyArray<string>\n /** The members it reads of the row before a write (fields, `one` relations); none for a state invariant. */\n readonly before: ReadonlyArray<string>\n /** The members it reads of the row after. */\n readonly after: ReadonlyArray<string>\n}\n\n/** The keys of an Entity's `one` relations: what a row holds as the id each points at. */\ntype LinkKeys<E extends AnyEntity> = {\n [K in keyof E['relations'] & string]: E['relations'][K]['cardinality'] extends 'one' ? K : never\n}[keyof E['relations'] & string]\n\n/** The id a `one` relation points at, as a row holds it: null for an optional one pointing nowhere. */\ntype LinkOf<\n E extends AnyEntity,\n K extends keyof E['relations'],\n> = E['relations'][K]['optional'] extends true ? string | null : string\n\n/**\n * Each field as the row before a write holds it, and each `one` relation as\n * the id it points at: what an invariant reads as `before`. Encoded, as the\n * store holds it and the judge reads it, so a literal is written so too (a\n * date as its ISO text).\n */\nexport type BeforeRow<E extends AnyEntity> = {\n readonly [K in keyof E['fields'] & string]: FieldExpr<\n Schema.Codec.Encoded<E['fields'][K]['schema']>\n > &\n Reads<E['name']>\n} & { readonly [K in LinkKeys<E>]: FieldExpr<LinkOf<E, K>> & Reads<E['name']> }\n\n/** Each field, and each `one` relation's id, as the row after a write holds it: `after`. */\nexport type AfterRow<E extends AnyEntity> = {\n readonly [K in keyof E['fields'] & string]: NextExpr<\n Schema.Codec.Encoded<E['fields'][K]['schema']>\n > &\n Reads<E['name']>\n} & { readonly [K in LinkKeys<E>]: NextExpr<LinkOf<E, K>> & Reads<E['name']> }\n\n/** A row, or a change from one row to another, as an invariant is judged over it. */\nexport interface Change {\n readonly after: Row\n /** The row before an update; none for a create, which judges no transition invariant. */\n readonly before?: Row\n}\n\nconst Invariants = Metadata.key<Invariant>('foldkit-entity/invariants', {\n // The same invariant reached twice (two annotated copies combined) is one.\n merge: values => [...new Set(values)],\n summarize: invariant => invariant.id,\n})\n\n/** What a row, or a change, comes to under an Entity's invariants. */\nexport type Judgement =\n | { readonly _tag: 'Valid' }\n | { readonly _tag: 'Invalid'; readonly failures: ReadonlyArray<Invariant> }\n /**\n * Validity is not known: some invariant reads a field the row does not have\n * (`fields`), or calls an operator the table does not run (`operators`, by name).\n */\n | {\n readonly _tag: 'Undecided'\n readonly fields: ReadonlyArray<string>\n readonly operators: ReadonlyArray<string>\n }\n\n/** Whether an invariant reads the row before a write: judged on updates only, and no CHECK. */\nexport const readsBefore = (held: Invariant): boolean => held.before.length > 0\n\n/**\n * An invariant as declared: the step that attaches it to its Entity, carrying\n * its id and, once attached, that Entity's name, so a refusal is matched\n * against the declaration rather than a string spelled again\n * (`Refusal.isInvalidBy(refusal, reservedWithinQuantity)`). An id is unique\n * only within an Entity, so the name is part of what a refusal names; reading\n * it before the declaration is attached throws.\n */\nexport interface DeclaredInvariant<E extends AnyEntity> {\n (entity: E): E\n readonly id: string\n readonly entity: string\n}\n\nconst fail = (entity: AnyEntity, message: string): never => {\n throw new Error(`[foldkit-entity] Entity.invariant on ${entity.name}: ${message}`)\n}\n\n/** How an invariant is declared: what `build` returns over the rows, and what a failure says. */\ntype Build<E extends AnyEntity> = (rows: {\n readonly before: BeforeRow<E>\n readonly after: AfterRow<E>\n}) => Predicate & Reads<E['name']>\n\ninterface Options<E extends AnyEntity> {\n readonly message: string\n readonly path?: ReadonlyArray<(keyof E['fields'] & string) | LinkKeys<E>>\n}\n\n/** The invariant `build` declares over `entity`'s rows, refused where it could judge nothing. */\nconst declareOn = <E extends AnyEntity>(\n entity: E,\n id: string,\n build: Build<E>,\n options: Options<E>,\n): Invariant => {\n const fields = entity.fields as Readonly<Record<string, E['fields'][string]>>\n const relations = entity.relations as Readonly<Record<string, EntityMember>>\n // A `one` relation reads as the id it points at; a `many` holds no one value.\n const links = Object.values(relations).flatMap(member => {\n if (member._tag !== 'Relation' || member.cardinality !== 'one') return []\n return [member as OneRelation]\n })\n const nexts = [\n ...Object.entries(fields).map(([key, field]) => [key, Expr.next(field)] as const),\n ...links.map(link => [link.key, Expr.next(link)] as const),\n ]\n const after = Object.fromEntries(nexts) as unknown as AfterRow<E>\n // Before a write, each is what its `after` reads after it: the same operand, unmoved.\n const before = Object.fromEntries(\n nexts.map(([key, next]) => [key, next.field]),\n ) as unknown as BeforeRow<E>\n const predicate = build({ before, after }) as Predicate\n // `where` refuses a predicate over another Entity, which the type allows when it is unmarked.\n const body = Query.from(entity).pipe(Query.where(predicate))\n const dependencies = Query.dependencies(body)\n if (dependencies.inputs.length > 0) {\n fail(entity, `\"${id}\" reads the input ${dependencies.inputs.join(', ')}; it judges stored rows`)\n }\n const beforeReads = dependencies.predicate.map(field => field.key)\n const afterReads = dependencies.next.map(field => field.key)\n // Reading the row before alone, it says which rows a write may start from: a write's `when`.\n // Judged as an invariant, a create would skip it and a repair would be refused by it.\n if (afterReads.length === 0) {\n fail(entity, `\"${id}\" reads no field of \\`after\\`; what a write may start from is its \\`when\\``)\n }\n const path = options.path ?? [...new Set([...afterReads, ...beforeReads])]\n for (const key of path) {\n if (!Object.hasOwn(fields, key) && !links.some(link => link.key === key))\n fail(entity, `\"${id}\"'s path names \"${key}\", neither a field nor a one relation`)\n }\n return Object.freeze({\n id,\n entity: entity.name,\n predicate,\n message: options.message,\n path: Object.freeze([...path]),\n before: Object.freeze(beforeReads),\n after: Object.freeze(afterReads),\n })\n}\n\n/**\n * Declares what every stored row, or every change of one, must hold:\n * `Entity.invariant('reservedWithinQuantity', ({ after }) =>\n * Expr.lte(after.reserved, after.quantity), { message })` over the row a\n * write leaves, or with `before` too over the change an update makes.\n * Refused where it is declared: an id declared twice, a predicate over another\n * Entity, one reading an input or nothing of `after` (that is a `when`), a path\n * naming no field.\n */\nexport const invariant = <E extends AnyEntity>(\n id: string,\n build: Build<E>,\n options: Options<E>,\n): DeclaredInvariant<E> => {\n let attached: string | undefined\n const declared = (entity: E): E => {\n if (id.length === 0) fail(entity, 'an invariant needs an id')\n if (attached !== undefined && attached !== entity.name)\n fail(entity, `\"${id}\" is declared on ${attached} already: declare it again for this Entity`)\n if (invariantsOf(entity).some(held => held.id === id)) fail(entity, `\"${id}\" is declared twice`)\n const held = declareOn(entity, id, build, options)\n attached = entity.name\n return remake(entity, {\n metadata: Metadata.combine([entity.metadata, Invariants.of(held)]),\n }) as E\n }\n return Object.defineProperties(declared, {\n id: { value: id, enumerable: true },\n entity: {\n enumerable: true,\n get: () => {\n if (attached === undefined) {\n throw new Error(\n `[foldkit-entity] Entity.invariant \"${id}\" names no Entity until it is attached to one`,\n )\n }\n return attached\n },\n },\n }) as DeclaredInvariant<E>\n}\n\nconst ofCases = new WeakMap<EntityIdentity<string>, ReadonlyArray<Invariant>>()\n\n/**\n * Each case's invariant of a variant Entity (`variant_Available`): a field\n * of its own is held, and one of another case is null. Built when first\n * read, so declaring variants reaches no expression code.\n */\nconst caseInvariants = (identity: EntityIdentity<string>): ReadonlyArray<Invariant> => {\n const base = variantBases.get(identity)\n if (base === undefined) return []\n const known = ofCases.get(identity)\n if (known !== undefined) return known\n const variants = Option.getOrThrow(variantsOf(identity))\n const { name } = base\n const separate = Object.keys(base.fields).filter(\n key => key !== '_tag' && variants.tags.some(tag => !Object.hasOwn(variants.cases[tag]!, key)),\n )\n const built = variants.tags.flatMap(tag => {\n const own = variants.cases[tag]!\n const reads = separate.filter(key => !Object.hasOwn(own, key) || !storesNull(own[key]!))\n if (reads.length === 0) return []\n const held = reads.filter(key => Object.hasOwn(own, key))\n const foreign = reads.filter(key => !Object.hasOwn(own, key))\n return [\n declareOn<AnyEntity>(\n base,\n `variant_${tag}`,\n ({ after }) => {\n const row = after as Readonly<Record<string, NextExpr<unknown>>>\n const checks = [\n ...held.map(key => Expr.isNotNull(row[key]!)),\n ...foreign.map(key => Expr.isNull(row[key]!)),\n ]\n return Expr.or(\n Expr.not(Expr.eq(row._tag!, tag)),\n Expr.and(checks[0]!, ...checks.slice(1)),\n )\n },\n {\n message: `A ${name} that is ${tag} ${[\n ...(held.length > 0 ? [`holds ${held.join(', ')}`] : []),\n ...(foreign.length > 0 ? [`holds none of ${foreign.join(', ')}`] : []),\n ].join(' and ')}`,\n path: reads,\n },\n ),\n ]\n })\n ofCases.set(identity, built)\n return built\n}\n\n/** The Entity's invariants, in the order they were declared. */\nexport const invariantsOf = (entity: AnyEntity): ReadonlyArray<Invariant> => {\n const cases = caseInvariants(entity.identity)\n const declared = Invariants.get(entity.metadata)\n return cases.length === 0 ? declared : [...cases, ...declared]\n}\n\n/** `Entity.judge` against invariants already read, such as those a database binding keeps. */\nexport const judgeAgainst = (\n invariants: ReadonlyArray<Invariant>,\n change: Change,\n operators: MemoryOperators = kernelOperators,\n): Judgement => {\n const missing = new Set<string>()\n const unrun = new Set<string>()\n const failures: Array<Invariant> = []\n const { after, before } = change\n for (const held of invariants) {\n // A create has no row before, so a transition invariant has nothing to judge.\n if (readsBefore(held) && before === undefined) continue\n const absent = [\n ...held.after.filter(key => !Object.hasOwn(after, key)),\n ...held.before.filter(key => !Object.hasOwn(before ?? {}, key)),\n ]\n if (absent.length > 0) absent.forEach(key => missing.add(key))\n else {\n try {\n if (truthOver(held.predicate, before ?? {}, {}, after, operators) !== true) {\n failures.push(held)\n }\n } catch (error) {\n // An operator this table does not run is a judgement it cannot make, as a\n // field the row lacks is: a form passes it, and a server's checks refuse to\n // start without the operator (expr-operations-DESIGN §5.6).\n if (!(error instanceof OperatorMissingError)) throw error\n unrun.add(error.named)\n }\n }\n }\n if (failures.length > 0) return { _tag: 'Invalid', failures }\n if (missing.size > 0 || unrun.size > 0) {\n return { _tag: 'Undecided', fields: [...missing], operators: [...unrun] }\n }\n return { _tag: 'Valid' }\n}\n\n/**\n * A row, or a change, under every invariant (each row as the store holds it,\n * encoded): valid only when each is true. SQL's unknown, from a null, fails\n * one, as a `WHERE` drops the row; a field a row does not have leaves it\n * undecided, never valid. Without `before` (a create), transition invariants\n * are not judged.\n */\nexport const judge = (\n entity: AnyEntity,\n change: Change,\n operators: MemoryOperators = kernelOperators,\n): Judgement => judgeAgainst(invariantsOf(entity), change, operators)\n\n/**\n * The row an input's value describes, judged under its Entity's state\n * invariants: each key mapped to a field, encoded as the store holds it, and\n * each mapped to a `one` relation as the id it points at. An\n * invariant over a field the input does not set (an `Option` holding nothing, a\n * key left out) is undecided, so a partial input is never called valid on its\n * account. It has no row before, so it judges no transition.\n */\nexport const judgeInput = (\n input: EntityInput<AnyEntity, any, any>,\n value: Readonly<Record<string, unknown>>,\n operators: MemoryOperators = kernelOperators,\n): Judgement => {\n const invariants = invariantsOf(input.entity)\n if (invariants.length === 0) return { _tag: 'Valid' }\n const members = input.members as Readonly<Record<string, InputMember>>\n const row: Record<string, unknown> = {}\n for (const [key, member] of Object.entries(members)) {\n if (!Object.hasOwn(value, key)) continue\n // A `one` relation's key holds the id it points at: the row holds that id, or null.\n if (member._tag === 'RelationInput' && member.relation.cardinality === 'one') {\n const given = value[key]\n const id = Option.isOption(given) ? Option.getOrUndefined(given) : given\n if (id === null || typeof id === 'string') put(row, member.relation.key, id)\n continue\n }\n if (member._tag !== 'Field') continue\n const encode = Schema.encodeUnknownOption(\n member.schema as unknown as Schema.Codec<unknown, unknown>,\n )\n const given = value[key]\n const held = Option.isOption(given) ? given : Option.fromUndefinedOr(given)\n // The value as the field holds it: itself for a field typed `Option`, else what it holds.\n // One the field cannot hold is no row the store would keep, so it decides nothing here.\n const stored = Option.orElse(encode(given), () => Option.flatMap(held, encode))\n Option.map(\n Option.flatMap(held, () => stored),\n encoded => put(row, member.key, encoded),\n )\n }\n return judgeAgainst(invariants, { after: row }, operators)\n}\n\n/**\n * The Entity's state invariants as an Effect Schema check over its row type:\n * each failure at its path, with its message. The value is encoded first,\n * field by field, so it is judged as the store would hold it. Refused where it\n * is made when an invariant calls an operator `operators` does not run: such a\n * check would pass every value.\n */\nexport const check = <E extends AnyEntity>(\n entity: E,\n options: { readonly operators?: MemoryOperators | undefined } = {},\n): SchemaAST.Filter<Schema.Schema.Type<E['schema']>> => {\n const predicates = invariantsOf(entity).map(held => held.predicate)\n // The judge runs every operation an invariant reads; an operator alone can be missing.\n const missing = Expr.unsupported(predicates, {\n operations: dependenciesOf(...predicates).operations,\n operators: options.operators ?? kernelOperators,\n })\n if (missing.length > 0) {\n throw new Error(\n `[foldkit-entity] Entity.check of ${entity.name}: its invariants call ${missing.join(', ')}, which the operator table does not run; pass one that does as \\`operators\\``,\n )\n }\n return Schema.makeFilter(value => {\n const fields = entity.fields as Readonly<Record<string, AnyField>>\n const decoded = value as Readonly<Record<string, unknown>>\n const row: Record<string, unknown> = {}\n for (const [key, field] of Object.entries(fields)) {\n if (!Object.hasOwn(decoded, key)) continue\n put(\n row,\n key,\n Schema.encodeUnknownSync(field.schema as unknown as Schema.Codec<unknown, unknown>)(\n decoded[key],\n ),\n )\n }\n const judged = judge(entity, { after: row }, options.operators)\n return Match.valueTags(judged, {\n Invalid: ({ failures }) =>\n failures.flatMap((failure): ReadonlyArray<Schema.FilterIssue> =>\n failure.path.length === 0\n ? [failure.message]\n : failure.path.map(key => ({ path: [key], issue: failure.message })),\n ),\n Valid: () => undefined,\n Undecided: () => undefined,\n })\n })\n}\n"],"mappings":"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"}
|
package/dist/law.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"law.d.ts","names":[],"sources":["../src/law.ts"],"mappings":";;;
|
|
1
|
+
{"version":3,"file":"law.d.ts","names":[],"sources":["../src/law.ts"],"mappings":";;;KAaK,cAAc,SAAS,cAAc,OAAO,MAAM,OAAO;;YAGlD;;;;;YAMA,MAAM,KAAK;;EAErB;aAAwB,QAAQ,OAAO,OAAO,OAAO;;;EAErD;aAAwB,QAAQ,OAAO,OAAO,OAAO;;;EAErD;aAAuB,QAAQ,OAAO,OAAO,OAAO;;;EAEpD;aACW,QAAQ,OAAO,OAAO,OAAO;aAC7B;aACA,MAAM;;;EAGjB;aACW,QAAQ,OAAO,OAAO,OAAO;aAC7B;aACA,MAAM;;;EAGjB;aACW,QAAQ,OAAO,OAAO,OAAO;aAC7B,OAAO;aACP;;;EAGX;aAAwB,QAAQ,OAAO,OAAO,OAAO;aAAe,MAAM;;;EAE1E;aACW,QAAQ,OAAO,OAAO,OAAO;aAC7B;aACA;;;EAGX;aAA+B,QAAQ,OAAO,OAAO,OAAO;;;;;;;;qBAUjD,gBAAc,OAAA;;;;;YAKf,wBAAwB,eAAe;qBAQtC;EACX;;aAxDgC,QAAA,OAAO,OAAO,OAAO;;EAyDrD;;aAvDgC,QAAA,OAAO,OAAO,OAAO;;EAwDrD;;aAtD+B,QAAA,OAAO,OAAO,OAAO;;EAuDpD;;aA3BuC,QAAA,OAAO,OAAO,OAAO;;;EA6B5D,WAAQ,gBAAiB,OAAQ,SAAgB;;EAGjD,YAAS,gBAAiB,OAAQ,SAAgB;;EAGlD,UAAU,WAAW,cAAc,OAAO,MAAM,YAAY,OAAO,KAAG,OAC7D,SAAS,IAAI,MAAI,sBAEvB;;EAEH,cAAc,WAAW,cAAc,OAAO,MAAM,YAAY,OAAO,KAAG,MAClE,SAAS,IAAI,SAClB;;EAEH,YAAS,wCAAyC,qBAAqB;;;;;;EAOvE,SAAM,KAAQ,KAAG,QAAU,OAAO,QAAM;EAGxC;;;eAzEmB,QAAA,OAAO,OAAO,OAAO;eACtB;eACD,MAAA;;;eAfe,QAAA,OAAO,OAAO,OAAO;;;eAErB,QAAA,OAAO,OAAO,OAAO;;;eAsBrB,QAAA,OAAO,OAAO,OAAO;eAAqB,MAAA;;;eApB3C,QAAA,OAAO,OAAO,OAAO;;;eAGjC,QAAA,OAAO,OAAO,OAAO;eACtB;eACD,MAAA;;;eAUE,QAAA,OAAO,OAAO,OAAO;eACtB,OAAA;eACG;;;eAMF,QAAA,OAAO,OAAO,OAAO;eAClB;eACD;;;eAGkB,QAAA,OAAO,OAAO,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAnBzC,QAAA,OAAO,OAAO,OAAO;eACtB;eACD,MAAA;;;eAfe,QAAA,OAAO,OAAO,OAAO;;;eAErB,QAAA,OAAO,OAAO,OAAO;;;eAsBrB,QAAA,OAAO,OAAO,OAAO;eAAqB,MAAA;;;eApB3C,QAAA,OAAO,OAAO,OAAO;;;eAGjC,QAAA,OAAO,OAAO,OAAO;eACtB;eACD,MAAA;;;eAUE,QAAA,OAAO,OAAO,OAAO;eACtB,OAAA;eACG;;;eAMF,QAAA,OAAO,OAAO,OAAO;eAClB;eACD;;;eAGkB,QAAA,OAAO,OAAO,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6D5D,iBAAc,KAAQ,mBAAiB;;EAMvC,WAAQ,KAAQ,QAAM"}
|