@ghom/orm 1.9.2 → 2.0.0

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;
@@ -44,13 +44,47 @@ export interface ORMConfig {
      */
     caching?: number;
 }
+/**
+ * The main ORM class that manages database connections, tables, and caching.
+ *
+ * @example
+ * // With database connection
+ * const orm = new ORM({
+ *   tableLocation: "./tables",
+ *   database: { client: "sqlite3", connection: { filename: ":memory:" } }
+ * })
+ * await orm.init()
+ *
+ * @example
+ * // Without database connection (for type exports only)
+ * const orm = new ORM(false)
+ * orm.isConnected // false
+ */
 export declare class ORM {
-    config: ORMConfig;
+    config: ORMConfig | false;
     private _ready;
-    client: Knex<any, unknown[]>;
-    handler: Handler<Table<any>>;
-    _rawCache: CachedQuery<[raw: string], any>;
-    constructor(config: ORMConfig);
+    _client?: Knex;
+    handler?: Handler<Table<any>>;
+    _rawCache?: CachedQuery<[raw: string], Knex.Raw>;
+    /**
+     * Creates a new ORM instance.
+     *
+     * @param config - The ORM configuration, or `false` to create an unconnected instance.
+     *
+     * When `false` is passed, the ORM will not connect to any database.
+     * This is useful for scenarios where you only need to export types or
+     * use the ORM structure without an actual database connection.
+     *
+     * Methods that require a database connection will throw an error
+     * if called on an unconnected ORM instance.
+     */
+    constructor(config: ORMConfig | false);
+    private requireClient;
+    get client(): Knex;
+    /**
+     * Returns true if the ORM has a database client connected.
+     */
+    get isConnected(): boolean;
     get cachedTables(): Table<any>[];
     get cachedTableNames(): string[];
     hasCachedTable(name: string): boolean;

package/dist/app/orm.js

@@ -1,19 +1,49 @@
 import url from "node:url";
 import { Handler } from "@ghom/handler";
+import { CachedQuery } from "@ghom/query";
 import { default as knex } from "knex";
-import { isCJS } from "./util.js";
+import { backupTable, disableForeignKeys, enableForeignKeys, restoreBackup } from "./backup.js";
 import { Table } from "./table.js";
-import { CachedQuery } from "@ghom/query";
-import { backupTable, restoreBackup, disableForeignKeys, enableForeignKeys, } from "./backup.js";
+import { isCJS } from "./util.js";
+/**
+ * The main ORM class that manages database connections, tables, and caching.
+ *
+ * @example
+ * // With database connection
+ * const orm = new ORM({
+ *   tableLocation: "./tables",
+ *   database: { client: "sqlite3", connection: { filename: ":memory:" } }
+ * })
+ * await orm.init()
+ *
+ * @example
+ * // Without database connection (for type exports only)
+ * const orm = new ORM(false)
+ * orm.isConnected // false
+ */
 export class ORM {
     config;
     _ready = false;
-    client;
+    _client;
     handler;
     _rawCache;
+    /**
+     * Creates a new ORM instance.
+     *
+     * @param config - The ORM configuration, or `false` to create an unconnected instance.
+     *
+     * When `false` is passed, the ORM will not connect to any database.
+     * This is useful for scenarios where you only need to export types or
+     * use the ORM structure without an actual database connection.
+     *
+     * Methods that require a database connection will throw an error
+     * if called on an unconnected ORM instance.
+     */
     constructor(config) {
         this.config = config;
-        this.client = knex(config.database ?? {
+        if (config === false)
+            return;
+        this._client = knex(config.database ?? {
             client: "sqlite3",
             useNullAsDefault: true,
             connection: {
@@ -31,7 +61,23 @@ export class ORM {
         });
         this._rawCache = new CachedQuery(async (raw) => await this.raw(raw), config.caching ?? Infinity);
     }
+    requireClient() {
+        if (!this._client)
+            throw new Error("ORM client is not initialized. Cannot use this method without a database connection.");
+    }
+    get client() {
+        this.requireClient();
+        return this._client;
+    }
+    /**
+     * Returns true if the ORM has a database client connected.
+     */
+    get isConnected() {
+        return this._client !== undefined;
+    }
     get cachedTables() {
+        if (!this.handler)
+            return [];
         return [...this.handler.elements.values()];
     }
     get cachedTableNames() {
@@ -41,12 +87,14 @@ export class ORM {
         return this.cachedTables.some((table) => table.options.name === name);
     }
     async hasTable(name) {
-        return this.client.schema.hasTable(name);
+        this.requireClient();
+        return this._client.schema.hasTable(name);
     }
     /**
      * Handle the table files and create the tables in the database.
      */
     async init() {
+        this.requireClient();
         await this.handler.init();
         try {
             await enableForeignKeys(this);
@@ -55,10 +103,10 @@ export class ORM {
         this.handler.elements.set("migration", new Table({
             name: "migration",
             priority: Infinity,
-            setup: (table) => {
-                table.string("table").unique().notNullable();
-                table.integer("version").notNullable();
-            },
+            columns: (col) => ({
+                table: col.string().unique(),
+                version: col.integer(),
+            }),
         }));
         const sortedTables = this.cachedTables.toSorted((a, b) => (b.options.priority ?? 0) - (a.options.priority ?? 0));
         for (const table of sortedTables) {
@@ -67,22 +115,26 @@ export class ORM {
         this._ready = true;
     }
     raw(sql) {
+        this.requireClient();
         if (this._ready)
             this.cache.invalidate();
-        return this.client.raw(sql);
+        return this._client.raw(sql);
     }
     cache = {
         raw: (sql, anyDataUpdated) => {
+            this.requireClient();
             if (anyDataUpdated)
                 this.cache.invalidate();
             return this._rawCache.get(sql, sql);
         },
         invalidate: () => {
-            this._rawCache.invalidate();
+            this._rawCache?.invalidate();
             this.cachedTables.forEach((table) => table.cache.invalidate());
         },
     };
     clientBasedOperation(operation) {
+        if (this.config === false)
+            return undefined;
         const client = (this.config.database?.client ?? "sqlite3");
         return operation[client]?.();
     }
@@ -91,7 +143,8 @@ export class ORM {
      * The backup will be saved in the location specified in the config.
      */
     async createBackup(dirname) {
-        for (let table of this.cachedTables) {
+        this.requireClient();
+        for (const table of this.cachedTables) {
             await backupTable(table, dirname);
         }
         console.log("Database backup created.");
@@ -101,8 +154,9 @@ export class ORM {
      * @warning This will delete all the data in the tables.
      */
     async restoreBackup(dirname) {
+        this.requireClient();
         await disableForeignKeys(this, async (trx) => {
-            for (let table of this.cachedTables) {
+            for (const table of this.cachedTables) {
                 await restoreBackup(table, trx, dirname);
             }
         });

package/dist/app/table.d.ts

@@ -1,11 +1,16 @@
-import { Knex } from "knex";
-import { ORM } from "./orm.js";
 import { CachedQuery } from "@ghom/query";
+import type { Knex } from "knex";
+import { type ColumnDef, type InferColumns } from "./column.js";
+import type { ORM } from "./orm.js";
 export interface MigrationData {
     table: string;
     version: number;
 }
-export interface TableOptions<Type extends object = object> {
+/**
+ * Table options with typed columns.
+ * Type is automatically inferred from the column definitions.
+ */
+export interface TableOptions<Columns extends Record<string, ColumnDef<any, any>>> {
     name: string;
     description?: string;
     priority?: number;
@@ -15,22 +20,48 @@ export interface TableOptions<Type extends object = object> {
      */
     caching?: number;
     migrations?: {
-        [version: number]: (table: Knex.CreateTableBuilder) => void;
+        [version: number]: (builder: Knex.CreateTableBuilder) => void;
     };
-    then?: (this: Table<Type>, table: Table<Type>) => unknown;
-    setup: (table: Knex.CreateTableBuilder) => void;
+    then?: (this: Table<Columns>, table: Table<Columns>) => unknown;
+    /**
+     * Typed columns definition with automatic type inference.
+     *
+     * @example
+     * columns: (col) => ({
+     *   id: col.increments(),
+     *   username: col.string().unique(),
+     *   age: col.integer().nullable(),
+     *   role: col.enum(["admin", "user"]),
+     * })
+     */
+    columns: (col: typeof import("./column.js").col) => Columns;
 }
-export declare class Table<Type extends object = object> {
-    readonly options: TableOptions<Type>;
+/**
+ * Represents a database table with typed columns.
+ *
+ * @example
+ * const userTable = new Table({
+ *   name: "user",
+ *   columns: (col) => ({
+ *     id: col.increments(),
+ *     username: col.string().unique(),
+ *     age: col.integer().nullable(),
+ *   }),
+ * })
+ * // Type is automatically inferred as { id: number; username: string; age: number | null }
+ */
+export declare class Table<Columns extends Record<string, ColumnDef<any, any>> = Record<string, ColumnDef<any, any>>> {
+    readonly options: TableOptions<Columns>;
     orm?: ORM;
-    _whereCache?: CachedQuery<[
-        cb: (query: Table<Type>["query"]) => unknown
-    ], unknown>;
+    _whereCache?: CachedQuery<[cb: (query: Table<Columns>["query"]) => unknown], unknown>;
     _countCache?: CachedQuery<[where: string | null], number>;
-    constructor(options: TableOptions<Type>);
-    get db(): Knex<any, unknown[]>;
-    get query(): Knex.QueryBuilder<Type, {
-        _base: Type;
+    constructor(options: TableOptions<Columns>);
+    /** The inferred TypeScript type for rows of this table */
+    readonly $type: InferColumns<Columns>;
+    private requireOrm;
+    get client(): Knex;
+    get query(): Knex.QueryBuilder<InferColumns<Columns>, {
+        _base: InferColumns<Columns>;
         _hasSelection: false;
         _keys: never;
         _aliases: {};
@@ -39,16 +70,16 @@ export declare class Table<Type extends object = object> {
         _unionProps: never;
     }[]>;
     get cache(): {
-        get: <Return>(id: string, cb: (table: Pick<Table<Type>["query"], "select" | "count" | "avg" | "sum" | "countDistinct" | "avgDistinct" | "sumDistinct">) => Return) => Return;
-        set: <Return>(cb: (table: Pick<Table<Type>["query"], "update" | "delete" | "insert" | "upsert" | "truncate" | "jsonInsert">) => Return) => Return;
+        get: <Return>(id: string, cb: (table: Pick<Table<Columns>["query"], "select" | "count" | "avg" | "sum" | "countDistinct" | "avgDistinct" | "sumDistinct">) => Return) => Return;
+        set: <Return>(cb: (table: Pick<Table<Columns>["query"], "update" | "delete" | "insert" | "upsert" | "truncate" | "jsonInsert">) => Return) => Return;
         count: (where?: string) => Promise<number>;
         invalidate: () => void;
     };
     count(where?: string): Promise<number>;
-    hasColumn(name: keyof Type & string): Promise<boolean>;
-    getColumn(name: keyof Type & string): Promise<Knex.ColumnInfo>;
-    getColumns(): Promise<Record<keyof Type & string, Knex.ColumnInfo>>;
-    getColumnNames(): Promise<Array<keyof Type & string>>;
+    hasColumn(name: keyof InferColumns<Columns> & string): Promise<boolean>;
+    getColumn(name: keyof InferColumns<Columns> & string): Promise<Knex.ColumnInfo>;
+    getColumns(): Promise<Record<keyof InferColumns<Columns> & string, Knex.ColumnInfo>>;
+    getColumnNames(): Promise<Array<keyof InferColumns<Columns> & string>>;
     isEmpty(): Promise<boolean>;
     make(orm: ORM): Promise<this>;
     private migrate;

package/dist/app/table.js

@@ -1,5 +1,20 @@
-import { styled } from "./util.js";
 import { CachedQuery } from "@ghom/query";
+import { buildColumnsSchema, col } from "./column.js";
+import { styled } from "./util.js";
+/**
+ * Represents a database table with typed columns.
+ *
+ * @example
+ * const userTable = new Table({
+ *   name: "user",
+ *   columns: (col) => ({
+ *     id: col.increments(),
+ *     username: col.string().unique(),
+ *     age: col.integer().nullable(),
+ *   }),
+ * })
+ * // Type is automatically inferred as { id: number; username: string; age: number | null }
+ */
 export class Table {
     options;
     orm;
@@ -8,19 +23,23 @@ export class Table {
     constructor(options) {
         this.options = options;
     }
-    get db() {
+    requireOrm() {
         if (!this.orm)
             throw new Error("missing ORM");
+        if (!this.orm._client)
+            throw new Error("ORM client is not initialized");
+    }
+    get client() {
+        this.requireOrm();
         return this.orm.client;
     }
     get query() {
-        return this.db(this.options.name);
+        return this.client(this.options.name);
     }
     get cache() {
         if (!this._whereCache || !this._countCache)
             throw new Error("missing cache");
-        if (!this.orm)
-            throw new Error("missing ORM");
+        this.requireOrm();
         return {
             get: (id, cb) => {
                 return this._whereCache.get(id, cb);
@@ -42,18 +61,18 @@ export class Table {
     }
     async count(where) {
         return this.query
-            .select(this.db.raw("count(*) as total"))
+            .select(this.client.raw("count(*) as total"))
             .whereRaw(where ?? "1=1")
             .then((rows) => +(rows?.[0] ?? { total: 0 }).total);
     }
     async hasColumn(name) {
-        return this.db.schema.hasColumn(this.options.name, name);
+        return this.client.schema.hasColumn(this.options.name, name);
     }
     async getColumn(name) {
-        return this.db(this.options.name).columnInfo(name);
+        return this.client(this.options.name).columnInfo(name);
     }
     async getColumns() {
-        return this.db(this.options.name).columnInfo();
+        return this.client(this.options.name).columnInfo();
     }
     async getColumnNames() {
         return this.getColumns().then(Object.keys);
@@ -63,18 +82,22 @@ export class Table {
     }
     async make(orm) {
         this.orm = orm;
-        this._whereCache = new CachedQuery((cb) => cb(this.query), this.options.caching ?? this.orm?.config.caching ?? Infinity);
-        this._countCache = new CachedQuery((where) => this.count(where ?? undefined), this.options.caching ?? this.orm?.config.caching ?? Infinity);
+        this.requireOrm();
+        this._whereCache = new CachedQuery((cb) => cb(this.query), this.options.caching ?? this.orm.config.caching ?? Infinity);
+        this._countCache = new CachedQuery((where) => this.count(where ?? undefined), this.options.caching ?? this.orm.config.caching ?? Infinity);
         const tableNameLog = `table ${styled(this.orm, this.options.name, "highlight")}${this.options.description
             ? ` ${styled(this.orm, this.options.description, "description")}`
             : ""}`;
         try {
-            await this.db.schema.createTable(this.options.name, this.options.setup);
+            await this.client.schema.createTable(this.options.name, (builder) => {
+                const columns = this.options.columns(col);
+                buildColumnsSchema(builder, columns);
+            });
             this.orm.config.logger?.log(`created table ${tableNameLog}`);
         }
         catch (error) {
             if (error.toString().includes("syntax error")) {
-                this.orm.config.logger?.error(`you need to implement the "setup" method in options of your ${styled(this.orm, this.options.name, "highlight")} table!`);
+                this.orm.config.logger?.error(`you need to implement the "columns" callback in options of your ${styled(this.orm, this.options.name, "highlight")} table!`);
                 throw error;
             }
             else {
@@ -91,8 +114,10 @@ export class Table {
             this.orm.config.logger?.error(error);
             throw error;
         }
-        if ((await this.count()) === 0)
-            await this.options.then?.bind(this)(this);
+        if ((await this.count()) === 0) {
+            const thenFn = this.options.then;
+            await thenFn?.bind(this)(this);
+        }
         return this;
     }
     async migrate() {
@@ -101,7 +126,7 @@ export class Table {
         const migrations = new Map(Object.entries(this.options.migrations)
             .sort((a, b) => Number(a[0]) - Number(b[0]))
             .map((entry) => [Number(entry[0]), entry[1]]));
-        const fromDatabase = await this.db("migration")
+        const fromDatabase = await this.client("migration")
             .where("table", this.options.name)
             .first();
         const data = fromDatabase || {
@@ -110,17 +135,14 @@ export class Table {
         };
         const baseVersion = data.version;
         for (const [version, migration] of migrations) {
-            await this.db.schema.alterTable(this.options.name, (builder) => {
+            await this.client.schema.alterTable(this.options.name, (builder) => {
                 if (version <= data.version)
                     return;
                 migration(builder);
                 data.version = version;
             });
         }
-        await this.db("migration")
-            .insert(data)
-            .onConflict("table")
-            .merge();
+        await this.client("migration").insert(data).onConflict("table").merge();
         return baseVersion === data.version ? false : data.version;
     }
 }

package/dist/app/util.d.ts

@@ -4,7 +4,7 @@ export type TextStyle = Parameters<typeof util.styleText>[0];
 export declare const DEFAULT_BACKUP_LOCATION: string;
 export declare const DEFAULT_BACKUP_CHUNK_SIZE: number;
 export declare const DEFAULT_LOGGER_HIGHLIGHT = "blueBright";
-export declare const DEFAULT_LOGGER_DESCRIPTION = "grey";
+export declare const DEFAULT_LOGGER_DESCRIPTION = "gray";
 export declare const DEFAULT_LOGGER_RAW_VALUE = "magentaBright";
 declare let isCJS: boolean;
 export { isCJS };

package/dist/app/util.js

@@ -1,15 +1,15 @@
-import util from "node:util";
-import path from "node:path";
 import fs from "node:fs";
+import path from "node:path";
+import util from "node:util";
 export const DEFAULT_BACKUP_LOCATION = path.join(process.cwd(), "backup");
 export const DEFAULT_BACKUP_CHUNK_SIZE = 5 * 1024 * 1024; // 5MB
 export const DEFAULT_LOGGER_HIGHLIGHT = "blueBright";
-export const DEFAULT_LOGGER_DESCRIPTION = "grey";
+export const DEFAULT_LOGGER_DESCRIPTION = "gray";
 export const DEFAULT_LOGGER_RAW_VALUE = "magentaBright";
 let isCJS = false;
 try {
     const pack = JSON.parse(fs.readFileSync(path.join(process.cwd(), "package.json"), "utf8"));
-    isCJS = pack.type === "commonjs" || pack.type == void 0;
+    isCJS = pack.type === "commonjs" || pack.type === void 0;
 }
 catch {
     throw new Error("Missing package.json: Can't detect the type of modules.\n" +
@@ -18,7 +18,8 @@ catch {
 }
 export { isCJS };
 export function styled(orm, message, style) {
-    return util.styleText(orm.config.loggerStyles?.[style] ??
+    const config = orm.config !== false ? orm.config : undefined;
+    return util.styleText(config?.loggerStyles?.[style] ??
         (style === "highlight"
             ? DEFAULT_LOGGER_HIGHLIGHT
             : style === "rawValue"

package/dist/index.d.ts

@@ -1,4 +1,5 @@
+export * from "./app/backup.js";
+export * from "./app/column.js";
 export * from "./app/orm.js";
 export * from "./app/table.js";
-export * from "./app/backup.js";
 export * from "./app/util.js";

package/dist/index.js

@@ -1,4 +1,5 @@
+export * from "./app/backup.js";
+export * from "./app/column.js";
 export * from "./app/orm.js";
 export * from "./app/table.js";
-export * from "./app/backup.js";
 export * from "./app/util.js";

package/package.json

@@ -1,47 +1,43 @@
-{
-  "name": "@ghom/orm",
-  "version": "1.9.2",
-  "license": "MIT",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "description": "TypeScript KnexJS ORM & handler",
-  "homepage": "https://github.com/GhomKrosmonaute/orm",
-  "prettier": {
-    "semi": false
-  },
-  "scripts": {
-    "format": "prettier --write src tsconfig.json tests",
-    "build": "rimraf dist && tsc",
-    "test": "npm run build && node --experimental-vm-modules node_modules/jest/bin/jest.js tests/test.js --detectOpenHandles",
-    "prepublishOnly": "npm run format && npm test"
-  },
-  "devDependencies": {
-    "@types/jest": "^29.5.6",
-    "@types/node": "^22.0.0",
-    "dotenv": "^16.3.1",
-    "jest": "^29.7.0",
-    "prettier": "^3.0.3",
-    "rimraf": "^6.0.1",
-    "typescript": "^5.2.2"
-  },
-  "optionalDependencies": {
-    "mysql2": "^3.6.2",
-    "pg": "^8.11.3",
-    "sqlite3": "^5.1.6"
-  },
-  "dependencies": {
-    "@ghom/handler": "^3.1.0",
-    "@ghom/query": "1.0.0",
-    "csv-parser": "^3.0.0",
-    "json-2-csv": "^5.5.6",
-    "knex": "^3.0.1"
-  },
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "repository": {
-    "url": "https://github.com/GhomKrosmonaute/orm.git",
-    "type": "git"
-  }
-}
+{
+  "name": "@ghom/orm",
+  "version": "2.0.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "description": "TypeScript KnexJS ORM & handler",
+  "homepage": "https://github.com/GhomKrosmonaute/orm",
+  "scripts": {
+    "format": "biome format --write src",
+    "lint": "biome lint .",
+    "check": "biome check --write .",
+    "build": "rimraf dist && tsc",
+    "test": "bun test",
+    "prepublishOnly": "npm run check && npm run build && npm test"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.13",
+    "@types/bun": "^1.1.0",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.2.2"
+  },
+  "optionalDependencies": {
+    "mysql2": "^3.6.2",
+    "pg": "^8.11.3",
+    "sqlite3": "^5.1.6"
+  },
+  "dependencies": {
+    "@ghom/handler": "^3.1.0",
+    "@ghom/query": "1.0.0",
+    "csv-parser": "^3.0.0",
+    "json-2-csv": "^5.5.6",
+    "knex": "^3.0.1"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "url": "https://github.com/GhomKrosmonaute/orm.git",
+    "type": "git"
+  }
+}

package/readme.md

@@ -41,6 +41,25 @@ const orm = new ORM({
 await orm.init()
 ```
 
+### Unconnected ORM
+
+You can also create an ORM instance without connecting to a database. This is useful when you only need to export types or prepare the ORM structure for a future database connection.
+
+```typescript
+import { ORM } from "@ghom/orm"
+
+const orm = new ORM(false)
+
+orm.isConnected // false
+orm.cachedTables // []
+orm.cachedTableNames // []
+
+// Methods requiring a database connection will throw an error
+orm.init() // throws Error
+orm.hasTable("user") // throws Error
+orm.raw("SELECT 1") // throws Error
+```
+
 ## Add tables
 
 The tables are automatically loaded from the `location` directory.