@estra/client 0.0.0-stage → 0.1.0

package/dist/firestore.js

@@ -0,0 +1,576 @@
+import { getPath } from "./local.js";
+import { EstraClientError } from "./transport.js";
+export { EstraClientError as FirestoreError };
+const fail = (code, msg) => {
+    throw new EstraClientError(code, msg);
+};
+// ---- values -------------------------------------------------------------------------------
+export class Timestamp {
+    seconds;
+    nanoseconds;
+    constructor(seconds, nanoseconds) {
+        this.seconds = seconds;
+        this.nanoseconds = nanoseconds;
+    }
+    static now() {
+        return Timestamp.fromMillis(Date.now());
+    }
+    static fromDate(d) {
+        return Timestamp.fromMillis(d.getTime());
+    }
+    static fromMillis(ms) {
+        const s = Math.floor(ms / 1000);
+        return new Timestamp(s, Math.round((ms - s * 1000) * 1e6));
+    }
+    toMillis() {
+        return this.seconds * 1000 + Math.floor(this.nanoseconds / 1e6);
+    }
+    toDate() {
+        return new Date(this.toMillis());
+    }
+    isEqual(o) {
+        return o instanceof Timestamp && o.seconds === this.seconds && o.nanoseconds === this.nanoseconds;
+    }
+    valueOf() {
+        return String(this.toMillis()).padStart(20, "0");
+    }
+    toJSON() {
+        return { seconds: this.seconds, nanoseconds: this.nanoseconds };
+    }
+}
+export class GeoPoint {
+    latitude;
+    longitude;
+    constructor(latitude, longitude) {
+        this.latitude = latitude;
+        this.longitude = longitude;
+    }
+    isEqual(o) {
+        return o instanceof GeoPoint && o.latitude === this.latitude && o.longitude === this.longitude;
+    }
+}
+export class FieldValue {
+    wire;
+    constructor(wire) {
+        this.wire = wire;
+    }
+}
+export const serverTimestamp = () => new FieldValue({ $op: "now" });
+export const increment = (n) => new FieldValue({ $op: "inc", by: n });
+export const arrayUnion = (...values) => new FieldValue({ $op: "union", values: values.map(encode) });
+export const arrayRemove = (...values) => new FieldValue({ $op: "remove", values: values.map(encode) });
+export const deleteField = () => new FieldValue({ $op: "delete" });
+export class FieldPath {
+    segments;
+    constructor(...segments) {
+        this.segments = segments;
+    }
+}
+export const documentId = () => new FieldPath("__name__");
+function encode(v) {
+    if (v === undefined)
+        return fail("invalid-argument", "undefined is not a valid value (use null or deleteField())");
+    if (v === null || typeof v !== "object")
+        return v;
+    if (v instanceof FieldValue)
+        return v.wire;
+    if (v instanceof Timestamp)
+        return { $t: v.toMillis() };
+    if (v instanceof Date)
+        return { $t: v.getTime() };
+    if (v instanceof GeoPoint)
+        return { $geo: [v.latitude, v.longitude] };
+    if (v instanceof DocumentReference)
+        return { $ref: v.path };
+    if (Array.isArray(v))
+        return v.map(encode);
+    return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, encode(x)]));
+}
+function decode(db, v) {
+    if (v === null || typeof v !== "object")
+        return v;
+    if (Array.isArray(v))
+        return v.map((x) => decode(db, x));
+    const o = v;
+    const keys = Object.keys(o);
+    if (keys.length === 1 && typeof o.$t === "number")
+        return Timestamp.fromMillis(o.$t);
+    if (keys.length === 1 && Array.isArray(o.$geo))
+        return new GeoPoint(o.$geo[0], o.$geo[1]);
+    if (keys.length === 1 && typeof o.$ref === "string")
+        return new DocumentReference(db, o.$ref);
+    return Object.fromEntries(keys.map((k) => [k, decode(db, o[k])]));
+}
+const encodeData = (data) => {
+    if (typeof data !== "object" || data === null || Array.isArray(data))
+        fail("invalid-argument", "data must be an object");
+    const out = {};
+    // Dotted keys ("stats.plays") address a sub-field, as in Firestore's updateDoc.
+    for (const [k, v] of Object.entries(data))
+        out[k] = encode(v);
+    return out;
+};
+// ---- references -----------------------------------------------------------------------------
+export class Firestore {
+    type = "firestore";
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+}
+export const getFirestore = (t) => new Firestore("transport" in t ? t.transport : t);
+const cleanPath = (parts) => {
+    const p = parts.join("/").replace(/^\/+|\/+$/g, "");
+    if (!p || p.split("/").some((s) => !s))
+        fail("invalid-argument", `bad path "${parts.join("/")}"`);
+    return p;
+};
+const AUTO_ID = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+export const autoId = () => Array.from(crypto.getRandomValues(new Uint8Array(20)), (b) => AUTO_ID[b % 62]).join("");
+export class DocumentReference {
+    type = "document";
+    firestore;
+    path;
+    constructor(firestore, path) {
+        this.firestore = firestore;
+        this.path = path;
+        if (path.split("/").length % 2)
+            fail("invalid-argument", `"${path}" is a collection, not a document`);
+    }
+    get id() {
+        return this.path.split("/").pop();
+    }
+    get parent() {
+        return new CollectionReference(this.firestore, this.path.split("/").slice(0, -1).join("/"));
+    }
+}
+export class Query {
+    type = "query";
+    firestore;
+    state;
+    constructor(firestore, state) {
+        this.firestore = firestore;
+        this.state = state;
+    }
+    ast() {
+        const s = this.state;
+        return {
+            ...(s.from !== undefined ? { from: s.from } : { group: s.group }),
+            ...(s.where.length ? { where: s.where.length === 1 ? s.where[0] : { and: s.where } } : {}),
+            ...(s.orderBy.length ? { orderBy: s.orderBy } : {}),
+            ...(s.limit !== undefined ? { limit: s.limit } : {}),
+            ...(s.limitToLast !== undefined ? { limitToLast: s.limitToLast } : {}),
+            ...(s.startAfter ? { startAfter: s.startAfter } : {}),
+            ...(s.startAt ? { startAt: s.startAt } : {}),
+            ...(s.endAt ? { endAt: s.endAt } : {}),
+            ...(s.endBefore ? { endBefore: s.endBefore } : {}),
+            ...(s.near ? { near: s.near } : {}),
+        };
+    }
+}
+export class CollectionReference extends Query {
+    type = "collection";
+    path;
+    constructor(firestore, path) {
+        super(firestore, { from: path, where: [], orderBy: [] });
+        this.path = path;
+        if (path.split("/").length % 2 === 0)
+            fail("invalid-argument", `"${path}" is a document, not a collection`);
+    }
+    get id() {
+        return this.path.split("/").pop();
+    }
+    get parent() {
+        const p = this.path.split("/");
+        return p.length > 1 ? new DocumentReference(this.firestore, p.slice(0, -1).join("/")) : null;
+    }
+}
+export function doc(parent, path, ...more) {
+    if (parent instanceof Firestore)
+        return new DocumentReference(parent, cleanPath([path ?? fail("invalid-argument", "doc() needs a path"), ...more]));
+    if (parent instanceof CollectionReference)
+        return new DocumentReference(parent.firestore, cleanPath([parent.path, path ?? autoId(), ...more]));
+    return new DocumentReference(parent.firestore, cleanPath([parent.path, path ?? fail("invalid-argument", "doc() needs a path"), ...more]));
+}
+export function collection(parent, path, ...more) {
+    const db = parent instanceof Firestore ? parent : parent.firestore;
+    const base = parent instanceof Firestore ? [] : [parent.path];
+    return new CollectionReference(db, cleanPath([...base, path, ...more]));
+}
+export const collectionGroup = (db, id) => new Query(db, { group: id, where: [], orderBy: [] });
+const fieldName = (f) => (f instanceof FieldPath ? f.segments.join(".") : f);
+export class QueryConstraint {
+    apply;
+    constructor(apply) {
+        this.apply = apply;
+    }
+}
+export class QueryFilterConstraint extends QueryConstraint {
+    filter;
+    constructor(filter) {
+        super((s) => ({ ...s, where: [...s.where, filter] }));
+        this.filter = filter;
+    }
+}
+export function where(field, op, value) {
+    const name = fieldName(field);
+    let v = encode(value);
+    // documentId() compares ids; accept full paths or references like Firestore does.
+    if (name === "__name__") {
+        const id = (x) => (typeof x === "object" && x && "$ref" in x ? String(x.$ref) : String(x)).split("/").pop();
+        v = Array.isArray(v) ? v.map(id) : id(v);
+    }
+    return new QueryFilterConstraint({ field: name, op, value: v });
+}
+export const and = (...fs) => new QueryFilterConstraint({ and: fs.map((f) => f.filter) });
+export const or = (...fs) => new QueryFilterConstraint({ or: fs.map((f) => f.filter) });
+export const orderBy = (field, dir = "asc") => new QueryConstraint((s) => ({ ...s, orderBy: [...s.orderBy, { field: fieldName(field), dir }] }));
+// The last limit()/limitToLast() wins, as in Firestore.
+export const limit = (n) => new QueryConstraint((s) => ({ ...s, limit: n, limitToLast: undefined }));
+/** The last n results in orderBy order (needs an orderBy). */
+export const limitToLast = (n) => new QueryConstraint((s) => ({ ...s, limitToLast: n, limit: undefined }));
+function cursorValues(s, args) {
+    if (args.length === 1 && args[0] instanceof DocumentSnapshot) {
+        const snap = args[0];
+        const raw = snap._raw ?? fail("invalid-argument", "cursor document doesn't exist");
+        return [...s.orderBy.map((o) => (o.field === "__name__" || o.field === "id" ? raw.id : getPath(raw.data, o.field))), raw.id];
+    }
+    return args.map(encode);
+}
+export const startAfter = (...args) => new QueryConstraint((s) => ({ ...s, startAfter: cursorValues(s, args), startAt: undefined }));
+export const startAt = (...args) => new QueryConstraint((s) => ({ ...s, startAt: cursorValues(s, args), startAfter: undefined }));
+/**
+ * Radius search (an Estra addition): documents whose geo field is within `radiusMi` of `center`.
+ * Without an orderBy, results sort by distance; each snapshot's `distanceMi` says how far. Works
+ * in listeners too (moving documents enter and leave the results).
+ */
+export const near = (field, center, radiusMi) => new QueryConstraint((s) => ({ ...s, near: { field: fieldName(field), lat: center instanceof GeoPoint ? center.latitude : center.lat, lng: center instanceof GeoPoint ? center.longitude : center.lng, radiusMi } }));
+export const endAt = (...args) => new QueryConstraint((s) => ({ ...s, endAt: cursorValues(s, args), endBefore: undefined }));
+export const endBefore = (...args) => new QueryConstraint((s) => ({ ...s, endBefore: cursorValues(s, args), endAt: undefined }));
+export function query(q, ...constraints) {
+    return new Query(q.firestore, constraints.reduce((s, c) => c.apply(s), q.state));
+}
+const meta = (m) => {
+    const fromCache = !!m?.fromCache, hasPendingWrites = !!m?.hasPendingWrites;
+    return { fromCache, hasPendingWrites, isEqual: (o) => o.fromCache === fromCache && o.hasPendingWrites === hasPendingWrites };
+};
+export class DocumentSnapshot {
+    ref;
+    metadata;
+    _raw;
+    constructor(ref, raw, m) {
+        this.ref = ref;
+        this._raw = raw;
+        this.metadata = meta(m ?? raw?.meta);
+    }
+    get id() {
+        return this.ref.id;
+    }
+    exists() {
+        return this._raw !== null;
+    }
+    /** For `near` queries: miles from the query's center (an Estra addition). */
+    get distanceMi() {
+        return this._raw?.distanceMi;
+    }
+    data() {
+        return this._raw ? decode(this.ref.firestore, this._raw.data) : undefined;
+    }
+    get(field) {
+        const parts = field instanceof FieldPath ? field.segments : field.split(".");
+        let cur = this.data();
+        for (const p of parts)
+            cur = cur == null ? undefined : cur[p];
+        return cur;
+    }
+}
+export class QueryDocumentSnapshot extends DocumentSnapshot {
+    data() {
+        return super.data();
+    }
+}
+export class QuerySnapshot {
+    query;
+    docs;
+    metadata;
+    changes;
+    constructor(q, docs, changes = null, m) {
+        this.query = q;
+        this.docs = docs;
+        this.changes = changes;
+        this.metadata = meta(m ?? { fromCache: docs.some((d) => d.metadata.fromCache), hasPendingWrites: docs.some((d) => d.metadata.hasPendingWrites) });
+    }
+    /** Changes since the previous snapshot of a listener (all "added" for a one-off read). */
+    docChanges() {
+        return this.changes ?? this.docs.map((doc, i) => ({ type: "added", doc, oldIndex: -1, newIndex: i }));
+    }
+    get size() {
+        return this.docs.length;
+    }
+    get empty() {
+        return this.docs.length === 0;
+    }
+    forEach(cb) {
+        this.docs.forEach(cb);
+    }
+}
+// ---- reads ----------------------------------------------------------------------------------
+export async function getDoc(ref) {
+    const [raw] = await ref.firestore.transport.getAll([ref.path]);
+    return new DocumentSnapshot(ref, raw ?? null);
+}
+/** Without a limit, pages until every match is read (like Firestore), up to 50,000 documents. */
+const ALL_CAP = 50_000;
+export async function getDocs(q) {
+    const db = q.firestore;
+    const ast = q.ast();
+    const out = [];
+    let page = await db.transport.query(ast);
+    const fromCache = !!page.fromCache;
+    out.push(...page.docs);
+    while (ast.limit === undefined && ast.limitToLast === undefined && page.hasMore && page.docs.length && out.length < ALL_CAP) {
+        const last = page.docs[page.docs.length - 1];
+        const cursor = [...(ast.orderBy ?? []).map((o) => (o.field === "id" || o.field === "__name__" ? last.id : getPath(last.data, o.field))), last.id];
+        page = await db.transport.query({ ...ast, startAfter: cursor, startAt: undefined });
+        out.push(...page.docs);
+    }
+    const docs = out.map((d) => new QueryDocumentSnapshot(new DocumentReference(db, d.path), d));
+    return new QuerySnapshot(q, docs, null, { fromCache, hasPendingWrites: out.some((d) => d.v < 0) });
+}
+const controls = (db) => db.transport;
+export const waitForPendingWrites = (db) => controls(db).waitForPendingWrites?.() ?? Promise.resolve();
+export const disableNetwork = (db) => controls(db).disableNetwork?.() ?? fail("unimplemented", "disableNetwork needs offline()");
+export const enableNetwork = (db) => controls(db).enableNetwork?.() ?? Promise.resolve();
+export const clearIndexedDbPersistence = (db) => controls(db).clearPersistence?.() ?? Promise.resolve();
+export const clearPersistence = clearIndexedDbPersistence;
+export async function getCountFromServer(q) {
+    const r = await q.firestore.transport.aggregate({ ...q.ast(), aggregate: { count: true } });
+    return { data: () => ({ count: Number(r.count ?? 0) }) };
+}
+export const count = () => ({ kind: "count" });
+export const sum = (field) => ({ kind: "sum", field });
+export const average = (field) => ({ kind: "avg", field });
+const aggAst = (q, spec) => {
+    const specs = Object.values(spec);
+    return {
+        ...q.ast(),
+        aggregate: {
+            count: specs.some((s) => s.kind === "count"),
+            sum: specs.flatMap((s) => (s.kind === "sum" ? [s.field] : [])),
+            avg: specs.flatMap((s) => (s.kind === "avg" ? [s.field] : [])),
+        },
+    };
+};
+const aggData = (spec, r) => Object.fromEntries(Object.entries(spec).map(([k, s]) => [k, s.kind === "count" ? Number(r.count ?? 0) : (r[`${s.kind}:${s.field}`] ?? null)]));
+export async function getAggregateFromServer(q, spec) {
+    const data = aggData(spec, await q.firestore.transport.aggregate(aggAst(q, spec)));
+    return { data: () => data };
+}
+/**
+ * Live aggregates (an Estra addition; Firestore has none): calls `next` with the current values,
+ * then again whenever a matching document changes them. Same rules and caps as getAggregateFromServer.
+ *   onAggregateSnapshot(query(collection(db, "orders"), where("open", "==", true)), { n: count(), total: sum("amount") }, (s) => show(s.data()))
+ */
+export function onAggregateSnapshot(q, spec, next, error) {
+    const listen = q.firestore.transport.listen ?? fail("unimplemented", "this transport has no listeners (use httpTransport with a WebSocket)");
+    return listen({ query: aggAst(q, spec) }, {
+        next: (s) => {
+            if (!s.aggregate)
+                return;
+            const data = aggData(spec, s.aggregate);
+            next({ data: () => data });
+        },
+        error: (e) => error?.(new EstraClientError(e.code, e.message)),
+    });
+}
+const setWrite = (ref, data, o) => ({ op: "set", path: ref.path, data: encodeData(data), ...(o?.merge ? { merge: true } : {}) });
+function updateWrite(ref, a, rest) {
+    const data = typeof a === "string" || a instanceof FieldPath ? {} : a;
+    if (typeof a === "string" || a instanceof FieldPath) {
+        const pairs = [a, ...rest];
+        for (let i = 0; i < pairs.length; i += 2)
+            data[fieldName(pairs[i])] = pairs[i + 1];
+    }
+    return { op: "update", path: ref.path, data: encodeData(data) };
+}
+const commitOne = async (db, w) => {
+    await db.transport.commit({ writes: [w] });
+};
+/**
+ * Hot counters: adds `by` to a number field through the server's counter buffer (one commit about
+ * every second, however many calls). Resolves with the new value (stored + buffered). Needs
+ * `createEstra({ counters })`, and passes the document's update rule per call. Online only.
+ */
+export async function incrementBuffered(ref, field, by = 1) {
+    const inc = ref.firestore.transport.counterInc ?? fail("unimplemented", "this transport has no counters (use httpTransport)");
+    return (await inc(ref.path, fieldName(field), by)).value;
+}
+export const setDoc = (ref, data, o) => commitOne(ref.firestore, setWrite(ref, data, o));
+export const updateDoc = (ref, a, ...rest) => commitOne(ref.firestore, updateWrite(ref, a, rest));
+export const deleteDoc = (ref) => commitOne(ref.firestore, { op: "delete", path: ref.path });
+export async function addDoc(coll, data) {
+    const ref = doc(coll);
+    await coll.firestore.transport.commit({ writes: [{ ...setWrite(ref, data), pre: { exists: false } }] });
+    return ref;
+}
+export class WriteBatch {
+    db;
+    writes = [];
+    constructor(db) {
+        this.db = db;
+    }
+    set(ref, data, o) {
+        this.writes.push(setWrite(ref, data, o));
+        return this;
+    }
+    update(ref, a, ...rest) {
+        this.writes.push(updateWrite(ref, a, rest));
+        return this;
+    }
+    delete(ref) {
+        this.writes.push({ op: "delete", path: ref.path });
+        return this;
+    }
+    async commit() {
+        if (this.writes.length)
+            await this.db.transport.commit({ writes: this.writes });
+    }
+}
+export const writeBatch = (db) => new WriteBatch(db);
+export class Transaction {
+    db;
+    reads = new Map();
+    writes = [];
+    constructor(db) {
+        this.db = db;
+    }
+    async get(ref) {
+        if (this.writes.length)
+            fail("invalid-argument", "transactions must read before they write");
+        const snap = await getDoc(ref);
+        this.reads.set(ref.path, snap._raw?.v ?? 0);
+        return snap;
+    }
+    set(ref, data, o) {
+        this.writes.push(setWrite(ref, data, o));
+        return this;
+    }
+    update(ref, a, ...rest) {
+        this.writes.push(updateWrite(ref, a, rest));
+        return this;
+    }
+    delete(ref) {
+        this.writes.push({ op: "delete", path: ref.path });
+        return this;
+    }
+}
+/** Reads, then writes guarded on the versions read; retried when a read went stale. */
+export async function runTransaction(db, fn, o = {}) {
+    const max = o.maxAttempts ?? 5;
+    for (let attempt = 1;; attempt++) {
+        const t = new Transaction(db);
+        const result = await fn(t);
+        const writes = t.writes.map((w) => (t.reads.has(w.path) ? { ...w, pre: { ...w.pre, version: t.reads.get(w.path) } } : w));
+        // Documents read but not written are guarded too: the commit fails if any of them changed.
+        const written = new Set(t.writes.map((w) => w.path));
+        for (const [path, version] of t.reads)
+            if (!written.has(path))
+                writes.push({ op: "check", path, pre: { version } });
+        try {
+            if (t.writes.length)
+                await db.transport.commit({ writes });
+            return result;
+        }
+        catch (e) {
+            const stale = e instanceof EstraClientError && (e.code === "failed-precondition" || e.code === "aborted");
+            if (!stale || attempt >= max)
+                throw e;
+        }
+    }
+}
+export function onSnapshot(target, ...args) {
+    let includeMeta = false;
+    if (args[0] && typeof args[0] === "object" && !("next" in args[0]) && !("error" in args[0]))
+        includeMeta = !!args.shift().includeMetadataChanges;
+    const obs = typeof args[0] === "function" ? { next: args[0], error: args[1] } : (args[0] ?? {});
+    const db = target.firestore;
+    const listen = db.transport.listen ?? fail("unimplemented", "this transport has no listeners (use httpTransport with a WebSocket)");
+    const onError = (e) => obs.error?.(new EstraClientError(e.code, e.message));
+    // Like Firestore, snapshots whose only change is metadata (fromCache, hasPendingWrites) are
+    // skipped unless includeMetadataChanges is set.
+    const metaKey = (m) => `${!!m?.fromCache}|${!!m?.hasPendingWrites}`;
+    const sameData = (a, b) => (!a && !b) || (!!a && !!b && (a.v === b.v || JSON.stringify(a.data) === JSON.stringify(b.data)));
+    if (target instanceof DocumentReference) {
+        let cur = null;
+        let first = true;
+        let lastMeta = "";
+        return listen({ doc: target.path }, {
+            next: (s) => {
+                const prev = cur;
+                cur = s.docs[0] ?? (s.removed?.length || s.reset ? null : cur);
+                const meta = metaKey(s.meta);
+                const quiet = !first && sameData(prev, cur) && (!includeMeta || meta === lastMeta);
+                first = false;
+                lastMeta = meta;
+                if (!quiet)
+                    obs.next?.(new DocumentSnapshot(target, cur, s.meta));
+            },
+            error: onError,
+            resume: () => (first ? undefined : cur ? { [cur.path]: cur.v } : {}),
+        });
+    }
+    const q = target;
+    const cache = new Map();
+    let order = [];
+    let first = true;
+    let lastMeta = "";
+    return listen({ query: q.ast() }, {
+        resume: () => (first ? undefined : Object.fromEntries([...cache.values()].filter((d) => d.v > 0).map((d) => [d.path, d.v]))),
+        next: (s) => {
+            const prevOrder = order;
+            const prevDocs = new Map(prevOrder.map((p) => [p, cache.get(p)]));
+            if (s.reset)
+                cache.clear();
+            for (const p of s.removed ?? [])
+                cache.delete(p);
+            for (const d of s.docs)
+                cache.set(d.path, d);
+            order = s.order ?? order;
+            const snap = (p) => new QueryDocumentSnapshot(new DocumentReference(db, p), cache.get(p));
+            const docs = order.filter((p) => cache.has(p)).map(snap);
+            const changes = [];
+            if (!first) {
+                const now = new Set(order);
+                prevOrder.forEach((p, i) => {
+                    if (!now.has(p))
+                        changes.push({ type: "removed", doc: new QueryDocumentSnapshot(new DocumentReference(db, p), { path: p, id: p.split("/").pop(), v: 0, createTime: 0, updateTime: 0, data: {} }), oldIndex: i, newIndex: -1 });
+                });
+                order.forEach((p, i) => {
+                    const was = prevOrder.indexOf(p);
+                    if (was < 0)
+                        changes.push({ type: "added", doc: snap(p), oldIndex: -1, newIndex: i });
+                    else {
+                        const before = prevDocs.get(p);
+                        const after = cache.get(p);
+                        // A data change, or (with includeMetadataChanges) a pending write that got confirmed.
+                        const metaOnly = sameData(before, after) && before?.v !== after?.v && (before?.v ?? 0) < 0 !== (after?.v ?? 0) < 0;
+                        if (!sameData(before, after) || (includeMeta && metaOnly))
+                            changes.push({ type: "modified", doc: snap(p), oldIndex: was, newIndex: i });
+                    }
+                });
+                for (const p of prevOrder)
+                    if (!new Set(order).has(p))
+                        cache.delete(p);
+            }
+            const meta = metaKey(s.meta);
+            const moved = prevOrder.join("\n") !== order.join("\n");
+            const quiet = !first && !changes.length && !moved && (!includeMeta || meta === lastMeta);
+            const out = new QuerySnapshot(q, docs, first ? null : changes, s.meta);
+            first = false;
+            lastMeta = meta;
+            if (!quiet)
+                obs.next?.(out);
+        },
+        error: onError,
+    });
+}

