boma 2.0.6 → 2.1.1

package/dist/async.d.ts

@@ -0,0 +1,4 @@
+import type { addToJSONProps, ReadJSONProps, ReadJSONResult, SaveJSONProps } from './common.js';
+export declare const saveJSONAsync: (saveInput: SaveJSONProps) => Promise<void>;
+export declare const readJSONAsync: <T = any>(props: ReadJSONProps) => Promise<ReadJSONResult<T>>;
+export declare const addToJSONAsync: (saveInput: addToJSONProps) => Promise<void>;

package/dist/async.js

@@ -0,0 +1,150 @@
+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) {
+            const firstIssue = issues[0];
+            const errorMessage = `[${getDate()}] Boma got non JSON-serializable object at saveJSON! ${getIssueMessage(firstIssue)}`;
+            throw new Error(errorMessage);
+        }
+    }
+    const valueToSave = replaceNonSerializable && issues.length > 0
+        ? sanitizeNonSerializable(objToSave)
+        : objToSave;
+    try {
+        const json = format ? JSON.stringify(valueToSave, null, 2) : JSON.stringify(valueToSave);
+        await writeFile(filePath, json, 'utf8');
+        !silent && logSaving && console.log(`[${getDate()}] Write file ${filePath} successfully`);
+    }
+    catch (error) {
+        if (isErrorWithCode(error)) {
+            console.error(`[${getDate()}] Boma got filesystem error for ${filePath}:`, error);
+        }
+        throw error;
+    }
+};
+export const readJSONAsync = async (props) => {
+    const { filePath, createIfNotFound = false, parseJSON = true, silent = true, throwError = false, } = props;
+    try {
+        const savedfile = await readFile(filePath, 'utf8');
+        if (parseJSON) {
+            return savedfile.trim() === '' ? null : JSON.parse(savedfile);
+        }
+        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 {
+                            await writeFile(filePath, initialContent, { encoding: 'utf8', flag: 'wx' });
+                        }
+                        catch (writeErr) {
+                            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 (parseJSON ? initialValue : initialContent);
+                    }
+                    !silent && console.info("Boma can't find file: ", filePath);
+                    return parseJSON ? {} : null;
+                case 'EACCES':
+                    !silent && console.error(`[${getDate()}] Access denied error for ${filePath}`);
+                    return null;
+                default:
+                    !silent && console.error(`[${getDate()}] Boma get some filesystem error when try readJSON: ${filePath}`, err);
+                    return null;
+            }
+        }
+        if (isSyntaxError(err)) {
+            !silent && console.error('File ', filePath, ' has incorrect JSON syntax', '\n');
+            return null;
+        }
+        !silent && console.error('Function readJSON error:', err, '\n');
+        return null;
+    }
+};
+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,
+            objToSave: dataToAdd,
+            format,
+            logSaving,
+            replaceNonSerializable,
+            silent,
+        });
+    }
+    if (Array.isArray(oldJSON) && Array.isArray(dataToAdd)) {
+        await saveJSONAsync({
+            filePath,
+            objToSave: [...oldJSON, ...dataToAdd],
+            format,
+            logSaving,
+            replaceNonSerializable,
+            silent,
+        });
+        return;
+    }
+    if (isPlainMergeableObject(oldJSON) && isPlainMergeableObject(dataToAdd)) {
+        await saveJSONAsync({
+            filePath,
+            objToSave: { ...oldJSON, ...dataToAdd },
+            format,
+            logSaving,
+            replaceNonSerializable,
+            silent,
+        });
+        return;
+    }
+    if (Array.isArray(dataToAdd)
+        && isPlainMergeableObject(oldJSON)
+        && Object.keys(oldJSON).length === 0) {
+        await saveJSONAsync({
+            filePath,
+            objToSave: [...dataToAdd],
+            format,
+            logSaving,
+            replaceNonSerializable,
+            silent,
+        });
+        return;
+    }
+    throw new Error('Cannot merge array with object');
+});

package/dist/boma.d.ts

