@jsonkit/db 2.0.1 → 3.0.2

package/README.md

@@ -4,8 +4,8 @@
 
 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`.
+- **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.
 
@@ -19,67 +19,28 @@ npm install @jsonkit/db
 
 ---
 
-## 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
-```
-
-### `DeleteManyOutput`
-
-Returned by bulk delete operations.
-
-```ts
-type DeleteManyOutput = {
-  deletedIds: string[]
-  ignoredIds: string[]
-}
-```
-
----
-
 ## Multi-entry Databases
 
 Multi-entry databases manage collections of entries keyed by `id`.
 
 ### Common API (`MultiEntryDb<T>`)
 
-All multi-entry implementations expose the same async API:
-
-* `create(entry)`
-* `getById(id)`
-* `getByIdOrThrow(id)`
-* `getWhere(predicate, max?)`
-* `getAll(ids?)`
-* `getAllIds()`
-* `update(id, updater)`
-* `delete(id)`
-* `deleteByIds(ids)`
-* `deleteWhere(predicate)`
-* `exists(id)`
-* `countAll()`
-* `countWhere(predicate)`
-* `destroy()`
+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.
 
@@ -97,9 +58,9 @@ 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.
+- 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
 
@@ -116,9 +77,9 @@ new MultiEntryFileDb<T>(dirpath, options?)
 
 #### Notes
 
-* Failed reads (missing file or invalid JSON) return `null`.
-* `destroy()` deletes the entire directory.
-* Intended for development, prototyping, and small datasets.
+- Failed reads (missing file or invalid JSON) return `null`.
+- `destroy()` deletes the entire directory.
+- Intended for development, prototyping, and small datasets.
 
 ---
 
@@ -134,9 +95,9 @@ const db = new MultiEntryMemDb<User>()
 
 #### Behavior
 
-* Fast, ephemeral storage.
-* Ideal for tests and short-lived processes.
-* `destroy()` clears all entries.
+- Fast, ephemeral storage.
+- Ideal for tests and short-lived processes.
+- `destroy()` clears all entries.
 
 ---
 
@@ -146,10 +107,10 @@ Single-entry databases manage **exactly one value**, often used for configuratio
 
 ### Common API (`SingleEntryDb<T>`)
 
-* `isInited()`
-* `read()`
-* `write(entry | updater)`
-* `delete()`
+- `isInited()`
+- `read()`
+- `write(entry | updater)`
+- `delete()`
 
 `write` supports either replacing the entry or partially updating it via an updater function.
 
@@ -167,9 +128,9 @@ 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.
+- Reads and writes a single JSON file.
+- `isInited()` checks file existence.
+- `read()` throws if the file does not exist.
 
 #### Constructor
 
