@tmlmobilidade/utils 20250827.1127.52 → 20250827.1228.57

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './src/batching/index.js';
 export * from './src/convert-object.js';
 export * from './src/css/index.js';
+export * from './src/databases/index.js';
 export * from './src/dates/index.js';
 export * from './src/files/files.js';
 export * from './src/generic/index.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from './src/batching/index.js';
 export * from './src/convert-object.js';
 export * from './src/css/index.js';
+export * from './src/databases/index.js';
 export * from './src/dates/index.js';
 export * from './src/files/files.js';
 export * from './src/generic/index.js';

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

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

package/dist/src/databases/index.js

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

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

@@ -0,0 +1,57 @@
+/**
+ * A map-like structure backed by SQLite for persistent key-value storage.
+ * Use it to store and retrieve data across sessions without memory constraints.
+ * The API is similar to the native javascript Map object.
+ */
+export declare class SQLiteMap<K extends string, V> {
+    /**
+     * Returns the number of entries in the map.
+     */
+    get size(): number;
+    private databaseInstance;
+    constructor();
+    /**
+     * Clears all entries from the map.
+     */
+    clear(): void;
+    /**
+     * Deletes a key-value pair from the map.
+     * @param key The key of the entry to delete.
+     * @returns True if the entry was deleted, false if it didn't exist.
+     */
+    delete(key: K): boolean;
+    /**
+     * Returns an iterator over the entries in the map.
+     */
+    entries(): IterableIterator<[K, V]>;
+    /**
+     * Retrieves the value associated with the given key.
+     * @param key The key of the entry to retrieve.
+     * @returns The value associated with the key, or undefined if it doesn't exist.
+     */
+    get(key: K): undefined | V;
+    /**
+     * Checks if the map contains a value for the given key.
+     * @param key The key to check.
+     * @returns True if the key exists, false otherwise.
+     */
+    has(key: K): boolean;
+    /**
+     * Returns an iterator over the keys in the map.
+     */
+    keys(): IterableIterator<K>;
+    /**
+     * Sets the value for the given key.
+     * @param key The key of the entry to set.
+     * @param value The value to associate with the key.
+     */
+    set(key: K, value: V): void;
+    /**
+     * Returns an iterator over the entries in the map.
+     */
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+    /**
+     * Returns an iterator over the values in the map.
+     */
+    values(): IterableIterator<V>;
+}

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

@@ -0,0 +1,121 @@
+/* * */
+import { generateRandomString } from '../random/generate-random-string.js';
+import BSQLite3 from 'better-sqlite3';
+/* * */
+/**
+ * A map-like structure backed by SQLite for persistent key-value storage.
+ * Use it to store and retrieve data across sessions without memory constraints.
+ * The API is similar to the native javascript Map object.
+ */
+export class SQLiteMap {
+    //
+    /**
+     * Returns the number of entries in the map.
+     */
+    get size() {
+        const row = this.databaseInstance
+            .prepare(`SELECT COUNT(*) as count FROM map`)
+            .get();
+        return row.count;
+    }
+    databaseInstance;
+    constructor() {
+        //
+        //
+        // Set up a new database instance
+        const databaseFileName = generateRandomString();
+        this.databaseInstance = new BSQLite3(`/tmp/${databaseFileName}.db`);
+        //
+        // Create a new table if it doesn't exist
+        this.databaseInstance.pragma('journal_mode = WAL');
+        this.databaseInstance.pragma('synchronous = NORMAL');
+        this.databaseInstance
+            .prepare(`CREATE TABLE IF NOT EXISTS map (key TEXT PRIMARY KEY, value TEXT NOT NULL)`)
+            .run();
+        //
+    }
+    /**
+     * Clears all entries from the map.
+     */
+    clear() {
+        this.databaseInstance
+            .prepare(`DELETE FROM map`)
+            .run();
+    }
+    /**
+     * Deletes a key-value pair from the map.
+     * @param key The key of the entry to delete.
+     * @returns True if the entry was deleted, false if it didn't exist.
+     */
+    delete(key) {
+        const result = this.databaseInstance
+            .prepare(`DELETE FROM map WHERE key = ?`)
+            .run(key);
+        return result.changes > 0;
+    }
+    /**
+     * Returns an iterator over the entries in the map.
+     */
+    *entries() {
+        const statement = this.databaseInstance.prepare(`SELECT key, value FROM map`);
+        for (const row of statement.iterate()) {
+            yield [JSON.parse(row.key), JSON.parse(row.value)];
+        }
+    }
+    /**
+     * Retrieves the value associated with the given key.
+     * @param key The key of the entry to retrieve.
+     * @returns The value associated with the key, or undefined if it doesn't exist.
+     */
+    get(key) {
+        const row = this.databaseInstance
+            .prepare(`SELECT value FROM map WHERE key = ?`)
+            .get(key);
+        return row ? JSON.parse(row.value) : undefined;
+    }
+    /**
+     * Checks if the map contains a value for the given key.
+     * @param key The key to check.
+     * @returns True if the key exists, false otherwise.
+     */
+    has(key) {
+        const row = this.databaseInstance
+            .prepare(`SELECT 1 FROM map WHERE key = ?`)
+            .get(key);
+        return !!row;
+    }
+    /**
+     * Returns an iterator over the keys in the map.
+     */
+    *keys() {
+        const statement = this.databaseInstance.prepare(`SELECT key FROM map`);
+        for (const row of statement.iterate()) {
+            yield JSON.parse(row.key);
+        }
+    }
+    /**
+     * Sets the value for the given key.
+     * @param key The key of the entry to set.
+     * @param value The value to associate with the key.
+     */
+    set(key, value) {
+        this.databaseInstance
+            .prepare(`INSERT OR REPLACE INTO map (key, value) VALUES (?, ?)`)
+            .run(key, JSON.stringify(value));
+    }
+    /**
+     * Returns an iterator over the entries in the map.
+     */
+    [Symbol.iterator]() {
+        return this.entries();
+    }
+    /**
+     * Returns an iterator over the values in the map.
+     */
+    *values() {
+        const statement = this.databaseInstance.prepare(`SELECT value FROM map`);
+        for (const row of statement.iterate()) {
+            yield JSON.parse(row.value);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tmlmobilidade/utils",
-	"version": "20250827.1127.52",
+	"version": "20250827.1228.57",
 	"author": "João de Vasconcelos & Jusi Monteiro",
 	"license": "AGPL-3.0-or-later",
 	"homepage": "https://github.com/tmlmobilidade/services#readme",
@@ -41,6 +41,7 @@
 	"dependencies": {
 		"@tmlmobilidade/lib": "*",
 		"@turf/turf": "7.2.0",
+		"better-sqlite3": "12.2.0",
 		"extract-zip": "2.0.1",
 		"geojson": "0.5.0",
 		"jszip": "3.10.1",