@tmlmobilidade/sqlite 20251202.1817.5

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/sqlite-db.d.ts

@@ -0,0 +1,65 @@
+import { SQLiteDatabaseConfig, SQLiteTable } from './types.js';
+import BSQLite3, { type Database } from 'better-sqlite3';
+import { Readable } from 'node:stream';
+export declare class SQLiteDatabase {
+    databaseInstance: Database;
+    private tables;
+    constructor(config?: SQLiteDatabaseConfig);
+    /**
+     * Registers a new table and returns an object with methods for that table.
+     */
+    registerTable<T>(tableName: string, params: SQLiteTable<T>): SQLiteTableInstance<T>;
+}
+export declare class SQLiteTableInstance<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 tableName;
+    constructor(databaseInstance: Database, tableName: string, params: SQLiteTable<T>);
+    /**
+     * Get all rows, optionally filtered by a WHERE clause.
+     * @param whereClause Optional SQL WHERE clause (e.g., "WHERE id = ?").
+     * @param params Parameters for the WHERE clause.
+     * @returns An array of matching rows.
+     */
+    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;
+    query(sqlQuery?: string, params?: (boolean | number | string)[]): BSQLite3.RunResult;
+    /**
+     * Iterator to go through all rows in the table.
+     */
+    stream(whereClause?: string, params?: (boolean | number | string)[]): Readable;
+    update(whereClause: string, newData: Partial<T>, params?: (boolean | number | string)[]): T[];
+    /**
+     * Add one item to buffer, flush automatically when batchSize reached.
+     */
+    write(item: T): void;
+}

package/dist/sqlite-db.js

