{"id":16634,"library":"jsoning","title":"Jsoning","description":"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.","status":"active","version":"1.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/khalby786/jsoning","tags":["javascript","json","database","typescript"],"install":[{"cmd":"npm install jsoning","lang":"bash","label":"npm"},{"cmd":"yarn add jsoning","lang":"bash","label":"yarn"},{"cmd":"pnpm add jsoning","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v1.0.0, jsoning is an ESM-first package, requiring named imports. CommonJS `require()` will not work for the main class.","wrong":"const Jsoning = require('jsoning');","symbol":"Jsoning","correct":"import { Jsoning } from 'jsoning';"},{"note":"MathOps is an enum for arithmetic operations, exported as a named export from the main package. Correctly import it with destructuring.","wrong":"const MathOps = require('jsoning').MathOps;","symbol":"MathOps","correct":"import { MathOps } from 'jsoning';"},{"note":"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.","wrong":"import { Jsoning } from 'jsoning';","symbol":"Jsoning (Type)","correct":"import type { Jsoning } from 'jsoning';"}],"quickstart":{"code":"import { Jsoning, MathOps } from 'jsoning';\nimport { createRequire } from 'module';\nimport path from 'path';\nimport { fileURLToPath } from 'url';\n\nconst require = createRequire(import.meta.url);\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\nconst dbPath = path.join(__dirname, 'temp-database.json');\nconst db = new Jsoning(dbPath);\n\nasync function runExample() {\n  console.log('--- Initializing Database ---');\n  await db.clear(); // Ensure a clean start\n\n  // Set some values with a key\n  await db.set('birthday', '07-aug');\n  await db.set('age', '13');\n  console.log('Set birthday and age.');\n\n  // Push stuff to an array for a particular key\n  await db.push('transformers', 'optimus prime');\n  await db.push('transformers', 'bumblebee');\n  await db.push('transformers', 'iron hide');\n  console.log('Pushed transformers.');\n\n  // Get the value of a key\n  console.log('Transformers:', await db.get('transformers'));\n\n  // Get all the values\n  console.log('All data:', await db.all());\n\n  // does such a value exist?\n  console.log('Has \"value2\"?', await db.has('value2'));\n\n  // My age keeps changing, so I'm deleting it\n  console.log('Deleted age:', await db.delete('age'));\n\n  // I got $100 for my birthday\n  await db.set('money', 100);\n\n  // and someone gave me $200 more\n  await db.math('money', MathOps.Add, 200);\n  console.log('Performed math operation on money.');\n\n  // Just wanna make sure how much money I got\n  console.log('Current money:', await db.get('money'));\n\n  // RIP iron hide, he died\n  await db.remove('transformers', 'iron hide');\n  console.log('Removed iron hide from transformers:', await db.get('transformers'));\n\n  // I'm getting bored, so I'm clearing the whole database\n  await db.clear();\n  console.log('Cleared database.');\n  console.log('All data after clear:', await db.all());\n}\n\nrunExample().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Since 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`.","severity":"breaking","affected_versions":">=1.0.0"},{"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)`).","message":"Prior 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.","severity":"breaking","affected_versions":">=0.13.23"},{"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.","message":"From 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.","severity":"gotcha","affected_versions":">=0.10.19"},{"fix":"Upgrade to jsoning v0.9.18 or higher to patch the prototype pollution vulnerability.","message":"A 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.","severity":"breaking","affected_versions":"<0.9.18"},{"fix":"Always use `await` before calling `jsoning` methods within an `async` function, or handle the returned Promises with `.then().catch()`.","message":"Many `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.","severity":"gotcha","affected_versions":">=0.8.14"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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`).","cause":"Attempting to import `Jsoning` using CommonJS `require()` syntax or as a default import when it's an ESM named export (since v1.0.0).","error":"TypeError: Jsoning is not a constructor"},{"fix":"Ensure all calls to `jsoning` methods are `await`ed within an `async` function. For example, `await db.set('key', 'value');`.","cause":"An asynchronous `jsoning` method (like `set`, `get`, `all`) was called without `await`, and its returned Promise was not handled.","error":"(node:XXXX) UnhandledPromiseRejectionWarning: TypeError: (intermediate value).then is not a function"},{"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.","cause":"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).","error":"Error: ENOENT: no such file or directory, open 'database.json'"},{"fix":"Add `import { MathOps } from 'jsoning';` to your file alongside the `Jsoning` import.","cause":"Attempting to use the `MathOps` enum without explicitly importing it as a named export.","error":"ReferenceError: MathOps is not defined"}],"ecosystem":"npm"}