tina4-nodejs 3.0.0-rc.2

package/packages/orm/src/sqlTranslation.ts

@@ -0,0 +1,272 @@
+/**
+ * Tina4 SQL Translation — Cross-engine SQL translator.
+ *
+ * Translates SQL dialect differences between engines so that application
+ * code can use a single SQL style and have it adapted at runtime.
+ *
+ *   import { SQLTranslator } from "@tina4/orm";
+ *
+ *   // Firebird: LIMIT/OFFSET → ROWS X TO Y
+ *   SQLTranslator.limitToRows("SELECT * FROM users LIMIT 10 OFFSET 5");
+ *   // → "SELECT * FROM users ROWS 6 TO 15"
+ *
+ *   // MSSQL: LIMIT → TOP N
+ *   SQLTranslator.limitToTop("SELECT * FROM users LIMIT 10");
+ *   // → "SELECT TOP 10 * FROM users"
+ *
+ * Also includes a query cache with TTL support.
+ */
+
+// ── SQL Translator ───────────────────────────────────────────
+
+export class SQLTranslator {
+  /**
+   * Convert LIMIT/OFFSET to Firebird ROWS...TO syntax.
+   *
+   * LIMIT 10 OFFSET 5  →  ROWS 6 TO 15
+   * LIMIT 10           →  ROWS 1 TO 10
+   */
+  static limitToRows(sql: string): string {
+    // Match LIMIT n OFFSET m at end of statement
+    const limitOffset = /\bLIMIT\s+(\d+)\s+OFFSET\s+(\d+)\s*$/i;
+    let m = sql.match(limitOffset);
+    if (m) {
+      const limit = parseInt(m[1], 10);
+      const offset = parseInt(m[2], 10);
+      const start = offset + 1;
+      const end = offset + limit;
+      return sql.slice(0, m.index) + `ROWS ${start} TO ${end}`;
+    }
+
+    // Match LIMIT n at end of statement
+    const limitOnly = /\bLIMIT\s+(\d+)\s*$/i;
+    m = sql.match(limitOnly);
+    if (m) {
+      const limit = parseInt(m[1], 10);
+      return sql.slice(0, m.index) + `ROWS 1 TO ${limit}`;
+    }
+
+    return sql;
+  }
+
+  /**
+   * Convert LIMIT to MSSQL TOP syntax.
+   *
+   * SELECT ... LIMIT 10  →  SELECT TOP 10 ...
+   * Does NOT convert if OFFSET is present (TOP doesn't support it).
+   */
+  static limitToTop(sql: string): string {
+    const limitOnly = /\bLIMIT\s+(\d+)\s*$/i;
+    const m = sql.match(limitOnly);
+    if (m && !/\bOFFSET\b/i.test(sql)) {
+      const limit = parseInt(m[1], 10);
+      const body = sql.slice(0, m.index).trim();
+      return body.replace(/^(SELECT)\b/i, `$1 TOP ${limit}`);
+    }
+    return sql;
+  }
+
+  /**
+   * Convert || concatenation to CONCAT() for MySQL/MSSQL.
+   *
+   * 'a' || 'b' || 'c'  →  CONCAT('a', 'b', 'c')
+   */
+  static concatPipesToFunc(sql: string): string {
+    if (!sql.includes("||")) return sql;
+    const parts = sql.split("||");
+    if (parts.length > 1) {
+      return "CONCAT(" + parts.map((p) => p.trim()).join(", ") + ")";
+    }
+    return sql;
+  }
+
+  /**
+   * Convert TRUE/FALSE to 1/0 for engines without boolean type (Firebird).
+   */
+  static booleanToInt(sql: string): string {
+    sql = sql.replace(/\bTRUE\b/gi, "1");
+    sql = sql.replace(/\bFALSE\b/gi, "0");
+    return sql;
+  }
+
+  /**
+   * Convert ILIKE to LOWER() LIKE LOWER() for engines without ILIKE.
+   */
+  static ilikeToLike(sql: string): string {
+    return sql.replace(
+      /(\S+)\s+ILIKE\s+(\S+)/gi,
+      (_match, col: string, val: string) => `LOWER(${col.trim()}) LIKE LOWER(${val.trim()})`,
+    );
+  }
+
+  /**
+   * Translate AUTOINCREMENT across engines in DDL.
+   */
+  static autoIncrementSyntax(sql: string, engine: string): string {
+    switch (engine) {
+      case "mysql":
+        return sql.replace(/AUTOINCREMENT/gi, "AUTO_INCREMENT");
+      case "postgresql":
+        return sql.replace(
+          /INTEGER\s+PRIMARY\s+KEY\s+AUTOINCREMENT/gi,
+          "SERIAL PRIMARY KEY",
+        );
+      case "mssql":
+        return sql.replace(/AUTOINCREMENT/gi, "IDENTITY(1,1)");
+      case "firebird":
+        return sql.replace(/\s*AUTOINCREMENT\b/gi, "");
+      default:
+        return sql;
+    }
+  }
+
+  /**
+   * Convert ? placeholders to engine-specific style.
+   *
+   * ? → %s (MySQL, PostgreSQL)
+   * ? → :1, :2, :3 (Oracle, Firebird)
+   */
+  static placeholderStyle(sql: string, style: string): string {
+    if (style === "%s") {
+      return sql.replace(/\?/g, "%s");
+    }
+    if (style.startsWith(":")) {
+      let count = 0;
+      return sql.replace(/\?/g, () => {
+        count++;
+        return `:${count}`;
+      });
+    }
+    return sql;
+  }
+
+  /**
+   * Detect and strip RETURNING clause from INSERT/UPDATE statements.
+   * Returns the cleaned SQL and the list of RETURNING columns.
+   *
+   * "INSERT INTO t (x) VALUES (1) RETURNING id, name"
+   * → { sql: "INSERT INTO t (x) VALUES (1)", columns: ["id", "name"] }
+   */
+  static parseReturning(sql: string): { sql: string; columns: string[] } {
+    const m = sql.match(/\bRETURNING\s+(.+)$/i);
+    if (!m) return { sql, columns: [] };
+    const columns = m[1].split(",").map((c) => c.trim());
+    return {
+      sql: sql.slice(0, m.index!).trim(),
+      columns,
+    };
+  }
+}
+
+// ── Query Cache ──────────────────────────────────────────────
+
+interface CacheEntry<T> {
+  value: T;
+  expiresAt: number;
+}
+
+/**
+ * Simple in-memory query cache with TTL support.
+ */
+export class QueryCache {
+  private store = new Map<string, CacheEntry<unknown>>();
+  private defaultTtl: number;
+  private maxSize: number;
+
+  constructor(options?: { defaultTtl?: number; maxSize?: number }) {
+    this.defaultTtl = options?.defaultTtl ?? 60;
+    this.maxSize = options?.maxSize ?? 1000;
+  }
+
+  /**
+   * Generate a cache key from a SQL query and params.
+   */
+  static queryKey(sql: string, params?: unknown[]): string {
+    const paramStr = params ? JSON.stringify(params) : "";
+    // Simple hash via string combination
+    return `query:${sql}:${paramStr}`;
+  }
+
+  /**
+   * Get a cached value. Returns undefined if expired or missing.
+   */
+  get<T>(key: string): T | undefined {
+    const entry = this.store.get(key) as CacheEntry<T> | undefined;
+    if (!entry) return undefined;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  /**
+   * Set a cached value with optional TTL (seconds).
+   */
+  set<T>(key: string, value: T, ttl?: number): void {
+    // Evict oldest entry if at max size
+    if (this.store.size >= this.maxSize) {
+      const firstKey = this.store.keys().next().value;
+      if (firstKey !== undefined) this.store.delete(firstKey);
+    }
+
+    this.store.set(key, {
+      value,
+      expiresAt: Date.now() + (ttl ?? this.defaultTtl) * 1000,
+    });
+  }
+
+  /**
+   * Check if a key exists and is not expired.
+   */
+  has(key: string): boolean {
+    return this.get(key) !== undefined;
+  }
+
+  /**
+   * Delete a specific key.
+   */
+  delete(key: string): boolean {
+    return this.store.delete(key);
+  }
+
+  /**
+   * Remove all expired entries.
+   */
+  sweep(): number {
+    const now = Date.now();
+    let removed = 0;
+    for (const [key, entry] of this.store) {
+      if (now > entry.expiresAt) {
+        this.store.delete(key);
+        removed++;
+      }
+    }
+    return removed;
+  }
+
+  /**
+   * Clear all cached entries.
+   */
+  clear(): void {
+    this.store.clear();
+  }
+
+  /**
+   * Get the number of cached entries.
+   */
+  size(): number {
+    return this.store.size;
+  }
+
+  /**
+   * Get or set a value using a factory function.
+   */
+  remember<T>(key: string, ttl: number, factory: () => T): T {
+    const cached = this.get<T>(key);
+    if (cached !== undefined) return cached;
+    const value = factory();
+    this.set(key, value, ttl);
+    return value;
+  }
+}

package/packages/orm/src/types.ts

@@ -0,0 +1,110 @@
+export type FieldType = "string" | "integer" | "number" | "numeric" | "boolean" | "datetime" | "text";
+
+export interface FieldDefinition {
+  type: FieldType;
+  primaryKey?: boolean;
+  autoIncrement?: boolean;
+  required?: boolean;
+  default?: unknown;
+  minLength?: number;
+  maxLength?: number;
+  min?: number;
+  max?: number;
+  pattern?: string;
+}
+
+export interface RelationshipDefinition {
+  model: string;
+  foreignKey: string;
+}
+
+export interface ModelDefinition {
+  tableName: string;
+  fields: Record<string, FieldDefinition>;
+  softDelete?: boolean;
+  tableFilter?: string;
+  hasOne?: RelationshipDefinition[];
+  hasMany?: RelationshipDefinition[];
+  dbName?: string;
+}
+
+export interface ColumnInfo {
+  name: string;
+  type: string;
+  nullable?: boolean;
+  default?: unknown;
+  primaryKey?: boolean;
+}
+
+export interface DatabaseResult {
+  success: boolean;
+  rowsAffected: number;
+  lastInsertId?: number | bigint;
+  error?: string;
+}
+
+export interface DatabaseAdapter {
+  /** Execute a statement (INSERT, UPDATE, DELETE, DDL). */
+  execute(sql: string, params?: unknown[]): unknown;
+
+  /** Execute a single SQL statement with multiple parameter sets (batch). */
+  executeMany(sql: string, paramsList: unknown[][]): { totalAffected: number; lastInsertId?: number | bigint };
+
+  /** Query rows. */
+  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+
+  /** Fetch rows with optional pagination (limit/skip). */
+  fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[];
+
+  /** Fetch a single row or null. */
+  fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
+
+  /** Insert one or more rows into a table, returns result with lastInsertId. */
+  insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
+
+  /** Update rows in a table matching filter, returns affected row count. */
+  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): DatabaseResult;
+
+  /** Delete rows from a table matching filter (object, string WHERE, or array of objects). */
+  delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[]): DatabaseResult;
+
+  /** Start a transaction. */
+  startTransaction(): void;
+
+  /** Commit the current transaction. */
+  commit(): void;
+
+  /** Rollback the current transaction. */
+  rollback(): void;
+
+  /** List all tables in the database. */
+  tables(): string[];
+
+  /** List columns with types for a table. */
+  columns(table: string): ColumnInfo[];
+
+  /** Get the last auto-increment id. */
+  lastInsertId(): number | bigint | null;
+
+  /** Close the connection. */
+  close(): void;
+
+  /** Check if a table exists. */
+  tableExists(name: string): boolean;
+
+  /** Create a table from field definitions. */
+  createTable(name: string, columns: Record<string, FieldDefinition>): void;
+
+  /** Get raw column info (legacy, used by migration). */
+  getTableColumns?(name: string): Array<{ name: string; type: string }>;
+
+  /** Add a column to an existing table (legacy, used by migration). */
+  addColumn?(table: string, colName: string, def: FieldDefinition): void;
+}
+
+export interface QueryOptions {
+  filter?: Record<string, unknown>;
+  sort?: string;
+  page?: number;
+  limit?: number;
+}

