pyric/rules

Classes

RulesAssertionError

Thrown by assertCase / a runner case’s run() when the simulated decision did not match the case’s expectation. The message is the rendered trace from explainCase, so a test runner surfaces the “why” without extra wiring.

Extends

• Error

Constructors

Constructor

new RulesAssertionError(message: string): RulesAssertionError;

Parameters

Returns

RulesAssertionError

Overrides

Error.constructor

RulesCompileError

Thrown by firestoreRules(source) / rtdbRules(...) when the source cannot compile. Carries the compile-blocking issues on .issues so a caller can surface them without re-parsing.

Extends

• Error

Constructors

Constructor

new RulesCompileError(message: string, issues: RuleIssue[]): RulesCompileError;

Parameters

Returns

RulesCompileError

Overrides

Error.constructor

Properties

RulesUnsupportedError

Thrown by assertCase / a runner case’s run() when the simulator abstained — it hit a feature it does not implement, so neither a pass nor a genuine failure can be asserted. Distinct from RulesAssertionError so a runner can choose to skip rather than fail on a known simulator gap.

Extends

• Error

Constructors

Constructor

new RulesUnsupportedError(message: string): RulesUnsupportedError;

Parameters

Returns

RulesUnsupportedError

Overrides

Error.constructor

Interfaces

CaseResult

The outcome of running one Firestore case through simulate. Never a thrown error — a denied or abstained case is data, not an exception.

Properties

EvaluatedRuleInfo

The DECIDING rule’s source position + sub-expression trace, projected from a TestResult — for BOTH verdicts: the allow rule that granted an ALLOW, or the rule responsible for a DENY. Additive companion to renderLegacyDebugMessages: that flattens the per-rule trace to strings (dropping line and expressionTrace); this preserves the structured detail a UI needs to point at the exact source line and step through the evaluation (“show the work”). Position/trace fields are optional so a partial trace projects honestly.

Properties

Explanation

The structured account of why one Firestore case resolved as it did.

Properties

ExprTraceEntry

One entry in a per-rule expression trace, emitted in evaluation order.

Properties

FirestoreCase

One Firestore rules case: a single request plus the outcome it should produce. Structurally identical to the engine’s TestCase — re-exported here under the public name so callers never reach into the engine seam.

Properties

FirestoreRuleset

Methods

explain()

explain(oneCase: FirestoreCase): Explanation;

The structured account of why one case resolved as it did.

Parameters

Returns

Explanation

lint()

lint(): RuleIssue[];

Structural, security, and budget findings on the compiled ruleset. No parse errors — the source already compiled.

Returns

RuleIssue[]

simulate()

simulate(cases: FirestoreCase[]): SimulationSummary;

Run every case. Never throws on a rule outcome: a denied or abstained case is reported in the returned summary.

Parameters

Returns

SimulationSummary

toJSON()

toJSON(): FirestoreRules;

The parsed ruleset as plain data (the AST).

Returns

FirestoreRules

PathDef

Definition of rules for a single database path.

Properties

PathResolutionEntry

One match block the simulator considered while resolving the request path. Together, PathResolutionTrace.attempts forms a complete picture of “what did the resolver try, and where did each attempt fall apart?” — useful for the agent when a request lands in the default-deny path because no block matched.

Recorded only by the local simulator; the production Test API client doesn’t expose path-resolution internals.

Properties

PathResolutionTrace

Properties

RtdbCase

One Realtime Database rules case. expectation is required so a simulate run can partition cases into passed/failed the same way Firestore does — the RTDB simulator otherwise returns only a raw allow/deny with no notion of an expectation.

Properties

RtdbCaseResult

The outcome of running one RTDB case through simulate.

Properties

RtdbExplanation

Properties

RtdbRulesCheckResult

Properties

RtdbRulesDefinition

Properties

RtdbRulesDocument

The authored RTDB rules artifact defineRtdbRules returns.

Deliberately INERT on the public surface: it exposes no methods. It is a value you author and hand to rtdbRules(), which is the one analysis surface (lint / simulate / explain / toJSON). The brand is type-level only; nothing exists at runtime.

Properties

RtdbRuleset

Methods

explain()

explain(oneCase: RtdbCase): RtdbExplanation;

The structured account of why one case resolved as it did.

Parameters

Returns

RtdbExplanation

lint()

lint(): RuleIssue[];

Structural findings on the compiled ruleset (from check()).

