Entity / foldkit-entity
API
| Call | Meaning |
|---|---|
Entity.define(name, struct) | A new Entity with a Field per property. |
Entity.relate(entities, { Owner: { key: Relation.one(Target) } }) | The entities with their relations declared; targets resolve to the returned entities. |
Entity.select(entity, { key: true or Selection }) | A Selection: what was selected (members) and the schema of the result. |
Entity.page(selection, { first, after } or { last, before }) | In a Selection, a many relation read as a page: items, hasNext, hasPrevious. |
Entity.fields(entity, ...keys) | The schemas of those fields, by key, to spread into an input's struct. |
Write.update(input, { id, expect? }) | A declared update of one row: every key the input maps to a field, but the id and the expected revision. |
Write.writes(write) / Write.bind(write, value, keys?) | The fields it may change; the row and values one input writes, encoded as the store holds them. |
Entity.input(entity, struct, mapping?) | Experimental. Which member each key of an operation's input writes. |
Relation.nested(relation, input) | In an input mapping: the key holds the target itself, written through input. |
Entity.selectFor(input) | The Selection of the members an input writes: what an edit screen loads. |
Entity.valuesFor(input, value) | The input values that reproduce a loaded value: fields as they are, refs as ids. |
Entity.derived({ key: Derived.make(schema) }) | Pipe step adding readable, externally supplied members. |
Entity.annotate(metadata) | Pipe step attaching metadata to the Entity. |
Entity.annotateMembers({ key: metadata }) | Pipe step attaching metadata to members by key. |
Entity.same(a, b) | Whether two descriptors are versions of one Entity. |
Selected<typeof selection> | Type: the value a Selection reads (its schema's Type). |
Words.of(schema) | A schema's title and description, each an Option, including a title given before a check. |
Entity.is(value) | Whether a value is an Entity descriptor. |
Expr.eq(left, right) | Two values are the same: a field (or an expression) on the left, and the value on the right, which is typed from it; a predicate may stand where a boolean is wanted. A plain value on the left is a compile error that says so. |
Expr.isNull(field) / Expr.isNotNull(field) | Whether a value is absent; one node, with the answer absence gives flipped. |
Expr.contains(field, search) | Whether text contains text, over a text or nullable-text operand only. Containing the empty string is everything, but a null contains nothing. |
Expr.in(field, among) | Whether a value is one of a list (written out, or an input), each compared as eq compares; SQL's in, an empty list matching nothing. |
Expr.and(a, b, …) / Expr.or(a, b, …) | Every operand holds / at least one does, as SQL's three-valued and and or. At least one operand; a nested one of the same kind is flattened in. |
Expr.not(predicate) | The predicate does not hold; an unknown stays unknown, so a null matches neither side. |
Expr.lt / lte / gt / gte(left, right, { collation? }) | One value orders before or after the other. Numbers as numbers; text only under binary or asciiFold (the field's declared collation, or the one given), and only against a field. |
Expr.whenGiven(input, given => predicate) | A filter applying only when a nullable input is given: or(isNull(input), predicate), the predicate seeing the input as never null. |
Expr.field(field) | One field of one Entity, as a scalar. |
Expr.input(key, schema) | A value the query is given when it runs, as a placeholder. |
Expr.literal(value) | A constant. Comparisons coerce one, so this is rarely written. |
Order.asc(expr, { nulls? }) / Order.desc(expr, { nulls? }) | One term of an ordering, over a field or a scalar. Rows without a value go last ascending and first descending unless nulls says otherwise; every interpreter is told, since databases disagree when it is unsaid. |
Collation.binary / .asciiFold / .locale(name) / .of(collation) | How a text field orders, as member metadata; see above. |
ReadFilter.of(members) / .members(metadata) | Entity metadata: the members a server filters rows by under a rule the client does not run (an authorization rule; foldkit-guard attaches it). A client placing rows in a list fetches the list instead when one changes. Annotations add up. |
Query.placement(query, input) | Placeable, or NotPlaceable with why: whether a client can order as the server does. |
Order.chosen(sort, choices) | The field an input's sort names ({ by, direction }, or null for none), among choices. |
dependenciesOf(...nodes) | The distinct fields, inputs, and operations those expressions use. |
Query.from(entity) | Every row of an Entity: the query each step narrows. |
Query.where(...predicates) | Pipe step keeping the rows those hold for; conjoins with what is there. |
Query.orderBy(...terms) | Pipe step reading in that order; appends after existing terms. |
Query.orderFor(query, input) | The fixed terms it orders by for one input, each chosen order resolved, ending on the id. |
Query.dependencies(query) | What the whole query reads, with its fields also split by role: predicate (can change which rows match) and order (can change where a row sits). |
Query.unsupported(query, supported) | The operations it needs that an interpreter does not run. |
Query.show(query) / Expr.show(node) | The query or expression as readable text, for a person and not for an interpreter. |
Limits
- The identifier is the field named
id; no other field can be declared as it, because Remote keys its store byid. - A Selection has no filtering or ordering, and a page has no total; those belong to the interpreter that fetches.
- Relations reach only the entities of one
Entity.relatecall; relating the result again adds relations but earlier targets keep pointing at the earlier result. target()returns the entity asrelatereturned it. Metadata attached afterwards (CmsPostabove) is on the new descriptor only, so annotate before relating when a target should carry it.- No registry: nothing checks that two different entities share a name.