@@ -0,0 +1,11 @@
+import type { AddToJSONAsyncProps, addToJSONProps, AddToJSONSyncProps, ReadJSONAsyncProps, ReadJSONProps, ReadJSONResult, ReadJSONSyncProps, SaveJSONAsyncProps, SaveJSONProps, SaveJSONSyncProps } from './common.js';
+export * from './common.js';
+export declare function saveJSON(props: SaveJSONAsyncProps): Promise<void>;
+export declare function saveJSON(props: SaveJSONSyncProps): void;
+export declare function saveJSON(props: SaveJSONProps): void | Promise<void>;
+export declare function readJSON<T = any>(props: ReadJSONAsyncProps): Promise<ReadJSONResult<T>>;
+export declare function readJSON<T = any>(props: ReadJSONSyncProps): ReadJSONResult<T>;
+export declare function readJSON<T = any>(props: ReadJSONProps): ReadJSONResult<T> | Promise<ReadJSONResult<T>>;
+export declare function addToJSON(props: AddToJSONAsyncProps): Promise<void>;
+export declare function addToJSON(props: AddToJSONSyncProps): void;
+export declare function addToJSON(props: addToJSONProps): void | Promise<void>;

package/dist/boma.js

@@ -0,0 +1,130 @@
+import { readFileSync, writeFileSync } from 'fs';
+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 issues = getSerializationIssues(objToSave);
+    if (issues.length > 0) {
+        !silent && logSerializationIssues(issues);
+        if (!replaceNonSerializable) {
+            const firstIssue = issues[0];
+            const errorMessage = `[${getDate()}] Boma got non JSON-serializable object at saveJSON! ${getIssueMessage(firstIssue)}`;
+            throw new Error(errorMessage);
+        }
+    }
+    const valueToSave = replaceNonSerializable && issues.length > 0
+        ? sanitizeNonSerializable(objToSave)
+        : objToSave;
+    try {
+        const json = format ? JSON.stringify(valueToSave, null, 2) : JSON.stringify(valueToSave);
+        writeFileSync(filePath, json, 'utf8');
+        !silent && logSaving && console.log(`[${getDate()}] Write file ${filePath} successfully`);
+    }
+    catch (error) {
+        if (isErrorWithCode(error)) {
+            console.error(`[${getDate()}] Boma got filesystem error for ${filePath}:`, error);
+        }
+        throw error;
+    }
+};
+const readJSONSync = (props) => {
+    const { filePath, createIfNotFound = false, parseJSON = true, silent = true, throwError = false, } = props;
+    try {
+        const savedfile = readFileSync(filePath, 'utf8');
+        if (parseJSON) {
+            return savedfile.trim() === '' ? null : JSON.parse(savedfile);
+        }
+        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 {
+                            writeFileSync(filePath, initialContent, { encoding: 'utf8', flag: 'wx' });
+                        }
+                        catch (writeErr) {
+                            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 (parseJSON ? initialValue : initialContent);
+                    }
+                    !silent && console.info("Boma can't find file: ", filePath);
+                    return parseJSON ? {} : null;
+                case 'EACCES':
+                    !silent && console.error(`Access denied for ${filePath}`);
+                    return null;
+                default:
+                    !silent && console.error(`Some filesystem error when try readJSON: ${filePath}`, err);
+                    return null;
+            }
+        }
+        if (isSyntaxError(err)) {
+            !silent && console.error('File ', filePath, ' has incorrect JSON syntax', '\n');
+            return null;
+        }
+        !silent && console.error('Function readJSON error:', err, '\n');
+        return null;
+    }
+};
+const addToJSONSync = (saveInput) => {
+    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 });
+    }
+    if (Array.isArray(oldJSON) && Array.isArray(dataToAdd)) {
+        saveJSONSync({
+            filePath,
+            objToSave: [...oldJSON, ...dataToAdd],
+            format,
+            logSaving,
+            replaceNonSerializable,
+            silent
+        });
+        return;
+    }
+    if (isPlainMergeableObject(oldJSON) && isPlainMergeableObject(dataToAdd)) {
+        saveJSONSync({
+            filePath,
+            objToSave: { ...oldJSON, ...dataToAdd },
+            format,
+            logSaving,
+            replaceNonSerializable,
+            silent
+        });
+        return;
+    }
+    if (Array.isArray(dataToAdd) && isPlainMergeableObject(oldJSON) && Object.keys(oldJSON).length === 0) {
+        saveJSONSync({
+            filePath,
+            objToSave: [...dataToAdd],
+            format,
+            logSaving,
+            replaceNonSerializable,
+            silent
+        });
+        return;
+    }
+    throw new Error('Cannot merge array with object');
+};
+export function saveJSON(props) {
+    return props.async === true ? saveJSONAsync(props) : saveJSONSync(props);
+}
+export function readJSON(props) {
+    return props.async === true ? readJSONAsync(props) : readJSONSync(props);
+}
+export function addToJSON(props) {
+    return props.async === true ? addToJSONAsync(props) : addToJSONSync(props);
+}

