@estra/schema 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,53 @@
-# Temporary Holding Version
+# @estra/schema
 
-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 schema for an [Estra](https://estra.cloud) backend: `defineSchema`, `collection` and the `f` field
+builders, the query and write types shared with the clients, and the `estra migrate` CLI.
+
+```sh
+npm install @estra/schema
+```
+
+## Define collections
+
+```ts
+import { collection, defineSchema, f } from "@estra/schema";
+
+export const schema = defineSchema({
+  posts: collection({
+    fields: {
+      title: f.string({ required: true }),
+      authorId: f.string(),
+      published: f.bool(),
+      score: f.int(),
+      at: f.timestamp(),
+      tags: f.array("string", { indexed: true }), // array-contains uses an index
+      loc: f.geo(),                               // near() radius queries
+      meta: f.json(),                             // any JSON, not queryable
+      stats: f.map({ views: f.int(), likes: f.int() }), // "stats.views" in queries and updates
+    },
+    indexes: [["authorId", ["at", "desc"]], ["published", "at"]],
+    sub: { comments: collection({ fields: { body: f.string(), by: f.string() } }) },
+  }),
+});
+```
+
+Each collection is a table; `f.map` leaves become their own columns, and subcollections are keyed by
+their parent ids. Fields are typed, so queries on fields the schema does not know are rejected.
+
+## Migrations
+
+```sh
+npx estra migrate --schema schema.ts --out migrations
+```
+
+Diffs the schema against the last snapshot in `migrations/` and writes the next numbered SQL file.
+Destructive changes need `--allow-destructive`. Loading `schema.ts` directly needs Node 22.18 or later
+(type stripping); older Nodes can load a compiled `schema.js`.
+
+## Types
+
+`Query`, `Write`, `DocOut`, `Filter`, `Order` and the sentinels (`{ $op: "inc" | "union" | "remove" |
+"now" | "delete" }`) describe the wire format that `@estra/client`, `@estra/admin-node` and the server
+share.
+
+Docs: https://github.com/Realm-8/estra/tree/main/docs. MIT licensed.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// estra migrate --schema <file.ts> --out <migrations dir> [--name <label>] [--allow-destructive]
+// Diffs the schema against <out>/schema.snapshot.json and writes the next numbered SQL file.
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { diff, pluginDiff, snapshot } from "./sql.js";
+const args = process.argv.slice(2);
+const opt = (k) => {
+    const i = args.indexOf(`--${k}`);
+    return i >= 0 ? args[i + 1] : undefined;
+};
+if (args[0] !== "migrate" || !opt("schema") || !opt("out")) {
+    console.error("usage: estra migrate --schema <file.ts> --out <dir> [--name <label>] [--allow-destructive]");
+    process.exit(2);
+}
+const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(resolve(opt("schema"))).href)));
+const schema = mod.schema ?? mod.default;
+if (!schema?.tables)
+    throw new Error("the schema file must export `schema` (or default) from defineSchema()");
+const out = resolve(opt("out"));
+mkdirSync(out, { recursive: true });
+const snapFile = join(out, "schema.snapshot.json");
+const prev = existsSync(snapFile) ? JSON.parse(readFileSync(snapFile, "utf8")) : null;
+const plugins = mod.plugins ?? [];
+const next = snapshot(schema, plugins);
+const d = diff(prev, next, { allowDestructive: args.includes("--allow-destructive") });
+d.statements.push(...pluginDiff(prev, plugins));
+if (d.destructive.length && !args.includes("--allow-destructive")) {
+    console.error("destructive changes need --allow-destructive (or a hand-written migration):\n  " + d.destructive.join("\n  "));
+    process.exit(1);
+}
+if (!d.statements.length) {
+    console.log("schema unchanged");
+    process.exit(0);
+}
+const n = readdirSync(out).filter((f) => /^\d{4}_.*\.sql$/.test(f)).length + 1;
+const file = join(out, `${String(n).padStart(4, "0")}_${(opt("name") ?? (prev ? "change" : "init")).replace(/[^a-z0-9_]/gi, "_")}.sql`);
+writeFileSync(file, `-- Generated by estra migrate. Edit the schema, not this file.\n${d.statements.join(";\n")};\n`);
+writeFileSync(snapFile, JSON.stringify(next, null, 2) + "\n");
+console.log(`wrote ${file}`);

