@rindle/client 0.4.2 → 0.4.3

package/src/schema.ts

@@ -8,13 +8,19 @@
 
 import type { Arg, Cond } from "./operators.ts";
 import { fieldCondition } from "./operators.ts";
-import type { ColType } from "./types.ts";
+import type { ColType, WireValue } from "./types.ts";
 
 /** A column descriptor. `type` drives the comparator + JSON parsing; `__t` is a phantom. A
  *  nullable column is a `Col<T | null>` — that is the ONLY thing nullability changes at the type
- *  level, so `RowOf` (and the field-condition factory) widen automatically. */
+ *  level, so `RowOf` (and the field-condition factory) widen automatically.
+ *
+ *  `optional` is the runtime companion of that phantom: set by {@link ColBuilder.nullable}, it is
+ *  what the write funnels read to make a nullable column omittable from an insert (filled with
+ *  `null`, design 206 §6.2). It mirrors the engine's `ColumnDef.optional`
+ *  (`pragma_table_info.notnull == 0`); absent ⇒ `NOT NULL` / required. */
 export interface Col<T> {
   readonly type: ColType;
+  readonly optional?: boolean;
   readonly __t?: T;
 }
 export type ColT<X> = X extends Col<infer T> ? T : never;
@@ -24,13 +30,18 @@ export type RowOf<C extends AnyCols> = { [K in keyof C]: ColT<C[K]> };
 /** The chainable form returned by the column factories: a {@link Col} plus `.nullable()`.
  *
  *  `.nullable()` widens the column's value type to `T | null` — its `Row<…>` field becomes
- *  `T | null`, and (design 206 Phase 2) it may be omitted from an insert. `rindle schema gen` emits
- *  `.nullable()` for every nullable (non-`NOT NULL`) SQL column; you can also call it by hand on a
- *  local-only table's columns. It is idempotent and stays chainable. */
+ *  `T | null` — and sets the runtime {@link Col.optional} marker so it may be omitted from an insert
+ *  (design 206 §6.2). `rindle schema gen` emits `.nullable()` for every nullable (non-`NOT NULL`) SQL
+ *  column; you can also call it by hand on a local-only table's columns. It is idempotent and stays
+ *  chainable. */
 export interface ColBuilder<T> extends Col<T> {
   nullable(): ColBuilder<T | null>;
 }
-const makeCol = <T>(type: ColType): ColBuilder<T> => ({ type, nullable: () => makeCol<T | null>(type) });
+const makeCol = <T>(type: ColType, optional = false): ColBuilder<T> => ({
+  type,
+  ...(optional ? { optional: true } : null),
+  nullable: () => makeCol<T | null>(type, true),
+});
 
 export const string = <T extends string = string>(): ColBuilder<T> => makeCol<T>("string");
 export const number = <T extends number = number>(): ColBuilder<T> => makeCol<T>("number");
@@ -40,13 +51,15 @@ export const json = <T = unknown>(): ColBuilder<T> => makeCol<T>("json");
 /** Metadata key on a {@link TableDef} (a `unique symbol`, so no column name collides). */
 export const SCHEMA: unique symbol = Symbol("rindle.schema");
 
