@wxn0brp/db-storage-sqlite 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 wxn0brP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @wxn0brp/db-storage-sqlite
+
+A **pure SQLite storage adapter** for the ValtheraDB database library.
+This package allows you to use SQLite as a backend while leveraging the **full power of ValtheraDB** (CRUD operations, relations, queries, `_id` generation, sorting, pagination, etc.).
+
+> ⚠️ **Note:** Unlike the original ValtheraDB, SQLite requires tables to exist before inserting data. This adapter provides `ensureCollection` to check for table existence, but it **does not create empty tables automatically**.
+
+## Features
+
+* **Full CRUD** – Create, Read, Update, Delete operations fully supported.
+* **Collection-based** – Each collection corresponds to a SQLite table.
+* **Flexible Search** – Supports function-based or object-based searches.
+* **Automatic ID Generation** – `_id` is generated automatically if missing.
+* **Sorting & Pagination** – Built-in support for sorting, limiting, and offsetting results.
+* **TypeScript Support** – Fully typed for safety and autocompletion.
+
+## Installation
+
+```bash
+yarn add github:wxn0brP/ValtheraDB-storage-sqlite#dist
+```
+
+## Usage
+
+```ts
+import { SQLiteValthera } from "@wxn0brp/db-storage-sqlite";
+import { ValtheraClass } from "@wxn0brp/db-core";
+import Database from "better-sqlite3";
+
+// 1. Initialize SQLite database connection
+const sqliteDB = new Database("path/to/database.sqlite");
+
+// 2. Create the SQLiteValthera instance
+const sqliteDbAction = new SQLiteValthera(sqliteDB);
+
+// 3. Ensure the collection/table exists
+await sqliteDbAction.ensureCollection("users");
+
+// 4. Create ValtheraClass instance using the SQLite adapter
+const db = new ValtheraClass({
+    dbAction: sqliteDbAction
+});
+
+// 5. Add a new entry (_id generated automatically, _id is type `TEXT`)
+await db.add("users", { name: "John Doe", email: "john@example.com" });
+
+// 6. Find entries
+const users = await db.find("users", { name: "John Doe" });
+
+// 7. Update entries
+await db.update("users", { name: "John Doe" }, { email: "newemail@example.com" });
+
+// 8. Remove entries
+await db.remove("users", { name: "John Doe" });
+```
+
+## API Notes
+
+* **`ensureCollection(collection: string)`**
+  Checks if the collection (table) exists.
+  Throws an error if the table does not exist.
+
+  > This is necessary because SQLite cannot create a table without defining at least one column.
+
+* All other methods (`add`, `find`, `update`, `remove`) are **fully compatible with ValtheraDB**, preserving all features like `_id` generation, complex filters (`hasFieldsAdvanced`), sorting, pagination, and function-based search.
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions and bug requests are welcome!

package/dist/find.d.ts

@@ -0,0 +1,4 @@
+import Data from "@wxn0brp/db-core/types/data";
+import { VQuery } from "@wxn0brp/db-core/types/query";
+import { SQLiteValthera } from "./index.js";
+export declare function find(slv: SQLiteValthera, config: VQuery): Promise<Data[]>;

package/dist/find.js

