Write Realtime Database rules in TypeScript
Realtime Database support is still incomplete. Check the generated conformance reference for the exact supported surface before depending on it.
Realtime Database rules are strings inside a JSON tree. Pyric lets you write them as TypeScript instead: typed builders compose into expressions, the expressions assemble into a ruleset, and the ruleset checks itself, simulates requests, and compiles to the exact JSON Firebase deploys. A typo becomes a compile error instead of a production surprise.
Define the rules in code
import {
rtdbRules, defineRtdbRules,
authenticated, ownerOrNew, immutable,
} from 'pyric/rules';
const rules = rtdbRules(defineRtdbRules({
paths: {
'/notes/$noteId': {
read: authenticated(),
write: ownerOrNew('ownerId'),
validate: immutable('createdAt'),
},
},
}));
defineRtdbRules builds the ruleset; rtdbRules wraps it in a handle that lints, simulates, and compiles. $noteId is a real wildcard. ownerOrNew('ownerId') compiles to the signed-in-and-owner-or-new expression you would have written by hand, and immutable('createdAt') pins a field after creation. Every builder’s output is pinned by tests, so what you compose is what deploys.
Check it before anything runs
const issues = rules.lint();
// []
lint() parses and validates every expression in the tree and returns each problem as an issue with a code, a severity, and the path it applies to. A definition that cannot compile comes back as a COMPILE_ERROR. rtdbRules also takes the compiled { rules } JSON, and lint() on it returns the same issues as lint() on the definition it came from. No deploy, no network.
Simulate a request
const summary = rules.simulate([
{
description: 'the owner edits their note',
expectation: 'ALLOW',
operation: 'write',
path: '/notes/n1',
auth: 'alice',
data: { notes: { n1: { ownerId: 'alice', createdAt: 1 } } },
newData: { ownerId: 'alice', createdAt: 1, title: 'edited' },
},
{
description: 'another user cannot edit it',
expectation: 'DENY',
operation: 'write',
path: '/notes/n1',
auth: 'mallory',
data: { notes: { n1: { ownerId: 'alice', createdAt: 1 } } },
newData: { ownerId: 'alice', createdAt: 1, title: 'edited' },
},
]);
// summary.passed === 2
The simulator runs in-process against the same grammar the sandbox enforces. data is the database tree before the write, from the root; newData is the value written at path. auth: 'alice' is shorthand for { uid: 'alice', token: {} }. Each case result carries the decision, whether it passed, and the matchedPath and matchedRule that decided it.
A case can describe three more kinds of request:
- A scalar write:
newDatais any JSON value, so{ operation: 'write', path: '/scores/alice', newData: 5 }isset(ref, 5). - A multi-path update:
operation: 'update'takesnewDataas the patch, keyed by paths relative topath, such as{ operation: 'update', path: '/', newData: { 'rooms/r1/title': 'x', 'rooms/r2/title': 'y' } }. Every written path is judged against the tree the whole update produces, and the case isDENYwhen any path is denied.matchedPathnames the path that decided. - A query read:
queryon areadcase sets the membersquery.*rules read,orderByChild,orderByKey,orderByValue,equalTo,startAt,endAt,limitToFirstandlimitToLast. A rule such asquery.orderByChild == 'owner' && query.equalTo == auth.uidisALLOWfor a case that carries that query andDENYfor the same read without it.
The same fields work in rtdb_simulate_access and rules.simulate (data, query, and operation: 'update'), and pyric verify replays captured updates, scalar writes and query reads against candidate rules.
Ship the JSON
import { writeFileSync } from 'node:fs';
writeFileSync('database.rules.json', JSON.stringify(rules.toJSON(), null, 2));
# or: pyric database rules generate
pyric rules lint --service database --rules-file database.rules.json
firebase deploy --only database
toJSON() emits the { rules: ... } document Firebase expects. Generate or write that file locally (pyric database rules generate), then ship it with firebase-tools (or the Console) using the path your firebase.json points at.
The CLI checks the JSON file itself, so CI can gate on it without TypeScript in the loop:
pyric rules lint --service database --rules-file database.rules.jsonprints every issue, errors and warnings, the same listrtdbRules(json).lint()returns for the file’s contents. It exits2when any issue is an error and0otherwise. Without--rules-file, it lints the rules the sandbox is running.pyric database rules validate database.rules.jsonprints the error findings only. It exits2when there is one or when the file is not rules JSON,1when the file can’t be read, and0otherwise.pyric rules simulate --service database --rules-file database.rules.json --operation read --path /notes/n1evaluates one request against the file.
Compare compiled rules with the rules you wrote by hand
When you move hand-written rules to TypeScript, the compiled JSON spells the same rules differently: auth != null where you wrote auth.uid !== null, child('a').child($id) where you wrote child('a/' + $id). diffRtdbRules with ignoreEquivalent reports only the rules that can decide differently:
import { readFileSync } from 'node:fs';
import { diffRtdbRules, canonicalRtdbExpression } from 'pyric/rules';
const handWritten = JSON.parse(readFileSync('legacy/database.rules.json', 'utf8')).rules;
const compiled = rules.toJSON().rules;
diffRtdbRules(handWritten, compiled); // every rule whose text differs
diffRtdbRules(handWritten, compiled, { ignoreEquivalent: true }); // only rules that can decide differently
// → [{ path, kind: '.read' | '.write' | '.validate' | '.indexOn', change: 'added' | 'removed' | 'changed', deployed?, local? }]
canonicalRtdbExpression("$uid === auth.uid"); // "$uid == auth.uid"
canonicalRtdbExpression("auth.uid !== null"); // "!(auth == null)"
A changed entry keeps both expressions exactly as written. Without the option the diff compares text.
Two expressions are equivalent when their canonical texts are equal. The canonical form applies only rewrites that cannot change a decision, errors included (a rule that errors fails, and || or ! does not rescue it):
| Treated as the same | Why |
|---|---|
whitespace, grouping parentheses, a && (b && c) and a && b && c | parentheses only shape the tree; && and || evaluate left to right either way |
"a" and 'a', for a string literal written without a backslash | the same string; a literal with any escape ('\d', '\u0041') keeps its spelling, since production’s reading of most escapes has not been observed |
=== and ==, !== and != | RTDB compares without type conversion in both |
auth.uid == null and auth == null | auth is null exactly when signed out, and a signed-in auth always has a uid |
child('a/b/' + $id + '/c') and child('a').child('b').child($id).child('c') | a $ variable is exactly one key, and child() reads / as a separator |
a != b and !(a == b) | both fail on the same inputs; otherwise == gives a boolean |
a == b and b == a | equality is symmetric; operands that could fail other than with a rule error, or that index into an array, keep their order |
Deliberately not treated as the same: a concatenated part that is not a string literal or a $ variable, auth.uid included (child('m/' + auth.uid) is not child('m').child(auth.uid), because production has not been observed reading a uid such as /x or a//b with empty segments the same way in both forms); a literal glued to a variable ('user_' + $id) or written with an escape; empty segments and key-invalid characters in a path; the order of && and || operands; >= and >; double negation; and arithmetic or constant folding. A rule that falls in one of those is reported as changed, so read those entries yourself.
Turn enforcement, from a deployed game
This turn-enforcement example is built from the same parts:
import {
ruleset, deny, any, isNew, authenticated,
turnGuard, flip, winCheckHelper,
} from 'pyric/rules';
const LINES = [[0,1,2],[3,4,5],[6,7,8],[0,3,6],[1,4,7],[2,5,8],[0,4,8],[2,4,6]];
const game = ruleset({
'/': { read: deny(), write: deny() },
'/games/$gameId': {
read: authenticated(),
write: any(isNew(), turnGuard('currentTurn', { X: 'playerX', O: 'playerO' }, 'status', 'playing')),
children: {
'/currentTurn': { validate: flip(['X', 'O']) },
'/xWins': { validate: winCheckHelper('X', LINES) },
'/oWins': { validate: winCheckHelper('O', LINES) },
},
},
});
Three constraints carry the whole game. turnGuard reads stored state, never the incoming write, so a player cannot hand themselves the turn. flip makes turn order a validation rule. And winCheckHelper verifies a win claim against the actual board, so the winner field only accepts the truth.
And from an agent
An agent authors and checks the same way you do: lint and simulate locally (pyric rules lint --service database, pyric rules simulate --service database, or rtdb_simulate_access against the connected sandbox), generate JSON with pyric database rules generate, then ship with firebase-tools. See the RTDB task in Work with an agent.
Where to go next
The full builder catalog, with the exact expression each one produces, is in the constraints reference. For matches, turns, results, counters, presence, rate limits and validated shapes, compose the RTDB rules standard library instead of writing the expressions yourself. For the data side of RTDB, see Sync realtime data.