Entity / Expressions
The expression language
The snippets below continue Post and rows from the first example.
Values: fields, literals, and inputs
A comparison always takes a field on the left and a literal or Expr.input(key, schema) placeholder on the right:
const search = Expr.input('search', Schema.String)
const Found = Query.from(Post).pipe(Query.where(Expr.contains(Post.fields.title, search)), byTitle)
evaluate(Found, { search: 'COMP' }, rows).map(row => row.id) // ['p2', 'p3']
evaluate(Found, { search: '' }, rows).map(row => row.id) // ['p2', 'p1', 'p3']TypeScript checks operand types at the call site:
// @ts-expect-error a title is text, not a number
Expr.eq(Post.fields.title, 42)
// @ts-expect-error the value's type comes from the left, so the field goes first
Expr.eq('Compilers', Post.fields.title)
// @ts-expect-error `contains` searches text
Expr.contains(Post.fields.words, search)Because Expr.input is a symbolic placeholder evaluated later, JavaScript conditionals like search === '' ? a : b inspect the placeholder object rather than the runtime string. Express optional filters with Expr.whenGiven(input, value => predicate) instead. Values compare in their stored representation, so ISO date strings compare as text.
Nulls and three-valued logic
Predicates evaluate to true, false, or unknown. Comparisons against null yield unknown, not(unknown) stays unknown, and only true rows pass a filter:
const early = Expr.lt(Post.fields.publishedAt, 200)
ids(early) // ['p1']
ids(Expr.not(early)) // ['p3'] — p2 (null) is in neither
ids(Expr.or(Expr.isNull(Post.fields.publishedAt), Expr.not(early))) // ['p2', 'p3']
ids(Expr.eq(Post.fields.publishedAt, null)) // [] — use Expr.isNullUse Expr.implies(a, b) (equivalent to Expr.or(Expr.not(a), b)) when a rule constrains only rows matching condition a:
ids(Expr.implies(Expr.lt(Post.fields.words, 1000), Expr.gte(Post.fields.publishedAt, 200))) // ['p2', 'p3']Boolean connectives follow SQL: and absorbs false over unknown, or absorbs true over unknown, and Expr.isNull / Expr.isNotNull always return a definite boolean.
Comparisons and text collations
Expr.lt, lte, gt, and gte compare numbers directly and compare text only when the field or call declares a collation:
// `title` declares Collation.binary: uppercase orders before lowercase.
ids(Expr.gte(Post.fields.title, 'a')) // ['p3']
// Override per comparison: ASCII case-folded, then code point.
ids(Expr.gte(Post.fields.title, 'a', { collation: Collation.asciiFold })) // ['p2', 'p1', 'p3']| Collation | Behavior | SQLite | Postgres |
|---|---|---|---|
Collation.binary | Unicode code point order | BINARY | COLLATE "C" |
Collation.asciiFold | ASCII letters folded, then code point | NOCASE | lower(x COLLATE "C") |
Collation.locale('en-US') | Database locale ordering | Refused | Server only; client skips order |
Comparing text without a collation throws immediately, naming the field. Expr.contains(text, search) folds ASCII case (É stays distinct from é) and escapes % and _ as literal characters. Expr.in(field, list) returns false on an empty list. Express range checks by combining gte and lte with Expr.and.
Sums and differences
Expr.add(a, b) and Expr.sub(a, b) compute numeric sums and differences from fields, inputs, literals, or nested arithmetic:
ids(Expr.lt(Expr.add(Post.fields.words, 200), 1000)) // ['p3']
Expr.show(Expr.sub(Post.fields.words, Expr.input('cut', Schema.Number))) // '(Post.words - $cut)'Arithmetic propagates null on either operand and runs identically across memory, SQLite, and Postgres within standard integer/double bounds (Postgres raises range errors beyond integer limits; non-numeric operands fail type checking).
Sorting with Order
Use Order.asc, Order.desc, or Order.chosen over fields on the Entity:
const Newest = Query.from(Post).pipe(Query.orderBy(Order.desc(Post.fields.publishedAt)))
Query.orderFor(Newest, {}).map(term => `${Expr.show(term.expr)} ${term.direction} nulls ${term.nulls}`)
// ['Post.publishedAt desc nulls first', 'Post.id asc nulls last']
evaluate(Newest, {}, rows).map(row => row.id) // ['p2', 'p3', 'p1']
Query.placement(Newest, {}) // { _tag: 'Placeable' }- Total ordering:
Query.orderForappends the Entity'sidautomatically so ties and cursors remain deterministic. - Null placement: Ascending puts nulls last and descending puts nulls first unless
{ nulls }overrides it. - Client placement:
Query.placementchecks whether the browser can position newly created or edited rows locally (Placeable) or must ask the server (NotPlaceable, for example when ordering by a locale or undeclared text collation). - Text sorting: Declare
Collation.binaryorCollation.asciiFoldon text sort keys soevaluate, SQLite, and Postgres agree.
Context values: Expr.viewer and Expr.now
Expr.viewer(Entity) evaluates to the current caller's ID for that Entity (or null for an unauthenticated visitor), and Expr.now evaluates to the current timestamp in milliseconds:
import { Option } from 'effect'
const Out = Query.from(Post).pipe(Query.where(Expr.lt(Post.fields.publishedAt, Expr.now)), byTitle)
evaluate(Out, {}, rows, { context: { viewer: Option.none(), now: Option.some(200) } }).map(row => row.id)
// ['p1']RemoteServer.make({ viewer }) and Remote.make({ viewer }) supply the viewer context automatically. Missing context throws ContextMissingError, and queries using Expr.now defer list placement to the server clock.
Relations: links, paths, and exists
After relating Entities with Entity.relate, predicates can traverse links in three ways:
const AuthorFields = Entity.define('Author', Schema.Struct({ id: Schema.String, name: Schema.String }))
const CommentFields = Entity.define('Comment', Schema.Struct({ id: Schema.String, body: Schema.String }))
const PostFields = Entity.define(
'Post',
Schema.Struct({ id: Schema.String, title: Schema.String, words: Schema.Number, published: Schema.Boolean }),
).pipe(Entity.annotateMembers({ title: Collation.of(Collation.binary) }))
const { Author, Comment, Post } = Entity.relate(
{ Author: AuthorFields, Comment: CommentFields, Post: PostFields },
{
Post: { author: Relation.one(AuthorFields), editor: Relation.one(AuthorFields, { optional: true }) },
Comment: { post: Relation.one(PostFields), author: Relation.one(AuthorFields) },
},
)
const byTitle = Query.orderBy(Order.asc(Post.fields.title))
// 1. Relation as an operand compares the linked ID.
const Mine = Query.from(Post).pipe(Query.where(Expr.eq(Post.relations.author, Expr.viewer(Author))), byTitle)
// 2. Path traverses a `one` relation (up to 4 hops) to read a target field.
const ByAuthorName = Query.from(Post).pipe(
Query.where(Expr.eq(Expr.path(Post.relations.author, Author.fields.name), Expr.input('name', Schema.String))),
byTitle,
)
// 3. Exists checks if at least one child row matches an optional predicate.
const Discussed = Query.from(Post).pipe(
Query.where(Expr.exists(Comment.relations.post, Expr.eq(Comment.relations.author, Expr.viewer(Author)))),
byTitle,
)Expr.pathfollows up to fouronerelations; anullor guard-hidden link evaluates tonull.Expr.existschecks visible pointing rows and always evaluates totrueorfalsein SQL.- Sorting on relations:
Order.asc(Expr.path(...))throws at definition time; queries sort on the root Entity's own fields. - Cross-row dependencies: Inspect
Query.dependencies(ByAuthorName).reaches(which reports'Post.author.name') to invalidate lists when a related Author changes.
SQL compiles path into a scalar subquery and exists into EXISTS (...) filtered by guard rules; Judge evaluates both over held client rows.
Judging partial client caches with Judge
Because browsers hold only a subset of rows and fields, Judge distinguishes a null field from an unfetched field or uncached target row:
const posts = [
{ id: 'p1', title: 'Notes on the Engine', words: 900, published: true, author: 'a1', editor: null },
{ id: 'p3', title: 'compost', words: 300, published: true, author: 'a2', editor: 'a1' },
]
const page = Held.rows([
{ entity: Post, rows: posts },
{ entity: Author, rows: [{ id: 'a1', name: 'Ada' }], complete: false },
])
const verdict = (id: string) =>
Option.map(page.row(Post, id), row => Judge.query(ByAuthorName, { name: 'Ada' }, row))
verdict('p1') // some({ _tag: 'Known', truth: true })
verdict('p3') // some({ _tag: 'Unknown', reason: 'Author a2 is not held' })Read verdicts with Judge.match. Known verdicts match SQL; Unknown leaves uncertain list updates to the next server query rather than guessing. Short-circuit logic still resolves whenever possible (such as false in an and, or one held matching child in an exists).
Using expressions in invariants, states, writes, and guards
Invariants, Entity.refine states, write when preconditions, and foldkit-guard rules all use the same Expr predicates:
const publishedHasWords = Entity.invariant<typeof Post>(
'publishedHasWords',
({ after }) => Expr.or(Expr.eq(after.published, false), Expr.gt(after.words, 0)),
{ message: 'A published post has words', path: ['words'] },
)
const Checked = Post.pipe(publishedHasWords)
Entity.judge(Checked, {
after: { id: 'p9', title: 'Untitled', words: 0, published: true, author: 'a1', editor: null },
})._tag // 'Invalid'
const Live = Entity.refine(Post, 'Live', { published: true })
evaluate(Query.from(Live).pipe(byTitle), {}, posts).map(row => row.id) // ['p1', 'p3']
const Publish = Mutation.update('Publish', Post, {
set: { published: Schema.Literal(true) },
when: () => Expr.gt(Post.fields.words, 0),
})
Write.reads(Publish.write).map(field => field.key) // ['words']For reusable named predicates across queries and writes, see Operators.