1.1.4 • Published 6 months ago

@randajan/file-db v1.1.4

Weekly downloads
-
License
MIT
Repository
github
Last release
6 months ago

@randajan/file-db

NPM JavaScript Style Guide

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

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.

OptionTypeDescription
dirstringRoot directory path
extensionstringFile extension (without .)
encodingstringFile encoding
encrypt(json, key)functionMust return string
decrypt(raw, key)functionMust return JSON string
timeoutnumberOption will be passed as ttl to @randajan/treelock
on(thread, state)functionHook from @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

PropertyTypeDescription
dirstringRoot path
extensionstringFile extension
encodingstringFile encoding
threadTreeLockSee @randajan/treelock

šŸ“˜ FileDB Properties

PropertyTypeDescription
namestringFile name
fullnamestringNamespaced name (e.g. MyDB.users)
pathnamestringFull path to the file
isReadablebooleanWhether file is readable
errorError?Last read-related error
threadTreeLockSee @randajan/treelock

šŸ“š API Overview

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


šŸ”¹ FilesDB

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<Array<any>>

Asynchronous
Runs the provided function on all linked files in parallel.

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

Asynchronous
Populates obj with data collected from all files.

reduce(initialValue: any, fn: (result: any, file: FileDB) => any): Promise<any>

Asynchronous
Applies a reducer over all files.

values(): Promise<Array<FileDB>>

Alias for map(file => file)

keys(): Promise<Array<string>>

Alias for map((file, name) => name)

entries(): Promise<Array<[string, FileDB]>>

Alias for map((file, name) => [name, file])

index(): Promise<Record<string, FileDB>>

Collects all files into a dictionary.

verify(): Promise<{ isOk: boolean, errors?: [string, Error][] }>

Async & Treelock protected
Checks readability of all linked files.

unlock(key: string): Promise<{ isOk: boolean, errors?: [string, Error][] }>

Async & Treelock protected
Attempts to decrypt and verify all linked files with the provided key.

optimize(): Promise<{ isOk: boolean, errors?: [string, Error][] }>

Async & Treelock protected
Regenerates all files to a compact form.

rekey(newKey: string, currentKey: string): Promise<{ isOk: boolean, errors?: [string, Error][] }>

Async & Treelock protected
Regenerates and re-encrypts all files using a new key. Requires currentKey to be provided because of security.


šŸ”¹ FileDB

write(id:string, body: object): Promise<void>

Async & Treelock protected
Appends a single record. Requires the file to be readable.

To delete record simple provide its id and no body (body==null)

writeSync(id:string, body: object): void

Synchronous
Synchronous version of write.

map(fn: (body: object, id: string) => any): Promise<Array<any>>

Async & Treelock protected
Iterates over all records, giving only the latest per ID.

collect(obj: object, fn: (collector: object, body: object, id: string) => void): Promise<object>

Async & Treelock protected
Populates obj from all unique records.

reduce(initialValue: any, fn: (result: any, body: object, id: string) => any): Promise<any>

Async & Treelock protected
Reduces over all unique records.

values(): Promise<Array<object>>

Alias for map(body => body)

keys(): Promise<Array<string>>

Alias for map((body, id) => id)

entries(): Promise<Array<[string, object]>>

Alias for map((body, id) => [id, body])

index(): Promise<Record<string, object>>

Collects records by ID.

verify(): Promise<void>

Async & Treelock protected
Validates the file can be read and parsed. Throws if unreadable.

unlock(key: string): Promise<void>

Async & Treelock protected
Attempts to decrypt and verify the file with the provided key.

optimize(): Promise<void>

Async & Treelock protected
Compacts the file to remove duplicate entries.

rekey(newKey: string, currentKey: string): Promise<void>

Async & Treelock protected
Regenerates the file using a new key. Requires currentKey to be provided because of security.


🧠 Notes

  • isReadable is false until at least one successful verify, map, or unlock.
  • Errors during reading are stored in error and prevent writes.

MIT License • Made with ā˜• by Jan / @randajan

1.1.1

6 months ago

1.1.0

6 months ago

1.0.0

6 months ago

1.1.4

6 months ago

1.1.3

6 months ago

1.1.2

6 months ago

0.3.5

6 months ago

0.3.4

6 months ago

0.3.3

1 year ago

0.3.2

1 year ago

0.3.1

1 year ago

0.3.0

1 year ago

0.2.1

2 years ago

0.2.0

2 years ago

0.1.2

2 years ago

0.1.1

2 years ago

0.1.0

2 years ago