kysely-schema 0.1.0

package/src/schema/types.ts

@@ -0,0 +1,158 @@
+// ─── Referential Actions ───────────────────────────────────────────────────────
+
+export type ReferentialAction = 'cascade' | 'set null' | 'restrict' | 'no action';
+
+// ─── Column Types ──────────────────────────────────────────────────────────────
+
+export type ColumnType =
+    | 'serial'
+    | 'integer'
+    | 'bigint'
+    | 'decimal'
+    | 'text'
+    | 'varchar'
+    | 'timestamp'
+    | 'date'
+    | 'time'
+    | 'boolean'
+    | 'json'
+    | 'jsonb'
+    | 'binary'
+    | 'uuid';
+
+// ─── Column Definition ────────────────────────────────────────────────────────
+
+export interface ForeignKeyReference {
+    table: string;
+    column: string;
+}
+
+export interface ColumnDefinition {
+    type: ColumnType;
+    primaryKey?: boolean;
+    notNull?: boolean;
+    nullable?: boolean;
+    unique?: boolean;
+    default?: string | number | boolean;
+    references?: ForeignKeyReference;
+    onDelete?: ReferentialAction;
+    onUpdate?: ReferentialAction;
+    index?: boolean;
+    check?: string;
+    length?: number;
+    precision?: number;
+    scale?: number;
+}
+
+// ─── Table Definition ─────────────────────────────────────────────────────────
+
+export interface IndexDefinition {
+    name?: string;
+    columns: string[];
+    unique?: boolean;
+}
+
+export interface TableDefinition {
+    columns: Record<string, ColumnDefinition>;
+    indexes: IndexDefinition[];
+    checks?: string[];
+}
+
+// ─── Schema Definition ────────────────────────────────────────────────────────
+
+export interface SchemaDefinition {
+    tables: Record<string, TableDefinition>;
+}
+
+// ─── Migration File ───────────────────────────────────────────────────────────
+
+export interface MigrationFile {
+    filename: string;
+    content: string;
+}
+
+// ─── Diff Operations ──────────────────────────────────────────────────────────
+
+export type DiffOperationType =
+    | 'addTable'
+    | 'dropTable'
+    | 'addColumn'
+    | 'dropColumn'
+    | 'alterColumn'
+    | 'addIndex'
+    | 'dropIndex';
+
+export interface BaseDiffOperation {
+    type: DiffOperationType;
+    description: string;
+}
+
+export interface AddTableOperation extends BaseDiffOperation {
+    type: 'addTable';
+    tableName: string;
+    table: TableDefinition;
+}
+
+export interface DropTableOperation extends BaseDiffOperation {
+    type: 'dropTable';
+    tableName: string;
+}
+
+export interface AddColumnOperation extends BaseDiffOperation {
+    type: 'addColumn';
+    tableName: string;
+    columnName: string;
+    column: ColumnDefinition;
+}
+
+export interface DropColumnOperation extends BaseDiffOperation {
+    type: 'dropColumn';
+    tableName: string;
+    columnName: string;
+}
+
+export interface AlterColumnOperation extends BaseDiffOperation {
+    type: 'alterColumn';
+    tableName: string;
+    columnName: string;
+    oldColumn: ColumnDefinition;
+    newColumn: ColumnDefinition;
+}
+
+export interface AddIndexOperation extends BaseDiffOperation {
+    type: 'addIndex';
+    tableName: string;
+    index: IndexDefinition;
+}
+
+export interface DropIndexOperation extends BaseDiffOperation {
+    type: 'dropIndex';
+    tableName: string;
+    indexName: string;
+}
+
+export type DiffOperation =
+    | AddTableOperation
+    | DropTableOperation
+    | AddColumnOperation
+    | DropColumnOperation
+    | AlterColumnOperation
+    | AddIndexOperation
+    | DropIndexOperation;
+
+// ─── Schema Snapshot (used by differ) ─────────────────────────────────────────
+
+export interface SchemaSnapshot {
+    version: string;
+    timestamp: string;
+    schema: SchemaDefinition;
+}
+
+// ─── Config ───────────────────────────────────────────────────────────────────
+
+export interface KyselySchemaConfig {
+    schemaPath: string;
+    migrationsDir: string;
+    generatedDir: string;
+    snapshotDir: string;
+}

package/src/schema/validators.ts