Returns

RuleIssue[]

simulate()

simulate(cases: RtdbCase[]): RtdbSimulationSummary;

Run every case. Never throws on a rule outcome.

Parameters

Returns

RtdbSimulationSummary

toJSON()

toJSON(): RtdbRulesJson;

The compiled rules.json.

Returns

RtdbRulesJson

RtdbRulesFinding

Properties

RtdbSimulationSummary

Properties

RuleEvaluation

Per-rule evaluation entry produced by the local simulator. Each entry corresponds to one allow declaration the simulator evaluated, in source order.

Populated only by the internal simulator (which has the parsed AST in hand); the production Test API client (TestFirestoreRulesHandler) returns an empty trace and surfaces the wire text on TestResult.notes.

Properties

RuleIssue

Properties

RulesetContext

Context passed to the callback overload of ruleset().

Properties

SchemaRulesResult

Properties

SimulationSummary

Aggregate of a simulate(cases) run. Counts partition the cases: passed + failed + unsupported === cases.length.

Properties

Type Aliases

Expr

type Expr = string;

Type alias for RTDB rule expression strings.

FirestoreMethod

type FirestoreMethod = typeof FIRESTORE_METHODS[number];

RtdbRulesFindingRule

type RtdbRulesFindingRule = ".read" | ".write" | ".validate" | "ruleset";

RtdbRulesJson

type RtdbRulesJson = {
  rules: Record<string, unknown>;
};

Properties

RtdbRulesSimulationAuth

type RtdbRulesSimulationAuth =
  | string
  | {
  token?: Record<string, unknown>;
  uid: string;
}
  | null;

RtdbRulesSimulationInput

type RtdbRulesSimulationInput = Omit<SimulationInput, "auth" | "mockData"> & {
  auth?: RtdbRulesSimulationAuth;
  data?: Record<string, unknown>;
  mockData?: Record<string, unknown>;
};

Type Declaration

auth?

optional auth: RtdbRulesSimulationAuth;

data?

optional data: Record<string, unknown>;

mockData?

optional mockData: Record<string, unknown>;

RuleIssueOrigin

type RuleIssueOrigin = "parse" | "validate" | "lint";

The stage that produced the issue.

• parse — the source did not parse; nothing downstream ran.
• validate — a structural/security finding on a parsed ruleset.
• lint — a budget/quality/hallucination warning.

RuleIssueSeverity

type RuleIssueSeverity = "error" | "warning" | "info";

Ordered by decreasing urgency. info is advisory.

Segment

type Segment =
  | string
  | {
  $: string;
};

A path segment: string for literal, { $: name } for path variable.

Variables

all()

const all: (...exprs: Expr[]) => Expr;

All conditions must be true (AND).

Parameters

Returns

Expr

allow()

const allow: () => Expr;

Always allow (true). Readable alias for always().

Returns

Expr

always()

const always: () => Expr;

Always allow (true).

Returns

Expr

any()

const any: (...exprs: Expr[]) => Expr;

At least one condition must be true (OR).

Parameters

Returns

Expr

AUTH_UID

const AUTH_UID: Segment;

auth.uid as a comparison value (unquoted in expressions)

authenticated()

const authenticated: () => Expr;

Returns

Expr

dataExists()

const dataExists: (path?: string) => Expr;

Check if data exists at current node or a child path

Parameters

Returns

Expr

dataParentVal()

const dataParentVal: (depth: number, field: string) => Expr;

Navigate up from data snapshot, then read a child field’s value

Parameters

Returns

Expr

dataVal()

const dataVal: (path?: string) => Expr;

Read data value at current node or a child path (pre-write state)

Parameters

Returns

Expr

deny()

const deny: () => Expr;

Always deny (false).

Returns

Expr

eq()

const eq: (left: Expr, right: CompareValue) => Expr;

Strict equality: left === right (right is a literal value or runtime ref)

Parameters

Returns

Expr

expr()

const expr: (raw: string) => Expr;

Create an Expr from a raw expression string.

Parameters

Returns

Expr

fieldEnum()

const fieldEnum: (field: string, values: string[]) => Expr;

Field must be one of the allowed string values

Parameters

Returns

Expr

fieldIsBoolean()

const fieldIsBoolean: (field: string) => Expr;

Field must be a boolean

Parameters

Returns

Expr

fieldIsNumber()