@@ -0,0 +1,39 @@
+import { compareSafe } from "@wxn0brp/db-core/utils/compare";
+import hasFieldsAdvanced from "@wxn0brp/db-core/utils/hasFieldsAdvanced";
+import updateFindObject from "@wxn0brp/db-core/utils/updateFindObject";
+export async function find(slv, config) {
+    const { collection, search, findOpts, dbFindOpts, context } = config;
+    let sqlResult = [];
+    if (typeof search === "function" || Object.keys(search).length === 0) {
+        const stmt = await slv._prepare(`SELECT * FROM ${collection}`);
+        sqlResult = await Promise.resolve(stmt.all());
+    }
+    else {
+        const baseKeys = Object.keys(search)
+            .filter(k => search[k] !== undefined)
+            .filter(k => !k.startsWith("$"))
+            .filter(k => typeof search[k] !== "object");
+        const baseSql = `SELECT * FROM ${collection} WHERE ${baseKeys.map(k => `${k} = ?`).join(" AND ")}`;
+        const baseValues = baseKeys.map(k => search[k]);
+        const stmt = await slv._prepare(baseSql);
+        sqlResult = await Promise.resolve(stmt.all(...baseValues));
+    }
+    let result = sqlResult.filter(entry => typeof search === "function" ? search(entry, context) : hasFieldsAdvanced(entry, search));
+    const { reverse = false, limit = -1, offset = 0, sortBy, sortAsc = true } = dbFindOpts;
+    if (reverse)
+        result.reverse();
+    if (sortBy) {
+        const dir = sortAsc ? 1 : -1;
+        result.sort((a, b) => compareSafe(a[sortBy], b[sortBy]) * dir);
+        const start = offset;
+        const end = limit !== -1 ? offset + limit : undefined;
+        result = result.slice(start, end);
+    }
+    else {
+        if (offset > 0)
+            result.splice(0, offset);
+        if (limit > 0)
+            result.splice(limit);
+    }
+    return result.length ? result.map(res => updateFindObject(res, findOpts)) : [];
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import ActionsBase from "@wxn0brp/db-core/base/actions";
+import Data from "@wxn0brp/db-core/types/data";
+import { VQuery } from "@wxn0brp/db-core/types/query";
+import { Statement } from "bun:sqlite";
+import { SupportedDB } from "./types.js";
+export declare class SQLiteValthera extends ActionsBase {
+    db: SupportedDB;
+    _inited: boolean;
+    constructor(db: SupportedDB);
+    _prepare(sql: string): Promise<Statement>;
+    add(config: VQuery): Promise<Data>;
+    find(config: VQuery): Promise<Data[]>;
+    findOne(config: VQuery): Promise<Data | null>;
+    update(config: VQuery): Promise<boolean>;
+    updateOne(config: VQuery): Promise<boolean>;
+    remove(config: VQuery): Promise<boolean>;
+    removeOne(config: VQuery): Promise<boolean>;
+    removeCollection(config: VQuery): Promise<boolean>;
+    issetCollection(config: VQuery): Promise<boolean>;
+    ensureCollection(config: VQuery): Promise<boolean>;
+}

package/dist/index.js

@@ -0,0 +1,80 @@
+import { genId } from "@wxn0brp/db-core";
+import ActionsBase from "@wxn0brp/db-core/base/actions";
+import { find } from "./find.js";
+import { remove } from "./remove.js";
+import { update } from "./update.js";
+export class SQLiteValthera extends ActionsBase {
+    db;
+    _inited = true;
+    constructor(db) {
+        super();
+        this.db = db;
+    }
+    async _prepare(sql) {
+        const db = this.db;
+        if (typeof db.prepare !== "undefined")
+            return await db.prepare(sql);
+        if (typeof db.prepareSync !== "undefined")
+            return await db.prepareSync(sql);
+        if (typeof db.query === "function") {
+            const q = await db.query(sql);
+            if (q && (q.all || q.get || q.run))
+                return q;
+        }
+        throw new Error("Unsupported database");
+    }
+    async add(config) {
+        const { data, id_gen = true, collection } = config;
+        if (id_gen && !data._id)
+            data._id = genId();
+        const keys = Object.keys(data);
+        const placeholders = keys.map(() => "?").join(", ");
+        const values = keys.map(k => data[k]);
+        const sql = `INSERT INTO ${collection} (${keys.join(", ")}) VALUES (${placeholders})`;
+        const stmt = await this._prepare(sql);
+        await Promise.resolve(stmt.run(...values));
+        return data;
+    }
+    find(config) {
+        return find(this, config);
+    }
+    async findOne(config) {
+        config.dbFindOpts = { limit: 1 };
+        const result = await this.find(config);
+        return result.length ? result[0] : null;
+    }
+    update(config) {
+        return update(this, config.collection, false, config.search, config.updater, config.context);
+    }
+    updateOne(config) {
+        return update(this, config.collection, true, config.search, config.updater, config.context);
+    }
+    remove(config) {
+        return remove(this, config.collection, false, config.search, config.context);
+    }
+    removeOne(config) {
+        return remove(this, config.collection, true, config.search, config.context);
+    }
+    async removeCollection(config) {
+        const { collection } = config;
+        const sql = `DROP TABLE IF EXISTS ${collection}`;
+        const stmt = await this._prepare(sql);
+        await Promise.resolve(stmt.run());
+        return true;
+    }
+    async issetCollection(config) {
+        const { collection } = config;
+        const sql = `SELECT name FROM sqlite_master WHERE type='table' AND name=?`;
+        const stmt = await this._prepare(sql);
+        const result = await Promise.resolve(stmt.all(collection));
+        return result.length > 0;
+    }
+    async ensureCollection(config) {
+        const { collection } = config;
+        const issetCollection = await this.issetCollection({ collection });
+        if (!issetCollection) {
+            throw new Error(`Collection "${collection}" not found. Please create it first.`);
+        }
+        return true;
+    }
+}

package/dist/remove.d.ts

@@ -0,0 +1,4 @@
+import { Search } from "@wxn0brp/db-core/types/arg";
+import { VContext } from "@wxn0brp/db-core/types/types";
+import { SQLiteValthera } from "./index.js";
+export declare function remove(slv: SQLiteValthera, collection: string, one: boolean, search: Search, context?: VContext): Promise<boolean>;

package/dist/remove.js

@@ -0,0 +1,25 @@
+import hasFieldsAdvanced from "@wxn0brp/db-core/utils/hasFieldsAdvanced";
+export async function remove(slv, collection, one, search, context = {}) {
+    let stmt = await slv._prepare(`SELECT * FROM "${collection}"`);
+    const allEntries = await Promise.resolve(stmt.all());
+    const toDelete = [];
+    let removed = false;
+    for (const entry of allEntries) {
+        const match = typeof search === "function"
+            ? search(entry, context)
+            : hasFieldsAdvanced(entry, search);
+        if (match) {
+            toDelete.push(entry);
+            removed = true;
+            if (one)
+                break;
+        }
+    }
+    if (!removed)
+        return false;
+    stmt = await slv._prepare(`DELETE FROM "${collection}" WHERE _id = ?`);
+    for (const entry of toDelete) {
+        await Promise.resolve(stmt.run(entry._id));
+    }
+    return true;
+}

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+import type { Database as BetterSqliteDB } from "better-sqlite3";
+import type { Database as BunSqliteDB } from "bun:sqlite";
+import type { DatabaseSync as NodeSqliteDB } from "node:sqlite";
+import type BetterSqlite3 from "better-sqlite3";
+import type NodeSqlite from "node:sqlite";
+export type SupportedDB = BetterSqliteDB | NodeSqliteDB | BunSqliteDB;
+export type Statement = BetterSqlite3.Statement | NodeSqlite.StatementSync;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/update.d.ts

@@ -0,0 +1,4 @@
+import { Search, Updater } from "@wxn0brp/db-core/types/arg";
+import { VContext } from "@wxn0brp/db-core/types/types";
+import { SQLiteValthera } from "./index.js";
+export declare function update(slv: SQLiteValthera, collection: string, one: boolean, search: Search, updater: Updater, context?: VContext): Promise<boolean>;

package/dist/update.js

@@ -0,0 +1,33 @@
+import hasFieldsAdvanced from "@wxn0brp/db-core/utils/hasFieldsAdvanced";
+export async function update(slv, collection, one, search, updater, context = {}) {
+    const stmt = await slv._prepare(`SELECT * FROM "${collection}"`);
+    const allEntries = await Promise.resolve(stmt.all());
+    const matched = [];
+    for (const entry of allEntries) {
+        const match = typeof search === "function"
+            ? search(entry, context)
+            : hasFieldsAdvanced(entry, search);
+        if (match) {
+            matched.push(entry);
+            if (one)
+                break;
+        }
+    }
+    if (matched.length === 0)
+        return false;
+    const updateOne = async (target) => {
+        const newData = typeof updater === "function"
+            ? updater(target, context)
+            : { ...target, ...updater };
+        if (newData._id !== target._id)
+            newData._id = target._id;
+        const keys = Object.keys(newData).filter(k => k !== "_id");
+        const values = keys.map(k => newData[k]);
+        const sql = `UPDATE "${collection}" SET ${keys.map(k => `"${k}" = ?`).join(", ")} WHERE _id = ?`;
+        const stmt = await slv._prepare(sql);
+        await Promise.resolve(stmt.run(...values, target._id));
+    };
+    for (const target of matched)
+        await updateOne(target);
+    return true;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "@wxn0brp/db-storage-sqlite",
+    "version": "0.0.1",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "description": "",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/wxn0brP/ValtheraDB-storage-sqlite.git"
+    },
+    "homepage": "https://github.com/wxn0brP/ValtheraDB-storage-sqlite",
+    "author": "wxn0brP",
+    "license": "MIT",
+    "type": "module",
+    "scripts": {
+        "build": "tsc && tsc-alias"
+    },
+    "devDependencies": {
+        "@types/better-sqlite3": "^7.6.13",
+        "@types/bun": "*",
+        "@types/node": "*",
+        "@wxn0brp/db-core": "^0.3.0",
+        "better-sqlite3": "^12.5.0",
+        "tsc-alias": "*",
+        "typescript": "*"
+    },
+    "peerDependencies": {
+        "@wxn0brp/db-core": ">=0.3.0",
+        "better-sqlite3": "^12.5.0"
+    },
+    "peerDependenciesMeta": {
+        "@wxn0brp/db-core": {
+            "optional": false
+        },
+        "better-sqlite3": {
+            "optional": true
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        },
+        "./*": {
+            "types": "./dist/*.d.ts",
+            "import": "./dist/*.js",
+            "default": "./dist/*.js"
+        }
+    }
+}