@tmlmobilidade/utils 20250827.1228.57 → 20250827.1349.36

package/dist/src/databases/index.d.ts

@@ -1 +1,2 @@
 export * from './sqlite-map.js';
+export * from './sqlite-writer.js';

package/dist/src/databases/index.js

@@ -1 +1,2 @@
 export * from './sqlite-map.js';
+export * from './sqlite-writer.js';

package/dist/src/databases/sqlite-writer.d.ts

@@ -0,0 +1,63 @@
+interface SQLiteWriterColumn<T> {
+    indexed?: boolean;
+    name: Extract<keyof T, string>;
+    not_null?: boolean;
+    primary_key?: boolean;
+    type: 'BLOB' | 'INTEGER' | 'REAL' | 'TEXT';
+}
+export interface SQLiteWriterParams<T> {
+    /**
+     * The maximum number of items to hold in memory
+     * before flushing to the database.
+     * @default 3000
+     */
+    batch_size?: number;
+    /**
+     * Columns in the table.
+     * Order matters for INSERT.
+     * Must be keys of T or custom names.
+     */
+    columns: SQLiteWriterColumn<T>[];
+}
+export declare class SQLiteWriter<T> {
+    /**
+     * Get the number of rows in the table.
+     * @returns The number of rows.
+     */
+    get size(): number;
+    private batch;
+    private batchSize;
+    private columns;
+    private databaseInstance;
+    private insertStatement;
+    private instanceName;
+    constructor(params: SQLiteWriterParams<T>);
+    all(whereClause?: string, params?: (boolean | number | string)[]): T[];
+    /**
+     * Clears all entries from the map.
+     */
+    clear(): void;
+    /**
+     * Flush current buffer into DB synchronously.
+     */
+    flush(): void;
+    /**
+     * Get a single row by column value.
+     * @param col The column to filter by.
+     * @param value The value to match.
+     * @returns The matching row, or undefined if not found.
+     */
+    get<K extends keyof T>(col: K, value: T[K]): T | undefined;
+    /**
+     * Check if a row exists by column value.
+     * @param col The column to filter by.
+     * @param value The value to match.
+     * @returns True if the row exists, false otherwise.
+     */
+    has<K extends keyof T>(col: K, value: T[K]): boolean;
+    /**
+     * Add one item to buffer, flush automatically when batchSize reached.
+     */
+    write(item: T): void;
+}
+export {};

package/dist/src/databases/sqlite-writer.js

