@zintrust/core 0.1.27 → 0.1.28

package/src/orm/Schema.ts

@@ -0,0 +1,403 @@
+/**
+ * Schema - Column definition and type system
+ * Defines database columns with type safety
+ */
+
+export type ColumnType =
+  | 'string'
+  | 'integer'
+  | 'boolean'
+  | 'date'
+  | 'datetime'
+  | 'json'
+  | 'text'
+  | 'timestamp'
+  | 'decimal'
+  | 'uuid'
+  | 'float'
+  | 'double'
+  | 'binary'
+  | 'enum'
+  | 'bigInteger'
+  | 'smallInteger'
+  | 'tinyInteger'
+  | 'mediumInteger'
+  | 'time'
+  | 'year'
+  | 'char'
+  | 'longText'
+  | 'mediumText'
+  | 'tinyText'
+  | 'blob'
+  | 'mediumBlob'
+  | 'longBlob'
+  | 'tinyBlob'
+  | 'ipAddress'
+  | 'macAddress'
+  | 'geometry'
+  | 'point'
+  | 'lineString'
+  | 'polygon'
+  | 'geometryCollection'
+  | 'multiPoint'
+  | 'multiLineString'
+  | 'multiPolygon';
+
+export interface ColumnDefinition {
+  name: string;
+  type: ColumnType;
+  nullable: boolean;
+  default?: unknown;
+  unique: boolean;
+  primary: boolean;
+  index: boolean;
+  autoIncrement?: boolean;
+  unsigned?: boolean;
+  comment?: string;
+  references?: string;
+  on?: string;
+  onDelete?: string;
+  onUpdate?: string;
+  renameTo?: string;
+  change?: boolean;
+  drop?: boolean;
+  after?: string;
+  first?: boolean;
+  charset?: string;
+  collation?: string;
+  length?: number;
+  precision?: number;
+  scale?: number;
+  values?: string[];
+}
+
+export interface IColumn {
+  nullable(): IColumn;
+  default(value: unknown): IColumn;
+  unique(): IColumn;
+  primary(): IColumn;
+  index(): IColumn;
+  autoIncrement(): IColumn;
+  unsigned(): IColumn;
+  comment(text: string): IColumn;
+  references(column: string): IColumn;
+  on(table: string): IColumn;
+  onDelete(action: string): IColumn;
+  onUpdate(action: string): IColumn;
+  renameTo(name: string): IColumn;
+  change(): IColumn;
+  drop(): IColumn;
+  after(column: string): IColumn;
+  first(): IColumn;
+  charset(value: string): IColumn;
+  collation(value: string): IColumn;
+  length(value: number): IColumn;
+  precision(value: number): IColumn;
+  scale(value: number): IColumn;
+  values(value: string[]): IColumn;
+  getDefinition(): ColumnDefinition;
+}
+
+interface DefinitionBuilder {
+  name: string;
+  type: ColumnType;
+  nullable: boolean;
+  unique: boolean;
+  primary: boolean;
+  index: boolean;
+}
+
+const definitionBuilder = (name: string, type: ColumnType): DefinitionBuilder => {
+  return {
+    name,
+    type,
+    nullable: false,
+    unique: false,
+    primary: false,
+    index: false,
+  };
+};
+
+type ColumnBooleanKey =
+  | 'nullable'
+  | 'unique'
+  | 'primary'
+  | 'index'
+  | 'autoIncrement'
+  | 'unsigned'
+  | 'change'
+  | 'drop'
+  | 'first';
+
+const createColumnFromDefinition = (definition: ColumnDefinition): IColumn => {
+  const column = {} as IColumn;
+
+  const enable = <K extends ColumnBooleanKey>(key: K): (() => IColumn) => {
+    return () => {
+      definition[key] = true;
+      return column;
+    };
+  };
+
+  const assign = <K extends keyof ColumnDefinition>(
+    key: K
+  ): ((value: ColumnDefinition[K]) => IColumn) => {
+    return (value: ColumnDefinition[K]) => {
+      definition[key] = value;
+      return column;
+    };
+  };
+
+  column.nullable = enable('nullable');
+  column.unique = enable('unique');
+  column.primary = enable('primary');
+  column.index = enable('index');
+  column.autoIncrement = enable('autoIncrement');
+  column.unsigned = enable('unsigned');
+  column.change = enable('change');
+  column.drop = enable('drop');
+  column.first = enable('first');
+
+  column.default = assign('default') as (value: unknown) => IColumn;
+  column.comment = assign('comment') as (text: string) => IColumn;
+  column.references = assign('references') as (column: string) => IColumn;
+  column.on = assign('on') as (table: string) => IColumn;
+  column.onDelete = assign('onDelete') as (action: string) => IColumn;
+  column.onUpdate = assign('onUpdate') as (action: string) => IColumn;
+  column.renameTo = assign('renameTo') as (name: string) => IColumn;
+  column.after = assign('after') as (column: string) => IColumn;
+  column.charset = assign('charset') as (value: string) => IColumn;
+  column.collation = assign('collation') as (value: string) => IColumn;
+  column.length = assign('length') as (value: number) => IColumn;
+  column.precision = assign('precision') as (value: number) => IColumn;
+  column.scale = assign('scale') as (value: number) => IColumn;
+  column.values = assign('values') as (value: string[]) => IColumn;
+
+  column.getDefinition = (): ColumnDefinition => ({ ...definition });
+
+  return column;
+};
+
+/**
+ * Column - Column definition builder
+ * Sealed namespace object following Pattern 2
+ *
+ * @see FRAMEWORK_REFACTOR_FUNCTION_PATTERN.md for Pattern 2 details
+ */
+export const Column = Object.freeze({
+  /**
+   * Create a new column instance
+   */
+  create(name: string, type: ColumnType): IColumn {
+    const definition: ColumnDefinition = definitionBuilder(name, type);
+    return createColumnFromDefinition(definition);
+  },
+});
+
+export interface ISchema {
+  string(name: string, length?: number): IColumn;
+  integer(name: string): IColumn;
+  boolean(name: string): IColumn;
+  date(name: string): IColumn;
+  datetime(name: string): IColumn;
+  json(name: string): IColumn;
+  text(name: string): IColumn;
+  timestamp(name: string): IColumn;
+  decimal(name: string, precision?: number, scale?: number): IColumn;
+  uuid(name: string): IColumn;
+  float(name: string): IColumn;
+  double(name: string): IColumn;
+  binary(name: string): IColumn;
+  enum(name: string, values: string[]): IColumn;
+  bigInteger(name: string): IColumn;
+  smallInteger(name: string): IColumn;
+  tinyInteger(name: string): IColumn;
+  mediumInteger(name: string): IColumn;
+  time(name: string): IColumn;
+  year(name: string): IColumn;
+  char(name: string, length?: number): IColumn;
+  longText(name: string): IColumn;
+  mediumText(name: string): IColumn;
+  tinyText(name: string): IColumn;
+  blob(name: string): IColumn;
+  mediumBlob(name: string): IColumn;
+  longBlob(name: string): IColumn;
+  tinyBlob(name: string): IColumn;
+  ipAddress(name: string): IColumn;
+  macAddress(name: string): IColumn;
+  geometry(name: string): IColumn;
+  point(name: string): IColumn;
+  lineString(name: string): IColumn;
+  polygon(name: string): IColumn;
+  geometryCollection(name: string): IColumn;
+  multiPoint(name: string): IColumn;
+  multiLineString(name: string): IColumn;
+  multiPolygon(name: string): IColumn;
+  increments(name: string): IColumn;
+  bigIncrements(name: string): IColumn;
+  timestamps(): void;
+  softDeletes(): void;
+  getColumns(): Map<string, IColumn>;
+  getTable(): string;
+}
+
+/**
+ * Schema - Table definition builder
+ * Refactored to Functional Object pattern
+ */
+/**
+ * Create a column proxy to track definition updates
+ */
+const createColumnProxy = (
+  name: string,
+  type: ColumnType,
+  columns: Map<string, IColumn>
+): IColumn => {
+  const column = Column.create(name, type);
+  columns.set(name, column);
+
+  return column;
+};
+
+type SimpleSchemaColumnType =
+  | 'integer'
+  | 'boolean'
+  | 'date'
+  | 'datetime'
+  | 'json'
+  | 'text'
+  | 'timestamp'
+  | 'uuid'
+  | 'float'
+  | 'double'
+  | 'binary'
+  | 'bigInteger'
+  | 'smallInteger'
+  | 'tinyInteger'
+  | 'mediumInteger'
+  | 'time'
+  | 'year'
+  | 'longText'
+  | 'mediumText'
+  | 'tinyText'
+  | 'blob'
+  | 'mediumBlob'
+  | 'longBlob'
+  | 'tinyBlob'
+  | 'ipAddress'
+  | 'macAddress'
+  | 'geometry'
+  | 'point'
+  | 'lineString'
+  | 'polygon'
+  | 'geometryCollection'
+  | 'multiPoint'
+  | 'multiLineString'
+  | 'multiPolygon';
+
+const SIMPLE_SCHEMA_COLUMN_TYPES: readonly SimpleSchemaColumnType[] = [
+  'integer',
+  'boolean',
+  'date',
+  'datetime',
+  'json',
+  'text',
+  'timestamp',
+  'uuid',
+  'float',
+  'double',
+  'binary',
+  'bigInteger',
+  'smallInteger',
+  'tinyInteger',
+  'mediumInteger',
+  'time',
+  'year',
+  'longText',
+  'mediumText',
+  'tinyText',
+  'blob',
+  'mediumBlob',
+  'longBlob',
+  'tinyBlob',
+  'ipAddress',
+  'macAddress',
+  'geometry',
+  'point',
+  'lineString',
+  'polygon',
+  'geometryCollection',
+  'multiPoint',
+  'multiLineString',
+  'multiPolygon',
+];
+
+const setSchemaMethod = <K extends keyof ISchema>(
+  target: Partial<ISchema>,
+  key: K,
+  fn: ISchema[K]
+): void => {
+  (target as Record<string, unknown>)[key as string] = fn as unknown;
+};
+
+export const Schema = Object.freeze({
+  /**
+   * Create a new schema instance
+   */
+  create(table: string): ISchema {
+    const columns = new Map<string, IColumn>();
+
+    const schema: Partial<ISchema> = {};
+
+    setSchemaMethod(schema, 'string', (name: string, length?: number) => {
+      const col = createColumnProxy(name, 'string', columns);
+      if (length !== undefined) col.length(length);
+      return col;
+    });
+
+    setSchemaMethod(schema, 'decimal', (name: string, precision?: number, scale?: number) => {
+      const col = createColumnProxy(name, 'decimal', columns);
+      if (precision !== undefined) col.precision(precision);
+      if (scale !== undefined) col.scale(scale);
+      return col;
+    });
+
+    setSchemaMethod(schema, 'enum', (name: string, values: string[]) => {
+      const col = createColumnProxy(name, 'enum', columns);
+      col.values(values);
+      return col;
+    });
+
+    setSchemaMethod(schema, 'char', (name: string, length?: number) => {
+      const col = createColumnProxy(name, 'char', columns);
+      if (length !== undefined) col.length(length);
+      return col;
+    });
+
+    for (const type of SIMPLE_SCHEMA_COLUMN_TYPES) {
+      setSchemaMethod(schema, type, (name: string) => createColumnProxy(name, type, columns));
+    }
+
+    setSchemaMethod(schema, 'increments', (name: string) =>
+      createColumnProxy(name, 'integer', columns).primary().autoIncrement()
+    );
+
+    setSchemaMethod(schema, 'bigIncrements', (name: string) =>
+      createColumnProxy(name, 'bigInteger', columns).primary().autoIncrement()
+    );
+
+    setSchemaMethod(schema, 'timestamps', () => {
+      createColumnProxy('created_at', 'timestamp', columns).nullable();
+      createColumnProxy('updated_at', 'timestamp', columns).nullable();
+    });
+
+    setSchemaMethod(schema, 'softDeletes', () => {
+      createColumnProxy('deleted_at', 'timestamp', columns).nullable();
+    });
+
+    setSchemaMethod(schema, 'getColumns', () => columns);
+    setSchemaMethod(schema, 'getTable', () => table);
+
+    return schema as ISchema;
+  },
+});

