@syncular/typegen 0.1.2 → 0.2.0

package/src/index.ts

@@ -1,16 +1,19 @@
 /**
- * @syncular/typegen - Generate TypeScript types from migrations
- *
- * Creates type definitions by:
- * 1. Applying migrations to an in-memory database (SQLite or PostgreSQL)
- * 2. Introspecting the resulting schema
- * 3. Generating TypeScript interfaces
+ * @syncular/typegen — SQL migrations + syncular.json → neutral schema
+ * IR (JSON) → generated TS module (REVISE B5). Dependency-free; the CLI
+ * lives in `src/cli.ts` (bin `syncular`).
  */
-
-export * from './app-contract';
-export * from './checksums';
+export * from './emit';
+export * from './emit-dart';
+export * from './emit-kotlin';
+export * from './emit-queries';
+export * from './emit-queries-dart';
+export * from './emit-queries-kotlin';
+export * from './emit-queries-swift';
+export * from './emit-swift';
+export * from './errors';
 export * from './generate';
-export * from './introspect';
-export * from './map-types';
-export * from './render';
-export * from './types';
+export * from './ir';
+export * from './manifest';
+export * from './query';
+export * from './sql';

package/src/init.ts

@@ -0,0 +1,100 @@
+/**
+ * `syncular init` — drop a starter `syncular.json` + `migrations/0001_initial`
+ * into an existing project (the "add syncular to my app" path). Writes nothing
+ * that would clobber an existing manifest or migration; fails loud instead.
+ *
+ * The starter mirrors the `create-app` minimal template's schema shape so the
+ * two on-ramps agree. Kept dependency-free and pure of process concerns.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { MANIFEST_FILENAME } from './manifest';
+
+const STARTER_MANIFEST = `{
+  "manifestVersion": 1,
+  "migrations": "./migrations",
+  "queries": "./queries",
+  "output": {
+    "ir": "./syncular.ir.json",
+    "module": "./src/syncular.generated.ts",
+    "queries": "./src/syncular.queries.ts"
+  },
+  "schemaVersions": [{ "version": 1, "through": "0001_initial" }],
+  "tables": [{ "name": "notes", "scopes": ["list:{list_id}"] }],
+  "subscriptions": [
+    {
+      "name": "notesInList",
+      "table": "notes",
+      "scopes": { "list_id": ["{listId}"] }
+    }
+  ]
+}
+`;
+
+const STARTER_MIGRATION = `-- Your first table. typegen reads this for the schema SHAPE (column types,
+-- primary key); the server manages its own sync_* tables and never runs it.
+CREATE TABLE notes (
+  id TEXT PRIMARY KEY,
+  list_id TEXT NOT NULL,
+  body TEXT NOT NULL,
+  updated_at_ms INTEGER NOT NULL
+);
+`;
+
+// A starter NAMED query (the typed .sql read tier). typegen type-checks it
+// against the schema via SQLite and emits a typed \`notesInList(client, listId)\`
+// + \`NotesInListRow\` into src/syncular.queries.ts. :listId infers to TEXT
+// (compared against notes.list_id).
+const STARTER_QUERY = `-- Every note in a list, id-ordered. Typed by SQLite against your schema.
+SELECT id, list_id, body, updated_at_ms
+FROM notes
+WHERE list_id = :listId
+ORDER BY id
+`;
+
+export interface InitResult {
+  readonly written: readonly string[];
+}
+
+/** Errors that carry a friendly, actionable message for the CLI. */
+export class InitError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'InitError';
+  }
+}
+
+/**
+ * Create the starter files under `dir`. Refuses to overwrite an existing
+ * manifest or `migrations/0001_initial/up.sql`.
+ */
+export function initProject(dir: string): InitResult {
+  const root = resolve(dir);
+  const manifestPath = join(root, MANIFEST_FILENAME);
+  const migrationDir = join(root, 'migrations', '0001_initial');
+  const migrationPath = join(migrationDir, 'up.sql');
+  const queriesDir = join(root, 'queries');
+  const queryPath = join(queriesDir, 'notes-in-list.sql');
+
+  if (existsSync(manifestPath)) {
+    throw new InitError(
+      `${manifestPath} already exists — refusing to overwrite. ` +
+        'Edit it directly, or run `syncular generate`.',
+    );
+  }
+  if (existsSync(migrationPath)) {
+    throw new InitError(
+      `${migrationPath} already exists — refusing to overwrite.`,
+    );
+  }
+  if (existsSync(queryPath)) {
+    throw new InitError(`${queryPath} already exists — refusing to overwrite.`);
+  }
+
+  mkdirSync(migrationDir, { recursive: true });
+  mkdirSync(queriesDir, { recursive: true });
+  writeFileSync(manifestPath, STARTER_MANIFEST, 'utf8');
+  writeFileSync(migrationPath, STARTER_MIGRATION, 'utf8');
+  writeFileSync(queryPath, STARTER_QUERY, 'utf8');
+  return { written: [manifestPath, migrationPath, queryPath] };
+}

