ts-mysql-ddl 1.0.0

package/src/define-table.ts

@@ -0,0 +1,62 @@
+/**
+ * Factory that creates a TableSchema from column refs and metadata.
+ *
+ * Input columns are ColumnRef objects (created via `col()`).
+ * defineTable sets their _table and _column identity.
+ *
+ * Usage:
+ *   const columns = {
+ *     id:   col({ type: MysqlType.VARCHAR, length: 12, primaryKey: true }),
+ *     name: col({ type: MysqlType.VARCHAR, length: 100 }),
+ *   };
+ *
+ *   export const merchant = defineTable('merchant', { columns });
+ *
+ *   export const coupon = defineTable('coupon', {
+ *     columns: {
+ *       mer_id: col({ type: MysqlType.VARCHAR, length: 20 }),
+ *     },
+ *     foreignKeys: {
+ *       fk_coupon_merchant: {
+ *         columns: [columns.mer_id],
+ *         ref: merchant.columns.id,
+ *       },
+ *     },
+ *   });
+ */
+
+import { ColumnRef } from './column-ref';
+import type { InternalTableDef, TableSchema, ForeignKey, IndexDef } from './table-def';
+
+export interface DefineTableInput {
+  columns: Record<string, ColumnRef>;
+  primaryKey?: ColumnRef | ColumnRef[];
+  foreignKeys?: Record<string, ForeignKey>;
+  indexes?: IndexDef[];
+  comment?: string;
+}
+
+export function defineTable(name: string, input: DefineTableInput): TableSchema {
+  const colDefs: Record<string, import('./column-def').ColumnDef> = {};
+  const refs: Record<string, ColumnRef> = {};
+
+  for (const [colName, colRef] of Object.entries(input.columns)) {
+    // Set column identity on the ref
+    colRef._table = name;
+    colRef._column = colName;
+
+    colDefs[colName] = colRef.def;
+    refs[colName] = colRef;
+  }
+
+  const internal: InternalTableDef = {
+    name,
+    columns: colDefs,
+  };
+  if (input.primaryKey) internal.primaryKey = input.primaryKey;
+  if (input.foreignKeys) internal.foreignKeys = input.foreignKeys;
+  if (input.indexes) internal.indexes = input.indexes;
+  if (input.comment) internal.comment = input.comment;
+
+  return { _schema: internal, columns: refs };
+}

package/src/generate-ddl.ts