@@ -0,0 +1,113 @@
+import type { SchemaDefinition } from './types.js';
+
+export interface ValidationError {
+    table: string;
+    column?: string;
+    message: string;
+}
+
+/**
+ * Validate a schema definition and return a list of problems.
+ * Returns an empty array if the schema is valid.
+ */
+export function validateSchema(schema: SchemaDefinition): ValidationError[] {
+    const errors: ValidationError[] = [];
+    const tableNames = Object.keys(schema.tables);
+
+    for (const [tableName, tableDef] of Object.entries(schema.tables)) {
+        const columnNames = Object.keys(tableDef.columns);
+
+        // ── check: table must have at least one column ──
+        if (columnNames.length === 0) {
+            errors.push({
+                table: tableName,
+                message: 'Table has no columns defined.',
+            });
+        }
+
+        // ── check: at least one primary key ──
+        const pks = columnNames.filter((c) => tableDef.columns[c].primaryKey);
+        if (pks.length === 0) {
+            errors.push({
+                table: tableName,
+                message: 'Table has no primary key defined.',
+            });
+        }
+
+        for (const [colName, colDef] of Object.entries(tableDef.columns)) {
+            // ── check: notNull + nullable conflict ──
+            if (colDef.notNull && colDef.nullable) {
+                errors.push({
+                    table: tableName,
+                    column: colName,
+                    message: 'Column cannot be both notNull and nullable.',
+                });
+            }
+
+            // ── check: foreign key target exists ──
+            if (colDef.references) {
+                if (!tableNames.includes(colDef.references.table)) {
+                    errors.push({
+                        table: tableName,
+                        column: colName,
+                        message: `Foreign key references unknown table '${colDef.references.table}'.`,
+                    });
+                } else {
+                    const targetTable = schema.tables[colDef.references.table];
+                    if (
+                        targetTable &&
+                        !Object.keys(targetTable.columns).includes(colDef.references.column)
+                    ) {
+                        errors.push({
+                            table: tableName,
+                            column: colName,
+                            message: `Foreign key references unknown column '${colDef.references.column}' in table '${colDef.references.table}'.`,
+                        });
+                    }
+                }
+            }
+
+            // ── check: onDelete / onUpdate without references ──
+            if ((colDef.onDelete || colDef.onUpdate) && !colDef.references) {
+                errors.push({
+                    table: tableName,
+                    column: colName,
+                    message: 'onDelete/onUpdate specified without a foreign key reference.',
+                });
+            }
+
+            // ── check: varchar length ──
+            if (colDef.type === 'varchar' && colDef.length !== undefined && colDef.length <= 0) {
+                errors.push({
+                    table: tableName,
+                    column: colName,
+                    message: 'varchar length must be a positive number.',
+                });
+            }
+
+            // ── check: decimal precision/scale ──
+            if (colDef.type === 'decimal') {
+                if (colDef.precision !== undefined && colDef.precision <= 0) {
+                    errors.push({
+                        table: tableName,
+                        column: colName,
+                        message: 'decimal precision must be a positive number.',
+                    });
+                }
+                if (
+                    colDef.scale !== undefined &&
+                    colDef.precision !== undefined &&
+                    colDef.scale > colDef.precision
+                ) {
+                    errors.push({
+                        table: tableName,
+                        column: colName,
+                        message: 'decimal scale cannot exceed precision.',
+                    });
+                }
+            }
+        }
+    }
+
+    return errors;
+}

package/tests/differ.test.ts

