@syncular/typegen 0.0.6-96 → 0.1.0

package/dist/types.d.ts

@@ -3,10 +3,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.
  */
@@ -82,15 +78,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) */
@@ -114,4 +101,22 @@ 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;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/typegen",
-  "version": "0.0.6-96",
+  "version": "0.1.0",
   "description": "TypeScript type generator for Syncular schemas",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -27,6 +27,9 @@
     "access": "public"
   },
   "type": "module",
+  "bin": {
+    "syncular-typegen": "./src/cli.ts"
+  },
   "exports": {
     ".": {
       "bun": "./src/index.ts",
@@ -40,12 +43,12 @@
     "test": "bun test --pass-with-no-tests",
     "tsgo": "tsgo --noEmit",
     "build": "tsgo",
-    "release": "bunx syncular-publish"
+    "release": "syncular-publish"
   },
   "dependencies": {
     "@electric-sql/pglite": "^0.3.15",
-    "@syncular/migrations": "0.0.6-96",
-    "better-sqlite3": "^12.6.2",
+    "@syncular/migrations": "workspace:*",
+    "better-sqlite3": "^12.8.0",
     "kysely-bun-sqlite": "^0.4.0",
     "kysely-pglite-dialect": "^1.2.0"
   },
@@ -53,12 +56,19 @@
     "kysely": "^0.28.0"
   },
   "devDependencies": {
-    "@syncular/config": "0.0.0",
+    "@syncular/config": "workspace:*",
     "@types/better-sqlite3": "^7.6.13",
     "kysely": "*"
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__/**",
+    "!dist/**/*.test.*",
+    "!dist/**/__tests__/**",
+    "!test/**",
+    "!tests/**"
   ]
 }

package/src/app-contract.ts

