@syncular/server 0.1.3 → 0.2.0

package/dist/relational-rows.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Relational current-row storage (DESIGN-relational-server-storage.md).
+ *
+ * Every synced table is a REAL table in the server database — the app's
+ * columns with proper type affinities, queryable with plain SQL/joins/BI —
+ * plus five `_sync_*` meta columns:
+ *
+ *   _sync_partition       TEXT      partition key (multi-partition servers
+ *                                   share one database; same app PK in two
+ *                                   partitions must coexist)
+ *   _sync_row_id          TEXT      the change rowId (§2.2) — the string
+ *                                   rendering of the app PK. The storage key
+ *                                   stays TEXT so lookup and scan-pagination
+ *                                   semantics are byte-identical to the old
+ *                                   generic store regardless of the PK's type.
+ *   _sync_server_version  INTEGER   §2.2 server version
+ *   _sync_scopes          TEXT/JSONB the stored-scope map the §3.4 authz read
+ *                                   consumes (also present as real columns;
+ *                                   the map is cheaper to read back)
+ *   _sync_payload         BLOB/BYTEA the verbatim row-codec bytes — the wire
+ *                                   source of truth. The serve path reads
+ *                                   THIS, never re-encodes from typed columns,
+ *                                   so sync round-trips are byte-identical by
+ *                                   construction. Typed columns are a
+ *                                   queryable projection.
+ *
+ * PRIMARY KEY (_sync_partition, _sync_row_id).
+ *
+ * The typed columns are written from `decodeRow(payload)` in the same
+ * statement as the payload, so projection and payload cannot drift except
+ * through a codec bug — which the round-trip contract tests would catch.
+ *
+ * Dialect notes:
+ * - postgres maps `json` → JSONB (queryable: `->>`, GIN). JSONB normalizes
+ *   bytes, which is safe because the wire never reads typed columns.
+ *   A json value that fails to parse binds NULL on postgres (the payload
+ *   still holds it verbatim); sqlite stores the text as-is.
+ * - D1's JSON transport represents integers as JS doubles; app integer
+ *   columns beyond 2^53 lose precision in the PROJECTION only — the
+ *   payload is exact, sync is unaffected.
+ * - Migration-added columns (ALTER TABLE ADD COLUMN) are always nullable at
+ *   the DB layer: SQLite cannot add a NOT NULL column without a default, and
+ *   the row codec — not the DB — is the type authority. Fresh CREATEs carry
+ *   NOT NULL per the schema.
+ */
+import { type RowColumn, type RowValue } from '@syncular/core';
+import type { CompiledSchema, CompiledTable } from './schema.js';
+import type { StoredRow } from './storage.js';
+export type RelationalDialect = 'sqlite' | 'postgres';
+export declare const SYNC_PARTITION_COLUMN = "_sync_partition";
+export declare const SYNC_ROW_ID_COLUMN = "_sync_row_id";
+export declare const SYNC_VERSION_COLUMN = "_sync_server_version";
+export declare const SYNC_SCOPES_COLUMN = "_sync_scopes";
+export declare const SYNC_PAYLOAD_COLUMN = "_sync_payload";
+/** SQL-standard identifier quoting (both dialects). */
+export declare function quoteIdent(name: string): string;
+/** §5.3-style type affinities, per dialect (DESIGN type-mapping table). */
+export declare function columnSqlType(column: RowColumn, dialect: RelationalDialect): string;
+/**
+ * The full column list of a relational row table, in INSERT order:
+ * partition, row id, app columns (schema order; only when the table is
+ * materialized), version, scopes, payload.
+ */
+export declare function tableColumnNames(table: CompiledTable): string[];
+/** CREATE TABLE IF NOT EXISTS for one app table. */
+export declare function createTableDdl(table: CompiledTable, dialect: RelationalDialect): string;
+/**
+ * ALTER TABLE ADD COLUMN statements for schema columns missing from
+ * `existingColumns` (introspected). Added columns are nullable (header note).
+ */
+export declare function addColumnDdl(table: CompiledTable, existingColumns: ReadonlySet<string>, dialect: RelationalDialect): string[];
+/**
+ * CREATE INDEX IF NOT EXISTS for the table's user-declared indexes
+ * (DESIGN "user indexes" — the same names/columns the client materializes;
+ * cross-table index-name uniqueness is the user's schema concern, exactly
+ * as it is client-side).
+ */
+export declare function createIndexDdl(table: CompiledTable): string[];
+/**
+ * Convert one decoded row value to its SQL bind value.
+ * - boolean → 0/1 on sqlite (INTEGER affinity), native on postgres;
+ * - json → the raw string on sqlite; on postgres, NULL if unparseable
+ *   (JSONB would reject the INSERT — the payload keeps the verbatim value);
+ * - everything else binds naturally (Uint8Array → BLOB/BYTEA).
+ */
+export declare function toSqlValue(column: RowColumn, value: RowValue, dialect: RelationalDialect): unknown;
+/**
+ * Bind values for an upsert, in `tableColumnNames` order. Decodes the
+ * payload once; the typed columns and the verbatim payload land in one
+ * statement, so they cannot drift.
+ */
+export declare function upsertValues(table: CompiledTable, partition: string, row: StoredRow, dialect: RelationalDialect): unknown[];
+/** Upsert statement text (bind with `upsertValues`). */
+export declare function upsertSql(table: CompiledTable, dialect: RelationalDialect): string;
+/**
+ * SELECT one stored row. Aliased to the legacy record shape
+ * (`row_id`/`server_version`/`scopes`/`payload`) so the existing
+ * `toStoredRow` converters keep working. Params: [partition, rowId].
+ */
+export declare function selectRowSql(table: CompiledTable, dialect: RelationalDialect): string;
+/**
+ * One-round-trip page scan for `scanRows`: candidates from the inverted
+ * scope index (ordered + LIMITed at the covering `sync_row_scopes` PK —
+ * exactly the old candidate query, so the index-first posture is unchanged)
+ * LEFT JOINed to the row table, so a whole page arrives in ONE statement
+ * instead of one lookup per candidate. That per-candidate lookup was the
+ * cold-bootstrap hot path: a 100k-row snapshot on Postgres paid ~100k
+ * network round-trips (~10 s at 0.1 ms each) before this join.
+ *
+ * LEFT JOIN (not INNER): a candidate whose row vanished (index entry
+ * without a row) must still reach the caller — its `row_id` advances the
+ * keyset cursor — so it comes back with NULL payload rather than
+ * disappearing from the page.
+ *
+ * Bind order:
+ *   - postgres: [partition, tbl, var, ...values, afterRowId, limit]
+ *     (the join reuses `$1` for the partition);
+ *   - sqlite:   [partition, tbl, var, ...values, afterRowId, limit,
+ *     partition] (positional `?` — the partition binds again for the join).
+ */
+export declare function scanRowPageSql(table: CompiledTable, valueCount: number, dialect: RelationalDialect): string;
+/**
+ * One-round-trip page read for `readCommitWindow` (sync_* tables only; it
+ * lives here beside `scanRowPageSql` because it is the same join-the-index
+ * posture, dialect-parameterized the same way): candidates from the inverted
+ * change-scope index (ordered + LIMITed at the covering `sync_change_scopes`
+ * PK — exactly the old candidate query, so the index-first invariant of
+ * `CommitWindowQuery` is unchanged) LEFT JOINed to the commit metadata and
+ * to the commit's changes for the table, so a whole window page arrives in
+ * ONE statement instead of 1 + 2×candidates round trips. This is the
+ * incremental-pull hot path — it runs on every sync round; before the join a
+ * 500-candidate catch-up window on Postgres paid ~1000 network round trips.
+ *
+ * LEFT JOIN (not INNER): a candidate whose commit vanished (scope-index
+ * entry without a commit/changes row) must still reach the caller — its
+ * `commit_seq` advances the window cursor — so it comes back with NULL
+ * meta/change columns rather than disappearing from the page.
+ *
+ * Rows arrive ordered (commit_seq, idx): oldest-first commits, each commit's
+ * change rows consecutive in `idx` order — the caller groups consecutive
+ * rows and verifies the full multi-variable scope match in JS.
+ *
+ * Bind order:
+ *   - postgres: [partition, tbl, var, ...values, afterSeq, throughSeq,
+ *     limit] (the joins reuse `$1`/`$2`);
+ *   - sqlite:   [partition, tbl, var, ...values, afterSeq, throughSeq,
+ *     limit, partition, partition, tbl] (positional `?` — partition/tbl bind
+ *     again for the joins).
+ */
+export declare function commitWindowPageSql(valueCount: number, dialect: RelationalDialect): string;
+/** SELECT a row's version + scope map (admin/blob authz). Params: [partition, rowId]. */
+export declare function selectRowScopesSql(table: CompiledTable, dialect: RelationalDialect): string;
+/** DELETE one stored row. Params: [partition, rowId]. */
+export declare function deleteRowSql(table: CompiledTable, dialect: RelationalDialect): string;
+/**
+ * The schema-version marker table gating DDL work (DESIGN "server-side
+ * schema migration"): `ensureSchema` compares the stored version and skips
+ * all introspection/DDL when it matches — one cheap read per storage
+ * instance (relevant for D1's per-request instantiation).
+ *
+ * `layouts` persists each table's column layout (name/type/nullable, the
+ * exact inputs the row codec's byte layout depends on) as of the LAST
+ * applied schema version. The codec is strict — a payload only decodes
+ * under the column list it was encoded with — so a version bump MUST
+ * re-encode stored payloads (append trailing NULLs for added columns);
+ * decoding the old bytes requires the old layout, and this column is where
+ * it lives.
+ */
+export declare const SCHEMA_META_DDL_SQLITE = "CREATE TABLE IF NOT EXISTS sync_schema_meta(\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  schema_version INTEGER NOT NULL,\n  layouts TEXT NOT NULL DEFAULT '{}'\n)";
+export declare const SCHEMA_META_DDL_POSTGRES = "CREATE TABLE IF NOT EXISTS sync_schema_meta(\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  schema_version BIGINT NOT NULL,\n  layouts TEXT NOT NULL DEFAULT '{}'\n)";
+/** The codec-relevant subset of a column, persisted per applied version. */
+export interface StoredColumnLayout {
+    readonly name: string;
+    readonly type: RowColumn['type'];
+    readonly nullable: boolean;
+}
+export type StoredLayouts = Record<string, readonly StoredColumnLayout[]>;
+/** The layouts JSON persisted alongside the schema version marker. */
+export declare function layoutsOf(schema: CompiledSchema): string;
+export declare function parseLayouts(json: string | null | undefined): StoredLayouts;
+/**
+ * Enforce the migration subset on a table's column list: the old layout
+ * must be an exact prefix (same name, type, nullability) of the new one,
+ * and appended columns must be nullable (there is no default to backfill).
+ * Returns `true` iff columns were appended.
+ */
+export declare function assertAppendOnlyMigration(tableName: string, oldLayout: readonly StoredColumnLayout[], table: CompiledTable): boolean;
+/**
+ * Re-encode an old-layout payload under the current columns: decode with
+ * the layout it was written under, append NULLs for the added columns,
+ * encode with the current column list. The write path (§3.4 scope-strip,
+ * CRDT merge, conflict serverRow) and the bootstrap serve path both decode
+ * stored payloads under the CURRENT schema, so this migration is a
+ * correctness requirement of the version bump, not an optimization.
+ */
+export declare function migratePayload(oldLayout: readonly StoredColumnLayout[], table: CompiledTable, payload: Uint8Array): Uint8Array;
+/**
+ * Keyset-paged scan of a row table for the migration rewrite.
+ * Params: [afterPartition, afterRowId, limit].
+ */
+export declare function selectRowsForRewriteSql(table: CompiledTable, dialect: RelationalDialect): string;
+/**
+ * Rewrite one row during a migration: refresh the projection columns (when
+ * materialized) and the payload. Bind with `rewriteValues`.
+ */
+export declare function rewriteRowSql(table: CompiledTable, dialect: RelationalDialect): string;
+/** Bind values for `rewriteRowSql` from the (already migrated) payload. */
+export declare function rewriteValues(table: CompiledTable, partition: string, rowId: string, payload: Uint8Array, dialect: RelationalDialect): unknown[];
+/**
+ * What the migration rewrite phase must do for one table, derived from the
+ * persisted layouts + the physical columns present before this run.
+ *
+ * - `migrate`: the layout gained columns — every stored payload re-encodes
+ *   under the new column list (correctness; see `migratePayload`).
+ * - `backfill`: the table just gained physical projection columns whose
+ *   values exist in stored payloads (materialization flipped on) — the
+ *   projection refreshes from the payload, no re-encode.
+ */
+export declare function rewritePlan(table: CompiledTable, oldLayout: readonly StoredColumnLayout[] | undefined, physicalColumnsBefore: ReadonlySet<string> | undefined): {
+    migrate: boolean;
+    backfill: boolean;
+};
+/**
+ * Every DDL statement to bring a database from `existingColumnsByTable`
+ * (introspected; a missing key = table absent) to `schema`: CREATE TABLE
+ * for absent tables, ADD COLUMN for missing columns, CREATE INDEX for the
+ * declared user indexes — exactly the migration subset.
+ */
+export declare function schemaDdl(schema: CompiledSchema, existingColumnsByTable: ReadonlyMap<string, ReadonlySet<string>>, dialect: RelationalDialect): string[];