pyric-admin/firestore

Classes

FieldPath

Firebase Admin-compatible field paths and DocumentSnapshot field lookup.

Every local/remote snapshot producer delegates here so validation, dotted string traversal, literal-dot FieldPath segments, and missing-value behavior cannot drift between one-shot, query, transaction, and listener reads.

Constructors

Constructor

new FieldPath(...segments: string[]): FieldPath;

Parameters

Returns

FieldPath

Methods

isEqual()

isEqual(other: FieldPath): boolean;

Parameters

Returns

boolean

toString()

toString(): string;

Returns

string

documentId()

static documentId(): FieldPath;

Returns

FieldPath

Interfaces

AdminDocumentSnapshot

Extended by

• AdminQueryDocumentSnapshot

Properties

Methods

data()

data(): DocumentData;

Returns

DocumentData

get()

get(fieldPath: SnapshotFieldPath): unknown;

Parameters

Returns

unknown

AdminQueryDocumentSnapshot

Extends

• AdminDocumentSnapshot

Properties

Methods

data()

data(): DocumentData;

Returns

DocumentData

Overrides

AdminDocumentSnapshot.data

get()

get(fieldPath: SnapshotFieldPath): unknown;

Parameters

Returns

unknown

Inherited from

AdminDocumentSnapshot.get

AdminQuerySnapshot

Properties

Methods

forEach()

forEach(callback: (snap: AdminQueryDocumentSnapshot) => void): void;

Parameters

Returns

void

AggregateQuerySnapshot

Result of Query.aggregate(spec).get(). .data() returns the computed numbers under the spec’s aliases. Empty-input averages resolve to null to mirror Firestore production behavior (averaging over zero documents has no meaningful number).

Methods

data()

data(): Record<string, number | null>;

Returns

Record<string, number | null>

CollectionReference

Extends

• Query

Properties

Methods

add()

add(data: DocumentData, opts?: OperationOptions): Promise<DocumentReference>;

Parameters

Returns

Promise<DocumentReference>

aggregate()

aggregate(spec: AggregateSpec): Promise<AggregateQuerySnapshot>;

Compute one or more aggregates over the documents matching this query. Mirrors the Admin SDK’s query.aggregate({ … }).get() pattern, collapsed into one call for the simulator (no need to build an AggregateQuery reference type when there’s no remote dispatch).

Each entry in spec is keyed by a caller-chosen alias and resolves to an AggregateField. The returned snapshot exposes the computed numbers under the same aliases via .data().

Where / orderBy clauses ARE applied before aggregation (they narrow the candidate doc set). limit is honored — the aggregate computes against the limited set, matching production semantics.

Parameters

Returns

Promise<AggregateQuerySnapshot>

Inherited from

Query.aggregate

applyFilter()

applyFilter(filter: Filter): Query;

Add a composite filter (leaf, AND, or OR) to the query’s filter stack. Each applyFilter call AND-s with whatever filters are already on the query — same implicit-AND semantics as multiple where() calls. To OR multiple predicates, wrap them with { kind: 'or', filters: [...] } before calling. Backs the modular or() / and() constraints in pyric/firestore.

Parameters

Returns

Query

Inherited from

Query.applyFilter

doc()

doc(id?: string): DocumentReference;

Parameters

Returns

DocumentReference

endCursor()

endCursor(values: unknown[], inclusive: boolean): Query;

Set the end position of the query relative to the orderBy fields. inclusive controls endAt (true) vs endBefore (false).

Parameters

Returns

Query

Inherited from

Query.endCursor

endCursorFromSnapshot()

endCursorFromSnapshot(snapshot: AdminDocumentSnapshot, inclusive: boolean): Query;

Snapshot-based variant of endCursor.

Parameters

Returns

Query

Inherited from

Query.endCursorFromSnapshot

get()

get(opts?: OperationOptions): Promise<AdminQuerySnapshot>;

Parameters

Returns

Promise<AdminQuerySnapshot>

Inherited from

Query.get

limit()

limit(n: number): Query;

Parameters

Returns

Query

Inherited from

Query.limit

limitToLast()

limitToLast(n: number): Query;

Limit from the END of the ordered result. Equivalent to reversing the orderBy, taking n, then re-reversing — the simulator implements it that way. Requires at least one orderBy clause on the query (matches the JS SDK’s runtime contract).

