@randajan/file-db

 

FileDB is a minimalistic file-based adapter for storing and retrieving records using append-only logs. It is not a database. It is a thin and efficient layer for handling records in plain files — optimized for performance, clarity, and simplicity.

---

📌 Philosophy

FileDB is not a database. It does not manage schemas, indexes, or validation. Instead, it provides:

- Raw access to record-based file logs
- Encryption support via user-defined encrypt/decrypt
- Per-record identification for deduplication and optimization
- Thread-safe writes using @randajan/treelock

You are responsible for data shape and logic. FileDB focuses solely on reliable, structured persistence.

---

🚀 Example

``js
import createFileDB from "@randajan/file-db";
import CryptoJS from "crypto-js";

const fdb = createFileDB({
dir: "./data",
extension: "fdb",
encrypt:(json, key) => {
if (!key) return json;
return CryptoJS.AES.encrypt(json, key).toString();
},
decrypt:(raw, key) => {
if (!key) return raw;
const bytes = CryptoJS.AES.decrypt(raw, key);
return bytes.toString(CryptoJS.enc.Utf8);
},
on: ({ name, ram }, state) => {
console.log(${name} changed state to, state, (${ram} in queue));
}
});

const users = fdb.link("users");

await fdb.unlock("secret-key");

await users.write("john", { role: "admin" });
console.log(await users.index());

await fdb.optimize();
`

---

⚙️ Options

All options are passed to FilesDB on creation.

| Option | Type | Description |
|------------|------------|-------------|
| dir | string | Root directory path |
| extension| string | File extension (without .) |
| encoding | string | File encoding |
| encrypt(json, key) | function | Must return string |
| decrypt(raw, key) | function | Must return JSON string |
| timeout | number | Option will be passed as __ttl__ to @randajan/treelock |
| on(thread, state) | function | Hook from " class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">@randajan/treelock |

🔒 Hooks must not be asynchronous.

---

🔁 Inheritance

Options passed to FilesDB are inherited by default in FileDB. However, each file can override them individually when calling .link(name, options).

---

📘 FilesDB Properties

| Property | Type | Description |
|--------------|----------|-------------|
| dir | string | Root path |
| extension | string | File extension |
| encoding | string | File encoding |
| thread | TreeLock | See @randajan/treelock |

---

📘 FileDB Properties

| Property | Type | Description |
|--------------|----------|-------------|
| name | string | File name |
| fullname | string | Namespaced name (e.g. MyDB.users) |
| pathname | string | Full path to the file |
| isReadable | boolean| Whether file is readable |
| error | Error? | Last read-related error |
| thread | TreeLock | See @randajan/treelock |

---

📚 API Overview

This section provides a detailed explanation of all public methods of FilesDB and FileDB.

---

$3

#### link(name: string, options?: object, throwError?: boolean): FileDB
Synchronous
Links a file by name and returns its FileDB instance. Throws if already linked (unless throwError is false).

#### unlink(name: string, throwError?: boolean): boolean
Synchronous
Unlinks a file. Throws if not linked (unless throwError is false).

#### get(name: string, throwError?: boolean): FileDB
Synchronous
Returns the FileDB instance for a linked file. Throws if not linked (unless throwError is false).

#### map(fn: (file: FileDB, name: string) => any): Promise>
Asynchronous
Runs the provided function on all linked files in parallel.

#### collect(obj: object, fn: (collector: object, file: FileDB, name: string) => void): Promise