package/dist/fields.d.ts

@@ -0,0 +1,41 @@
+export type ScalarKind = "string" | "int" | "float" | "bool" | "timestamp";
+export type FieldKind = ScalarKind | "json" | "ref" | "array" | "geo" | "map";
+export interface FieldDef {
+    kind: FieldKind;
+    /** Array element type ("json" = anything). */
+    of?: ScalarKind | "json";
+    /** Arrays only: keep a side table so `array-contains` / `array-contains-any` use an index. */
+    indexed?: boolean;
+    /** Must be present when a document is created with a full `set`. */
+    required?: boolean;
+    /** Maps only: the sub-fields (each leaf is its own column, "parent.child"). */
+    fields?: Record<string, FieldDef>;
+}
+type Opts = {
+    required?: boolean;
+};
+export declare const f: {
+    string: (o?: Opts) => FieldDef;
+    int: (o?: Opts) => FieldDef;
+    float: (o?: Opts) => FieldDef;
+    bool: (o?: Opts) => FieldDef;
+    /** Milliseconds since the epoch on disk; `{ $t: ms }` on the wire. */
+    timestamp: (o?: Opts) => FieldDef;
+    /** Any JSON value, stored as text. Not queryable. */
+    json: (o?: Opts) => FieldDef;
+    /** A document path, e.g. "users/abc". */
+    ref: (o?: Opts) => FieldDef;
+    array: (of?: ScalarKind | "json", o?: Opts & {
+        indexed?: boolean;
+    }) => FieldDef;
+    /** A point: `<name>__lat` and `<name>__lng` columns, queried with `near`. */
+    geo: (o?: Opts) => FieldDef;
+    /**
+     * A typed sub-object. Each leaf is a real column ("stats.plays"), so dotted paths work in
+     * where/orderBy/indexes/rules and in updates ("stats.plays": inc(1)). Writing the whole map
+     * replaces it (unlisted sub-fields become null), as in Firestore.
+     */
+    map: (fields: Record<string, FieldDef>, o?: Opts) => FieldDef;
+};
+export declare const SQL_TYPE: Record<FieldKind, string>;
+export {};

package/dist/fields.js