Parameters

Returns

Query

Inherited from

Query.limitToLast

orderBy()

orderBy(field: string, direction?: QueryOrderDirection): Query;

Parameters

Returns

Query

Inherited from

Query.orderBy

startCursor()

startCursor(values: unknown[], inclusive: boolean): Query;

Set the start position of the query relative to the orderBy fields. values corresponds 1:1 with the orderBy clauses on the query (one value per clause); inclusive controls startAt (true) vs startAfter (false). Repeated calls replace the previous cursor — matches production.

Parameters

Returns

Query

Inherited from

Query.startCursor

startCursorFromSnapshot()

startCursorFromSnapshot(snapshot: AdminDocumentSnapshot, inclusive: boolean): Query;

Variant of startCursor that takes a DocumentSnapshot and extracts the cursor values from the snapshot’s data at each orderBy field. Mirrors the JS SDK’s startAt(snapshot) overload and shines for cursor-based pagination (“hand me the next page after this one”). Requires at least one orderBy clause — thrown at call time, not at get-time, so the failure surfaces close to the bug.

Parameters

Returns

Query

Inherited from

Query.startCursorFromSnapshot

where()

where(
   field: string,
   op: QueryWhereFilterOp,
   value: unknown): Query;

Parameters

Returns

Query

Inherited from

Query.where

DocChangesOptions

Options for QuerySnapshot.docChanges. Mirrors Web SDK shape.

Properties

DocumentChange

Properties

DocumentReference

Properties

Methods

collection()

collection(name: string): CollectionReference;

Parameters

Returns

CollectionReference

delete()

delete(opts?: OperationOptions): Promise<void>;

Parameters

Returns

Promise<void>

get()

get(opts?: OperationOptions): Promise<AdminDocumentSnapshot>;

Parameters

Returns

Promise<AdminDocumentSnapshot>

set()

set(data: DocumentData, options?: SetOptions): Promise<void>;

Parameters

Returns

Promise<void>

update()

update(data: DocumentData, opts?: OperationOptions): Promise<void>;

Parameters

Returns

Promise<void>

DocumentSnapshot

Extended by

• QueryDocumentSnapshot

Properties

Methods

data()

data(): DocumentData;

Returns

DocumentData

exists()

exists(): boolean;

Returns

boolean

get()

get(fieldPath: SnapshotFieldPath): unknown;

Field accessor mirroring firebase/firestore’s DocumentSnapshot.get(fieldPath). Dotted paths supported. Missing intermediate keys yield undefined — production behavior; agents commonly chain optional reads.

Parameters

Returns

unknown

Firestore

Extended by

• SandboxFirestore

Methods

batch()

batch(): WriteBatch;

Returns

WriteBatch

collection()

collection(path: string): CollectionReference;

Parameters

Returns

CollectionReference

collectionGroup()

collectionGroup(collectionId: string): Query;

Cross-collection query — returns a Query that scans every document under every collection whose final segment matches collectionId, regardless of position in the path. Matches the Admin SDK’s Firestore.collectionGroup(id) shape.

The returned Query accepts where / orderBy / limit like any other; the simulator gathers all candidate docs first, then applies the constraints in-memory.

Parameters

Returns

Query

doc()

doc(path: string): DocumentReference;

Parameters

Returns

DocumentReference

runTransaction()

runTransaction<R>(fn: (tx: Transaction) => R | Promise<R>, opts?: OperationOptions): Promise<R>;

Type Parameters

Parameters

Returns

Promise<R>

LintWarning

Properties

Query

Extended by

• CollectionReference

Methods

aggregate()

aggregate(spec: AggregateSpec): Promise<AggregateQuerySnapshot>;

Compute one or more aggregates over the documents matching this query. Mirrors the Admin SDK’s query.aggregate({ … }).get() pattern, collapsed into one call for the simulator (no need to build an AggregateQuery reference type when there’s no remote dispatch).

Each entry in spec is keyed by a caller-chosen alias and resolves to an AggregateField. The returned snapshot exposes the computed numbers under the same aliases via .data().

Where / orderBy clauses ARE applied before aggregation (they narrow the candidate doc set). limit is honored — the aggregate computes against the limited set, matching production semantics.

Parameters

Returns

