@quatrain/backend-sqlite 1.1.6 → 1.1.7

package/dist/SQLiteAdapter.d.ts

@@ -2,7 +2,9 @@ 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>;
@@ -10,8 +12,11 @@ export declare class SQLiteAdapter extends AbstractBackendAdapter {
     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>>;
@@ -28,15 +33,44 @@ export declare class SQLiteAdapter extends AbstractBackendAdapter {
      */
     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 +79,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 = {}) {
@@ -61,8 +63,11 @@ class SQLiteAdapter extends backend_1.AbstractBackendAdapter {
         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 = []) {
@@ -175,10 +180,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 +246,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 +317,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 +370,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 +407,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 +434,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.7",
   "license": "AGPL-3.0-only",
   "description": "Backend adapter for SQLite",
   "main": "dist/index.js",
@@ -20,7 +20,7 @@
   },
   "author": "Quatrain Développement SAS <developers@quatrain.com>",
   "dependencies": {
-    "@quatrain/backend": "^1.2.4",
+    "@quatrain/backend": "^1.2.7",
     "@quatrain/core": "^1.2.5",
     "sqlite": "^5.1.1",
     "sqlite3": "^5.1.7"
@@ -28,6 +28,7 @@
   "devDependencies": {
     "@faker-js/faker": "^7.6.0",
     "@jest/expect": "^30.0.0",
+    "@quatrain/testing": "^1.1.3",
     "@tsconfig/recommended": "^1.0.1",
     "@types/jest": "^29.5.12",
     "@types/node": "^22.10.1",

package/src/SQLiteAdapter.ts

@@ -40,7 +40,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>
@@ -78,8 +80,11 @@ export class SQLiteAdapter extends AbstractBackendAdapter {
    }
 
    /**
-    * 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()
@@ -205,10 +210,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 +302,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 +396,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 +471,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 +519,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 +551,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>,