package/dist/functions.d.ts

@@ -0,0 +1,20 @@
+export interface Functions {
+    url: string;
+    getToken?: () => Promise<string | null> | string | null;
+    fetch?: typeof fetch;
+}
+export declare class FunctionsError extends Error {
+    /** "functions/<code>" as in the Firebase SDK: functions/not-found, functions/permission-denied … */
+    readonly code: string;
+    readonly details: unknown;
+    constructor(code: string, message: string, details?: unknown);
+}
+export declare const getFunctions: (o: Functions) => Functions;
+export interface HttpsCallableOptions {
+    /** Milliseconds before the call fails with functions/deadline-exceeded (default 70 s, like Firebase). */
+    timeout?: number;
+}
+export type HttpsCallable<Req, Res> = (data?: Req | null) => Promise<{
+    data: Res;
+}>;
+export declare function httpsCallable<Req = unknown, Res = unknown>(f: Functions, name: string, o?: HttpsCallableOptions): HttpsCallable<Req, Res>;

package/dist/functions.js

@@ -0,0 +1,43 @@
+// Callable functions with Firebase's shapes (firebase/functions → @estra/client/functions):
+//
+//   const functions = getFunctions({ url: "https://api.example.com", getToken: () => auth.getIdToken() });
+//   const addMessage = httpsCallable<{ text: string }, { ok: boolean }>(functions, "addMessage");
+//   const { data } = await addMessage({ text: "hi" });
+//
+// Values travel as JSON (as with Firebase callables; Timestamps arrive as plain objects).
+export class FunctionsError extends Error {
+    /** "functions/<code>" as in the Firebase SDK: functions/not-found, functions/permission-denied … */
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = `functions/${code}`;
+        this.details = details;
+        this.name = "FunctionsError";
+    }
+}
+export const getFunctions = (o) => o;
+export function httpsCallable(f, name, o = {}) {
+    return async (data) => {
+        const token = f.getToken ? await f.getToken() : null;
+        const headers = { "content-type": "application/json" };
+        if (token)
+            headers.authorization = `Bearer ${token}`;
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), o.timeout ?? 70_000);
+        let r;
+        try {
+            r = await (f.fetch ?? fetch)(`${f.url.replace(/\/$/, "")}/v1/fn/${encodeURIComponent(name)}`, { method: "POST", headers, body: JSON.stringify({ data: data ?? null }), signal: ac.signal });
+        }
+        catch {
+            throw ac.signal.aborted ? new FunctionsError("deadline-exceeded", "the call timed out") : new FunctionsError("unavailable", "network request failed");
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const j = (await r.json().catch(() => ({})));
+        if (!r.ok || j.error)
+            throw new FunctionsError(j.error?.code ?? (r.status >= 500 ? "internal" : "unknown"), j.error?.message ?? `HTTP ${r.status}`, j.error?.details);
+        return { data: j.result };
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./transport.js";
+export * from "./realtime.js";
+export * from "./offline.js";
+export * from "./store.js";
+export { applyWrite, runLocal, matchesFilter } from "./local.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./transport.js";
+export * from "./realtime.js";
+export * from "./offline.js";
+export * from "./store.js";
+export { applyWrite, runLocal, matchesFilter } from "./local.js";

package/dist/local.d.ts

@@ -0,0 +1 @@
+export { applyWrite, getPath, inCollection, matchesFilter, matchesQuery, orderComparator, runLocal } from "./_schema/index.js";

package/dist/local.js

@@ -0,0 +1,2 @@
+// The in-memory query engine lives in @estra/schema (shared with the server's realtime sessions).
+export { applyWrite, getPath, inCollection, matchesFilter, matchesQuery, orderComparator, runLocal } from "./_schema/index.js";

package/dist/offline.d.ts

@@ -0,0 +1,15 @@
+import { type CacheStore } from "./store.js";
+import { type Transport } from "./transport.js";
+export interface OfflineOptions {
+    store?: CacheStore;
+    /** First retry delay after a failed flush (doubles up to 60 s). Default 1 s. */
+    retryMs?: number;
+}
+export interface OfflineTransport extends Transport {
+    waitForPendingWrites(): Promise<void>;
+    disableNetwork(): Promise<void>;
+    enableNetwork(): Promise<void>;
+    clearPersistence(): Promise<void>;
+    readonly pendingWrites: number;
+}
+export declare function offline(inner: Transport, o?: OfflineOptions): OfflineTransport;