@jsonkit/db 1.0.1 → 3.0.1

package/README.md

@@ -1,3 +1,249 @@
 # @jsonkit/db
 
-A simple JSON file based database for use in simple server side applications
+`@jsonkit/db` is a lightweight, zero-dependency database abstraction for rapid prototyping. It provides simple **file-based** and **in-memory** databases with consistent APIs, suitable for small applications, tooling, tests, and early-stage prototypes where setting up a full database would be unnecessary overhead.
+
+The package exposes two core concepts:
+
+* **Single-entry databases** – manage exactly one JSON-serializable object.
+* **Multi-entry databases** – manage collections of identifiable records keyed by an `id`.
+
+Both concepts are available in **file-backed** and **in-memory** variants.
+
+---
+
+## Installation
+
+```bash
+npm install @jsonkit/db
+```
+
+---
+
+## Multi-entry Databases
+
+Multi-entry databases manage collections of entries keyed by `id`.
+
+### Common API (`MultiEntryDb<T>`)
+
+All multi-entry implementations expose the same methods:
+
+* `create(entry)`
+* `getById(id)`
+* `getByIdOrThrow(id)`
+* `getWhere(predicate, pagination?)`
+* `getAll(ids?)`
+* `getAllIds()`
+* `update(id, updater)`
+* `deleteById(id)`
+* `deleteByIds(ids)`
+* `deleteWhere(predicate)`
+* `exists(id)`
+* `countAll()`
+* `countWhere(predicate)`
+* `destroy()`
+
+Updates are **partial merges**, and changing an entry’s `id` during an update is supported.
+
+---
+
+### `MultiEntryFileDb<T extends Identifiable>`
+
+A file-backed database where **each entry is stored as its own JSON file**.
+
+```ts
+import { MultiEntryFileDb } from '@jsonkit/db'
+
+const db = new MultiEntryFileDb<User>('./data/users')
+```
+
+#### Behavior
+
+* Each entry is stored as `<id>.json` in the provided directory.
+* The directory is created implicitly as files are written.
+* IDs are validated to prevent path traversal by default.
+
+#### Constructor
+
+```ts
+new MultiEntryFileDb<T>(dirpath, options?)
+```
+
+**Options**
+
+| Option          | Description                            | Default |
+| --------------- | -------------------------------------- | ------- |
+| `noPathlikeIds` | Reject IDs containing `/` or `\`       | `true`  |
+| `parser`        | Custom JSON parser (`{ parse(text) }`) | `JSON`  |
+
+#### Notes
+
+* Failed reads (missing file or invalid JSON) return `null`.
+* `destroy()` deletes the entire directory.
+* Intended for development, prototyping, and small datasets.
+
+---
+
+### `MultiEntryMemDb<T extends Identifiable>`
+
+An in-memory implementation backed by a `Map`.
+
+```ts
+import { MultiEntryMemDb } from '@jsonkit/db'
+
+const db = new MultiEntryMemDb<User>()
+```
+
+#### Behavior
+
+* Fast, ephemeral storage.
+* Ideal for tests and short-lived processes.
+* `destroy()` clears all entries.
+
+---
+
+## Single-entry Databases
+
+Single-entry databases manage **exactly one value**, often used for configuration or application state.
+
+### Common API (`SingleEntryDb<T>`)
+
+* `isInited()`
+* `read()`
+* `write(entry | updater)`
+* `delete()`
+
+`write` supports either replacing the entry or partially updating it via an updater function.
+
+---
+
+### `SingleEntryFileDb<T>`
+
+Stores a single JSON object in a file.
+
+```ts
+import { SingleEntryFileDb } from '@jsonkit/db'
+
+const db = new SingleEntryFileDb<AppConfig>('./config.json')
+```
+
+#### Behavior
+
+* Reads and writes a single JSON file.
+* `isInited()` checks file existence.
+* `read()` throws if the file does not exist.
+
+#### Constructor
+
+```ts
+new SingleEntryFileDb<T>(filepath, parser?)
+```
+
+* `parser` defaults to `JSON`.
+
+---
+
+### `SingleEntryMemDb<T>`
+
+An in-memory single-value database.
+
+```ts
+import { SingleEntryMemDb } from '@jsonkit/db'
+
+const db = new SingleEntryMemDb<AppConfig>()
+```
+
+#### Behavior
+
+* Optional initial value.
+* `read()` throws if uninitialized.
+* `delete()` resets the entry to `null`.
+
+---
+
+## Example
+
+```ts
+type User = { id: string; name: string }
+
+const users = new MultiEntryFileDb<User>('./users')
+
+await users.create({ id: 'u1', name: 'Alice' })
+
+await users.update('u1', (u) => ({ name: 'Alice Smith' }))
+
+const allUsers = await users.getAll()
+```
+
+---
+
+## Use Cases
+
+* Rapid application prototyping
+* CLI tools
+* Small internal services
+* Tests and mocks
+* Configuration and state persistence
+
+---
+
+## Core Types
+
+### `Identifiable`
+
+```ts
+type Identifiable = { id: string }
+```
+
+All multi-entry databases require entries to have a string `id`.
+
+### `Promisable<T>`
+
+A value or a promise of a value.
+
+```ts
+type Promisable<T> = T | Promise<T>
+```
+
+### `PredicateFn<T>`
+
+Used for filtering entries.
+
+```ts
+type PredicateFn<T extends Identifiable> = (entry: T) => boolean
+```
+
+### `PaginationInput`
+
+Used for filtering entries.
+
+```ts
+type PredicateFn<T extends Identifiable> = (entry: T) => boolean
+```
+
+### `DeleteManyOutput`
+
+Returned by bulk delete operations.
+
+```ts
+type DeleteManyOutput = {
+  deletedIds: string[]
+  ignoredIds: string[]
+}
+```
+
+---
+
+## Non-goals
+
+* Concurrency control
+* High-performance querying
+* Large datasets
+* ACID guarantees
+
+For these, a dedicated database is recommended.
+
+---
+
+## License
+
+MIT

package/dist/cjs/index.cjs

@@ -27,6 +27,106 @@ var path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
 var fsSync__namespace = /*#__PURE__*/_interopNamespaceDefault(fsSync);
 var readline__namespace = /*#__PURE__*/_interopNamespaceDefault(readline);
 
+class MultiEntryDb {
+    async getByIdOrThrow(id) {
+        const entry = await this.getById(id);
+        if (!entry)
+            throw new Error(`Entry with id '${id}' does not exist`);
+        return entry;
+    }
+    async getWhere(predicate, pagination) {
+        let totalMatched = 0;
+        const entries = [];
+        if (!pagination) {
+            for await (const entry of this.iterEntries()) {
+                const isMatch = predicate(entry);
+                if (isMatch)
+                    entries.push(entry);
+            }
+            return entries;
+        }
+        const { take, page } = pagination;
+        const skip = pagination.skip ?? 0;
+        const startIndex = (page - 1) * take + skip;
+        const endIndex = startIndex + take;
+        for await (const entry of this.iterEntries()) {
+            const isMatch = predicate(entry);
+            if (isMatch) {
+                if (totalMatched >= startIndex && totalMatched < endIndex) {
+                    entries.push(entry);
+                }
+                totalMatched++;
+                if (totalMatched >= endIndex)
+                    break;
+            }
+        }
+        return entries;
+    }
+    getAll() {
+        return this.getWhere(() => true);
+    }
+    async getAllIds() {
+        const ids = [];
+        for await (const id of this.iterIds()) {
+            ids.push(id);
+        }
+        return ids;
+    }
+    deleteByIds(ids) {
+        return this.deleteWhere((entry) => ids.includes(entry.id));
+    }
+    async deleteWhere(predicate) {
+        const deletedIds = [];
+        const ignoredIds = [];
+        for await (const entry of this.iterEntries()) {
+            if (!predicate(entry))
+                continue;
+            const didDelete = await this.deleteById(entry.id);
+            if (didDelete) {
+                deletedIds.push(entry.id);
+            }
+            else {
+                ignoredIds.push(entry.id);
+            }
+        }
+        return { deletedIds, ignoredIds };
+    }
+    async exists(id) {
+        const entry = await this.getById(id);
+        return entry !== null;
+    }
+    countAll() {
+        return this.countWhere(() => true);
+    }
+    async countWhere(predicate, pagination) {
+        let totalMatched = 0;
+        let count = 0;
+        if (!pagination) {
+            for await (const entry of this.iterEntries()) {
+                const isMatch = predicate(entry);
+                if (isMatch)
+                    count++;
+            }
+            return count;
+        }
+        const { take, page } = pagination;
+        const skip = pagination.skip ?? 0;
+        const startIndex = (page - 1) * take + skip;
+        const endIndex = startIndex + take;
+        for await (const entry of this.iterEntries()) {
+            const isMatch = predicate(entry);
+            if (isMatch) {
+                if (totalMatched >= startIndex && totalMatched < endIndex)
+                    count++;
+                totalMatched++;
+                if (totalMatched >= endIndex)
+                    break;
+            }
+        }
+        return count;
+    }
+}
+
 exports.FileType = void 0;
 (function (FileType) {
     FileType["File"] = "file";
@@ -35,7 +135,7 @@ exports.FileType = void 0;
 })(exports.FileType || (exports.FileType = {}));
 
 const DEFUALT_ENCODING = 'utf-8';
-class FilesService {
+class Files {
     async move(oldPath, newPath) {
         await fs__namespace.rename(oldPath, newPath);
     }
@@ -243,64 +343,44 @@ class FilesService {
     }
 }
 
-class MultiEntryFileDb {
-    constructor(dirpath, parser = JSON) {
+class MultiEntryFileDb extends MultiEntryDb {
+    constructor(dirpath, options) {
+        super();
         this.dirpath = dirpath;
-        this.parser = parser;
-        this.files = new FilesService();
+        this.files = new Files();
+        this.parser = options?.parser ?? JSON;
+        this.noPathlikeIds = options?.noPathlikeIds ?? true;
     }
     async create(entry) {
         await this.writeEntry(entry);
         return entry;
     }
     async getById(id) {
-        return await this.readEntry(id);
-    }
-    async getByIdOrThrow(id) {
-        const entry = await this.readEntry(id);
-        if (!entry) {
-            throw new Error('Entry with id ' + id + ' does not exist');
-        }
-        return entry;
-    }
-    async getWhere(predicate, max) {
-        const entries = await this.getAll();
-        return entries.filter(predicate).slice(0, max);
-    }
-    async getAll(whereIds) {
-        const ids = whereIds === undefined ? await this.getAllIds() : whereIds;
-        const entries = [];
-        for (const id of ids) {
-            const entry = await this.readEntry(id);
-            if (entry)
-                entries.push(entry);
-        }
-        return entries;
-    }
-    async getAllIds() {
+        if (!this.isIdValid(id))
+            throw new Error(`Invalid id: ${id}`);
         try {
-            const entries = await this.files.list(this.dirpath);
-            return entries.filter((name) => name.endsWith('.json')).map((name) => name.slice(0, -5)); // Remove .json extension
+            const filepath = this.getFilePath(id);
+            const text = await this.files.read(filepath);
+            const entry = this.parser.parse(text);
+            return entry;
         }
-        catch {
-            // Directory might not exist
-            return [];
+        catch (error) {
+            console.error('Failed to read entry', error);
+            // File doesn't exist or invalid JSON
+            return null;
         }
     }
     async update(id, updater) {
-        const entry = await this.readEntry(id);
-        if (!entry) {
-            throw new Error('Entry with id ' + id + ' does not exist');
-        }
+        const entry = await this.getByIdOrThrow(id);
         const updatedEntryFields = await updater(entry);
         const updatedEntry = { ...entry, ...updatedEntryFields };
         await this.writeEntry(updatedEntry);
         if (updatedEntry.id !== id) {
-            await this.delete(id);
+            await this.deleteById(id);
         }
         return updatedEntry;
     }
-    async delete(id) {
+    async deleteById(id) {
         try {
             const filepath = this.getFilePath(id);
             await this.files.delete(filepath, { force: false });
@@ -314,71 +394,51 @@ class MultiEntryFileDb {
     async deleteByIds(ids) {
         return this.deleteWhere((entry) => ids.includes(entry.id));
     }
-    async deleteWhere(predicate) {
-        const deletedIds = [];
-        const ignoredIds = [];
-        for await (const entry of this.iterEntries()) {
-            if (!predicate(entry))
-                continue;
-            const didDelete = await this.delete(entry.id);
-            if (didDelete) {
-                deletedIds.push(entry.id);
-            }
-            else {
-                ignoredIds.push(entry.id);
-            }
-        }
-        return { deletedIds, ignoredIds };
-    }
     async destroy() {
         await this.files.delete(this.dirpath);
     }
-    async exists(id) {
-        const entry = await this.readEntry(id);
-        return entry !== null;
-    }
-    async countAll() {
-        const ids = await this.getAllIds();
-        return ids.length;
-    }
-    async countWhere(predicate) {
-        return (await this.getWhere(predicate)).length;
-    }
     getFilePath(id) {
         return path__namespace.join(this.dirpath, `${id}.json`);
     }
-    async readEntry(id) {
-        try {
-            const filepath = this.getFilePath(id);
-            const text = await this.files.read(filepath);
-            const entry = this.parser.parse(text);
-            return entry;
-        }
-        catch (error) {
-            console.error('Failed to read entry', error);
-            // File doesn't exist or invalid JSON
-            return null;
-        }
-    }
     async writeEntry(entry) {
+        if (!this.isIdValid(entry.id))
+            throw new Error(`Invalid id: ${entry.id}`);
         const filepath = this.getFilePath(entry.id);
         await this.files.write(filepath, JSON.stringify(entry, null, 2));
     }
+    isIdValid(id) {
+        if (typeof id !== 'string')
+            return false;
+        if (!this.noPathlikeIds)
+            return true;
+        if (id.includes('/') || id.includes('\\'))
+            return false;
+        return true;
+    }
     async *iterEntries() {
-        const ids = await this.getAllIds();
-        for (const id of ids) {
-            const entry = await this.readEntry(id);
+        for await (const id of this.iterIds()) {
+            const entry = await this.getById(id);
             if (entry)
                 yield entry;
         }
     }
+    async *iterIds() {
+        const filenames = await this.files.list(this.dirpath);
+        for (const filename of filenames) {
+            if (!filename.endsWith('.json'))
+                continue;
+            const id = filename.replace(/\.json$/, '');
+            if (this.isIdValid(id))
+                yield id;
+        }
+    }
 }
 
 class SingleEntryFileDb {
     constructor(filepath, parser = JSON) {
         this.filepath = filepath;
         this.parser = parser;
-        this.files = new FilesService();
+        this.files = new Files();
     }
     path() {
         return this.filepath;
@@ -411,6 +471,81 @@ class SingleEntryFileDb {
     }
 }
 
+class MultiEntryMemDb extends MultiEntryDb {
+    constructor() {
+        super(...arguments);
+        this.entries = new Map();
+    }
+    async create(entry) {
+        this.entries.set(entry.id, entry);
+        return entry;
+    }
+    async getById(id) {
+        return this.entries.get(id) ?? null;
+    }
+    async update(id, updater) {
+        const entry = await this.getByIdOrThrow(id);
+        const updatedEntryFields = await updater(entry);
+        const updatedEntry = { ...entry, ...updatedEntryFields };
+        this.entries.set(updatedEntry.id, updatedEntry);
+        if (updatedEntry.id !== id)
+            this.entries.delete(id);
+        return updatedEntry;
+    }
+    async deleteById(id) {
+        return this.entries.delete(id);
+    }
+    async destroy() {
+        this.entries.clear();
+    }
+    async *iterEntries() {
+        for (const entry of this.entries.values()) {
+            yield entry;
+        }
+    }
+    async *iterIds() {
+        for (const id of this.entries.keys()) {
+            yield id;
+        }
+    }
+}
+
+class SingleEntryMemDb {
+    constructor(initialEntry = null) {
+        this.entry = null;
+        this.entry = initialEntry;
+    }
+    isInited() {
+        return this.entry !== null;
+    }
+    read() {
+        if (this.entry === null)
+            throw new Error('Entry not initialized');
+        return this.entry;
+    }
+    write(updaterOrEntry) {
+        let entry;
+        if (typeof updaterOrEntry === 'function') {
+            const updater = updaterOrEntry;
+            if (this.entry === null) {
+                throw new Error('Cannot update uninitialized entry. Use write(entry) to initialize first.');
+            }
+            const updatedFields = updater(this.entry);
+            entry = { ...this.entry, ...updatedFields };
+        }
+        else {
+            entry = updaterOrEntry;
+        }
+        this.entry = entry;
+        return entry;
+    }
+    delete() {
+        this.entry = null;
+    }
+}
+
 exports.MultiEntryFileDb = MultiEntryFileDb;
+exports.MultiEntryMemDb = MultiEntryMemDb;
 exports.SingleEntryFileDb = SingleEntryFileDb;
+exports.SingleEntryMemDb = SingleEntryMemDb;
 //# sourceMappingURL=index.cjs.map