boma 2.1.0 → 2.1.1

package/dist/async.js

@@ -1,14 +1,30 @@
 import { readFile, writeFile } from 'fs/promises';
+import { resolve } from 'path';
 import { getDate, getIssueMessage, getSerializationIssues, isErrorWithCode, isPlainMergeableObject, isSyntaxError, logSerializationIssues, sanitizeNonSerializable, } from './common.js';
+const addToJSONQueues = new Map();
+const runAddToJSONExclusive = async (filePath, operation) => {
+    const key = resolve(filePath);
+    const previous = addToJSONQueues.get(key) ?? Promise.resolve();
+    const current = previous.catch(() => undefined).then(operation);
+    const settled = current.then(() => undefined, () => undefined);
+    addToJSONQueues.set(key, settled);
+    try {
+        return await current;
+    }
+    finally {
+        if (addToJSONQueues.get(key) === settled) {
+            addToJSONQueues.delete(key);
+        }
+    }
+};
 export const saveJSONAsync = async (saveInput) => {
     const { filePath, objToSave, format = false, logSaving = false, replaceNonSerializable = false, silent = true, } = saveInput;
     const issues = getSerializationIssues(objToSave);
     if (issues.length > 0) {
         !silent && logSerializationIssues(issues);
-        if (!replaceNonSerializable && !silent) {
+        if (!replaceNonSerializable) {
             const firstIssue = issues[0];
             const errorMessage = `[${getDate()}] Boma got non JSON-serializable object at saveJSON! ${getIssueMessage(firstIssue)}`;
-            console.error(errorMessage);
             throw new Error(errorMessage);
         }
     }
@@ -28,7 +44,7 @@ export const saveJSONAsync = async (saveInput) => {
     }
 };
 export const readJSONAsync = async (props) => {
-    const { filePath, createIfNotFound = false, parseJSON = true, silent = true } = props;
+    const { filePath, createIfNotFound = false, parseJSON = true, silent = true, throwError = false, } = props;
     try {
         const savedfile = await readFile(filePath, 'utf8');
         if (parseJSON) {
@@ -37,41 +53,54 @@ export const readJSONAsync = async (props) => {
         return savedfile;
     }
     catch (err) {
+        if (throwError)
+            throw err;
         if (isErrorWithCode(err)) {
             switch (err.code) {
                 case 'ENOENT':
                     if (createIfNotFound) {
                         !silent && console.log('Try to create: ', filePath);
+                        const initialValue = typeof createIfNotFound === 'boolean' ? {} : createIfNotFound;
+                        const initialContent = JSON.stringify(initialValue);
                         try {
-                            const initialContent = typeof createIfNotFound === 'boolean' ? '{}' : JSON.stringify(createIfNotFound);
-                            await writeFile(filePath, initialContent, 'utf8');
+                            await writeFile(filePath, initialContent, { encoding: 'utf8', flag: 'wx' });
                         }
                         catch (writeErr) {
-                            console.error(`Error creating file ${filePath}: `, writeErr, '\n');
+                            if (isErrorWithCode(writeErr) && writeErr.code === 'EEXIST') {
+                                return readJSONAsync({ ...props, createIfNotFound: false });
+                            }
+                            if (throwError)
+                                throw writeErr;
+                            console.error(`[${getDate()}] Boma got error while creating file ${filePath}: `, writeErr, '\n');
                         }
-                        return (typeof createIfNotFound === 'boolean' ? {} : createIfNotFound);
+                        return (parseJSON ? initialValue : initialContent);
                     }
-                    console.info("Boma can't find file: ", filePath);
+                    !silent && console.info("Boma can't find file: ", filePath);
                     return parseJSON ? {} : null;
                 case 'EACCES':
-                    console.error(`Access denied for ${filePath}`);
+                    !silent && console.error(`[${getDate()}] Access denied error for ${filePath}`);
                     return null;
                 default:
-                    console.error(`Some filesystem error when try readJSON: ${filePath}`);
+                    !silent && console.error(`[${getDate()}] Boma get some filesystem error when try readJSON: ${filePath}`, err);
                     return null;
             }
         }
         if (isSyntaxError(err)) {
-            console.error('File ', filePath, ' has incorrect JSON syntax', '\n');
+            !silent && console.error('File ', filePath, ' has incorrect JSON syntax', '\n');
             return null;
         }
-        console.error('Function readJSON error:', err, '\n');
+        !silent && console.error('Function readJSON error:', err, '\n');
         return null;
     }
 };
-export const addToJSONAsync = async (saveInput) => {
-    const { filePath, dataToAdd, format = false, logSaving = false, replaceNonSerializable = false, silent = true, } = saveInput;
-    const oldJSON = await readJSONAsync({ filePath, createIfNotFound: true, silent });
+export const addToJSONAsync = (saveInput) => runAddToJSONExclusive(saveInput.filePath, async () => {
+    const { filePath, dataToAdd, format = false, logSaving = false, replaceNonSerializable = false, silent = true, throwError = false, } = saveInput;
+    const oldJSON = await readJSONAsync({
+        filePath,
+        createIfNotFound: true,
+        silent,
+        throwError,
+    });
     if (oldJSON === null || typeof oldJSON !== 'object') {
         return saveJSONAsync({
             filePath,
@@ -79,7 +108,7 @@ export const addToJSONAsync = async (saveInput) => {
             format,
             logSaving,
             replaceNonSerializable,
-            silent
+            silent,
         });
     }
     if (Array.isArray(oldJSON) && Array.isArray(dataToAdd)) {
@@ -89,7 +118,7 @@ export const addToJSONAsync = async (saveInput) => {
             format,
             logSaving,
             replaceNonSerializable,
-            silent
+            silent,
         });
         return;
     }
@@ -100,20 +129,22 @@ export const addToJSONAsync = async (saveInput) => {
             format,
             logSaving,
             replaceNonSerializable,
-            silent
+            silent,
         });
         return;
     }
-    if (Array.isArray(dataToAdd) && isPlainMergeableObject(oldJSON) && Object.keys(oldJSON).length === 0) {
+    if (Array.isArray(dataToAdd)
+        && isPlainMergeableObject(oldJSON)
+        && Object.keys(oldJSON).length === 0) {
         await saveJSONAsync({
             filePath,
             objToSave: [...dataToAdd],
             format,
             logSaving,
             replaceNonSerializable,
-            silent
+            silent,
         });
         return;
     }
     throw new Error('Cannot merge array with object');
-};
+});

package/dist/boma.js

@@ -3,14 +3,13 @@ import { addToJSONAsync, readJSONAsync, saveJSONAsync } from './async.js';
 import { getDate, getIssueMessage, getSerializationIssues, isErrorWithCode, isPlainMergeableObject, isSyntaxError, logSerializationIssues, sanitizeNonSerializable } from './common.js';
 export * from './common.js';
 const saveJSONSync = (saveInput) => {
-    const { filePath, objToSave, format = false, logSaving = false, replaceNonSerializable = false, silent = true, } = saveInput;
+    const { filePath, objToSave, format = false, logSaving = false, replaceNonSerializable = false, silent = true } = saveInput;
     const issues = getSerializationIssues(objToSave);
     if (issues.length > 0) {
         !silent && logSerializationIssues(issues);
-        if (!replaceNonSerializable && !silent) {
+        if (!replaceNonSerializable) {
             const firstIssue = issues[0];
             const errorMessage = `[${getDate()}] Boma got non JSON-serializable object at saveJSON! ${getIssueMessage(firstIssue)}`;
-            console.error(errorMessage);
             throw new Error(errorMessage);
         }
     }
@@ -30,7 +29,7 @@ const saveJSONSync = (saveInput) => {
     }
 };
 const readJSONSync = (props) => {
-    const { filePath, createIfNotFound = false, parseJSON = true, silent = true } = props;
+    const { filePath, createIfNotFound = false, parseJSON = true, silent = true, throwError = false, } = props;
     try {
         const savedfile = readFileSync(filePath, 'utf8');
         if (parseJSON) {
@@ -39,41 +38,49 @@ const readJSONSync = (props) => {
         return savedfile;
     }
     catch (err) {
+        if (throwError)
+            throw err;
         if (isErrorWithCode(err)) {
             switch (err.code) {
                 case 'ENOENT':
                     if (createIfNotFound) {
                         !silent && console.log('Try to create: ', filePath);
+                        const initialValue = typeof createIfNotFound === 'boolean' ? {} : createIfNotFound;
+                        const initialContent = JSON.stringify(initialValue);
                         try {
-                            const initialContent = typeof createIfNotFound === 'boolean' ? '{}' : JSON.stringify(createIfNotFound);
-                            writeFileSync(filePath, initialContent, 'utf8');
+                            writeFileSync(filePath, initialContent, { encoding: 'utf8', flag: 'wx' });
                         }
                         catch (writeErr) {
-                            console.error(`Error creating file ${filePath}: `, writeErr, '\n');
+                            if (isErrorWithCode(writeErr) && writeErr.code === 'EEXIST') {
+                                return readJSONSync({ ...props, createIfNotFound: false });
+                            }
+                            if (throwError)
+                                throw writeErr;
+                            console.error(`[${getDate()}] Boma got error while creating file ${filePath}: `, writeErr, '\n');
                         }
-                        return (typeof createIfNotFound === 'boolean' ? {} : createIfNotFound);
+                        return (parseJSON ? initialValue : initialContent);
                     }
-                    console.info("Boma can't find file: ", filePath);
+                    !silent && console.info("Boma can't find file: ", filePath);
                     return parseJSON ? {} : null;
                 case 'EACCES':
-                    console.error(`Access denied for ${filePath}`);
+                    !silent && console.error(`Access denied for ${filePath}`);
                     return null;
                 default:
-                    console.error(`Some filesystem error when try readJSON: ${filePath}`);
+                    !silent && console.error(`Some filesystem error when try readJSON: ${filePath}`, err);
                     return null;
             }
         }
         if (isSyntaxError(err)) {
-            console.error('File ', filePath, ' has incorrect JSON syntax', '\n');
+            !silent && console.error('File ', filePath, ' has incorrect JSON syntax', '\n');
             return null;
         }
-        console.error('Function readJSON error:', err, '\n');
+        !silent && console.error('Function readJSON error:', err, '\n');
         return null;
     }
 };
 const addToJSONSync = (saveInput) => {
-    const { filePath, dataToAdd, format = false, logSaving = false, replaceNonSerializable = false, silent = true, } = saveInput;
-    const oldJSON = readJSONSync({ filePath, createIfNotFound: true, silent });
+    const { filePath, dataToAdd, format = false, logSaving = false, replaceNonSerializable = false, silent = true, throwError = false, } = saveInput;
+    const oldJSON = readJSONSync({ filePath, createIfNotFound: true, silent, throwError });
     if (oldJSON === null || typeof oldJSON !== 'object') {
         return saveJSONSync({ filePath, objToSave: dataToAdd, format, logSaving, replaceNonSerializable, silent });
     }

package/dist/common.d.ts

@@ -11,6 +11,7 @@ export interface ReadJSONProps {
     parseJSON?: boolean;
     createIfNotFound?: boolean | SerializableObject | SerializableArray;
     silent?: boolean;
+    throwError?: boolean;
     async?: boolean;
 }
 export interface SaveJSONProps {
@@ -29,6 +30,7 @@ export interface addToJSONProps {
     logSaving?: boolean;
     replaceNonSerializable?: boolean;
     silent?: boolean;
+    throwError?: boolean;
     async?: boolean;
 }
 export type ReadJSONSyncProps = ReadJSONProps & {

package/dist/common.js

@@ -168,6 +168,9 @@ export const sanitizeNonSerializable = (value, path = '$', ancestors = new WeakM
         if (ancestors.has(value)) {
             return 'circular';
         }
+        if (typeof value.toJSON === 'function') {
+            return sanitizeNonSerializable(value.toJSON(), path, ancestors);
+        }
         ancestors.set(value, path);
         const result = {};
         for (const key of Object.keys(value)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "boma",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Simple JSON helper",
   "main": "./dist/boma.js",
   "types": "./dist/boma.d.ts",

package/readme.md

@@ -1,5 +1,7 @@
 # Boma JSON helper
 
+[![npm version](https://img.shields.io/npm/v/boma?color=%20027dec)](https://www.npmjs.org/package/boma)
+
 Super-simple helper for reading, saving and updating JSON files.
 
 Works in synchronous mode by default.
@@ -7,6 +9,17 @@ Pass `async: true` to use the asynchronous implementation.
 
 Old synchronous calls remain unchanged.
 
+# Basic features
+
+- Using the `createIfNotFound` parameter in `readJSON` and `addToJSONS`, you can immediately create a missing file with the specified (default) object or array without any additional steps. This is convenient, for example, for writing configuration files.
+- `addToJSON` — reads a file and shallow merges objects or concatenates arrays.
+- Flag `replaceNonSerializable` — replaces `function`, `undefined`, `bigint`, `loops`, `NaN`, and `Infinity` with understandable markers.
+- Flag `getSerializationIssues` — shows all problematic fields with paths like `[OBJECT].user.callback`.
+- Single interface with `async: true`, instead of separate `readFile` / `readFileSync`.
+- You can get raw text using flag `parseJSON`: false.
+- By default, boma hides many errors when reading a file and returns `null` or `{}` — this is very convenient in a production environment. If necessary, you can set the `throwError: true` in `readJSON` and `addToJSONS` to catch and handle all errors yourself. However, write errors are much more critical, so `boma` always throws them.
+- Concurrent `addToJSON` calls within the same process are serialized per file, preventing lost updates from overlapping read–merge–write cycles. **Important! This does not provide cross-process or cross-thread locking, so multiple workers or external writers may still cause race conditions.**
+
 # Install
 
 ```bash