package/packages/orm/src/validation.ts

@@ -0,0 +1,93 @@
+import type { FieldDefinition } from "./types.js";
+
+export interface ValidationError {
+  field: string;
+  message: string;
+}
+
+export function validate(
+  data: Record<string, unknown>,
+  fields: Record<string, FieldDefinition>,
+  isUpdate = false
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  // Pre-compile regex patterns outside the loop (E005)
+  const compiledPatterns = new Map<string, RegExp>();
+  for (const [name, def] of Object.entries(fields)) {
+    if (def.pattern !== undefined) {
+      compiledPatterns.set(name, new RegExp(def.pattern));
+    }
+  }
+
+  for (const [name, def] of Object.entries(fields)) {
+    // Skip primary key / autoIncrement fields on create
+    if (def.primaryKey && def.autoIncrement) continue;
+
+    const value = data[name];
+
+    // Required check (skip on update if field not provided)
+    if (def.required && !isUpdate && (value === undefined || value === null || value === "")) {
+      errors.push({ field: name, message: "is required" });
+      continue;
+    }
+
+    // Skip further validation if value not provided
+    if (value === undefined || value === null) continue;
+
+    // Type checks
+    switch (def.type) {
+      case "string":
+      case "text":
+        if (typeof value !== "string") {
+          errors.push({ field: name, message: "must be a string" });
+        } else {
+          if (def.minLength !== undefined && value.length < def.minLength) {
+            errors.push({ field: name, message: `must be at least ${def.minLength} characters` });
+          }
+          if (def.maxLength !== undefined && value.length > def.maxLength) {
+            errors.push({ field: name, message: `must be at most ${def.maxLength} characters` });
+          }
+          const regex = compiledPatterns.get(name);
+          if (regex && !regex.test(value)) {
+            errors.push({ field: name, message: `does not match required pattern` });
+          }
+        }
+        break;
+
+      case "integer":
+      case "number":
+      case "numeric": {
+        const num = typeof value === "string" ? Number(value) : value;
+        if (typeof num !== "number" || isNaN(num)) {
+          errors.push({ field: name, message: "must be a number" });
+        } else {
+          if (def.type === "integer" && !Number.isInteger(num)) {
+            errors.push({ field: name, message: "must be an integer" });
+          }
+          if (def.min !== undefined && num < def.min) {
+            errors.push({ field: name, message: `must be at least ${def.min}` });
+          }
+          if (def.max !== undefined && num > def.max) {
+            errors.push({ field: name, message: `must be at most ${def.max}` });
+          }
+        }
+        break;
+      }
+
+      case "boolean":
+        if (typeof value !== "boolean" && value !== 0 && value !== 1 && value !== "true" && value !== "false") {
+          errors.push({ field: name, message: "must be a boolean" });
+        }
+        break;
+
+      case "datetime":
+        if (typeof value === "string" && isNaN(Date.parse(value))) {
+          errors.push({ field: name, message: "must be a valid date/time" });
+        }
+        break;
+    }
+  }
+
+  return errors;
+}

