@syncular/typegen 0.0.1-100

package/src/introspect-sqlite.ts

@@ -0,0 +1,151 @@
+/**
+ * @syncular/typegen - SQLite schema introspection
+ *
+ * Works with both better-sqlite3 (Node.js) and bun:sqlite (Bun runtime).
+ */
+
+import type { DefinedMigrations } from '@syncular/migrations';
+import { Kysely, SqliteDialect } from 'kysely';
+import type { TableSchema, VersionedSchema } from './types';
+
+interface SqliteColumnInfo {
+  cid: number;
+  name: string;
+  type: string;
+  notnull: 0 | 1;
+  dflt_value: string | null;
+  pk: 0 | 1;
+}
+
+/** Minimal interface shared by better-sqlite3 and bun:sqlite */
+interface SqliteDb {
+  prepare(sql: string): { all(...params: unknown[]): unknown[] };
+  close(): void;
+}
+
+const isBun = typeof globalThis.Bun !== 'undefined';
+
+async function createSqliteDb(): Promise<SqliteDb> {
+  if (isBun) {
+    const { Database } = await import('bun:sqlite');
+    return new Database(':memory:');
+  }
+  const { default: Database } = await import('better-sqlite3');
+  return new Database(':memory:');
+}
+
+async function createKysely<DB>(sqliteDb: SqliteDb): Promise<Kysely<DB>> {
+  if (isBun) {
+    const { BunSqliteDialect } = await import('kysely-bun-sqlite');
+    return new Kysely<DB>({
+      dialect: new BunSqliteDialect({
+        database: sqliteDb as never,
+      }),
+    });
+  }
+
+  return new Kysely<DB>({
+    dialect: new SqliteDialect({
+      database: sqliteDb as never,
+    }),
+  });
+}
+
+function introspectTable(sqliteDb: SqliteDb, tableName: string): TableSchema {
+  const columns = sqliteDb
+    .prepare(`PRAGMA table_info("${tableName}")`)
+    .all() as SqliteColumnInfo[];
+
+  return {
+    name: tableName,
+    columns: columns.map((col) => {
+      const nullable = col.notnull === 0 && col.pk === 0;
+      const hasDefault = col.dflt_value !== null;
+      return {
+        name: col.name,
+        sqlType: col.type,
+        tsType: '', // resolved later by map-types
+        nullable,
+        isPrimaryKey: col.pk === 1,
+        hasDefault,
+      };
+    }),
+  };
+}
+
+function getAllTables(sqliteDb: SqliteDb): string[] {
+  const rows = sqliteDb
+    .prepare(
+      `SELECT name FROM sqlite_master
+       WHERE type='table'
+       AND name NOT LIKE 'sqlite_%'
+       ORDER BY name`
+    )
+    .all() as { name: string }[];
+
+  return rows.map((r) => r.name);
+}
+
+async function introspectAtVersion<DB = unknown>(
+  migrations: DefinedMigrations<DB>,
+  targetVersion: number,
+  filterTables?: string[]
+): Promise<VersionedSchema> {
+  const sqliteDb = await createSqliteDb();
+
+  try {
+    const db = await createKysely<DB>(sqliteDb);
+
+    for (const migration of migrations.migrations) {
+      if (migration.version > targetVersion) break;
+      await migration.fn(db);
+    }
+
+    let tableNames = getAllTables(sqliteDb);
+
+    if (filterTables && filterTables.length > 0) {
+      const filterSet = new Set(filterTables);
+      tableNames = tableNames.filter((t) => filterSet.has(t));
+    }
+
+    const tables = tableNames.map((name) => introspectTable(sqliteDb, name));
+
+    await db.destroy();
+
+    return {
+      version: targetVersion,
+      tables,
+    };
+  } finally {
+    sqliteDb.close();
+  }
+}
+
+export async function introspectSqliteAllVersions<DB = unknown>(
+  migrations: DefinedMigrations<DB>,
+  filterTables?: string[]
+): Promise<VersionedSchema[]> {
+  const schemas: VersionedSchema[] = [];
+
+  for (const migration of migrations.migrations) {
+    const schema = await introspectAtVersion(
+      migrations,
+      migration.version,
+      filterTables
+    );
+    schemas.push(schema);
+  }
+
+  return schemas;
+}
+
+export async function introspectSqliteCurrentSchema<DB = unknown>(
+  migrations: DefinedMigrations<DB>,
+  filterTables?: string[]
+): Promise<VersionedSchema> {
+  return introspectAtVersion(
+    migrations,
+    migrations.currentVersion,
+    filterTables
+  );
+}

