kysely-schema 0.1.0

package/src/differ/index.ts

@@ -0,0 +1,150 @@
+import type {
+    SchemaDefinition,
+    DiffOperation,
+    ColumnDefinition,
+} from '../schema/types.js';
+
+/**
+ * Compares two schema snapshots and returns a list of diff operations
+ * needed to migrate from `previous` to `current`.
+ */
+export class SchemaDiffer {
+    diff(previous: SchemaDefinition, current: SchemaDefinition): DiffOperation[] {
+        const ops: DiffOperation[] = [];
+
+        const prevTables = new Set(Object.keys(previous.tables));
+        const currTables = new Set(Object.keys(current.tables));
+
+        // ── Added tables ──
+        for (const tableName of currTables) {
+            if (!prevTables.has(tableName)) {
+                ops.push({
+                    type: 'addTable',
+                    tableName,
+                    table: current.tables[tableName],
+                    description: `Create table '${tableName}'`,
+                });
+            }
+        }
+
+        // ── Dropped tables ──
+        for (const tableName of prevTables) {
+            if (!currTables.has(tableName)) {
+                ops.push({
+                    type: 'dropTable',
+                    tableName,
+                    description: `Drop table '${tableName}'`,
+                });
+            }
+        }
+
+        // ── Changed tables (columns) ──
+        for (const tableName of currTables) {
+            if (!prevTables.has(tableName)) continue; // already handled as addTable
+
+            const prevCols = previous.tables[tableName].columns;
+            const currCols = current.tables[tableName].columns;
+            const prevColNames = new Set(Object.keys(prevCols));
+            const currColNames = new Set(Object.keys(currCols));
+
+            // Added columns
+            for (const colName of currColNames) {
+                if (!prevColNames.has(colName)) {
+                    ops.push({
+                        type: 'addColumn',
+                        tableName,
+                        columnName: colName,
+                        column: currCols[colName],
+                        description: `Add column '${colName}' to table '${tableName}'`,
+                    });
+                }
+            }
+
+            // Dropped columns
+            for (const colName of prevColNames) {
+                if (!currColNames.has(colName)) {
+                    ops.push({
+                        type: 'dropColumn',
+                        tableName,
+                        columnName: colName,
+                        description: `Drop column '${colName}' from table '${tableName}'`,
+                    });
+                }
+            }
+
+            // Altered columns
+            for (const colName of currColNames) {
+                if (!prevColNames.has(colName)) continue;
+                if (!this.columnsEqual(prevCols[colName], currCols[colName])) {
+                    ops.push({
+                        type: 'alterColumn',
+                        tableName,
+                        columnName: colName,
+                        oldColumn: prevCols[colName],
+                        newColumn: currCols[colName],
+                        description: `Alter column '${colName}' in table '${tableName}'`,
+                    });
+                }
+            }
+        }
+
+        return ops;
+    }
+
+    /**
+     * Generate an ALTER-TABLE migration string from a list of diff operations.
+     */
+    generateAlterMigration(ops: DiffOperation[]): { up: string; down: string } {
+        const upLines: string[] = [];
+        const downLines: string[] = [];
+
+        for (const op of ops) {
+            switch (op.type) {
+                case 'addTable': {
+                    upLines.push(`  await db.schema`);
+                    upLines.push(`    .createTable('${op.tableName}')`);
+                    for (const [colName, colDef] of Object.entries(op.table.columns)) {
+                        upLines.push(`    .addColumn('${colName}', '${colDef.type}')`);
+                    }
+                    upLines.push(`    .execute();`);
+                    downLines.push(`  await db.schema.dropTable('${op.tableName}').ifExists().execute();`);
+                    break;
+                }
+                case 'dropTable': {
+                    upLines.push(`  await db.schema.dropTable('${op.tableName}').ifExists().execute();`);
+                    // down: cannot fully reverse without the old definition
+                    downLines.push(`  // TODO: Recreate table '${op.tableName}'`);
+                    break;
+                }
+                case 'addColumn': {
+                    upLines.push(`  await db.schema.alterTable('${op.tableName}').addColumn('${op.columnName}', '${op.column.type}').execute();`);
+                    downLines.push(`  await db.schema.alterTable('${op.tableName}').dropColumn('${op.columnName}').execute();`);
+                    break;
+                }
+                case 'dropColumn': {
+                    upLines.push(`  await db.schema.alterTable('${op.tableName}').dropColumn('${op.columnName}').execute();`);
+                    downLines.push(`  // TODO: Re-add column '${op.columnName}' to '${op.tableName}'`);
+                    break;
+                }
+                case 'alterColumn': {
+                    upLines.push(`  await db.schema.alterTable('${op.tableName}').alterColumn('${op.columnName}', (col) => col.setDataType('${op.newColumn.type}')).execute();`);
+                    downLines.push(`  await db.schema.alterTable('${op.tableName}').alterColumn('${op.columnName}', (col) => col.setDataType('${op.oldColumn.type}')).execute();`);
+                    break;
+                }
+                default:
+                    break;
+            }
+        }
+
+        return {
+            up: upLines.join('\n'),
+            down: downLines.join('\n'),
+        };
+    }
+
+    // ── Private helpers ──────────────────────────────────────────────────
+
+    private columnsEqual(a: ColumnDefinition, b: ColumnDefinition): boolean {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+}

package/src/differ/operations.ts

@@ -0,0 +1,33 @@
+import type { DiffOperation } from '../schema/types.js';
+
+// Re-export the operation types for convenience
+export type {
+    DiffOperation,
+    AddTableOperation,
+    DropTableOperation,
+    AddColumnOperation,
+    DropColumnOperation,
+    AlterColumnOperation,
+    AddIndexOperation,
+    DropIndexOperation,
+} from '../schema/types.js';
+
+/**
+ * Labels used when printing diffs to the console.
+ */
+export const operationLabels: Record<DiffOperation['type'], string> = {
+    addTable: '+ ADD TABLE',
+    dropTable: '- DROP TABLE',
+    addColumn: '+ ADD COLUMN',
+    dropColumn: '- DROP COLUMN',
+    alterColumn: '~ ALTER COLUMN',
+    addIndex: '+ ADD INDEX',
+    dropIndex: '- DROP INDEX',
+};
+
+/**
+ * Return a human-readable summary for a diff operation.
+ */
+export function describeOperation(op: DiffOperation): string {
+    return `${operationLabels[op.type]}: ${op.description}`;
+}

package/src/generators/migration.ts

@@ -0,0 +1,172 @@
+import type {
+    SchemaDefinition,
+    MigrationFile,
+    ColumnDefinition,
+    TableDefinition,
+} from '../schema/types.js';
+
+/**
+ * Generates Kysely migration files from a SchemaDefinition.
+ */
+export class MigrationGenerator {
+    /**
+     * Generate a full CREATE-TABLE migration for the entire schema.
+     */
+    generate(schema: SchemaDefinition, migrationName: string): MigrationFile {
+        const timestamp = this.generateTimestamp();
+        const filename = `${timestamp}_${this.sanitize(migrationName)}.ts`;
+
+        const upCode = this.generateUpFunction(schema);
+        const downCode = this.generateDownFunction(schema);
+
+        const content = [
+            `import { Kysely, sql } from 'kysely';`,
+            ``,
+            `export async function up(db: Kysely<any>): Promise<void> {`,
+            upCode,
+            `}`,
+            ``,
+            `export async function down(db: Kysely<any>): Promise<void> {`,
+            downCode,
+            `}`,
+            ``,
+        ].join('\n');
+
+        return { filename, content };
+    }
+
+    // ── Private helpers ──────────────────────────────────────────────────────
+
+    private generateUpFunction(schema: SchemaDefinition): string {
+        const parts: string[] = [];
+
+        for (const [tableName, tableDef] of Object.entries(schema.tables)) {
+            parts.push(this.generateCreateTable(tableName, tableDef));
+            const indexes = this.generateIndexes(tableName, tableDef);
+            if (indexes) parts.push(indexes);
+        }
+
+        return parts.join('\n');
+    }
+
+    private generateCreateTable(name: string, def: TableDefinition): string {
+        const lines: string[] = [];
+        lines.push(`  await db.schema`);
+        lines.push(`    .createTable('${name}')`);
+
+        for (const [colName, colDef] of Object.entries(def.columns)) {
+            lines.push(this.generateColumnDefinition(colName, colDef));
+        }
+
+        lines.push(`    .execute();`);
+        return lines.join('\n');
+    }
+
+    private generateColumnDefinition(name: string, def: ColumnDefinition): string {
+        const type = this.mapColumnType(def);
+        const modifiers = this.buildModifiers(def);
+
+        if (modifiers.length > 0) {
+            return `    .addColumn('${name}', '${type}', (col) => col.${modifiers.join('.')})`;
+        }
+        return `    .addColumn('${name}', '${type}')`;
+    }
+
+    private buildModifiers(def: ColumnDefinition): string[] {
+        const mods: string[] = [];
+
+        if (def.primaryKey) mods.push('primaryKey()');
+        if (def.notNull) mods.push('notNull()');
+        if (def.unique) mods.push('unique()');
+
+        if (def.default !== undefined) {
+            mods.push(`defaultTo(${this.formatDefaultValue(def.default, def.type)})`);
+        }
+
+        if (def.references) {
+            mods.push(`references('${def.references.table}.${def.references.column}')`);
+            if (def.onDelete) mods.push(`onDelete('${def.onDelete}')`);
+            if (def.onUpdate) mods.push(`onUpdate('${def.onUpdate}')`);
+        }
+
+        if (def.check) {
+            mods.push(`check(sql\`${def.check}\`)`);
+        }
+
+        return mods;
+    }
+
+    private generateDownFunction(schema: SchemaDefinition): string {
+        const tables = Object.keys(schema.tables).reverse();
+        return tables
+            .map((t) => `  await db.schema.dropTable('${t}').ifExists().execute();`)
+            .join('\n');
+    }
+
+    private generateIndexes(tableName: string, tableDef: TableDefinition): string {
+        const lines: string[] = [];
+
+        // Auto-generate indexes for indexed columns and foreign keys
+        for (const [colName, colDef] of Object.entries(tableDef.columns)) {
+            if (colDef.index || colDef.references) {
+                lines.push(`  await db.schema`);
+                lines.push(`    .createIndex('${tableName}_${colName}_index')`);
+                lines.push(`    .on('${tableName}')`);
+                lines.push(`    .column('${colName}')`);
+                lines.push(`    .execute();`);
+            }
+        }
+
+        // Explicit indexes
+        for (const idx of tableDef.indexes) {
+            const idxName = idx.name || `${tableName}_${idx.columns.join('_')}_index`;
+            lines.push(`  await db.schema`);
+            if (idx.unique) {
+                lines.push(`    .createIndex('${idxName}')`);
+                lines.push(`    .on('${tableName}')`);
+                lines.push(`    .columns([${idx.columns.map((c) => `'${c}'`).join(', ')}])`);
+                lines.push(`    .unique()`);
+            } else {
+                lines.push(`    .createIndex('${idxName}')`);
+                lines.push(`    .on('${tableName}')`);
+                lines.push(`    .columns([${idx.columns.map((c) => `'${c}'`).join(', ')}])`);
+            }
+            lines.push(`    .execute();`);
+        }
+
+        return lines.length > 0 ? lines.join('\n') : '';
+    }
+
+    private mapColumnType(def: ColumnDefinition): string {
+        switch (def.type) {
+            case 'varchar':
+                return def.length ? `varchar(${def.length})` : 'varchar';
+            case 'decimal':
+                if (def.precision !== undefined && def.scale !== undefined) {
+                    return `decimal(${def.precision}, ${def.scale})`;
+                }
+                return 'decimal';
+            default:
+                return def.type;
+        }
+    }
+
+    private formatDefaultValue(value: string | number | boolean, _type: string): string {
+        if (typeof value === 'string' && value === 'now()') return 'sql`now()`';
+        if (typeof value === 'string') return `'${value}'`;
+        if (typeof value === 'boolean') return value.toString();
+        return String(value);
+    }
+
+    private generateTimestamp(): string {
+        const now = new Date();
+        return now
+            .toISOString()
+            .replace(/[-:]/g, '')
+            .split('.')[0];
+    }
+
+    private sanitize(name: string): string {
+        return name.replace(/[^a-zA-Z0-9_]/g, '_').toLowerCase();
+    }
+}

package/src/generators/templates.ts

@@ -0,0 +1,33 @@
+// ─── Code templates used by the CLI ────────────────────────────────────────
+
+/**
+ * Default schema template written by `kysely-schema init`.
+ */
+export const schemaTemplate = `import { defineSchema, table, column } from 'kysely-schema';
+
+export default defineSchema({
+  // Define your tables here. Example:
+  //
+  // user: table({
+  //   id: column.serial().primaryKey(),
+  //   email: column.text().notNull().unique(),
+  //   name: column.text().nullable(),
+  //   createdAt: column.timestamp().default('now()').notNull(),
+  // }),
+});
+`;
+
+/**
+ * Default config file template.
+ */
+export const configTemplate = `import type { KyselySchemaConfig } from 'kysely-schema';
+
+const config: KyselySchemaConfig = {
+  schemaPath: './schema/index.ts',
+  migrationsDir: './migrations',
+  generatedDir: './generated',
+  snapshotDir: './.kysely-schema',
+};
+
+export default config;
+`;

package/src/generators/types.ts

@@ -0,0 +1,91 @@
+import type { SchemaDefinition, ColumnDefinition } from '../schema/types.js';
+
+/**
+ * Generates a TypeScript `Database` interface from a SchemaDefinition.
+ */
+export class TypeGenerator {
+    generate(schema: SchemaDefinition): string {
+        const lines: string[] = [];
+
+        lines.push('// Auto-generated by kysely-schema — DO NOT EDIT');
+        lines.push('');
+        lines.push('import type { Generated, ColumnType } from \'kysely\';');
+        lines.push('');
+
+        // Generate individual table interfaces
+        for (const [tableName, tableDef] of Object.entries(schema.tables)) {
+            const pascalName = this.toPascalCase(tableName);
+            lines.push(`export interface ${pascalName}Table {`);
+
+            for (const [colName, colDef] of Object.entries(tableDef.columns)) {
+                const tsType = this.mapToTypeScript(colDef);
+                lines.push(`  ${colName}: ${tsType};`);
+            }
+
+            lines.push('}');
+            lines.push('');
+        }
+
+        // Generate the Database interface
+        lines.push('export interface Database {');
+        for (const tableName of Object.keys(schema.tables)) {
+            const pascalName = this.toPascalCase(tableName);
+            lines.push(`  ${tableName}: ${pascalName}Table;`);
+        }
+        lines.push('}');
+        lines.push('');
+
+        return lines.join('\n');
+    }
+
+    // ── Private helpers ──────────────────────────────────────────────────
+
+    private mapToTypeScript(def: ColumnDefinition): string {
+        const baseType = this.baseTypeMap(def.type);
+        let tsType = baseType;
+
+        // serial / auto-increment columns are Generated<>
+        if (def.type === 'serial') {
+            tsType = `Generated<${baseType}>`;
+        }
+
+        // Columns with a default value but not serial are also Generated<>
+        if (def.default !== undefined && def.type !== 'serial') {
+            tsType = `Generated<${baseType}>`;
+        }
+
+        // Nullable
+        if (def.nullable || (!def.notNull && !def.primaryKey && def.type !== 'serial')) {
+            tsType += ' | null';
+        }
+
+        return tsType;
+    }
+
+    private baseTypeMap(type: string): string {
+        const map: Record<string, string> = {
+            serial: 'number',
+            integer: 'number',
+            bigint: 'string',
+            decimal: 'string',
+            text: 'string',
+            varchar: 'string',
+            timestamp: 'Date',
+            date: 'Date',
+            time: 'string',
+            boolean: 'boolean',
+            json: 'unknown',
+            jsonb: 'unknown',
+            binary: 'Buffer',
+            uuid: 'string',
+        };
+        return map[type] || 'unknown';
+    }
+
+    private toPascalCase(str: string): string {
+        return str
+            .split(/[_\- ]+/)
+            .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+            .join('');
+    }
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+// ─── Public API for kysely-schema ────────────────────────────────────────────
+
+// Schema DSL
+export { column, table, defineSchema, ColumnBuilder } from './schema/dsl.js';
+
+// Schema types
+export type {
+    ColumnDefinition,
+    ColumnType,
+    ReferentialAction,
+    ForeignKeyReference,
+    IndexDefinition,
+    TableDefinition,
+    SchemaDefinition,
+    MigrationFile,
+    DiffOperation,
+    DiffOperationType,
+    AddTableOperation,
+    DropTableOperation,
+    AddColumnOperation,
+    DropColumnOperation,
+    AlterColumnOperation,
+    AddIndexOperation,
+    DropIndexOperation,
+    SchemaSnapshot,
+    KyselySchemaConfig,
+} from './schema/types.js';
+
+// Validators
+export { validateSchema } from './schema/validators.js';
+export type { ValidationError } from './schema/validators.js';
+
+// Generators
+export { MigrationGenerator } from './generators/migration.js';
+export { TypeGenerator } from './generators/types.js';
+export { schemaTemplate, configTemplate } from './generators/templates.js';
+
+// Differ
+export { SchemaDiffer } from './differ/index.js';
+export { operationLabels, describeOperation } from './differ/operations.js';

package/src/schema/dsl.ts

@@ -0,0 +1,125 @@
+import type {
+    ColumnDefinition,
+    ColumnType,
+    ReferentialAction,
+    TableDefinition,
+    SchemaDefinition,
+} from './types.js';
+
+// ─── ColumnBuilder ────────────────────────────────────────────────────────────
+
+export class ColumnBuilder {
+    private def: ColumnDefinition;
+
+    constructor(init: Partial<ColumnDefinition> & { type: ColumnType }) {
+        this.def = { ...init } as ColumnDefinition;
+    }
+
+    primaryKey(): this {
+        this.def.primaryKey = true;
+        return this;
+    }
+
+    notNull(): this {
+        this.def.notNull = true;
+        return this;
+    }
+
+    nullable(): this {
+        this.def.nullable = true;
+        return this;
+    }
+
+    unique(): this {
+        this.def.unique = true;
+        return this;
+    }
+
+    default(value: string | number | boolean): this {
+        this.def.default = value;
+        return this;
+    }
+
+    references(table: string, col: string): this {
+        this.def.references = { table, column: col };
+        return this;
+    }
+
+    onDelete(action: ReferentialAction): this {
+        this.def.onDelete = action;
+        return this;
+    }
+
+    onUpdate(action: ReferentialAction): this {
+        this.def.onUpdate = action;
+        return this;
+    }
+
+    index(): this {
+        this.def.index = true;
+        return this;
+    }
+
+    check(expression: string): this {
+        this.def.check = expression;
+        return this;
+    }
+
+    /** @internal Return the raw column definition. */
+    build(): ColumnDefinition {
+        return { ...this.def };
+    }
+}
+
+// ─── Column factory ──────────────────────────────────────────────────────────
+
+export const column = {
+    // Numeric types
+    serial: () => new ColumnBuilder({ type: 'serial' }),
+    integer: () => new ColumnBuilder({ type: 'integer' }),
+    bigint: () => new ColumnBuilder({ type: 'bigint' }),
+    decimal: (precision?: number, scale?: number) =>
+        new ColumnBuilder({ type: 'decimal', precision, scale }),
+
+    // Text types
+    text: () => new ColumnBuilder({ type: 'text' }),
+    varchar: (length?: number) => new ColumnBuilder({ type: 'varchar', length }),
+
+    // Date / Time types
+    timestamp: () => new ColumnBuilder({ type: 'timestamp' }),
+    date: () => new ColumnBuilder({ type: 'date' }),
+    time: () => new ColumnBuilder({ type: 'time' }),
+
+    // Boolean
+    boolean: () => new ColumnBuilder({ type: 'boolean' }),
+
+    // JSON
+    json: () => new ColumnBuilder({ type: 'json' }),
+    jsonb: () => new ColumnBuilder({ type: 'jsonb' }),
+
+    // Binary
+    binary: () => new ColumnBuilder({ type: 'binary' }),
+
+    // UUID
+    uuid: () => new ColumnBuilder({ type: 'uuid' }),
+};
+
+// ─── Table helper ─────────────────────────────────────────────────────────────
+
+export function table(
+    columns: Record<string, ColumnBuilder>,
+): TableDefinition {
+    const built: Record<string, ColumnDefinition> = {};
+    for (const [name, builder] of Object.entries(columns)) {
+        built[name] = builder.build();
+    }
+    return { columns: built, indexes: [] };
+}
+
+// ─── defineSchema ─────────────────────────────────────────────────────────────
+
+export function defineSchema(
+    tables: Record<string, TableDefinition>,
+): SchemaDefinition {
+    return { tables };
+}