package/dist/{index.d.ts → common.d.ts}

@@ -11,6 +11,8 @@ export interface ReadJSONProps {
     parseJSON?: boolean;
     createIfNotFound?: boolean | SerializableObject | SerializableArray;
     silent?: boolean;
+    throwError?: boolean;
+    async?: boolean;
 }
 export interface SaveJSONProps {
     filePath: string;
@@ -19,6 +21,7 @@ export interface SaveJSONProps {
     logSaving?: boolean;
     replaceNonSerializable?: boolean;
     silent?: boolean;
+    async?: boolean;
 }
 export interface addToJSONProps {
     filePath: string;
@@ -27,7 +30,28 @@ export interface addToJSONProps {
     logSaving?: boolean;
     replaceNonSerializable?: boolean;
     silent?: boolean;
+    throwError?: boolean;
+    async?: boolean;
 }
+export type ReadJSONSyncProps = ReadJSONProps & {
+    async?: false;
+};
+export type ReadJSONAsyncProps = ReadJSONProps & {
+    async: true;
+};
+export type SaveJSONSyncProps = SaveJSONProps & {
+    async?: false;
+};
+export type SaveJSONAsyncProps = SaveJSONProps & {
+    async: true;
+};
+export type AddToJSONSyncProps = addToJSONProps & {
+    async?: false;
+};
+export type AddToJSONAsyncProps = addToJSONProps & {
+    async: true;
+};
+export type ReadJSONResult<T = any> = T | string | null;
 export type ErrorWithCode = Error & {
     code: string;
 };
@@ -44,12 +68,12 @@ export interface SerializationIssue {
 export declare const isErrorWithCode: (error: unknown) => error is ErrorWithCode;
 export declare const isErrorWithMessage: (error: unknown) => error is ErrorWithMessage;
 export declare const isSyntaxError: (error: unknown) => error is SyntaxError;
+export declare const getDate: () => string;
 export declare const isObjectLike: (value: unknown) => value is object;
 export declare const isPlainMergeableObject: (value: unknown) => value is Record<string, unknown>;
+export declare const getIssueMessage: (issue: SerializationIssue) => string;
 export declare const getSerializationIssues: (value: unknown, path?: string, ancestors?: WeakMap<object, string>, issues?: SerializationIssue[]) => SerializationIssue[];
 export declare const isSerializable: (value: unknown) => value is Serializable;
 export declare const sanitizeNonSerializable: (value: unknown, path?: string, ancestors?: WeakMap<object, string>) => Serializable;
-export declare const saveJSON: (saveInput: SaveJSONProps) => void;
-export declare const readJSON: (props: ReadJSONProps) => any;
-export declare const addToJSON: (saveInput: addToJSONProps) => void;
+export declare const logSerializationIssues: (issues: SerializationIssue[]) => void;
 export {};

package/dist/{index.js → common.js}

@@ -1,4 +1,3 @@
-import { readFileSync, writeFileSync } from 'fs';
 export const isErrorWithCode = (error) => {
     return error instanceof Error && 'code' in error;
 };
@@ -8,7 +7,7 @@ export const isErrorWithMessage = (error) => {
 export const isSyntaxError = (error) => {
     return error instanceof SyntaxError;
 };
-const getDate = () => {
+export const getDate = () => {
     const castedDate = new Date();
     return castedDate.toLocaleTimeString('ru-RU', { hour: '2-digit', minute: '2-digit' });
 };
@@ -26,7 +25,7 @@ const pathJoin = (basePath, key) => {
         ? `${basePath}.${key}`
         : `${basePath}[${JSON.stringify(key)}]`;
 };
-const getIssueMessage = (issue) => {
+export const getIssueMessage = (issue) => {
     if (issue.kind === 'circular') {
         return `Field "${issue.path}" contains circular reference${issue.circularTo ? ` to "${issue.circularTo}"` : ''}`;
     }
@@ -144,7 +143,10 @@ const typeFlagFromValue = (value) => {
     return String(t);
 };
 export const sanitizeNonSerializable = (value, path = '$', ancestors = new WeakMap()) => {
-    if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+    if (value === null) {
+        return null;
+    }
+    if (typeof value === 'string' || typeof value === 'boolean') {
         return value;
     }
     if (typeof value === 'number') {
@@ -166,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)) {
@@ -176,125 +181,8 @@ export const sanitizeNonSerializable = (value, path = '$', ancestors = new WeakM
     }
     return typeFlagFromValue(value);
 };
-const logSerializationIssues = (issues) => {
+export const logSerializationIssues = (issues) => {
     for (const issue of issues) {
         console.info(`[${getDate()}] Boma serialization info: ${getIssueMessage(issue)}`);
     }
 };
-export const saveJSON = (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) {
-            const firstIssue = issues[0];
-            const errorMessage = `[${getDate()}] Boma got non JSON-serializable object at saveJSON! ${getIssueMessage(firstIssue)}`;
-            console.error(errorMessage);
-            throw new Error(errorMessage);
-        }
-    }
-    const valueToSave = replaceNonSerializable && issues.length > 0
-        ? sanitizeNonSerializable(objToSave)
-        : objToSave;
-    try {
-        const json = format ? JSON.stringify(valueToSave, null, 2) : JSON.stringify(valueToSave);
-        writeFileSync(filePath, json, 'utf8');
-        !silent && logSaving && console.log(`[${getDate()}] Write file ${filePath} successfully`);
-    }
-    catch (error) {
-        if (isErrorWithCode(error)) {
-            console.error(`[${getDate()}] Boma got filesystem error for ${filePath}:`, error);
-        }
-        throw error;
-    }
-};
-export const readJSON = (props) => {
-    const { filePath, createIfNotFound = false, parseJSON = true, silent = true } = props;
-    try {
-        const savedfile = readFileSync(filePath, 'utf8');
-        if (parseJSON) {
-            return savedfile.trim() === '' ? null : JSON.parse(savedfile);
-        }
-        return savedfile;
-    }
-    catch (err) {
-        if (isErrorWithCode(err)) {
-            switch (err.code) {
-                case 'ENOENT':
-                    if (createIfNotFound) {
-                        !silent && console.log('Try to create: ', filePath);
-                        try {
-                            const initialContent = typeof createIfNotFound === 'boolean' ? '{}' : JSON.stringify(createIfNotFound);
-                            writeFileSync(filePath, initialContent, 'utf8');
-                        }
-                        catch (writeErr) {
-                            console.error(`Error creating file ${filePath}: `, writeErr, '\n');
-                        }
-                        return typeof createIfNotFound === 'boolean' ? {} : createIfNotFound;
-                    }
-                    console.info("Boma can't find file: ", filePath);
-                    return parseJSON ? {} : null;
-                case 'EACCES':
-                    console.error(`Access denied for ${filePath}`);
-                    return null;
-                default:
-                    console.error(`Some filesystem error when try readJSON: ${filePath}`);
-                    return null;
-            }
-        }
-        if (isSyntaxError(err)) {
-            console.error('File ', filePath, ' has incorrect JSON syntax', '\n');
-            return null;
-        }
-        console.error('Function readJSON error:', err, '\n');
-        return null;
-    }
-};
-export const addToJSON = (saveInput) => {
-    const { filePath, dataToAdd, format = false, logSaving = false, replaceNonSerializable = false, silent = true, } = saveInput;
-    const oldJSON = readJSON({ filePath, createIfNotFound: true, silent });
-    if (oldJSON === null || typeof oldJSON !== 'object') {
-        return saveJSON({
-            filePath,
-            objToSave: dataToAdd,
-            format,
-            logSaving,
-            replaceNonSerializable,
-            silent
-        });
-    }
-    if (Array.isArray(oldJSON) && Array.isArray(dataToAdd)) {
-        saveJSON({
-            filePath,
-            objToSave: [...oldJSON, ...dataToAdd],
-            format,
-            logSaving,
-            replaceNonSerializable,
-            silent
-        });
-        return;
-    }
-    if (isPlainMergeableObject(oldJSON) && isPlainMergeableObject(dataToAdd)) {
-        saveJSON({
-            filePath,
-            objToSave: { ...oldJSON, ...dataToAdd },
-            format,
-            logSaving,
-            replaceNonSerializable,
-            silent
-        });
-        return;
-    }
-    if (Array.isArray(dataToAdd) && isPlainMergeableObject(oldJSON) && Object.keys(oldJSON).length === 0) {
-        saveJSON({
-            filePath,
-            objToSave: [...dataToAdd],
-            format,
-            logSaving,
-            replaceNonSerializable,
-            silent
-        });
-        return;
-    }
-    throw new Error('Cannot merge array with object');
-};

package/package.json

@@ -1,9 +1,16 @@
 {
   "name": "boma",
-  "version": "2.0.6",
-  "description": "Primitive JSON helper",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "version": "2.1.1",
+  "description": "Simple JSON helper",
+  "main": "./dist/boma.js",
+  "types": "./dist/boma.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/boma.d.ts",
+      "import": "./dist/boma.js",
+      "default": "./dist/boma.js"
+    }
+  },
   "type": "module",
   "scripts": {
     "build": "tsc",
@@ -13,13 +20,7 @@
     "type": "git",
     "url": "git+https://github.com/Psychosynthesis/Boma.git"
   },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    }
-  },
+  "files": [ "dist", "readme.md", "LICENSE" ],
   "author": "Nick G.",
   "license": "MIT",
   "bugs": {

package/readme.md

@@ -1,88 +1,469 @@
 # Boma JSON helper
- Super-simple helper for working with JSON
 
- Work only in synchronous mode for now.
+[![npm version](https://img.shields.io/npm/v/boma?color=%20027dec)](https://www.npmjs.org/package/boma)
 
-# Usage
+Super-simple helper for reading, saving and updating JSON files.
 
-```JS
+Works in synchronous mode by default.
+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
+npm install boma
+```
+
+# Import
+
+```typescript
+import { readJSON, saveJSON, addToJSON } from 'boma';
+```
+
+# Synchronous usage
+
+Without the `async` option, all functions work synchronously.
+
+```typescript
 const logs = readJSON({
-  filePath: '/support.log',
+  filePath: '/support.json',
   createIfNotFound: {},
   parseJSON: true,
-  silent: true, // Do not log warnings (only file not found will be logged)
+  silent: true, // Do not log warnings
 });
+
 /*
 logs = {
-  any: {}, //
+  any: {},
   key: {}
 }
 */
+```
 
+```typescript
 saveJSON({
   filePath: '/test.json',
-  objToSave: { any: {}, key: {} },
+  objToSave: {
+    any: {},
+    key: {},
+  },
   format: true,
   logSaving: false,
-  silent: true, // Do not log warnings
-}); // Format for save line break's
-/* Will save:
+  silent: true,
+});
+
+/*
+Will save:
+
 {
-  "any": {}, // saved line break's
+  "any": {},
   "key": {}
 }
 */
+```
 
+```typescript
 addToJSON({
-  filePath: '/support.log',
-  dataToAdd: { 6sdf89g7dghg: { any: "data", someFunc: () => {} }},
+  filePath: '/support.json',
+  dataToAdd: {
+    '6sdf89g7dghg': {
+      any: 'data',
+      someFunc: () => {},
+    },
+  },
   format: false,
   logSaving: false,
-  replaceNonSerializable: true
+  replaceNonSerializable: true,
 });
-/* Will save:
-"{ "6sdf89g7dghg": { "any": "data", "someFunc": "function" } }"
+
+/*
+Will save:
+
+{
+  "6sdf89g7dghg": {
+    "any": "data",
+    "someFunc": "function"
+  }
+}
 */
 ```
 
-## Types
+# Asynchronous usage
+
+Pass `async: true` to any main function.
+
+In this mode:
+
+* `readJSON` returns a `Promise` with the read value;
+* `saveJSON` returns `Promise<void>`;
+* `addToJSON` returns `Promise<void>`.
+
+```typescript
+const logs = await readJSON({
+  filePath: '/support.json',
+  createIfNotFound: {},
+  parseJSON: true,
+  silent: true,
+  async: true,
+});
+```
+
+```typescript
+await saveJSON({
+  filePath: '/test.json',
+  objToSave: {
+    any: {},
+    key: {},
+  },
+  format: true,
+  logSaving: false,
+  silent: true,
+  async: true,
+});
+```
+
+```typescript
+await addToJSON({
+  filePath: '/support.json',
+  dataToAdd: {
+    newKey: {
+      any: 'data',
+    },
+  },
+  format: true,
+  silent: true,
+  async: true,
+});
+```
+
+The same functions are used in both modes. Separate async imports are not required.
+
+# Reading JSON
+
+```typescript
+const result = readJSON({
+  filePath: '/test.json',
+});
+```
+
+Default options:
+
+```typescript
+{
+  parseJSON: true,
+  createIfNotFound: false,
+  silent: true,
+  async: false
+}
+```
+
+When `parseJSON` is `true`, file content is parsed using `JSON.parse`.
+
+When `parseJSON` is `false`, raw file content is returned as a string.
+
+```typescript
+const rawContent = readJSON({
+  filePath: '/test.json',
+  parseJSON: false,
+});
+```
+
+When `createIfNotFound` is `true`, a missing file is created with an empty object:
+
+```typescript
+const result = readJSON({
+  filePath: '/test.json',
+  createIfNotFound: true,
+});
+```
+
+You can also provide the initial object or array:
+
+```typescript
+const result = readJSON({
+  filePath: '/test.json',
+  createIfNotFound: {
+    created: true,
+  },
+});
+```
+
+# Saving JSON
+
+```typescript
+saveJSON({
+  filePath: '/test.json',
+  objToSave: {
+    any: 'data',
+  },
+});
+```
+
+Use `format: true` to save formatted JSON with indentation and line breaks:
+
+```typescript
+saveJSON({
+  filePath: '/test.json',
+  objToSave: {
+    any: 'data',
+  },
+  format: true,
+});
+```
+
+Use `logSaving: true` to log successful file saving when `silent` is `false`.
+
+# Non-serializable values
+
+JSON does not support values such as:
+
+* `undefined`;
+* functions;
+* symbols;
+* `bigint`;
+* `NaN` and `Infinity`;
+* circular references.
+
+Use `replaceNonSerializable: true` to replace such values with string type flags:
+
+```typescript
+saveJSON({
+  filePath: '/test.json',
+  objToSave: {
+    callback: () => {},
+    missing: undefined,
+    largeNumber: BigInt(10),
+    invalidNumber: NaN,
+  },
+  replaceNonSerializable: true,
+  format: true,
+});
+```
+
+Will save:
+
+```json
+{
+  "callback": "function",
+  "missing": "undefined",
+  "largeNumber": "bigint",
+  "invalidNumber": "non-finite-number"
+}
+```
+
+Circular references are replaced with `"circular"`.
+
+# Adding data to JSON
+
+`addToJSON` reads the existing file, merges the new data and saves the result.
+
+Objects are shallow merged:
+
+```typescript
+// Existing file:
+{
+  "first": 1,
+  "second": 2
+}
+```
+
+```typescript
+addToJSON({
+  filePath: '/test.json',
+  dataToAdd: {
+    second: 20,
+    third: 3,
+  },
+});
+```
+
+Result:
+
+```json
+{
+  "first": 1,
+  "second": 20,
+  "third": 3
+}
+```
+
+Existing object keys are overwritten by values from `dataToAdd`.
+
+Arrays are concatenated:
+
+```typescript
+// Existing file:
+[1, 2]
+```
+
+```typescript
+addToJSON({
+  filePath: '/test.json',
+  dataToAdd: [3, 4],
+});
+```
+
+Result:
+
+```json
+[1, 2, 3, 4]
+```
+
+An object cannot be merged with an array. In this case, `addToJSON` throws:
+
+```text
+Cannot merge array with object
+```
+
+A missing file is created automatically.
+
+# Typed reading
+
+A result type can be passed to `readJSON`:
+
+```typescript
+interface Config {
+  port: number;
+  production: boolean;
+}
+
+const config = readJSON<Config>({
+  filePath: '/config.json',
+});
+```
+
+Async mode uses the same generic:
+
+```typescript
+const config = await readJSON<Config>({
+  filePath: '/config.json',
+  async: true,
+});
+```
+
+Because `parseJSON: false` returns a string and reading errors can return `null`, the complete result type also includes `string | null`.
+
+# Types
+
 Main types:
 
 ```typescript
 export type SerializablePrimitive = string | number | boolean | null;
 export type SerializableArray = Serializable[];
-export type SerializableObject = { [key: string]: Serializable };
-export type Serializable = SerializablePrimitive | SerializableArray | SerializableObject;
+export type SerializableObject = {
+  [key: string]: Serializable;
+};
+
+export type Serializable =
+  | SerializablePrimitive
+  | SerializableArray
+  | SerializableObject;
 
 export interface ReadJSONProps {
   filePath: string;
   parseJSON?: boolean;
-  createIfNotFound?: boolean | SerializableObject | SerializableArray; // Файл с чем создать, если не создан
+  createIfNotFound?:
+    | boolean
+    | SerializableObject
+    | SerializableArray;
+  silent?: boolean;
+  async?: boolean;
 }
 
 export interface SaveJSONProps {
   filePath: string;
-  objToSave: Serializable;
-  format?: boolean
+  objToSave: unknown;
+  format?: boolean;
   logSaving?: boolean;
-  replaceNonSerializable?: boolean; // Заменять несереализуемые значения их типом
-  silent?: boolean; // Не выводим предупреждения
+  replaceNonSerializable?: boolean;
+  silent?: boolean;
+  async?: boolean;
 }
 
 export interface addToJSONProps {
   filePath: string;
-  dataToAdd: SerializableObject | SerializableArray;
-  format?: boolean
+  dataToAdd:
+    | Record<string, unknown>
+    | unknown[];
+  format?: boolean;
   logSaving?: boolean;
-  silent?: boolean; // Не выводим предупреждения
+  replaceNonSerializable?: boolean;
+  silent?: boolean;
+  async?: boolean;
 }
+```
+
+Types used for synchronous and asynchronous overloads are also exported:
+
+```typescript
+export type ReadJSONSyncProps =
+  ReadJSONProps & { async?: false };
+
+export type ReadJSONAsyncProps =
+  ReadJSONProps & { async: true };
+
+export type SaveJSONSyncProps =
+  SaveJSONProps & { async?: false };
+
+export type SaveJSONAsyncProps =
+  SaveJSONProps & { async: true };
+
+export type AddToJSONSyncProps =
+  addToJSONProps & { async?: false };
+
+export type AddToJSONAsyncProps =
+  addToJSONProps & { async: true };
+
+export type ReadJSONResult<T = any> =
+  T | string | null;
+```
 
-// We also export some helpers:
-export const isSerializable = (value: unknown) => boolean;
-export const isObjectLike = (value: unknown) => boolean;
-export const isPlainMergeableObject = (value: unknown) => boolean;
+# Helpers
 
-export const isErrorWithCode = (error: unknown) => boolean;
-export const isErrorWithMessage = (error: unknown) => boolean;
-export const isSyntaxError = (error: unknown) => boolean;
+The package also exports serialization and type-checking helpers:
+
+```typescript
+isSerializable(value);
+sanitizeNonSerializable(value);
+getSerializationIssues(value);
+
+isObjectLike(value);
+isPlainMergeableObject(value);
+
+isErrorWithCode(error);
+isErrorWithMessage(error);
+isSyntaxError(error);
+```
+
+`getSerializationIssues` returns all detected serialization problems with their object paths:
+
+```typescript
+const issues = getSerializationIssues({
+  user: {
+    callback: () => {},
+  },
+});
+
+/*
+[
+  {
+    path: '[OBJECT].user.callback',
+    kind: 'function',
+    message:
+      'Field "[OBJECT].user.callback" has non-serializable value of type "function"'
+  }
+]
+*/
 ```