package/src/introspect.ts

@@ -0,0 +1,36 @@
+/**
+ * @syncular/typegen - Schema introspection dispatcher
+ */
+
+import type { DefinedMigrations } from '@syncular/migrations';
+import {
+  introspectPostgresAllVersions,
+  introspectPostgresCurrentSchema,
+} from './introspect-postgres';
+import {
+  introspectSqliteAllVersions,
+  introspectSqliteCurrentSchema,
+} from './introspect-sqlite';
+import type { TypegenDialect, VersionedSchema } from './types';
+
+export async function introspectAllVersions<DB = unknown>(
+  migrations: DefinedMigrations<DB>,
+  dialect: TypegenDialect,
+  filterTables?: string[]
+): Promise<VersionedSchema[]> {
+  if (dialect === 'postgres') {
+    return introspectPostgresAllVersions(migrations, filterTables);
+  }
+  return introspectSqliteAllVersions(migrations, filterTables);
+}
+
+export async function introspectCurrentSchema<DB = unknown>(
+  migrations: DefinedMigrations<DB>,
+  dialect: TypegenDialect,
+  filterTables?: string[]
+): Promise<VersionedSchema> {
+  if (dialect === 'postgres') {
+    return introspectPostgresCurrentSchema(migrations, filterTables);
+  }
+  return introspectSqliteCurrentSchema(migrations, filterTables);
+}

package/src/map-types.ts

