@estra/client 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Realm 8
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @estra/client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The client for [Estra](https://estra.cloud): documents and queries, live listeners, auth and callable
+functions. It runs in browsers, in Node 20+ and on edge runtimes, and has no dependencies.
+
+```sh
+npm install @estra/client
+```
+
+## Firebase-compatible API
+
+If your app uses the Firebase web SDK, switch the imports and point the app at your Estra URL:
+
+```ts
+import { initializeApp } from "@estra/client/compat/app";
+import { getAuth, signInWithEmailAndPassword } from "@estra/client/compat/auth";
+import { collection, getFirestore, onSnapshot, query, where } from "@estra/client/compat/firestore";
+
+const app = initializeApp({ estraUrl: "https://my-app.estra.cloud" });
+const auth = getAuth(app);
+const db = getFirestore(app);
+
+await signInWithEmailAndPassword(auth, "ann@example.com", "password");
+onSnapshot(query(collection(db, "posts"), where("authorId", "==", auth.currentUser!.uid)), (snap) => {
+  for (const d of snap.docs) console.log(d.id, d.data());
+});
+```
+
+`@estra/client/compat/storage` covers file storage the same way.
+
+## Callable functions
+
+```ts
+import { getFunctions, httpsCallable } from "@estra/client/functions";
+
+const functions = getFunctions({ url: "https://my-app.estra.cloud", getToken: () => auth.currentUser?.getIdToken() ?? null });
+const { data } = await httpsCallable(functions, "addPost")({ title: "Hello" });
+```
+
+## Servers and scripts
+
+`httpTransport` reads and writes as whoever its token belongs to. With your project's service key it
+acts as an admin and skips security rules, so keep that key on servers only.
+
+```ts
+import { httpTransport } from "@estra/client";
+
+const db = httpTransport({ url: "https://my-app.estra.cloud", getToken: () => process.env.ESTRA_SERVICE_KEY!, WebSocket: false });
+const [post] = await db.getAll(["posts/p1"]);
+await db.commit({ writes: [{ op: "update", path: "posts/p1", data: { score: { $op: "inc", by: 1 } } }] });
+const { docs } = await db.query({ from: "posts", where: { field: "score", op: ">", value: 10 }, limit: 20 });
+```
+
+MIT licensed.

package/dist/_schema/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./query.js";
+export * from "./local.js";

package/dist/_schema/index.js

@@ -0,0 +1,2 @@
+export * from "./query.js";
+export * from "./local.js";

package/dist/_schema/local.d.ts

@@ -0,0 +1,14 @@
+import { type DocOut, type Filter, type Query, type Write } from "./query.js";
+/** The value at a dotted path ("stats.plays"), or undefined. */
+export declare function getPath(o: Record<string, unknown>, path: string): unknown;
+/** A doc's data after a write, or null after a delete. `now` stands in for serverTimestamp. Keys may be dotted. */
+export declare function applyWrite(before: Record<string, unknown> | null, w: Write, now: number): Record<string, unknown> | null;
+export declare function matchesFilter(d: DocOut, f: Filter | undefined): boolean;
+/** Is this document in the query's collection (path or group)? */
+export declare function inCollection(d: DocOut, q: Query): boolean;
+/** Compares two docs in the query's result order (orderBy, then id). */
+export declare function orderComparator(query: Query): (a: DocOut, b: DocOut) => number;
+/** Could this doc be in the query's results, ignoring limit/limitToLast/offset? */
+export declare function matchesQuery(d: DocOut, q: Query): boolean;
+/** Runs a query over documents in memory, with Firestore/Estra semantics. */
+export declare function runLocal(docs: Iterable<DocOut>, query: Query): DocOut[];

package/dist/_schema/local.js

@@ -0,0 +1,186 @@
+// In-memory evaluation over wire-format documents: apply a write (sentinels included) and run a
+// query (filters, order, cursors, limit, near). Clients use it for the offline cache and latency
+// compensation; the server's realtime sessions use it to skip re-reads a change can't affect.
+// Mirrors the SQL engine's semantics (packages/server/src/compile.ts): keep them in step.
+import { withImplicitOrder } from "./query.js";
+const isObj = (x) => typeof x === "object" && x !== null && !Array.isArray(x);
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const isSentinel = (v) => isObj(v) && typeof v.$op === "string";
+/** The value at a dotted path ("stats.plays"), or undefined. */
+export function getPath(o, path) {
+    let cur = o;
+    for (const k of path.split("."))
+        cur = isObj(cur) ? cur[k] : undefined;
+    return cur;
+}
+function setPath(o, path, v) {
+    const segs = path.split(".");
+    let cur = o;
+    for (const k of segs.slice(0, -1)) {
+        if (!isObj(cur[k]))
+            cur[k] = {};
+        cur = cur[k];
+    }
+    const last = segs[segs.length - 1];
+    if (v === undefined || v === null)
+        delete cur[last];
+    else
+        cur[last] = v;
+}
+/** A doc's data after a write, or null after a delete. `now` stands in for serverTimestamp. Keys may be dotted. */
+export function applyWrite(before, w, now) {
+    if (w.op === "delete")
+        return null;
+    if (w.op === "check")
+        return before;
+    const out = w.op === "set" && !w.merge ? {} : structuredClone(before ?? {});
+    for (const [k, v] of Object.entries(w.data)) {
+        if (!isSentinel(v)) {
+            setPath(out, k, v);
+            continue;
+        }
+        const cur = getPath(out, k);
+        if (v.$op === "delete")
+            setPath(out, k, undefined);
+        else if (v.$op === "now")
+            setPath(out, k, { $t: now });
+        else if (v.$op === "inc")
+            setPath(out, k, (typeof cur === "number" ? cur : 0) + (v.by ?? 0));
+        else if (v.$op === "union") {
+            const arr = Array.isArray(cur) ? [...cur] : [];
+            for (const e of v.values ?? [])
+                if (!arr.some((x) => same(x, e)))
+                    arr.push(e);
+            setPath(out, k, arr);
+        }
+        else if (v.$op === "remove")
+            setPath(out, k, (Array.isArray(cur) ? cur : []).filter((x) => !(v.values ?? []).some((r) => same(x, r))));
+    }
+    return out;
+}
+/** Comparable form of a wire value (timestamps → ms, refs → path). */
+const key = (v) => (isObj(v) && typeof v.$t === "number" ? v.$t : isObj(v) && typeof v.$ref === "string" ? v.$ref : typeof v === "boolean" ? (v ? 1 : 0) : v);
+function cmp(a, b) {
+    const x = key(a), y = key(b);
+    if (typeof x === "number" && typeof y === "number")
+        return x - y;
+    if (typeof x === "string" && typeof y === "string")
+        return x < y ? -1 : x > y ? 1 : 0;
+    return null;
+}
+const fieldOf = (d, f) => (f === "id" || f === "__name__" ? d.id : getPath(d.data, f));
+export function matchesFilter(d, f) {
+    if (!f)
+        return true;
+    if ("and" in f)
+        return f.and.every((x) => matchesFilter(d, x));
+    if ("or" in f)
+        return f.or.some((x) => matchesFilter(d, x));
+    const v = fieldOf(d, f.field);
+    const missing = v === undefined || v === null;
+    const eq = (a, b) => same(key(a), key(b));
+    switch (f.op) {
+        case "==":
+            return f.value === null ? missing : !missing && eq(v, f.value);
+        case "!=":
+            return f.value === null ? !missing : !missing && !eq(v, f.value);
+        case "<":
+        case "<=":
+        case ">":
+        case ">=": {
+            if (missing)
+                return false;
+            const c = cmp(v, f.value);
+            if (c === null)
+                return false;
+            return f.op === "<" ? c < 0 : f.op === "<=" ? c <= 0 : f.op === ">" ? c > 0 : c >= 0;
+        }
+        case "in":
+            return !missing && Array.isArray(f.value) && f.value.some((x) => eq(v, x));
+        case "not-in":
+            return !missing && Array.isArray(f.value) && !f.value.some((x) => eq(v, x));
+        case "array-contains":
+            return Array.isArray(v) && v.some((x) => eq(x, f.value));
+        case "array-contains-any":
+            return Array.isArray(v) && Array.isArray(f.value) && v.some((x) => f.value.some((y) => eq(x, y)));
+    }
+    return false;
+}
+const haversineMi = (a, b, c, d) => {
+    const r = (x) => (x * Math.PI) / 180;
+    const h = Math.sin(r(c - a) / 2) ** 2 + Math.cos(r(a)) * Math.cos(r(c)) * Math.sin(r(d - b) / 2) ** 2;
+    return 3958.8 * 2 * Math.asin(Math.min(1, Math.sqrt(h)));
+};
+/** Is this document in the query's collection (path or group)? */
+export function inCollection(d, q) {
+    const segs = d.path.split("/");
+    if (q.group !== undefined)
+        return segs[segs.length - 2] === q.group;
+    return segs.slice(0, -1).join("/") === q.from;
+}
+const orderKeys = (q) => {
+    const orders = q.orderBy ?? [];
+    return orders.some((o) => o.field === "id" || o.field === "__name__") ? orders : [...orders, { field: "id", dir: orders.at(-1)?.dir ?? "asc" }];
+};
+/** Compares two docs in the query's result order (orderBy, then id). */
+export function orderComparator(query) {
+    const keys = orderKeys(withImplicitOrder(query));
+    return (a, b) => {
+        for (const k of keys) {
+            const c = cmp(fieldOf(a, k.field), fieldOf(b, k.field)) ?? 0;
+            if (c)
+                return k.dir === "desc" ? -c : c;
+        }
+        return 0;
+    };
+}
+/** Could this doc be in the query's results, ignoring limit/limitToLast/offset? */
+export function matchesQuery(d, q) {
+    return runLocal([d], { ...q, limit: undefined, limitToLast: undefined, offset: undefined }).length === 1;
+}
+/** Runs a query over documents in memory, with Firestore/Estra semantics. */
+export function runLocal(docs, query) {
+    const q = withImplicitOrder(query);
+    let out = [...docs].filter((d) => inCollection(d, q) && matchesFilter(d, q.where));
+    const orders = q.orderBy ?? [];
+    for (const o of orders)
+        if (o.field !== "id" && o.field !== "__name__")
+            out = out.filter((d) => getPath(d.data, o.field) !== undefined && getPath(d.data, o.field) !== null);
+    if (q.near) {
+        const n = q.near;
+        out = out.flatMap((d) => {
+            const g = getPath(d.data, n.field);
+            if (!g?.$geo)
+                return [];
+            const dist = haversineMi(n.lat, n.lng, g.$geo[0], g.$geo[1]);
+            return dist <= n.radiusMi ? [{ ...d, distanceMi: Math.round(dist * 100) / 100 }] : [];
+        });
+    }
+    const keys = orderKeys(q);
+    const sortKey = orderComparator(q);
+    if (q.near && !orders.length)
+        out.sort((a, b) => (a.distanceMi ?? 0) - (b.distanceMi ?? 0));
+    else
+        out.sort(sortKey);
+    // Where a doc sits against a cursor in result order: <0 before it, 0 on it, >0 past it.
+    const against = (d, cursor) => {
+        for (let i = 0; i < cursor.length; i++) {
+            const k = keys[i];
+            const c = cmp(fieldOf(d, k.field), cursor[i]) ?? 0;
+            if (c)
+                return k.dir === "desc" ? -c : c;
+        }
+        return 0;
+    };
+    const start = q.startAfter ?? q.startAt;
+    if (start)
+        out = out.filter((d) => (q.startAt ? against(d, start) >= 0 : against(d, start) > 0));
+    const end = q.endBefore ?? q.endAt;
+    if (end)
+        out = out.filter((d) => (q.endAt ? against(d, end) <= 0 : against(d, end) < 0));
+    if (q.offset)
+        out = out.slice(q.offset);
+    if (q.limitToLast !== undefined)
+        return out.slice(Math.max(0, out.length - q.limitToLast));
+    return q.limit !== undefined ? out.slice(0, q.limit) : out;
+}

package/dist/_schema/query.d.ts

@@ -0,0 +1,132 @@
+export type Op = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not-in" | "array-contains" | "array-contains-any";
+export interface FieldFilter {
+    field: string;
+    op: Op;
+    value: unknown;
+}
+export type Filter = FieldFilter | {
+    and: Filter[];
+} | {
+    or: Filter[];
+};
+export interface Order {
+    field: string;
+    dir?: "asc" | "desc";
+}
+export interface Near {
+    field: string;
+    lat: number;
+    lng: number;
+    radiusMi: number;
+}
+export interface Query {
+    /** Collection path ("posts", "posts/abc/comments"), or `group` for every parent at once. */
+    from?: string;
+    /** Collection id for a collection-group query ("comments"). */
+    group?: string;
+    where?: Filter;
+    orderBy?: Order[];
+    limit?: number;
+    /** The last N results in orderBy order (needs an orderBy; not with limit). */
+    limitToLast?: number;
+    /** Skip this many results first (with limit, not limitToLast). Service key only (clients page with cursors); at most 10,000. */
+    offset?: number;
+    /** Cursor values in orderBy order, optionally followed by the document id. */
+    startAfter?: unknown[];
+    startAt?: unknown[];
+    /** Upper cursors, same shape as the start ones. */
+    endAt?: unknown[];
+    endBefore?: unknown[];
+    /** Points within radiusMi of (lat, lng). Results carry `distanceMi`. */
+    near?: Near;
+    aggregate?: {
+        count?: boolean;
+        sum?: string[];
+        avg?: string[];
+    };
+}
+/** Field value sentinels (the Firestore FieldValue equivalents). */
+export type Sentinel = {
+    $op: "inc";
+    by: number;
+} | {
+    $op: "union";
+    values: unknown[];
+} | {
+    $op: "remove";
+    values: unknown[];
+} | {
+    $op: "now";
+} | {
+    $op: "delete";
+};
+export interface Precondition {
+    exists?: boolean;
+    /** Row version (`v` of a read); 0 = must not exist. */
+    version?: number;
+}
+export type Write = {
+    op: "set";
+    path: string;
+    data: Record<string, unknown>;
+    merge?: boolean;
+    pre?: Precondition;
+} | {
+    op: "update";
+    path: string;
+    data: Record<string, unknown>;
+    pre?: Precondition;
+} | {
+    op: "delete";
+    path: string;
+    pre?: Precondition;
+}
+/** Writes nothing: only asserts `pre` (transactions guard the documents they read but don't write). */
+ | {
+    op: "check";
+    path: string;
+    pre: Precondition;
+};
+export interface CommitRequest {
+    writes: Write[];
+    /** Idempotency key: a commit replayed with the same key is applied once. */
+    opKey?: string;
+}
+export interface DocOut {
+    path: string;
+    id: string;
+    v: number;
+    createTime: number;
+    updateTime: number;
+    data: Record<string, unknown>;
+    distanceMi?: number;
+    /** Set by the client's offline cache: where this copy came from. */
+    meta?: {
+        fromCache: boolean;
+        hasPendingWrites: boolean;
+    };
+}
+export declare const inc: (by?: number) => Sentinel;
+export declare const arrayUnion: (...values: unknown[]) => Sentinel;
+export declare const arrayRemove: (...values: unknown[]) => Sentinel;
+export declare const serverTimestamp: () => Sentinel;
+export declare const deleteField: () => Sentinel;
+/** Tagged wire values: timestamps, refs and points. */
+export declare const ts: (ms: number) => {
+    $t: number;
+};
+export declare const ref: (path: string) => {
+    $ref: string;
+};
+export declare const geo: (lat: number, lng: number) => {
+    $geo: [number, number];
+};
+/**
+ * Firestore's implicit order: a query with inequality filters and no orderBy is ordered by the
+ * inequality fields (ascending, by field name), then by id. Everything that orders results (SQL,
+ * the gateway's paging, the in-memory engine) goes through this, so a `limit` keeps the same rows.
+ * https://firebase.google.com/docs/firestore/query-data/order-limit-data#limitations
+ */
+export declare function withImplicitOrder<Q extends Query>(q: Q): Q & {
+    orderBy?: Order[];
+};

package/dist/_schema/query.js

@@ -0,0 +1,34 @@
+// The query and write AST: the JSON every client sends (POST /v1/query, /v1/commit).
+export const inc = (by = 1) => ({ $op: "inc", by });
+export const arrayUnion = (...values) => ({ $op: "union", values });
+export const arrayRemove = (...values) => ({ $op: "remove", values });
+export const serverTimestamp = () => ({ $op: "now" });
+export const deleteField = () => ({ $op: "delete" });
+/** Tagged wire values: timestamps, refs and points. */
+export const ts = (ms) => ({ $t: ms });
+export const ref = (path) => ({ $ref: path });
+export const geo = (lat, lng) => ({ $geo: [lat, lng] });
+const INEQUALITY = new Set(["<", "<=", ">", ">=", "!=", "not-in"]);
+/**
+ * Firestore's implicit order: a query with inequality filters and no orderBy is ordered by the
+ * inequality fields (ascending, by field name), then by id. Everything that orders results (SQL,
+ * the gateway's paging, the in-memory engine) goes through this, so a `limit` keeps the same rows.
+ * https://firebase.google.com/docs/firestore/query-data/order-limit-data#limitations
+ */
+export function withImplicitOrder(q) {
+    if (q.orderBy?.length || q.near)
+        return q;
+    const fields = new Set();
+    const walk = (f) => {
+        if (!f)
+            return;
+        if ("and" in f)
+            f.and.forEach(walk);
+        else if ("or" in f)
+            f.or.forEach(walk);
+        else if (INEQUALITY.has(f.op) && f.field !== "id" && f.field !== "__name__")
+            fields.add(f.field);
+    };
+    walk(q.where);
+    return fields.size ? { ...q, orderBy: [...fields].sort().map((field) => ({ field, dir: "asc" })) } : q;
+}

package/dist/auth.d.ts

@@ -0,0 +1,108 @@
+export interface AuthUser {
+    uid: string;
+    email: string | null;
+    emailVerified: boolean;
+    displayName: string | null;
+    photoUrl: string | null;
+    anonymous: boolean;
+    disabled: boolean;
+    providers: string[];
+    createdAt: number;
+    lastSignInAt: number | null;
+    /** Sessions from before this time (ms) were revoked; null when never revoked. */
+    tokensValidAfter?: number | null;
+    claims: Record<string, unknown>;
+}
+/** Where the session lives: localStorage on the web, Keychain/Keystore on mobile, memory in tests. */
+export interface SessionStorage {
+    get(key: string): string | null | Promise<string | null>;
+    set(key: string, value: string): void | Promise<void>;
+    remove(key: string): void | Promise<void>;
+}
+export declare const memoryStorage: () => SessionStorage;
+export declare const browserStorage: () => SessionStorage;
+/** The slice of `window` the popup/redirect flows use (injectable for tests). */
+export interface WindowLike {
+    location: {
+        origin: string;
+        href: string;
+        hash: string;
+        assign(url: string): void;
+    };
+    open(url: string, target?: string, features?: string): {
+        closed: boolean;
+        location: {
+            href: string;
+        };
+        close(): void;
+    } | null;
+    addEventListener(type: "message", fn: (e: {
+        origin: string;
+        data: unknown;
+        source?: unknown;
+    }) => void): void;
+    removeEventListener(type: "message", fn: (e: {
+        origin: string;
+        data: unknown;
+        source?: unknown;
+    }) => void): void;
+    history?: {
+        replaceState(data: unknown, unused: string, url: string): void;
+    };
+}
+export type OAuthProvider = "google.com" | "apple.com" | "github.com";
+export interface AuthOptions {
+    url: string;
+    /** Browser window for popup/redirect sign-in (defaults to globalThis.window). */
+    window?: WindowLike;
+    storage?: SessionStorage;
+    fetch?: typeof fetch;
+    /** Refresh this long before expiry (default 5 min). */
+    refreshMarginMs?: number;
+}
+export type Unsubscribe = () => void;
+export declare function createAuth(o: AuthOptions): {
+    readonly currentUser: AuthUser | null;
+    /** Resolves once the stored session (if any) is loaded. */
+    ready: () => Promise<void>;
+    onAuthStateChanged(cb: (u: AuthUser | null) => void): Unsubscribe;
+    /** A valid access token (refreshed when near expiry), or null when signed out. */
+    getIdToken(forceRefresh?: boolean): Promise<string | null>;
+    signUp: (email: string, password: string, displayName?: string) => Promise<AuthUser>;
+    signIn: (email: string, password: string) => Promise<AuthUser>;
+    /** Google/Apple: pass the ID token from Google Identity Services or Sign in with Apple. */
+    signInWithIdToken: (provider: "google.com" | "apple.com", idToken: string, o?: {
+        nonce?: string;
+        displayName?: string;
+    }) => Promise<AuthUser>;
+    signInAnonymously: () => Promise<AuthUser>;
+    /** Google / Apple / GitHub in a popup (call from a click handler). */
+    signInWithPopup: (provider: OAuthProvider) => Promise<AuthUser>;
+    /** Link a provider to the signed-in account (an anonymous account becomes a full one, same uid). */
+    linkWithPopup: (provider: OAuthProvider) => Promise<AuthUser>;
+    /** Sign in again with the same account (before sensitive changes). Fails if a different account answers. */
+    reauthenticateWithPopup: (provider: OAuthProvider) => Promise<AuthUser>;
+    /** Full-page redirect sign-in; finish with getRedirectResult() on the page you return to. */
+    signInWithRedirect: (provider: OAuthProvider, returnTo?: string) => void;
+    linkWithRedirect: (provider: OAuthProvider, returnTo?: string) => Promise<void>;
+    /** After a redirect: the signed-in user, null when this page load isn't a sign-in return. */
+    getRedirectResult: () => Promise<AuthUser | null>;
+    /** Native apps: link a Google/Apple ID token to the signed-in account. */
+    linkWithIdToken: (provider: "google.com" | "apple.com", idToken: string, nonce?: string) => Promise<AuthUser>;
+    sendSignInLink: (email: string) => Promise<unknown>;
+    /** Finish a link from the email: mode + oobCode come from its query string. */
+    signInWithLink: (oobCode: string) => Promise<AuthUser>;
+    sendPasswordReset: (email: string) => Promise<unknown>;
+    confirmPasswordReset: (oobCode: string, newPassword: string) => Promise<unknown>;
+    sendEmailVerification: () => Promise<unknown>;
+    applyEmailVerification: (oobCode: string) => Promise<void>;
+    updateProfile: (p: {
+        displayName?: string | null;
+        photoUrl?: string | null;
+        password?: string;
+        currentPassword?: string;
+    }) => Promise<AuthUser>;
+    deleteUser: () => Promise<void>;
+    signOut: () => Promise<void>;
+};
+export type EstraAuth = ReturnType<typeof createAuth>;