@@ -177,7 +138,7 @@ const db = new SingleEntryFileDb<AppConfig>('./config.json')
 new SingleEntryFileDb<T>(filepath, parser?)
 ```
 
-* `parser` defaults to `JSON`.
+- `parser` defaults to `JSON`.
 
 ---
 
@@ -193,9 +154,9 @@ const db = new SingleEntryMemDb<AppConfig>()
 
 #### Behavior
 
-* Optional initial value.
-* `read()` throws if uninitialized.
-* `delete()` resets the entry to `null`.
+- Optional initial value.
+- `read()` throws if uninitialized.
+- `delete()` resets the entry to `null`.
 
 ---
 
@@ -217,20 +178,67 @@ const allUsers = await users.getAll()
 
 ## Use Cases
 
-* Rapid application prototyping
-* CLI tools
-* Small internal services
-* Tests and mocks
-* Configuration and state persistence
+- 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
+- Concurrency control
+- High-performance querying
+- Large datasets
+- ACID guarantees
 
 For these, a dedicated database is recommended.
 

package/dist/cjs/index.cjs

@@ -27,16 +27,112 @@ 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";
     FileType["Directory"] = "directory";
     //Symlink: 'symlink'
 })(exports.FileType || (exports.FileType = {}));
-class SingleEntryDb {
-}
-class MultiEntryDb {
-}
 
 const DEFUALT_ENCODING = 'utf-8';
 class Files {
@@ -260,53 +356,31 @@ class MultiEntryFileDb extends MultiEntryDb {
         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 });
@@ -320,54 +394,12 @@ class MultiEntryFileDb extends MultiEntryDb {
     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) {
-        if (!this.isIdValid(id))
-            throw new Error(`Invalid id: ${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}`);
@@ -384,18 +416,26 @@ class MultiEntryFileDb extends MultiEntryDb {
         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 extends SingleEntryDb {
+class SingleEntryFileDb {
     constructor(filepath, parser = JSON) {
-        super();
         this.filepath = filepath;
         this.parser = parser;
         this.files = new Files();
@@ -443,108 +483,54 @@ class MultiEntryMemDb extends MultiEntryDb {
     async getById(id) {
         return this.entries.get(id) ?? null;
     }
-    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, max) {
-        const entries = Array.from(this.entries.values()).filter(predicate);
-        return max !== undefined ? entries.slice(0, max) : entries;
-    }
-    async getAll(whereIds) {
-        if (whereIds === undefined) {
-            return Array.from(this.entries.values());
-        }
-        const entries = [];
-        for (const id of whereIds) {
-            const entry = this.entries.get(id);
-            if (entry)
-                entries.push(entry);
-        }
-        return entries;
-    }
-    async getAllIds() {
-        return Array.from(this.entries.keys());
-    }
     async update(id, updater) {
-        const entry = this.entries.get(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 };
         this.entries.set(updatedEntry.id, updatedEntry);
-        if (updatedEntry.id !== id) {
+        if (updatedEntry.id !== id)
             this.entries.delete(id);
-        }
         return updatedEntry;
     }
-    async delete(id) {
+    async deleteById(id) {
         return this.entries.delete(id);
     }
-    async deleteByIds(ids) {
-        return this.deleteWhere((entry) => ids.includes(entry.id));
-    }
-    async deleteWhere(predicate) {
-        const deletedIds = [];
-        const ignoredIds = [];
-        for (const [id, entry] of this.entries) {
-            if (!predicate(entry))
-                continue;
-            const didDelete = await this.delete(id);
-            if (didDelete) {
-                deletedIds.push(id);
-            }
-            else {
-                ignoredIds.push(id);
-            }
-        }
-        return { deletedIds, ignoredIds };
-    }
     async destroy() {
         this.entries.clear();
     }
-    async exists(id) {
-        return this.entries.has(id);
-    }
-    async countAll() {
-        return this.entries.size;
-    }
-    async countWhere(predicate) {
-        return Array.from(this.entries.values()).filter(predicate).length;
-    }
     async *iterEntries() {
         for (const entry of this.entries.values()) {
             yield entry;
         }
     }
+    async *iterIds() {
+        for (const id of this.entries.keys()) {
+            yield id;
+        }
+    }
 }
 
-class SingleEntryMemDb extends SingleEntryDb {
+class SingleEntryMemDb {
     constructor(initialEntry = null) {
-        super();
         this.entry = null;
         this.entry = initialEntry;
     }
-    async isInited() {
+    isInited() {
         return this.entry !== null;
     }
-    async read() {
+    read() {
         if (this.entry === null)
             throw new Error('Entry not initialized');
         return this.entry;
     }
-    async write(updaterOrEntry) {
+    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 = await updater(this.entry);
+            const updatedFields = updater(this.entry);
             entry = { ...this.entry, ...updatedFields };
         }
         else {
@@ -553,15 +539,13 @@ class SingleEntryMemDb extends SingleEntryDb {
         this.entry = entry;
         return entry;
     }
-    async delete() {
+    delete() {
         this.entry = null;
     }
 }
 
-exports.MultiEntryDb = MultiEntryDb;
 exports.MultiEntryFileDb = MultiEntryFileDb;
 exports.MultiEntryMemDb = MultiEntryMemDb;
-exports.SingleEntryDb = SingleEntryDb;
 exports.SingleEntryFileDb = SingleEntryFileDb;
 exports.SingleEntryMemDb = SingleEntryMemDb;
 //# sourceMappingURL=index.cjs.map