@@ -0,0 +1,161 @@
+import { describe, it, expect } from 'vitest';
+import { SchemaDiffer } from '../src/differ/index.js';
+import { defineSchema, table, column } from '../src/schema/dsl.js';
+
+describe('SchemaDiffer', () => {
+    const differ = new SchemaDiffer();
+
+    it('detects no changes for identical schemas', () => {
+        const schema = defineSchema({
+            user: table({ id: column.serial().primaryKey() }),
+        });
+        const ops = differ.diff(schema, schema);
+        expect(ops).toEqual([]);
+    });
+
+    it('detects added tables', () => {
+        const prev = defineSchema({
+            user: table({ id: column.serial().primaryKey() }),
+        });
+        const curr = defineSchema({
+            user: table({ id: column.serial().primaryKey() }),
+            post: table({ id: column.serial().primaryKey() }),
+        });
+
+        const ops = differ.diff(prev, curr);
+        expect(ops).toHaveLength(1);
+        expect(ops[0].type).toBe('addTable');
+        if (ops[0].type === 'addTable') {
+            expect(ops[0].tableName).toBe('post');
+        }
+    });
+
+    it('detects dropped tables', () => {
+        const prev = defineSchema({
+            user: table({ id: column.serial().primaryKey() }),
+            post: table({ id: column.serial().primaryKey() }),
+        });
+        const curr = defineSchema({
+            user: table({ id: column.serial().primaryKey() }),
+        });
+
+        const ops = differ.diff(prev, curr);
+        expect(ops).toHaveLength(1);
+        expect(ops[0].type).toBe('dropTable');
+        if (ops[0].type === 'dropTable') {
+            expect(ops[0].tableName).toBe('post');
+        }
+    });
+
+    it('detects added columns', () => {
+        const prev = defineSchema({
+            user: table({ id: column.serial().primaryKey() }),
+        });
+        const curr = defineSchema({
+            user: table({
+                id: column.serial().primaryKey(),
+                email: column.text().notNull(),
+            }),
+        });
+
+        const ops = differ.diff(prev, curr);
+        expect(ops).toHaveLength(1);
+        expect(ops[0].type).toBe('addColumn');
+        if (ops[0].type === 'addColumn') {
+            expect(ops[0].tableName).toBe('user');
+            expect(ops[0].columnName).toBe('email');
+        }
+    });
+
+    it('detects dropped columns', () => {
+        const prev = defineSchema({
+            user: table({
+                id: column.serial().primaryKey(),
+                email: column.text().notNull(),
+            }),
+        });
+        const curr = defineSchema({
+            user: table({ id: column.serial().primaryKey() }),
+        });
+
+        const ops = differ.diff(prev, curr);
+        expect(ops).toHaveLength(1);
+        expect(ops[0].type).toBe('dropColumn');
+        if (ops[0].type === 'dropColumn') {
+            expect(ops[0].tableName).toBe('user');
+            expect(ops[0].columnName).toBe('email');
+        }
+    });
+
+    it('detects altered columns', () => {
+        const prev = defineSchema({
+            user: table({
+                id: column.serial().primaryKey(),
+                name: column.text().notNull(),
+            }),
+        });
+        const curr = defineSchema({
+            user: table({
+                id: column.serial().primaryKey(),
+                name: column.varchar(200).notNull(),
+            }),
+        });
+
+        const ops = differ.diff(prev, curr);
+        expect(ops).toHaveLength(1);
+        expect(ops[0].type).toBe('alterColumn');
+        if (ops[0].type === 'alterColumn') {
+            expect(ops[0].tableName).toBe('user');
+            expect(ops[0].columnName).toBe('name');
+            expect(ops[0].oldColumn.type).toBe('text');
+            expect(ops[0].newColumn.type).toBe('varchar');
+        }
+    });
+
+    it('detects multiple changes at once', () => {
+        const prev = defineSchema({
+            user: table({
+                id: column.serial().primaryKey(),
+                email: column.text().notNull(),
+            }),
+            post: table({ id: column.serial().primaryKey() }),
+        });
+        const curr = defineSchema({
+            user: table({
+                id: column.serial().primaryKey(),
+                email: column.varchar(255).notNull(),
+                name: column.text().nullable(),
+            }),
+            comment: table({ id: column.serial().primaryKey() }),
+        });
+
+        const ops = differ.diff(prev, curr);
+        const types = ops.map((o) => o.type);
+
+        expect(types).toContain('addTable');      // comment
+        expect(types).toContain('dropTable');      // post
+        expect(types).toContain('addColumn');      // user.name
+        expect(types).toContain('alterColumn');    // user.email
+    });
+
+    describe('generateAlterMigration()', () => {
+        it('generates ALTER TABLE for add column', () => {
+            const prev = defineSchema({
+                user: table({ id: column.serial().primaryKey() }),
+            });
+            const curr = defineSchema({
+                user: table({
+                    id: column.serial().primaryKey(),
+                    name: column.text().nullable(),
+                }),
+            });
+
+            const ops = differ.diff(prev, curr);
+            const migration = differ.generateAlterMigration(ops);
+
+            expect(migration.up).toContain("alterTable('user')");
+            expect(migration.up).toContain("addColumn('name', 'text')");
+            expect(migration.down).toContain("dropColumn('name')");
+        });
+    });
+});

