tina4-nodejs 3.13.92 → 3.13.94

package/types/orm/src/sqlTranslator.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 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.
+ */
+export declare 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;
+    /**
+     * 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;
+    /**
+     * Convert || concatenation to CONCAT() for MySQL/MSSQL.
+     *
+     * 'a' || 'b' || 'c'  →  CONCAT('a', 'b', 'c')
+     */
+    static concatPipesToFunc(sql: string): string;
+    /**
+     * Convert TRUE/FALSE to 1/0 for engines without boolean type (Firebird).
+     */
+    static booleanToInt(sql: string): string;
+    /**
+     * Convert ILIKE to LOWER() LIKE LOWER() for engines without ILIKE.
+     */
+    static ilikeToLike(sql: string): string;
+    /**
+     * Translate AUTOINCREMENT across engines in DDL.
+     */
+    static autoIncrementSyntax(sql: string, engine: string): string;
+    /**
+     * Convert ? placeholders to engine-specific style.
+     *
+     * ? → %s (MySQL, PostgreSQL)
+     * ? → :1, :2, :3 (Oracle, Firebird)
+     */
+    static placeholderStyle(sql: string, style: string): string;
+    /**
+     * 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[];
+    };
+    /**
+     * v3.13.14 (#48): split a possibly-qualified table name into [schema, table].
+     *
+     * A model whose table name is qualified — PostgreSQL "gift_cards.gift_card",
+     * MSSQL "dbo.widget", MySQL "otherdb.table", SQLite "attached.table" — lives
+     * in that schema/catalog, not the default. Adapters use this so tableExists /
+     * getColumns query the right namespace instead of matching the whole dotted
+     * string as one flat name. Returns [null, name] for a bare name. Splits on the
+     * first dot. Firebird has no schemas, so its adapter ignores this.
+     */
+    static splitSchema(name: string): [string | null, string];
+}
+/**
+ * Simple in-memory query cache with TTL support.
+ */
+export declare class QueryCache {
+    private store;
+    private defaultTtl;
+    private maxSize;
+    constructor(options?: {
+        defaultTtl?: number;
+        maxSize?: number;
+    });
+    /**
+     * Generate a cache key from a SQL query and params.
+     */
+    static queryKey(sql: string, params?: unknown[]): string;
+    /**
+     * Get a cached value. Returns undefined if expired or missing.
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Set a cached value with optional TTL (seconds) and tags for grouped
+     * invalidation via clearTag().
+     */
+    set<T>(key: string, value: T, ttl?: number, tags?: string[]): void;
+    /**
+     * Remove all entries that carry the given tag. Returns the number removed.
+     */
+    clearTag(tag: string): number;
+    /**
+     * Check if a key exists and is not expired.
+     */
+    has(key: string): boolean;
+    /**
+     * Delete a specific key.
+     */
+    delete(key: string): boolean;
+    /**
+     * Remove all expired entries.
+     */
+    sweep(): number;
+    /**
+     * Clear all cached entries.
+     */
+    clear(): void;
+    /**
+     * Get the number of cached entries.
+     */
+    size(): number;
+    /**
+     * Get or set a value using a factory function.
+     */
+    remember<T>(key: string, ttl: number, factory: () => T): T;
+}

package/types/orm/src/types.d.ts

