@frockbot/applet-sdk 0.0.0 → 0.3.13

package/src/schema/index.ts

@@ -0,0 +1,436 @@
+/**
+ * Schema-first table and column declarations.
+ *
+ * One declaration produces four things that must never drift apart: the SQLite
+ * DDL the server creates, the row validator every write goes through, the JSON
+ * Schema a tool declaration publishes, and the TypeScript row/insert types the
+ * author and the client see. Everything else in the SDK reads this module
+ * rather than re-deriving any of them.
+ */
+
+export type ColumnKind =
+  "id" | "text" | "integer" | "real" | "boolean" | "timestamp" | "json";
+
+export interface ColumnDefinition {
+  readonly kind: ColumnKind;
+  readonly optional: boolean;
+  readonly hasDefault: boolean;
+  readonly defaultValue?: unknown;
+}
+
+const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_]{0,62}$/;
+/** Table names the SDK owns; an Applet may not declare them. */
+export const RESERVED_TABLE_PREFIX = "_applet_";
+
+/** Value surfaced to TypeScript for a column of each kind. */
+export interface ColumnValueByKind {
+  id: string;
+  text: string;
+  integer: number;
+  real: number;
+  boolean: boolean;
+  /** ISO-8601 UTC instant, stored as TEXT so it sorts lexicographically. */
+  timestamp: string;
+  json: unknown;
+}
+
+export class Column<
+  TValue = unknown,
+  TOptional extends boolean = false,
+  THasDefault extends boolean = false,
+> {
+  /** Nominal marker so `ColumnValue<C>` can never resolve structurally. */
+  declare readonly __value: TValue;
+  declare readonly __optional: TOptional;
+  declare readonly __hasDefault: THasDefault;
+
+  constructor(readonly definition: ColumnDefinition) {}
+
+  /**
+   * A value written when the insert omits the column. Also makes the column
+   * optional in the insert type.
+   */
+  default(value: TValue): Column<TValue, TOptional, true> {
+    return new Column({
+      ...this.definition,
+      hasDefault: true,
+      defaultValue: value,
+    });
+  }
+
+  /** Nullable in SQLite, `T | null` in TypeScript, omittable on insert. */
+  optional(): Column<TValue | null, true, THasDefault> {
+    return new Column({ ...this.definition, optional: true });
+  }
+}
+
+export type AnyColumn = Column<any, boolean, boolean>;
+
+function column<K extends ColumnKind>(
+  kind: K,
+): Column<ColumnValueByKind[K], false, K extends "id" ? true : false> {
+  return new Column({
+    kind,
+    optional: false,
+    // An id is generated by the server when the insert omits it.
+    hasDefault: kind === "id",
+  }) as never;
+}
+
+/** Column constructors. `t.id()` is the primary key and is server-generated. */
+export const t = {
+  id: () => column("id"),
+  text: () => column("text"),
+  integer: () => column("integer"),
+  real: () => column("real"),
+  boolean: () => column("boolean"),
+  timestamp: () => column("timestamp"),
+  json: () => column("json"),
+} as const;
+
+export type ColumnsShape = Record<string, AnyColumn>;
+
+export class TableDefinition<TColumns extends ColumnsShape = ColumnsShape> {
+  readonly primaryKey: string;
+
+  constructor(readonly columns: TColumns) {
+    const names = Object.keys(columns);
+    if (names.length === 0 || names.length > 64) {
+      throw new Error("A table must declare between 1 and 64 columns");
+    }
+    const keys: string[] = [];
+    for (const name of names) {
+      if (!IDENTIFIER.test(name)) {
+        throw new Error(`Column name "${name}" is not a valid identifier`);
+      }
+      if (columns[name]!.definition.kind === "id") keys.push(name);
+    }
+    if (keys.length !== 1) {
+      throw new Error("A table must declare exactly one t.id() column");
+    }
+    if (columns[keys[0]!]!.definition.optional) {
+      throw new Error("The t.id() column may not be optional");
+    }
+    this.primaryKey = keys[0]!;
+  }
+}
+
+/** Declare a table. Column order is the DDL order and the snapshot order. */
+export function table<TColumns extends ColumnsShape>(
+  columns: TColumns,
+): TableDefinition<TColumns> {
+  return new TableDefinition(columns);
+}
+
+export type TablesShape = Record<string, TableDefinition<ColumnsShape>>;
+
+// ---------------------------------------------------------------------------
+// Type inference
+// ---------------------------------------------------------------------------
+
+type ColumnValue<C> = C extends Column<infer V, boolean, boolean> ? V : never;
+type OptionalOnInsert<C> =
+  C extends Column<unknown, infer O, infer D>
+    ? O extends true
+      ? true
+      : D extends true
+        ? true
+        : false
+    : false;
+
+type InsertOptionalKeys<TColumns extends ColumnsShape> = {
+  [K in keyof TColumns]: OptionalOnInsert<TColumns[K]> extends true ? K : never;
+}[keyof TColumns];
+
+/** The shape a row has once it is stored: every column present. */
+export type RowOf<T> =
+  T extends TableDefinition<infer TColumns>
+    ? { [K in keyof TColumns]: ColumnValue<TColumns[K]> }
+    : never;
+
+/** The shape an insert accepts: defaulted and optional columns may be omitted. */
+export type InsertOf<T> =
+  T extends TableDefinition<infer TColumns>
+    ? {
+        [
+          K in Exclude<keyof TColumns, InsertOptionalKeys<TColumns>>
+        ]: ColumnValue<TColumns[K]>;
+      } & {
+        [K in InsertOptionalKeys<TColumns> & keyof TColumns]?: ColumnValue<
+          TColumns[K]
+        >;
+      }
+    : never;
+
+/** The shape an update accepts: any column but the primary key. */
+export type PatchOf<T> =
+  T extends TableDefinition<infer TColumns>
+    ? Partial<{ [K in keyof TColumns]: ColumnValue<TColumns[K]> }>
+    : never;
+
+// ---------------------------------------------------------------------------
+// DDL
+// ---------------------------------------------------------------------------
+
+const SQLITE_TYPE: Record<ColumnKind, string> = {
+  id: "TEXT",
+  text: "TEXT",
+  integer: "INTEGER",
+  real: "REAL",
+  boolean: "INTEGER",
+  timestamp: "TEXT",
+  json: "TEXT",
+};
+
+/** Also allows the SDK's own leading-underscore tables. */
+const SQL_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]{0,62}$/;
+
+export function quoteIdentifier(name: string): string {
+  if (!SQL_IDENTIFIER.test(name)) {
+    throw new Error(`"${name}" is not a valid SQL identifier`);
+  }
+  return `"${name}"`;
+}
+
+function columnDdl(name: string, definition: ColumnDefinition): string {
+  const type = SQLITE_TYPE[definition.kind];
+  if (definition.kind === "id") {
+    return `${quoteIdentifier(name)} ${type} PRIMARY KEY NOT NULL`;
+  }
+  return `${quoteIdentifier(name)} ${type}${definition.optional ? "" : " NOT NULL"}`;
+}
+
+/** `CREATE TABLE IF NOT EXISTS`; safe to run on every mount. */
+export function createTableStatement(
+  name: string,
+  definition: TableDefinition,
+): string {
+  const columns = Object.entries(definition.columns).map(([column, spec]) =>
+    columnDdl(column, spec.definition),
+  );
+  return `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(name)} (${columns.join(", ")})`;
+}
+
+/**
+ * `ALTER TABLE ... ADD COLUMN` for a column added since the table was created.
+ * SQLite refuses a NOT NULL add without a default, so an added required column
+ * is written with the column's default and rejected when it has none — which
+ * is exactly the case an Applet must handle in `migrate`.
+ */
+export function addColumnStatement(
+  table: string,
+  name: string,
+  column: AnyColumn,
+): string {
+  const definition = column.definition;
+  if (definition.kind === "id") {
+    throw new Error("The primary key cannot be added to an existing table");
+  }
+  const type = SQLITE_TYPE[definition.kind];
+  if (definition.optional) {
+    return `ALTER TABLE ${quoteIdentifier(table)} ADD COLUMN ${quoteIdentifier(name)} ${type}`;
+  }
+  if (!definition.hasDefault) {
+    throw new Error(
+      `Column "${table}.${name}" was added without .default() or .optional(); ` +
+        "existing rows have no value for it",
+    );
+  }
+  const literal = sqlLiteral(
+    encodeValue(name, definition, definition.defaultValue),
+  );
+  return `ALTER TABLE ${quoteIdentifier(table)} ADD COLUMN ${quoteIdentifier(name)} ${type} NOT NULL DEFAULT ${literal}`;
+}
+
+function sqlLiteral(value: SqlValue): string {
+  if (value === null) return "NULL";
+  if (typeof value === "number") return String(value);
+  return `'${value.replaceAll("'", "''")}'`;
+}
+
+// ---------------------------------------------------------------------------
+// Value coding and validation
+// ---------------------------------------------------------------------------
+
+export type SqlValue = string | number | null;
+
+export class AppletValidationError extends Error {}
+
+function fail(message: string): never {
+  throw new AppletValidationError(message);
+}
+
+const ISO =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/;
+
+/** Validate an author- or client-supplied value and encode it for SQLite. */
+export function encodeValue(
+  name: string,
+  definition: ColumnDefinition,
+  value: unknown,
+): SqlValue {
+  if (value === null || value === undefined) {
+    if (!definition.optional) fail(`Column "${name}" may not be null`);
+    return null;
+  }
+  switch (definition.kind) {
+    case "id":
+    case "text":
+      if (typeof value !== "string" || value.length > 16_384) {
+        fail(`Column "${name}" must be a string of at most 16384 characters`);
+      }
+      return value;
+    case "integer":
+      if (!Number.isSafeInteger(value)) {
+        fail(`Column "${name}" must be a safe integer`);
+      }
+      return value as number;
+    case "real":
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        fail(`Column "${name}" must be a finite number`);
+      }
+      return value;
+    case "boolean":
+      if (typeof value !== "boolean")
+        fail(`Column "${name}" must be a boolean`);
+      return value ? 1 : 0;
+    case "timestamp":
+      if (typeof value !== "string" || !ISO.test(value)) {
+        fail(`Column "${name}" must be an ISO-8601 instant`);
+      }
+      return value;
+    case "json": {
+      let wire: string;
+      try {
+        wire = JSON.stringify(value);
+      } catch {
+        return fail(`Column "${name}" must contain acyclic JSON`);
+      }
+      if (wire === undefined) fail(`Column "${name}" must contain JSON`);
+      if (wire.length > 65_536) fail(`Column "${name}" JSON is too large`);
+      return wire;
+    }
+  }
+}
+
+/** Decode a SQLite cell back to the value the author and client see. */
+export function decodeValue(
+  definition: ColumnDefinition,
+  value: unknown,
+): unknown {
+  if (value === null || value === undefined) return null;
+  switch (definition.kind) {
+    case "boolean":
+      return value !== 0;
+    case "json":
+      return JSON.parse(String(value));
+    case "integer":
+    case "real":
+      return Number(value);
+    default:
+      return String(value);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// JSON Schema (tool inputs)
+// ---------------------------------------------------------------------------
+
+export interface JsonSchemaObject {
+  type: "object";
+  properties: Record<string, Record<string, unknown>>;
+  required: string[];
+  additionalProperties: false;
+}
+
+const JSON_SCHEMA_BY_KIND: Record<ColumnKind, Record<string, unknown>> = {
+  id: { type: "string" },
+  text: { type: "string" },
+  integer: { type: "integer" },
+  real: { type: "number" },
+  boolean: { type: "boolean" },
+  timestamp: { type: "string", format: "date-time" },
+  json: {},
+};
+
+/** Turn a record of columns into the JSON Schema a tool declaration carries. */
+export function jsonSchemaFromColumns(columns: ColumnsShape): JsonSchemaObject {
+  const properties: Record<string, Record<string, unknown>> = {};
+  const required: string[] = [];
+  for (const [name, spec] of Object.entries(columns)) {
+    const definition = spec.definition;
+    const base = { ...JSON_SCHEMA_BY_KIND[definition.kind] };
+    properties[name] = definition.optional
+      ? { anyOf: [base, { type: "null" }] }
+      : base;
+    if (!definition.optional && !definition.hasDefault) required.push(name);
+  }
+  return { type: "object", properties, required, additionalProperties: false };
+}
+
+/** Validate a tool input against its declared columns and decode it. */
+export function decodeToolInput(
+  columns: ColumnsShape,
+  input: unknown,
+): Record<string, unknown> {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    fail("Tool input must be an object");
+  }
+  const value = input as Record<string, unknown>;
+  for (const key of Object.keys(value)) {
+    if (!Object.hasOwn(columns, key)) fail(`Unknown tool input field "${key}"`);
+  }
+  const out: Record<string, unknown> = {};
+  for (const [name, spec] of Object.entries(columns)) {
+    const definition = spec.definition;
+    const supplied = value[name];
+    if (supplied === undefined) {
+      if (definition.hasDefault) {
+        out[name] = definition.defaultValue;
+        continue;
+      }
+      if (definition.optional) {
+        out[name] = null;
+        continue;
+      }
+      fail(`Tool input field "${name}" is required`);
+    }
+    // Encode to validate, decode to hand the author the ordinary value.
+    out[name] = decodeValue(
+      definition,
+      encodeValue(name, definition, supplied),
+    );
+  }
+  return out;
+}
+
+/**
+ * A stable fingerprint of the declared schema. The server stores it so a mount
+ * over existing storage can tell "unchanged" from "needs migrate" without the
+ * author maintaining a revision number by hand.
+ */
+export function schemaFingerprint(tables: TablesShape): string {
+  const shape = Object.keys(tables)
+    .sort()
+    .map((name) => {
+      const definition = tables[name]!;
+      const columns = Object.entries(definition.columns).map(
+        ([column, spec]) =>
+          `${column}:${spec.definition.kind}${spec.definition.optional ? "?" : ""}`,
+      );
+      return `${name}(${columns.join(",")})`;
+    });
+  return shape.join(";");
+}
+
+export function assertTableNames(tables: TablesShape): void {
+  const names = Object.keys(tables);
+  if (names.length === 0 || names.length > 32) {
+    throw new Error("An Applet must declare between 1 and 32 tables");
+  }
+  for (const name of names) {
+    if (!IDENTIFIER.test(name) || name.startsWith(RESERVED_TABLE_PREFIX)) {
+      throw new Error(`Table name "${name}" is invalid or reserved`);
+    }
+  }
+}