Promise<AggregateQuerySnapshot>

applyFilter()

applyFilter(filter: Filter): Query;

Add a composite filter (leaf, AND, or OR) to the query’s filter stack. Each applyFilter call AND-s with whatever filters are already on the query — same implicit-AND semantics as multiple where() calls. To OR multiple predicates, wrap them with { kind: 'or', filters: [...] } before calling. Backs the modular or() / and() constraints in pyric/firestore.

Parameters

Returns

Query

endCursor()

endCursor(values: unknown[], inclusive: boolean): Query;

Set the end position of the query relative to the orderBy fields. inclusive controls endAt (true) vs endBefore (false).

Parameters

Returns

Query

endCursorFromSnapshot()

endCursorFromSnapshot(snapshot: AdminDocumentSnapshot, inclusive: boolean): Query;

Snapshot-based variant of endCursor.

Parameters

Returns

Query

get()

get(opts?: OperationOptions): Promise<AdminQuerySnapshot>;

Parameters

Returns

Promise<AdminQuerySnapshot>

limit()

limit(n: number): Query;

Parameters

Returns

Query

limitToLast()

limitToLast(n: number): Query;

Limit from the END of the ordered result. Equivalent to reversing the orderBy, taking n, then re-reversing — the simulator implements it that way. Requires at least one orderBy clause on the query (matches the JS SDK’s runtime contract).

Parameters

Returns

Query

orderBy()

orderBy(field: string, direction?: QueryOrderDirection): Query;

Parameters

Returns

Query

startCursor()

startCursor(values: unknown[], inclusive: boolean): Query;

Set the start position of the query relative to the orderBy fields. values corresponds 1:1 with the orderBy clauses on the query (one value per clause); inclusive controls startAt (true) vs startAfter (false). Repeated calls replace the previous cursor — matches production.

Parameters

Returns

Query

startCursorFromSnapshot()

startCursorFromSnapshot(snapshot: AdminDocumentSnapshot, inclusive: boolean): Query;

Variant of startCursor that takes a DocumentSnapshot and extracts the cursor values from the snapshot’s data at each orderBy field. Mirrors the JS SDK’s startAt(snapshot) overload and shines for cursor-based pagination (“hand me the next page after this one”). Requires at least one orderBy clause — thrown at call time, not at get-time, so the failure surfaces close to the bug.

Parameters

Returns

Query

where()

where(
   field: string,
   op: QueryWhereFilterOp,
   value: unknown): Query;

Parameters

Returns

Query

QueryDocumentSnapshot

Production narrows data() to non-undefined here. We follow suit so that agent code calling snap.data().foo doesn’t need a guard for the items inside a QuerySnapshot.docs array.

Extends

• DocumentSnapshot

Properties

Methods

data()

data(): DocumentData;

Returns

DocumentData

Overrides

DocumentSnapshot.data

exists()

exists(): boolean;

Returns

boolean

Inherited from

DocumentSnapshot.exists

get()

get(fieldPath: SnapshotFieldPath): unknown;

Field accessor mirroring firebase/firestore’s DocumentSnapshot.get(fieldPath). Dotted paths supported. Missing intermediate keys yield undefined — production behavior; agents commonly chain optional reads.

Parameters

Returns

unknown

Inherited from

DocumentSnapshot.get

QuerySnapshot

Properties

Methods

docChanges()

docChanges(options?: DocChangesOptions): DocumentChange[];

Per findings section 4: cached by includeMetadataChanges value; throws if called with true when the listener did not subscribe with includeMetadataChanges: true. The Slice 2 implementation produces “all docs added” on the first fire — Slice 3 supplies real diffs.

Parameters

Returns

DocumentChange[]

forEach()

forEach(callback: (snap: QueryDocumentSnapshot) => void): void;

Parameters

Returns

void

RulesMetrics

Properties

SandboxFirestore

Sandbox-extended Firestore handle. Adds three sandbox-only methods on top of the production-shaped Firestore surface:

• SandboxFirestore.setRules — replace the active ruleset for subsequent operations.
• SandboxFirestore.seed — replace stored documents with a fresh seed map (rules are preserved).
• SandboxFirestore.snapshot — capture all stored documents as a path-keyed map.

These have no production analog. They use sandbox vocabulary (setRules, seed, snapshot) deliberately so a reader can’t confuse them with Firebase deployment semantics.

