@ghom/orm 1.9.1 → 1.10.0

package/dist/app/backup.js

@@ -3,13 +3,19 @@ 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";
+function getConfig(orm) {
+    if (orm.config === false)
+        throw new Error("ORM config is not available");
+    return orm.config;
+}
 export async function backupTable(table, dirname) {
     if (!table.orm)
         throw new Error("missing ORM");
+    const config = getConfig(table.orm);
     let offset = 0;
     let processedRows = 0;
     let chunkIndex = 0;
-    const chunkDir = path.join(table.orm.config.backups?.location ?? DEFAULT_BACKUP_LOCATION, dirname ?? "");
+    const chunkDir = path.join(config.backups?.location ?? DEFAULT_BACKUP_LOCATION, dirname ?? "");
     if (!fs.existsSync(chunkDir)) {
         fs.mkdirSync(chunkDir, { recursive: true });
         console.log(`Backup directory ${styled(table.orm, path.relative(process.cwd(), chunkDir), "highlight")} created.`);
@@ -28,7 +34,7 @@ export async function backupTable(table, dirname) {
             // Si aucun fichier n'est créé ou qu'on a dépassé la taille max du chunk, on crée un nouveau fichier CSV
             if (!writeStream ||
                 writeStream.bytesWritten + Buffer.byteLength(csvData, "utf8") >
-                    (table.orm.config.backups?.chunkSize ?? DEFAULT_BACKUP_CHUNK_SIZE)) {
+                    (config.backups?.chunkSize ?? DEFAULT_BACKUP_CHUNK_SIZE)) {
                 if (writeStream) {
                     closePromises.push(new Promise((resolve) => writeStream.end(resolve))); // Ajouter la promesse de fermeture
                 }
@@ -58,7 +64,8 @@ export async function backupTable(table, dirname) {
 export async function restoreBackup(table, trx, dirname) {
     if (!table.orm)
         throw new Error("missing ORM");
-    const chunkDir = path.join(table.orm.config.backups?.location ?? DEFAULT_BACKUP_LOCATION, dirname ?? "");
+    const config = getConfig(table.orm);
+    const chunkDir = path.join(config.backups?.location ?? DEFAULT_BACKUP_LOCATION, dirname ?? "");
     const chunkFiles = fs
         .readdirSync(chunkDir)
         .filter((file) => file.split("_chunk_")[0] === table.options.name);
@@ -112,6 +119,8 @@ export async function enableForeignKeys(orm, trx) {
     });
 }
 export async function disableForeignKeys(orm, run) {
+    if (!orm.client)
+        throw new Error("ORM client is not initialized");
     const trx = orm.clientBasedOperation({
         sqlite3: () => orm.client,
     }) ?? (await orm.client.transaction());

package/dist/app/orm.d.ts

@@ -2,7 +2,7 @@ import { Handler } from "@ghom/handler";
 import { Knex } from "knex";
 import { TextStyle } from "./util.js";
 import { Table } from "./table.js";
-import { ResponseCache } from "./caching.js";
+import { CachedQuery } from "@ghom/query";
 export interface ILogger {
     log: (message: string) => void;
     error: (error: string | Error) => void;
@@ -44,13 +44,46 @@ 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: ResponseCache<[raw: string], Knex.Raw<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;
+    /**
+     * Returns true if the ORM has a database client connected.
+     */
+    get isConnected(): boolean;
     get cachedTables(): Table<any>[];
     get cachedTableNames(): string[];
     hasCachedTable(name: string): boolean;
@@ -61,7 +94,7 @@ export declare class ORM {
     init(): Promise<void>;
     raw(sql: Knex.Value): Knex.Raw;
     cache: {
-        raw: (sql: string, anyDataUpdated?: boolean) => Knex.Raw;
+        raw: (sql: string, anyDataUpdated?: boolean) => Promise<Knex.Raw>;
         invalidate: () => void;
     };
     clientBasedOperation<Return>(operation: Partial<Record<"pg" | "mysql2" | "sqlite3", () => Return>>): Return | undefined;

package/dist/app/orm.js

@@ -3,16 +3,46 @@ import { Handler } from "@ghom/handler";
 import { default as knex } from "knex";
 import { isCJS } from "./util.js";
 import { Table } from "./table.js";
-import { ResponseCache } from "./caching.js";
+import { CachedQuery } from "@ghom/query";
 import { backupTable, restoreBackup, disableForeignKeys, enableForeignKeys, } from "./backup.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;
     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;
+        if (config === false)
+            return;
         this.client = knex(config.database ?? {
             client: "sqlite3",
             useNullAsDefault: true,
@@ -29,9 +59,21 @@ export class ORM {
                 throw new Error(`${filepath}: default export must be a Table instance`);
             },
         });
-        this._rawCache = new ResponseCache((raw) => this.raw(raw), config.caching ?? Infinity);
+        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.");
+    }
+    /**
+     * 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 +83,14 @@ export class ORM {
         return this.cachedTables.some((table) => table.options.name === name);
     }
     async 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);
@@ -67,22 +111,26 @@ export class ORM {
         this._ready = true;
     }
     raw(sql) {
+        this.requireClient();
         if (this._ready)
             this.cache.invalidate();
         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,6 +139,7 @@ export class ORM {
      * The backup will be saved in the location specified in the config.
      */
     async createBackup(dirname) {
+        this.requireClient();
         for (let table of this.cachedTables) {
             await backupTable(table, dirname);
         }
@@ -101,6 +150,7 @@ 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) {
                 await restoreBackup(table, trx, dirname);

package/dist/app/table.d.ts

@@ -1,6 +1,6 @@
 import { Knex } from "knex";
 import { ORM } from "./orm.js";
-import { ResponseCache } from "./caching.js";
+import { CachedQuery } from "@ghom/query";
 export interface MigrationData {
     table: string;
     version: number;
@@ -23,12 +23,13 @@ export interface TableOptions<Type extends object = object> {
 export declare class Table<Type extends object = object> {
     readonly options: TableOptions<Type>;
     orm?: ORM;
-    _whereCache?: ResponseCache<[
+    _whereCache?: CachedQuery<[
         cb: (query: Table<Type>["query"]) => unknown
     ], unknown>;
-    _countCache?: ResponseCache<[where: string | null], Promise<number>>;
+    _countCache?: CachedQuery<[where: string | null], number>;
     constructor(options: TableOptions<Type>);
-    get db(): Knex<any, unknown[]>;
+    private requireOrm;
+    get db(): Knex;
     get query(): Knex.QueryBuilder<Type, {
         _base: Type;
         _hasSelection: false;

package/dist/app/table.js

@@ -1,5 +1,5 @@
 import { styled } from "./util.js";
-import { ResponseCache } from "./caching.js";
+import { CachedQuery } from "@ghom/query";
 export class Table {
     options;
     orm;
@@ -8,9 +8,14 @@ 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 db() {
+        this.requireOrm();
         return this.orm.client;
     }
     get query() {
@@ -19,8 +24,7 @@ export class Table {
     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);
@@ -63,8 +67,9 @@ export class Table {
     }
     async make(orm) {
         this.orm = orm;
-        this._whereCache = new ResponseCache((cb) => cb(this.query), this.options.caching ?? this.orm?.config.caching ?? Infinity);
-        this._countCache = new ResponseCache((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")}`
             : ""}`;

package/dist/app/util.js

@@ -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,5 +1,4 @@
 export * from "./app/orm.js";
 export * from "./app/table.js";
-export * from "./app/caching.js";
 export * from "./app/backup.js";
 export * from "./app/util.js";

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghom/orm",
-  "version": "1.9.1",
+  "version": "1.10.0",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -32,6 +32,7 @@
   },
   "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"

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.

package/tests/test.js

@@ -16,6 +16,30 @@ import a from "./tables/a"
 import b from "./tables/b"
 import c from "./tables/c"
 
+describe("unconnected ORM", () => {
+  test("can be initialized with false", () => {
+    const unconnectedOrm = new ORM(false)
+
+    expect(unconnectedOrm).toBeInstanceOf(ORM)
+    expect(unconnectedOrm.isConnected).toBe(false)
+    expect(unconnectedOrm.config).toBe(false)
+    expect(unconnectedOrm.client).toBeUndefined()
+    expect(unconnectedOrm.handler).toBeUndefined()
+    expect(unconnectedOrm.cachedTables).toEqual([])
+    expect(unconnectedOrm.cachedTableNames).toEqual([])
+  })
+
+  test("throws when calling methods requiring client", async () => {
+    const unconnectedOrm = new ORM(false)
+
+    await expect(unconnectedOrm.init()).rejects.toThrow()
+    await expect(unconnectedOrm.hasTable("test")).rejects.toThrow()
+    expect(() => unconnectedOrm.raw("SELECT 1")).toThrow()
+    await expect(unconnectedOrm.createBackup()).rejects.toThrow()
+    await expect(unconnectedOrm.restoreBackup()).rejects.toThrow()
+  })
+})
+
 const orm = new ORM({
   tableLocation: path.join(process.cwd(), "tests", "tables"),
   backups: {

package/dist/app/caching.d.ts

@@ -1,18 +0,0 @@
-export interface ResponseCacheData<Value> {
-    value: Value;
-    expires: number;
-    outdated?: boolean;
-}
-/**
- * Advanced cache for async queries
- */
-export declare class ResponseCache<Params extends any[], Value> {
-    private _request;
-    private _timeout;
-    private _cache;
-    constructor(_request: (...params: Params) => Value, _timeout: number);
-    get(id: string, ...params: Params): Value;
-    fetch(id: string, ...params: Params): Value;
-    invalidate(): void;
-    invalidate(id: string): void;
-}

package/dist/app/caching.js

@@ -1,36 +0,0 @@
-/**
- * Advanced cache for async queries
- */
-export class ResponseCache {
-    _request;
-    _timeout;
-    _cache = new Map();
-    constructor(_request, _timeout) {
-        this._request = _request;
-        this._timeout = _timeout;
-    }
-    get(id, ...params) {
-        const cached = this._cache.get(id);
-        if (!cached || cached.expires < Date.now()) {
-            this._cache.set(id, {
-                value: this._request(...params),
-                expires: Date.now() + this._timeout,
-            });
-        }
-        return this._cache.get(id).value;
-    }
-    fetch(id, ...params) {
-        this._cache.set(id, {
-            value: this._request(...params),
-            expires: Date.now() + this._timeout,
-        });
-        return this._cache.get(id).value;
-    }
-    invalidate(id) {
-        if (!id) {
-            this._cache.clear();
-            return;
-        }
-        this._cache.delete(id);
-    }
-}