@@ -0,0 +1,531 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import type { DefinedMigrations } from '@syncular/migrations';
+import { introspectCurrentSchema } from './introspect';
+import type { TableSchema, TypegenDialect } from './types';
+
+export type SyncularScopeSource = 'actorId' | 'projectId';
+export type SyncularCrdtYjsKind = 'text' | 'xml-fragment' | 'prosemirror';
+export type SyncularCrdtYjsSyncMode = 'server-merge' | 'encrypted-update-log';
+
+export interface SyncularScopeDefinition {
+  name?: string;
+  column: string;
+  source: SyncularScopeSource;
+  required?: boolean;
+}
+
+export interface SyncularCrdtYjsFieldDefinition {
+  field?: string;
+  stateColumn: string;
+  containerKey?: string;
+  rowIdField?: string;
+  kind?: SyncularCrdtYjsKind;
+  syncMode?: SyncularCrdtYjsSyncMode;
+}
+
+export interface SyncularEncryptedFieldDefinition {
+  field: string;
+  scope?: string;
+  rowIdField?: string;
+}
+
+export interface SyncedTableDefinition {
+  table: string;
+  subscriptionId?: string;
+  subscriptionParams?: Record<string, unknown>;
+  scopes?: readonly SyncularScopeDefinition[];
+  serverVersion: string;
+  blobColumns?: readonly string[];
+  crdt?: Record<string, SyncularCrdtYjsFieldDefinition>;
+  crdtYjsFields?: readonly SyncularCrdtYjsFieldDefinition[];
+  encryptedFields?: readonly SyncularEncryptedFieldDefinition[];
+  softDelete?: string;
+  sqliteWithoutRowid?: boolean;
+}
+
+export interface SyncularCountByReadModelDefinition {
+  name: string;
+  kind: 'countBy';
+  sourceTable: string;
+  outputTable: string;
+  dimensions: readonly string[];
+  countColumn?: string;
+}
+
+export type SyncularLocalReadModelDefinition =
+  SyncularCountByReadModelDefinition;
+
+export interface SyncularClientSchemaSupportDefinition {
+  minSupported?: number;
+  supported?: readonly number[];
+}
+
+export interface SyncularCodegenPathsDefinition {
+  schemaOutputPath?: string;
+  typescriptOutputPath?: string;
+  typescriptServerOutputPath?: string;
+  typescriptRuntimeImportPath?: string;
+  rustRuntimeCratePath?: string;
+  nativeSwiftOutputPath?: string;
+  nativeKotlinOutputPath?: string;
+  nativeAndroidKotlinOutputPath?: string;
+  nativeAndroidKotlinPackage?: string;
+}
+
+export interface DefineSyncularClientOptions<
+  Tables extends Record<string, SyncedTableDefinition>,
+> extends SyncularCodegenPathsDefinition {
+  migrations?: unknown;
+  tables: Tables;
+  localOnlyTables?: readonly string[];
+  localReadModels?: readonly SyncularLocalReadModelDefinition[];
+  clientSchemaSupport?: SyncularClientSchemaSupportDefinition;
+}
+
+export interface SyncularClientContract<
+  Tables extends Record<string, SyncedTableDefinition> = Record<
+    string,
+    SyncedTableDefinition
+  >,
+> extends DefineSyncularClientOptions<Tables> {
+  readonly kind: 'syncular-client-contract';
+}
+
+export interface SyncularCodegenScopeConfig {
+  name?: string;
+  column: string;
+  source: SyncularScopeSource;
+  required?: boolean;
+}
+
+export interface SyncularCodegenCrdtYjsFieldConfig {
+  field: string;
+  stateColumn: string;
+  containerKey?: string;
+  rowIdField?: string;
+  kind?: SyncularCrdtYjsKind;
+  syncMode?: SyncularCrdtYjsSyncMode;
+}
+
+export interface SyncularCodegenEncryptedFieldConfig {
+  field: string;
+  scope?: string;
+  rowIdField?: string;
+}
+
+export interface SyncularCodegenTableConfig {
+  subscriptionId?: string;
+  subscriptionParams?: Record<string, unknown>;
+  scopes?: SyncularCodegenScopeConfig[];
+  serverVersionColumn: string;
+  blobColumns?: string[];
+  crdtYjsFields?: SyncularCodegenCrdtYjsFieldConfig[];
+  encryptedFields?: SyncularCodegenEncryptedFieldConfig[];
+  softDeleteColumn?: string;
+  sqliteWithoutRowid?: boolean;
+}
+
+export interface SyncularCodegenLocalReadModelConfig {
+  name: string;
+  kind: 'countBy';
+  sourceTable: string;
+  outputTable: string;
+  dimensions: string[];
+  countColumn: string;
+}
+
+export interface SyncularCodegenConfig extends SyncularCodegenPathsDefinition {
+  tables: Record<string, SyncularCodegenTableConfig>;
+  localOnlyTables?: string[];
+  localReadModels?: SyncularCodegenLocalReadModelConfig[];
+  clientSchemaSupport?: {
+    minSupported?: number;
+    supported?: number[];
+  };
+}
+
+export interface ScaffoldSyncularClientContractOptions<DB = unknown>
+  extends SyncularCodegenPathsDefinition {
+  migrations: DefinedMigrations<DB>;
+  dialect?: TypegenDialect;
+  tables?: readonly string[];
+  scopes?: Record<string, readonly SyncularScopeDefinition[]>;
+  serverVersionColumn?:
+    | string
+    | Record<string, string>
+    | ((table: TableSchema) => string);
+  subscriptionId?:
+    | string
+    | Record<string, string>
+    | ((table: string) => string);
+  sqliteWithoutRowid?:
+    | boolean
+    | Record<string, boolean>
+    | ((table: TableSchema) => boolean);
+  clientSchemaSupport?: SyncularClientSchemaSupportDefinition;
+}
+
+export function defineSyncularClient<
+  Tables extends Record<string, SyncedTableDefinition>,
+>(
+  options: DefineSyncularClientOptions<Tables>
+): SyncularClientContract<Tables> {
+  return {
+    ...options,
+    kind: 'syncular-client-contract',
+  };
+}
+
+export function isSyncularClientContract(
+  value: unknown
+): value is SyncularClientContract {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { kind?: unknown }).kind === 'syncular-client-contract' &&
+    typeof (value as { tables?: unknown }).tables === 'object' &&
+    (value as { tables?: unknown }).tables !== null
+  );
+}
+
+export function syncedTable(
+  options: SyncedTableDefinition
+): SyncedTableDefinition {
+  return { ...options };
+}
+
+export function scope(
+  name: string,
+  options: {
+    column?: string;
+    source: SyncularScopeSource;
+    required?: boolean;
+  }
+): SyncularScopeDefinition {
+  return {
+    name,
+    column: options.column ?? name,
+    source: options.source,
+    required: options.required,
+  };
+}
+
+export function yjsText(
+  options: Omit<SyncularCrdtYjsFieldDefinition, 'kind'>
+): SyncularCrdtYjsFieldDefinition {
+  return { ...options, kind: 'text' };
+}
+
+export function encryptedField(
+  field: string,
+  options: Omit<SyncularEncryptedFieldDefinition, 'field'> = {}
+): SyncularEncryptedFieldDefinition {
+  return { field, ...options };
+}
+
+export function countByReadModel(
+  options: Omit<SyncularCountByReadModelDefinition, 'kind'>
+): SyncularCountByReadModelDefinition {
+  return { ...options, kind: 'countBy' };
+}
+
+export function toSyncularCodegenConfig(
+  contract: SyncularClientContract
+): SyncularCodegenConfig {
+  const config: SyncularCodegenConfig = {
+    tables: Object.fromEntries(
+      Object.values(contract.tables).map((table) => [
+        table.table,
+        toCodegenTable(table),
+      ])
+    ),
+  };
+
+  for (const key of CODEGEN_PATH_KEYS) {
+    const value = contract[key];
+    if (value !== undefined) {
+      config[key] = value;
+    }
+  }
+
+  if (contract.localOnlyTables && contract.localOnlyTables.length > 0) {
+    config.localOnlyTables = [...contract.localOnlyTables];
+  }
+
+  if (contract.localReadModels && contract.localReadModels.length > 0) {
+    config.localReadModels = contract.localReadModels.map((model) => ({
+      name: model.name,
+      kind: model.kind,
+      sourceTable: model.sourceTable,
+      outputTable: model.outputTable,
+      dimensions: [...model.dimensions],
+      countColumn: model.countColumn ?? 'row_count',
+    }));
+  }
+
+  if (contract.clientSchemaSupport) {
+    config.clientSchemaSupport = {
+      ...(contract.clientSchemaSupport.minSupported !== undefined
+        ? { minSupported: contract.clientSchemaSupport.minSupported }
+        : {}),
+      ...(contract.clientSchemaSupport.supported !== undefined
+        ? { supported: [...contract.clientSchemaSupport.supported] }
+        : {}),
+    };
+  }
+
+  return config;
+}
+
+export function toSyncularCodegenJson(
+  contract: SyncularClientContract,
+  space = 2
+): string {
+  return `${JSON.stringify(toSyncularCodegenConfig(contract), null, space)}\n`;
+}
+
+export async function writeSyncularCodegenJson(
+  contract: SyncularClientContract,
+  outputPath: string | URL = 'generated/syncular.codegen.json',
+  space = 2
+): Promise<void> {
+  if (typeof outputPath === 'string') {
+    await mkdir(dirname(outputPath), { recursive: true });
+  } else if (outputPath.protocol === 'file:') {
+    await mkdir(dirname(fileURLToPath(outputPath)), { recursive: true });
+  }
+  await writeFile(outputPath, toSyncularCodegenJson(contract, space));
+}
+
+export interface LoadSyncularClientContractOptions {
+  modulePath: string | URL;
+  exportName?: string;
+}
+
+export async function loadSyncularClientContract(
+  options: LoadSyncularClientContractOptions
+): Promise<SyncularClientContract> {
+  const exportName = options.exportName ?? 'app';
+  const module = (await import(
+    syncularContractModuleSpecifier(options.modulePath)
+  )) as Record<string, unknown>;
+  const contract = module[exportName];
+  if (!isSyncularClientContract(contract)) {
+    throw new Error(
+      `Syncular app contract module must export ${exportName} from defineSyncularClient(...)`
+    );
+  }
+  return contract;
+}
+
+export interface WriteSyncularCodegenJsonFromModuleOptions
+  extends LoadSyncularClientContractOptions {
+  outputPath?: string | URL;
+  space?: number;
+}
+
+export async function writeSyncularCodegenJsonFromModule(
+  options: WriteSyncularCodegenJsonFromModuleOptions
+): Promise<SyncularClientContract> {
+  const contract = await loadSyncularClientContract(options);
+  await writeSyncularCodegenJson(
+    contract,
+    options.outputPath ?? 'generated/syncular.codegen.json',
+    options.space
+  );
+  return contract;
+}
+
+export async function scaffoldSyncularClientContract<DB = unknown>(
+  options: ScaffoldSyncularClientContractOptions<DB>
+): Promise<SyncularClientContract<Record<string, SyncedTableDefinition>>> {
+  const schema = await introspectCurrentSchema(
+    options.migrations,
+    options.dialect ?? 'sqlite',
+    options.tables ? [...options.tables] : undefined
+  );
+  const tables = Object.fromEntries(
+    schema.tables.map((table) => {
+      const serverVersion = resolveServerVersionColumn(
+        table,
+        options.serverVersionColumn
+      );
+      assertColumnExists(table, serverVersion, 'server version');
+      const synced = syncedTable({
+        table: table.name,
+        subscriptionId: resolveStringOption(
+          table.name,
+          options.subscriptionId,
+          `sub-${table.name}`
+        ),
+        serverVersion,
+        scopes: options.scopes?.[table.name] ?? [],
+        sqliteWithoutRowid: resolveBooleanOption(
+          table,
+          options.sqliteWithoutRowid
+        ),
+      });
+      return [table.name, synced];
+    })
+  );
+
+  return defineSyncularClient({
+    ...pickCodegenPathOptions(options),
+    clientSchemaSupport: options.clientSchemaSupport,
+    tables,
+  });
+}
+
+const CODEGEN_PATH_KEYS = [
+  'schemaOutputPath',
+  'typescriptOutputPath',
+  'typescriptServerOutputPath',
+  'typescriptRuntimeImportPath',
+  'rustRuntimeCratePath',
+  'nativeSwiftOutputPath',
+  'nativeKotlinOutputPath',
+  'nativeAndroidKotlinOutputPath',
+  'nativeAndroidKotlinPackage',
+] as const satisfies readonly (keyof SyncularCodegenPathsDefinition)[];
+
+function toCodegenTable(
+  table: SyncedTableDefinition
+): SyncularCodegenTableConfig {
+  const config: SyncularCodegenTableConfig = {
+    serverVersionColumn: table.serverVersion,
+  };
+
+  if (table.subscriptionId !== undefined) {
+    config.subscriptionId = table.subscriptionId;
+  }
+  if (table.subscriptionParams !== undefined) {
+    config.subscriptionParams = table.subscriptionParams;
+  }
+  if (table.scopes && table.scopes.length > 0) {
+    config.scopes = table.scopes.map((item) => ({
+      ...(item.name !== undefined ? { name: item.name } : {}),
+      column: item.column,
+      source: item.source,
+      ...(item.required !== undefined ? { required: item.required } : {}),
+    }));
+  }
+  if (table.blobColumns && table.blobColumns.length > 0) {
+    config.blobColumns = [...table.blobColumns];
+  }
+
+  const crdtFields = [
+    ...Object.entries(table.crdt ?? {}).map(([field, definition]) => ({
+      field,
+      ...definition,
+    })),
+    ...(table.crdtYjsFields ?? []),
+  ];
+  if (crdtFields.length > 0) {
+    config.crdtYjsFields = crdtFields.map((field) => ({
+      field: field.field ?? '',
+      stateColumn: field.stateColumn,
+      ...(field.containerKey !== undefined
+        ? { containerKey: field.containerKey }
+        : {}),
+      ...(field.rowIdField !== undefined
+        ? { rowIdField: field.rowIdField }
+        : {}),
+      ...(field.kind !== undefined ? { kind: field.kind } : {}),
+      ...(field.syncMode !== undefined ? { syncMode: field.syncMode } : {}),
+    }));
+  }
+  if (table.encryptedFields && table.encryptedFields.length > 0) {
+    config.encryptedFields = table.encryptedFields.map((field) => ({
+      field: field.field,
+      ...(field.scope !== undefined ? { scope: field.scope } : {}),
+      ...(field.rowIdField !== undefined
+        ? { rowIdField: field.rowIdField }
+        : {}),
+    }));
+  }
+  if (table.softDelete !== undefined) {
+    config.softDeleteColumn = table.softDelete;
+  }
+  if (table.sqliteWithoutRowid !== undefined) {
+    config.sqliteWithoutRowid = table.sqliteWithoutRowid;
+  }
+
+  return config;
+}
+
+function pickCodegenPathOptions(
+  options: SyncularCodegenPathsDefinition
+): SyncularCodegenPathsDefinition {
+  const picked: SyncularCodegenPathsDefinition = {};
+  for (const key of CODEGEN_PATH_KEYS) {
+    const value = options[key];
+    if (value !== undefined) {
+      picked[key] = value;
+    }
+  }
+  return picked;
+}
+
+function syncularContractModuleSpecifier(modulePath: string | URL): string {
+  if (modulePath instanceof URL) return modulePath.href;
+  try {
+    const parsed = new URL(modulePath);
+    if (parsed.protocol === 'file:') return parsed.href;
+  } catch {
+    // Treat non-URL strings as filesystem paths or package specifiers below.
+  }
+  if (syncularLooksLikeLocalModulePath(modulePath)) {
+    return pathToFileURL(resolve(modulePath)).href;
+  }
+  return modulePath;
+}
+
+function syncularLooksLikeLocalModulePath(modulePath: string): boolean {
+  return (
+    modulePath.startsWith('.') ||
+    modulePath.startsWith('/') ||
+    (!modulePath.startsWith('@') && modulePath.includes('/')) ||
+    /\.(?:cjs|cts|js|jsx|mjs|mts|ts|tsx)$/.test(modulePath)
+  );
+}
+
+function resolveServerVersionColumn(
+  table: TableSchema,
+  option: ScaffoldSyncularClientContractOptions['serverVersionColumn']
+): string {
+  if (typeof option === 'function') return option(table);
+  if (typeof option === 'string') return option;
+  return option?.[table.name] ?? 'server_version';
+}
+
+function resolveStringOption(
+  table: string,
+  option: ScaffoldSyncularClientContractOptions['subscriptionId'],
+  fallback: string
+): string {
+  if (typeof option === 'function') return option(table);
+  if (typeof option === 'string') return option;
+  return option?.[table] ?? fallback;
+}
+
+function resolveBooleanOption(
+  table: TableSchema,
+  option: ScaffoldSyncularClientContractOptions['sqliteWithoutRowid']
+): boolean | undefined {
+  if (typeof option === 'function') return option(table);
+  if (typeof option === 'boolean') return option;
+  return option?.[table.name];
+}
+
+function assertColumnExists(
+  table: TableSchema,
+  column: string,
+  label: string
+): void {
+  if (table.columns.some((candidate) => candidate.name === column)) return;
+  throw new Error(
+    `Cannot scaffold Syncular table ${table.name}: ${label} column ${column} does not exist`
+  );
+}