package/tests/dsl.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect } from 'vitest';
+import { column, table, defineSchema, ColumnBuilder } from '../src/schema/dsl.js';
+
+describe('ColumnBuilder', () => {
+    it('creates a serial column', () => {
+        const col = column.serial().build();
+        expect(col.type).toBe('serial');
+    });
+
+    it('chains primaryKey()', () => {
+        const col = column.serial().primaryKey().build();
+        expect(col.primaryKey).toBe(true);
+    });
+
+    it('chains notNull()', () => {
+        const col = column.text().notNull().build();
+        expect(col.notNull).toBe(true);
+    });
+
+    it('chains nullable()', () => {
+        const col = column.text().nullable().build();
+        expect(col.nullable).toBe(true);
+    });
+
+    it('chains unique()', () => {
+        const col = column.text().unique().build();
+        expect(col.unique).toBe(true);
+    });
+
+    it('chains default() with string', () => {
+        const col = column.text().default('hello').build();
+        expect(col.default).toBe('hello');
+    });
+
+    it('chains default() with boolean', () => {
+        const col = column.boolean().default(false).build();
+        expect(col.default).toBe(false);
+    });
+
+    it('chains default() with number', () => {
+        const col = column.integer().default(42).build();
+        expect(col.default).toBe(42);
+    });
+
+    it('chains references()', () => {
+        const col = column.integer().references('user', 'id').build();
+        expect(col.references).toEqual({ table: 'user', column: 'id' });
+    });
+
+    it('chains onDelete() and onUpdate()', () => {
+        const col = column
+            .integer()
+            .references('user', 'id')
+            .onDelete('cascade')
+            .onUpdate('set null')
+            .build();
+        expect(col.onDelete).toBe('cascade');
+        expect(col.onUpdate).toBe('set null');
+    });
+
+    it('chains index()', () => {
+        const col = column.integer().index().build();
+        expect(col.index).toBe(true);
+    });
+
+    it('chains check()', () => {
+        const col = column.integer().check('value > 0').build();
+        expect(col.check).toBe('value > 0');
+    });
+});
+
+describe('column factory', () => {
+    it.each([
+        ['serial', column.serial],
+        ['integer', column.integer],
+        ['bigint', column.bigint],
+        ['text', column.text],
+        ['boolean', column.boolean],
+        ['timestamp', column.timestamp],
+        ['date', column.date],
+        ['time', column.time],
+        ['json', column.json],
+        ['jsonb', column.jsonb],
+        ['binary', column.binary],
+        ['uuid', column.uuid],
+    ] as const)('creates %s column', (type, factory) => {
+        const col = factory().build();
+        expect(col.type).toBe(type);
+    });
+
+    it('creates varchar with length', () => {
+        const col = column.varchar(255).build();
+        expect(col.type).toBe('varchar');
+        expect(col.length).toBe(255);
+    });
+
+    it('creates decimal with precision and scale', () => {
+        const col = column.decimal(10, 2).build();
+        expect(col.type).toBe('decimal');
+        expect(col.precision).toBe(10);
+        expect(col.scale).toBe(2);
+    });
+});
+
+describe('table()', () => {
+    it('converts ColumnBuilders to ColumnDefinitions', () => {
+        const t = table({
+            id: column.serial().primaryKey(),
+            name: column.text().notNull(),
+        });
+        expect(t.columns.id.type).toBe('serial');
+        expect(t.columns.id.primaryKey).toBe(true);
+        expect(t.columns.name.type).toBe('text');
+        expect(t.columns.name.notNull).toBe(true);
+        expect(t.indexes).toEqual([]);
+    });
+});
+
+describe('defineSchema()', () => {
+    it('wraps tables into a SchemaDefinition', () => {
+        const schema = defineSchema({
+            user: table({
+                id: column.serial().primaryKey(),
+                email: column.text().notNull().unique(),
+            }),
+        });
+        expect(schema.tables).toBeDefined();
+        expect(schema.tables.user).toBeDefined();
+        expect(schema.tables.user.columns.id.primaryKey).toBe(true);
+        expect(schema.tables.user.columns.email.unique).toBe(true);
+    });
+
+    it('supports multiple tables', () => {
+        const schema = defineSchema({
+            user: table({ id: column.serial().primaryKey() }),
+            post: table({ id: column.serial().primaryKey() }),
+        });
+        expect(Object.keys(schema.tables)).toEqual(['user', 'post']);
+    });
+});
+
+describe('complex schema', () => {
+    it('builds a blog schema with relations', () => {
+        const schema = defineSchema({
+            user: table({
+                id: column.serial().primaryKey(),
+                email: column.text().notNull().unique(),
+                name: column.text().nullable(),
+                createdAt: column.timestamp().default('now()').notNull(),
+            }),
+            post: table({
+                id: column.serial().primaryKey(),
+                title: column.text().notNull(),
+                authorId: column
+                    .integer()
+                    .notNull()
+                    .references('user', 'id')
+                    .onDelete('cascade'),
+                createdAt: column.timestamp().default('now()').notNull(),
+            }),
+        });
+
+        const postAuthorId = schema.tables.post.columns.authorId;
+        expect(postAuthorId.references).toEqual({ table: 'user', column: 'id' });
+        expect(postAuthorId.onDelete).toBe('cascade');
+        expect(postAuthorId.notNull).toBe(true);
+    });
+});