@quatrain/backend-sqlite 1.1.6 → 1.1.8

package/dist/SQLiteAdapter.d.ts

@@ -2,16 +2,20 @@ import { DataObjectClass, AbstractBackendAdapter, BackendParameters, QueryResult
 import sqlite3 from 'sqlite3';
 import { Database } from 'sqlite';
 /**
- * SQLite Backend Adapter for Quatrain
+ * Backend adapter implementation for SQLite databases.
+ * Uses the `sqlite` driver to provide a fast, local relational store without external dependencies.
+ * Highly useful for local development, CI/CD testing environments, or lightweight local deployments.
  */
 export declare class SQLiteAdapter extends AbstractBackendAdapter {
     protected _connection: undefined | Database<sqlite3.Database>;
     protected _dbPath: string;
     constructor(params?: BackendParameters);
-    protected _buildPath(dataObject: DataObjectClass<any>, uid?: string): string;
     /**
-     * Executes a raw query on the backend.
-     * Only supported by SQL adapters.
+     * Executes an arbitrary raw SQL query against the SQLite database.
+     *
+     * @param sql - The SQL statement with optional `?` parameterized placeholders.
+     * @param params - The array of parameter values.
+     * @returns A promise resolving to the SQLite result rows.
      */
     rawQuery(sql: string, params?: any[]): Promise<any>;
     protected _connect(): Promise<Database<sqlite3.Database>>;
@@ -21,22 +25,51 @@ export declare class SQLiteAdapter extends AbstractBackendAdapter {
      * @param filterNulls
      * @returns
      */
-    protected _prepareData(data: any, filterNulls?: boolean): any;
+    protected _prepareData(data: any, filterNulls?: boolean): any[];
     /**
      * Ensure the collection table exists in SQLite
      * @param dataObject DataObject to create table for
      */
     private _ensureTable;
     /**
-     * Create record in backend
-     * @param dataObject DataObject instance to persist in backend
-     * @param desiredUid Desired unique ID for record
-     * @returns DataObject
+     * Translates a DataObject creation request into an `INSERT INTO` SQL query.
+     * SQLite handles JSON by parsing array properties internally.
+     *
+     * @param dataObject - The DataObject payload.
+     * @param desiredUid - Optional explicit UUID.
+     * @returns A promise resolving to the saved DataObject.
      */
     create(dataObject: DataObjectClass<any>, desiredUid: string | undefined): Promise<DataObjectClass<any>>;
+    /**
+     * Executes a `SELECT *` query to retrieve a document by its UID.
+     * Handles mapping of JSON text columns back into arrays/objects.
+     *
+     * @param dataObject - The empty DataObject containing the target path.
+     * @returns A promise resolving to the hydrated DataObject.
+     */
     read(dataObject: DataObjectClass<any>): Promise<DataObjectClass<any>>;
+    /**
+     * Processes an `UPDATE` command for modified object properties.
+     * Automatically ensures the table exists and properly escapes JSON-backed properties.
+     *
+     * @param dataObject - The modified DataObject.
+     * @returns A promise resolving to the updated instance.
+     */
     update(dataObject: DataObjectClass<any>): Promise<DataObjectClass<any>>;
+    /**
+     * Generates a `DELETE FROM` or `UPDATE` query depending on the `hardDelete` parameter.
+     *
+     * @param dataObject - The DataObject to remove.
+     * @param hardDelete - Force permanent deletion over soft delete.
+     * @returns A promise resolving upon completion.
+     */
     delete(dataObject: DataObjectClass<any>, hardDelete?: boolean): Promise<DataObjectClass<any>>;
+    /**
+     * Wipes all records from a table by executing a blanket `DELETE FROM`.
+     *
+     * @param collection - The table name to purge.
+     * @param batchSize - Ignored for SQLite bulk deletes.
+     */
     deleteCollection(collection: string, batchSize?: number): Promise<void>;
     /**
      * Convert array into SQL expression
@@ -45,12 +78,14 @@ export declare class SQLiteAdapter extends AbstractBackendAdapter {
      */
     protected _array2String(from: (string | number)[]): string;
     /**
-     * Execute a query on a collection
-     * @param dataObject
-     * @param filters
-     * @param pagination
-     * @params parent
-     * @returns
+     * Translates the Quatrain `Filters` logic into SQLite query syntax.
+     * Employs internal `json_each` extensions for Array-contains searches when JSON1 is available.
+     *
+     * @param dataObject - The targeted collection object.
+     * @param filters - Requested Query filters.
+     * @param pagination - Query Limits & Pagination rules.
+     * @param parent - Optional parent linkage.
+     * @returns A promise resolving to hydrated objects and metadata.
      */
     find(dataObject: DataObjectClass<any>, filters?: Filters | Filter[] | undefined, pagination?: SortAndLimit | undefined, parent?: DataObjectClass<any> | undefined): Promise<QueryResultType<DataObjectClass<any>>>;
     /**

package/dist/SQLiteAdapter.js

@@ -34,7 +34,9 @@ const operatorsMap = {
     isNotNull: 'IS NOT NULL',
 };
 /**
- * SQLite Backend Adapter for Quatrain
+ * Backend adapter implementation for SQLite databases.
+ * Uses the `sqlite` driver to provide a fast, local relational store without external dependencies.
+ * Highly useful for local development, CI/CD testing environments, or lightweight local deployments.
  */
 class SQLiteAdapter extends backend_1.AbstractBackendAdapter {
     constructor(params = {}) {
@@ -42,27 +44,12 @@ class SQLiteAdapter extends backend_1.AbstractBackendAdapter {
         super(params);
         this._dbPath = ((_a = params.config) === null || _a === void 0 ? void 0 : _a.database) || ':memory:';
     }
-    _buildPath(dataObject, uid) {
-        const collection = this.getCollection(dataObject);
-        if (!collection) {
-            throw new backend_1.BackendError(`[SQLA] Can't define record path without a collection name`);
-        }
-        // define document path
-        let path = `${collection}/${uid}`;
-        if (this._params.hierarchy &&
-            this._params.hierarchy[collection] ===
-                backend_1.CollectionHierarchy.SUBCOLLECTION &&
-            dataObject.parentProp &&
-            dataObject.has(dataObject.parentProp) &&
-            dataObject.val(dataObject.parentProp)) {
-            path = `${dataObject.val(dataObject.parentProp).path}/${path}`;
-        }
-        backend_1.Backend.info(`[SQLA] Record path is '${path}'`);
-        return path;
-    }
     /**
-     * Executes a raw query on the backend.
-     * Only supported by SQL adapters.
+     * Executes an arbitrary raw SQL query against the SQLite database.
+     *
+     * @param sql - The SQL statement with optional `?` parameterized placeholders.
+     * @param params - The array of parameter values.
+     * @returns A promise resolving to the SQLite result rows.
      */
     rawQuery(sql_1) {
         return __awaiter(this, arguments, void 0, function* (sql, params = []) {
@@ -114,21 +101,7 @@ class SQLiteAdapter extends backend_1.AbstractBackendAdapter {
                 data[key] = JSON.stringify(el);
             }
         });
-        if (this._params['useNativeForeignKeys'] &&
-            this._params['useNativeForeignKeys'] === true) {
-            data.forEach((el, key) => {
-                if (typeof el === 'object' &&
-                    el !== null &&
-                    Reflect.has(el, 'ref')) {
-                    const resourcePart = el.ref.split('/').pop();
-                    if (resourcePart.indexOf('.') === -1) {
-                        // convert reference for database objects only
-                        data[key] = el.ref.split('/').pop();
-                    }
-                }
-            });
-        }
-        return data;
+        return this._resolveNativeForeignKeys(data);
     }
     /**
      * Ensure the collection table exists in SQLite
@@ -175,10 +148,12 @@ class SQLiteAdapter extends backend_1.AbstractBackendAdapter {
         });
     }
     /**
-     * Create record in backend
-     * @param dataObject DataObject instance to persist in backend
-     * @param desiredUid Desired unique ID for record
-     * @returns DataObject
+     * Translates a DataObject creation request into an `INSERT INTO` SQL query.
+     * SQLite handles JSON by parsing array properties internally.
+     *
+     * @param dataObject - The DataObject payload.
+     * @param desiredUid - Optional explicit UUID.
+     * @returns A promise resolving to the saved DataObject.
      */
     create(dataObject, desiredUid) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -239,6 +214,13 @@ class SQLiteAdapter extends backend_1.AbstractBackendAdapter {
             }
         });
     }
+    /**
+     * Executes a `SELECT *` query to retrieve a document by its UID.
+     * Handles mapping of JSON text columns back into arrays/objects.
+     *
+     * @param dataObject - The empty DataObject containing the target path.
+     * @returns A promise resolving to the hydrated DataObject.
+     */
     read(dataObject) {
         return __awaiter(this, void 0, void 0, function* () {
             const path = dataObject.path;
@@ -303,6 +285,13 @@ class SQLiteAdapter extends backend_1.AbstractBackendAdapter {
             return dataObject;
         });
     }
+    /**
+     * Processes an `UPDATE` command for modified object properties.
+     * Automatically ensures the table exists and properly escapes JSON-backed properties.
+     *
+     * @param dataObject - The modified DataObject.
+     * @returns A promise resolving to the updated instance.
+     */
     update(dataObject) {
         return __awaiter(this, void 0, void 0, function* () {
             if (dataObject.uid === undefined) {
@@ -349,6 +338,13 @@ class SQLiteAdapter extends backend_1.AbstractBackendAdapter {
             return dataObject;
         });
     }
+    /**
+     * Generates a `DELETE FROM` or `UPDATE` query depending on the `hardDelete` parameter.
+     *
+     * @param dataObject - The DataObject to remove.
+     * @param hardDelete - Force permanent deletion over soft delete.
+     * @returns A promise resolving upon completion.
+     */
     delete(dataObject_1) {
         return __awaiter(this, arguments, void 0, function* (dataObject, hardDelete = false) {
             if (dataObject.uid === undefined) {
@@ -379,6 +375,12 @@ class SQLiteAdapter extends backend_1.AbstractBackendAdapter {
             return dataObject;
         });
     }
+    /**
+     * Wipes all records from a table by executing a blanket `DELETE FROM`.
+     *
+     * @param collection - The table name to purge.
+     * @param batchSize - Ignored for SQLite bulk deletes.
+     */
     deleteCollection(collection_1) {
         return __awaiter(this, arguments, void 0, function* (collection, batchSize = 500) {
             backend_1.Backend.log(`Deleting all records from collection '${collection}'`);
@@ -400,12 +402,14 @@ class SQLiteAdapter extends backend_1.AbstractBackendAdapter {
         return `'${JSON.stringify(from)}'`;
     }
     /**
-     * Execute a query on a collection
-     * @param dataObject
-     * @param filters
-     * @param pagination
-     * @params parent
-     * @returns
+     * Translates the Quatrain `Filters` logic into SQLite query syntax.
+     * Employs internal `json_each` extensions for Array-contains searches when JSON1 is available.
+     *
+     * @param dataObject - The targeted collection object.
+     * @param filters - Requested Query filters.
+     * @param pagination - Query Limits & Pagination rules.
+     * @param parent - Optional parent linkage.
+     * @returns A promise resolving to hydrated objects and metadata.
      */
     find(dataObject_1) {
         return __awaiter(this, arguments, void 0, function* (dataObject, filters = undefined, pagination = undefined, parent = undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quatrain/backend-sqlite",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "license": "AGPL-3.0-only",
   "description": "Backend adapter for SQLite",
   "main": "dist/index.js",
@@ -20,14 +20,15 @@
   },
   "author": "Quatrain Développement SAS <developers@quatrain.com>",
   "dependencies": {
-    "@quatrain/backend": "^1.2.4",
-    "@quatrain/core": "^1.2.5",
+    "@quatrain/backend": "^1.2.12",
+    "@quatrain/core": "^1.2.14",
     "sqlite": "^5.1.1",
     "sqlite3": "^5.1.7"
   },
   "devDependencies": {
     "@faker-js/faker": "^7.6.0",
     "@jest/expect": "^30.0.0",
+    "@quatrain/testing": "^1.1.4",
     "@tsconfig/recommended": "^1.0.1",
     "@types/jest": "^29.5.12",
     "@types/node": "^22.10.1",

package/src/SQLiteAdapter.ts

@@ -17,7 +17,6 @@ import {
    Filter,
    SortAndLimit,
    Sorting,
-   CollectionHierarchy,
 } from '@quatrain/backend'
 import { randomUUID } from 'node:crypto'
 import sqlite3, { Statement } from 'sqlite3'
@@ -40,7 +39,9 @@ const operatorsMap: { [x: string]: string } = {
 }
 
 /**
- * SQLite Backend Adapter for Quatrain
+ * Backend adapter implementation for SQLite databases.
+ * Uses the `sqlite` driver to provide a fast, local relational store without external dependencies.
+ * Highly useful for local development, CI/CD testing environments, or lightweight local deployments.
  */
 export class SQLiteAdapter extends AbstractBackendAdapter {
    protected _connection: undefined | Database<sqlite3.Database>
@@ -51,35 +52,14 @@ export class SQLiteAdapter extends AbstractBackendAdapter {
       this._dbPath = (params.config?.database as string) || ':memory:'
    }
 
-   protected _buildPath(dataObject: DataObjectClass<any>, uid?: string) {
-      const collection = this.getCollection(dataObject)
-      if (!collection) {
-         throw new BackendError(
-            `[SQLA] Can't define record path without a collection name`
-         )
-      }
-
-      // define document path
-      let path = `${collection}/${uid}`
-      if (
-         this._params.hierarchy &&
-         this._params.hierarchy[collection] ===
-            CollectionHierarchy.SUBCOLLECTION &&
-         dataObject.parentProp &&
-         dataObject.has(dataObject.parentProp) &&
-         dataObject.val(dataObject.parentProp)
-      ) {
-         path = `${dataObject.val(dataObject.parentProp).path}/${path}`
-      }
 
-      Backend.info(`[SQLA] Record path is '${path}'`)
-
-      return path
-   }
 
    /**
-    * Executes a raw query on the backend.
-    * Only supported by SQL adapters.
+    * Executes an arbitrary raw SQL query against the SQLite database.
+    * 
+    * @param sql - The SQL statement with optional `?` parameterized placeholders.
+    * @param params - The array of parameter values.
+    * @returns A promise resolving to the SQLite result rows.
     */
    async rawQuery(sql: string, params: any[] = []): Promise<any> {
       const connection = await this._connect()
@@ -132,26 +112,7 @@ export class SQLiteAdapter extends AbstractBackendAdapter {
          }
       })
 
-      if (
-         this._params['useNativeForeignKeys'] &&
-         this._params['useNativeForeignKeys'] === true
-      ) {
-         data.forEach((el: any, key: number) => {
-            if (
-               typeof el === 'object' &&
-               el !== null &&
-               Reflect.has(el, 'ref')
-            ) {
-               const resourcePart = el.ref.split('/').pop()
-               if (resourcePart.indexOf('.') === -1) {
-                  // convert reference for database objects only
-                  data[key] = el.ref.split('/').pop()
-               }
-            }
-         })
-      }
-
-      return data
+      return this._resolveNativeForeignKeys(data)
    }
 
    /**
@@ -205,10 +166,12 @@ export class SQLiteAdapter extends AbstractBackendAdapter {
    }
 
    /**
-    * Create record in backend
-    * @param dataObject DataObject instance to persist in backend
-    * @param desiredUid Desired unique ID for record
-    * @returns DataObject
+    * Translates a DataObject creation request into an `INSERT INTO` SQL query.
+    * SQLite handles JSON by parsing array properties internally.
+    * 
+    * @param dataObject - The DataObject payload.
+    * @param desiredUid - Optional explicit UUID.
+    * @returns A promise resolving to the saved DataObject.
     */
    async create(
       dataObject: DataObjectClass<any>,
@@ -295,6 +258,13 @@ export class SQLiteAdapter extends AbstractBackendAdapter {
       }
    }
 
+   /**
+    * Executes a `SELECT *` query to retrieve a document by its UID.
+    * Handles mapping of JSON text columns back into arrays/objects.
+    * 
+    * @param dataObject - The empty DataObject containing the target path.
+    * @returns A promise resolving to the hydrated DataObject.
+    */
    async read(dataObject: DataObjectClass<any>): Promise<DataObjectClass<any>> {
       const path = dataObject.path
       const collection = this.getCollection(dataObject)
@@ -382,6 +352,13 @@ export class SQLiteAdapter extends AbstractBackendAdapter {
       return dataObject
    }
 
+   /**
+    * Processes an `UPDATE` command for modified object properties.
+    * Automatically ensures the table exists and properly escapes JSON-backed properties.
+    * 
+    * @param dataObject - The modified DataObject.
+    * @returns A promise resolving to the updated instance.
+    */
    async update(
       dataObject: DataObjectClass<any>
    ): Promise<DataObjectClass<any>> {
@@ -450,6 +427,13 @@ export class SQLiteAdapter extends AbstractBackendAdapter {
       return dataObject
    }
 
+   /**
+    * Generates a `DELETE FROM` or `UPDATE` query depending on the `hardDelete` parameter.
+    * 
+    * @param dataObject - The DataObject to remove.
+    * @param hardDelete - Force permanent deletion over soft delete.
+    * @returns A promise resolving upon completion.
+    */
    async delete(
       dataObject: DataObjectClass<any>,
       hardDelete = false
@@ -491,6 +475,12 @@ export class SQLiteAdapter extends AbstractBackendAdapter {
       return dataObject
    }
 
+   /**
+    * Wipes all records from a table by executing a blanket `DELETE FROM`.
+    * 
+    * @param collection - The table name to purge.
+    * @param batchSize - Ignored for SQLite bulk deletes.
+    */
    async deleteCollection(collection: string, batchSize = 500): Promise<void> {
       Backend.log(`Deleting all records from collection '${collection}'`)
       const db = await this._connect()
@@ -517,12 +507,14 @@ export class SQLiteAdapter extends AbstractBackendAdapter {
    }
 
    /**
-    * Execute a query on a collection
-    * @param dataObject
-    * @param filters
-    * @param pagination
-    * @params parent
-    * @returns
+    * Translates the Quatrain `Filters` logic into SQLite query syntax.
+    * Employs internal `json_each` extensions for Array-contains searches when JSON1 is available.
+    * 
+    * @param dataObject - The targeted collection object.
+    * @param filters - Requested Query filters.
+    * @param pagination - Query Limits & Pagination rules.
+    * @param parent - Optional parent linkage.
+    * @returns A promise resolving to hydrated objects and metadata.
     */
    async find(
       dataObject: DataObjectClass<any>,