@syncular/typegen 0.1.2 → 0.2.0

package/src/emit.ts

@@ -0,0 +1,239 @@
+/**
+ * TS emitter: neutral IR → one standalone generated module exporting
+ *
+ * - `schema` — a ServerSchema-compatible object (structurally typed; the
+ *   generated file imports nothing),
+ * - a `<Table>Row` interface per table,
+ * - `<Table>Insert` / `<Table>Update` mutation-input shapes honoring
+ *   nullability,
+ * - a `<name>Subscription` helper constant per manifest subscription with
+ *   a typed requested-scopes builder.
+ *
+ * The header carries the IR hash so `--check` verifies freshness
+ * byte-exactly.
+ */
+import type { IrColumnType, IrDocument, IrSubscription, IrTable } from './ir';
+
+const TS_TYPE: Readonly<Record<IrColumnType, string>> = {
+  string: 'string',
+  integer: 'number',
+  float: 'number',
+  boolean: 'boolean',
+  json: 'string',
+  bytes: 'Uint8Array',
+  // §5.9: a blob_ref value is the raw canonical BlobRef JSON string
+  // (like `json`); the client's blob API parses it into a BlobRef object.
+  blob_ref: 'string',
+  // §5.10: a crdt value is opaque bytes (like `bytes`); the Y.Doc accessor
+  // is an app-level helper in @syncular/crdt-yjs, not generated code.
+  crdt: 'Uint8Array',
+};
+
+/**
+ * §5.11: the app-side TS type of a column. An encrypted column's wire type is
+ * `bytes`, but the app sees its declared type (the local mirror is plaintext).
+ */
+function appTsType(column: IrTable['columns'][number]): string {
+  const type =
+    column.encrypted === true && column.declaredType !== undefined
+      ? column.declaredType
+      : column.type;
+  return TS_TYPE[type];
+}
+
+function pascalCase(name: string): string {
+  return name
+    .split(/[_-]+/)
+    .filter((part) => part.length > 0)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+function quote(value: string): string {
+  return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+
+const IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+function propertyKey(name: string): string {
+  return IDENTIFIER_RE.test(name) ? name : quote(name);
+}
+
+function emitSchema(ir: IrDocument): string {
+  const lines: string[] = [];
+  lines.push('/** ServerSchema-compatible schema object (SPEC §2.4, §3.1). */');
+  lines.push('export const schema = {');
+  lines.push(`  version: ${ir.schemaVersion},`);
+  lines.push('  tables: [');
+  for (const table of ir.tables) {
+    lines.push('    {');
+    lines.push(`      name: ${quote(table.name)},`);
+    lines.push('      columns: [');
+    for (const column of table.columns) {
+      // §5.10.1: emit crdtType on crdt columns so a generated server schema
+      // can select the merger; omitted (and thus unchanged) for others.
+      const crdtType =
+        column.crdtType !== undefined
+          ? `, crdtType: ${quote(column.crdtType)}`
+          : '';
+      // §5.11: emit encrypted/declaredType on encrypted columns so the client
+      // codec encrypts/decrypts them; omitted for others.
+      const encrypted =
+        column.encrypted === true
+          ? `, encrypted: true, declaredType: ${quote(column.declaredType ?? column.type)}`
+          : '';
+      lines.push(
+        `        { name: ${quote(column.name)}, type: ${quote(column.type)}, nullable: ${column.nullable}${crdtType}${encrypted} },`,
+      );
+    }
+    lines.push('      ],');
+    lines.push(`      primaryKey: ${quote(table.primaryKey)},`);
+    lines.push('      scopes: [');
+    for (const scope of table.scopes) {
+      lines.push(
+        `        { pattern: ${quote(scope.pattern)}, column: ${quote(scope.column)} },`,
+      );
+    }
+    lines.push('      ],');
+    // Local secondary indexes — emitted only when the table declares any, so
+    // index-free tables keep their exact pre-index generated bytes.
+    if (table.indexes.length > 0) {
+      lines.push('      indexes: [');
+      for (const index of table.indexes) {
+        const cols = index.columns.map((c) => quote(c)).join(', ');
+        lines.push(
+          `        { name: ${quote(index.name)}, columns: [${cols}], unique: ${index.unique} },`,
+        );
+      }
+      lines.push('      ],');
+    }
+    lines.push('    },');
+  }
+  lines.push('  ],');
+  lines.push('} as const;');
+  return lines.join('\n');
+}
+
+function emitRowInterfaces(table: IrTable): string {
+  const type = pascalCase(table.name);
+  const lines: string[] = [];
+  lines.push(`/** One ${table.name} row (§2.4 column order). */`);
+  lines.push(`export interface ${type}Row {`);
+  for (const column of table.columns) {
+    const ts = appTsType(column);
+    lines.push(
+      `  ${propertyKey(column.name)}: ${ts}${column.nullable ? ' | null' : ''};`,
+    );
+  }
+  lines.push('}');
+  lines.push('');
+  lines.push(`/** Insert shape: nullable columns may be omitted. */`);
+  lines.push(`export interface ${type}Insert {`);
+  for (const column of table.columns) {
+    const ts = appTsType(column);
+    lines.push(
+      column.nullable
+        ? `  ${propertyKey(column.name)}?: ${ts} | null;`
+        : `  ${propertyKey(column.name)}: ${ts};`,
+    );
+  }
+  lines.push('}');
+  lines.push('');
+  lines.push(
+    `/** Update shape: primary key required, all other columns optional. */`,
+  );
+  lines.push(`export interface ${type}Update {`);
+  for (const column of table.columns) {
+    const ts = appTsType(column);
+    if (column.name === table.primaryKey) {
+      lines.push(`  ${propertyKey(column.name)}: ${ts};`);
+    } else {
+      lines.push(
+        `  ${propertyKey(column.name)}?: ${ts}${column.nullable ? ' | null' : ''};`,
+      );
+    }
+  }
+  lines.push('}');
+  return lines.join('\n');
+}
+
+/**
+ * A Kysely-compatible `Database` interface: table name → Row type. This is
+ * the generic `@syncular/kysely`'s `SyncularDialect` is parameterized by
+ * (`new Kysely<Database>({ dialect })`). Additive — the Row interfaces it
+ * references are already emitted above. Property keys use the raw table name
+ * (quoted when not an identifier) so `db.selectFrom('table-name')` types.
+ */
+function emitDatabaseInterface(ir: IrDocument): string {
+  const lines: string[] = [];
+  lines.push('/** Kysely `Database` interface (table → Row); the generic for');
+  lines.push(" *  @syncular/kysely's SyncularDialect. */");
+  lines.push('export interface Database {');
+  for (const table of ir.tables) {
+    lines.push(`  ${propertyKey(table.name)}: ${pascalCase(table.name)}Row;`);
+  }
+  lines.push('}');
+  return lines.join('\n');
+}
+
+function emitSubscription(sub: IrSubscription): string {
+  const params: string[] = [];
+  for (const scope of sub.scopes) {
+    for (const value of scope.values) {
+      if (value.kind === 'parameter' && !params.includes(value.name)) {
+        params.push(value.name);
+      }
+    }
+  }
+  const lines: string[] = [];
+  const paramsType = `${pascalCase(sub.name)}Params`;
+  if (params.length > 0) {
+    lines.push(`export interface ${paramsType} {`);
+    for (const param of params) {
+      lines.push(`  ${propertyKey(param)}: string;`);
+    }
+    lines.push('}');
+    lines.push('');
+  }
+  lines.push(
+    `/** Requested-scope template for the ${quote(sub.name)} subscription. */`,
+  );
+  lines.push(`export const ${sub.name}Subscription = {`);
+  lines.push(`  name: ${quote(sub.name)},`);
+  lines.push(`  table: ${quote(sub.table)},`);
+  const args = params.length > 0 ? `params: ${paramsType}` : '';
+  lines.push(`  scopes: (${args}): Record<string, string[]> => ({`);
+  for (const scope of sub.scopes) {
+    const values = scope.values
+      .map((value) =>
+        value.kind === 'literal'
+          ? quote(value.value)
+          : `params.${propertyKey(value.name)}`,
+      )
+      .join(', ');
+    lines.push(`    ${propertyKey(scope.variable)}: [${values}],`);
+  }
+  lines.push('  }),');
+  lines.push('} as const;');
+  return lines.join('\n');
+}
+
+export function emitModule(ir: IrDocument, hash: string): string {
+  const parts: string[] = [];
+  parts.push(
+    [
+      '// Generated by @syncular/typegen — DO NOT EDIT.',
+      `// irVersion: ${ir.irVersion}`,
+      `// irHash: ${hash}`,
+    ].join('\n'),
+  );
+  parts.push(emitSchema(ir));
+  for (const table of ir.tables) {
+    parts.push(emitRowInterfaces(table));
+  }
+  parts.push(emitDatabaseInterface(ir));
+  for (const sub of ir.subscriptions) {
+    parts.push(emitSubscription(sub));
+  }
+  return `${parts.join('\n\n')}\n`;
+}

package/src/errors.ts

@@ -0,0 +1,11 @@
+/** Fail-loud codegen error: every message names the offending construct. */
+export class TypegenError extends Error {
+  /** Input the error came from (a migration file, the manifest, …). */
+  readonly source: string;
+
+  constructor(source: string, message: string) {
+    super(`${source}: ${message}`);
+    this.name = 'TypegenError';
+    this.source = source;
+  }
+}