Classes
FieldPath
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
Properties
Methods
data()
data(): DocumentData;
Returns
DocumentData
get()
get(fieldPath: SnapshotFieldPath): unknown;
Parameters
Returns
unknown
AdminQueryDocumentSnapshot
Extends
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
docChanges()
docChanges(options?: {
includeMetadataChanges?: boolean;
}): {
doc: AdminQueryDocumentSnapshot;
newIndex: number;
oldIndex: number;
type: "added" | "removed" | "modified";
}[];
Parameters
Returns
{
doc: AdminQueryDocumentSnapshot;
newIndex: number;
oldIndex: number;
type: "added" | "removed" | "modified";
}[]
forEach()
forEach(callback: (snap: AdminQueryDocumentSnapshot) => void, thisArg?: unknown): 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
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,
fromSnapshot?: 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: SnapshotFieldPath, direction?: QueryOrderDirection): Query;
Parameters
Returns
Query
Inherited from
Query.orderBy
startCursor()
startCursor(
values: unknown[],
inclusive: boolean,
fromSnapshot?: 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: SnapshotFieldPath,
op:
| "<"
| "<="
| "=="
| "!="
| ">="
| ">"
| "in"
| "not-in"
| "array-contains"
| "array-contains-any",
value: unknown): Query;
Parameters
Returns
Query
Inherited from
Query.where
DocChangesOptions
Options for QuerySnapshot.docChanges. Mirrors Web SDK shape.
Properties
DocumentChange
Type Parameters
Properties
DocumentReference
Properties
Methods
collection()
collection(name: string): CollectionReference;
Parameters
Returns
CollectionReference
create()
create(data: DocumentData, opts?: OperationOptions): Promise<void>;
Parameters
Returns
Promise<void>
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()
Call Signature
update(data: DocumentData, opts?: OperationOptions): Promise<void>;
Parameters
Returns
Promise<void>
Call Signature
update(
field: string | FieldPath,
value: unknown, ...
moreFieldsAndValues: unknown[]): Promise<void>;
Parameters
Returns
Promise<void>
Call Signature
update(dataOrField:
| string
| DocumentData
| FieldPath, ...preconditionOrValues: unknown[]): Promise<void>;
Parameters
Returns
Promise<void>
DocumentSnapshot
Extended by
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
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
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,
fromSnapshot?: 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: SnapshotFieldPath, direction?: QueryOrderDirection): Query;
Parameters
Returns
Query
startCursor()
startCursor(
values: unknown[],
inclusive: boolean,
fromSnapshot?: 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: SnapshotFieldPath,
op:
| "<"
| "<="
| "=="
| "!="
| ">="
| ">"
| "in"
| "not-in"
| "array-contains"
| "array-contains-any",
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
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<QueryDocumentSnapshot>[];
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<QueryDocumentSnapshot>[]
forEach()
forEach(callback: (snap: QueryDocumentSnapshot) => void, thisArg?: unknown): void;
Parameters
Returns
void
RulesMetrics
Properties
SandboxFirestore
Sandbox-extended Firestore handle. Adds three sandbox-only methods
on top of the production-shaped Firestore surface:
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
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 } → merge the nested leaf fields 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 field paths, 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. This is a known validation gap.
Extends
Properties
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
Methods
create()
create(ref: DocumentReference, data: DocumentData): Transaction;
Parameters
Returns
Transaction
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,
options?: SetOptions): Transaction;
Parameters
Returns
Transaction
update()
Call Signature
update(ref: DocumentReference, data: DocumentData): Transaction;
Parameters
Returns
Transaction
Call Signature
update(
ref: DocumentReference,
field: string | FieldPath,
value: unknown, ...
moreFieldsAndValues: unknown[]): Transaction;
Parameters
Returns
Transaction
Call Signature
update(
ref: DocumentReference,
dataOrField:
| string
| DocumentData
| FieldPath, ...
preconditionOrValues: unknown[]): Transaction;
Parameters
Returns
Transaction
WriteBatch
Methods
commit()
commit(opts?: OperationOptions): Promise<void>;
Parameters
Returns
Promise<void>
create()
create(ref: DocumentReference, data: DocumentData): WriteBatch;
Parameters
Returns
WriteBatch
delete()
delete(ref: DocumentReference): WriteBatch;
Parameters
Returns
WriteBatch
set()
set(
ref: DocumentReference,
data: DocumentData,
options?: SetOptions): WriteBatch;
Parameters
Returns
WriteBatch
update()
Call Signature
update(ref: DocumentReference, data: DocumentData): WriteBatch;
Parameters
Returns
WriteBatch
Call Signature
update(
ref: DocumentReference,
field: string | FieldPath,
value: unknown, ...
moreFieldsAndValues: unknown[]): WriteBatch;
Parameters
Returns
WriteBatch
Call Signature
update(
ref: DocumentReference,
dataOrField:
| string
| DocumentData
| FieldPath, ...
preconditionOrValues: unknown[]): WriteBatch;
Parameters
Returns
WriteBatch
Type Aliases
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";
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
Variables
AggregateField
const AggregateField: DeferredApi;
Filter
const Filter: DeferredApi;
GeoPoint
const GeoPoint: DeferredApi;
GrpcStatus
const GrpcStatus: DeferredApi;
initializeFirestore
const initializeFirestore: DeferredApi;
setLogFunction
const setLogFunction: DeferredApi;
Functions
getAdminFirestore()
Call Signature
function getAdminFirestore(ctx: SandboxContext): SandboxFirestore;
Parameters
Returns
SandboxFirestore
Call Signature
function getAdminFirestore(sandbox: Sandbox): SandboxFirestore;
Parameters
Returns
SandboxFirestore
getFirestore()
function getFirestore(target?:
| SandboxContext
| SandboxAdminApp): 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