package/src/ir.ts

@@ -0,0 +1,197 @@
+/**
+ * Neutral schema IR (REVISE B5).
+ *
+ * The IR is a versioned, language-neutral JSON document: tables with the
+ * SPEC §2.4 column types (+ nullability + primary key), scope patterns
+ * (§3.1), the schema-version history (§1.5 gating), subscription templates,
+ * and a reserved `extensions` slot (the WP-49 apply/read-model hooks home —
+ * empty today, present in the schema so later emitters share one shape).
+ * Serialization is deterministic: fixed key order, sorted extension keys,
+ * 2-space indent, trailing newline — so the IR file diffs cleanly and the
+ * Swift/Kotlin emitters can hash it the same way the TS emitter does.
+ */
+import { createHash } from 'node:crypto';
+
+export const IR_VERSION = 1;
+
+/** The §2.4 column types (wire tags 1..8, in this order; tag 7 = blob_ref,
+ * §5.9; tag 8 = crdt, §5.10). */
+export type IrColumnType =
+  | 'string'
+  | 'integer'
+  | 'float'
+  | 'boolean'
+  | 'json'
+  | 'bytes'
+  | 'blob_ref'
+  | 'crdt';
+
+export interface IrColumn {
+  readonly name: string;
+  readonly type: IrColumnType;
+  readonly nullable: boolean;
+  /** For a `crdt` column (§5.10.1): the merger name (default `yjs-doc`).
+   * Present only for `crdt`; serialized after `nullable` when set. */
+  readonly crdtType?: string;
+  /** §5.11: this column is encrypted end-to-end. When set, `type` is `bytes`
+   * (the wire type) and `declaredType` is the pre-flip app type. Both are IR
+   * metadata (never on the wire, like `crdtType`). Present only for encrypted
+   * columns, so non-encrypted columns stay byte-identical in the IR. */
+  readonly encrypted?: boolean;
+  /** §5.11: the app-side type of an encrypted column. Present iff `encrypted`. */
+  readonly declaredType?: IrColumnType;
+}
+
+/** One §3.1 scope pattern, fully resolved (no re-parsing downstream). */
+export interface IrScope {
+  readonly pattern: string;
+  readonly variable: string;
+  readonly column: string;
+}
+
+/**
+ * One local secondary index declared by a `CREATE [UNIQUE] INDEX` migration.
+ * Applied on BOTH sides: the client materializes it in its local SQLite, and
+ * the server creates it on the relational per-app row table
+ * (DESIGN-relational-server-storage.md "user indexes"; the sync read path
+ * itself still uses the scope inverted-index). `columns` preserves declared
+ * order (a compound index is order-sensitive). Index order within a table is
+ * declaration order.
+ */
+export interface IrIndex {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly unique: boolean;
+}
+
+export interface IrTable {
+  readonly name: string;
+  readonly primaryKey: string;
+  /** Declaration order — this IS the §2.4 row-codec positional order. */
+  readonly columns: readonly IrColumn[];
+  readonly scopes: readonly IrScope[];
+  /** Local secondary indexes (§migration subset), in declaration order.
+   * Additive under irVersion 1: absent/empty for tables that declare none. */
+  readonly indexes: readonly IrIndex[];
+  /** Reserved per-table hook slot (WP-49); empty object for now. */
+  readonly extensions: Readonly<Record<string, unknown>>;
+}
+
+export type IrScopeValue =
+  | { readonly kind: 'literal'; readonly value: string }
+  | { readonly kind: 'parameter'; readonly name: string };
+
+export interface IrSubscriptionScope {
+  readonly variable: string;
+  readonly values: readonly IrScopeValue[];
+}
+
+export interface IrSubscription {
+  readonly name: string;
+  readonly table: string;
+  /** Sorted by variable for stable diffs. */
+  readonly scopes: readonly IrSubscriptionScope[];
+}
+
+export interface IrSchemaVersion {
+  readonly version: number;
+  /** Migration names this version added, in application order. */
+  readonly migrations: readonly string[];
+}
+
+export interface IrDocument {
+  readonly irVersion: number;
+  /** The current (latest) generated schema version (§1.5). */
+  readonly schemaVersion: number;
+  readonly schemaVersions: readonly IrSchemaVersion[];
+  /** Manifest order — the handler-declared bootstrap order (§4.7). */
+  readonly tables: readonly IrTable[];
+  readonly subscriptions: readonly IrSubscription[];
+  /** Reserved document-level hook slot (WP-49); empty object for now. */
+  readonly extensions: Readonly<Record<string, unknown>>;
+}
+
+/** Recursively sort object keys so extension payloads serialize stably. */
+export function canonicalizeExtensions(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalizeExtensions);
+  if (value !== null && typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>).sort(
+      ([a], [b]) => (a < b ? -1 : a > b ? 1 : 0),
+    );
+    const out: Record<string, unknown> = {};
+    for (const [key, entry] of entries) {
+      out[key] = canonicalizeExtensions(entry);
+    }
+    return out;
+  }
+  return value;
+}
+
+function canonicalScopeValue(value: IrScopeValue): Record<string, unknown> {
+  return value.kind === 'literal'
+    ? { kind: 'literal', value: value.value }
+    : { kind: 'parameter', name: value.name };
+}
+
+/** Serialize with a fixed key order — byte-deterministic for equal IRs. */
+export function serializeIr(ir: IrDocument): string {
+  const doc = {
+    irVersion: ir.irVersion,
+    schemaVersion: ir.schemaVersion,
+    schemaVersions: ir.schemaVersions.map((v) => ({
+      version: v.version,
+      migrations: v.migrations,
+    })),
+    tables: ir.tables.map((table) => ({
+      name: table.name,
+      primaryKey: table.primaryKey,
+      columns: table.columns.map((column) => ({
+        name: column.name,
+        type: column.type,
+        nullable: column.nullable,
+        // §5.10.1: crdtType is IR metadata (never on the wire); emitted only
+        // for crdt columns so non-crdt column diffs stay byte-identical.
+        ...(column.crdtType !== undefined ? { crdtType: column.crdtType } : {}),
+        // §5.11: encrypted/declaredType are IR metadata (never on the wire);
+        // emitted only for encrypted columns so non-encrypted diffs stay
+        // byte-identical.
+        ...(column.encrypted === true
+          ? { encrypted: true, declaredType: column.declaredType }
+          : {}),
+      })),
+      scopes: table.scopes.map((scope) => ({
+        pattern: scope.pattern,
+        variable: scope.variable,
+        column: scope.column,
+      })),
+      // Indexes are additive under irVersion 1: emitted only when the table
+      // declares at least one, so index-free tables (every pre-index manifest)
+      // stay byte-identical and --check fresh. Declaration order preserved.
+      ...(table.indexes.length > 0
+        ? {
+            indexes: table.indexes.map((index) => ({
+              name: index.name,
+              columns: index.columns,
+              unique: index.unique,
+            })),
+          }
+        : {}),
+      extensions: canonicalizeExtensions(table.extensions),
+    })),
+    subscriptions: ir.subscriptions.map((sub) => ({
+      name: sub.name,
+      table: sub.table,
+      scopes: sub.scopes.map((scope) => ({
+        variable: scope.variable,
+        values: scope.values.map(canonicalScopeValue),
+      })),
+    })),
+    extensions: canonicalizeExtensions(ir.extensions),
+  };
+  return `${JSON.stringify(doc, null, 2)}\n`;
+}
+
+/** Hash of the exact IR file bytes; stamped into generated modules. */
+export function irHash(irJson: string): string {
+  return `sha256:${createHash('sha256').update(irJson, 'utf8').digest('hex')}`;
+}