@@ -0,0 +1,195 @@
+/* * */
+import { generateRandomString } from '@tmlmobilidade/strings';
+import BSQLite3 from 'better-sqlite3';
+import fs from 'node:fs';
+import { Readable } from 'node:stream';
+/* * */
+export class SQLiteDatabase {
+    //
+    //
+    //  Properties
+    databaseInstance;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    tables = new Map();
+    //
+    //  Constructor
+    constructor(config = {}) {
+        //
+        //
+        // If not provided, generate random values
+        // and create a new database instance.
+        if (!config.instanceName && !config.memory) {
+            config.instanceName = generateRandomString();
+        }
+        if (!config.instancePath && !config.memory) {
+            config.instancePath = `/tmp/${config.instanceName}/${config.instanceName}.db`;
+            fs.mkdirSync(`/tmp/${config.instanceName}`, { recursive: true });
+        }
+        if (!config.databaseInstance) {
+            config.databaseInstance = new BSQLite3(config.memory ? ':memory:' : config.instancePath);
+        }
+        //
+        // Initialize the database instance
+        this.databaseInstance = config.databaseInstance;
+        this.databaseInstance.pragma('journal_mode = WAL');
+        this.databaseInstance.pragma('synchronous = ON');
+        this.databaseInstance.pragma('temp_store = MEMORY');
+    }
+    /**
+     * Registers a new table and returns an object with methods for that table.
+     */
+    registerTable(tableName, params) {
+        if (this.tables.has(tableName)) {
+            throw new Error(`Table "${tableName}" already registered`);
+        }
+        const tableInstance = new SQLiteTableInstance(this.databaseInstance, tableName, params);
+        this.tables.set(tableName, tableInstance);
+        return tableInstance;
+    }
+}
+/* * */
+export class SQLiteTableInstance {
+    //
+    /**
+     * Get the number of rows in the table.
+     * @returns The number of rows.
+     */
+    get size() {
+        const sql = `SELECT COUNT(*) as count FROM ${this.tableName}`;
+        const row = this.databaseInstance.prepare(sql).get();
+        return row.count;
+    }
+    //
+    //  Constructor
+    batch = [];
+    batchSize = 3000;
+    columns;
+    databaseInstance;
+    insertStatement;
+    tableName;
+    constructor(databaseInstance, tableName, params) {
+        //
+        //
+        // Set up properties
+        this.databaseInstance = databaseInstance;
+        this.batchSize = params.batch_size ?? 3000;
+        this.columns = params.columns;
+        this.tableName = tableName;
+        // Create table
+        this.databaseInstance
+            .prepare(`CREATE TABLE IF NOT EXISTS ${this.tableName} (${params.columns.map(c => `"${c.name}" ${c.type}`).join(', ')})`)
+            .run();
+        // Create indexes
+        params.columns.forEach((c) => {
+            if (c.indexed) {
+                this.databaseInstance.exec(`CREATE INDEX IF NOT EXISTS idx_${this.tableName}_${c.name} ON ${this.tableName}("${c.name}")`);
+            }
+        });
+        //
+        // Prepare insert statement
+        const placeholders = this.columns.map(() => '?').join(', ');
+        const insertSQL = `INSERT INTO ${this.tableName} (${this.columns.map(c => `"${c.name}"`).join(', ')}) VALUES (${placeholders})`;
+        this.insertStatement = this.databaseInstance.prepare(insertSQL);
+    }
+    /**
+     * Get all rows, optionally filtered by a WHERE clause.
+     * @param whereClause Optional SQL WHERE clause (e.g., "WHERE id = ?").
+     * @param params Parameters for the WHERE clause.
+     * @returns An array of matching rows.
+     */
+    all(whereClause = '', params = []) {
+        const sql = `SELECT * FROM ${this.tableName} ${whereClause}`;
+        return this.databaseInstance.prepare(sql).all(...params);
+    }
+    /**
+     * Clears all entries from the map.
+     */
+    clear() {
+        this.databaseInstance
+            .prepare(`DELETE FROM ${this.tableName}`)
+            .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) => {
+                    const value = row[col.name];
+                    // Convert boolean to 0 or 1
+                    if (typeof value === 'boolean') {
+                        return value ? 1 : 0;
+                    }
+                    return value;
+                });
+                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.tableName} 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.tableName} WHERE ${String(col)} = ? LIMIT 1`;
+        return !!this.databaseInstance.prepare(sql).get(value);
+    }
+    query(sqlQuery = '', params = []) {
+        return this.databaseInstance.prepare(sqlQuery).run(...params);
+    }
+    /**
+     * Iterator to go through all rows in the table.
+     */
+    stream(whereClause = '', params = []) {
+        // Create an iterator for the query
+        const iterator = this.databaseInstance
+            .prepare(`SELECT * FROM ${this.tableName} ${whereClause}`)
+            .iterate(...params);
+        // Return a Readable stream in object mode
+        return new Readable({
+            objectMode: true,
+            read() {
+                const next = iterator.next();
+                if (next.done)
+                    this.push(null); // end of stream
+                else
+                    this.push(next.value);
+            },
+        });
+    }
+    update(whereClause = '', newData, params = []) {
+        const sql = `UPDATE ${this.tableName} SET ${Object.keys(newData).map(key => `${key} = ?`).join(', ')} WHERE ${whereClause}`;
+        return this.databaseInstance.prepare(sql).all(...params);
+    }
+    /**
+     * 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/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/sqlite-map.js

@@ -0,0 +1,121 @@
+/* * */
+import { generateRandomString } from '@tmlmobilidade/strings';
+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/dist/sqlite-writer.d.ts

@@ -0,0 +1,11 @@
+import { SQLiteTableInstance } from './sqlite-db.js';
+import { type SQLiteTable } from './types.js';
+/**
+ * @deprecated Use `SQLiteDatabase` instead.
+ */
+export declare class SQLiteWriter<T> extends SQLiteTableInstance<T> {
+    readonly instanceName: string;
+    readonly instancePath: string;
+    constructor(params: SQLiteTable<T>);
+    private static createDatabase;
+}

package/dist/sqlite-writer.js

@@ -0,0 +1,41 @@
+/* * */
+import { SQLiteTableInstance } from './sqlite-db.js';
+import { generateRandomString } from '@tmlmobilidade/strings';
+import BSQLite3 from 'better-sqlite3';
+/**
+ * @deprecated Use `SQLiteDatabase` instead.
+ */
+export class SQLiteWriter extends SQLiteTableInstance {
+    //
+    //
+    // Properties
+    instanceName;
+    instancePath;
+    //
+    // Constructor
+    constructor(params) {
+        //
+        //
+        // Otherwise, generate a random instance name and path
+        // and create a new database instance
+        const instanceName = generateRandomString({ type: 'alphabetic' });
+        const instancePath = `/tmp/${instanceName}.db`;
+        const db = SQLiteWriter.createDatabase(instancePath);
+        super(db, instanceName, params);
+        this.instanceName = instanceName;
+        this.instancePath = instancePath;
+    }
+    //
+    //  Methods
+    static createDatabase(path) {
+        //
+        // Set up the database
+        const db = new BSQLite3(path);
+        db.pragma('journal_mode = WAL');
+        db.pragma('synchronous = OFF');
+        db.pragma('temp_store = MEMORY');
+        //
+        // Return the database
+        return db;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,49 @@
+import { type Database } from 'better-sqlite3';
+export interface SQLiteDatabaseConfig {
+    /**
+     * The BetterSQLite3 database instance to use.
+     * If not provided, a temporary database will be created.
+     */
+    databaseInstance?: Database;
+    /**
+     * Optional custom instance name.
+     * If not provided, a random name will be generated.
+     */
+    instanceName?: string;
+    /**
+     * Optional custom database file path.
+     * If not provided, a temporary file path will be generated.
+     */
+    instancePath?: string;
+    /**
+     * If true, the database will be created in memory.
+     * Defaults to false.
+     * Note: If using in-memory, data will be lost when the process exits.
+     * Also, multiple instances will not share the same data.
+     * Use only for testing or ephemeral data storage.
+     * If true, instancePath is ignored.
+     * @default false
+     */
+    memory?: boolean;
+}
+export interface SQLiteColumn<T> {
+    indexed?: boolean;
+    name: Extract<keyof T, string>;
+    not_null?: boolean;
+    primary_key?: boolean;
+    type: 'BLOB' | 'BOOLEAN' | 'INTEGER' | 'REAL' | 'TEXT';
+}
+export interface SQLiteTable<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: SQLiteColumn<T>[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+/* * */
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@tmlmobilidade/sqlite",
+	"version": "20251202.1817.5",
+	"author": {
+		"email": "iso@tmlmobilidade.pt",
+		"name": "TML-ISO"
+	},
+	"license": "AGPL-3.0-or-later",
+	"homepage": "https://github.com/tmlmobilidade/go#readme",
+	"bugs": {
+		"url": "https://github.com/tmlmobilidade/go/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tmlmobilidade/go.git"
+	},
+	"keywords": [
+		"public transit",
+		"tml",
+		"transportes metropolitanos de lisboa",
+		"go"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsc && resolve-tspaths",
+		"lint": "eslint ./src/ && tsc --noEmit",
+		"lint:fix": "eslint ./src/ --fix",
+		"watch": "tsc-watch --onSuccess 'resolve-tspaths'"
+	},
+	"dependencies": {
+		"@tmlmobilidade/strings": "*",
+		"better-sqlite3": "12.5.0"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/tsconfig": "*",
+		"@types/better-sqlite3": "7.6.13",
+		"@types/node": "24.10.1",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.0",
+		"typescript": "5.9.3"
+	}
+}