@@ -0,0 +1,127 @@
+/* * */
+import { generateRandomString } from '../random/generate-random-string.js';
+import BSQLite3 from 'better-sqlite3';
+/* * */
+export class SQLiteWriter {
+    //
+    /**
+     * Get the number of rows in the table.
+     * @returns The number of rows.
+     */
+    get size() {
+        const sql = `SELECT COUNT(*) as count FROM ${this.instanceName}`;
+        const row = this.databaseInstance.prepare(sql).get();
+        return row.count;
+    }
+    batch = [];
+    batchSize = 3000;
+    columns;
+    databaseInstance;
+    insertStatement;
+    instanceName;
+    constructor(params) {
+        //
+        //
+        // Set up options
+        this.batchSize = params.batch_size ?? 3000;
+        this.columns = params.columns;
+        this.instanceName = generateRandomString({ type: 'alphabetic' });
+        //
+        // Create a new SQLite instance
+        this.databaseInstance = new BSQLite3(`/tmp/${this.instanceName}.db`);
+        //
+        // Setup table columns from params
+        const preparedColumns = [];
+        const preparedIndexes = [];
+        for (const columnSpec of this.columns) {
+            // Extract column definition
+            const parts = [`"${columnSpec.name}"`, columnSpec.type];
+            // Set column preferences
+            if (columnSpec.not_null)
+                parts.push('NOT NULL');
+            if (columnSpec.primary_key)
+                parts.push('PRIMARY KEY');
+            // Save the column definition
+            preparedColumns.push(parts.join(' '));
+            // Save the index definition
+            if (columnSpec.indexed)
+                preparedIndexes.push(`CREATE INDEX IF NOT EXISTS idx_${this.instanceName}_${columnSpec.name} ON ${this.instanceName}("${columnSpec.name}")`);
+        }
+        //
+        // Create the table with the prepared columns and indexes
+        this.databaseInstance.pragma('journal_mode = WAL');
+        this.databaseInstance.pragma('synchronous = OFF');
+        this.databaseInstance.pragma('temp_store = MEMORY');
+        this.databaseInstance
+            .prepare(`CREATE TABLE IF NOT EXISTS ${this.instanceName} (${preparedColumns.join(',\n')})`)
+            .run();
+        preparedIndexes.forEach(i => this.databaseInstance.exec(i));
+        //
+        // Prepare insert statement
+        const placeholders = this.columns.map(() => '?').join(', ');
+        const insertSQL = `INSERT INTO ${this.instanceName} (${this.columns.map(c => `"${c.name}"`).join(', ')}) VALUES (${placeholders})`;
+        this.insertStatement = this.databaseInstance.prepare(insertSQL);
+        //
+    }
+    all(whereClause = '', params = []) {
+        const sql = `SELECT * FROM ${this.instanceName} ${whereClause}`;
+        return this.databaseInstance.prepare(sql).all(...params);
+    }
+    /**
+     * Clears all entries from the map.
+     */
+    clear() {
+        this.databaseInstance
+            .prepare(`DELETE FROM ${this.instanceName}`)
+            .run();
+    }
+    /**
+     * Flush current buffer into DB synchronously.
+     */
+    flush() {
+        // Skip if batch is empty
+        if (this.batch.length === 0)
+            return;
+        // Prepare the operation
+        const insertManyOperation = this.databaseInstance.transaction((rows) => {
+            rows.forEach((row) => {
+                // Populate the columns with the row values
+                // to ensure the order of placeholders is preserved
+                const rowValues = this.columns.map(col => row[col.name]);
+                this.insertStatement.run(rowValues);
+            });
+        });
+        // Run the operation
+        insertManyOperation(this.batch);
+        // Empty batch
+        this.batch = [];
+    }
+    /**
+     * Get a single row by column value.
+     * @param col The column to filter by.
+     * @param value The value to match.
+     * @returns The matching row, or undefined if not found.
+     */
+    get(col, value) {
+        const sql = `SELECT * FROM ${this.instanceName} WHERE ${String(col)} = ? LIMIT 1`;
+        return this.databaseInstance.prepare(sql).get(value);
+    }
+    /**
+     * Check if a row exists by column value.
+     * @param col The column to filter by.
+     * @param value The value to match.
+     * @returns True if the row exists, false otherwise.
+     */
+    has(col, value) {
+        const sql = `SELECT 1 FROM ${this.instanceName} WHERE ${String(col)} = ? LIMIT 1`;
+        return !!this.databaseInstance.prepare(sql).get(value);
+    }
+    /**
+     * Add one item to buffer, flush automatically when batchSize reached.
+     */
+    write(item) {
+        this.batch.push(item);
+        if (this.batch.length >= this.batchSize)
+            this.flush();
+    }
+}

package/dist/src/random/generate-random-string.d.ts

@@ -1,6 +1,6 @@
 interface GenerateRandomStringProps {
     length?: number;
-    type?: 'alphanumeric' | 'numeric';
+    type?: 'alphabetic' | 'alphanumeric' | 'numeric';
 }
 /**
  * Creates a random string of a given length and type.

package/dist/src/random/generate-random-string.js

@@ -9,9 +9,13 @@ import { generateRandomNumber } from './generate-random-number.js';
 export function generateRandomString({ length = 6, type = 'alphanumeric' } = {}) {
     //
     const numericSet = '0123456789';
+    const alphabeticSet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
     const alphanumericSet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
     let allowedCharacters;
     switch (type) {
+        case 'alphabetic':
+            allowedCharacters = alphabeticSet;
+            break;
         case 'numeric':
             allowedCharacters = numericSet;
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tmlmobilidade/utils",
-	"version": "20250827.1228.57",
+	"version": "20250827.1349.36",
 	"author": "João de Vasconcelos & Jusi Monteiro",
 	"license": "AGPL-3.0-or-later",
 	"homepage": "https://github.com/tmlmobilidade/services#readme",
@@ -54,6 +54,7 @@
 		"@carrismetropolitana/eslint": "20250622.1204.50",
 		"@tmlmobilidade/tsconfig": "*",
 		"@tmlmobilidade/types": "*",
+		"@types/better-sqlite3": "7.6.13",
 		"@types/luxon": "3.7.1",
 		"@types/node": "24.3.0",
 		"@types/papaparse": "5.3.16",