pyric 0.0.1 → 0.1.0-alpha.10

package/dist/firestore/persistence.d.ts

@@ -0,0 +1,227 @@
+/**
+ * `pyric/firestore` — offline / persistence / network + cache-init family.
+ *
+ * The honest-mirror surface a real app's init sequence touches: persistence
+ * toggles, network enable/disable, the inert cache/tab-manager/GC config
+ * tokens, `initializeFirestore`, the get-from-server / get-from-cache read
+ * variants, `setLogLevel`, and `onSnapshotsInSync`. Read the section note
+ * below before touching any function.
+ */
+import type { FirebaseApp } from '../app/types.js';
+import type { Sandbox, SandboxContext } from 'pyric/sandbox';
+import type { DocumentData } from 'pyric/sandbox/admin-firestore';
+import type { Firestore, DocumentReference, DocumentSnapshot, Query, QuerySnapshot, Unsubscribe } from './types.js';
+export interface PersistenceSettings {
+    forceOwnership?: boolean;
+}
+/**
+ * Sandbox: no-op success. The sandbox's default persistence (IndexedDB
+ * on the SharedWorker/serve path, or whatever backend `enablePersistence`
+ * was configured with) already caches every write — this call has
+ * nothing left to enable. Resolves immediately.
+ *
+ * Unlike the real SDK, this does NOT reject with `'failed-precondition'`
+ * when called after other Firestore ops have already run. The guard
+ * exists in the real SDK to protect an actual cache-initialization
+ * race; the sandbox has no such race (there's no cache to initialize),
+ * so enforcing the same restriction would only make app code that
+ * calls this defensively at startup fail for no local reason.
+ *
+ */
+export declare function enableIndexedDbPersistence(db: Firestore, persistenceSettings?: PersistenceSettings): Promise<void>;
+/**
+ * Sandbox: no-op success, same rationale as {@link enableIndexedDbPersistence}.
+ * Multi-tab coordination is meaningless here too: the sandbox's
+ * SharedWorker path already IS the single shared store every tab talks
+ * to, so there's no separate "multi-tab" mode to opt into.
+ *
+ */
+export declare function enableMultiTabIndexedDbPersistence(db: Firestore): Promise<void>;
+/**
+ * Sandbox: actually clears the sandbox's persisted store via
+ * `Sandbox.clearPersistence()` — the honest mapping, not a no-op. This
+ * wipes the persisted blob (IndexedDB, or whatever backend
+ * `enablePersistence` was configured with) while leaving in-memory
+ * state untouched, matching `clearPersistence`'s own contract. It is
+ * ALREADY a no-op when persistence was never enabled, so callers that
+ * invoke this defensively at startup are safe either way.
+ *
+ * `getFirestore(ctx)` (frozen `SandboxContext`) targets don't carry a
+ * live `Sandbox` handle with a `clearPersistence` method reachable the
+ * same way as a `sandbox`/`sandbox-live` target's `.sandbox` field —
+ * both variants do, in fact, so this always has a sandbox to call into.
+ *
+ * The real SDK requires this before Firestore starts; the sandbox's mapped
+ * `clearPersistence()` has no such restriction.
+ */
+export declare function clearIndexedDbPersistence(db: Firestore): Promise<void>;
+/**
+ * Sandbox: no-op success. There is no network in the sandbox — every
+ * op is a local call into the in-memory/IndexedDB-backed store — so
+ * there is nothing to disable. This deliberately does NOT simulate an
+ * offline mode: queued writes still commit immediately rather than
+ * queuing, because the sandbox cannot honestly deliver "queued until
+ * reconnected" when there is no connection to lose in the first place.
+ * App code that calls this to prep for flaky connectivity will not
+ * crash, but it also will not observe write-queuing behavior.
+ *
+ */
+export declare function disableNetwork(db: Firestore): Promise<void>;
+/**
+ * Sandbox: no-op success, symmetric with {@link disableNetwork} — since
+ * network was never disabled locally, there is nothing to re-enable.
+ *
+ */
+export declare function enableNetwork(db: Firestore): Promise<void>;
+/**
+ * Sandbox: resolves immediately. The real SDK's version waits for
+ * queued writes to reach the server; the sandbox has no server to wait
+ * on — every write it accepts is already committed to the local store
+ * by the time the write's own promise resolves, so by the time this is
+ * called there are, honestly, never any writes still pending a round
+ * trip.
+ *
+ */
+export declare function waitForPendingWrites(db: Firestore): Promise<void>;
+/**
+ * Sandbox: genuinely tears the target down by calling
+ * `Sandbox.dispose()` — NOT a pure no-op like the rest of this family.
+ * `dispose()` tears down listener registries on the sandbox's
+ * environment without replacing it (idempotent, doesn't touch data).
+ * This is the honest mapping of "terminate this Firestore instance":
+ * a real app that calls `terminate(db)` expects listeners to stop and
+ * the instance to be unusable for further meaningful work, and
+ * `dispose()` delivers exactly that for the sandbox.
+ *
+ * Caveat: `dispose()` operates on the whole `Sandbox`, not a
+ * Firestore-only slice of it — if `pyric/database` or `pyric/storage`
+ * share the same `Sandbox`, their listener registries are torn down
+ * too. This differs from the real SDK, where `terminate()` only
+ * affects the one `Firestore` instance. Documented divergence.
+ *
+ */
+export declare function terminate(db: Firestore): Promise<void>;
+/** Hidden brand on {@link LocalCache} tokens returned by
+ *  {@link persistentLocalCache} / {@link memoryLocalCache}. Never
+ *  inspected by consumer code — `initializeFirestore` accepts the
+ *  token but the cache/network settings it carries are no-ops. */
+declare const LOCAL_CACHE_SYMBOL: unique symbol;
+/** Hidden brand on tab-manager tokens returned by
+ *  {@link persistentSingleTabManager} / {@link persistentMultipleTabManager}. */
+declare const TAB_MANAGER_SYMBOL: unique symbol;
+/** Hidden brand on garbage-collector tokens returned by
+ *  {@link memoryEagerGarbageCollector} / {@link memoryLruGarbageCollector}. */
+declare const GC_SYMBOL: unique symbol;
+/** Opaque tab-manager config token. Inert — persistence is always on,
+ *  and the SharedWorker/`pyric dev` path already is the one shared
+ *  store every tab talks to, so there is no separate multi-tab mode
+ *  to opt into. Carries the requested kind only for debugging. */
+export interface PersistentTabManager {
+    readonly [TAB_MANAGER_SYMBOL]: 'single' | 'multiple';
+}
+/** Opaque garbage-collector config token. Inert for the same reason —
+ *  there is no memory cache tier with GC pressure to tune. */
+export interface MemoryGarbageCollector {
+    readonly [GC_SYMBOL]: 'eager' | 'lru';
+}
+/** Opaque local-cache config token accepted by {@link initializeFirestore}'s
+ *  `settings.localCache`. Inert — see the tier-1 section rationale above. */
+export interface LocalCache {
+    readonly [LOCAL_CACHE_SYMBOL]: 'persistent' | 'memory';
+    readonly tabManager?: PersistentTabManager;
+    readonly garbageCollector?: MemoryGarbageCollector;
+}
+/**
+ * Inert config token. Real Firebase uses this to select an on-disk,
+ * persistent IndexedDB cache tier; the sandbox has no separate cache
+ * tier — persistence is already the default — so this just returns a
+ * tagged token `initializeFirestore` can accept without crashing.
+ */
+export declare function persistentLocalCache(settings?: {
+    tabManager?: PersistentTabManager;
+    cacheSizeBytes?: number;
+}): LocalCache;
+/** Inert config token — the memory-cache counterpart of {@link persistentLocalCache}. */
+export declare function memoryLocalCache(settings?: {
+    garbageCollector?: MemoryGarbageCollector;
+}): LocalCache;
+/** Inert config token accepted by {@link persistentLocalCache}'s `tabManager`. */
+export declare function persistentSingleTabManager(_settings?: {
+    forceOwnership?: boolean;
+}): PersistentTabManager;
+/** Inert config token accepted by {@link persistentLocalCache}'s `tabManager`. */
+export declare function persistentMultipleTabManager(): PersistentTabManager;
+/** Inert config token accepted by {@link memoryLocalCache}'s `garbageCollector`. */
+export declare function memoryEagerGarbageCollector(): MemoryGarbageCollector;
+/** Inert config token accepted by {@link memoryLocalCache}'s `garbageCollector`. */
+export declare function memoryLruGarbageCollector(_settings?: {
+    cacheSizeBytes?: number;
+}): MemoryGarbageCollector;
+/** Client-cache/network settings `initializeFirestore` accepts but no-ops
+ *  on sandbox targets — see the tier-1 section rationale above. */
+export interface FirestoreSettings {
+    localCache?: LocalCache;
+    cacheSizeBytes?: number;
+    ignoreUndefinedProperties?: boolean;
+    experimentalForceLongPolling?: boolean;
+    experimentalAutoDetectLongPolling?: boolean;
+    host?: string;
+    ssl?: boolean;
+}
+/**
+ * Delegates to {@link getFirestore} and returns the same handle. Accepts
+ * the `settings` argument (so the explicit-init pattern app code commonly
+ * writes — `initializeFirestore(app, { localCache: persistentLocalCache(...) } )`
+ * — no longer crashes at import) but no-ops the cache/network settings:
+ * persistence is already the sandbox default, so there is nothing left to
+ * configure into existence.
+ *
+ */
+export declare function initializeFirestore(app: SandboxContext | Sandbox | FirebaseApp, _settings?: FirestoreSettings, _databaseId?: string): Firestore;
+/**
+ * Sandbox: delegates to {@link getDoc}. The sandbox store IS the
+ * authoritative, always-fresh source — there is no separate server
+ * round-trip to force, so "from server" and the default read are the
+ * same honest thing.
+ *
+ */
+export declare function getDocFromServer<T = DocumentData>(ref: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
+/** Query-plural form of {@link getDocFromServer}. */
+export declare function getDocsFromServer<T = DocumentData>(query: Query<T>): Promise<QuerySnapshot<T>>;
+/**
+ * Sandbox: delegates to {@link getDoc}. Real Firebase THROWS
+ * `'unavailable'` here on a cache miss (nothing local matches the
+ * ref); pyric never misses — the local store always has whatever is
+ * there — so this never throws for that reason. Documented divergence,
+ * not a claim of parity.
+ *
+ */
+export declare function getDocFromCache<T = DocumentData>(ref: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
+/** Query-plural form of {@link getDocFromCache} — same cache-miss divergence. */
+export declare function getDocsFromCache<T = DocumentData>(query: Query<T>): Promise<QuerySnapshot<T>>;
+/** Mirrors `firebase/firestore`'s `LogLevel` union. */
+export type LogLevel = 'debug' | 'verbose' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * Accepted no-op: the sandbox has no modular-SDK-style logger to wire
+ * a level into (it uses host-level `console` logging directly, gated
+ * by `pyric dev`'s own flags, not this call). Exists purely so app
+ * code that calls this defensively at startup doesn't crash on a
+ * missing export.
+ */
+export declare function setLogLevel(logLevel: LogLevel): void;
+/**
+ * Sandbox: fires the callback once the current snapshot-delivery
+ * microtask queue settles — the closest honest approximation of "every
+ * active listener has delivered its latest state" available without a
+ * true cross-listener sync signal (the sandbox doesn't track one).
+ * This is NOT the real SDK's guarantee (which is scoped to actual
+ * server round-trips); it is scoped to local delivery only.
+ *
+ */
+export declare function onSnapshotsInSync(db: Firestore, observerOrCallback: (() => void) | {
+    next?: () => void;
+    complete?: () => void;
+    error?: (error: unknown) => void;
+}): Unsubscribe;
+export {};
+//# sourceMappingURL=persistence.d.ts.map

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

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

package/dist/firestore/persistence.js

@@ -0,0 +1,245 @@
+import { targetOf } from './state.js';
+import { getFirestore } from './instances.js';
+import { getDoc, getDocs } from './reads.js';
+/**
+ * Sandbox: no-op success. The sandbox's default persistence (IndexedDB
+ * on the SharedWorker/serve path, or whatever backend `enablePersistence`
+ * was configured with) already caches every write — this call has
+ * nothing left to enable. Resolves immediately.
+ *
+ * Unlike the real SDK, this does NOT reject with `'failed-precondition'`
+ * when called after other Firestore ops have already run. The guard
+ * exists in the real SDK to protect an actual cache-initialization
+ * race; the sandbox has no such race (there's no cache to initialize),
+ * so enforcing the same restriction would only make app code that
+ * calls this defensively at startup fail for no local reason.
+ *
+ */
+export function enableIndexedDbPersistence(db, persistenceSettings) {
+    targetOf(db);
+    void persistenceSettings;
+    return Promise.resolve();
+}
+/**
+ * Sandbox: no-op success, same rationale as {@link enableIndexedDbPersistence}.
+ * Multi-tab coordination is meaningless here too: the sandbox's
+ * SharedWorker path already IS the single shared store every tab talks
+ * to, so there's no separate "multi-tab" mode to opt into.
+ *
+ */
+export function enableMultiTabIndexedDbPersistence(db) {
+    targetOf(db);
+    return Promise.resolve();
+}
+/**
+ * Sandbox: actually clears the sandbox's persisted store via
+ * `Sandbox.clearPersistence()` — the honest mapping, not a no-op. This
+ * wipes the persisted blob (IndexedDB, or whatever backend
+ * `enablePersistence` was configured with) while leaving in-memory
+ * state untouched, matching `clearPersistence`'s own contract. It is
+ * ALREADY a no-op when persistence was never enabled, so callers that
+ * invoke this defensively at startup are safe either way.
+ *
+ * `getFirestore(ctx)` (frozen `SandboxContext`) targets don't carry a
+ * live `Sandbox` handle with a `clearPersistence` method reachable the
+ * same way as a `sandbox`/`sandbox-live` target's `.sandbox` field —
+ * both variants do, in fact, so this always has a sandbox to call into.
+ *
+ * The real SDK requires this before Firestore starts; the sandbox's mapped
+ * `clearPersistence()` has no such restriction.
+ */
+export function clearIndexedDbPersistence(db) {
+    const target = targetOf(db);
+    return target.sandbox.clearPersistence();
+}
+/**
+ * Sandbox: no-op success. There is no network in the sandbox — every
+ * op is a local call into the in-memory/IndexedDB-backed store — so
+ * there is nothing to disable. This deliberately does NOT simulate an
+ * offline mode: queued writes still commit immediately rather than
+ * queuing, because the sandbox cannot honestly deliver "queued until
+ * reconnected" when there is no connection to lose in the first place.
+ * App code that calls this to prep for flaky connectivity will not
+ * crash, but it also will not observe write-queuing behavior.
+ *
+ */
+export function disableNetwork(db) {
+    targetOf(db);
+    return Promise.resolve();
+}
+/**
+ * Sandbox: no-op success, symmetric with {@link disableNetwork} — since
+ * network was never disabled locally, there is nothing to re-enable.
+ *
+ */
+export function enableNetwork(db) {
+    targetOf(db);
+    return Promise.resolve();
+}
+/**
+ * Sandbox: resolves immediately. The real SDK's version waits for
+ * queued writes to reach the server; the sandbox has no server to wait
+ * on — every write it accepts is already committed to the local store
+ * by the time the write's own promise resolves, so by the time this is
+ * called there are, honestly, never any writes still pending a round
+ * trip.
+ *
+ */
+export function waitForPendingWrites(db) {
+    targetOf(db);
+    return Promise.resolve();
+}
+/**
+ * Sandbox: genuinely tears the target down by calling
+ * `Sandbox.dispose()` — NOT a pure no-op like the rest of this family.
+ * `dispose()` tears down listener registries on the sandbox's
+ * environment without replacing it (idempotent, doesn't touch data).
+ * This is the honest mapping of "terminate this Firestore instance":
+ * a real app that calls `terminate(db)` expects listeners to stop and
+ * the instance to be unusable for further meaningful work, and
+ * `dispose()` delivers exactly that for the sandbox.
+ *
+ * Caveat: `dispose()` operates on the whole `Sandbox`, not a
+ * Firestore-only slice of it — if `pyric/database` or `pyric/storage`
+ * share the same `Sandbox`, their listener registries are torn down
+ * too. This differs from the real SDK, where `terminate()` only
+ * affects the one `Firestore` instance. Documented divergence.
+ *
+ */
+export function terminate(db) {
+    const target = targetOf(db);
+    target.sandbox.dispose();
+    return Promise.resolve();
+}
+// ─── Tier-1 cache-init + get-from-* + log-level + snapshot-sync ───────
+// (issue #144, tier-1 pass). These extend the honest-mirror rationale
+// above: a real app's explicit-init pattern —
+//
+//   initializeFirestore(app, {
+//     localCache: persistentLocalCache(persistentMultipleTabManager()),
+//   })
+//
+// — crashed at IMPORT (a missing named export) before this pass, before
+// the app ever ran a read or write. `initializeFirestore` and the six
+// cache-factory tokens below are aliases and honest no-op config
+// tokens, not new feature work: the sandbox is local-first with
+// persistence on by default, so there is no separate cache tier to
+// configure into existence. `getDocFromServer`/`getDocFromCache` and
+// their plural forms delegate to the same read path as `getDoc`/
+// `getDocs` (the sandbox store IS the authoritative, always-fresh source —
+// there's no cache/server split to honor). `setLogLevel` and
+// `onSnapshotsInSync` round out the surface a real app's init sequence
+// commonly touches alongside the persistence family.
+/** Hidden brand on {@link LocalCache} tokens returned by
+ *  {@link persistentLocalCache} / {@link memoryLocalCache}. Never
+ *  inspected by consumer code — `initializeFirestore` accepts the
+ *  token but the cache/network settings it carries are no-ops. */
+const LOCAL_CACHE_SYMBOL = Symbol('pyric/firestore/localCache');
+/** Hidden brand on tab-manager tokens returned by
+ *  {@link persistentSingleTabManager} / {@link persistentMultipleTabManager}. */
+const TAB_MANAGER_SYMBOL = Symbol('pyric/firestore/tabManager');
+/** Hidden brand on garbage-collector tokens returned by
+ *  {@link memoryEagerGarbageCollector} / {@link memoryLruGarbageCollector}. */
+const GC_SYMBOL = Symbol('pyric/firestore/gc');
+/**
+ * Inert config token. Real Firebase uses this to select an on-disk,
+ * persistent IndexedDB cache tier; the sandbox has no separate cache
+ * tier — persistence is already the default — so this just returns a
+ * tagged token `initializeFirestore` can accept without crashing.
+ */
+export function persistentLocalCache(settings) {
+    return { [LOCAL_CACHE_SYMBOL]: 'persistent', tabManager: settings?.tabManager };
+}
+/** Inert config token — the memory-cache counterpart of {@link persistentLocalCache}. */
+export function memoryLocalCache(settings) {
+    return { [LOCAL_CACHE_SYMBOL]: 'memory', garbageCollector: settings?.garbageCollector };
+}
+/** Inert config token accepted by {@link persistentLocalCache}'s `tabManager`. */
+export function persistentSingleTabManager(_settings) {
+    return { [TAB_MANAGER_SYMBOL]: 'single' };
+}
+/** Inert config token accepted by {@link persistentLocalCache}'s `tabManager`. */
+export function persistentMultipleTabManager() {
+    return { [TAB_MANAGER_SYMBOL]: 'multiple' };
+}
+/** Inert config token accepted by {@link memoryLocalCache}'s `garbageCollector`. */
+export function memoryEagerGarbageCollector() {
+    return { [GC_SYMBOL]: 'eager' };
+}
+/** Inert config token accepted by {@link memoryLocalCache}'s `garbageCollector`. */
+export function memoryLruGarbageCollector(_settings) {
+    return { [GC_SYMBOL]: 'lru' };
+}
+/**
+ * Delegates to {@link getFirestore} and returns the same handle. Accepts
+ * the `settings` argument (so the explicit-init pattern app code commonly
+ * writes — `initializeFirestore(app, { localCache: persistentLocalCache(...) } )`
+ * — no longer crashes at import) but no-ops the cache/network settings:
+ * persistence is already the sandbox default, so there is nothing left to
+ * configure into existence.
+ *
+ */
+export function initializeFirestore(app, _settings, _databaseId) {
+    return getFirestore(app);
+}
+/**
+ * Sandbox: delegates to {@link getDoc}. The sandbox store IS the
+ * authoritative, always-fresh source — there is no separate server
+ * round-trip to force, so "from server" and the default read are the
+ * same honest thing.
+ *
+ */
+export function getDocFromServer(ref) {
+    return getDoc(ref);
+}
+/** Query-plural form of {@link getDocFromServer}. */
+export function getDocsFromServer(query) {
+    return getDocs(query);
+}
+/**
+ * Sandbox: delegates to {@link getDoc}. Real Firebase THROWS
+ * `'unavailable'` here on a cache miss (nothing local matches the
+ * ref); pyric never misses — the local store always has whatever is
+ * there — so this never throws for that reason. Documented divergence,
+ * not a claim of parity.
+ *
+ */
+export function getDocFromCache(ref) {
+    return getDoc(ref);
+}
+/** Query-plural form of {@link getDocFromCache} — same cache-miss divergence. */
+export function getDocsFromCache(query) {
+    return getDocs(query);
+}
+/**
+ * Accepted no-op: the sandbox has no modular-SDK-style logger to wire
+ * a level into (it uses host-level `console` logging directly, gated
+ * by `pyric dev`'s own flags, not this call). Exists purely so app
+ * code that calls this defensively at startup doesn't crash on a
+ * missing export.
+ */
+export function setLogLevel(logLevel) {
+    void logLevel;
+}
+/**
+ * Sandbox: fires the callback once the current snapshot-delivery
+ * microtask queue settles — the closest honest approximation of "every
+ * active listener has delivered its latest state" available without a
+ * true cross-listener sync signal (the sandbox doesn't track one).
+ * This is NOT the real SDK's guarantee (which is scoped to actual
+ * server round-trips); it is scoped to local delivery only.
+ *
+ */
+export function onSnapshotsInSync(db, observerOrCallback) {
+    targetOf(db);
+    const cb = typeof observerOrCallback === 'function' ? observerOrCallback : observerOrCallback.next;
+    let cancelled = false;
+    queueMicrotask(() => {
+        if (!cancelled && cb)
+            cb();
+    });
+    return () => {
+        cancelled = true;
+    };
+}
+//# sourceMappingURL=persistence.js.map

package/dist/firestore/persistence.js.map

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

package/dist/firestore/query-constraints.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `pyric/firestore` — query builder + constraints.
+ *
+ * `query` and the constraint factories (`where` / `or` / `and` / `orderBy`
+ * / `limit` / `limitToLast` and the `startAt` / `startAfter` / `endAt` /
+ * `endBefore` cursors). Each constraint applies to the sandbox's chainable
+ * query representation.
+ */
+import type { Query as ChainQuery, Filter as ChainFilter, WhereFilterOp, OrderDirection } from 'pyric/sandbox/admin-firestore';
+import { FieldPath } from './field-values.js';
+import type { CollectionReference, Query, DocumentSnapshot, DocumentData } from './types.js';
+export interface QueryConstraint {
+    applySandbox(q: ChainQuery): ChainQuery;
+    /**
+     * Internal — the filter representation for composite-filter
+     * composition. `where()` populates it as a leaf; `or()` / `and()`
+     * combine sub-constraints' filters into a composite tree. Non-filter
+     * constraints (`orderBy`, `limit`) leave it undefined; passing one
+     * to `or()` / `and()` throws.
+     */
+    _sandboxFilter?: ChainFilter;
+}
+export declare function query<T = DocumentData>(source: CollectionReference<T> | Query<T>, ...constraints: QueryConstraint[]): Query<T>;
+export declare function where(field: string | FieldPath, op: WhereFilterOp, value: unknown): QueryConstraint;
+/**
+ * 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 declare function or(...filters: QueryConstraint[]): QueryConstraint;
+/**
+ * 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 declare function and(...filters: QueryConstraint[]): QueryConstraint;
+export declare function orderBy(field: string | FieldPath, direction?: OrderDirection): QueryConstraint;
+export declare function limit(n: number): QueryConstraint;
+/**
+ * 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 declare function limitToLast(n: number): QueryConstraint;
+/**
+ * Start the query at the document whose ordered field values match
+ * the cursor. Inclusive — the document at the cursor IS included in
+ * the result. Two overloads:
+ *
+ *   `startAt(snapshot)` — values come from `snapshot.data()` indexed
+ *     by the query's orderBy fields.
+ *   `startAt(...values)` — explicit positional values (one per
+ *     orderBy clause).
+ */
+export declare function startAt(snapshot: DocumentSnapshot): QueryConstraint;
+export declare function startAt(...values: unknown[]): QueryConstraint;
+/** Same as `startAt`, but EXCLUDES the document at the cursor — the
+ *  result starts at the next ordered position. */
+export declare function startAfter(snapshot: DocumentSnapshot): QueryConstraint;
+export declare function startAfter(...values: unknown[]): QueryConstraint;
+/** End the query at the document whose ordered field values match
+ *  the cursor. Inclusive — the document at the cursor IS included. */
+export declare function endAt(snapshot: DocumentSnapshot): QueryConstraint;
+export declare function endAt(...values: unknown[]): QueryConstraint;
+/** Same as `endAt`, but EXCLUDES the document at the cursor — the
+ *  result ends at the prior ordered position. */
+export declare function endBefore(snapshot: DocumentSnapshot): QueryConstraint;
+export declare function endBefore(...values: unknown[]): QueryConstraint;
+//# sourceMappingURL=query-constraints.d.ts.map

package/dist/firestore/query-constraints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-constraints.d.ts","sourceRoot":"","sources":["../../src/firestore/query-constraints.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAEV,KAAK,IAAI,UAAU,EACnB,MAAM,IAAI,WAAW,EACrB,aAAa,EACb,cAAc,EAEf,MAAM,+BAA+B,CAAC;AAUvC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EACV,mBAAmB,EACnB,KAAK,EACL,gBAAgB,EAChB,YAAY,EACb,MAAM,YAAY,CAAC;AAUpB,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACxC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED,wBAAgB,KAAK,CAAC,CAAC,GAAG,YAAY,EACpC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,EACzC,GAAG,WAAW,EAAE,eAAe,EAAE,GAChC,KAAK,CAAC,CAAC,CAAC,CAyBV;AAED,wBAAgB,KAAK,CACnB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,EAAE,EAAE,aAAa,EACjB,KAAK,EAAE,OAAO,GACb,eAAe,CAOjB;AAED;;;;;;;GAOG;AACH,wBAAgB,EAAE,CAAC,GAAG,OAAO,EAAE,eAAe,EAAE,GAAG,eAAe,CAEjE;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,GAAG,OAAO,EAAE,eAAe,EAAE,GAAG,eAAe,CAElE;AA+BD,wBAAgB,OAAO,CACrB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,SAAS,CAAC,EAAE,cAAc,GACzB,eAAe,CAKjB;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,eAAe,CAIhD;AAeD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,eAAe,CAItD;AA4BD;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,gBAAgB,GAAG,eAAe,CAAC;AACrE,wBAAgB,OAAO,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,eAAe,CAAC;AAa/D;kDACkD;AAClD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,gBAAgB,GAAG,eAAe,CAAC;AACxE,wBAAgB,UAAU,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,eAAe,CAAC;AAalE;sEACsE;AACtE,wBAAgB,KAAK,CAAC,QAAQ,EAAE,gBAAgB,GAAG,eAAe,CAAC;AACnE,wBAAgB,KAAK,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,eAAe,CAAC;AAa7D;iDACiD;AACjD,wBAAgB,SAAS,CAAC,QAAQ,EAAE,gBAAgB,GAAG,eAAe,CAAC;AACvE,wBAAgB,SAAS,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,eAAe,CAAC"}