const fieldIsNumber: (field: string) => Expr;

Field must be a number

Parameters

Returns

Expr

fieldIsString()

const fieldIsString: (field: string) => Expr;

Field must be a string

Parameters

Returns

Expr

fieldOwnerOnly()

const fieldOwnerOnly: (field: string) => Expr;

Only the field owner (auth.uid === data.child(field).val()) can access

Parameters

Returns

Expr

gt()

const gt: (left: Expr, right: number) => Expr;

Greater than: left > right

Parameters

Returns

Expr

hasChild()

const hasChild: (field: string) => Expr;

Incoming data must have a specific child field

Parameters

Returns

Expr

hasChildren()

const hasChildren: () => Expr;

Incoming data must be an object with at least one child

Returns

Expr

hasRole()

const hasRole: (segments: Segment[], role: string) => Expr;

Cross-path role check via root lookup

Parameters

Returns

Expr

immutable()

const immutable: (field: string) => Expr;

Field can be set on creation but never changed after

Parameters

Returns

Expr

immutableSelf()

const immutableSelf: () => Expr;

This node’s own value can be set on creation but never changed

Returns

Expr

isMember()

const isMember: (listName: string, pathVarName: string) => Expr;

Cross-path membership check: root.child(list).child($var).child(auth.uid).exists()

Parameters

Returns

Expr

isNew()

const isNew: () => Expr;

Data at this path doesn’t exist yet (creation check)

Returns

Expr

lte()

const lte: (left: Expr, right: number) => Expr;

Less than or equal: left <= right

Parameters

Returns

Expr

neq()

const neq: (left: Expr, right: CompareValue) => Expr;

Strict inequality: left !== right

Parameters

Returns

Expr

newDataExists()

const newDataExists: (path?: string) => Expr;

Check if incoming data exists at current node or a child path

Parameters

Returns

Expr

newDataIs()

const newDataIs: (type: "String" | "Number" | "Boolean") => Expr;

Check incoming data type at current node

Parameters

Returns

Expr

newDataParentExists()

const newDataParentExists: (depth: number, field: string) => Expr;

Navigate up from newData snapshot, then check if a child field exists

Parameters

Returns

Expr

newDataParentVal()

const newDataParentVal: (depth: number, field: string) => Expr;

Navigate up from newData snapshot, then read a child field’s value

Parameters

Returns

Expr

newDataVal()

const newDataVal: (path?: string) => Expr;

Read incoming data value at current node or a child path (post-write state)

Parameters

Returns

Expr

not()

const not: (e: Expr) => Expr;

Negate a condition.

Parameters

Returns

Expr

ownerOrNew()

const ownerOrNew: (field: string) => Expr;

Anyone authenticated can create; only the field owner can edit

Parameters

Returns

Expr

ownField()

const ownField: (field: string) => Expr;

Field-based ownership: auth.uid matches a value stored in a data field

Parameters

Returns

Expr

ownPath()

const ownPath: (pathVar: string) => Expr;

Path-based ownership: auth.uid matches a URL path variable

Parameters

Returns

Expr

pathOwnerOnly()

const pathOwnerOnly: (pathVar: string) => Expr;

Only the path owner (auth.uid === $pathVar) can access

Parameters

Returns

Expr

required()

const required: (...fields: string[]) => Expr;

All specified fields must be present in the incoming data

Parameters

Returns

Expr

rootEquals()

const rootEquals: (segments: Segment[], value: string) => Expr;

Check if a path’s value equals a specific string (via root)

Parameters

Returns

Expr

rootExists()

const rootExists: (segments: Segment[]) => Expr;

Check if a path exists in the database (via root)

Parameters

Returns

Expr

transition()

const transition: (field: string, allowed: [string, string][]) => Expr;

State machine: only allowed transitions on a field

Parameters

Returns

Expr

Functions

assertCase()

Call Signature

function assertCase(result: CaseResult | RtdbCaseResult): void;

Throw when a case result did not pass. A simulator abstention throws RulesUnsupportedError; a genuine expectation mismatch throws RulesAssertionError. Both carry the explainCase trace as their message. Returns void on a passing result.

Parameters

Returns

void

Call Signature

function assertCase(ruleset: FirestoreRuleset, oneCase: FirestoreCase): void;

Simulate one case against a ruleset and throw on a miss — the runner form: for (const c of cases) test(c.description, () => assertCase(ruleset, c)).