@@ -0,0 +1,40 @@
+// Field types. Every field is one SQL column (geo is two), so queries run on real indexes.
+// Columns are nullable: a missing field and a null field read the same (see docs/decisions/001).
+const def = (kind, o = {}) => ({ kind, ...(o.required ? { required: true } : {}) });
+export const f = {
+    string: (o) => def("string", o),
+    int: (o) => def("int", o),
+    float: (o) => def("float", o),
+    bool: (o) => def("bool", o),
+    /** Milliseconds since the epoch on disk; `{ $t: ms }` on the wire. */
+    timestamp: (o) => def("timestamp", o),
+    /** Any JSON value, stored as text. Not queryable. */
+    json: (o) => def("json", o),
+    /** A document path, e.g. "users/abc". */
+    ref: (o) => def("ref", o),
+    array: (of = "json", o = {}) => {
+        if (o.indexed && of === "json")
+            throw new Error("only arrays of scalars can be indexed");
+        return { ...def("array", o), of, ...(o.indexed ? { indexed: true } : {}) };
+    },
+    /** A point: `<name>__lat` and `<name>__lng` columns, queried with `near`. */
+    geo: (o) => def("geo", o),
+    /**
+     * A typed sub-object. Each leaf is a real column ("stats.plays"), so dotted paths work in
+     * where/orderBy/indexes/rules and in updates ("stats.plays": inc(1)). Writing the whole map
+     * replaces it (unlisted sub-fields become null), as in Firestore.
+     */
+    map: (fields, o) => ({ ...def("map", o), fields }),
+};
+export const SQL_TYPE = {
+    string: "TEXT",
+    int: "INTEGER",
+    float: "REAL",
+    bool: "INTEGER",
+    timestamp: "INTEGER",
+    json: "TEXT",
+    ref: "TEXT",
+    array: "TEXT",
+    geo: "REAL",
+    map: "TEXT", // never a column itself: its leaves are
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./fields.js";
+export * from "./schema.js";
+export * from "./sql.js";
+export * from "./query.js";
+export * from "./local.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./fields.js";
+export * from "./schema.js";
+export * from "./sql.js";
+export * from "./query.js";
+export * from "./local.js";

package/dist/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/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/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/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/schema.d.ts

@@ -0,0 +1,47 @@
+import { type FieldDef } from "./fields.js";
+export type IndexField = string | [string, "asc" | "desc"];
+export interface CollectionDef {
+    fields: Record<string, FieldDef>;
+    /** Composite indexes, leading column first. Single fields used alone get one too. */
+    indexes?: IndexField[][];
+    sub?: Record<string, CollectionDef>;
+}
+export declare const collection: (c: CollectionDef) => CollectionDef;
+export interface Column {
+    name: string;
+    type: string;
+}
+export interface TableInfo {
+    /** Quoted-safe table name: collection ids joined with "/". */
+    table: string;
+    /** Collection ids from the root, e.g. ["posts", "comments"]. */
+    pattern: string[];
+    /** Parent id columns, `_p0` … */
+    parents: string[];
+    fields: Record<string, FieldDef>;
+    /** Index name → column list (with " DESC" where descending). */
+    indexes: Record<string, string[]>;
+    /** Indexed array field → side table name. */
+    sides: Record<string, string>;
+}
+export interface Schema {
+    tables: Record<string, TableInfo>;
+}
+export declare function defineSchema(root: Record<string, CollectionDef>): Schema;
+/** Data columns of a table (geo fields expand to two). */
+export declare function columnsOf(t: TableInfo): Column[];
+/** Every non-map field, with its dotted path ("stats.plays"). Maps contribute their leaves. */
+export declare function leavesOf(fields: Record<string, FieldDef>, prefix?: string): {
+    path: string;
+    fd: FieldDef;
+}[];
+/**
+ * Resolves a dotted path. Walks through maps; stops at the first non-map field and returns the
+ * rest of the path (non-empty only for json fields: a path inside the JSON value).
+ * Null when the path names no field, or goes "inside" a scalar.
+ */
+export declare function fieldAt(fields: Record<string, FieldDef>, path: string): {
+    fd: FieldDef;
+    base: string;
+    rest: string[];
+} | null;

package/dist/schema.js

@@ -0,0 +1,99 @@
+// defineSchema(): collections → SQL tables. A subcollection is its own table whose rows carry
+// their parents' ids in `_p0`, `_p1`, … (posts/{a}/comments/{b} → table "posts/comments", _p0 = a).
+import { SQL_TYPE } from "./fields.js";
+export const collection = (c) => c;
+const ID_RE = /^[a-z][a-zA-Z0-9_]{0,62}$/;
+const FIELD_RE = /^[a-zA-Z][a-zA-Z0-9_]{0,62}$/;
+const RESERVED = new Set(["id"]);
+export function defineSchema(root) {
+    const tables = {};
+    const walk = (defs, prefix) => {
+        for (const [id, c] of Object.entries(defs)) {
+            if (!ID_RE.test(id))
+                throw new Error(`bad collection id "${id}"`);
+            const pattern = [...prefix, id];
+            const table = pattern.join("/");
+            const checkNames = (fields, prefix, depth) => {
+                if (depth > 4)
+                    throw new Error(`${table}: maps nest at most 4 deep ("${prefix}")`);
+                for (const [name, fd] of Object.entries(fields)) {
+                    if (!FIELD_RE.test(name) || (depth === 0 && RESERVED.has(name)) || name.includes("__"))
+                        throw new Error(`${table}: bad field name "${prefix}${name}"`);
+                    if (fd.kind === "map")
+                        checkNames(fd.fields ?? {}, `${prefix}${name}.`, depth + 1);
+                }
+            };
+            checkNames(c.fields, "", 0);
+            const indexes = {};
+            for (const ix of c.indexes ?? []) {
+                const cols = ix.flatMap((e) => {
+                    const [name, dir] = typeof e === "string" ? [e, "asc"] : e;
+                    const at = name === "id" ? null : fieldAt(c.fields, name);
+                    const fd = at && at.rest.length === 0 ? at.fd : undefined;
+                    if (name !== "id" && !fd)
+                        throw new Error(`${table}: index on unknown field "${name}"`);
+                    if (fd && (fd.kind === "json" || fd.kind === "array" || fd.kind === "map"))
+                        throw new Error(`${table}: cannot index ${fd.kind} field "${name}" (index arrays with { indexed: true }; index a map's leaves)`);
+                    const d = dir === "desc" ? " DESC" : "";
+                    return fd?.kind === "geo" ? [`${name}__lat${d}`, `${name}__lng${d}`] : [`${name}${d}`];
+                });
+                indexes[`${table}(${cols.join(",")})`] = cols;
+            }
+            const sides = {};
+            for (const { path: name, fd } of leavesOf(c.fields)) {
+                if (fd.kind === "array" && fd.indexed)
+                    sides[name] = `${table}#${name}`;
+                if (fd.kind === "geo") {
+                    const cols = [`${name}__lat`, `${name}__lng`];
+                    indexes[`${table}(${cols.join(",")})`] ??= cols;
+                }
+            }
+            tables[table] = { table, pattern, parents: prefix.map((_, i) => `_p${i}`), fields: c.fields, indexes, sides };
+            if (c.sub)
+                walk(c.sub, pattern);
+        }
+    };
+    walk(root, []);
+    return { tables };
+}
+/** Data columns of a table (geo fields expand to two). */
+export function columnsOf(t) {
+    const out = [];
+    for (const { path: name, fd } of leavesOf(t.fields)) {
+        if (fd.kind === "geo")
+            out.push({ name: `${name}__lat`, type: "REAL" }, { name: `${name}__lng`, type: "REAL" });
+        else
+            out.push({ name, type: SQL_TYPE[fd.kind] });
+    }
+    return out;
+}
+/** Every non-map field, with its dotted path ("stats.plays"). Maps contribute their leaves. */
+export function leavesOf(fields, prefix = "") {
+    return Object.entries(fields).flatMap(([name, fd]) => (fd.kind === "map" ? leavesOf(fd.fields ?? {}, `${prefix}${name}.`) : [{ path: `${prefix}${name}`, fd }]));
+}
+/**
+ * Resolves a dotted path. Walks through maps; stops at the first non-map field and returns the
+ * rest of the path (non-empty only for json fields: a path inside the JSON value).
+ * Null when the path names no field, or goes "inside" a scalar.
+ */
+export function fieldAt(fields, path) {
+    const segs = path.split(".");
+    let cur = fields;
+    for (let i = 0; i < segs.length; i++) {
+        const fd = cur[segs[i]];
+        if (!fd)
+            return null;
+        const base = segs.slice(0, i + 1).join(".");
+        const rest = segs.slice(i + 1);
+        if (fd.kind === "map" && rest.length) {
+            cur = fd.fields ?? {};
+            continue;
+        }
+        if (rest.length && fd.kind !== "json")
+            return null;
+        if (rest.some((r) => !r || /["\\]/.test(r)))
+            return null;
+        return { fd, base, rest };
+    }
+    return null;
+}

package/dist/sql.d.ts

@@ -0,0 +1,39 @@
+import { type Schema, type TableInfo } from "./schema.js";
+export declare const q: (name: string) => string;
+/** Tables every Estra database has, by version (a snapshot records how many it has applied). */
+export declare const SYSTEM_MIGRATIONS: string[][];
+/** Every system statement (fresh databases). */
+export declare const SYSTEM_SQL: string[];
+export interface TableSnap {
+    parents: string[];
+    columns: Record<string, string>;
+    indexes: Record<string, string[]>;
+    sides: Record<string, string>;
+}
+export interface Snapshot {
+    version: 1;
+    tables: Record<string, TableSnap>;
+    /** Plugin name → migrations applied. */
+    plugins?: Record<string, number>;
+    /** System migrations applied (absent in snapshots older than the field = 1). */
+    system?: number;
+}
+/** The part of a plugin migrations care about (EstraPlugin in @estra/server). */
+export interface PluginMigrations {
+    name: string;
+    migrations: string[][];
+}
+/** Plugin SQL a database at `prev` hasn't had yet. */
+export declare function pluginDiff(prev: Snapshot | null, plugins: PluginMigrations[]): string[];
+export declare function snapshot(schema: Schema, plugins?: PluginMigrations[]): Snapshot;
+/** Full SQL for a fresh database. */
+export declare function schemaToSql(schema: Schema): string[];
+export interface Diff {
+    statements: string[];
+    /** Drops and type changes, left out unless `allowDestructive`. */
+    destructive: string[];
+}
+export declare function diff(prev: Snapshot | null, next: Snapshot, opts?: {
+    allowDestructive?: boolean;
+}): Diff;
+export type { TableInfo };

package/dist/sql.js

@@ -0,0 +1,115 @@
+// Schema → SQL (SQLite). `snapshot()` records what a migration produced, and `diff()`
+// turns the change between two snapshots into the next migration.
+import { columnsOf } from "./schema.js";
+export const q = (name) => `"${name.replace(/"/g, '""')}"`;
+/** Tables every Estra database has, by version (a snapshot records how many it has applied). */
+export const SYSTEM_MIGRATIONS = [
+    [
+        `CREATE TABLE IF NOT EXISTS "_changes" ("seq" INTEGER PRIMARY KEY AUTOINCREMENT, "tbl" TEXT NOT NULL, "key" TEXT NOT NULL, "op" TEXT NOT NULL, "v" INTEGER, "at" INTEGER NOT NULL, "origin" TEXT)`,
+        `CREATE INDEX IF NOT EXISTS "_changes(at)" ON "_changes" ("at")`,
+        `CREATE TABLE IF NOT EXISTS "_ops" ("op_key" TEXT PRIMARY KEY, "at" INTEGER NOT NULL)`,
+        // A batch inserts 0 here to abort itself (failed precondition): CHECK fails → whole batch rolls back.
+        `CREATE TABLE IF NOT EXISTS "_assert" ("ok" INTEGER NOT NULL CHECK ("ok" = 1))`,
+    ],
+    [
+        // Trigger outbox: one row per write to a table with triggers, written in the commit's own batch.
+        `CREATE TABLE IF NOT EXISTS "_events" ("id" INTEGER PRIMARY KEY AUTOINCREMENT, "seq" INTEGER, "tbl" TEXT NOT NULL, "path" TEXT NOT NULL, "op" TEXT NOT NULL, "before" TEXT, "after" TEXT, "origin" TEXT, "at" INTEGER NOT NULL, "attempts" INTEGER NOT NULL DEFAULT 0, "claimed_at" INTEGER, "state" INTEGER NOT NULL DEFAULT 0, "error" TEXT)`,
+        `CREATE INDEX IF NOT EXISTS "_events(state,id)" ON "_events" ("state", "id")`,
+    ],
+];
+/** Every system statement (fresh databases). */
+export const SYSTEM_SQL = SYSTEM_MIGRATIONS.flat();
+/** Plugin SQL a database at `prev` hasn't had yet. */
+export function pluginDiff(prev, plugins) {
+    return plugins.flatMap((p) => p.migrations.slice(prev?.plugins?.[p.name] ?? 0).flat());
+}
+export function snapshot(schema, plugins = []) {
+    const tables = {};
+    for (const t of Object.values(schema.tables)) {
+        tables[t.table] = {
+            parents: t.parents,
+            columns: Object.fromEntries(columnsOf(t).map((c) => [c.name, c.type])),
+            indexes: t.indexes,
+            sides: t.sides,
+        };
+    }
+    return { version: 1, tables, system: SYSTEM_MIGRATIONS.length, ...(plugins.length ? { plugins: Object.fromEntries(plugins.map((p) => [p.name, p.migrations.length])) } : {}) };
+}
+const colList = (cols) => cols.map((c) => (c.endsWith(" DESC") ? `${q(c.slice(0, -5))} DESC` : q(c))).join(", ");
+function createTable(name, t) {
+    const key = [...t.parents, "id"];
+    const cols = [...key.map((k) => `${q(k)} TEXT NOT NULL`), ...Object.entries(t.columns).map(([c, ty]) => `${q(c)} ${ty}`)];
+    cols.push(`"_v" INTEGER NOT NULL`, `"_created" INTEGER NOT NULL`, `"_updated" INTEGER NOT NULL`);
+    const out = [`CREATE TABLE IF NOT EXISTS ${q(name)} (${cols.join(", ")}, PRIMARY KEY (${colList(key)}))`];
+    for (const [ix, ixCols] of Object.entries(t.indexes))
+        out.push(createIndex(name, t, ix, ixCols));
+    for (const side of Object.values(t.sides))
+        out.push(...createSide(side, t));
+    return out;
+}
+// Subcollection indexes lead with the parent ids: queries run inside one parent.
+const createIndex = (table, t, ix, cols) => `CREATE INDEX IF NOT EXISTS ${q(ix)} ON ${q(table)} (${colList([...t.parents, ...cols])})`;
+function createSide(side, t) {
+    const key = [...t.parents, "id"];
+    return [
+        `CREATE TABLE IF NOT EXISTS ${q(side)} (${key.map((k) => `${q(k)} TEXT NOT NULL`).join(", ")}, "value" NOT NULL, PRIMARY KEY (${colList([...key, "value"])}))`,
+        `CREATE INDEX IF NOT EXISTS ${q(`${side}(value)`)} ON ${q(side)} (${colList(["value", ...key])})`,
+    ];
+}
+const backfillSide = (table, field, side, t) => {
+    const key = [...t.parents, "id"];
+    return `INSERT OR IGNORE INTO ${q(side)} (${colList([...key, "value"])}) SELECT ${key.map((k) => `d.${q(k)}`).join(", ")}, j.value FROM ${q(table)} AS d, json_each(d.${q(field)}) AS j WHERE d.${q(field)} IS NOT NULL AND j.type NOT IN ('object', 'array', 'null')`;
+};
+/** Full SQL for a fresh database. */
+export function schemaToSql(schema) {
+    return diff(null, snapshot(schema)).statements;
+}
+export function diff(prev, next, opts = {}) {
+    const statements = SYSTEM_MIGRATIONS.slice(prev ? (prev.system ?? 1) : 0).flat();
+    const destructive = [];
+    const drop = (desc, sql) => {
+        destructive.push(desc);
+        if (opts.allowDestructive)
+            statements.push(sql);
+    };
+    const before = prev?.tables ?? {};
+    for (const [name, t] of Object.entries(next.tables)) {
+        const p = before[name];
+        if (!p) {
+            statements.push(...createTable(name, t));
+            continue;
+        }
+        if (p.parents.join() !== t.parents.join())
+            throw new Error(`${name}: parent keys changed; needs a hand-written migration`);
+        for (const [c, ty] of Object.entries(t.columns)) {
+            if (!(c in p.columns))
+                statements.push(`ALTER TABLE ${q(name)} ADD COLUMN ${q(c)} ${ty}`);
+            else if (p.columns[c] !== ty)
+                destructive.push(`${name}.${c}: type ${p.columns[c]} → ${ty} (hand-written migration)`);
+        }
+        for (const c of Object.keys(p.columns))
+            if (!(c in t.columns))
+                drop(`${name}.${c}: column removed`, `ALTER TABLE ${q(name)} DROP COLUMN ${q(c)}`);
+        for (const [ix, cols] of Object.entries(t.indexes))
+            if (!(ix in p.indexes))
+                statements.push(createIndex(name, t, ix, cols));
+        for (const ix of Object.keys(p.indexes))
+            if (!(ix in t.indexes))
+                statements.push(`DROP INDEX IF EXISTS ${q(ix)}`);
+        for (const [field, side] of Object.entries(t.sides)) {
+            if (!(field in p.sides))
+                statements.push(...createSide(side, t), backfillSide(name, field, side, t));
+        }
+        for (const [field, side] of Object.entries(p.sides))
+            if (!(field in t.sides))
+                statements.push(`DROP TABLE IF EXISTS ${q(side)}`);
+    }
+    for (const [name, p] of Object.entries(before)) {
+        if (name in next.tables)
+            continue;
+        drop(`${name}: table removed`, `DROP TABLE IF EXISTS ${q(name)}`);
+        for (const side of Object.values(p.sides))
+            drop(`${side}: side table removed`, `DROP TABLE IF EXISTS ${q(side)}`);
+    }
+    return { statements, destructive };
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@estra/schema",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Estra's schema: defineSchema and field types, the query and write types, and the estra migrate CLI.",
+  "license": "MIT",
+  "homepage": "https://estra.cloud",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Realm-8/estra.git",
+    "directory": "packages/schema"
+  },
+  "bugs": "https://github.com/Realm-8/estra/issues",
+  "keywords": [
+    "estra",
+    "schema",
+    "database",
+    "migrations",
+    "firestore"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "estra": "./dist/cli.js"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2",
+    "vitest": "4.1.0",
+    "@types/node": "^24.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p .",
+    "build": "node ../../scripts/build-package.ts schema",
+    "test": "vitest run"
+  },
+  "types": "./dist/index.d.ts"
 }