@tangentfeed/schema 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sreeraj T A
+
+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

@@ -0,0 +1,98 @@
+# @tangentfeed/schema
+
+A typed schema for tangentfeed: infers TypeScript types from one declaration
+and validates local writes. Zero runtime dependencies.
+
+```ts
+import { openSpace } from "tangentfeed";
+import { s, defineSchema } from "@tangentfeed/schema";
+
+const schema = defineSchema({
+  tasks: {
+    title:    s.string(),
+    done:     s.boolean().default(false),
+    priority: s.number().optional(),
+    tags:     s.array(s.string()).default([]),
+  },
+});
+
+const db = await openSpace({ space: "kitchen-42", schema });
+
+await db.insert("tasks", { title: "Oat milk" });   // done and tags defaulted
+await db.insert("tasks", { titel: "typo" });       // compile error + throws
+
+const rows = await db.list("tasks");
+//    ^? { id: string; title: string; done: boolean;
+//         priority?: number; tags: string[] }[]
+```
+
+## What it validates
+
+Local writes only, in `insert` and `update`, before ops are generated.
+Unknown tables, unknown columns, type mismatches and missing required fields
+throw a `SchemaError` carrying `table`, `column`, `expected` and `received`.
+
+**Data arriving from peers is never inspected.** Validation is a local
+precondition — rejected data never becomes an op — so a peer running a
+different schema still syncs with you completely. Filtering reads through a
+local schema would make visible state depend on schema version, which would
+break convergence.
+
+That property is enforced by a test: for input where every defaulted column is
+supplied explicitly, the ops emitted through a schema-wrapped space are
+identical to those from an unwrapped one.
+
+## Reads are asserted, not proven
+
+`list("tasks")` returns `Task[]` because that is the schema you write through,
+not because anything checked the op log. A peer on an older schema may have
+written a number where you expect a string, and nothing here will catch it.
+
+Where that matters, check explicitly:
+
+```ts
+import { parseRow } from "@tangentfeed/schema";
+
+const row = await db.get("tasks", id);
+const checked = parseRow(schema.tasks, row);
+if (!checked.ok) console.warn(checked.issues);
+```
+
+`parseRow` returns a result rather than throwing, and reports every issue
+rather than only the first.
+
+## Field types
+
+`s.string()`, `s.number()`, `s.boolean()`, `s.array(field)`, `s.object(shape)`,
+`s.enum(...values)` — each with `.optional()`, `.nullable()` and
+`.default(value)`.
+
+`.optional()` makes a column omissible on insert and possibly absent on read.
+`.default(v)` makes it omissible on insert but always present on read, because
+the default is written as a real cell. `.nullable()` widens the value, not the
+presence — `Json` allows `null` everywhere, so the DSL makes you say when it is
+meaningful.
+
+`s.object(...)` validates its interior but is **one cell**: cell-level LWW
+merges it atomically. Nesting is storage, not structure.
+
+`update` never applies defaults — it writes individual cells, and inventing a
+default there would clobber a peer's value.
+
+## React
+
+The hooks in `@tangentfeed/react` are generic over the schema, so types carry
+through:
+
+```ts
+const db = useSpace({ space: "kitchen-42", schema });
+const { rows } = useRows(db, "tasks");        // Task[]
+const { insert } = useTable(db, "tasks");     // insert({ title: string, done?: boolean })
+```
+
+## Not included
+
+Migrations and schema versioning, read validation, relations, indexes, and
+bring-your-own-validator interop. Versioning a schema while peers still hold
+rows written under an older one is a hard distributed problem and is
+deliberately out of scope.

package/dist/index.d.ts