Parameters

Returns

void

Call Signature

function assertCase(ruleset: RtdbRuleset, oneCase: RtdbCase): void;

Throw when a case result did not pass. A simulator abstention throws RulesUnsupportedError; a genuine expectation mismatch throws RulesAssertionError. Both carry the explainCase trace as their message. Returns void on a passing result.

Parameters

Returns

void

Call Signature

function assertCase(source: string, oneCase: FirestoreCase): void;

Convenience: compile Firestore source and assert one case against it.

Parameters

Returns

void

bytes()

function bytes(input: string | Uint8Array<ArrayBufferLike>): Bytes;

A bytes value.

• string → UTF-8 encoded
• Uint8Array → used verbatim

Parameters

Returns

Bytes

defineRtdbRules()

function defineRtdbRules(definition: RtdbRulesDefinition): RtdbRulesDocument;

Parameters

Returns

RtdbRulesDocument

duration()

function duration(value: number, unit?: string): Duration;

A duration value. unit is one of the Firestore duration units ('w' | 'd' | 'h' | 'm' | 's' | 'ms' | 'ns'); defaults to seconds.

Parameters

Returns

Duration

explainCase()

function explainCase(result: CaseResult | RtdbCaseResult): string;

Render a case result as a human-readable trace. The single sanctioned trace renderer — used as the message of the error assertCase throws, and available directly for logging a result without asserting.

Parameters

Returns

string

firestoreRules()

function firestoreRules(source: string): FirestoreRuleset;

Compile Firestore rules source into a deep, safe-by-default handle.

Parameters

Returns

FirestoreRuleset

Throws

when the source does not parse. The thrown error carries the compile-blocking issues on .issues.

flip()

function flip(marks: string[]): string;

Turn flip: validates a turn field alternates between marks. First mark is the initial value on creation. Supports 2+ players with circular rotation.

Parameters

Returns

string

latlng()

function latlng(lat: number, lng: number): LatLng;

A latlng geographic point.

Parameters

Returns

LatLng

lint()

function lint(source: string): RuleIssue[];

Lint Firestore rules source. Accepts anything — including empty or syntactically broken source — and always returns an issue list.

Parameters

Returns

RuleIssue[]

reference()

function reference(path: string): Reference;

A reference to a document, by its path (e.g. "users/alice").

Parameters

Returns

Reference

rtdbRules()

function rtdbRules(input: RtdbRulesInput): RtdbRuleset;

Build a deep handle on a Realtime Database ruleset from a definition, a compiled document, or compiled { rules } JSON.

Parameters

Returns

RtdbRuleset

ruleset()

function ruleset(input:
  | Record<string, PathDef>
  | (ctx: RulesetContext) => void): RtdbNode;

Compile a declarative rules definition into an environment-independent tree.

Parameters

Returns

RtdbNode

schemaRules()

function schemaRules(schema: ZodObject<any>, fieldConstraints?: Record<string, Expr[]>): SchemaRulesResult;

Generate RTDB validate rules from a Zod object schema. Optional fieldConstraints are AND-composed with the schema type check.

Parameters

Returns

SchemaRulesResult

serverTimestamp()

function serverTimestamp(): {
};

The server-timestamp sentinel — the case-data equivalent of FieldValue.serverTimestamp(). The simulator resolves it to the request time, so a rule comparing data.createdAt == request.time sees a match.

Returns

{
}

timestamp()

function timestamp(input:
  | string
  | number
  | {
  nanos?: number;
  seconds: number;
}): Timestamp;

A Firestore timestamp value.

• number → milliseconds since the epoch
• string → ISO-8601
• object → explicit { seconds, nanos }

Parameters

Returns

Timestamp

turnGuard()

function turnGuard(
   turnField: string,
   players: Record<string, string>,
   statusField?: string,
   playingValue?: string): string;

Turn enforcement: only the current turn’s player can write. Uses data (pre-write) for the turn check — NOT newData.

Parameters

Returns

string

vector()

function vector(values: readonly number[]): Vector;

A vector value from its numeric components.

Parameters

Returns

Vector

winCheckHelper()

function winCheckHelper(
   mark: string,
   lines: number[][],
   boardPath?: string): string;

Win check helper: validates a boolean field against winning lines on a board. If true, at least one winning line must exist. If false, no winning line can exist. Uses the “client claims, rules verify” pattern.

Parameters

Returns

string