pyric 0.0.1 → 0.1.0-alpha.10

package/dist/firestore/query-constraints.js

@@ -0,0 +1,168 @@
+import { targetOf, sandboxDb, converterOf, parentRebuild, tagSandboxRef, buildSandboxShell, } from './state.js';
+/** Accept modular `where`/`orderBy` field args as string or FieldPath. */
+function fieldToString(field) {
+    if (typeof field === 'string')
+        return field;
+    return field._internalPath.segments.join('.');
+}
+export function query(source, ...constraints) {
+    const target = targetOf(source);
+    const conv = converterOf(source);
+    // For sandbox-live, the rebuild closure applies the same constraint chain
+    // against a fresh identity-bound handle at operation time.
+    const sourceRebuild = parentRebuild(source);
+    const buildAt = (db) => {
+        let q = sourceRebuild(db);
+        for (const c of constraints)
+            q = c.applySandbox(q);
+        return q;
+    };
+    const q = buildAt(sandboxDb(target));
+    const tagged = tagSandboxRef(q, target, (fresh) => buildAt(fresh));
+    if (conv) {
+        return buildSandboxShell(tagged, target, conv);
+    }
+    return tagged;
+}
+export function where(field, op, value) {
+    const fieldPath = fieldToString(field);
+    const sandboxFilter = { kind: 'where', field: fieldPath, op, value };
+    return {
+        applySandbox: (q) => q.where(fieldPath, op, value),
+        _sandboxFilter: sandboxFilter,
+    };
+}
+/**
+ * OR composite — at least one of the inner constraints must match.
+ * Each argument must itself be a filter constraint (`where()`, or
+ * nested `or()` / `and()`); passing `orderBy()` or `limit()` here is
+ * a type error at runtime.
+ *
+ * Mirrors `firebase/firestore`'s `or(...filters)` shape.
+ */
+export function or(...filters) {
+    return composite('or', filters);
+}
+/**
+ * AND composite. Same shape as `or()` but every inner constraint
+ * must match. Useful inside an `or()` to combine constraints that
+ * would otherwise be at the top level.
+ */
+export function and(...filters) {
+    return composite('and', filters);
+}
+/**
+ * Build a composite QueryConstraint. Extracts each sub-constraint's filter
+ * representation and rejects non-filter constraints.
+ */
+function composite(kind, filters) {
+    if (filters.length === 0) {
+        throw new TypeError(`pyric/firestore: ${kind}() requires at least one filter argument.`);
+    }
+    const sandboxSubs = [];
+    for (const c of filters) {
+        if (c._sandboxFilter === undefined) {
+            throw new TypeError(`pyric/firestore: ${kind}() received a non-filter constraint (orderBy / limit are not valid here).`);
+        }
+        sandboxSubs.push(c._sandboxFilter);
+    }
+    const sandboxFilter = { kind, filters: sandboxSubs };
+    return {
+        applySandbox: (q) => q.applyFilter(sandboxFilter),
+        _sandboxFilter: sandboxFilter,
+    };
+}
+export function orderBy(field, direction) {
+    const fieldPath = fieldToString(field);
+    return {
+        applySandbox: (q) => q.orderBy(fieldPath, direction),
+    };
+}
+export function limit(n) {
+    return {
+        applySandbox: (q) => q.limit(n),
+    };
+}
+// ─── Cursor pagination + limitToLast (Tier 3) ────────────────────────
+//
+// Modular Web-SDK shape:
+//
+//   query(coll,
+//     orderBy('priority'),
+//     startAfter(prevPagePriority),
+//     limit(10),
+//   );
+//
+// Each cursor factory accepts a positional values list (one per orderBy
+// clause) and passes it into the chainable cursor methods.
+/**
+ * Limit the query to the LAST `n` documents in the ordered result.
+ * Requires at least one `orderBy` on the query (production-aligned —
+ * the simulator throws at execute time without one).
+ */
+export function limitToLast(n) {
+    return {
+        applySandbox: (q) => q.limitToLast(n),
+    };
+}
+/**
+ * Heuristic for the snapshot overload: a single argument whose
+ * `.data` is a function. The public and chainable snapshot shapes both
+ * expose `.data()`. Falls back to the values-spread variant for everything
+ * else (including a single non-snapshot scalar arg, which is
+ * legitimate when the orderBy is on one field).
+ */
+function isDocumentSnapshot(args) {
+    if (args.length !== 1)
+        return false;
+    const a = args[0];
+    return (a !== null &&
+        typeof a === 'object' &&
+        'data' in a &&
+        typeof a.data === 'function');
+}
+export function startAt(...args) {
+    if (isDocumentSnapshot(args)) {
+        const snap = args[0];
+        return {
+            applySandbox: (q) => q.startCursorFromSnapshot(snap, true),
+        };
+    }
+    return {
+        applySandbox: (q) => q.startCursor(args, true),
+    };
+}
+export function startAfter(...args) {
+    if (isDocumentSnapshot(args)) {
+        const snap = args[0];
+        return {
+            applySandbox: (q) => q.startCursorFromSnapshot(snap, false),
+        };
+    }
+    return {
+        applySandbox: (q) => q.startCursor(args, false),
+    };
+}
+export function endAt(...args) {
+    if (isDocumentSnapshot(args)) {
+        const snap = args[0];
+        return {
+            applySandbox: (q) => q.endCursorFromSnapshot(snap, true),
+        };
+    }
+    return {
+        applySandbox: (q) => q.endCursor(args, true),
+    };
+}
+export function endBefore(...args) {
+    if (isDocumentSnapshot(args)) {
+        const snap = args[0];
+        return {
+            applySandbox: (q) => q.endCursorFromSnapshot(snap, false),
+        };
+    }
+    return {
+        applySandbox: (q) => q.endCursor(args, false),
+    };
+}
+//# sourceMappingURL=query-constraints.js.map