@@ -0,0 +1,193 @@
+/**
+ * @syncular/typegen - Type mapping
+ *
+ * Maps SQL types to TypeScript types for each dialect,
+ * with support for user-provided resolver overrides.
+ */
+
+import type { ColumnInfo, ResolveTypeFn, TypegenDialect } from './types';
+
+export interface ResolvedType {
+  tsType: string;
+  imports: Array<{ name: string; from: string }>;
+}
+
+function mapSqliteType(sqlType: string): string {
+  const upper = sqlType.toUpperCase();
+
+  if (upper.includes('INT')) return 'number';
+  if (
+    upper.includes('REAL') ||
+    upper.includes('FLOAT') ||
+    upper.includes('DOUBLE')
+  )
+    return 'number';
+  if (upper.includes('BLOB')) return 'Uint8Array';
+  if (upper.includes('BOOL')) return 'number';
+  // TEXT, VARCHAR, CHAR, etc.
+  return 'string';
+}
+
+function mapPostgresType(sqlType: string): string {
+  const lower = sqlType.toLowerCase().replace(/\s+/g, ' ').trim();
+
+  // Array types — strip trailing [] and map the element type
+  if (lower.endsWith('[]')) {
+    const element = mapPostgresType(lower.slice(0, -2));
+    return `${element}[]`;
+  }
+
+  // Integer types
+  if (
+    lower === 'int2' ||
+    lower === 'int4' ||
+    lower === 'integer' ||
+    lower === 'smallint' ||
+    lower === 'serial'
+  )
+    return 'number';
+
+  // 64-bit integers — not safe in JS
+  if (lower === 'int8' || lower === 'bigint' || lower === 'bigserial')
+    return 'string';
+
+  // Floating-point / numeric
+  if (
+    lower === 'float4' ||
+    lower === 'float8' ||
+    lower === 'real' ||
+    lower === 'double precision'
+  )
+    return 'number';
+
+  // Exact numeric types are string by default to match common pg driver behavior.
+  if (lower === 'numeric' || lower === 'decimal') return 'string';
+
+  // Boolean
+  if (lower === 'bool' || lower === 'boolean') return 'boolean';
+
+  // JSON
+  if (lower === 'json' || lower === 'jsonb') return 'unknown';
+
+  // Date/time
+  if (
+    lower === 'timestamp' ||
+    lower === 'timestamptz' ||
+    lower === 'timestamp with time zone' ||
+    lower === 'timestamp without time zone' ||
+    lower === 'date' ||
+    lower === 'time' ||
+    lower === 'timetz' ||
+    lower === 'time with time zone' ||
+    lower === 'time without time zone'
+  )
+    return 'string';
+
+  // Binary
+  if (lower === 'bytea') return 'Uint8Array';
+
+  // Text types
+  if (
+    lower === 'uuid' ||
+    lower === 'text' ||
+    lower === 'varchar' ||
+    lower === 'char' ||
+    lower === 'citext' ||
+    lower.startsWith('character varying') ||
+    lower.startsWith('character(') ||
+    lower.startsWith('varchar(') ||
+    lower.startsWith('char(')
+  )
+    return 'string';
+
+  // Interval
+  if (lower === 'interval') return 'string';
+
+  // Network types
+  if (lower === 'inet' || lower === 'cidr' || lower === 'macaddr')
+    return 'string';
+
+  // Geometric types
+  if (
+    lower === 'point' ||
+    lower === 'line' ||
+    lower === 'box' ||
+    lower === 'path' ||
+    lower === 'polygon' ||
+    lower === 'circle' ||
+    lower === 'lseg'
+  )
+    return 'string';
+
+  // Range types
+  if (
+    lower === 'int4range' ||
+    lower === 'int8range' ||
+    lower === 'tsrange' ||
+    lower === 'tstzrange' ||
+    lower === 'daterange' ||
+    lower === 'numrange'
+  )
+    return 'string';
+
+  // Full-text search
+  if (lower === 'tsvector' || lower === 'tsquery') return 'string';
+
+  // Other
+  if (lower === 'xml') return 'string';
+  if (lower === 'money') return 'string';
+  if (
+    lower === 'bit' ||
+    lower === 'varbit' ||
+    lower.startsWith('bit(') ||
+    lower.startsWith('bit varying')
+  )
+    return 'string';
+
+  return 'string';
+}
+
+function defaultMapper(dialect: TypegenDialect): (sqlType: string) => string {
+  return dialect === 'postgres' ? mapPostgresType : mapSqliteType;
+}
+
+/**
+ * Resolve the TypeScript type for a column, applying the user resolver first
+ * and falling back to the default dialect mapping.
+ */
+export function resolveColumnType(
+  col: ColumnInfo,
+  userResolver?: ResolveTypeFn
+): ResolvedType {
+  const imports: Array<{ name: string; from: string }> = [];
+
+  // Try user resolver first
+  if (userResolver) {
+    const override = userResolver(col);
+    if (override !== undefined) {
+      if (typeof override === 'string') {
+        const baseType = override;
+        return {
+          tsType: col.nullable ? `${baseType} | null` : baseType,
+          imports,
+        };
+      }
+      if (override.import) {
+        imports.push(override.import);
+      }
+      const baseType = override.type;
+      return {
+        tsType: col.nullable ? `${baseType} | null` : baseType,
+        imports,
+      };
+    }
+  }
+
+  // Default mapping
+  const mapper = defaultMapper(col.dialect);
+  const baseType = mapper(col.sqlType);
+  return {
+    tsType: col.nullable ? `${baseType} | null` : baseType,
+    imports,
+  };
+}

package/src/render.ts