-export interface TableMeta<N extends string = string, C extends AnyCols = AnyCols> {
+export interface TableMeta<N extends string = string, C extends AnyCols = AnyCols, PK extends string = string> {
   readonly name: N;
   readonly columns: C;
-  // Plain `string[]` (NOT `keyof C`): `keyof C` is contravariant, which would make
-  // `TableMeta` non-covariant in `C` and break `TableDef<concrete>` → `AnyTable`. Key
-  // validity is enforced on the `primaryKey()` builder method (`K extends keyof C`).
-  readonly primaryKey: readonly string[];
+  // `PK` is an INDEPENDENT param (a plain string union), NOT `keyof C`: `keyof C` would be
+  // contravariant and make `TableMeta` non-covariant in `C`, breaking `TableDef<concrete>` →
+  // `AnyTable`. Key validity is enforced on the `primaryKey()` builder (`K extends keyof C`); PK is
+  // captured there so the mutator tx can type `update`/`delete` pk args (`PkOf`/`UpdateOf`). The
+  // default `string` erases it (older 2-arg `TableMeta<N, C>` refs still resolve).
+  readonly primaryKey: readonly PK[];
   /** A **local-only** table (`201-LOCAL-ONLY-TABLES-DESIGN.md`): client-authoritative,
    *  never synced/tracked/rebased. The single marker the whole design keys off (§4) — it is
    *  immutable for the table's lifetime (N2) and never crosses the wire (C2). Absent ⇒ an
@@ -62,8 +75,8 @@ export interface TableOptions {
   local?: boolean;
 }
 
-export type TableDef<N extends string, C extends AnyCols> = {
-  readonly [SCHEMA]: TableMeta<N, C>;
+export type TableDef<N extends string, C extends AnyCols, PK extends string = string> = {
+  readonly [SCHEMA]: TableMeta<N, C, PK>;
 } & {
   readonly [K in keyof C]: (arg: Arg<ColT<C[K]>>) => Cond<RowOf<C>>;
 };
@@ -79,28 +92,77 @@ export type AnyTable = TableLike<AnyCols>;
  *  the schema instead of hand-maintaining a parallel twin. */
 export type Row<T extends AnyTable> = RowOf<T[typeof SCHEMA]["columns"]>;
 
+/** Flatten an intersection of mapped types into a single object type (preserving `?`/`readonly`) so
+ *  {@link InsertOf} reads as one clean shape in editor hovers, not `A & B`. */
+type Simplify<T> = { [K in keyof T]: T[K] };
+
+/** True for the top types `unknown`/`any` (`unknown extends any` too), where `[null] extends [T]` is
+ *  vacuously true and so can't tell a `.nullable()` apart. */
+type IsTop<T> = unknown extends T ? true : false;
+
+/** Whether column `X` may be OMITTED from an insert: it admits `null` at the type level — EXCLUDING
+ *  the top types. A bare `json()` is `json<unknown>()`, and `unknown | null` collapses back to
+ *  `unknown`, erasing whether `.nullable()` was applied; treating it as required is the safe
+ *  direction (a `NOT NULL` json column is never wrongly made optional). Declare `json<T>()` to make a
+ *  nullable json column omittable. The runtime companion is `Col.optional` (design 206 §6.2/§7). */
+type InsertOptional<X> = IsTop<ColT<X>> extends true ? false : [null] extends [ColT<X>] ? true : false;
+
+/** The INSERT shape of a column map: {@link RowOf} with every NULLABLE column made OPTIONAL (`?`) —
+ *  it may be omitted and is filled with `null` by both write funnels (design 206 §6.2/§7). `NOT NULL`
+ *  columns stay required. The insert-side twin of {@link RowOf}, mirroring Drizzle's `$inferInsert`
+ *  vs `$inferSelect` split. */
+export type InsertOf<C extends AnyCols> = Simplify<
+  { [K in keyof C as InsertOptional<C[K]> extends true ? never : K]: ColT<C[K]> } & {
+    [K in keyof C as InsertOptional<C[K]> extends true ? K : never]?: ColT<C[K]>;
+  }
+>;
+
+/** The insert type of a table def: `Insert<typeof issue>` → `{ id: string; … assignee?: string | null }`.
+ *  The whole-table ergonomic form of {@link InsertOf} (the insert-side twin of {@link Row}). */
+export type Insert<T extends AnyTable> = InsertOf<T[typeof SCHEMA]["columns"]>;
+
+/** The exact PRIMARY-KEY columns of a table (each typed), required — the identity a `delete`/`row`,
+ *  and the WHERE half of an `update`, take. `PK` is the table's pk-column union (the schema's `__pk`). */
+export type PkOf<C extends AnyCols, PK extends string> = { [K in PK & keyof C]: ColT<C[K & keyof C]> };
+
+/** The UPDATE shape of a table: its {@link PkOf primary-key columns} REQUIRED (they identify the row)
+ *  plus every non-pk column OPTIONAL (`?`) and typed — a nullable one stays `T | null` (settable to
+ *  null), a `NOT NULL` one is `T`. Omitted non-pk columns are left unchanged. */
+export type UpdateOf<C extends AnyCols, PK extends string> = Simplify<
+  PkOf<C, PK> & { [K in Exclude<keyof C, PK>]?: ColT<C[K]> }
+>;
+
+/** The primary-key column union for table `N` of a schema, read from its `__pk` map `P` and narrowed
+ *  to `N`'s actual columns (falling back to all columns when `P` doesn't name `N` — e.g. the loose
+ *  default schema). Feeds {@link PkOf}/{@link UpdateOf} in the typed mutator tx. */
+export type PkColsOf<S extends ColsMap, P extends Record<string, string>, N extends keyof S> = (N extends keyof P
+  ? P[N]
+  : keyof S[N] & string) &
+  keyof S[N] &
+  string;
+
 /** `table("issue").columns({ id: string(), … }).primaryKey("id")`. Pass `{ local: true }` for a
  *  {@link TableMeta.local local-only} table (`201-LOCAL-ONLY-TABLES-DESIGN.md`). */
 export function table<N extends string>(name: N, opts?: TableOptions) {
   return {
     columns<C extends AnyCols>(cols: C) {
       return {
-        primaryKey<K extends keyof C & string>(...keys: K[]): TableDef<N, C> {
-          return makeTableDef<N, C>({ name, columns: cols, primaryKey: keys, local: opts?.local });
+        primaryKey<K extends keyof C & string>(...keys: K[]): TableDef<N, C, K> {
+          return makeTableDef<N, C, K>({ name, columns: cols, primaryKey: keys, local: opts?.local });
         },
       };
     },
   };
 }
 
-function makeTableDef<N extends string, C extends AnyCols>(meta: TableMeta<N, C>): TableDef<N, C> {
+function makeTableDef<N extends string, C extends AnyCols, PK extends string>(meta: TableMeta<N, C, PK>): TableDef<N, C, PK> {
   return new Proxy({} as Record<string | symbol, unknown>, {
     get(_target, prop) {
       if (prop === SCHEMA) return meta;
       if (typeof prop === "string") return (arg: unknown) => fieldCondition(prop, arg);
       return undefined;
     },
-  }) as unknown as TableDef<N, C>;
+  }) as unknown as TableDef<N, C, PK>;
 }
 
 /** Read a table's metadata (columns / PK / name). */
@@ -113,13 +175,25 @@ export type SchemaOf<T extends readonly AnyTable[]> = {
   [E in T[number] as E[typeof SCHEMA]["name"]]: E[typeof SCHEMA]["columns"];
 };
 
+/** name → its primary-key column union, derived from the tables array (the PK captured by the
+ *  `primaryKey(...)` builder). Powers the mutator tx's typed `update`/`delete`/`row` pk args. */
+export type PkMapOf<T extends readonly AnyTable[]> = {
+  [E in T[number] as E[typeof SCHEMA]["name"]]: E[typeof SCHEMA]["primaryKey"][number];
+};
+
 /** name → columns, the resolved schema map carried in the {@link Schema} type. */
 export type ColsMap = Record<string, AnyCols>;
 
-export interface Schema<S extends ColsMap = ColsMap> {
+/** name → (some subset of its column names): the loose shape a {@link Schema}'s pk-map satisfies. The
+ *  fallback when a schema wasn't built through {@link createSchema} — every column could be the pk. */
+export type PkMap<S extends ColsMap> = { [N in keyof S]: keyof S[N] & string };
+
+export interface Schema<S extends ColsMap = ColsMap, P extends Record<string, string> = PkMap<S>> {
   readonly tables: Readonly<Record<string, TableMeta>>;
   /** Phantom carrying name→columns for query-root inference (never read at runtime). */
   readonly __cols: S;
+  /** Phantom carrying name→pk-column-union for the typed mutator tx (never read at runtime). */
+  readonly __pk: P;
 }
 
 /** Table-name prefixes reserved by the engine for SYNTHETIC tables — `__agg_<fnv>` aggregate
@@ -138,13 +212,13 @@ export function isReservedTableName(name: string): boolean {
 
 export function createSchema<const T extends readonly AnyTable[]>(opts: {
   tables: T;
-}): Schema<SchemaOf<T>> {
+}): Schema<SchemaOf<T>, PkMapOf<T>> {
   const tables: Record<string, TableMeta> = {};
   for (const t of opts.tables) {
     const m = t[SCHEMA];
     addTableMeta(tables, m, "createSchema");
   }
-  return { tables } as Schema<SchemaOf<T>>;
+  return { tables } as unknown as Schema<SchemaOf<T>, PkMapOf<T>>;
 }
 
 /** Extend a generated/synced schema with client-authoritative local-only tables.
@@ -154,10 +228,10 @@ export function createSchema<const T extends readonly AnyTable[]>(opts: {
  *  client. The added tables MUST be `table(name, { local: true })`: `extendSchema` deliberately
  *  refuses to append ordinary synced tables, because those need to come from daemon introspection
  *  (`rindle schema gen`) so the server and client cannot drift. */
-export function extendSchema<S extends ColsMap, const T extends readonly AnyTable[]>(
-  base: Schema<S>,
+export function extendSchema<S extends ColsMap, P extends Record<string, string>, const T extends readonly AnyTable[]>(
+  base: Schema<S, P>,
   opts: { tables: T },
-): Schema<S & SchemaOf<T>> {
+): Schema<S & SchemaOf<T>, P & PkMapOf<T>> {
   const tables: Record<string, TableMeta> = { ...base.tables };
   for (const t of opts.tables) {
     const m = t[SCHEMA];
@@ -168,7 +242,7 @@ export function extendSchema<S extends ColsMap, const T extends readonly AnyTabl
     }
     addTableMeta(tables, m, "extendSchema");
   }
-  return { tables } as Schema<S & SchemaOf<T>>;
+  return { tables } as unknown as Schema<S & SchemaOf<T>, P & PkMapOf<T>>;
 }
 
 function addTableMeta(tables: Record<string, TableMeta>, m: TableMeta, caller: "createSchema" | "extendSchema") {
@@ -257,10 +331,10 @@ export type RefinedColsMap<S extends ColsMap, T extends readonly AnyTable[]> = {
  *  Runtime-validated identity: each def must name a table already in the schema and match its
  *  runtime shape exactly (same columns, kinds, primary key, and locality) — refinement narrows TS
  *  types, never what's on the wire. Composes with {@link extendSchema} in either order. */
-export function refineSchema<S extends ColsMap, const T extends readonly RefinableTable<S>[]>(
-  base: Schema<S>,
+export function refineSchema<S extends ColsMap, P extends Record<string, string>, const T extends readonly RefinableTable<S>[]>(
+  base: Schema<S, P>,
   opts: { tables: T },
-): Schema<RefinedColsMap<S, T>> {
+): Schema<RefinedColsMap<S, T>, P> {
   const seen = new Set<string>();
   for (const t of opts.tables) {
     const m = t[SCHEMA];
@@ -277,7 +351,7 @@ export function refineSchema<S extends ColsMap, const T extends readonly Refinab
     seen.add(m.name);
     assertRefinementMatches(m, baseMeta);
   }
-  return base as unknown as Schema<RefinedColsMap<S, T>>;
+  return base as unknown as Schema<RefinedColsMap<S, T>, P>;
 }
 
 /** The refined def must be the same table the schema already carries — identical column set, kinds,
@@ -372,6 +446,43 @@ export function tableSpec(meta: TableMeta): { columns: string[]; primaryKey: num
   return { columns, primaryKey };
 }
 
+/** A table's insert-completeness plan, derived once from its `Col` markers and shared by BOTH write
+ *  funnels — the client `trackingTx` and the server `renderOp` — so their required-sets can't drift
+ *  (design 206 §6.1/§6.2). A `NOT NULL` column is `required`; a nullable column (`.nullable()` set
+ *  `Col.optional`) may be omitted and is filled with `null` (see {@link insertCell}). PK columns are
+ *  never nullable (introspection forces them non-null), so they are always required. */
+export interface InsertPlan {
+  /** Every column, in wire order. */
+  readonly columns: string[];
+  /** Columns that MUST be present on a full insert — the non-nullable ones. */
+  readonly required: string[];
+  /** The nullable (omittable-to-null) columns, for a fast membership test in the fill. */
+  readonly nullable: ReadonlySet<string>;
+}
+
+/** Derive a table's {@link InsertPlan} from its column markers. */
+export function insertPlan(meta: TableMeta): InsertPlan {
+  const columns = Object.keys(meta.columns);
+  const nullable = new Set(columns.filter((c) => meta.columns[c].optional === true));
+  return { columns, required: columns.filter((c) => !nullable.has(c)), nullable };
+}
+
+/** The cell a full insert writes for column `c`: the given value, or `null` when a nullable column
+ *  is omitted (design 206 §6.2). The caller's completeness check ({@link InsertPlan.required})
+ *  guarantees a non-nullable column is present, so its omission never reaches here. */
+export function insertCell(row: Record<string, WireValue>, c: string): WireValue {
+  return c in row ? row[c] : null;
+}
+
+/** Encode a keyed-row cell to its wire {@link WireValue} for a column KIND — the one place both write
+ *  funnels stringify a `json<T>` object (the typed mutator surface / design 206 §7). An
+ *  already-stringified json value (a `string`) or any non-json cell passes through unchanged, so a
+ *  mutator may pass EITHER a parsed object OR a JSON string. Mirrors `store.positionalize`. */
+export function toCell(v: WireValue | object, type: ColType): WireValue {
+  if (type === "json" && v !== null && typeof v === "object") return JSON.stringify(v);
+  return v as WireValue;
+}
+
 /** The client's per-table flat schema (name + column order + PK indices), the shape a
  *  normalized `hello` advertises (NORMALIZED-CHANGES-DESIGN.md §3). Used to validate a
  *  server hello against the CLIENT's own typed schema so a column-order / PK skew is caught

package/src/store.ts

@@ -10,7 +10,7 @@
 import type { Ast } from "./ast.ts";
 import { stableKey } from "./key.ts";
 import { queries, type Query, type QueryRoot } from "./query.ts";
-import type { ColsMap, RowOf, Schema } from "./schema.ts";
+import type { ColsMap, InsertOf, RowOf, Schema } from "./schema.ts";
 import type { Backend, ChangeEvent, ColType, FlatChange, Mutation, QueryId, RemoteQuery, ResultType, WireSchema, WireValue } from "./types.ts";
 import { type ArrayView, FlatArrayView, type SingularArrayView, SingularView, type ViewTypes } from "./view.ts";
 
@@ -36,9 +36,13 @@ export interface AssembledNode {
 }
 
 /** The write transaction handed to `store.write(tx => …)`. Rows are objects keyed by column;
- *  the Store positionalizes them (and stringifies json columns) before the backend sees them. */
+ *  the Store positionalizes them (and stringifies json columns) before the backend sees them.
+ *
+ *  `add` takes an {@link InsertOf} row — a nullable column may be omitted (it is filled with `null`,
+ *  design 206 §7). `remove`/`edit` take a full {@link RowOf} row: they identify an EXISTING row, so
+ *  every column (nullable ones as their actual `T | null` value) must be present. */
 export interface WriteTx<S extends ColsMap> {
-  add<N extends keyof S & string>(table: N, row: RowOf<S[N]>): void;
+  add<N extends keyof S & string>(table: N, row: InsertOf<S[N]>): void;
   remove<N extends keyof S & string>(table: N, row: RowOf<S[N]>): void;
   edit<N extends keyof S & string>(table: N, oldRow: RowOf<S[N]>, newRow: RowOf<S[N]>): void;
 }