@rindle/client 0.1.0-rc.5

package/dist/types.d.ts

@@ -0,0 +1,250 @@
+/** A bare wire cell. (JSON columns arrive as their raw JSON string.) */
+export type WireValue = number | string | boolean | null;
+/** Declared column type (from the typed schema) — drives the comparator + JSON parsing. */
+export type ColType = "string" | "number" | "boolean" | "json";
+/** A scalar-projection annotation on a relationship slot (REDUCE-DESIGN.md §9): a
+ *  relationship aggregate (`issue { commentCount: count(comments) }`) lives as a singular
+ *  one-row relationship whose child is the aggregate row; this tells the receiver to unwrap
+ *  it into a scalar field — `commentCount: 5` instead of `commentCount: [{ count: 5 }]`. */
+export interface WireProjection {
+    /** Which CHILD column to surface as the scalar value (the aggregate column). */
+    col: number;
+    /** The value to emit when the relationship is empty (a childless parent) — the
+     *  aggregate identity (`0` for count, `null` for sum/avg). */
+    identity: WireValue;
+}
+export interface WireRel {
+    name: string;
+    slot: number;
+    /** `null` ⇒ an out-of-view / gating slot (the in-view gate drops `Child`s addressed here). */
+    child: WireSchema | null;
+    /** Non-null ⇒ a scalar-projected relationship aggregate the receiver unwraps to a scalar
+     *  (REDUCE-DESIGN.md §9). Absent/`null` for an ordinary (plural or `.one()`) relationship. */
+    project?: WireProjection | null;
+}
+export interface WireSchema {
+    columns: string[];
+    primaryKey: number[];
+    /** Resolved, PK-completed sort: `[columnIndex, ascending]` pairs (the comparator input). */
+    sort: [number, boolean][];
+    singular: boolean;
+    relationships: WireRel[];
+}
+export interface WireNode {
+    row: WireValue[];
+    rels: {
+        rel: number;
+        children: WireNode[];
+    }[];
+}
+export interface PathSeg {
+    rel: number;
+    parentRow: WireValue[];
+}
+export type FlatOp = {
+    tag: "add";
+    node: WireNode;
+} | {
+    tag: "remove";
+    row: WireValue[];
+} | {
+    tag: "edit";
+    old: WireValue[];
+    new: WireValue[];
+};
+export interface FlatChange {
+    path: PathSeg[];
+    op: FlatOp;
+}
+/**
+ * What a {@link Backend} pushes per query: the handshake (`hello`), the (possibly
+ * chunked) hydrate `snapshot`, then incremental `batch`es. The core builds an ArrayView
+ * on `hello`, hydrates on `snapshot`, folds on `batch` — identically for any backend.
+ */
+export type ChangeEvent = {
+    type: "hello";
+    schema: WireSchema;
+    comparatorVersion: number;
+} | {
+    type: "snapshot";
+    adds: FlatChange[];
+    last: boolean;
+} | {
+    type: "batch";
+    events: FlatChange[];
+};
+export type Mutation = {
+    op: "add";
+    table: string;
+    row: WireValue[];
+} | {
+    op: "remove";
+    table: string;
+    row: WireValue[];
+} | {
+    op: "edit";
+    table: string;
+    old: WireValue[];
+    new: WireValue[];
+};
+/**
+ * A table-tagged, path-free row delta — the **normalized** wire payload (the path-free twin
+ * of {@link FlatChange}; NORMALIZED-CHANGES-DESIGN.md §3). Rows are positional (bare cells; a
+ * json column is its raw JSON string). `op` is the discriminant. Lives here (not in
+ * `@rindle/normalized`) so both the protocol (`@rindle/remote`) and the sync layer share one type.
+ */
+export type NormalizedOp = {
+    table: string;
+    op: "add";
+    row: WireValue[];
+} | {
+    table: string;
+    op: "remove";
+    row: WireValue[];
+} | {
+    table: string;
+    op: "edit";
+    old: WireValue[];
+    new: WireValue[];
+};
+/** One base table's flat schema on the normalized `hello` (§3): column names (in order) +
+ *  primary-key column indices. Wire rows are positional against `columns`. */
+export interface NormalizedTableSchema {
+    name: string;
+    columns: string[];
+    primaryKey: number[];
+}
+/**
+ * A per-query NORMALIZED stream event — the path-free twin of {@link ChangeEvent}. The
+ * `hello` carries the flat per-table schemas (no nested view schema, §3); `snapshot`/`batch`
+ * carry table-tagged {@link NormalizedOp}s. The `NormalizedSync` layer folds these into the
+ * local engine's base tables.
+ *
+ * `cv` (the global commit version the frame's data reflects — OPTIMISTIC-WRITES-DESIGN.md
+ * §8.3/§8.6) is present on sources that speak the optimistic protocol; the plain normalized
+ * path may omit it.
+ */
+export type NormalizedEvent = {
+    type: "hello";
+    tables: NormalizedTableSchema[];
+    comparatorVersion: number;
+    normalizedFp: string;
+} | {
+    type: "snapshot";
+    ops: NormalizedOp[];
+    cv?: number;
+} | {
+    type: "batch";
+    ops: NormalizedOp[];
+    cv?: number;
+};
+export type QueryId = number;
+/** A query's SERVER-CHANNEL state, surfaced on its {@link ArrayView} (FOLDED-MUTATIONS-DESIGN §7 —
+ *  formerly conflated with pending-ness, OPTIMISTIC-WRITES-DESIGN.md §6):
+ *   - `unknown`  — not hydrated: the server has not produced a first result for this query yet;
+ *   - `complete` — the server has answered. STAYS `complete` while a local mutation is pending (the
+ *                  prediction is the client's best current answer); reversion on rejection is an
+ *                  event (`onRejected`), not a downgrade of completeness;
+ *   - `error`    — RESERVED for a future server-side, query-level error signal
+ *                  (see `designs/QUERY-ERRORS-DESIGN.md`); no longer produced by a pending mutation.
+ *  "Is a prediction pending here?" is now a separate reactive axis (the backend's `pending(qid)` /
+ *  `onPending`), not folded into this type. A backend with no server lifecycle (the in-process
+ *  engine) leaves every view `complete`. */
+export type ResultType = "unknown" | "complete" | "error";
+/** The network identity for a named query subscription. The local AST remains local; remote
+ *  normalized/optimistic sources use only this `(name,args)` pair upstream. */
+export interface RemoteQuery {
+    name: string;
+    args: unknown;
+}
+/**
+ * The seam the core talks to. Backend-agnostic: the same interface for the in-process
+ * WASM backend and a remote (network) backend. The core never knows which. A backend
+ * pushes a per-query {@link ChangeEvent} stream via {@link Backend.onEvent}; the remote
+ * backend additionally owns the epoch/seq/gap protocol and emits only clean, in-order
+ * events (so the ArrayView never sees the wire protocol).
+ */
+export interface Backend {
+    registerQuery(queryId: QueryId, ast: unknown, remote?: RemoteQuery): void;
+    unregisterQuery(queryId: QueryId): void;
+    /** Optional split path for local-first backends: retain/release a named remote footprint
+     *  without creating another local materialized view. `localQueryId`, when provided, names
+     *  the local AST view this remote footprint feeds. */
+    retainRemoteQuery?(queryId: QueryId, remote: RemoteQuery, localQueryId?: QueryId): void;
+    releaseRemoteQuery?(queryId: QueryId): void;
+    /** Local: applies now (changes flow back on the stream). Remote: sends to the server. */
+    mutate(mutations: Mutation[]): Promise<void>;
+    onEvent(handler: (queryId: QueryId, event: ChangeEvent) => void): void;
+    /** Optional: the backend pushes per-query {@link ResultType} changes here and the core routes
+     *  each to the matching view (so `view.resultType` tracks it). Backends with no lifecycle (the
+     *  in-process engine) omit it and every view stays `complete`. */
+    onResultType?(handler: (queryId: QueryId, resultType: ResultType) => void): void;
+}
+/**
+ * The server side of the **normalized** local-first path (NORMALIZED-CHANGES-DESIGN.md §5/§7):
+ * registers queries and pushes each one's normalized footprint stream ({@link NormalizedEvent}s).
+ * Both the in-process native (`@rindle/replica`) source and the ws (`@rindle/remote`
+ * `RemoteNormalizedSource`) implement it; `@rindle/normalized`'s `NormalizedBackend` consumes one,
+ * never knowing which — a sibling seam of {@link Backend} for the normalized composition.
+ */
+export interface NormalizedSource {
+    registerQuery(queryId: QueryId, remote: RemoteQuery): void;
+    unregisterQuery(queryId: QueryId): void;
+    /** Send base-table writes to the server; the authoritative stream flows back. */
+    mutate(mutations: Mutation[]): Promise<void>;
+    onNormalized(handler: (queryId: QueryId, event: NormalizedEvent) => void): void;
+    /** Optional: the backend hands its OWN typed per-table schemas so the source can validate
+     *  each server `hello` against them (column order / PK by name) and reject a schema skew
+     *  rather than silently transposing positional cells (CRIT#4 / §3 "drift ⇒ re-subscribe").
+     *  Sources that can't skew (the in-process native source) may omit it. */
+    expectClientSchema?(tables: NormalizedTableSchema[]): void;
+}
+/** The upstream named-mutator envelope (OPTIMISTIC-WRITES-DESIGN.md §8.1): the wire
+ *  carries the name + JSON args, never code; `mid` totally orders a client's mutations. */
+export interface MutationEnvelope {
+    clientID: string;
+    mid: number;
+    name: string;
+    args: unknown;
+}
+/** The connection-level progress frame (§8.6): advances the coherent-apply release point
+ *  (`cvMin`). A pure release signal — mutation confirmation does NOT ride it: `lmid` is a
+ *  row in {@link CLIENT_MUTATIONS_TABLE}, delivered through the client's own per-client
+ *  system query ({@link LMID_QUERY_NAME}) like any data, so it is released by the same
+ *  `cvMin` as the commit's effects (transactionally coherent by construction). */
+export interface ProgressFrame {
+    cvMin: number;
+}
+/** The replicated bookkeeping table carrying each client's high-water mutation id
+ *  (`lmid`). Engine-hosted and served like any base table; reserved (never part of a
+ *  user schema). Columns: `[client_id, last_mutation_id]`, PK `client_id`. */
+export declare const CLIENT_MUTATIONS_TABLE = "_rindle_client_mutations";
+/** The reserved server-query name every optimistic client subscribes at connect: the
+ *  one-row system query `CLIENT_MUTATIONS_TABLE WHERE client_id = <me>`. The server
+ *  derives the identity from the connection (args are ignored). */
+export declare const LMID_QUERY_NAME = "_rindle/clientLmid";
+/** The system table's wire schema — appended to the client's expected schemas so the
+ *  lmid query's `hello` passes CRIT#4 validation. */
+export declare const CLIENT_MUTATIONS_SCHEMA: NormalizedTableSchema;
+/**
+ * The server side of the OPTIMISTIC path (OPTIMISTIC-WRITES-DESIGN.md §8): the
+ * {@link NormalizedSource} stream with `cv`-tagged data frames, plus the connection-level
+ * {@link ProgressFrame} channel and the named-mutator upstream. The client buffers data
+ * frames by `cv` and applies all `cv ≤ cvMin` as one coherent release (§8.5).
+ */
+export interface OptimisticSource {
+    registerQuery(queryId: QueryId, remote: RemoteQuery): void;
+    unregisterQuery(queryId: QueryId): void;
+    /** Ship one named-mutator invocation upstream (§8.1). Confirmation rides the progress frames. */
+    pushMutation(envelope: MutationEnvelope): Promise<void>;
+    onNormalized(handler: (queryId: QueryId, event: NormalizedEvent) => void): void;
+    onProgress(handler: (frame: ProgressFrame) => void): void;
+    /** Optional: the backend hands its OWN typed per-table schemas so the source validates each
+     *  server `hello` against them and rejects a schema skew (CRIT#4); see {@link NormalizedSource}. */
+    expectClientSchema?(tables: NormalizedTableSchema[]): void;
+    /** Optional: fired when the server restarts (a transport that can detect it, e.g. via a daemon
+     *  boot id). The backend resets its `cv` watermark so the server's reset `cv` sequence is
+     *  accepted rather than dropped as stale. In-process sources never restart and omit it. */
+    onRestart?(handler: () => void): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,20 @@
+// Wire + protocol types for the flat-change client core (WASM-CLIENT-DESIGN.md §2, §6).
+//
+// Cells cross the boundary BARE (the host has a typed schema, so per-column types are
+// known here, not per-cell). JSON columns cross as their raw JSON string.
+/** The replicated bookkeeping table carrying each client's high-water mutation id
+ *  (`lmid`). Engine-hosted and served like any base table; reserved (never part of a
+ *  user schema). Columns: `[client_id, last_mutation_id]`, PK `client_id`. */
+export const CLIENT_MUTATIONS_TABLE = "_rindle_client_mutations";
+/** The reserved server-query name every optimistic client subscribes at connect: the
+ *  one-row system query `CLIENT_MUTATIONS_TABLE WHERE client_id = <me>`. The server
+ *  derives the identity from the connection (args are ignored). */
+export const LMID_QUERY_NAME = "_rindle/clientLmid";
+/** The system table's wire schema — appended to the client's expected schemas so the
+ *  lmid query's `hello` passes CRIT#4 validation. */
+export const CLIENT_MUTATIONS_SCHEMA = {
+    name: CLIENT_MUTATIONS_TABLE,
+    columns: ["client_id", "last_mutation_id"],
+    primaryKey: [0],
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,EAAE;AACF,sFAAsF;AACtF,0EAA0E;AAgM1E;;8EAE8E;AAC9E,MAAM,CAAC,MAAM,sBAAsB,GAAG,0BAA0B,CAAC;AAEjE;;mEAEmE;AACnE,MAAM,CAAC,MAAM,eAAe,GAAG,oBAAoB,CAAC;AAEpD;qDACqD;AACrD,MAAM,CAAC,MAAM,uBAAuB,GAA0B;IAC5D,IAAI,EAAE,sBAAsB;IAC5B,OAAO,EAAE,CAAC,WAAW,EAAE,kBAAkB,CAAC;IAC1C,UAAU,EAAE,CAAC,CAAC,CAAC;CAChB,CAAC"}

package/dist/view.d.ts

@@ -0,0 +1,88 @@
+import type { ColType, FlatChange, ResultType, WireSchema } from "./types.ts";
+/** Per-level column types (parallel to the WireSchema), used to JSON.parse json columns on
+ *  projection. Built by the Store from the typed schema; absent ⇒ no parsing (bare values). */
+export interface ViewTypes {
+    columnTypes: ColType[];
+    rels: Record<number, ViewTypes>;
+}
+/** The public ArrayView contract `materialize()` returns. */
+export interface ArrayView<R> {
+    /** The current materialized result (reference-stable where data is unchanged). */
+    readonly data: readonly R[];
+    /** The query's SERVER-CHANNEL state (`unknown` while loading, `complete` once server-authoritative;
+     *  the `error` variant is reserved and currently unproduced). A pending optimistic mutation no
+     *  longer moves this — it is a separate axis (FOLDED-MUTATIONS-DESIGN §7). `complete` for backends
+     *  with no server lifecycle. Changes notify subscribers. */
+    readonly resultType: ResultType;
+    /** Subscribe; fires immediately with the current data, then after each applied batch (and after
+     *  a {@link resultType} change — re-read `resultType` in the listener). */
+    subscribe(listener: (data: readonly R[]) => void): () => void;
+    /** Tear down + stop receiving updates. */
+    destroy(): void;
+}
+/** What a top-level `.one()` query materializes to: the single row (or `null`), not an array.
+ *  A thin adapter over a {@link FlatArrayView} — all the folding is shared; only the result
+ *  boundary unwraps (`data[0] ?? null`). Reference identity of the row is preserved. */
+export interface SingularArrayView<R> {
+    /** The single current row, or `null` when the query matches nothing. */
+    readonly data: R | null;
+    /** The query's lifecycle state — see {@link ArrayView.resultType}. */
+    readonly resultType: ResultType;
+    /** Subscribe; fires immediately with the current row, then after each applied batch (and after
+     *  a {@link resultType} change). */
+    subscribe(listener: (data: R | null) => void): () => void;
+    /** Tear down + stop receiving updates. */
+    destroy(): void;
+}
+/** Wrap a plural {@link FlatArrayView} as a {@link SingularArrayView} for a `.one()` query
+ *  (the engine caps it to `limit = 1`, so the top list holds at most one node). */
+export declare class SingularView<R> implements SingularArrayView<R> {
+    private readonly inner;
+    constructor(inner: ArrayView<R>);
+    get data(): R | null;
+    get resultType(): ResultType;
+    subscribe(listener: (data: R | null) => void): () => void;
+    destroy(): void;
+}
+export declare class FlatArrayView<R = unknown> implements ArrayView<R> {
+    private schema;
+    private types?;
+    private seeded;
+    private top;
+    private dirty;
+    private cached;
+    private rt;
+    private readonly listeners;
+    constructor(schema?: WireSchema, types?: ViewTypes);
+    get resultType(): ResultType;
+    /** Set the query's lifecycle state (the Store routes the backend's per-query signal here).
+     *  Notifies subscribers on a change so a status-bound listener (React `useQueryStatus`) re-reads,
+     *  WITHOUT re-projecting data (it is unchanged). */
+    setResultType(rt: ResultType): void;
+    /** (Re)bind to a schema and clear the tree IN PLACE. The first `hello` (pending → ready)
+     *  and a re-hydrate (gap → new epoch — FLAT-CHANGES-DESIGN.md §2.3) both go through here, so
+     *  the caller's view reference and its subscribers survive a re-subscribe. Does NOT notify —
+     *  the snapshot that follows (`applyChanges`) does, avoiding an empty-then-filled flicker. */
+    reset(schema: WireSchema, types?: ViewTypes): void;
+    /** Install a pre-projected SSR first-paint snapshot (SSR-DESIGN.md §6). The rows are already
+     *  in result shape (json columns parsed, relationships nested), so a view with no live backend
+     *  (the server one-shot Store) reads them directly, and a browser view shows them until its
+     *  first live `hello` (`reset`) swaps in the maintained tree. Does NOT notify — it is set at
+     *  materialize time, before any subscriber, and the live snapshot that follows notifies. */
+    seed(rows: readonly R[]): void;
+    /** Apply a batch (the hydrate snapshot or one transaction's events) in order, then
+     *  notify subscribers once. Order is significant (FLAT-CHANGES-DESIGN.md §5.4). A no-op
+     *  while pending (changes never precede the `hello` that resets the schema). */
+    applyChanges(events: FlatChange[]): void;
+    get data(): readonly R[];
+    subscribe(listener: (data: readonly R[]) => void): () => void;
+    destroy(): void;
+    private applyAt;
+    private applyOp;
+    private applyAdd;
+    private applyRemove;
+    private applyEdit;
+    private project;
+    private notify;
+}
+//# sourceMappingURL=view.d.ts.map

package/dist/view.d.ts.map

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