twin-db 1.3.0 → 2.0.0

package/README.md

@@ -1,18 +1,63 @@
 ### Before All
 Make sure to pass just values that JSON accepts, if not, the values will be changed to `null`.
+
 # How to Use?
 To create a new database make the following step:
 ```js
 import { TwinDB } from 'twin-db';
-const database = new TwinDB('db');
+const database = new TwinDB('database/twin');
+```
+or
+```js
+const { TwinDB } = require('twin-db');
+const database = new TwinDB('database/twin');
 ```
 And your database is done.
 ### You can make various databases too:
 ```js
 import { TwinDB } from 'twin-db';
-const database = new TwinDB('db');
-const coolDatabase = new TwinDB('cool');
+const database = new TwinDB('database/db');
+const coolDatabase = new TwinDB('database/cool');
+```
+> The first argument is a file **path** — folders in it are created automatically if they don't exist. If you don't pass one, it defaults to `database/twin`.
+
+# Storages
+By default, `TwinDB` saves your data in a local `.json` file (`JSONStorage`). If you'd rather store it in a local SQLite database, pass `SqliteStorage` in the options:
+```js
+import { TwinDB, SqliteStorage } from 'twin-db';
+
+const database = new TwinDB('database/db', { storage: SqliteStorage });
+```
+`SqliteStorage` also accepts an optional `table` and `key`, in case you want more than one database sharing the same `.db` file:
+```js
+const database = new TwinDB('database/db', {
+  storage: SqliteStorage,
+  table: 'users', // defaults to "twin"
+  key: 'main',    // defaults to "data"
+});
+```
+Both storages implement the same interface, so switching between them doesn't change any of the methods in **Database Methods**.
+
+# TwinMongoDB
+If you'd rather store your data in MongoDB instead of locally, use `TwinMongoDB`. It shares the exact same methods as `TwinDB` (`set`, `get`, `delete`, `sum`, `sub`, `concat`, `push`, `pull`, all with the same `fetch` parameter), the only difference is how you create it and that every method is asynchronous:
+```js
+import { TwinMongoDB } from 'twin-db';
+
+const database = new TwinMongoDB('mongodb://localhost:27017/mydb', 'myCollection', 'myId');
+
+await database.set('name', 'De');
+const name = await database.get('name');
+await database.push('hobbies', ['sleep'], true);
+```
+- `connectionURI` (required) — your MongoDB connection string.
+- `modelName` (optional) — the collection name, defaults to `"twin"`.
+- `id` (optional) — the document `_id` used to store your data, defaults to `"data"`. Useful if you want multiple independent databases inside the same collection.
+
+When you're done with it (e.g. before your process exits), make sure to close the connection so it doesn't hang:
+```js
+await database.close();
 ```
+
 # Database Methods
 Now we going to explain you the database methods.<br>
 Imagine the following data from a random database:
@@ -42,18 +87,18 @@ Get a value from a given path.
 ```js
 database.get('surname'); // returns "Costa".
 ```
-###  3. Delete Method
+###  3. Delete/Remove Method
 Deletes a value from data.
 ```js
 database.delete('cool') // now the cool value no longer exists.
 database.delete('address.country') // now the country no longer exists too.
 ```
-### 4. Sum Method
+### 4. Sum/Add Method
 Sum the current value of the given path with the given value.
 ```js
 database.sum('age', 30); // now the age is 80.
 ```
-### 5. Sub Method
+### 5. Sub/Subtract Method
 Subtract the current value of the given path with the given value.
 ```js
 database.sub('age', 10); // now the age is 70.
@@ -64,13 +109,14 @@ Concatenate the current value of the given path with the given value.
 database.concat('address.city', ' know'); // now the city is "I dont know".
 ```
 ### 7. Push Method
-Push the given values into the current value array.
+Push the given values into the current value array. **The values must be passed as an array**, even if it's just one value.
 ```js
-database.push('hobbies', 'sleep', 'valorant'); // now the hobbies is ["cs", "pizza", "sleep", "valorant"].
+database.push('hobbies', ['sleep', 'valorant']); // now the hobbies is ["cs", "pizza", "sleep", "valorant"].
 ```
 ### 8. Pull Method