@@ -0,0 +1,196 @@
+/**
+ * Generate MySQL DDL from TableSchema array.
+ *
+ * Output format matches the style of 001_init.sql:
+ *   - Full CREATE TABLE with IF NOT EXISTS
+ *   - Backtick-quoted identifiers
+ *   - Consistent indentation (2 spaces)
+ *   - Constraints after column definitions
+ *   - ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+ */
+
+import type { ColumnDef } from './column-def';
+import { columnSqlType } from './column-def';
+import type { TableSchema, ColumnRef } from './table-def';
+
+// ── Internal helpers ──
+
+interface ColumnMeta {
+  name: string;
+  def: ColumnDef;
+}
+
+/** Resolve a ColumnRef or lazy ColumnRef getter */
+function resolveRef(ref: ColumnRef | (() => ColumnRef)): ColumnRef {
+  return typeof ref === 'function' ? ref() : ref;
+}
+
+/** Resolve column name from a ColumnRef */
+function colName(ref: ColumnRef): string {
+  return ref._column || '?';
+}
+
+/** Resolve multiple column refs to names */
+function colNames(refs: ColumnRef | ColumnRef[]): string[] {
+  return Array.isArray(refs) ? refs.map(colName) : [colName(refs)];
+}
+
+/** Safe access to `.default` — only some variants have it */
+function getDefault(def: ColumnDef): string | number | undefined {
+  if ('default' in def) return def.default as string | number | undefined;
+  return undefined;
+}
+
+function isIntColumn(def: ColumnDef): def is IntColumn {
+  const t = def.type;
+  return t === 'TINYINT' || t === 'SMALLINT' || t === 'INT' || t === 'BIGINT';
+}
+
+function renderDefault(def: ColumnDef): string {
+  const val = getDefault(def);
+  if (val === undefined) return '';
+
+  if (val === 'CURRENT_TIMESTAMP') return ' DEFAULT CURRENT_TIMESTAMP';
+
+  if (isIntColumn(def)) {
+    return ` DEFAULT ${val}`;
+  }
+
+  return ` DEFAULT '${val}'`;
+}
+
+function renderNullable(def: ColumnDef): string {
+  if ('autoIncrement' in def && def.autoIncrement) return ' NOT NULL';
+  return def.nullable === true ? '' : ' NOT NULL';
+}
+
+function renderExtra(def: ColumnDef): string {
+  if ('autoIncrement' in def && def.autoIncrement) return ' AUTO_INCREMENT';
+  return '';
+}
+
+type IntColumn = import('./column-def').IntColumn;
+
+function renderComment(def: ColumnDef): string {
+  return def.comment ? ` COMMENT '${def.comment.replace(/'/g, "\\'")}'` : '';
+}
+
+function renderColumnLine(col: ColumnMeta): string {
+  const { name, def } = col;
+  const sqlType = columnSqlType(def);
+  const nullable = renderNullable(def);
+  const default_ = renderDefault(def);
+  const extra = renderExtra(def);
+  const comment = renderComment(def);
+  return `  \`${name}\` ${sqlType}${nullable}${default_}${extra}${comment}`;
+}
+
+function renderPrimaryKey(schema: { _schema: InternalTableDef }, columns: ColumnMeta[]): string | null {
+  const pk = schema._schema.primaryKey;
+
+  if (pk) {
+    const names = Array.isArray(pk) ? pk.map(colName) : [colName(pk)];
+    return `  PRIMARY KEY (\`${names.join('`, `')}\`)`;
+  }
+
+  // Auto-detect autoIncrement column
+  const autoIncCol = columns.find(c => 'autoIncrement' in c.def && c.def.autoIncrement);
+  if (autoIncCol) {
+    return `  PRIMARY KEY (\`${autoIncCol.name}\`)`;
+  }
+
+  // Check for column-level primaryKey: true
+  const pkCols = columns.filter(c => 'primaryKey' in c.def && c.def.primaryKey);
+  if (pkCols.length > 0) {
+    return `  PRIMARY KEY (\`${pkCols.map(c => c.name).join('`, `')}\`)`;
+  }
+
+  return null;
+}
+
+interface InternalTableDef {
+  name: string;
+  primaryKey?: ColumnRef | ColumnRef[];
+  indexes?: import('./table-def').IndexDef[];
+  foreignKeys?: Record<string, import('./table-def').ForeignKey>;
+  comment?: string;
+}
+
+function renderInlineConstraints(schema: { _schema: InternalTableDef }, columns: ColumnMeta[]): string[] {
+  const lines: string[] = [];
+
+  // UNIQUE constraints declared inline on columns
+  for (const col of columns) {
+    if ('unique' in col.def && col.def.unique) {
+      lines.push(`  UNIQUE KEY \`uk_${schema._schema.name}_${col.name}\` (\`${col.name}\`)`);
+    }
+  }
+
+  // INDEX constraints declared inline on columns
+  for (const col of columns) {
+    if ('index' in col.def && col.def.index) {
+      lines.push(`  KEY \`idx_${schema._schema.name}_${col.name}\` (\`${col.name}\`)`);
+    }
+  }
+
+  // Explicit indexes from table.indexes
+  const indexes = schema._schema.indexes;
+  if (indexes) {
+    for (const idx of indexes) {
+      const cols = idx.columns.map(c => `\`${colName(c)}\``).join(', ');
+      const name = idx.name || `idx_${idx.columns.map(c => colName(c)).join('_')}`;
+      const keyword = idx.unique ? 'UNIQUE KEY' : 'KEY';
+      lines.push(`  ${keyword} \`${name}\` (${cols})`);
+    }
+  }
+
+  return lines;
+}
+
+// ── Public API ──
+
+/**
+ * Generate DDL for multiple tables.
+ * Returns a single SQL string with CREATE TABLE statements separated by blank lines.
+ */
+export function generateDdl(tables: TableSchema[]): string {
+  const parts: string[] = [];
+
+  for (const table of tables) {
+    const schema = table._schema;
+    const columns: ColumnMeta[] = Object.entries(schema.columns).map(([name, def]) => ({ name, def }));
+    const lines: string[] = [];
+
+    // 1. Column definitions
+    for (const col of columns) {
+      lines.push(renderColumnLine(col));
+    }
+
+    // 2. Primary key
+    const pkLine = renderPrimaryKey(table, columns);
+    if (pkLine) lines.push(pkLine);
+
+    // 3. Constraints + indexes
+    const constraintLines = renderInlineConstraints(table, columns);
+    lines.push(...constraintLines);
+
+    // 4. Foreign keys
+    if (schema.foreignKeys) {
+      for (const [name, fk] of Object.entries(schema.foreignKeys)) {
+        const cols = colNames(fk.columns).map(c => `\`${c}\``).join(', ');
+        const resolved = resolveRef(fk.ref);
+        const onDelete = fk.onDelete ? ` ON DELETE ${fk.onDelete}` : '';
+        lines.push(`  CONSTRAINT \`${name}\` FOREIGN KEY (${cols}) REFERENCES \`${resolved._table}\`(\`${resolved._column}\`)${onDelete}`);
+      }
+    }
+
+    // 5. Join with commas
+    const body = lines.join(',\n');
+
+    const comment = schema.comment ? `-- ${schema.comment}\n` : '';
+    const ddl = `${comment}CREATE TABLE IF NOT EXISTS \`${schema.name}\` (\n${body}\n) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;`;
+    parts.push(ddl);
+  }
+
+  return parts.join('\n\n');
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+export { MysqlType } from './mysql-type';
+export type { MysqlType as MysqlTypeT } from './mysql-type';
+
+export { columnSqlType } from './column-def';
+export type {
+  ColumnDef,
+  EnumShape,
+  IntColumn,
+  DecimalColumn,
+  StringColumn,
+  TextColumn,
+  DateColumn,
+  DateTimeColumn,
+} from './column-def';
+
+export { ColumnRef, col } from './column-ref';
+
+export type { ForeignKey, IndexDef, TableSchema } from './table-def';
+
+export { defineTable } from './define-table';
+export type { DefineTableInput } from './define-table';
+
+export { generateDdl } from './generate-ddl';
+
+export { scanTables } from './scan-tables';
+
+export { buildSchema } from './build';
+export type { BuildSchemaOptions } from './build';

package/src/mysql-type.ts

@@ -0,0 +1,63 @@
+/**
+ * MySQL data type constants and type guard.
+ *
+ * Usage:
+ *   import { MysqlType } from '@fastify-api/ts-mysql-ddl';
+ *   const col = { type: MysqlType.VARCHAR, length: 100 };
+ */
+
+export const MysqlType = {
+  // Integers
+  TINYINT:   'TINYINT',
+  SMALLINT:  'SMALLINT',
+  INT:       'INT',
+  BIGINT:    'BIGINT',
+
+  // Decimals
+  DECIMAL:   'DECIMAL',
+
+  // Strings
+  CHAR:      'CHAR',
+  VARCHAR:   'VARCHAR',
+
+  // Text
+  TEXT:      'TEXT',
+
+  // Date / Time
+  DATE:      'DATE',
+  DATETIME:  'DATETIME',
+  TIMESTAMP: 'TIMESTAMP',
+} as const;
+
+export type MysqlType = (typeof MysqlType)[keyof typeof MysqlType];
+
+/** Integer type family guard */
+export type IntMysqlType =
+  | typeof MysqlType.TINYINT
+  | typeof MysqlType.SMALLINT
+  | typeof MysqlType.INT
+  | typeof MysqlType.BIGINT;
+
+/** String type family guard */
+export type StringMysqlType =
+  | typeof MysqlType.CHAR
+  | typeof MysqlType.VARCHAR;
+
+/** Date/time type family guard */
+export type DateTimeMysqlType =
+  | typeof MysqlType.DATE
+  | typeof MysqlType.DATETIME
+  | typeof MysqlType.TIMESTAMP;
+
+export function isIntType(t: MysqlType): t is IntMysqlType {
+  return t === MysqlType.TINYINT || t === MysqlType.SMALLINT
+      || t === MysqlType.INT || t === MysqlType.BIGINT;
+}
+
+export function isStringType(t: MysqlType): t is StringMysqlType {
+  return t === MysqlType.CHAR || t === MysqlType.VARCHAR;
+}
+
+export function isDateTimeType(t: MysqlType): t is DateTimeMysqlType {
+  return t === MysqlType.DATE || t === MysqlType.DATETIME || t === MysqlType.TIMESTAMP;
+}

package/src/scan-tables.ts

@@ -0,0 +1,81 @@
+/**
+ * Auto-discover table definitions from a directory of *.table.ts files.
+ *
+ * Each file exports at minimum `columns` (Record<string, ColumnRef>).
+ * Optional exports: `indexes`, `foreignKeys`, `primaryKey`, `comment`.
+ *
+ * Two-phase initialization ensures FK refs between tables resolve correctly
+ * regardless of file processing order:
+ *   Phase 1 — set _table/_column on all ColumnRefs
+ *   Phase 2 — build full TableSchema with FKs, indexes, etc.
+ *
+ * Usage:
+ *   const tables = await scanTables('./schema');
+ *   const sql = generateDdl(tables);
+ *   console.log(sql);
+ */
+
+import { readdirSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { defineTable } from './define-table';
+import { ColumnRef } from './column-ref';
+import type { ForeignKey, IndexDef, TableSchema } from './table-def';
+
+/** Module shape expected from each *.table.ts file */
+interface TableModule {
+  columns: Record<string, ColumnRef>;
+  primaryKey?: ColumnRef | ColumnRef[];
+  foreignKeys?: Record<string, ForeignKey>;
+  indexes?: IndexDef[];
+  comment?: string;
+}
+
+/**
+ * Scan a directory for *.table.ts files, import each, and return TableSchema[].
+ * Table name is derived from filename: "order.table.ts" → "order".
+ */
+export async function scanTables(dir: string): Promise<TableSchema[]> {
+  const absDir = path.resolve(dir);
+
+  // 1. Discover files
+  const files = readdirSync(absDir)
+    .filter((f: string) => f.endsWith('.table.ts'))
+    .sort();  // deterministic order
+
+  if (files.length === 0) {
+    throw new Error(`No *.table.ts files found in ${absDir}`);
+  }
+
+  // 2. Import all modules
+  const entries: { name: string; mod: TableModule }[] = [];
+
+  for (const file of files) {
+    const modulePath = path.join(absDir, file);
+    const tableName = file.replace(/\.table\.ts$/, '');
+    const mod: TableModule = await import(pathToFileURL(modulePath).href);
+
+    if (!mod.columns) {
+      console.warn(`Skipping ${file}: no 'columns' export`);
+      continue;
+    }
+
+    entries.push({ name: tableName, mod });
+  }
+
+  // 3. Phase 1 — set column identity on all refs
+  for (const { name, mod } of entries) {
+    for (const [colName, ref] of Object.entries(mod.columns)) {
+      ref._table = name;
+      ref._column = colName;
+    }
+  }
+
+  // 4. Phase 2 — build full schemas
+  const schemas: TableSchema[] = [];
+  for (const { name, mod } of entries) {
+    schemas.push(defineTable(name, mod));
+  }
+
+  return schemas;
+}

package/src/table-def.ts

@@ -0,0 +1,50 @@
+/**
+ * Table definition interfaces.
+ *
+ * Index and FK columns use ColumnRef for compile-time checking:
+ *   indexes: [{ columns: [columns.status, columns.deleted] }]
+ *   foreignKeys: { fk_x: { columns: [columns.mer_id], ref: merchant.columns.id } }
+ */
+
+import type { ColumnDef } from './column-def';
+import { ColumnRef } from './column-ref';
+
+export { ColumnRef, col } from './column-ref';
+
+// ── Index ──
+
+export interface IndexDef {
+  columns: ColumnRef[];
+  name?: string;
+  unique?: boolean;
+}
+
+// ── Foreign key ──
+
+export interface ForeignKey {
+  /** Local column(s) */
+  columns: ColumnRef | ColumnRef[];
+  /** Referenced column — direct ref or lazy for circular deps */
+  ref: ColumnRef | (() => ColumnRef);
+  onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
+}
+
+// ── Table schema (returned by defineTable) ──
+
+export interface TableSchema {
+  /** Internal table definition for DDL generation */
+  readonly _schema: InternalTableDef;
+  /** Column references for FK/index declarations, e.g. merchant.columns.id */
+  readonly columns: Record<string, ColumnRef>;
+}
+
+/** @internal — not exported directly */
+export interface InternalTableDef {
+  name: string;
+  /** Raw column definitions keyed by column name */
+  columns: Record<string, ColumnDef>;
+  primaryKey?: ColumnRef | ColumnRef[];
+  foreignKeys?: Record<string, ForeignKey>;
+  indexes?: IndexDef[];
+  comment?: string;
+}