@@ -0,0 +1,170 @@
+import { Json } from '@tangentfeed/core';
+
+/**
+ * Field descriptors.
+ *
+ * A descriptor is plain data (kind + flags) carrying three phantom type
+ * parameters that the inference types in ./types.ts read:
+ *
+ *   Out    — the value type when read back
+ *   InOpt  — may the key be omitted on insert?  (.optional() and .default())
+ *   OutOpt — may the key be absent when read?   (.optional() only)
+ *
+ * A defaulted field is optional going in and guaranteed coming out, which is
+ * why InOpt and OutOpt are tracked separately rather than as one flag.
+ */
+
+type FieldKind = "string" | "number" | "boolean" | "array" | "object" | "enum";
+interface FieldInit {
+    kind: FieldKind;
+    isOptional?: boolean;
+    isNullable?: boolean;
+    hasDefault?: boolean;
+    defaultValue?: Json | undefined;
+    element?: AnyField | undefined;
+    shape?: Record<string, AnyField> | undefined;
+    values?: readonly (string | number)[] | undefined;
+}
+declare class Field<Out = unknown, InOpt extends boolean = false, OutOpt extends boolean = false> {
+    readonly kind: FieldKind;
+    readonly isOptional: boolean;
+    readonly isNullable: boolean;
+    readonly hasDefault: boolean;
+    readonly defaultValue: Json | undefined;
+    readonly element: AnyField | undefined;
+    readonly shape: Record<string, AnyField> | undefined;
+    readonly values: readonly (string | number)[] | undefined;
+    readonly __out?: Out;
+    readonly __inOpt?: InOpt;
+    readonly __outOpt?: OutOpt;
+    constructor(init: FieldInit);
+    private clone;
+    /** Key may be omitted on insert, and may be absent when read. */
+    optional(): Field<Out, true, true>;
+    /** Value may be null. Independent of presence. */
+    nullable(): Field<Out | null, InOpt, OutOpt>;
+    /** Key may be omitted on insert; the default is written, so reads always see it. */
+    default(value: Out & Json): Field<Out, true, OutOpt>;
+}
+type AnyField = Field<unknown, boolean, boolean>;
+type TableShape = Record<string, AnyField>;
+type SchemaShape = Record<string, TableShape>;
+declare const s: {
+    string: () => Field<string, false, false>;
+    number: () => Field<number, false, false>;
+    boolean: () => Field<boolean, false, false>;
+    array: <E>(element: Field<E, boolean, boolean>) => Field<E[], false, false>;
+    /**
+     * Validates its interior and infers a nested type, but remains ONE cell:
+     * cell-level LWW merges the whole object atomically. Never add field-level
+     * merging inside an object.
+     */
+    object: <S extends TableShape>(shape: S) => Field<{ [K in keyof S]: S[K] extends Field<infer O, boolean, boolean> ? O : never; }, false, false>;
+    enum: <const V extends readonly (string | number)[]>(...values: V) => Field<V[number], false, false>;
+};
+/** Identity at runtime; exists to pin the generic so inference has something to read. */
+declare function defineSchema<S extends SchemaShape>(shape: S): S;
+
+/**
+ * Local write validation.
+ *
+ * Runs before ops are generated, so rejected data never enters the log. This
+ * is what makes the schema layer convergence-safe: it is a local precondition,
+ * not a filter on shared state. Remote data is never inspected here.
+ */
+
+declare class SchemaError extends Error {
+    readonly table: string;
+    readonly column: string | undefined;
+    readonly expected: string;
+    readonly received: string;
+    constructor(init: {
+        table: string;
+        column?: string | undefined;
+        expected: string;
+        received: string;
+        message: string;
+    });
+}
+/** Full-row validation. Fills defaults and requires every non-optional field. */
+declare function validateInsert(schema: SchemaShape, table: string, values: Record<string, unknown>): Record<string, Json>;
+/**
+ * Partial validation. No defaults: update writes individual cells, and
+ * materialising a default here would clobber a peer's value with a locally
+ * invented one.
+ */
+declare function validateUpdate(schema: SchemaShape, table: string, values: Record<string, unknown>): Record<string, Json>;
+interface ParseIssue {
+    readonly path: string;
+    readonly expected: string;
+    readonly received: string;
+}
+type ParseResult<T> = {
+    readonly ok: true;
+    readonly row: T;
+} | {
+    readonly ok: false;
+    readonly issues: readonly ParseIssue[];
+};
+/**
+ * Opt-in check of a row that has already been read.
+ *
+ * Reads are otherwise asserted rather than proven: the inferred row type
+ * describes the schema you write through, not the contents of the op log. Use
+ * this on paths where a peer may have written under a different schema.
+ *
+ * Collects every issue rather than throwing on the first — the caller is
+ * diagnosing foreign data, not fixing their own typo.
+ */
+declare function parseRow(shape: TableShape, row: unknown): ParseResult<Record<string, Json> & {
+    id: string;
+}>;
+
+/**
+ * Inference. Types only — this module emits no runtime code.
+ *
+ * The split that matters: a field carries InOpt (may the key be omitted on
+ * insert?) and OutOpt (may the key be absent on read?). `.default()` sets only
+ * InOpt, so a defaulted column is optional going in and guaranteed coming out.
+ */
+
+/** The value type a field reads back as. */
+type OutOf<F> = F extends Field<infer Out, boolean, boolean> ? Out : never;
+type InOptionalKeys<T extends TableShape> = {
+    [K in keyof T]: T[K] extends Field<unknown, true, boolean> ? K : never;
+}[keyof T];
+type InRequiredKeys<T extends TableShape> = Exclude<keyof T, InOptionalKeys<T>>;
+type OutOptionalKeys<T extends TableShape> = {
+    [K in keyof T]: T[K] extends Field<unknown, boolean, true> ? K : never;
+}[keyof T];
+type OutRequiredKeys<T extends TableShape> = Exclude<keyof T, OutOptionalKeys<T>>;
+/** Flattens an intersection so editor hovers show one object. */
+type Pretty<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** A row as read back, including the engine-assigned id. */
+type RowOf<S extends SchemaShape, T extends keyof S> = Pretty<{
+    id: string;
+} & {
+    [K in OutRequiredKeys<S[T]>]: OutOf<S[T][K]>;
+} & {
+    [K in OutOptionalKeys<S[T]>]?: OutOf<S[T][K]>;
+}>;
+/** What `insert` accepts: defaulted and optional columns may be omitted. */
+type InsertInput<S extends SchemaShape, T extends keyof S> = Pretty<{
+    [K in InRequiredKeys<S[T]>]: OutOf<S[T][K]>;
+} & {
+    [K in InOptionalKeys<S[T]>]?: OutOf<S[T][K]>;
+}>;
+/** What `update` accepts: any subset of columns, never the id. */
+type UpdateInput<S extends SchemaShape, T extends keyof S> = Pretty<{
+    [K in keyof S[T]]?: OutOf<S[T][K]>;
+}>;
+/** Every table name in the schema. */
+type TableName<S extends SchemaShape> = keyof S & string;
+/** The whole database shape, keyed by table. */
+type Infer<S extends SchemaShape> = {
+    [T in keyof S]: RowOf<S, T>;
+};
+
+export { type AnyField, Field, type FieldKind, type Infer, type InsertInput, type OutOf, type ParseIssue, type ParseResult, type RowOf, SchemaError, type SchemaShape, type TableName, type TableShape, type UpdateInput, defineSchema, parseRow, s, validateInsert, validateUpdate };