Extends

• Firestore

Methods

batch()

batch(): WriteBatch;

Returns

WriteBatch

Inherited from

Firestore.batch

collection()

collection(path: string): CollectionReference;

Parameters

Returns

CollectionReference

Inherited from

Firestore.collection

collectionGroup()

collectionGroup(collectionId: string): Query;

Cross-collection query — returns a Query that scans every document under every collection whose final segment matches collectionId, regardless of position in the path. Matches the Admin SDK’s Firestore.collectionGroup(id) shape.

The returned Query accepts where / orderBy / limit like any other; the simulator gathers all candidate docs first, then applies the constraints in-memory.

Parameters

Returns

Query

Inherited from

Firestore.collectionGroup

doc()

doc(path: string): DocumentReference;

Parameters

Returns

DocumentReference

Inherited from

Firestore.doc

runTransaction()

runTransaction<R>(fn: (tx: Transaction) => R | Promise<R>, opts?: OperationOptions): Promise<R>;

Type Parameters

Parameters

Returns

Promise<R>

Inherited from

Firestore.runTransaction

seed()

seed(options?: {
  documents?: Record<string, DocumentData>;
}): LintResult;

Replace stored documents with a new seed map. Active rules are preserved. Pass an empty documents map (or omit it) to clear state without touching rules.

Parameters

Returns

LintResult

setRules()

setRules(rules: string): LintResult;

Replace the active ruleset. Returns the lint result so callers can surface warnings; if the source has parse-level errors, the rules are not swapped (consistent with LocalEnvironment.deployRules).

Parameters

Returns

LintResult

snapshot()

snapshot(): Record<string, DocumentData>;

Capture every stored document as a { [path]: data } map. Reads from the live state and is independent of rules.

Returns

Record<string, DocumentData>

SetOptions

Options for DocumentReference.set. Mirrors the modular Web-SDK’s SetOptions shape with pyric’s auth per-op override layered on.

• default (neither flag set) → REPLACE the existing document entirely. Firestore default for set().
• { merge: true } → shallow-merge every top-level field in data into the existing document. Fields not in data are preserved. Rule eval still runs the update clause when the doc exists.
• { mergeFields: [...] } → project data down to just the listed top-level fields, then merge. Other fields in data are ignored; other fields in the existing doc are preserved.

merge and mergeFields are mutually exclusive at the JS-SDK level. We don’t currently enforce the constraint — if both are provided, mergeFields wins (matches the JS SDK’s effective behavior).

Extends

• OperationOptions

Properties

SnapshotMetadata