package/packages/swagger/src/generator.ts

@@ -0,0 +1,189 @@
+import type { RouteDefinition } from "@tina4/core";
+import type { ModelDefinition, FieldDefinition } from "@tina4/orm";
+
+interface OpenAPISpec {
+  openapi: string;
+  info: { title: string; version: string; description?: string };
+  paths: Record<string, Record<string, unknown>>;
+  components?: { schemas?: Record<string, unknown> };
+}
+
+export function generateOpenAPISpec(
+  routes: RouteDefinition[],
+  models: ModelDefinition[]
+): OpenAPISpec {
+  const spec: OpenAPISpec = {
+    openapi: "3.0.3",
+    info: {
+      title: "Tina4 API",
+      version: "0.0.1",
+      description: "Auto-generated API documentation",
+    },
+    paths: {},
+    components: { schemas: {} },
+  };
+
+  // Generate schemas from models
+  for (const model of models) {
+    const schema = modelToSchema(model);
+    spec.components!.schemas![model.tableName] = schema;
+  }
+
+  // Generate paths from routes
+  for (const route of routes) {
+    const openApiPath = patternToOpenAPI(route.pattern);
+    const method = route.method.toLowerCase();
+
+    if (!spec.paths[openApiPath]) {
+      spec.paths[openApiPath] = {};
+    }
+
+    const operation: Record<string, unknown> = {
+      summary: route.meta?.summary ?? `${route.method} ${route.pattern}`,
+      tags: route.meta?.tags ?? inferTags(route.pattern),
+      responses: route.meta?.responses ?? {
+        "200": { description: "Successful response" },
+      },
+    };
+
+    // Add path parameters
+    const pathParams = extractPathParams(route.pattern);
+    if (pathParams.length > 0) {
+      operation.parameters = pathParams.map((name) => ({
+        name,
+        in: "path",
+        required: true,
+        schema: { type: "string" },
+      }));
+    }
+
+    // Add query parameters for GET list endpoints
+    if (method === "get" && !route.pattern.includes("[id]") && !route.pattern.includes("[...")) {
+      const modelName = inferModelFromPath(route.pattern);
+      if (modelName && models.some((m) => m.tableName === modelName)) {
+        operation.parameters = [
+          ...(operation.parameters as unknown[] ?? []),
+          { name: "page", in: "query", schema: { type: "integer", default: 1 } },
+          { name: "limit", in: "query", schema: { type: "integer", default: 20 } },
+          { name: "sort", in: "query", schema: { type: "string" }, description: "Sort fields (prefix with - for descending)" },
+        ];
+      }
+    }
+
+    // Add request body for POST/PUT
+    if (method === "post" || method === "put") {
+      const modelName = inferModelFromPath(route.pattern);
+      if (modelName && models.some((m) => m.tableName === modelName)) {
+        operation.requestBody = {
+          required: true,
+          content: {
+            "application/json": {
+              schema: { $ref: `#/components/schemas/${modelName}` },
+            },
+          },
+        };
+
+        // Add response schema
+        operation.responses = {
+          ...(method === "post"
+            ? { "201": { description: "Created", content: { "application/json": { schema: { $ref: `#/components/schemas/${modelName}` } } } } }
+            : { "200": { description: "Updated", content: { "application/json": { schema: { $ref: `#/components/schemas/${modelName}` } } } } }),
+          "422": { description: "Validation failed" },
+        };
+      }
+    }
+
+    spec.paths[openApiPath][method] = operation;
+  }
+
+  return spec;
+}
+
+function modelToSchema(model: ModelDefinition): Record<string, unknown> {
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+
+  for (const [name, def] of Object.entries(model.fields)) {
+    properties[name] = fieldToSchemaProperty(def);
+    if (def.required && !def.primaryKey) {
+      required.push(name);
+    }
+  }
+
+  return {
+    type: "object",
+    properties,
+    ...(required.length > 0 ? { required } : {}),
+  };
+}
+
+function fieldToSchemaProperty(def: FieldDefinition): Record<string, unknown> {
+  const prop: Record<string, unknown> = {};
+
+  switch (def.type) {
+    case "string":
+    case "text":
+      prop.type = "string";
+      if (def.maxLength) prop.maxLength = def.maxLength;
+      if (def.minLength) prop.minLength = def.minLength;
+      if (def.pattern) prop.pattern = def.pattern;
+      break;
+    case "integer":
+      prop.type = "integer";
+      if (def.min !== undefined) prop.minimum = def.min;
+      if (def.max !== undefined) prop.maximum = def.max;
+      break;
+    case "number":
+    case "numeric":
+      prop.type = "number";
+      if (def.min !== undefined) prop.minimum = def.min;
+      if (def.max !== undefined) prop.maximum = def.max;
+      break;
+    case "boolean":
+      prop.type = "boolean";
+      break;
+    case "datetime":
+      prop.type = "string";
+      prop.format = "date-time";
+      break;
+  }
+
+  if (def.primaryKey && def.autoIncrement) {
+    prop.readOnly = true;
+  }
+
+  return prop;
+}
+
+function patternToOpenAPI(pattern: string): string {
+  return pattern.replace(/\[\.\.\.(\w+)\]/g, "{$1}").replace(/\[(\w+)\]/g, "{$1}");
+}
+
+function extractPathParams(pattern: string): string[] {
+  const params: string[] = [];
+  const regex = /\[(?:\.\.\.)?(\w+)\]/g;
+  let match;
+  while ((match = regex.exec(pattern)) !== null) {
+    params.push(match[1]);
+  }
+  return params;
+}
+
+function inferTags(pattern: string): string[] {
+  const parts = pattern.split("/").filter(Boolean);
+  // Use the first meaningful segment after /api/ as tag
+  const apiIndex = parts.indexOf("api");
+  if (apiIndex !== -1 && parts[apiIndex + 1]) {
+    return [parts[apiIndex + 1]];
+  }
+  return parts.length > 0 ? [parts[0]] : ["default"];
+}
+
+function inferModelFromPath(pattern: string): string | null {
+  const parts = pattern.split("/").filter(Boolean);
+  const apiIndex = parts.indexOf("api");
+  if (apiIndex !== -1 && parts[apiIndex + 1]) {
+    return parts[apiIndex + 1];
+  }
+  return null;
+}

package/packages/swagger/src/index.ts

@@ -0,0 +1,2 @@
+export { generateOpenAPISpec } from "./generator.js";
+export { createSwaggerRoutes } from "./ui.js";