boma 2.0.3 → 2.0.5

package/dist/index.d.ts

@@ -4,22 +4,29 @@ export type SerializableObject = {
     [key: string]: Serializable;
 };
 export type Serializable = SerializablePrimitive | SerializableArray | SerializableObject;
+type JSONLikeObject = Record<string, unknown>;
+type JSONLikeArray = unknown[];
 export interface ReadJSONProps {
     filePath: string;
     parseJSON?: boolean;
     createIfNotFound?: boolean | SerializableObject | SerializableArray;
+    silent?: boolean;
 }
 export interface SaveJSONProps {
     filePath: string;
-    objToSave: Serializable;
+    objToSave: unknown;
     format?: boolean;
     logSaving?: boolean;
+    replaceNonSerializable?: boolean;
+    silent?: boolean;
 }
 export interface addToJSONProps {
     filePath: string;
-    dataToAdd: SerializableObject | SerializableArray;
+    dataToAdd: JSONLikeObject | JSONLikeArray;
     format?: boolean;
     logSaving?: boolean;
+    replaceNonSerializable?: boolean;
+    silent?: boolean;
 }
 export type ErrorWithCode = Error & {
     code: string;
@@ -27,10 +34,22 @@ export type ErrorWithCode = Error & {
 export type ErrorWithMessage = Error & {
     message: any;
 };
+export type SerializationIssueKind = 'undefined' | 'function' | 'symbol' | 'bigint' | 'non-finite-number' | 'circular';
+export interface SerializationIssue {
+    path: string;
+    kind: SerializationIssueKind;
+    message: string;
+    circularTo?: string;
+}
 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 isSerializable: (value: unknown, seen?: WeakSet<object>) => value is Serializable;
+export declare const isObjectLike: (value: unknown) => value is object;
+export declare const isPlainMergeableObject: (value: unknown) => value is Record<string, unknown>;
+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 {};

package/dist/index.js

@@ -12,57 +12,211 @@ const getDate = () => {
     const castedDate = new Date();
     return castedDate.toLocaleTimeString('ru-RU', { hour: '2-digit', minute: '2-digit' });
 };
-export const isSerializable = (value, seen = new WeakSet()) => {
-    if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
-        return true;
+export const isObjectLike = (value) => {
+    return typeof value === 'object' && value !== null;
+};
+export const isPlainMergeableObject = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+const pathJoin = (basePath, key) => {
+    if (typeof key === 'number') {
+        return `${basePath}[${key}]`;
+    }
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+        ? `${basePath}.${key}`
+        : `${basePath}[${JSON.stringify(key)}]`;
+};
+const getIssueMessage = (issue) => {
+    if (issue.kind === 'circular') {
+        return `Field "${issue.path}" contains circular reference${issue.circularTo ? ` to "${issue.circularTo}"` : ''}`;
+    }
+    if (issue.kind === 'non-finite-number') {
+        return `Field "${issue.path}" contains non-finite number (NaN / Infinity)`;
+    }
+    return `Field "${issue.path}" has non-serializable value of type "${issue.kind}"`;
+};
+export const getSerializationIssues = (value, path = '[OBJECT]', ancestors = new WeakMap(), issues = []) => {
+    if (value === null) {
+        return issues;
+    }
+    const valueType = typeof value;
+    if (valueType === 'string' || valueType === 'boolean') {
+        return issues;
+    }
+    if (valueType === 'number') {
+        if (!Number.isFinite(value)) {
+            issues.push({
+                path,
+                kind: 'non-finite-number',
+                message: `Field "${path}" contains non-finite number (NaN / Infinity)`,
+            });
+        }
+        return issues;
+    }
+    if (valueType === 'undefined') {
+        issues.push({
+            path,
+            kind: 'undefined',
+            message: `Field "${path}" has non-serializable value of type "undefined"`,
+        });
+        return issues;
+    }
+    if (valueType === 'function') {
+        issues.push({
+            path,
+            kind: 'function',
+            message: `Field "${path}" has non-serializable value of type "function"`,
+        });
+        return issues;
+    }
+    if (valueType === 'symbol') {
+        issues.push({
+            path,
+            kind: 'symbol',
+            message: `Field "${path}" has non-serializable value of type "symbol"`,
+        });
+        return issues;
+    }
+    if (valueType === 'bigint') {
+        issues.push({
+            path,
+            kind: 'bigint',
+            message: `Field "${path}" has non-serializable value of type "bigint"`,
+        });
+        return issues;
     }
     if (Array.isArray(value)) {
-        for (const el of value) {
-            if (!isSerializable(el, seen)) {
-                return false;
-            }
+        if (ancestors.has(value)) {
+            const circularTo = ancestors.get(value);
+            issues.push({
+                path,
+                kind: 'circular',
+                circularTo,
+                message: `Field "${path}" contains circular reference${circularTo ? ` to "${circularTo}"` : ''}`,
+            });
+            return issues;
         }
-        return true;
+        ancestors.set(value, path);
+        for (let i = 0; i < value.length; i++) {
+            getSerializationIssues(value[i], pathJoin(path, i), ancestors, issues);
+        }
+        ancestors.delete(value);
+        return issues;
     }
-    if (typeof value === "object") {
-        if (seen.has(value)) {
-            return false;
+    if (isObjectLike(value)) {
+        if (ancestors.has(value)) {
+            const circularTo = ancestors.get(value);
+            issues.push({
+                path,
+                kind: 'circular',
+                circularTo,
+                message: `Field "${path}" contains circular reference${circularTo ? ` to "${circularTo}"` : ''}`,
+            });
+            return issues;
         }
-        seen.add(value);
-        const obj = value;
-        for (const key in obj) {
-            if (!isSerializable(obj[key], seen)) {
-                return false;
-            }
+        ancestors.set(value, path);
+        for (const key of Object.keys(value)) {
+            getSerializationIssues(value[key], pathJoin(path, key), ancestors, issues);
         }
-        return true;
+        ancestors.delete(value);
+        return issues;
+    }
+    return issues;
+};
+export const isSerializable = (value) => {
+    return getSerializationIssues(value).length === 0;
+};
+const typeFlagFromValue = (value) => {
+    if (value === null)
+        return null;
+    if (Array.isArray(value))
+        return 'array';
+    const t = typeof value;
+    if (String(t) === 'number' && !Number.isFinite(value)) {
+        return 'non-finite-number';
+    }
+    else if (['undefined', 'function', 'symbol', 'bigint'].includes(String(t))) {
+        return String(t);
+    }
+    else if (String(t) === 'object') {
+        return 'object';
+    }
+    return String(t);
+};
+export const sanitizeNonSerializable = (value, path = '$', ancestors = new WeakMap()) => {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : 'non-finite-number';
+    }
+    if (typeof value === 'undefined' ||
+        typeof value === 'function' ||
+        typeof value === 'symbol' ||
+        typeof value === 'bigint') {
+        return typeFlagFromValue(value);
+    }
+    if (Array.isArray(value)) {
+        if (ancestors.has(value)) {
+            return 'circular';
+        }
+        ancestors.set(value, path);
+        const result = value.map((item, index) => sanitizeNonSerializable(item, pathJoin(path, index), ancestors));
+        ancestors.delete(value);
+        return result;
+    }
+    if (isObjectLike(value)) {
+        if (ancestors.has(value)) {
+            return 'circular';
+        }
+        ancestors.set(value, path);
+        const result = {};
+        for (const key of Object.keys(value)) {
+            result[key] = sanitizeNonSerializable(value[key], pathJoin(path, key), ancestors);
+        }
+        ancestors.delete(value);
+        return result;
+    }
+    return typeFlagFromValue(value);
+};
+const logSerializationIssues = (issues) => {
+    for (const issue of issues) {
+        console.info(`[${getDate()}] Boma serialization info: ${getIssueMessage(issue)}`);
     }
-    return false;
 };
 export const saveJSON = (saveInput) => {
-    const { filePath, objToSave, format = false, logSaving = false } = saveInput;
-    if (!isSerializable(objToSave)) {
-        console.error(`[${getDate()}] Boma get non JSON-serializable object at saveJSON!`);
-        throw new Error(`[${getDate()}] Boma get non JSON-serializable object at saveJSON!`);
+    const { filePath, objToSave, format = false, logSaving = false, replaceNonSerializable = false, silent = true, } = saveInput;
+    const issues = getSerializationIssues(objToSave);
+    if (issues.length > 0) {
+        logSerializationIssues(issues);
+        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);
+        }
     }
+    const valueToSave = replaceNonSerializable && issues.length > 0
+        ? sanitizeNonSerializable(objToSave)
+        : objToSave;
     try {
-        const json = format ? JSON.stringify(objToSave, null, 2) : JSON.stringify(objToSave);
+        const json = format ? JSON.stringify(valueToSave, null, 2) : JSON.stringify(valueToSave);
         writeFileSync(filePath, json, 'utf8');
-        logSaving && console.log(`[${getDate()}] Write file ${filePath} successfully`);
+        !silent && logSaving && console.log(`[${getDate()}] Write file ${filePath} successfully`);
     }
     catch (error) {
         if (isErrorWithCode(error)) {
-            console.error(`[${getDate()}] Boma get filesystem error for ${filePath}:`, error);
+            console.error(`[${getDate()}] Boma got filesystem error for ${filePath}:`, error);
         }
         throw error;
     }
 };
 export const readJSON = (props) => {
-    const { filePath, createIfNotFound = false, parseJSON = true } = 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.trim() === '' ? null : JSON.parse(savedfile);
         }
         return savedfile;
     }
@@ -71,7 +225,7 @@ export const readJSON = (props) => {
             switch (err.code) {
                 case 'ENOENT':
                     if (createIfNotFound) {
-                        console.log('Try to create: ', filePath);
+                        !silent && console.log('Try to create: ', filePath);
                         try {
                             const initialContent = typeof createIfNotFound === 'boolean' ? '{}' : JSON.stringify(createIfNotFound);
                             writeFileSync(filePath, initialContent, 'utf8');
@@ -81,7 +235,7 @@ export const readJSON = (props) => {
                         }
                         return typeof createIfNotFound === 'boolean' ? {} : createIfNotFound;
                     }
-                    console.log('File not found: ', filePath);
+                    console.info("Boma can't find file: ", filePath);
                     return parseJSON ? {} : null;
                 case 'EACCES':
                     console.error(`Access denied for ${filePath}`);
@@ -100,21 +254,50 @@ export const readJSON = (props) => {
     }
 };
 export const addToJSON = (saveInput) => {
-    const { filePath, dataToAdd, format = false, logSaving = false } = saveInput;
-    const oldJSON = readJSON({ filePath, createIfNotFound: true });
+    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, logSaving });
+        return saveJSON({
+            filePath,
+            objToSave: dataToAdd,
+            format,
+            logSaving,
+            replaceNonSerializable,
+            silent
+        });
     }
     if (Array.isArray(oldJSON) && Array.isArray(dataToAdd)) {
-        saveJSON({ filePath, objToSave: [...oldJSON, ...dataToAdd], format, logSaving });
-    }
-    else if (!Array.isArray(oldJSON) && !Array.isArray(dataToAdd)) {
-        saveJSON({ filePath, objToSave: { ...oldJSON, ...dataToAdd }, format, logSaving });
+        saveJSON({
+            filePath,
+            objToSave: [...oldJSON, ...dataToAdd],
+            format,
+            logSaving,
+            replaceNonSerializable,
+            silent
+        });
+        return;
     }
-    else if (Array.isArray(dataToAdd) && Object.keys(oldJSON).length === 0) {
-        saveJSON({ filePath, objToSave: [...dataToAdd], format, logSaving });
+    if (isPlainMergeableObject(oldJSON) && isPlainMergeableObject(dataToAdd)) {
+        saveJSON({
+            filePath,
+            objToSave: { ...oldJSON, ...dataToAdd },
+            format,
+            logSaving,
+            replaceNonSerializable,
+            silent
+        });
+        return;
     }
-    else {
-        throw new Error('Cannot merge array with object');
+    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,6 +1,6 @@
 {
   "name": "boma",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "Primitive JSON helper",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/readme.md

@@ -6,7 +6,12 @@
 # Usage
 
 ```JS
-const logs = readJSON({ filePath: '/support.log', createIfNotFound: {}, parseJSON: true });
+const logs = readJSON({
+  filePath: '/support.log',
+  createIfNotFound: {},
+  parseJSON: true,
+  silent: true, // Do not log warnings (only file not found will be logged)
+});
 /*
 logs = {
   any: {}, //
@@ -14,7 +19,13 @@ logs = {
 }
 */
 
-saveJSON({ filePath: '/test.json', objToSave: { any: {}, key: {} }, format: true, logSaving: false }); // Format for save line break's
+saveJSON({
+  filePath: '/test.json',
+  objToSave: { any: {}, key: {} },
+  format: true,
+  logSaving: false,
+  silent: true, // Do not log warnings
+}); // Format for save line break's
 /* Will save:
 {
   "any": {}, // saved line break's
@@ -22,13 +33,21 @@ saveJSON({ filePath: '/test.json', objToSave: { any: {}, key: {} }, format: true
 }
 */
 
-addToJSON({ filePath: '/support.log', dataToAdd: { 6sdf89g7dghg: { any: "data" }}, format: false, logSaving: false });
+addToJSON({
+  filePath: '/support.log',
+  dataToAdd: { 6sdf89g7dghg: { any: "data", someFunc: () => {} }},
+  format: false,
+  logSaving: false,
+  replaceNonSerializable: true
+});
 /* Will save:
-"{ "any": {}, "key": {}, "6sdf89g7dghg": { "any": "data" } }"
+"{ "6sdf89g7dghg": { "any": "data", "someFunc": "function" } }"
 */
 ```
 
 ## Types
+Main types:
+
 ```typescript
 export type SerializablePrimitive = string | number | boolean | null;
 export type SerializableArray = Serializable[];
@@ -46,6 +65,8 @@ export interface SaveJSONProps {
   objToSave: Serializable;
   format?: boolean
   logSaving?: boolean;
+  replaceNonSerializable?: boolean; // Заменять несереализуемые значения их типом
+  silent?: boolean; // Не выводим предупреждения
 }
 
 export interface addToJSONProps {
@@ -53,5 +74,15 @@ export interface addToJSONProps {
   dataToAdd: SerializableObject | SerializableArray;
   format?: boolean
   logSaving?: boolean;
+  silent?: boolean; // Не выводим предупреждения
 }
+
+// We also export some helpers:
+export const isSerializable = (value: unknown) => boolean;
+export const isObjectLike = (value: unknown) => boolean;
+export const isPlainMergeableObject = (value: unknown) => boolean;
+
+export const isErrorWithCode = (error: unknown) => boolean;
+export const isErrorWithMessage = (error: unknown) => boolean;
+export const isSyntaxError = (error: unknown) => boolean;
 ```