package/src/orm/SchemaCompiler.ts

@@ -0,0 +1,160 @@
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import type { IDatabase } from '@orm/Database';
+import type { ColumnDefinition, ISchema } from '@orm/Schema';
+
+const IDENT_RE = /^[A-Za-z_]\w*$/;
+const INT_TYPES = new Set<ColumnDefinition['type']>([
+  'integer',
+  'smallInteger',
+  'tinyInteger',
+  'mediumInteger',
+]);
+
+function assertIdentifier(label: string, value: string): void {
+  if (!IDENT_RE.test(value)) {
+    throw ErrorFactory.createValidationError(`Invalid ${label} identifier: ${value}`);
+  }
+}
+
+function quoteIdent(driver: string, ident: string): string {
+  assertIdentifier('SQL', ident);
+
+  // MySQL uses backticks; Postgres/SQLite accept double-quotes.
+  if (driver === 'mysql') return `\`${ident}\``;
+  return `"${ident}"`;
+}
+
+function getAutoIncrementSql(driver: string, col: string, type: string): string | null {
+  const isSqlite = driver === 'sqlite' || driver === 'd1' || driver === 'd1-remote';
+
+  if (isSqlite) {
+    return `${col} INTEGER PRIMARY KEY AUTOINCREMENT`;
+  }
+  if (driver === 'postgresql') {
+    return `${col} ${type === 'bigInteger' ? 'BIGSERIAL' : 'SERIAL'} PRIMARY KEY`;
+  }
+  if (driver === 'mysql') {
+    const base = type === 'bigInteger' ? 'BIGINT' : 'INT';
+    return `${col} ${base} AUTO_INCREMENT PRIMARY KEY`;
+  }
+  return null;
+}
+
+function getStringTypeSql(driver: string, def: ColumnDefinition): string {
+  const isSqlite = driver === 'sqlite' || driver === 'd1' || driver === 'd1-remote';
+  const len = typeof def.length === 'number' && Number.isFinite(def.length) ? def.length : 255;
+  return isSqlite ? 'TEXT' : `VARCHAR(${len})`;
+}
+
+function getDecimalTypeSql(def: ColumnDefinition): string {
+  const p = typeof def.precision === 'number' ? def.precision : 10;
+  const s = typeof def.scale === 'number' ? def.scale : 2;
+  return `DECIMAL(${p},${s})`;
+}
+
+function getDateTimeTypeSql(driver: string): string {
+  if (driver === 'mysql') return 'DATETIME';
+  if (driver === 'postgresql') return 'TIMESTAMP';
+  return 'TEXT';
+}
+
+function getIntegerTypeSql(driver: string, type: ColumnDefinition['type']): string | null {
+  if (INT_TYPES.has(type)) return driver === 'mysql' ? 'INT' : 'INTEGER';
+  if (type === 'bigInteger') return 'BIGINT';
+  return null;
+}
+
+function getSpecialTypeSql(driver: string, type: ColumnDefinition['type']): string | null {
+  if (type === 'boolean') return driver === 'mysql' ? 'TINYINT(1)' : 'BOOLEAN';
+  if (type === 'json') return driver === 'postgresql' ? 'JSONB' : 'TEXT';
+  if (type === 'uuid') return driver === 'postgresql' ? 'UUID' : 'TEXT';
+  return null;
+}
+
+function getColumnTypeSql(driver: string, def: ColumnDefinition): string {
+  if (def.type === 'string' || def.type === 'char') return getStringTypeSql(driver, def);
+  if (def.type === 'decimal') return getDecimalTypeSql(def);
+  if (def.type === 'datetime' || def.type === 'timestamp') return getDateTimeTypeSql(driver);
+
+  const intSql = getIntegerTypeSql(driver, def.type);
+  if (intSql !== null) return intSql;
+
+  const specialSql = getSpecialTypeSql(driver, def.type);
+  if (specialSql !== null) return specialSql;
+
+  return 'TEXT';
+}
+
+function getDefaultValueSql(table: string, def: ColumnDefinition): string | null {
+  if (def.default === undefined) return null;
+
+  const dv = def.default;
+  if (dv === null) return 'DEFAULT NULL';
+  if (typeof dv === 'number' && Number.isFinite(dv)) return `DEFAULT ${dv}`;
+  if (typeof dv === 'boolean') return `DEFAULT ${dv ? 1 : 0}`;
+  if (typeof dv === 'string') {
+    const escaped = dv.replaceAll("'", "''");
+    return `DEFAULT '${escaped}'`;
+  }
+  throw ErrorFactory.createValidationError(`Unsupported default type for ${table}.${def.name}`);
+}
+
+function columnSql(driver: string, table: string, def: ColumnDefinition): string {
+  assertIdentifier('table', table);
+  assertIdentifier('column', def.name);
+
+  const col = quoteIdent(driver, def.name);
+  const isPrimary = def.primary === true;
+
+  if (def.autoIncrement === true && isPrimary) {
+    const autoInc = getAutoIncrementSql(driver, col, def.type);
+    if (autoInc !== null) return autoInc;
+  }
+
+  const parts: string[] = [`${col} ${getColumnTypeSql(driver, def)}`];
+
+  if (def.nullable !== true) parts.push('NOT NULL');
+  if (def.unique === true) parts.push('UNIQUE');
+  if (isPrimary) parts.push('PRIMARY KEY');
+
+  const defaultVal = getDefaultValueSql(table, def);
+  if (defaultVal !== null) parts.push(defaultVal);
+
+  return parts.join(' ');
+}
+
+function buildCreateTableSql(driver: string, schema: ISchema, ifNotExists: boolean): string {
+  const table = schema.getTable();
+  assertIdentifier('table', table);
+
+  const tableSql = quoteIdent(driver, table);
+
+  const cols = Array.from(schema.getColumns().values()).map((c) => c.getDefinition());
+  if (cols.length === 0) {
+    throw ErrorFactory.createValidationError(`Schema for table '${table}' has no columns`);
+  }
+
+  const columnLines = cols.map((d) => `  ${columnSql(driver, table, d)}`);
+
+  const ine = ifNotExists ? 'IF NOT EXISTS ' : '';
+  return `CREATE TABLE ${ine}${tableSql} (\n${columnLines.join(',\n')}\n)`;
+}
+
+export const SchemaCompiler = Object.freeze({
+  async createTable(
+    db: IDatabase,
+    schema: ISchema,
+    opts?: { ifNotExists?: boolean }
+  ): Promise<void> {
+    const driver = db.getType();
+    const sql = buildCreateTableSql(driver, schema, opts?.ifNotExists !== false);
+    await db.query(sql);
+  },
+
+  async dropTable(db: IDatabase, table: string): Promise<void> {
+    const driver = db.getType();
+    assertIdentifier('table', table);
+    const tableSql = quoteIdent(driver, table);
+    await db.query(`DROP TABLE IF EXISTS ${tableSql}`);
+  },
+});

