@ghom/orm 1.10.0 → 2.0.0

package/dist/app/backup.d.ts

@@ -1,6 +1,6 @@
-import { Knex } from "knex";
-import { ORM } from "./orm.js";
-import { Table } from "./table.js";
+import type { Knex } from "knex";
+import type { ORM } from "./orm.js";
+import type { Table } from "./table.js";
 export declare function backupTable(table: Table, dirname?: string): Promise<void>;
 export declare function restoreBackup(table: Table, trx: Knex.Transaction | Knex, dirname?: string): Promise<void>;
 export declare function enableForeignKeys(orm: ORM, trx?: Knex.Transaction | Knex): Promise<void>;

package/dist/app/backup.js

@@ -1,8 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
-import csv from "json-2-csv";
 import csvParser from "csv-parser";
-import { DEFAULT_BACKUP_CHUNK_SIZE, DEFAULT_BACKUP_LOCATION, styled, } from "./util.js";
+import csv from "json-2-csv";
+import { DEFAULT_BACKUP_CHUNK_SIZE, DEFAULT_BACKUP_LOCATION, styled } from "./util.js";
 function getConfig(orm) {
     if (orm.config === false)
         throw new Error("ORM config is not available");
@@ -75,7 +75,7 @@ export async function restoreBackup(table, trx, dirname) {
         const totalChunks = chunkFiles.length;
         let processedChunks = 0;
         let totalRowsRestored = 0;
-        for (let chunkFile of chunkFiles) {
+        for (const chunkFile of chunkFiles) {
             const filePath = path.join(chunkDir, chunkFile);
             let rows = [];
             let chunkRowsCount = 0;
@@ -119,30 +119,29 @@ export async function enableForeignKeys(orm, trx) {
     });
 }
 export async function disableForeignKeys(orm, run) {
-    if (!orm.client)
+    if (!orm._client)
         throw new Error("ORM client is not initialized");
     const trx = orm.clientBasedOperation({
-        sqlite3: () => orm.client,
-    }) ?? (await orm.client.transaction());
-    const ran = await orm.clientBasedOperation({
+        sqlite3: () => orm._client,
+    }) ?? (await orm._client.transaction());
+    const _ran = await orm.clientBasedOperation({
         mysql2: async () => {
             const result = await trx.raw("SELECT @@FOREIGN_KEY_CHECKS;");
-            const check = result?.[0] && result[0]["@@FOREIGN_KEY_CHECKS"] != 0;
+            const check = result?.[0] && result[0]["@@FOREIGN_KEY_CHECKS"] !== 0;
             if (check)
                 await trx.raw("SET FOREIGN_KEY_CHECKS = 0;");
             return check;
         },
         sqlite3: async () => {
             const result = await trx.raw("PRAGMA foreign_keys;");
-            const check = result?.[0] && result[0].foreign_keys != 0;
+            const check = result?.[0] && result[0].foreign_keys !== 0;
             if (check)
                 await trx.raw("PRAGMA foreign_keys = 0;");
             return check;
         },
         pg: async () => {
             const result = await trx.raw("SHOW session_replication_role;");
-            const check = result?.rows?.[0] &&
-                result.rows[0].session_replication_role !== "replica";
+            const check = result?.rows?.[0] && result.rows[0].session_replication_role !== "replica";
             if (check)
                 await trx.raw("SET session_replication_role = replica;");
             return check;

package/dist/app/column.d.ts

@@ -0,0 +1,225 @@
+import type { Knex } from "knex";
+/**
+ * Represents the inferred TypeScript type for a column definition.
+ */
+export type InferColumnType<T extends ColumnDef<any, any>> = T extends ColumnDef<infer Type, infer Nullable> ? Nullable extends true ? Type | null : Type : never;
+/**
+ * Infers the full record type from a columns definition.
+ */
+export type InferColumns<T extends Record<string, ColumnDef<any, any>>> = {
+    [K in keyof T]: InferColumnType<T[K]>;
+};
+/**
+ * Base column definition that tracks the TypeScript type and nullability.
+ */
+export declare class ColumnDef<Type, Nullable extends boolean = false> {
+    /** @internal */
+    readonly _buildFn: (tableBuilder: Knex.CreateTableBuilder, name: string) => Knex.ColumnBuilder;
+    /** @internal */
+    readonly _isNullable: Nullable;
+    /** @internal */
+    readonly _modifiers: Array<(col: Knex.ColumnBuilder) => Knex.ColumnBuilder>;
+    /** @internal */
+    readonly _type: Type;
+    /** @internal */
+    readonly _nullable: Nullable;
+    /** @internal */
+    _knexBuilder?: Knex.ColumnBuilder;
+    constructor(
+    /** @internal */
+    _buildFn: (tableBuilder: Knex.CreateTableBuilder, name: string) => Knex.ColumnBuilder, 
+    /** @internal */
+    _isNullable?: Nullable, 
+    /** @internal */
+    _modifiers?: Array<(col: Knex.ColumnBuilder) => Knex.ColumnBuilder>);
+    /**
+     * Makes this column nullable.
+     */
+    nullable(): ColumnDef<Type, true>;
+    /**
+     * Sets a default value for this column.
+     */
+    defaultTo(value: Type | Knex.Raw): ColumnDef<Type, Nullable>;
+    /**
+     * Makes this column unique.
+     */
+    unique(): ColumnDef<Type, Nullable>;
+    /**
+     * Makes this column the primary key.
+     */
+    primary(): ColumnDef<Type, Nullable>;
+    /**
+     * Adds an index to this column.
+     */
+    index(indexName?: string): ColumnDef<Type, Nullable>;
+    /**
+     * Adds a comment to this column.
+     */
+    comment(comment: string): ColumnDef<Type, Nullable>;
+    /**
+     * Sets the collation for this column.
+     */
+    collate(collation: string): ColumnDef<Type, Nullable>;
+    /**
+     * Adds a references constraint to this column.
+     */
+    references(columnName: string): ForeignColumnDef<Type, Nullable>;
+    /** @internal */
+    _build(tableBuilder: Knex.CreateTableBuilder, name: string): Knex.ColumnBuilder;
+}
+/**
+ * Column definition with foreign key support.
+ */
+export declare class ForeignColumnDef<Type, Nullable extends boolean> extends ColumnDef<Type, Nullable> {
+    private _referencesColumn;
+    private _inTable?;
+    private _onDelete?;
+    private _onUpdate?;
+    constructor(buildFn: (tableBuilder: Knex.CreateTableBuilder, name: string) => Knex.ColumnBuilder, isNullable: Nullable, modifiers: Array<(col: Knex.ColumnBuilder) => Knex.ColumnBuilder>, _referencesColumn: string, _inTable?: string | undefined, _onDelete?: string | undefined, _onUpdate?: string | undefined);
+    /**
+     * Sets the table for the foreign key reference.
+     */
+    inTable(tableName: string): ForeignColumnDef<Type, Nullable>;
+    /**
+     * Sets the ON DELETE action.
+     */
+    onDelete(action: "CASCADE" | "SET NULL" | "RESTRICT" | "NO ACTION"): ForeignColumnDef<Type, Nullable>;
+    /**
+     * Sets the ON UPDATE action.
+     */
+    onUpdate(action: "CASCADE" | "SET NULL" | "RESTRICT" | "NO ACTION"): ForeignColumnDef<Type, Nullable>;
+    /** @internal */
+    _build(tableBuilder: Knex.CreateTableBuilder, name: string): Knex.ColumnBuilder;
+}
+/**
+ * Number column definition with additional numeric options.
+ */
+export declare class NumberColumnDef<Nullable extends boolean = false> extends ColumnDef<number, Nullable> {
+    /**
+     * Makes this column unsigned (only positive values).
+     */
+    unsigned(): NumberColumnDef<Nullable>;
+    nullable(): NumberColumnDef<true>;
+    defaultTo(value: number | Knex.Raw): NumberColumnDef<Nullable>;
+}
+/**
+ * Column factory for creating typed column definitions.
+ */
+export declare const col: {
+    /**
+     * Auto-incrementing primary key (integer).
+     */
+    increments(): ColumnDef<number>;
+    /**
+     * Big auto-incrementing primary key (bigint).
+     */
+    bigIncrements(): ColumnDef<bigint>;
+    /**
+     * Integer column.
+     */
+    integer(): NumberColumnDef;
+    /**
+     * Big integer column.
+     */
+    bigInteger(): ColumnDef<bigint>;
+    /**
+     * Tiny integer column (0-255).
+     */
+    tinyint(): NumberColumnDef;
+    /**
+     * Small integer column.
+     */
+    smallint(): NumberColumnDef;
+    /**
+     * Medium integer column.
+     */
+    mediumint(): NumberColumnDef;
+    /**
+     * Floating-point number column.
+     * @param precision - Total number of digits
+     * @param scale - Number of decimal places
+     */
+    float(precision?: number, scale?: number): NumberColumnDef;
+    /**
+     * Double precision floating-point column.
+     * @param precision - Total number of digits
+     * @param scale - Number of decimal places
+     */
+    double(precision?: number, scale?: number): NumberColumnDef;
+    /**
+     * Decimal column for exact numeric values.
+     * @param precision - Total number of digits
+     * @param scale - Number of decimal places
+     */
+    decimal(precision?: number, scale?: number): NumberColumnDef;
+    /**
+     * String column.
+     * @param length - Maximum length (default: 255)
+     */
+    string(length?: number): ColumnDef<string>;
+    /**
+     * Text column for longer strings.
+     * @param textType - Type of text column
+     */
+    text(textType?: "text" | "mediumtext" | "longtext"): ColumnDef<string>;
+    /**
+     * Boolean column.
+     */
+    boolean(): ColumnDef<boolean>;
+    /**
+     * Date column (without time).
+     */
+    date(): ColumnDef<Date>;
+    /**
+     * DateTime column.
+     * @param options - DateTime options
+     */
+    datetime(options?: {
+        useTz?: boolean;
+        precision?: number;
+    }): ColumnDef<Date>;
+    /**
+     * Timestamp column.
+     * @param options - Timestamp options
+     */
+    timestamp(options?: {
+        useTz?: boolean;
+        precision?: number;
+    }): ColumnDef<Date>;
+    /**
+     * Time column.
+     */
+    time(): ColumnDef<string>;
+    /**
+     * Binary column.
+     * @param length - Maximum length
+     */
+    binary(length?: number): ColumnDef<Buffer>;
+    /**
+     * Enum column with specific allowed values.
+     * @param values - Array of allowed values
+     */
+    enum<T extends readonly string[]>(values: T): ColumnDef<T[number]>;
+    /**
+     * JSON column.
+     */
+    json<T = unknown>(): ColumnDef<T>;
+    /**
+     * JSONB column (PostgreSQL).
+     */
+    jsonb<T = unknown>(): ColumnDef<T>;
+    /**
+     * UUID column.
+     */
+    uuid(): ColumnDef<string>;
+    /**
+     * Specific database type column.
+     * @param type - The database-specific type
+     */
+    specificType<T = unknown>(type: string): ColumnDef<T>;
+};
+/**
+ * Builds the Knex table schema from column definitions.
+ * @internal
+ */
+export declare function buildColumnsSchema(tableBuilder: Knex.CreateTableBuilder, columns: Record<string, ColumnDef<any, any>>): void;

package/dist/app/column.js

@@ -0,0 +1,342 @@
+/**
+ * Base column definition that tracks the TypeScript type and nullability.
+ */
+export class ColumnDef {
+    _buildFn;
+    _isNullable;
+    _modifiers;
+    /** @internal */
+    _type;
+    /** @internal */
+    _nullable;
+    /** @internal */
+    _knexBuilder;
+    constructor(
+    /** @internal */
+    _buildFn, 
+    /** @internal */
+    _isNullable = false, 
+    /** @internal */
+    _modifiers = []) {
+        this._buildFn = _buildFn;
+        this._isNullable = _isNullable;
+        this._modifiers = _modifiers;
+    }
+    /**
+     * Makes this column nullable.
+     */
+    nullable() {
+        return new ColumnDef(this._buildFn, true, [
+            ...this._modifiers,
+            (col) => col.nullable(),
+        ]);
+    }
+    /**
+     * Sets a default value for this column.
+     */
+    defaultTo(value) {
+        return new ColumnDef(this._buildFn, this._isNullable, [
+            ...this._modifiers,
+            (col) => col.defaultTo(value),
+        ]);
+    }
+    /**
+     * Makes this column unique.
+     */
+    unique() {
+        return new ColumnDef(this._buildFn, this._isNullable, [
+            ...this._modifiers,
+            (col) => col.unique(),
+        ]);
+    }
+    /**
+     * Makes this column the primary key.
+     */
+    primary() {
+        return new ColumnDef(this._buildFn, this._isNullable, [
+            ...this._modifiers,
+            (col) => col.primary(),
+        ]);
+    }
+    /**
+     * Adds an index to this column.
+     */
+    index(indexName) {
+        return new ColumnDef(this._buildFn, this._isNullable, [
+            ...this._modifiers,
+            (col) => col.index(indexName),
+        ]);
+    }
+    /**
+     * Adds a comment to this column.
+     */
+    comment(comment) {
+        return new ColumnDef(this._buildFn, this._isNullable, [
+            ...this._modifiers,
+            (col) => col.comment(comment),
+        ]);
+    }
+    /**
+     * Sets the collation for this column.
+     */
+    collate(collation) {
+        return new ColumnDef(this._buildFn, this._isNullable, [
+            ...this._modifiers,
+            (col) => col.collate(collation),
+        ]);
+    }
+    /**
+     * Adds a references constraint to this column.
+     */
+    references(columnName) {
+        return new ForeignColumnDef(this._buildFn, this._isNullable, [...this._modifiers], columnName);
+    }
+    /** @internal */
+    _build(tableBuilder, name) {
+        let col = this._buildFn(tableBuilder, name);
+        if (!this._isNullable) {
+            col = col.notNullable();
+        }
+        for (const modifier of this._modifiers) {
+            col = modifier(col);
+        }
+        return col;
+    }
+}
+/**
+ * Column definition with foreign key support.
+ */
+export class ForeignColumnDef extends ColumnDef {
+    _referencesColumn;
+    _inTable;
+    _onDelete;
+    _onUpdate;
+    constructor(buildFn, isNullable, modifiers, _referencesColumn, _inTable, _onDelete, _onUpdate) {
+        super(buildFn, isNullable, modifiers);
+        this._referencesColumn = _referencesColumn;
+        this._inTable = _inTable;
+        this._onDelete = _onDelete;
+        this._onUpdate = _onUpdate;
+    }
+    /**
+     * Sets the table for the foreign key reference.
+     */
+    inTable(tableName) {
+        return new ForeignColumnDef(this._buildFn, this._isNullable, this._modifiers, this._referencesColumn, tableName, this._onDelete, this._onUpdate);
+    }
+    /**
+     * Sets the ON DELETE action.
+     */
+    onDelete(action) {
+        return new ForeignColumnDef(this._buildFn, this._isNullable, this._modifiers, this._referencesColumn, this._inTable, action, this._onUpdate);
+    }
+    /**
+     * Sets the ON UPDATE action.
+     */
+    onUpdate(action) {
+        return new ForeignColumnDef(this._buildFn, this._isNullable, this._modifiers, this._referencesColumn, this._inTable, this._onDelete, action);
+    }
+    /** @internal */
+    _build(tableBuilder, name) {
+        const col = super._build(tableBuilder, name);
+        let ref = col.references(this._referencesColumn);
+        if (this._inTable)
+            ref = ref.inTable(this._inTable);
+        if (this._onDelete)
+            ref = ref.onDelete(this._onDelete);
+        if (this._onUpdate)
+            ref = ref.onUpdate(this._onUpdate);
+        return col;
+    }
+}
+/**
+ * Number column definition with additional numeric options.
+ */
+export class NumberColumnDef extends ColumnDef {
+    /**
+     * Makes this column unsigned (only positive values).
+     */
+    unsigned() {
+        return new NumberColumnDef((tb, name) => {
+            const col = this._buildFn(tb, name);
+            return col.unsigned();
+        }, this._isNullable, this._modifiers);
+    }
+    nullable() {
+        return new NumberColumnDef(this._buildFn, true, [
+            ...this._modifiers,
+            (col) => col.nullable(),
+        ]);
+    }
+    defaultTo(value) {
+        return new NumberColumnDef(this._buildFn, this._isNullable, [
+            ...this._modifiers,
+            (col) => col.defaultTo(value),
+        ]);
+    }
+}
+/**
+ * Column factory for creating typed column definitions.
+ */
+export const col = {
+    /**
+     * Auto-incrementing primary key (integer).
+     */
+    increments() {
+        return new ColumnDef((tb, name) => tb.increments(name));
+    },
+    /**
+     * Big auto-incrementing primary key (bigint).
+     */
+    bigIncrements() {
+        return new ColumnDef((tb, name) => tb.bigIncrements(name));
+    },
+    /**
+     * Integer column.
+     */
+    integer() {
+        return new NumberColumnDef((tb, name) => tb.integer(name));
+    },
+    /**
+     * Big integer column.
+     */
+    bigInteger() {
+        return new ColumnDef((tb, name) => tb.bigInteger(name));
+    },
+    /**
+     * Tiny integer column (0-255).
+     */
+    tinyint() {
+        return new NumberColumnDef((tb, name) => tb.tinyint(name));
+    },
+    /**
+     * Small integer column.
+     */
+    smallint() {
+        return new NumberColumnDef((tb, name) => tb.smallint(name));
+    },
+    /**
+     * Medium integer column.
+     */
+    mediumint() {
+        return new NumberColumnDef((tb, name) => tb.mediumint(name));
+    },
+    /**
+     * Floating-point number column.
+     * @param precision - Total number of digits
+     * @param scale - Number of decimal places
+     */
+    float(precision, scale) {
+        return new NumberColumnDef((tb, name) => tb.float(name, precision, scale));
+    },
+    /**
+     * Double precision floating-point column.
+     * @param precision - Total number of digits
+     * @param scale - Number of decimal places
+     */
+    double(precision, scale) {
+        return new NumberColumnDef((tb, name) => tb.double(name, precision, scale));
+    },
+    /**
+     * Decimal column for exact numeric values.
+     * @param precision - Total number of digits
+     * @param scale - Number of decimal places
+     */
+    decimal(precision, scale) {
+        return new NumberColumnDef((tb, name) => tb.decimal(name, precision, scale));
+    },
+    /**
+     * String column.
+     * @param length - Maximum length (default: 255)
+     */
+    string(length) {
+        return new ColumnDef((tb, name) => tb.string(name, length));
+    },
+    /**
+     * Text column for longer strings.
+     * @param textType - Type of text column
+     */
+    text(textType) {
+        return new ColumnDef((tb, name) => tb.text(name, textType));
+    },
+    /**
+     * Boolean column.
+     */
+    boolean() {
+        return new ColumnDef((tb, name) => tb.boolean(name));
+    },
+    /**
+     * Date column (without time).
+     */
+    date() {
+        return new ColumnDef((tb, name) => tb.date(name));
+    },
+    /**
+     * DateTime column.
+     * @param options - DateTime options
+     */
+    datetime(options) {
+        return new ColumnDef((tb, name) => tb.datetime(name, options));
+    },
+    /**
+     * Timestamp column.
+     * @param options - Timestamp options
+     */
+    timestamp(options) {
+        return new ColumnDef((tb, name) => tb.timestamp(name, options));
+    },
+    /**
+     * Time column.
+     */
+    time() {
+        return new ColumnDef((tb, name) => tb.time(name));
+    },
+    /**
+     * Binary column.
+     * @param length - Maximum length
+     */
+    binary(length) {
+        return new ColumnDef((tb, name) => tb.binary(name, length));
+    },
+    /**
+     * Enum column with specific allowed values.
+     * @param values - Array of allowed values
+     */
+    enum(values) {
+        return new ColumnDef((tb, name) => tb.enum(name, [...values]));
+    },
+    /**
+     * JSON column.
+     */
+    json() {
+        return new ColumnDef((tb, name) => tb.json(name));
+    },
+    /**
+     * JSONB column (PostgreSQL).
+     */
+    jsonb() {
+        return new ColumnDef((tb, name) => tb.jsonb(name));
+    },
+    /**
+     * UUID column.
+     */
+    uuid() {
+        return new ColumnDef((tb, name) => tb.uuid(name));
+    },
+    /**
+     * Specific database type column.
+     * @param type - The database-specific type
+     */
+    specificType(type) {
+        return new ColumnDef((tb, name) => tb.specificType(name, type));
+    },
+};
+/**
+ * Builds the Knex table schema from column definitions.
+ * @internal
+ */
+export function buildColumnsSchema(tableBuilder, columns) {
+    for (const [name, columnDef] of Object.entries(columns)) {
+        columnDef._build(tableBuilder, name);
+    }
+}

package/dist/app/orm.d.ts

@@ -1,8 +1,8 @@
 import { Handler } from "@ghom/handler";
-import { Knex } from "knex";
-import { TextStyle } from "./util.js";
-import { Table } from "./table.js";
 import { CachedQuery } from "@ghom/query";
+import { type Knex } from "knex";
+import { Table } from "./table.js";
+import { type TextStyle } from "./util.js";
 export interface ILogger {
     log: (message: string) => void;
     error: (error: string | Error) => void;
@@ -63,7 +63,7 @@ export interface ORMConfig {
 export declare class ORM {
     config: ORMConfig | false;
     private _ready;
-    client?: Knex;
+    _client?: Knex;
     handler?: Handler<Table<any>>;
     _rawCache?: CachedQuery<[raw: string], Knex.Raw>;
     /**
@@ -80,6 +80,7 @@ export declare class ORM {
      */
     constructor(config: ORMConfig | false);
     private requireClient;
+    get client(): Knex;
     /**
      * Returns true if the ORM has a database client connected.
      */