package/dist/firestore/query-constraints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-constraints.js","sourceRoot":"","sources":["../../src/firestore/query-constraints.ts"],"names":[],"mappings":"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"}

package/dist/firestore/reads.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `pyric/firestore` — document + query reads.
+ *
+ * `getDoc` / `getDocs`: resolve the chainable ref under current auth, apply
+ * any converter, and hand back a snapshot rehydrated to the modular-SDK
+ * shape (see `snapshots.ts`).
+ */
+import type { DocumentData } from 'pyric/sandbox/admin-firestore';
+import type { DocumentReference, DocumentSnapshot, Query, QuerySnapshot } from './types.js';
+export declare function getDoc<T = DocumentData>(ref: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
+export declare function getDocs<T = DocumentData>(query: Query<T>): Promise<QuerySnapshot<T>>;
+//# sourceMappingURL=reads.d.ts.map

package/dist/firestore/reads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reads.d.ts","sourceRoot":"","sources":["../../src/firestore/reads.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAGV,YAAY,EACb,MAAM,+BAA+B,CAAC;AAavC,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,EACL,aAAa,EAGd,MAAM,YAAY,CAAC;AAEpB,wBAAsB,MAAM,CAAC,CAAC,GAAG,YAAY,EAAE,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAYtG;AAED,wBAAsB,OAAO,CAAC,CAAC,GAAG,YAAY,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAmB1F"}

package/dist/firestore/reads.js

@@ -0,0 +1,32 @@
+import { targetOf, converterOf, chainDocFor, chainQueryFor, } from './state.js';
+import { wrapSandboxDocSnap, applyConverterToDocSnap, tagSnapshotRefs, } from './snapshots.js';
+export async function getDoc(ref) {
+    const target = targetOf(ref);
+    const conv = converterOf(ref);
+    const snap = await chainDocFor(target, ref).get();
+    if (conv) {
+        return applyConverterToDocSnap(snap, conv);
+    }
+    tagSnapshotRefs(snap, target);
+    return wrapSandboxDocSnap(snap);
+}
+export async function getDocs(query) {
+    const target = targetOf(query);
+    const conv = converterOf(query);
+    const snap = await chainQueryFor(target, query).get();
+    if (conv) {
+        const c = conv;
+        const wrappedDocs = snap.docs.map((d) => applyConverterToDocSnap(d, c));
+        return {
+            size: wrappedDocs.length,
+            empty: wrappedDocs.length === 0,
+            docs: wrappedDocs,
+        };
+    }
+    tagSnapshotRefs(snap, target);
+    const docs = snap.docs;
+    for (const d of docs)
+        wrapSandboxDocSnap(d);
+    return snap;
+}
+//# sourceMappingURL=reads.js.map

package/dist/firestore/reads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reads.js","sourceRoot":"","sources":["../../src/firestore/reads.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,QAAQ,EACR,WAAW,EACX,WAAW,EACX,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAUxB,MAAM,CAAC,KAAK,UAAU,MAAM,CAAmB,GAAyB;IACtE,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC7B,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;IAClD,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,uBAAuB,CAC5B,IAA+B,EAC/B,IAAiC,CAClC,CAAC;IACJ,CAAC;IACD,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC9B,OAAO,kBAAkB,CAAI,IAAc,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAAmB,KAAe;IAC7D,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC/B,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAChC,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC;IACtD,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,CAAC,GAAG,IAAiC,CAAC;QAC5C,MAAM,WAAW,GAAI,IAAkC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACrE,uBAAuB,CAAC,CAA4B,EAAE,CAAC,CAA6B,CACrF,CAAC;QACF,OAAO;YACL,IAAI,EAAE,WAAW,CAAC,MAAM;YACxB,KAAK,EAAE,WAAW,CAAC,MAAM,KAAK,CAAC;YAC/B,IAAI,EAAE,WAAW;SAClB,CAAC;IACJ,CAAC;IACD,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAI,IAAkC,CAAC,IAAI,CAAC;IACtD,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,kBAAkB,CAAC,CAAW,CAAC,CAAC;IACtD,OAAO,IAAmC,CAAC;AAC7C,CAAC"}

package/dist/firestore/refs.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `pyric/firestore` — reference / query path constructors + `withConverter`.
+ *
+ * `doc` / `collection` / `collectionGroup` build tagged sandbox refs;
+ * `withConverter` attaches (or strips) a data converter, returning
+ * a fresh typed view that carries forward through the chain factories.
+ */
+import type { DocumentData } from 'pyric/sandbox/admin-firestore';
+import type { Firestore, DocumentReference, CollectionReference, Query, FirestoreDataConverter } from './types.js';
+export declare function doc<T = DocumentData>(parent: Firestore | CollectionReference<T>, ...pathSegments: string[]): DocumentReference<T>;
+/**
+ * Cross-collection query — scans every document under every
+ * collection whose final segment matches `collectionId`. Mirrors
+ * `firebase/firestore`'s `collectionGroup(db, id)` shape.
+ *
+ * Returned `Query` accepts the same `where` / `orderBy` / `limit`
+ * constraints as any other query.
+ */
+export declare function collectionGroup(db: Firestore, collectionId: string): Query;
+export declare function collection(parent: Firestore | DocumentReference, ...pathSegments: string[]): CollectionReference;
+export declare function withConverter<AppModel, DbModel extends DocumentData = DocumentData>(ref: DocumentReference<DocumentData>, converter: FirestoreDataConverter<AppModel, DbModel>): DocumentReference<AppModel>;
+export declare function withConverter(ref: DocumentReference<unknown>, converter: null): DocumentReference<DocumentData>;
+export declare function withConverter<AppModel, DbModel extends DocumentData = DocumentData>(ref: CollectionReference<DocumentData>, converter: FirestoreDataConverter<AppModel, DbModel>): CollectionReference<AppModel>;
+export declare function withConverter(ref: CollectionReference<unknown>, converter: null): CollectionReference<DocumentData>;
+export declare function withConverter<AppModel, DbModel extends DocumentData = DocumentData>(q: Query<DocumentData>, converter: FirestoreDataConverter<AppModel, DbModel>): Query<AppModel>;
+export declare function withConverter(q: Query<unknown>, converter: null): Query<DocumentData>;
+//# sourceMappingURL=refs.d.ts.map

package/dist/firestore/refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../../src/firestore/refs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAalE,OAAO,KAAK,EACV,SAAS,EACT,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,EACL,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAIpB,wBAAgB,GAAG,CAAC,CAAC,GAAG,YAAY,EAClC,MAAM,EAAE,SAAS,GAAG,mBAAmB,CAAC,CAAC,CAAC,EAC1C,GAAG,YAAY,EAAE,MAAM,EAAE,GACxB,iBAAiB,CAAC,CAAC,CAAC,CAsCtB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,KAAK,CAQ1E;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,iBAAiB,EAAE,GAAG,YAAY,EAAE,MAAM,EAAE,GAAG,mBAAmB,CA4BhH;AAkCD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,SAAS,YAAY,GAAG,YAAY,EACjF,GAAG,EAAE,iBAAiB,CAAC,YAAY,CAAC,EACpC,SAAS,EAAE,sBAAsB,CAAC,QAAQ,EAAE,OAAO,CAAC,GACnD,iBAAiB,CAAC,QAAQ,CAAC,CAAC;AAC/B,wBAAgB,aAAa,CAC3B,GAAG,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAC/B,SAAS,EAAE,IAAI,GACd,iBAAiB,CAAC,YAAY,CAAC,CAAC;AACnC,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,SAAS,YAAY,GAAG,YAAY,EACjF,GAAG,EAAE,mBAAmB,CAAC,YAAY,CAAC,EACtC,SAAS,EAAE,sBAAsB,CAAC,QAAQ,EAAE,OAAO,CAAC,GACnD,mBAAmB,CAAC,QAAQ,CAAC,CAAC;AACjC,wBAAgB,aAAa,CAC3B,GAAG,EAAE,mBAAmB,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,IAAI,GACd,mBAAmB,CAAC,YAAY,CAAC,CAAC;AACrC,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,SAAS,YAAY,GAAG,YAAY,EACjF,CAAC,EAAE,KAAK,CAAC,YAAY,CAAC,EACtB,SAAS,EAAE,sBAAsB,CAAC,QAAQ,EAAE,OAAO,CAAC,GACnD,KAAK,CAAC,QAAQ,CAAC,CAAC;AACnB,wBAAgB,aAAa,CAC3B,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,EACjB,SAAS,EAAE,IAAI,GACd,KAAK,CAAC,YAAY,CAAC,CAAC"}

package/dist/firestore/refs.js

@@ -0,0 +1,74 @@
+import { TARGET_SYMBOL, targetOf, sandboxDb, tagSandboxRef, converterOf, underlyingOf, buildSandboxShell, asChainColl, asChainDoc, } from './state.js';
+// ─── Path constructors ────────────────────────────────────────────────
+export function doc(parent, ...pathSegments) {
+    const target = targetOf(parent);
+    const isHandle = TARGET_SYMBOL in parent;
+    // Propagate any converter from a typed collection to the resulting
+    // doc — `doc(coll<User>, 'u1')` returns `DocumentReference<User>`.
+    const conv = isHandle ? undefined : converterOf(parent);
+    const db = sandboxDb(target);
+    if (isHandle) {
+        if (pathSegments.length === 0) {
+            throw new TypeError('doc(db, path) requires at least one path segment.');
+        }
+        const path = pathSegments.join('/');
+        const built = db.doc(path);
+        const tagged = tagSandboxRef(built, target, (fresh) => fresh.doc(path));
+        return tagged;
+    }
+    const coll = asChainColl(underlyingOf(parent));
+    const ref = pathSegments.length === 0
+        ? coll.doc()
+        : coll.doc(pathSegments.join('/'));
+    const absPath = ref.path;
+    const tagged = tagSandboxRef(ref, target, (fresh) => fresh.doc(absPath));
+    if (conv) {
+        return buildSandboxShell(tagged, target, conv);
+    }
+    return tagged;
+}
+/**
+ * Cross-collection query — scans every document under every
+ * collection whose final segment matches `collectionId`. Mirrors
+ * `firebase/firestore`'s `collectionGroup(db, id)` shape.
+ *
+ * Returned `Query` accepts the same `where` / `orderBy` / `limit`
+ * constraints as any other query.
+ */
+export function collectionGroup(db, collectionId) {
+    const target = targetOf(db);
+    const q = sandboxDb(target).collectionGroup(collectionId);
+    return tagSandboxRef(q, target, (fresh) => fresh.collectionGroup(collectionId));
+}
+export function collection(parent, ...pathSegments) {
+    const target = targetOf(parent);
+    const isHandle = TARGET_SYMBOL in parent;
+    if (pathSegments.length === 0) {
+        throw new TypeError('collection() requires at least one path segment.');
+    }
+    // Note: any converter on `parent` (typed DocumentReference<T>) does
+    // NOT propagate to the sub-collection — matches `firebase/firestore`'s
+    // `collection(typedDoc, path)` returning `CollectionReference<DocumentData>`.
+    // A parent doc's T describes its own data, not its subcollections'.
+    if (isHandle) {
+        const path = pathSegments.join('/');
+        const built = sandboxDb(target).collection(path);
+        return tagSandboxRef(built, target, (fresh) => fresh.collection(path));
+    }
+    const docRef = asChainDoc(underlyingOf(parent));
+    const subPath = pathSegments.join('/');
+    const built = docRef.collection(subPath);
+    const absPath = built.path;
+    return tagSandboxRef(built, target, (fresh) => fresh.collection(absPath));
+}
+export function withConverter(source, converter) {
+    const target = targetOf(source);
+    if (converter === null) {
+        // Strip — return the underlying plain ref. Falls back to `source`
+        // itself if it was never wrapped (no-op).
+        return underlyingOf(source);
+    }
+    const underlying = underlyingOf(source);
+    return buildSandboxShell(underlying, target, converter);
+}
+//# sourceMappingURL=refs.js.map

package/dist/firestore/refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.js","sourceRoot":"","sources":["../../src/firestore/refs.ts"],"names":[],"mappings":"AASA,OAAO,EACL,aAAa,EACb,QAAQ,EACR,SAAS,EACT,aAAa,EACb,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,UAAU,GACX,MAAM,YAAY,CAAC;AASpB,yEAAyE;AAEzE,MAAM,UAAU,GAAG,CACjB,MAA0C,EAC1C,GAAG,YAAsB;IAEzB,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,MAAM,QAAQ,GAAG,aAAa,IAAI,MAAM,CAAC;IACzC,mEAAmE;IACnE,mEAAmE;IACnE,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACxD,MAAM,EAAE,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAC7B,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,SAAS,CAAC,mDAAmD,CAAC,CAAC;QAC3E,CAAC;QACD,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpC,MAAM,KAAK,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3B,MAAM,MAAM,GAAG,aAAa,CAC1B,KAAe,EACf,MAAM,EACN,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAsB,CAChD,CAAC;QACF,OAAO,MAA8B,CAAC;IACxC,CAAC;IACD,MAAM,IAAI,GAAG,WAAW,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,YAAY,CAAC,MAAM,KAAK,CAAC;QACnC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;QACZ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrC,MAAM,OAAO,GAAI,GAAwB,CAAC,IAAI,CAAC;IAC/C,MAAM,MAAM,GAAG,aAAa,CAC1B,GAAa,EACb,MAAM,EACN,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAsB,CACnD,CAAC;IACF,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,iBAAiB,CACtB,MAAsC,EACtC,MAAM,EACN,IAAI,CACmB,CAAC;IAC5B,CAAC;IACD,OAAO,MAA8B,CAAC;AACxC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,EAAa,EAAE,YAAoB;IACjE,MAAM,MAAM,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC5B,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;IAC1D,OAAO,aAAa,CAClB,CAAqB,EACrB,MAAM,EACN,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,eAAe,CAAC,YAAY,CAAsB,CACpE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAqC,EAAE,GAAG,YAAsB;IACzF,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,MAAM,QAAQ,GAAG,aAAa,IAAI,MAAM,CAAC;IACzC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,SAAS,CAAC,kDAAkD,CAAC,CAAC;IAC1E,CAAC;IACD,oEAAoE;IACpE,uEAAuE;IACvE,8EAA8E;IAC9E,oEAAoE;IACpE,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpC,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACjD,OAAO,aAAa,CAClB,KAA4B,EAC5B,MAAM,EACN,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAsB,CACvD,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,UAAU,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,OAAO,GAAI,KAA0B,CAAC,IAAI,CAAC;IACjD,OAAO,aAAa,CAClB,KAA4B,EAC5B,MAAM,EACN,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAsB,CAC1D,CAAC;AACJ,CAAC;AA0DD,MAAM,UAAU,aAAa,CAC3B,MAAc,EACd,SAA+D;IAE/D,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,kEAAkE;QAClE,0CAA0C;QAC1C,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IACD,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,CAAmC,CAAC;IAC1E,OAAO,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;AAC1D,CAAC"}

package/dist/firestore/sandbox-controls.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Firestore-specific controls for the public `pyric/sandbox/firestore`
+ * subpath.
+ *
+ * The implementation stays with the Firestore module even though the package
+ * export is nested below `pyric/sandbox`: central sandbox owns cross-service
+ * lifecycle, while each Firebase surface owns its own backend controls.
+ */
+import type { LocalSandbox } from 'pyric/sandbox';
+import type { DocumentData, LintResult } from './types.js';
+export interface FirestoreInspectOptions {
+    /** Maximum number of recent requests and denials to return. Defaults to 10. */
+    recentEventLimit?: number;
+}
+/** Stable JSON-serializable Firestore diagnostic used by Studio and tools. */
+export interface FirestoreInspectReport {
+    rules: {
+        source: string;
+        sizeBytes: number;
+        isEmpty: boolean;
+        lint: {
+            errors: number;
+            warnings: number;
+            info: number;
+            findings: Array<{
+                rule: string;
+                severity: string;
+                message: string;
+            }>;
+        };
+    };
+    documents: {
+        totalCount: number;
+        byCollection: Record<string, number>;
+    };
+    events: {
+        totalCount: number;
+        recentDenials: Array<{
+            path: string;
+            method: string;
+            auth: unknown;
+            debugMessage?: string;
+        }>;
+        recentRequests: Array<{
+            path: string;
+            method: string;
+            result: string;
+            auth: unknown;
+        }>;
+    };
+}
+/** Load Firestore Rules into one sandbox and notify its live listeners. */
+export declare function setRules(sandbox: LocalSandbox, source: string): LintResult;
+/** Replace Firestore documents in bulk, preserving rules and bypassing evaluation. */
+export declare function seedDocuments(sandbox: LocalSandbox, documents: Record<string, DocumentData>): LintResult;
+/** Snapshot only Firestore documents without traversing other sandbox services. */
+export declare function snapshotDocuments(sandbox: LocalSandbox): Record<string, DocumentData>;
+/** Inspect Firestore rules, documents, and recent requests in one sandbox. */
+export declare function inspect(sandbox: LocalSandbox, options?: FirestoreInspectOptions): FirestoreInspectReport;
+//# sourceMappingURL=sandbox-controls.d.ts.map

package/dist/firestore/sandbox-controls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-controls.d.ts","sourceRoot":"","sources":["../../src/firestore/sandbox-controls.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,eAAe,CAAC;AAIjE,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE3D,MAAM,WAAW,uBAAuB;IACtC,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE;QACL,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,OAAO,CAAC;QACjB,IAAI,EAAE;YACJ,MAAM,EAAE,MAAM,CAAC;YACf,QAAQ,EAAE,MAAM,CAAC;YACjB,IAAI,EAAE,MAAM,CAAC;YACb,QAAQ,EAAE,KAAK,CAAC;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,QAAQ,EAAE,MAAM,CAAC;gBAAC,OAAO,EAAE,MAAM,CAAA;aAAE,CAAC,CAAC;SACtE,CAAC;KACH,CAAC;IACF,SAAS,EAAE;QACT,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACtC,CAAC;IACF,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,KAAK,CAAC;YACnB,IAAI,EAAE,MAAM,CAAC;YACb,MAAM,EAAE,MAAM,CAAC;YACf,IAAI,EAAE,OAAO,CAAC;YACd,YAAY,CAAC,EAAE,MAAM,CAAC;SACvB,CAAC,CAAC;QACH,cAAc,EAAE,KAAK,CAAC;YACpB,IAAI,EAAE,MAAM,CAAC;YACb,MAAM,EAAE,MAAM,CAAC;YACf,MAAM,EAAE,MAAM,CAAC;YACf,IAAI,EAAE,OAAO,CAAC;SACf,CAAC,CAAC;KACJ,CAAC;CACH;AAED,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAE1E;AAED,sFAAsF;AACtF,wBAAgB,aAAa,CAC3B,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GACtC,UAAU,CAGZ;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,GACpB,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAE9B;AAED,8EAA8E;AAC9E,wBAAgB,OAAO,CACrB,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CA2DxB"}

package/dist/firestore/sandbox-controls.js

@@ -0,0 +1,77 @@
+import { getInternalEnv } from 'pyric/sandbox/internal';
+import { lintFirestoreRules } from 'pyric/rules/internal';
+/** Load Firestore Rules into one sandbox and notify its live listeners. */
+export function setRules(sandbox, source) {
+    return getInternalEnv(sandbox).deployRules(source);
+}
+/** Replace Firestore documents in bulk, preserving rules and bypassing evaluation. */
+export function seedDocuments(sandbox, documents) {
+    const env = getInternalEnv(sandbox);
+    return env.seed({ rules: env.getRules(), documents });
+}
+/** Snapshot only Firestore documents without traversing other sandbox services. */
+export function snapshotDocuments(sandbox) {
+    return getInternalEnv(sandbox).snapshot();
+}
+/** Inspect Firestore rules, documents, and recent requests in one sandbox. */
+export function inspect(sandbox, options = {}) {
+    const recentLimit = options.recentEventLimit ?? 10;
+    const env = getInternalEnv(sandbox);
+    const rulesSource = env.getRules();
+    const lint = rulesSource ? lintFirestoreRules(rulesSource) : { warnings: [] };
+    const findings = lint.warnings.map((warning) => ({
+        rule: warning.rule,
+        severity: warning.severity,
+        message: warning.message,
+    }));
+    const counts = { errors: 0, warnings: 0, info: 0 };
+    for (const warning of lint.warnings) {
+        if (warning.severity === 'error')
+            counts.errors++;
+        else if (warning.severity === 'warning')
+            counts.warnings++;
+        else
+            counts.info++;
+    }
+    const documents = env.snapshot();
+    const byCollection = {};
+    for (const path of Object.keys(documents)) {
+        const top = path.split('/')[0] ?? '';
+        if (!top)
+            continue;
+        byCollection[top] = (byCollection[top] ?? 0) + 1;
+    }
+    const history = sandbox.history();
+    const requests = history.filter((event) => event.kind === 'request');
+    const denials = requests.filter((event) => event.result === 'deny');
+    const recentRequests = requests.slice(-recentLimit).map((event) => ({
+        path: String(event.path ?? ''),
+        method: String(event.method ?? ''),
+        result: String(event.result ?? ''),
+        auth: event.auth ?? null,
+    }));
+    const recentDenials = denials.slice(-recentLimit).map((event) => ({
+        path: String(event.path ?? ''),
+        method: String(event.method ?? ''),
+        auth: event.auth ?? null,
+        debugMessage: typeof event.debugMessage === 'string' ? event.debugMessage : undefined,
+    }));
+    return {
+        rules: {
+            source: rulesSource,
+            sizeBytes: new TextEncoder().encode(rulesSource).byteLength,
+            isEmpty: rulesSource.trim().length === 0,
+            lint: { ...counts, findings },
+        },
+        documents: {
+            totalCount: Object.keys(documents).length,
+            byCollection,
+        },
+        events: {
+            totalCount: history.length,
+            recentDenials,
+            recentRequests,
+        },
+    };
+}
+//# sourceMappingURL=sandbox-controls.js.map

package/dist/firestore/sandbox-controls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-controls.js","sourceRoot":"","sources":["../../src/firestore/sandbox-controls.ts"],"names":[],"mappings":"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"}

package/dist/firestore/snapshots.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `pyric/firestore` — shared sandbox snapshot rehydration.
+ *
+ * The read-path snapshot helpers used by BOTH `reads` (`getDoc` /
+ * `getDocs`) and `listeners` (`onSnapshot`): value finalization wrappers,
+ * ref tagging, and the `.exists` property→method normalization that makes
+ * sandbox snapshots match Firebase's modular-SDK shape.
+ *
+ * Package-internal — the barrel re-exports none of these; the public
+ * snapshot TYPES live in `types.ts`.
+ */
+import type { AdminDocumentSnapshot as ChainDocSnap } from 'pyric/sandbox/admin-firestore';
+import { type Target } from './state.js';
+import type { DocumentSnapshot, FirestoreDataConverter } from './types.js';
+/**
+ * Wrap a raw sandbox `DocumentSnapshot` so `.data()` runs the final
+ * value translation (rules wrappers → `firebase/firestore` types).
+ * Other surface (id / ref / exists) passes through unchanged so
+ * `tagSnapshotRefs` still operates on the original snap object.
+ */
+export declare function wrapSandboxDocSnap<T>(snap: object): DocumentSnapshot<T>;
+/**
+ * Wrap a plain sandbox `DocumentSnapshot` so `.data()` runs the
+ * converter's `fromFirestore`. Identity / `exists` pass through.
+ */
+export declare function applyConverterToDocSnap<AppModel>(snap: ChainDocSnap, conv: FirestoreDataConverter<AppModel>): DocumentSnapshot<AppModel>;
+/**
+ * Walk a snapshot and tag every ref-shaped field in `refToTarget`,
+ * AND normalize `.exists` to method form so consumer code targeting
+ * Firebase's modular SDK (`if (snap.exists())`) works uniformly.
+ *
+ * The chainable adapter exposes `exists` as a property (Admin SDK
+ * shape — `if (snap.exists)`). Firebase's modular SDK exposes it as
+ * a method (`if (snap.exists())`). Without this normalization, user
+ * code written against the documented Firebase API crashes against
+ * the sandbox with "snap.exists is not a function" — a parity bug
+ * agents and developers all rediscover by hand.
+ *
+ * Both forms remain readable on the returned object — the function
+ * branch in any "did the existing FirestoreTab handle both shapes"
+ * code still works.
+ *
+ * Idempotent — tagging an already-tagged object is a no-op, and the
+ * `exists` getter we install is a no-op when one already exists.
+ */
+export declare function tagSnapshotRefs(snap: unknown, target: Target): unknown;
+/**
+ * Snapshot `.ref` objects from the sandbox carry only `{ id, path }`
+ * — no `.onSnapshot`, `.get`, `.set`, etc. — so a follow-up
+ * `onSnapshot(snap.ref)` would crash with "ref.onSnapshot is not a
+ * function." Bind the snapshot ref to a full chainable doc ref via
+ * `refToUnderlying`; `underlyingOf(snap.ref)` then returns the real
+ * ref the chainable adapter exposes its op methods on. No-op for refs that
+ * already have a registered underlying.
+ */
+export declare function wireSnapshotRefToUnderlying(snapRef: {
+    path?: string;
+}, target: Target): void;
+/**
+ * If `obj.exists` is a boolean property, replace it with a function
+ * that returns that value — so consumer code can do `snap.exists()`
+ * uniformly across the sandbox + Firebase backends. Idempotent: if
+ * `exists` is already a function, leave it alone.
+ *
+ * `configurable: true` so a later normalize (over a re-yielded
+ * snapshot from the same listener) can re-install cleanly.
+ */
+export declare function normalizeExists(obj: {
+    exists?: boolean | (() => boolean);
+}): void;
+//# sourceMappingURL=snapshots.d.ts.map

package/dist/firestore/snapshots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshots.d.ts","sourceRoot":"","sources":["../../src/firestore/snapshots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,qBAAqB,IAAI,YAAY,EAAgB,MAAM,+BAA+B,CAAC;AAEzG,OAAO,EAML,KAAK,MAAM,EACZ,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,gBAAgB,EAEhB,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAWvE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAC9C,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GACrC,gBAAgB,CAAC,QAAQ,CAAC,CAsB5B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAsBtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAC1B,MAAM,EAAE,MAAM,GACb,IAAI,CAwBN;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE;IACnC,MAAM,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;CACpC,GAAG,IAAI,CAiBP"}