package/src/orm/adapters/D1Adapter.ts

@@ -0,0 +1,149 @@
+/**
+ * Cloudflare D1 Database Adapter
+ */
+
+import { Cloudflare } from '@config/cloudflare';
+import { FeatureFlags } from '@config/features';
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { AdaptersEnum, type SupportedDriver } from '@migrations/enum';
+import type {
+  DatabaseConfig,
+  ID1Database,
+  IDatabaseAdapter,
+  QueryResult,
+} from '@orm/DatabaseAdapter';
+import { QueryBuilder } from '@orm/QueryBuilder';
+
+/**
+ * Get D1 binding from config or global environment
+ */
+function getD1Binding(_config: DatabaseConfig): ID1Database | null {
+  return Cloudflare.getD1Binding(_config);
+}
+
+/**
+ * D1 adapter implementation
+ */
+export const D1Adapter = Object.freeze({
+  /**
+   * Create a new D1 adapter instance
+   */
+  // eslint-disable-next-line max-lines-per-function
+  create(_config: DatabaseConfig): IDatabaseAdapter {
+    let connected = false;
+
+    return {
+      // eslint-disable-next-line @typescript-eslint/require-await
+      async connect(): Promise<void> {
+        connected = true;
+        Logger.info('✓ D1 connected');
+      },
+
+      // eslint-disable-next-line @typescript-eslint/require-await
+      async disconnect(): Promise<void> {
+        connected = false;
+        Logger.info('✓ D1 disconnected');
+      },
+
+      async query(sql: string, parameters: unknown[]): Promise<QueryResult> {
+        if (!connected) throw ErrorFactory.createConnectionError('Database not connected');
+
+        const db = getD1Binding(_config);
+        if (db === null) {
+          throw ErrorFactory.createConfigError('D1 database binding not found');
+        }
+
+        try {
+          const stmt = db.prepare(sql);
+          const result = await stmt.bind(...parameters).all();
+          const rows = (result.results as Record<string, unknown>[]) ?? [];
+          return {
+            rows,
+            rowCount: rows.length,
+          };
+        } catch (error) {
+          throw ErrorFactory.createTryCatchError(`D1 query failed: ${sql}`, error);
+        }
+      },
+
+      async queryOne(sql: string, parameters: unknown[]): Promise<Record<string, unknown> | null> {
+        if (!connected) throw ErrorFactory.createConnectionError('Database not connected');
+
+        const db = getD1Binding(_config);
+        if (db === null) {
+          throw ErrorFactory.createConfigError('D1 database binding not found');
+        }
+
+        try {
+          const stmt = db.prepare(sql);
+          const result = await stmt.bind(...parameters).first<Record<string, unknown>>();
+          return result ?? null;
+        } catch (error) {
+          throw ErrorFactory.createTryCatchError(`D1 queryOne failed: ${sql}`, error);
+        }
+      },
+
+      async ping(): Promise<void> {
+        if (!connected) throw ErrorFactory.createConnectionError('Database not connected');
+
+        const db = getD1Binding(_config);
+        if (db === null) {
+          throw ErrorFactory.createConfigError('D1 database binding not found');
+        }
+
+        try {
+          // Use a minimal, side-effect-free query.
+          await db.prepare(QueryBuilder.create('').select('1').toSQL()).bind().first();
+        } catch (error) {
+          throw ErrorFactory.createTryCatchError('D1 ping failed', error);
+        }
+      },
+
+      async transaction<T>(callback: (adapter: IDatabaseAdapter) => Promise<T>): Promise<T> {
+        if (!connected) throw ErrorFactory.createConnectionError('Database not connected');
+        try {
+          const result = await callback(this);
+          return result;
+        } catch (error) {
+          throw ErrorFactory.createTryCatchError('Transaction failed', error);
+        }
+      },
+
+      getType(): SupportedDriver {
+        return AdaptersEnum.d1;
+      },
+      isConnected(): boolean {
+        return connected;
+      },
+      async rawQuery<T = unknown>(sql: string, parameters?: unknown[]): Promise<T[]> {
+        if (!FeatureFlags.isRawQueryEnabled()) {
+          throw ErrorFactory.createConfigError('Raw SQL queries are disabled');
+        }
+
+        if (!connected) {
+          throw ErrorFactory.createConnectionError('Database not connected');
+        }
+
+        const db = getD1Binding(_config);
+        if (db === null) {
+          throw ErrorFactory.createConfigError('D1 database binding not found');
+        }
+
+        try {
+          Logger.warn(`Raw SQL Query executed: ${sql}`, { parameters });
+          const stmt = db.prepare(sql);
+          const result = await stmt.bind(...(parameters ?? [])).all<T>();
+          return (result.results as T[]) ?? [];
+        } catch (error) {
+          throw ErrorFactory.createTryCatchError(`Raw SQL query failed: ${sql}`, error);
+        }
+      },
+      getPlaceholder(_index: number): string {
+        return '?';
+      },
+    };
+  },
+});
+
+export default D1Adapter;