jsoning

library1.0.1jsnpmunverified

Jsoning is a lightweight, key-value JSON-based persistent database library designed for Node.js environments. It currently maintains version 1.0.1 and has a moderate release cadence, with significant updates like the v1.0.0 TypeScript rewrite. The library focuses on ease of use and beginner-friendliness, providing a simple API for common database operations such as setting, getting, pushing, and deleting data within JSON files. Key differentiators include atomic file writing to prevent data corruption, built-in TypeScript support, and EventEmitter integration for reacting to database changes, making it suitable for small projects, prototyping, and educational purposes. It requires Node.js v16 or greater for operation.

database serialization

npm install jsoning

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JSONING

jsoning

databasejavascriptv1.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Jsoning

✓ import { Jsoning } from 'jsoning';

✗ const Jsoning = require('jsoning');

Since v1.0.0, jsoning is an ESM-first package, requiring named imports. CommonJS `require()` will not work for the main class.

MathOps

✓ import { MathOps } from 'jsoning';

✗ const MathOps = require('jsoning').MathOps;

MathOps is an enum for arithmetic operations, exported as a named export from the main package. Correctly import it with destructuring.

Jsoning (Type)

✓ import type { Jsoning } from 'jsoning';

✗ import { Jsoning } from 'jsoning';

While `Jsoning` is a class and can be imported as a value, explicitly using `import type` is a best practice for type-only imports in TypeScript, though not strictly required for classes in all TS configurations.

This example demonstrates basic CRUD operations using Jsoning, including setting and getting key-value pairs, manipulating arrays with push and remove, performing arithmetic operations, and clearing the entire database. It ensures a clean start and uses explicit file path handling for clarity.

import { Jsoning, MathOps } from 'jsoning'; import { createRequire } from 'module'; import path from 'path'; import { fileURLToPath } from 'url'; const require = createRequire(import.meta.url); const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); const dbPath = path.join(__dirname, 'temp-database.json'); const db = new Jsoning(dbPath); async function runExample() { console.log('--- Initializing Database ---'); await db.clear(); // Ensure a clean start // Set some values with a key await db.set('birthday', '07-aug'); await db.set('age', '13'); console.log('Set birthday and age.'); // Push stuff to an array for a particular key await db.push('transformers', 'optimus prime'); await db.push('transformers', 'bumblebee'); await db.push('transformers', 'iron hide'); console.log('Pushed transformers.'); // Get the value of a key console.log('Transformers:', await db.get('transformers')); // Get all the values console.log('All data:', await db.all()); // does such a value exist? console.log('Has "value2"?', await db.has('value2')); // My age keeps changing, so I'm deleting it console.log('Deleted age:', await db.delete('age')); // I got $100 for my birthday await db.set('money', 100); // and someone gave me $200 more await db.math('money', MathOps.Add, 200); console.log('Performed math operation on money.'); // Just wanna make sure how much money I got console.log('Current money:', await db.get('money')); // RIP iron hide, he died await db.remove('transformers', 'iron hide'); console.log('Removed iron hide from transformers:', await db.get('transformers')); // I'm getting bored, so I'm clearing the whole database await db.clear(); console.log('Cleared database.'); console.log('All data after clear:', await db.all()); } runExample().catch(console.error);

Debug

Known issues

breakingSince v1.0.0, jsoning has been rewritten in TypeScript and moved to an ESM-first architecture. This requires `import` syntax and Node.js v16 or higher. Older CommonJS `require()` statements will not work for importing `Jsoning`.

fix

Migrate your project to use ES modules (`type: 'module'` in `package.json` or `.mjs` files) and replace `require()` with `import { Jsoning } from 'jsoning';`. Ensure your Node.js version is 16 or greater.

affects: >=1.0.0

breakingPrior to v0.13.23, the `get()` method would return `false` if a key was not found. Since v0.13.23, it correctly returns `null` for non-existent keys. Applications relying on the `false` return value for logic might need adjustment.

fix

Update your code to check for `null` instead of `false` when determining if a key exists after a `get()` call (e.g., `if (value === null)` or `if (value == null)`).

affects: >=0.13.23

gotchaFrom v0.10.19, JSON database files are generated and chosen relative to the current working directory where the Node.js process is executed. This can cause issues if your application's CWD changes or if you expect files in a fixed location relative to your script.

fix

Always provide an absolute path to the `Jsoning` constructor, or ensure your application explicitly sets or manages its current working directory if relying on relative paths.

affects: >=0.10.19

breakingA prototype pollution vulnerability was discovered and patched in v0.9.18. Users running versions prior to 0.9.18 are strongly advised to update immediately to mitigate potential security risks.

fix

Upgrade to jsoning v0.9.18 or higher to patch the prototype pollution vulnerability.

affects: <0.9.18

gotchaMany `jsoning` methods (e.g., `set`, `get`, `push`, `delete`, `all`) are asynchronous and return Promises. Forgetting to use `await` or handle these Promises can lead to unhandled promise rejections, incorrect data, or unexpected program flow.

fix

Always use `await` before calling `jsoning` methods within an `async` function, or handle the returned Promises with `.then().catch()`.

affects: >=0.8.14

Errors

Common errors & fixes

TypeError: Jsoning is not a constructor

Attempting to import `Jsoning` using CommonJS `require()` syntax or as a default import when it's an ESM named export (since v1.0.0).

fix

Change your import statement to `import { Jsoning } from 'jsoning';` and ensure your environment supports ES modules (Node.js >=16 with `type: 'module'` in `package.json`).

(node:XXXX) UnhandledPromiseRejectionWarning: TypeError: (intermediate value).then is not a function

An asynchronous `jsoning` method (like `set`, `get`, `all`) was called without `await`, and its returned Promise was not handled.

fix

Ensure all calls to `jsoning` methods are `await`ed within an `async` function. For example, `await db.set('key', 'value');`.

Error: ENOENT: no such file or directory, open 'database.json'

The specified database file path is incorrect, or the `jsoning` instance is trying to access/create the file in an unexpected location due to changes in current working directory handling (since v0.10.19).

fix

Provide an absolute path to the `Jsoning` constructor (e.g., `new Jsoning(path.join(__dirname, 'data', 'my-db.json'))`) to ensure the file is always accessed from a predictable location.

ReferenceError: MathOps is not defined

Attempting to use the `MathOps` enum without explicitly importing it as a named export.

fix

Add `import { MathOps } from 'jsoning';` to your file alongside the `Jsoning` import.

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/khalby786/jsoning ↗

packagehttps://www.npmjs.com/package/jsoning ↗

homepagehttps://jsoning.js.org ↗