+Removes the given values from the current value array. **The values must be passed as an array**, even if it's just one value.
 ```js
-database.pull('hobbies', 'cs', 'sleep') // now the hobbies is ["pizza", "valorant"].
+database.pull('hobbies', ['cs', 'sleep']) // now the hobbies is ["pizza", "valorant"].
 ```
 ### Now the data object will looks like that:
 ```json
@@ -85,13 +131,13 @@ database.pull('hobbies', 'cs', 'sleep') // now the hobbies is ["pizza", "valoran
   }
 }
 ```
-## Updates
-`MM/DD/YYYY`<br>
-04/09/2026 - 1.1.*
-- Now **sum**, **sub** and **push** sets the value to the value you passed in execution when the path does not exists.
 
-05/03/2026 - 1.2.*
-- Now package doesn't uses eval anymore, providing better security.
+## The `fetch` parameter
+Every method above accepts an optional `fetch` boolean as its last parameter (default `false`). When `true`, it re-reads the storage before running the operation and refreshes the cache with it — useful if another process might have written to the same storage since your last read.
+```js
+database.get('name', true);
+database.push('hobbies', ['sleep'], true);
+```
 
-06/29/2026 - 1.3.*
-- Added support to require in commonjs.
+## Updates
+See new updates [here](https://github.com/toddy007/twin-db/releases).

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,91 +17,300 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  TwinDB: () => TwinDB
+  JSONStorage: () => JSONStorage,
+  SqliteStorage: () => SqliteStorage,
+  TwinDB: () => TwinDB,
+  TwinMongoDB: () => TwinMongoDB
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/structures/database.ts
-var import_fs = require("fs");
-var pathErrorMessage = "The path must be a string or you dont provide a path";
-var TwinDB = class {
-  constructor(name = "db") {
-    this.path = "database/" + name + ".json";
-    this.name = name;
-    this.data = {};
-    if (!(0, import_fs.existsSync)("database")) (0, import_fs.mkdirSync)("database");
-    this.load();
-  }
-  load() {
+// src/structures/TwinDB.ts
+var import_lodash = __toESM(require("lodash"), 1);
+
+// src/storages/JSONStorage.ts
+var import_node_fs = require("node:fs");
+var JSONStorage = class {
+  constructor(path2) {
+    if (!path2.endsWith(".json")) path2 += ".json";
+    this.path = path2;
+    if (!(0, import_node_fs.existsSync)(path2)) (0, import_node_fs.writeFileSync)(path2, "{}", "utf8");
+    else {
+      const data = (0, import_node_fs.readFileSync)(path2, "utf8");
+      let parsedData;
+      try {
+        parsedData = JSON.parse(data);
+      } catch (_) {
+      }
+      if (!data || !parsedData || typeof parsedData !== "object" || Array.isArray(parsedData))
+        (0, import_node_fs.writeFileSync)(path2, "{}", "utf8");
+    }
+  }
+  get() {
     let data;
     try {
-      data = (0, import_fs.readFileSync)(this.path, "utf8");
-    } catch (e) {
-      data = "";
+      data = (0, import_node_fs.readFileSync)(this.path, "utf8");
+    } catch (_) {
     }
-    this.data = data ? JSON.parse(data) : {};
-    if (!data)
-      (0, import_fs.writeFileSync)(
-        this.path,
-        JSON.stringify(this.data, null, 2),
-        "utf8"
+    let parsedData;
+    try {
+      if (data) parsedData = JSON.parse(data);
+    } catch (_) {
+    }
+    const checkedData = data && parsedData && typeof parsedData === "object" && !Array.isArray(parsedData);
+    if (!checkedData) (0, import_node_fs.writeFileSync)(this.path, "{}", "utf8");
+    return checkedData ? parsedData : {};
+  }
+  set(value) {
+    (0, import_node_fs.writeFileSync)(this.path, value, "utf8");
+    return true;
+  }
+};
+
+// src/storages/SqliteStorage.ts
+var import_node_sqlite = require("node:sqlite");
+
+// src/utils/vars.ts
+var DEFAULT_KEY = "data";
+var DEFAULT_NAME = "twin";
+var pathErrorMessage = "The path must be a string or you dont provided a path";
+
+// src/storages/SqliteStorage.ts
+var SqliteStorage = class {
+  constructor(path2, table = DEFAULT_NAME, key = DEFAULT_KEY) {
+    if (!table || typeof table !== "string") table = DEFAULT_NAME;
+    if (!key || typeof key !== "string") key = DEFAULT_KEY;
+    this.table = table;
+    this.key = key;
+    if (!path2.endsWith(".db")) path2 += ".db";
+    this.db = new import_node_sqlite.DatabaseSync(path2);
+    this.db.exec(`
+        CREATE TABLE IF NOT EXISTS ${table} (
+            key TEXT PRIMARY KEY,
+            value TEXT
+        )
+    `);
+  }
+  set(value) {
+    this.db.prepare(
+      `INSERT OR REPLACE INTO ${this.table} (key, value) VALUES (?, ?)`
+    ).run(this.key, value);
+    return true;
+  }
+  get() {
+    const row = this.db.prepare(`SELECT value FROM ${this.table} WHERE key = ?`).get(this.key);
+    return row ? JSON.parse(row.value) : {};
+  }
+};
+
+// src/structures/TwinDB.ts
+var import_node_path = __toESM(require("node:path"), 1);
+var import_node_fs2 = require("node:fs");
+var TwinDB = class {
+  constructor(argPath = "database/twin", options = { storage: JSONStorage }) {
+    this.remove = this.delete;
+    this.add = this.sum;
+    this.subtract = this.sub;
+    if (!argPath || typeof argPath !== "string")
+      throw new Error(pathErrorMessage);
+    const solvedPath = import_node_path.default.resolve(process.cwd(), argPath);
+    (0, import_node_fs2.mkdirSync)(import_node_path.default.dirname(solvedPath), { recursive: true });
+    if (!options || typeof options !== "object" || Array.isArray(options))
+      options = { storage: JSONStorage };
+    options.storage || (options.storage = JSONStorage);
+    if (![JSONStorage, SqliteStorage].includes(options.storage))
+      throw new Error("Invalid storage type passed in options");
+    this.storage = options.storage === SqliteStorage ? new options.storage(solvedPath, options.table, options.key) : new options.storage(solvedPath);
+    this.cache = this.storage.get();
+  }
+  update(path2, value, fetch = false) {
+    if (fetch) this.cache = this.storage.get();
+    import_lodash.default.set(this.cache, path2, value);
+    this.storage.set(JSON.stringify(this.cache));
+    return this.cache;
+  }
+  set(path2, value, fetch = false) {
+    if (!path2 || typeof path2 !== "string")
+      throw new Error(pathErrorMessage);
+    if (value === void 0)
+      throw new Error("You must provide a value to update");
+    return this.update(path2, value, fetch);
+  }
+  get(path2, fetch = false) {
+    if (!path2 || typeof path2 !== "string")
+      throw new Error(pathErrorMessage);
+    if (fetch) this.cache = this.storage.get();
+    return import_lodash.default.get(this.cache, path2, null);
+  }
+  delete(path2, fetch = false) {
+    if (!path2 || typeof path2 !== "string")
+      throw new Error(pathErrorMessage);
+    if (fetch) this.cache = this.storage.get();
+    const pathExists = this.get(path2);
+    if (pathExists === null)
+      throw new Error("The path does not exists or its value is null");
+    return this.update(path2, null);
+  }
+  sumOrSub(path2, value, type, fetch = false) {
+    if (!path2 || typeof path2 !== "string")
+      throw new Error(pathErrorMessage);
+    if (!type || !["sum", "sub"].includes(type))
+      throw new Error('The type must be "sum" or "sub"');
+    const isSum = type === "sum";
+    if (!value || typeof value !== "number")
+      throw new Error(
+        `The value to ${isSum ? "sum" : "sub"} must be a number`
       );
+    if (fetch) this.cache = this.storage.get();
+    let currentValue = this.get(path2) || 0;
+    if (typeof currentValue !== "number") currentValue = 0;
+    return this.update(
+      path2,
+      isSum ? currentValue + value : currentValue - value
+    );
   }
-  update(path, value) {
-    const keys = path.split(".");
-    let current = this.data;
-    for (let i = 0; i < keys.length; i++) {
-      let key = keys[i];
-      if (i === keys.length - 1) {
-        current[key] = value;
-        break;
-      }
-      if (typeof current[key] !== "object" || Array.isArray(current[key]) || !current[key]) {
-        current[key] = {};
-      }
-      current = current[key];
+  sum(path2, value, fetch = false) {
+    return this.sumOrSub(path2, value, "sum", fetch);
+  }
+  sub(path2, value, fetch = false) {
+    return this.sumOrSub(path2, value, "sub", fetch);
+  }
+  concat(path2, value, fetch = false) {
+    if (!path2 || typeof path2 !== "string")
+      throw new Error(pathErrorMessage);
+    if (!value || typeof value !== "string")
+      throw new Error("You must provide a string value to update");
+    if (fetch) this.cache = this.storage.get();
+    const currentValue = this.get(path2);
+    if (typeof currentValue !== "string")
+      throw new Error(
+        "The value to concat is not a string or the path does not exists"
+      );
+    return this.update(path2, currentValue + value);
+  }
+  push(path2, values, fetch = false) {
+    if (!path2 || typeof path2 !== "string")
+      throw new Error(pathErrorMessage);
+    if (!values || values.length === 0)
+      throw new Error("You must provide a value to update");
+    if (fetch) this.cache = this.storage.get();
+    let currentValue = this.get(path2) || [];
+    if (!Array.isArray(currentValue)) currentValue = [];
+    currentValue.push(...values);
+    return this.update(path2, currentValue);
+  }
+  pull(path2, values, fetch = false) {
+    if (!path2 || typeof path2 !== "string")
+      throw new Error(pathErrorMessage);
+    if (!values || values.length === 0)
+      throw new Error("You must provide a value to update");
+    if (fetch) this.cache = this.storage.get();
+    const currentValue = this.get(path2);
+    if (!Array.isArray(currentValue))
+      throw new Error(
+        "The current value of this path is not an array or the path does not exists"
+      );
+    for (const value of values) {
+      const index = currentValue.indexOf(value);
+      if (index < 0) continue;
+      currentValue.splice(index, 1);
+    }
+    return this.update(path2, currentValue);
+  }
+};
+
+// src/structures/TwinMongoDB.ts
+var import_lodash2 = __toESM(require("lodash"), 1);
+var import_mongodb = require("mongodb");
+var TwinMongoDB = class {
+  constructor(connectionURI, modelName = DEFAULT_NAME, id = DEFAULT_KEY) {
+    this.remove = this.delete;
+    this.add = this.sum;
+    this.subtract = this.sub;
+    if (!modelName || typeof modelName !== "string")
+      modelName = DEFAULT_NAME;
+    if (!id || typeof id !== "string") id = DEFAULT_KEY;
+    this.client = new import_mongodb.MongoClient(connectionURI);
+    this.cache = {};
+    this.id = id;
+    this.initPromise = this.init(modelName);
+  }
+  async init(modelName) {
+    await this.client.connect();
+    this.collection = this.client.db().collection(modelName);
+    const data = await this.collection.findOne({ _id: this.id });
+    if (!data) {
+      const created = { _id: this.id, data: {} };
+      await this.collection.insertOne(created);
+      this.cache = created.data;
+      return;
     }
-    (0, import_fs.writeFileSync)(this.path, JSON.stringify(this.data, null, 2), "utf8");
-    return this.data;
+    this.cache = data.data;
   }
-  set(path, value) {
-    if (!path || typeof path !== "string")
+  async close() {
+    await this.client.close();
+  }
+  async ready() {
+    await this.initPromise;
+  }
+  async update(path2, value, fetch = false) {
+    await this.ready();
+    if (fetch) {
+      const data = await this.collection.findOne({ _id: this.id });
+      this.cache = data ? data.data : {};
+    }
+    import_lodash2.default.set(this.cache, path2, value);
+    await this.collection.updateOne(
+      { _id: this.id },
+      { $set: { data: this.cache } },
+      { upsert: true }
+    );
+    return this.cache;
+  }
+  async set(path2, value, fetch = false) {
+    if (!path2 || typeof path2 !== "string")
       throw new Error(pathErrorMessage);
     if (value === void 0)
       throw new Error("You must provide a value to update");
-    return this.update(path, value);
+    return this.update(path2, value, fetch);
   }
-  get(path) {
-    if (!path || typeof path !== "string")
+  async get(path2, fetch = false) {
+    if (!path2 || typeof path2 !== "string")
       throw new Error(pathErrorMessage);
-    const keys = path.split(".");
-    let current = this.data;
-    let i = 0;
-    for (const key of keys) {
-      i++;
-      if (i === keys.length) return current[key] ?? null;
-      if (typeof current[key] !== "object") return null;
-      current = current[key];
+    await this.ready();
+    if (fetch) {
+      const data = await this.collection.findOne({ _id: this.id });
+      this.cache = data ? data.data : {};
     }
+    return import_lodash2.default.get(this.cache, path2, null);
   }
-  delete(path) {
-    if (!path || typeof path !== "string")
+  async delete(path2, fetch = false) {
+    if (!path2 || typeof path2 !== "string")
       throw new Error(pathErrorMessage);
-    const keys = path.split(".");
-    const pathExists = this.get(path);
+    await this.ready();
+    if (fetch) {
+      const data = await this.collection.findOne({ _id: this.id });
+      this.cache = data ? data.data : {};
+    }
+    const pathExists = await this.get(path2);
     if (pathExists === null)
       throw new Error("The path does not exists or its value is null");
-    this.update(path, null);
-    (0, import_fs.writeFileSync)(this.path, JSON.stringify(this.data, null, 2), "utf8");
-    return this.data;
+    return this.update(path2, null);
   }
-  sumOrSub(path, value, type) {
-    if (!path || typeof path !== "string")
+  async sumOrSub(path2, value, type, fetch = false) {
+    if (!path2 || typeof path2 !== "string")
       throw new Error(pathErrorMessage);
     if (!type || !["sum", "sub"].includes(type))
       throw new Error('The type must be "sum" or "sub"');
@@ -108,47 +319,67 @@ var TwinDB = class {
       throw new Error(
         `The value to ${isSum ? "sum" : "sub"} must be a number`
       );
-    let currentValue = this.get(path) || 0;
+    await this.ready();
+    if (fetch) {
+      const data = await this.collection.findOne({ _id: this.id });
+      this.cache = data ? data.data : {};
+    }
+    let currentValue = await this.get(path2) || 0;
     if (typeof currentValue !== "number") currentValue = 0;
     return this.update(
-      path,
+      path2,
       isSum ? currentValue + value : currentValue - value
     );
   }
-  sum(path, value) {
-    return this.sumOrSub(path, value, "sum");
+  async sum(path2, value, fetch = false) {
+    return this.sumOrSub(path2, value, "sum", fetch);
   }
-  sub(path, value) {
-    return this.sumOrSub(path, value, "sub");
+  async sub(path2, value, fetch = false) {
+    return this.sumOrSub(path2, value, "sub", fetch);
   }
-  concat(path, value) {
-    if (!path || typeof path !== "string")
+  async concat(path2, value, fetch = false) {
+    if (!path2 || typeof path2 !== "string")
       throw new Error(pathErrorMessage);
     if (!value || typeof value !== "string")
       throw new Error("You must provide a string value to update");
-    const currentValue = this.get(path);
+    await this.ready();
+    if (fetch) {
+      const data = await this.collection.findOne({ _id: this.id });
+      this.cache = data ? data.data : {};
+    }
+    const currentValue = await this.get(path2);
     if (typeof currentValue !== "string")
       throw new Error(
         "The value to concat is not a string or the path does not exists"
       );
-    return this.update(path, currentValue + value);
+    return this.update(path2, currentValue + value);
   }
-  push(path, ...values) {
-    if (!path || typeof path !== "string")
+  async push(path2, values, fetch = false) {
+    if (!path2 || typeof path2 !== "string")
       throw new Error(pathErrorMessage);
     if (!values || values.length === 0)
       throw new Error("You must provide a value to update");
-    let currentValue = this.get(path) || [];
+    await this.ready();
+    if (fetch) {
+      const data = await this.collection.findOne({ _id: this.id });
+      this.cache = data ? data.data : {};
+    }
+    let currentValue = await this.get(path2) || [];
     if (!Array.isArray(currentValue)) currentValue = [];
     currentValue.push(...values);
-    return this.update(path, currentValue);
+    return this.update(path2, currentValue);
   }
-  pull(path, ...values) {
-    if (!path || typeof path !== "string")
+  async pull(path2, values, fetch = false) {
+    if (!path2 || typeof path2 !== "string")
       throw new Error(pathErrorMessage);
     if (!values || values.length === 0)
       throw new Error("You must provide a value to update");
-    const currentValue = this.get(path);
+    await this.ready();
+    if (fetch) {
+      const data = await this.collection.findOne({ _id: this.id });
+      this.cache = data ? data.data : {};
+    }
+    const currentValue = await this.get(path2);
     if (!Array.isArray(currentValue))
       throw new Error(
         "The current value of this path is not an array or the path does not exists"
@@ -158,11 +389,14 @@ var TwinDB = class {
       if (index < 0) continue;
       currentValue.splice(index, 1);
     }
-    return this.update(path, currentValue);
+    return this.update(path2, currentValue);
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  TwinDB
+  JSONStorage,
+  SqliteStorage,
+  TwinDB,
+  TwinMongoDB
 });
 //# sourceMappingURL=index.cjs.map