@@ -0,0 +1,206 @@
+/**
+ * @syncular/typegen - TypeScript code generation
+ */
+
+import type { ColumnSchema, TableSchema, VersionedSchema } from './types';
+
+/**
+ * Convert a snake_case table/column name to PascalCase.
+ */
+function toPascalCase(str: string): string {
+  return str
+    .split(/[_-]/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join('');
+}
+
+/**
+ * Render a single column definition.
+ */
+function renderColumn(column: ColumnSchema): string {
+  const tsType = column.hasDefault
+    ? `Generated<${column.tsType}>`
+    : column.tsType;
+  return `  ${column.name}: ${tsType};`;
+}
+
+/**
+ * Render a table interface.
+ */
+function renderTableInterface(
+  table: TableSchema,
+  interfaceName: string
+): string {
+  const columns = table.columns.map(renderColumn).join('\n');
+  return `export interface ${interfaceName} {\n${columns}\n}`;
+}
+
+/**
+ * Render a database interface containing all tables.
+ */
+function renderDbInterface(
+  schema: VersionedSchema,
+  interfaceName: string,
+  extendsType?: string
+): string {
+  const extendsClause = extendsType ? ` extends ${extendsType}` : '';
+  const tableEntries = schema.tables
+    .map((t) => `  ${t.name}: ${toPascalCase(t.name)}Table;`)
+    .join('\n');
+
+  return `export interface ${interfaceName}${extendsClause} {\n${tableEntries}\n}`;
+}
+
+/**
+ * Options for rendering types.
+ */
+export interface RenderOptions {
+  /** Schemas at each version (for version history) */
+  schemas: VersionedSchema[];
+  /** Whether to extend SyncClientDb */
+  extendsSyncClientDb?: boolean;
+  /** Generate versioned interfaces */
+  includeVersionHistory?: boolean;
+  /** Custom imports collected from resolver results */
+  customImports?: Array<{ name: string; from: string }>;
+}
+
+/**
+ * Render complete TypeScript type definitions.
+ */
+export function renderTypes(options: RenderOptions): string {
+  const { schemas, extendsSyncClientDb, includeVersionHistory, customImports } =
+    options;
+  const lines: string[] = [];
+
+  // Header
+  lines.push('/**');
+  lines.push(' * Auto-generated database types from migrations.');
+  lines.push(' * DO NOT EDIT - regenerate with @syncular/typegen');
+  lines.push(' */');
+  lines.push('');
+
+  // Import SyncClientDb if extending
+  if (extendsSyncClientDb) {
+    lines.push("import type { SyncClientDb } from '@syncular/client';");
+    lines.push('');
+  }
+
+  const usesGenerated = schemas.some((schema) =>
+    schema.tables.some((table) =>
+      table.columns.some((column) => column.hasDefault)
+    )
+  );
+  if (usesGenerated) {
+    lines.push("import type { Generated } from 'kysely';");
+    lines.push('');
+  }
+
+  // Render custom imports from resolver
+  if (customImports && customImports.length > 0) {
+    // Group imports by source module
+    const byModule = new Map<string, Set<string>>();
+    for (const imp of customImports) {
+      let names = byModule.get(imp.from);
+      if (!names) {
+        names = new Set();
+        byModule.set(imp.from, names);
+      }
+      names.add(imp.name);
+    }
+    for (const [from, names] of byModule) {
+      const sorted = [...names].sort();
+      lines.push(`import type { ${sorted.join(', ')} } from '${from}';`);
+    }
+    lines.push('');
+  }
+
+  // Get the latest schema
+  const latestSchema = schemas[schemas.length - 1];
+  if (!latestSchema) {
+    lines.push('// No migrations defined');
+    return lines.join('\n');
+  }
+
+  // Generate table interfaces for latest version
+  for (const table of latestSchema.tables) {
+    lines.push(renderTableInterface(table, `${toPascalCase(table.name)}Table`));
+    lines.push('');
+  }
+
+  // Generate versioned DB interfaces if requested
+  if (includeVersionHistory && schemas.length > 0) {
+    for (const schema of schemas) {
+      // For each version, generate table interfaces with version suffix
+      // if they differ from the latest
+      const versionSuffix = `V${schema.version}`;
+
+      // Generate versioned table interfaces
+      for (const table of schema.tables) {
+        const latestTable = latestSchema.tables.find(
+          (t) => t.name === table.name
+        );
+
+        // Only generate versioned interface if different from latest
+        if (latestTable && !tablesEqual(table, latestTable)) {
+          lines.push(
+            renderTableInterface(
+              table,
+              `${toPascalCase(table.name)}Table${versionSuffix}`
+            )
+          );
+          lines.push('');
+        }
+      }
+
+      // Generate versioned DB interface
+      const tableEntries = schema.tables
+        .map((t) => {
+          const latestTable = latestSchema.tables.find(
+            (lt) => lt.name === t.name
+          );
+          const useVersioned = latestTable && !tablesEqual(t, latestTable);
+          const typeName = useVersioned
+            ? `${toPascalCase(t.name)}Table${versionSuffix}`
+            : `${toPascalCase(t.name)}Table`;
+          return `  ${t.name}: ${typeName};`;
+        })
+        .join('\n');
+
+      lines.push(`export interface ClientDb${versionSuffix} {`);
+      lines.push(tableEntries);
+      lines.push('}');
+      lines.push('');
+    }
+  }
+
+  // Generate main DB interface (latest version)
+  const extendsType = extendsSyncClientDb ? 'SyncClientDb' : undefined;
+  lines.push(renderDbInterface(latestSchema, 'ClientDb', extendsType));
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Check if two table schemas are equal.
+ */
+function tablesEqual(a: TableSchema, b: TableSchema): boolean {
+  if (a.columns.length !== b.columns.length) return false;
+
+  for (let i = 0; i < a.columns.length; i++) {
+    const colA = a.columns[i]!;
+    const colB = b.columns[i]!;
+
+    if (
+      colA.name !== colB.name ||
+      colA.tsType !== colB.tsType ||
+      colA.nullable !== colB.nullable ||
+      colA.hasDefault !== colB.hasDefault
+    ) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/types.ts

@@ -0,0 +1,94 @@
+/**
+ * @syncular/typegen - Type definitions
+ */
+
+import type { DefinedMigrations } from '@syncular/migrations';
+
+export type TypegenDialect = 'sqlite' | 'postgres';
+
+/**
+ * Column information passed to the resolver function.
+ */
+export interface ColumnInfo {
+  table: string;
+  column: string;
+  sqlType: string;
+  nullable: boolean;
+  isPrimaryKey: boolean;
+  hasDefault: boolean;
+  dialect: TypegenDialect;
+}
+
+/**
+ * Return type from a resolver function.
+ */
+export type TypeOverride =
+  | string
+  | { type: string; import?: { name: string; from: string } };
+
+/**
+ * User-provided function to override default type mapping.
+ */
+export type ResolveTypeFn = (col: ColumnInfo) => TypeOverride | undefined;
+
+/**
+ * Parsed table schema.
+ */
+export interface TableSchema {
+  name: string;
+  columns: ColumnSchema[];
+}
+
+/**
+ * Parsed column schema.
+ */
+export interface ColumnSchema {
+  name: string;
+  sqlType: string;
+  tsType: string;
+  nullable: boolean;
+  isPrimaryKey: boolean;
+  hasDefault: boolean;
+}
+
+/**
+ * Schema snapshot at a specific version.
+ */
+export interface VersionedSchema {
+  version: number;
+  tables: TableSchema[];
+}
+
+/**
+ * Options for generateTypes().
+ */
+export interface GenerateTypesOptions<DB = unknown> {
+  /** Defined migrations from defineMigrations() */
+  migrations: DefinedMigrations<DB>;
+  /** Output file path for generated types */
+  output: string;
+  /** Database dialect to use for introspection (default: 'sqlite') */
+  dialect?: TypegenDialect;
+  /** Whether to extend SyncClientDb interface (adds sync infrastructure types) */
+  extendsSyncClientDb?: boolean;
+  /** Generate versioned interfaces (ClientDbV1, ClientDbV2, etc.) */
+  includeVersionHistory?: boolean;
+  /** Only generate types for these tables (default: all tables) */
+  tables?: string[];
+  /** Custom type resolver for overriding default type mapping */
+  resolveType?: ResolveTypeFn;
+}
+
+/**
+ * Result of type generation.
+ */
+export interface GenerateTypesResult {
+  /** Path to the generated file */
+  outputPath: string;
+  /** Current schema version */
+  currentVersion: number;
+  /** Number of tables generated */
+  tableCount: number;
+  /** Generated TypeScript code */
+  code: string;
+}