@@ -0,0 +1,138 @@
+export type FieldType = "string" | "integer" | "number" | "numeric" | "boolean" | "datetime" | "text" | "json" | "foreignKey";
+export interface FieldDefinition {
+    type: FieldType;
+    primaryKey?: boolean;
+    autoIncrement?: boolean;
+    required?: boolean;
+    default?: unknown;
+    minLength?: number;
+    maxLength?: number;
+    min?: number;
+    max?: number;
+    pattern?: string;
+    /** For type "foreignKey": the referenced model name (string) */
+    references?: string;
+    /** For type "foreignKey": override the has-many property name on the referenced model */
+    relatedName?: string;
+}
+export interface RelationshipDefinition {
+    model: string;
+    foreignKey: string;
+    /**
+     * The relationship accessor/include name on the OWNING model. For an
+     * FK-auto-wired has-many this is the declaring class name lowercased + "s"
+     * (Python master rule) or the `relatedName` override. Used by eager-load
+     * include resolution so an `include: ["posts"]` matches the wired relation.
+     */
+    relatedName?: string;
+}
+export interface ModelDefinition {
+    tableName: string;
+    fields: Record<string, FieldDefinition>;
+    fieldMapping?: Record<string, string>;
+    softDelete?: boolean;
+    tableFilter?: string;
+    hasOne?: RelationshipDefinition[];
+    hasMany?: RelationshipDefinition[];
+    belongsTo?: RelationshipDefinition[];
+    dbName?: string;
+}
+export interface ColumnInfo {
+    name: string;
+    type: string;
+    nullable?: boolean;
+    default?: unknown;
+    primaryKey?: boolean;
+}
+export interface DatabaseResult {
+    success: boolean;
+    affectedRows: number;
+    lastId?: number | bigint | string;
+    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;
+        lastId?: 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 lastId. */
+    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>, params?: 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>[], params?: 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 inserted id (auto-increment integer, or a UUID/string PK). */
+    lastInsertId(): number | bigint | string | 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 PaginatedResult<T = Record<string, unknown>> {
+    data: T[];
+    page: number;
+    perPage: number;
+    total: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+/**
+ * Wraps an array of fetched rows with convenience methods.
+ *
+ * Mirrors Python's `DatabaseResult` and Ruby's `Tina4::DatabaseResult`.
+ */
+export declare class FetchResult<T = Record<string, unknown>> {
+    readonly records: T[];
+    readonly count: number;
+    readonly sql: string;
+    constructor(records: T[], sql?: string);
+    /** Paginate the in-memory result set. */
+    toPaginate(page?: number, perPage?: number): PaginatedResult<T>;
+    /** Return the first record or null. */
+    first(): T | null;
+    /** Return the last record or null. */
+    last(): T | null;
+    /** Check if result is empty. */
+    isEmpty(): boolean;
+    /** Convert to plain array. */
+    toArray(): T[];
+    /** Convert to JSON string. */
+    toJSON(): string;
+    /** Iterate over records. */
+    [Symbol.iterator](): Iterator<T>;
+}
+export interface QueryOptions {
+    filter?: Record<string, unknown>;
+    sort?: string;
+    page?: number;
+    limit?: number;
+}

package/types/orm/src/validation.d.ts

@@ -0,0 +1,6 @@
+import type { FieldDefinition } from "./types.js";
+export interface ValidationError {
+    field: string;
+    message: string;
+}
+export declare function validate(data: Record<string, unknown>, fields: Record<string, FieldDefinition>, isUpdate?: boolean): ValidationError[];

package/types/swagger/src/generator.d.ts

@@ -0,0 +1,46 @@
+import type { RouteDefinition } from "../../core/src/index.js";
+import type { ModelDefinition } from "../../orm/src/index.js";
+interface OpenAPISpecInfo {
+    title: string;
+    version: string;
+    description?: string;
+    contact?: {
+        name?: string;
+        url?: string;
+        email?: string;
+    };
+    license?: {
+        name: string;
+        url?: string;
+    };
+}
+interface OpenAPISpec {
+    openapi: string;
+    info: OpenAPISpecInfo;
+    servers?: {
+        url: string;
+    }[];
+    paths: Record<string, Record<string, unknown>>;
+    components?: {
+        schemas?: Record<string, unknown>;
+        securitySchemes?: Record<string, unknown>;
+    };
+    tags?: {
+        name: string;
+    }[];
+}
+/**
+ * Register a named OpenAPI security scheme (e.g. an oauth2 scheme with scopes,
+ * or a custom apiKey). Call at app bootstrap, before generate(). A registered
+ * scheme may override the built-in bearerAuth.
+ */
+export declare function addSecurityScheme(name: string, definition: Record<string, unknown>): void;
+/**
+ * Register a reusable component schema, referenceable via meta.requestSchema /
+ * meta.responseSchemas or a raw $ref.
+ */
+export declare function addSchema(name: string, schema: Record<string, unknown>): void;
+/** Clear the security-scheme and schema registries (test helper). */
+export declare function resetRegistry(): void;
+export declare function generate(routes: RouteDefinition[], models?: ModelDefinition[]): OpenAPISpec;
+export {};

package/types/swagger/src/index.d.ts

@@ -0,0 +1,2 @@
+export { generate, addSecurityScheme, addSchema, resetRegistry } from "./generator.js";
+export { createSwaggerRoutes, swaggerEnabled } from "./ui.js";

package/types/swagger/src/ui.d.ts

@@ -0,0 +1,11 @@
+import type { RouteDefinition } from "../../core/src/index.js";
+/**
+ * Whether the Swagger UI + spec routes should be registered at boot.
+ *
+ * Default: enabled when `TINA4_DEBUG=true`, disabled otherwise. Operators
+ * can force either state with `TINA4_SWAGGER_ENABLED=true|false`. Matches
+ * Python parity: dev-only by default to keep production attack surface
+ * minimal, but easy to expose intentionally for public APIs.
+ */
+export declare function swaggerEnabled(): boolean;
+export declare function createSwaggerRoutes(getSpec: () => unknown): RouteDefinition[];