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:

ts
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
// @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:

ts
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.isNull

Use Expr.implies(a, b) (equivalent to Expr.or(Expr.not(a), b)) when a rule constrains only rows matching condition a:

ts
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:

ts
// `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']
CollationBehaviorSQLitePostgres
Collation.binaryUnicode code point orderBINARYCOLLATE "C"
Collation.asciiFoldASCII letters folded, then code pointNOCASElower(x COLLATE "C")
Collation.locale('en-US')Database locale orderingRefusedServer 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:

ts
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:

ts
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.orderFor appends the Entity's id automatically so ties and cursors remain deterministic.
  • Null placement: Ascending puts nulls last and descending puts nulls first unless { nulls } overrides it.
  • Client placement: Query.placement checks 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.binary or Collation.asciiFold on text sort keys so evaluate, 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:

ts
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.

After relating Entities with Entity.relate, predicates can traverse links in three ways:

ts
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.path follows up to four one relations; a null or guard-hidden link evaluates to null.
  • Expr.exists checks visible pointing rows and always evaluates to true or false in 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:

ts
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:

ts
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.