Mirrors firebase/firestore’s SnapshotMetadata. fromCache is always false (the sandbox has no offline cache). hasPendingWrites transitions (item 3): a local write’s optimistic echo carries true, and the server ack carries false — so includeMetadataChanges has an observable effect matching prod (COMPAT firestore#85).

Properties

SnapshotObserver

Observer form accepted by onSnapshot. Mirrors firebase/firestore’s PartialObserver<T> shape — any subset of the three handlers. complete is accepted for shape parity but never fires in the sandbox: the local listener stream has no terminal state.

Type Parameters

Properties

Transaction

Extended by

• Transaction

Methods

delete()

delete(ref: DocumentReference): Transaction;

Parameters

Returns

Transaction

get()

Call Signature

get(ref: DocumentReference): Promise<AdminDocumentSnapshot>;

Parameters

Returns

Promise<AdminDocumentSnapshot>

Call Signature

get(query: Query): Promise<AdminQuerySnapshot>;

Parameters

Returns

Promise<AdminQuerySnapshot>

set()

set(ref: DocumentReference, data: DocumentData): Transaction;

Parameters

Returns

Transaction

update()

update(ref: DocumentReference, data: DocumentData): Transaction;

Parameters

Returns

Transaction

WriteBatch

Extended by

• WriteBatch

Methods

commit()

commit(opts?: OperationOptions): Promise<void>;

Parameters

Returns

Promise<void>

delete()

delete(ref: DocumentReference): WriteBatch;

Parameters

Returns

WriteBatch

set()

set(ref: DocumentReference, data: DocumentData): WriteBatch;

Parameters

Returns

WriteBatch

update()

update(ref: DocumentReference, data: DocumentData): WriteBatch;

Parameters

Returns

WriteBatch

Type Aliases

AggregateField

type AggregateField =
  | {
  kind: "count";
}
  | {
  field: string;
  kind: "sum";
}
  | {
  field: string;
  kind: "average";
};

Single aggregate definition. Field is required for sum / average, forbidden for count (no field has any meaning when you’re counting rows). Encoded as discriminated union so type errors surface at the call site, not at runtime.

AggregateSpec

type AggregateSpec = Record<string, AggregateField>;

Spec passed to Query.aggregate(...). Aliases become the keys in the returned snapshot’s .data() object.

DocumentChangeType

type DocumentChangeType = "added" | "modified" | "removed";

Filter

type Filter =
  | {
  field: string;
  kind: "where";
  op: WhereFilterOp;
  value: unknown;
}
  | {
  filters: Filter[];
  kind: "and";
}
  | {
  filters: Filter[];
  kind: "or";
};

Composite filter tree for Query.applyFilter. Recursive — and / or carry their own filters array of nested Filters; the leaves are field/op/value triples (kind: 'where').

Mirrors firebase/firestore’s QueryFilterConstraint shape, just as a tagged-union value type (the SDK’s classes carry an _op field; ours is the kind discriminant).

SnapshotFieldPath

type SnapshotFieldPath = string | FieldPath;

SnapshotListenOptions

type SnapshotListenOptions = SnapshotListenerOptions;

Mirrors firebase/firestore’s SnapshotListenOptions. The includeMetadataChanges flag is accepted for API parity but has no observable effect in the sandbox: there’s no offline cache and no pending-writes window, so metadata.fromCache and metadata.hasPendingWrites are always false (snapshot-listeners.ts section 6).

Unsubscribe()

type Unsubscribe = () => void;

Returned from onSnapshot. Calling it deregisters the listener and stops further callback invocations. Idempotent.

Returns

void

Functions

getAdminFirestore()

Call Signature

function getAdminFirestore(ctx: SandboxContext): SandboxFirestore;

Resolve a rules-bypassing Firestore handle for a context — the Pyric Studio admin lens (Gap #2). Same chainable SandboxFirestore surface as getFirestore, but every operation it issues (reads, writes, queries, batches, transactions) SKIPS security-rule evaluation and is treated as ALLOW. This is the modular/chainable-shaped sibling of the path-string sandbox.admin.* bypass — it reuses the exact same LocalEnvironment bypass execution path (bypassRules on the op), rather than reimplementing it.

Storage preconditions still apply (a create on an existing doc still fails already-exists, matching real Firestore admin), and the same request/write events fire + listeners wake, so the change shows up live and on the traffic log (stamped as an admin-bypass read/write).

Use for “edit anything as admin” surfaces (Studio F2). For rules-applied impersonation (“act as this user”), use getFirestore(sandbox.withAuth({ uid })) instead — that path is unchanged.

Parameters

Returns

SandboxFirestore

Example

import { initializeSandbox } from 'pyric/sandbox';
import { getFirestore, getAdminFirestore } from 'pyric-admin/firestore';

const sandbox = initializeSandbox();
getFirestore(sandbox.withAuth(null)).setRules('...deny everything...');

// Denied under rules:
await getFirestore(sandbox.withAuth({ uid: 'alice' }))
  .doc('locked/x').set({ a: 1 }); // throws permission-denied

// Bypasses rules:
await getAdminFirestore(sandbox).doc('locked/x').set({ a: 1 }); // ok

Call Signature

function getAdminFirestore(sandbox: Sandbox): SandboxFirestore;

Resolve a rules-bypassing Firestore handle for a context — the Pyric Studio admin lens (Gap #2). Same chainable SandboxFirestore surface as getFirestore, but every operation it issues (reads, writes, queries, batches, transactions) SKIPS security-rule evaluation and is treated as ALLOW. This is the modular/chainable-shaped sibling of the path-string sandbox.admin.* bypass — it reuses the exact same LocalEnvironment bypass execution path (bypassRules on the op), rather than reimplementing it.

Storage preconditions still apply (a create on an existing doc still fails already-exists, matching real Firestore admin), and the same request/write events fire + listeners wake, so the change shows up live and on the traffic log (stamped as an admin-bypass read/write).

Use for “edit anything as admin” surfaces (Studio F2). For rules-applied impersonation (“act as this user”), use getFirestore(sandbox.withAuth({ uid })) instead — that path is unchanged.

Parameters

Returns

SandboxFirestore

Example

import { initializeSandbox } from 'pyric/sandbox';
import { getFirestore, getAdminFirestore } from 'pyric-admin/firestore';

const sandbox = initializeSandbox();
getFirestore(sandbox.withAuth(null)).setRules('...deny everything...');

// Denied under rules:
await getFirestore(sandbox.withAuth({ uid: 'alice' }))
  .doc('locked/x').set({ a: 1 }); // throws permission-denied

// Bypasses rules:
await getAdminFirestore(sandbox).doc('locked/x').set({ a: 1 }); // ok

getFirestore()

function getFirestore(target?:
  | SandboxAdminApp
  | SandboxContext): SandboxFirestore;

Return the admin Firestore handle.

• getFirestore(ctx) — the original context form (rules-APPLIED for the ctx’s captured identity). Unchanged; idempotent per SandboxContext. This is the pyric-internal rules-simulation shape, not a firebase-admin shape, so it keeps rule evaluation.
• getFirestore(app) — resolves a PyricAdminApp’s sandbox to the rules-BYPASS admin lens (firebase-admin parity, #394).
• getFirestore() — resolves the default app to the rules-BYPASS admin lens; throws app/no-app when nothing is initialized.

The app forms mirror firebase-admin/firestore’s getFirestore(app?), which bypasses security rules — so a Cloud Function’s admin write lands the same way it does in production, instead of being denied as request.auth == null by the sandbox’s anon lens (the #394 deny-direction divergence).

Parameters

Returns

SandboxFirestore

onSnapshot()

Call Signature

function onSnapshot(reference: DocumentReference, observer: SnapshotObserver<DocumentSnapshot>): Unsubscribe;

Parameters

Returns

Unsubscribe

Call Signature

function onSnapshot(
   reference: DocumentReference,
   options: SnapshotListenerOptions,
   observer: SnapshotObserver<DocumentSnapshot>): Unsubscribe;

Parameters

Returns

Unsubscribe

Call Signature

function onSnapshot(
   reference: DocumentReference,
   onNext: (snapshot: DocumentSnapshot) => void,
   onError?: (error: unknown) => void,
   onCompletion?: () => void): Unsubscribe;

Parameters

Returns

Unsubscribe

Call Signature

function onSnapshot(
   reference: DocumentReference,
   options: SnapshotListenerOptions,
   onNext: (snapshot: DocumentSnapshot) => void,
   onError?: (error: unknown) => void,
   onCompletion?: () => void): Unsubscribe;

Parameters

Returns

Unsubscribe

Call Signature

function onSnapshot(reference: Query | CollectionReference, observer: SnapshotObserver<QuerySnapshot>): Unsubscribe;

Parameters

Returns

Unsubscribe

Call Signature

function onSnapshot(
   reference: Query | CollectionReference,
   options: SnapshotListenerOptions,
   observer: SnapshotObserver<QuerySnapshot>): Unsubscribe;

Parameters

Returns

Unsubscribe

Call Signature

function onSnapshot(
   reference: Query | CollectionReference,
   onNext: (snapshot: QuerySnapshot) => void,
   onError?: (error: unknown) => void,
   onCompletion?: () => void): Unsubscribe;

Parameters

Returns

Unsubscribe

Call Signature

function onSnapshot(
   reference: Query | CollectionReference,
   options: SnapshotListenerOptions,
   onNext: (snapshot: QuerySnapshot) => void,
   onError?: (error: unknown) => void,
   onCompletion?: () => void): Unsubscribe;

Parameters

Returns

Unsubscribe

References

AuthState

Re-exports AuthState

DocumentData

Re-exports DocumentData

FieldValue

Re-exports FieldValue

FieldValueSentinel

Re-exports FieldValueSentinel

LintResult

Re-exports LintResult

OrderDirection

Re-exports OrderDirection

Sandbox

Re-exports Sandbox

SandboxContext

Re-exports SandboxContext

SandboxError

Re-exports SandboxError

Timestamp

Re-exports Timestamp

WhereFilterOp

Re-exports WhereFilterOp