@syncular/typegen 0.0.6-95 → 0.1.0

package/src/checksums.ts

@@ -0,0 +1,257 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { PGlite } from '@electric-sql/pglite';
+import type {
+  DefinedMigrations,
+  MigrationChecksums,
+  ParsedMigration,
+} from '@syncular/migrations';
+import { Kysely, SqliteDialect } from 'kysely';
+import { PGliteDialect } from 'kysely-pglite-dialect';
+import type {
+  GenerateMigrationChecksumsOptions,
+  GenerateMigrationChecksumsResult,
+  TypegenDialect,
+} from './types';
+
+interface TraceableQuery {
+  sql: string;
+  parameters: readonly unknown[];
+}
+
+interface SqliteDb {
+  close(): void;
+}
+
+type BunAwareGlobals = typeof globalThis & {
+  Bun?: object;
+};
+
+const runtimeGlobals = globalThis as BunAwareGlobals;
+const isBun = typeof runtimeGlobals.Bun !== 'undefined';
+
+function hashString(value: string): string {
+  let hash = 0;
+
+  for (let index = 0; index < value.length; index += 1) {
+    hash = (hash * 31 + value.charCodeAt(index)) >>> 0;
+  }
+
+  return hash.toString(16).padStart(8, '0');
+}
+
+function normalizeParameterValue(value: unknown): unknown {
+  if (typeof value === 'bigint') {
+    return { type: 'bigint', value: value.toString() };
+  }
+  if (value instanceof Date) {
+    return { type: 'date', value: value.toISOString() };
+  }
+  if (value instanceof Uint8Array) {
+    return { type: 'bytes', value: Array.from(value) };
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => normalizeParameterValue(entry));
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, normalizeParameterValue(entry)])
+    );
+  }
+  return value;
+}
+
+function serializeQuery(query: TraceableQuery): string {
+  return JSON.stringify({
+    sql: query.sql,
+    parameters: query.parameters.map((value) => normalizeParameterValue(value)),
+  });
+}
+
+function hashTrace(entries: string[]): string {
+  return hashString(entries.join('\n'));
+}
+
+function quoteTsString(value: string): string {
+  return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`;
+}
+
+async function createSqliteTraceDb<DB>(traceEntries: string[]): Promise<{
+  db: Kysely<DB>;
+  sqliteDb: SqliteDb;
+}> {
+  if (isBun) {
+    const bunSqliteSpecifier = 'bun:sqlite';
+    const sqliteModule = await import(bunSqliteSpecifier);
+    const dialectModule = await import('kysely-bun-sqlite');
+    const sqliteDb = new sqliteModule.Database(':memory:');
+    const db = new Kysely<DB>({
+      dialect: new dialectModule.BunSqliteDialect({
+        database: sqliteDb as never,
+      }),
+      log(event) {
+        if (event.level === 'query') {
+          traceEntries.push(serializeQuery(event.query));
+        }
+      },
+    });
+
+    return { db, sqliteDb };
+  }
+
+  const { default: Database } = await import('better-sqlite3');
+  const sqliteDb = new Database(':memory:');
+  const db = new Kysely<DB>({
+    dialect: new SqliteDialect({
+      database: sqliteDb as never,
+    }),
+    log(event) {
+      if (event.level === 'query') {
+        traceEntries.push(serializeQuery(event.query));
+      }
+    },
+  });
+
+  return { db, sqliteDb };
+}
+
+async function createPostgresTraceDb<DB>(traceEntries: string[]): Promise<{
+  db: Kysely<DB>;
+  dispose: () => Promise<void>;
+}> {
+  const pglite = await PGlite.create();
+  const db = new Kysely<DB>({
+    dialect: new PGliteDialect(pglite),
+    log(event) {
+      if (event.level === 'query') {
+        traceEntries.push(serializeQuery(event.query));
+      }
+    },
+  });
+
+  return {
+    db,
+    dispose: async () => {
+      if (!pglite.closed) {
+        await pglite.close();
+      }
+    },
+  };
+}
+
+async function createTraceDb<DB>(
+  dialect: TypegenDialect,
+  traceEntries: string[]
+): Promise<{
+  db: Kysely<DB>;
+  dispose: () => Promise<void>;
+}> {
+  if (dialect === 'postgres') {
+    return createPostgresTraceDb<DB>(traceEntries);
+  }
+
+  const { db, sqliteDb } = await createSqliteTraceDb<DB>(traceEntries);
+  return {
+    db,
+    dispose: async () => {
+      sqliteDb.close();
+    },
+  };
+}
+
+async function computeMigrationChecksum<DB>(
+  migrations: DefinedMigrations<DB>,
+  targetMigration: ParsedMigration<DB>,
+  dialect: TypegenDialect
+): Promise<string> {
+  const traceEntries: string[] = [];
+  const { db, dispose } = await createTraceDb<DB>(dialect, traceEntries);
+
+  try {
+    for (const migration of migrations.migrations) {
+      if (migration.version > targetMigration.version) {
+        break;
+      }
+
+      if (migration.version === targetMigration.version) {
+        traceEntries.length = 0;
+      }
+
+      await migration.up(db);
+
+      if (migration.version === targetMigration.version) {
+        break;
+      }
+    }
+
+    return hashTrace(traceEntries);
+  } finally {
+    await db.destroy();
+    await dispose();
+  }
+}
+
+export async function createMigrationChecksums<DB>(
+  migrations: DefinedMigrations<DB>,
+  dialect: TypegenDialect = 'sqlite'
+): Promise<MigrationChecksums> {
+  const checksums: Record<string, string> = {};
+
+  for (const migration of migrations.migrations) {
+    if (migration.checksum === 'disabled') {
+      continue;
+    }
+
+    checksums[String(migration.version)] = await computeMigrationChecksum(
+      migrations,
+      migration,
+      dialect
+    );
+  }
+
+  return checksums;
+}
+
+export function renderMigrationChecksums(
+  checksums: MigrationChecksums
+): string {
+  const entries = Object.entries(checksums)
+    .sort(([left], [right]) => Number(left) - Number(right))
+    .map(
+      ([version, checksum]) =>
+        `  ${quoteTsString(version)}: ${quoteTsString(checksum)},`
+    )
+    .join('\n');
+
+  return [
+    '/**',
+    ' * Generated by @syncular/typegen.',
+    ' * Do not edit by hand.',
+    ' */',
+    '',
+    'export const migrationChecksums = {',
+    entries,
+    '} as const;',
+    '',
+  ].join('\n');
+}
+
+export async function generateMigrationChecksums<DB>(
+  options: GenerateMigrationChecksumsOptions<DB>
+): Promise<GenerateMigrationChecksumsResult> {
+  const { migrations, output, dialect = 'sqlite' } = options;
+  const checksums = await createMigrationChecksums(migrations, dialect);
+  const code = renderMigrationChecksums(checksums);
+
+  await mkdir(dirname(output), { recursive: true });
+  await writeFile(output, code, 'utf-8');
+
+  return {
+    outputPath: output,
+    currentVersion: migrations.currentVersion,
+    checksumCount: Object.keys(checksums).length,
+    code,
+  };
+}

package/src/cli.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env bun
+
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  loadSyncularClientContract,
+  toSyncularCodegenJson,
+  writeSyncularCodegenJsonFromModule,
+} from './app-contract';
+
+interface CodegenConfigCommand {
+  app: string;
+  out: string;
+  exportName?: string;
+  check: boolean;
+}
+
+async function main(argv: string[]): Promise<void> {
+  const command = argv[0];
+  if (command !== 'codegen-config') {
+    printUsageAndExit(command ? `Unknown command ${command}` : undefined);
+  }
+  const options = parseCodegenConfigArgs(argv.slice(1));
+  if (options.check) {
+    const contract = await loadSyncularClientContract({
+      modulePath: options.app,
+      exportName: options.exportName,
+    });
+    const expected = toSyncularCodegenJson(contract);
+    const actual = await readFile(options.out, 'utf8').catch((error) => {
+      throw new Error(
+        `Cannot read ${options.out}; run without --check to generate it first: ${error.message}`
+      );
+    });
+    if (actual !== expected) {
+      throw new Error(
+        `${options.out} does not match ${options.app}; run syncular generate --app ${options.app}`
+      );
+    }
+    return;
+  }
+  await writeSyncularCodegenJsonFromModule({
+    modulePath: options.app,
+    exportName: options.exportName,
+    outputPath: options.out,
+  });
+}
+
+function parseCodegenConfigArgs(args: string[]): CodegenConfigCommand {
+  let app: string | undefined;
+  let out: string | undefined;
+  let exportName: string | undefined;
+  let check = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--app') {
+      app = requireValue(args, (index += 1), '--app');
+    } else if (arg === '--out') {
+      out = requireValue(args, (index += 1), '--out');
+    } else if (arg === '--export') {
+      exportName = requireValue(args, (index += 1), '--export');
+    } else if (arg === '--check') {
+      check = true;
+    } else if (arg === '--help' || arg === '-h') {
+      printUsageAndExit();
+    } else {
+      printUsageAndExit(`Unknown option ${arg}`);
+    }
+  }
+  if (!app) printUsageAndExit('Missing --app');
+  return {
+    app,
+    out: out ?? defaultCodegenConfigPath(app),
+    exportName,
+    check,
+  };
+}
+
+function defaultCodegenConfigPath(app: string): string {
+  const appPath = app.startsWith('file:') ? fileURLToPath(app) : app;
+  return join(dirname(appPath), 'generated', 'syncular.codegen.json');
+}
+
+function requireValue(args: string[], index: number, option: string): string {
+  const value = args[index];
+  if (!value || value.startsWith('--')) {
+    printUsageAndExit(`${option} requires a value`);
+  }
+  return value;
+}
+
+function printUsageAndExit(message?: string): never {
+  if (message) console.error(message);
+  console.error(
+    [
+      'Usage:',
+      '  syncular-typegen codegen-config --app ./syncular.app.ts [--out ./generated/syncular.codegen.json] [--export app] [--check]',
+    ].join('\n')
+  );
+  process.exit(message ? 1 : 0);
+}
+
+await main(process.argv.slice(2));

package/src/generate.ts

@@ -68,7 +68,6 @@ function applyTypeMappings(
  * await generateTypes({
  *   migrations,
  *   output: './src/db.generated.ts',
- *   extendsSyncClientDb: true,
  * });
  * ```
  */
@@ -78,8 +77,6 @@ export async function generateTypes<DB>(
   const {
     migrations,
     output,
-    extendsSyncClientDb,
-    syncularImportType,
     includeVersionHistory,
     tables,
     dialect = 'sqlite',
@@ -105,8 +102,6 @@ export async function generateTypes<DB>(
   // Render TypeScript code
   const code = renderTypes({
     schemas,
-    extendsSyncClientDb,
-    syncularImportType,
     includeVersionHistory,
     customImports,
   });

package/src/index.ts

@@ -7,6 +7,8 @@
  * 3. Generating TypeScript interfaces
  */
 
+export * from './app-contract';
+export * from './checksums';
 export * from './generate';
 export * from './introspect';
 export * from './map-types';

package/src/introspect-postgres.ts

@@ -90,19 +90,16 @@ async function introspectAtVersion<DB = unknown>(
   filterTables?: string[]
 ): Promise<VersionedSchema> {
   const pglite = await PGlite.create();
+  const db = new Kysely<DB>({
+    dialect: new PGliteDialect(pglite),
+  });
 
   try {
-    const db = new Kysely<DB>({
-      dialect: new PGliteDialect(pglite),
-    });
-
     for (const migration of migrations.migrations) {
       if (migration.version > targetVersion) break;
       await migration.up(db);
     }
 
-    await db.destroy();
-
     let tables = await introspectPg(pglite);
 
     if (filterTables && filterTables.length > 0) {
@@ -115,7 +112,10 @@ async function introspectAtVersion<DB = unknown>(
       tables,
     };
   } finally {
-    await pglite.close();
+    await db.destroy();
+    if (!pglite.closed) {
+      await pglite.close();
+    }
   }
 }
 

package/src/introspect-sqlite.ts

@@ -23,7 +23,12 @@ interface SqliteDb {
   close(): void;
 }
 
-const isBun = typeof globalThis.Bun !== 'undefined';
+type BunAwareGlobals = typeof globalThis & {
+  Bun?: object;
+};
+
+const runtimeGlobals = globalThis as BunAwareGlobals;
+const isBun = typeof runtimeGlobals.Bun !== 'undefined';
 
 async function createSqliteDb(): Promise<SqliteDb> {
   if (isBun) {

package/src/render.ts

@@ -2,12 +2,7 @@
  * @syncular/typegen - TypeScript code generation
  */
 
-import type {
-  ColumnSchema,
-  SyncularImportType,
-  TableSchema,
-  VersionedSchema,
-} from './types';
+import type { ColumnSchema, TableSchema, VersionedSchema } from './types';
 
 /**
  * Convert a snake_case table/column name to PascalCase.
@@ -62,43 +57,17 @@ function renderDbInterface(
 export interface RenderOptions {
   /** Schemas at each version (for version history) */
   schemas: VersionedSchema[];
-  /** Whether to extend SyncClientDb */
-  extendsSyncClientDb?: boolean;
-  /** Controls package import style for SyncClientDb (default: 'scoped') */
-  syncularImportType?: SyncularImportType;
   /** Generate versioned interfaces */
   includeVersionHistory?: boolean;
   /** Custom imports collected from resolver results */
   customImports?: Array<{ name: string; from: string }>;
 }
 
-function resolveSyncClientImportPath(importType: SyncularImportType): string {
-  if (importType === 'umbrella') {
-    return 'syncular/client';
-  }
-  if (importType === 'scoped') {
-    return '@syncular/client';
-  }
-  const clientImportPath = importType.client.trim();
-  if (clientImportPath.length === 0) {
-    throw new Error(
-      'syncularImportType.client must be a non-empty package import path'
-    );
-  }
-  return clientImportPath;
-}
-
 /**
  * Render complete TypeScript type definitions.
  */
 export function renderTypes(options: RenderOptions): string {
-  const {
-    schemas,
-    extendsSyncClientDb,
-    syncularImportType = 'scoped',
-    includeVersionHistory,
-    customImports,
-  } = options;
+  const { schemas, includeVersionHistory, customImports } = options;
   const lines: string[] = [];
 
   // Header
@@ -108,14 +77,6 @@ export function renderTypes(options: RenderOptions): string {
   lines.push(' */');
   lines.push('');
 
-  // Import SyncClientDb if extending
-  if (extendsSyncClientDb) {
-    lines.push(
-      `import type { SyncClientDb } from '${resolveSyncClientImportPath(syncularImportType)}';`
-    );
-    lines.push('');
-  }
-
   const usesGenerated = schemas.some((schema) =>
     schema.tables.some((table) =>
       table.columns.some((column) => column.hasDefault)
@@ -205,8 +166,7 @@ export function renderTypes(options: RenderOptions): string {
   }
 
   // Generate main DB interface (latest version)
-  const extendsType = extendsSyncClientDb ? 'SyncClientDb' : undefined;
-  lines.push(renderDbInterface(latestSchema, 'ClientDb', extendsType));
+  lines.push(renderDbInterface(latestSchema, 'ClientDb'));
   lines.push('');
 
   return lines.join('\n');

package/src/types.ts

@@ -6,14 +6,6 @@ import type { DefinedMigrations } from '@syncular/migrations';
 
 export type TypegenDialect = 'sqlite' | 'postgres';
 
-export type SyncularImportType =
-  | 'scoped'
-  | 'umbrella'
-  | {
-      client: string;
-      [packageName: string]: string;
-    };
-
 /**
  * Column information for a schema column.
  */
@@ -99,15 +91,6 @@ export interface GenerateTypesOptions<DB = unknown> {
   output: string;
   /** Database dialect to use for introspection (default: 'sqlite') */
   dialect?: TypegenDialect;
-  /** Whether to extend SyncClientDb interface (adds sync infrastructure types) */
-  extendsSyncClientDb?: boolean;
-  /**
-   * Controls how syncular package imports are rendered in generated output.
-   * - 'scoped' (default): '@syncular/client'
-   * - 'umbrella': 'syncular/client'
-   * - object: explicit package mapping (must include `client`)
-   */
-  syncularImportType?: SyncularImportType;
   /** Generate versioned interfaces (ClientDbV1, ClientDbV2, etc.) */
   includeVersionHistory?: boolean;
   /** Only generate types for these tables (default: all tables) */
@@ -132,3 +115,23 @@ export interface GenerateTypesResult {
   /** Generated TypeScript code */
   code: string;
 }
+
+export interface GenerateMigrationChecksumsOptions<DB = unknown> {
+  /** Defined migrations from defineMigrations() */
+  migrations: DefinedMigrations<DB>;
+  /** Output file path for generated checksums */
+  output: string;
+  /** Database dialect to use for replay (default: 'sqlite') */
+  dialect?: TypegenDialect;
+}
+
+export interface GenerateMigrationChecksumsResult {
+  /** Path to the generated file */
+  outputPath: string;
+  /** Current schema version */
+  currentVersion: number;
+  /** Number of checksums generated */
+  checksumCount: number;
+  /** Generated TypeScript code */
+  code: string;
+}