package/dist/index.js

@@ -0,0 +1,246 @@
+// src/builders.ts
+var Field = class _Field {
+  kind;
+  isOptional;
+  isNullable;
+  hasDefault;
+  defaultValue;
+  element;
+  shape;
+  values;
+  constructor(init) {
+    this.kind = init.kind;
+    this.isOptional = init.isOptional ?? false;
+    this.isNullable = init.isNullable ?? false;
+    this.hasDefault = init.hasDefault ?? false;
+    this.defaultValue = init.defaultValue;
+    this.element = init.element;
+    this.shape = init.shape;
+    this.values = init.values;
+  }
+  clone(patch) {
+    return new _Field({
+      kind: this.kind,
+      isOptional: this.isOptional,
+      isNullable: this.isNullable,
+      hasDefault: this.hasDefault,
+      defaultValue: this.defaultValue,
+      element: this.element,
+      shape: this.shape,
+      values: this.values,
+      ...patch
+    });
+  }
+  /** Key may be omitted on insert, and may be absent when read. */
+  optional() {
+    return this.clone({ isOptional: true });
+  }
+  /** Value may be null. Independent of presence. */
+  nullable() {
+    return this.clone({ isNullable: true });
+  }
+  /** Key may be omitted on insert; the default is written, so reads always see it. */
+  default(value) {
+    return this.clone({
+      hasDefault: true,
+      defaultValue: value
+    });
+  }
+};
+var s = {
+  string: () => new Field({ kind: "string" }),
+  number: () => new Field({ kind: "number" }),
+  boolean: () => new Field({ kind: "boolean" }),
+  array: (element) => new Field({ kind: "array", element }),
+  /**
+   * Validates its interior and infers a nested type, but remains ONE cell:
+   * cell-level LWW merges the whole object atomically. Never add field-level
+   * merging inside an object.
+   */
+  object: (shape) => new Field({
+    kind: "object",
+    shape
+  }),
+  enum: (...values) => new Field({ kind: "enum", values })
+};
+function defineSchema(shape) {
+  return shape;
+}
+
+// src/validate.ts
+var SchemaError = class extends Error {
+  table;
+  column;
+  expected;
+  received;
+  constructor(init) {
+    super(init.message);
+    this.name = "SchemaError";
+    this.table = init.table;
+    this.column = init.column;
+    this.expected = init.expected;
+    this.received = init.received;
+  }
+};
+function describe(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+function checkValue(field, value, path) {
+  if (value === null) {
+    return field.isNullable ? null : { path, expected: field.kind };
+  }
+  switch (field.kind) {
+    case "string":
+    case "number":
+    case "boolean": {
+      if (typeof value !== field.kind) return { path, expected: field.kind };
+      if (field.kind === "number" && !Number.isFinite(value)) {
+        return { path, expected: "finite number" };
+      }
+      return null;
+    }
+    case "enum": {
+      const allowed = field.values ?? [];
+      return allowed.includes(value) ? null : { path, expected: `one of ${allowed.map((v) => JSON.stringify(v)).join(", ")}` };
+    }
+    case "array": {
+      if (!Array.isArray(value)) return { path, expected: "array" };
+      const element = field.element;
+      if (!element) return null;
+      for (let i = 0; i < value.length; i++) {
+        const bad = checkValue(element, value[i], `${path}[${i}]`);
+        if (bad) return bad;
+      }
+      return null;
+    }
+    case "object": {
+      if (typeof value !== "object" || Array.isArray(value)) return { path, expected: "object" };
+      const shape = field.shape;
+      if (!shape) return null;
+      const record = value;
+      for (const key of Object.keys(record)) {
+        if (!(key in shape)) return { path: `${path}.${key}`, expected: "no such key" };
+      }
+      for (const [key, sub] of Object.entries(shape)) {
+        if (!(key in record)) {
+          if (sub.isOptional) continue;
+          return { path: `${path}.${key}`, expected: `${sub.kind} (missing)` };
+        }
+        const bad = checkValue(sub, record[key], `${path}.${key}`);
+        if (bad) return bad;
+      }
+      return null;
+    }
+  }
+}
+function tableShape(schema, table) {
+  const shape = schema[table];
+  if (!shape) {
+    throw new SchemaError({
+      table,
+      expected: `one of ${Object.keys(schema).join(", ")}`,
+      received: table,
+      message: `unknown table "${table}"`
+    });
+  }
+  return shape;
+}
+function checkColumns(shape, table, values) {
+  const out = {};
+  for (const [column, value] of Object.entries(values)) {
+    const field = shape[column];
+    if (!field) {
+      throw new SchemaError({
+        table,
+        column,
+        expected: `one of ${Object.keys(shape).join(", ")}`,
+        received: column,
+        message: `unknown column "${column}" on table "${table}"`
+      });
+    }
+    const bad = checkValue(field, value, column);
+    if (bad) {
+      throw new SchemaError({
+        table,
+        column,
+        expected: bad.expected,
+        received: describe(value),
+        message: `${table}.${bad.path}: expected ${bad.expected}, received ${describe(value)}`
+      });
+    }
+    out[column] = value;
+  }
+  return out;
+}
+function validateInsert(schema, table, values) {
+  const shape = tableShape(schema, table);
+  const out = checkColumns(shape, table, values);
+  for (const [column, field] of Object.entries(shape)) {
+    if (column in out) continue;
+    if (field.hasDefault) {
+      out[column] = field.defaultValue;
+      continue;
+    }
+    if (field.isOptional) continue;
+    throw new SchemaError({
+      table,
+      column,
+      expected: field.kind,
+      received: "undefined",
+      message: `missing required column "${column}" on table "${table}"`
+    });
+  }
+  return out;
+}
+function validateUpdate(schema, table, values) {
+  const shape = tableShape(schema, table);
+  if (Object.keys(values).length === 0) {
+    throw new SchemaError({
+      table,
+      expected: "at least one column",
+      received: "{}",
+      message: `no columns to update on table "${table}"`
+    });
+  }
+  return checkColumns(shape, table, values);
+}
+function parseRow(shape, row) {
+  if (row === null || typeof row !== "object" || Array.isArray(row)) {
+    return {
+      ok: false,
+      issues: [{ path: "", expected: "object", received: describe(row) }]
+    };
+  }
+  const record = row;
+  const issues = [];
+  for (const key of Object.keys(record)) {
+    if (key === "id") continue;
+    if (!(key in shape)) {
+      issues.push({ path: key, expected: "no such column", received: describe(record[key]) });
+    }
+  }
+  for (const [column, field] of Object.entries(shape)) {
+    if (!(column in record)) {
+      if (!field.isOptional) {
+        issues.push({ path: column, expected: field.kind, received: "undefined" });
+      }
+      continue;
+    }
+    const bad = checkValue(field, record[column], column);
+    if (bad) {
+      issues.push({ path: bad.path, expected: bad.expected, received: describe(record[column]) });
+    }
+  }
+  return issues.length === 0 ? { ok: true, row: record } : { ok: false, issues };
+}
+export {
+  Field,
+  SchemaError,
+  defineSchema,
+  parseRow,
+  s,
+  validateInsert,
+  validateUpdate
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@tangentfeed/schema",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@tangentfeed/core": "0.2.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0",
+    "tsup": "^8.5.0"
+  },
+  "description": "Typed schema layer for tangentfeed: inference plus local write validation",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sreerajta/tangentfeed.git",
+    "directory": "packages/schema"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}