@cntwg/file-helper 0.0.1 → 0.0.2-b

package/index.d.ts

@@ -0,0 +1,35 @@
+import {
+  checkFsError,
+  loadFromFile, loadFromFileSync,
+  saveToFile, saveToFileSync,
+} from './lib/base-func';
+
+import type {
+  fsoDescr, VCOR_evalerrfs,
+} from './lib/base-func';
+
+import {
+  loadJSONFromFile, loadJSONFromFileSync,
+  saveJSONToFile, saveJSONToFileSync,
+} from './lib/json-func';
+
+import {
+  RVAL_loadjsonff,
+} from './lib/json-func';
+
+export {
+  checkFsError,
+  loadFromFile,
+  loadFromFileSync,
+  saveToFile,
+  saveToFileSync,
+  loadJSONFromFile,
+  loadJSONFromFileSync,
+  saveJSONToFile,
+  saveJSONToFileSync
+};
+
+export type {
+  fsoDescr, VCOR_evalerrfs,
+  RVAL_loadjsonff,
+};

package/lib/base-func.d.ts

@@ -0,0 +1,76 @@
+export namespace modHelper {
+  export { isArray };
+  export { isPlainObject };
+}
+/**
+ * An FS-ops result descriptor.
+ */
+export type fsoDescr = {
+  /**
+   * - flag
+   */
+  isERR: boolean;
+  /**
+   * - error code
+   */
+  errCode?: number;
+  /**
+   * - event ID
+   */
+  errEvent: string;
+  /**
+   * - event message
+   */
+  errMsg?: string;
+  /**
+   * - path to file
+   */
+  source?: string;
+  /**
+   * - file content
+   */
+  content?: any;
+};
+/**
+ * A result of an error check ops.
+ */
+export type VCOR_evalerrfs = {
+  /**
+   * - ops flag
+   */
+  isSucceed: boolean;
+  /**
+   * - description
+   */
+  descr: fsoDescr;
+};
+/**
+ * a ref to the `Array.isArray()` method
+ */
+declare const isArray: (arg: any) => arg is any[];
+/**
+ * Checks if the given value is a plain object
+ */
+declare function isPlainObject(value?: any): boolean;
+/**
+ * Checks an error code of a fs ops and sets descr info if succeed
+ */
+export function checkFsError(descr: fsoDescr, err: Error): VCOR_evalerrfs;
+/**
+ * Loads file by a given path
+ */
+export function loadFromFile(src: string): Promise<fsoDescr>;
+/**
+ * Loads file by a given path
+ */
+export function loadFromFileSync(src: string): fsoDescr;
+/**
+ * Saves a content to a file
+ */
+export function saveToFile(src: string, content?: string, opt?: any): Promise<fsoDescr>;
+/**
+ * Saves a content to a file
+ */
+export function saveToFileSync(src: string, content?: string, opt?: any): fsoDescr;
+
+export {};

package/lib/base-func.js

@@ -1,11 +1,11 @@
-// [v0.1.030-20250408]
+// [v0.1.032-20251126]
 
 // === module init block ===
 
 const fs = require('fs');
 const fse = fs.promises;
 
-// === module extra block (helper functions) ===
+// === module inner block ===
 
 /**
  * a ref to the `Array.isArray()` method
@@ -15,16 +15,21 @@ const fse = fs.promises;
 const isArray = Array.isArray;
 
 /**
+ * Checks if the given value is a plain object
  * @function isPlainObject
  * @param {any} value - some value to verify
  * @returns {boolean}
- * @description Checks if the given value is a plain object
  * @todo consider if an instance of 'Set' or 'Map' can be treated as plain object
  */
 function isPlainObject(value = null) {
   return value !== null && typeof value === 'object' && !isArray(value);
 };
 
+module.exports.modHelper = {
+  isArray,
+  isPlainObject,
+};
+
 // === module main block ===
 
 /***
@@ -36,6 +41,7 @@ function isPlainObject(value = null) {
  */
 
 /**
+ * An FS-ops result descriptor.
  * @typedef {Object} fsoDescr
  * @property {boolean} isERR - flag
  * @property {number} [errCode] - error code
@@ -43,22 +49,21 @@ function isPlainObject(value = null) {
  * @property {string} [errMsg] - event message
  * @property {string} [source] - path to file
  * @property {any} [content] - file content
- * @description A fs ops description.
  */
 
 /**
+ * A result of an error check ops.
  * @typedef {Object} VCOR_evalerrfs
  * @property {boolean} isSucceed - ops flag
  * @property {fsoDescr} descr - description
- * @description A result of an error check ops.
  */
 
 /**
+ * Checks an error code of a fs ops and sets descr info if succeed
  * @function checkFsError
  * @param {fsoDescr} descr - event descriptor
  * @param {Error} err - error event
  * @returns {VCOR_evalerrfs}
- * @description Checks an error code of a fs ops and sets descr info if succeed
  */
 function checkFsError(descr, err) {
   let isSucceed = false;
@@ -83,10 +88,10 @@ function checkFsError(descr, err) {
 };
 
 /**
+ * Loads file by a given path
  * @function loadFromFileSync
  * @param {string} src - a path to some file
  * @returns {fsoDescr}
- * @description Loads file by a given path
  */
 function loadFromFileSync(src) {
   /** @type {fsoDescr} */
@@ -124,11 +129,11 @@ function loadFromFileSync(src) {
 };
 
 /**
+ * Loads file by a given path
  * @function loadFromFile
  * @param {string} src - a path to some file
  * @returns {Promise<fsoDescr, Error>}
  * @async
- * @description Loads file by a given path
  */
 function loadFromFile(src) {
   /**/// main part that return promise as a result
@@ -172,12 +177,12 @@ function loadFromFile(src) {
 };
 
 /**
+ * Saves a content to a file
  * @function saveToFileSync
  * @param {string} src - a path to some file
  * @param {string} content - some file content
  * @param {any} [opt] - <reserved>
  * @returns {fsoDescr}
- * @description Saves a content to a file
  */
 function saveToFileSync(src, content = '', opt) {
   /** @type {fsoDescr} */
@@ -221,13 +226,13 @@ function saveToFileSync(src, content = '', opt) {
 };
 
 /**
+ * Saves a content to a file
  * @function saveToFile
  * @param {string} src - a path to some file
  * @param {string} content - some file content
  * @param {any} [opt] - <reserved>
  * @returns {Promise<fsoDescr, Error>}
  * @async
- * @description Saves a content to a file
  */
 function saveToFile(src, content = '', opt) {
   /**/// main part that return promise as a result

package/lib/json-func.d.ts

@@ -0,0 +1,30 @@
+import type { fsoDescr } from "./base-func";
+/**
+ * A result of `loadJSONFromFileSync`
+ */
+export type RVAL_loadjsonff = {
+  /**
+   * - ops description
+   */
+  descr: fsoDescr;
+  /**
+   * - loaded content
+   */
+  obj: any;
+};
+/**
+ * Loads a JSON-object from a file
+ */
+export function loadJSONFromFile(src: string, opt?: any): Promise<RVAL_loadjsonff>;
+/**
+ * Loads a JSON-object from a file
+ */
+export function loadJSONFromFileSync(src: string, opt?: any): RVAL_loadjsonff;
+/**
+ * Saves a JSON-object to a file
+ */
+export function saveJSONToFile(src: string, obj: object, opt?: any): Promise<fsoDescr>;
+/**
+ * Saves a JSON-object to a file
+ */
+export function saveJSONToFileSync(src: string, obj: object, opt?: any): fsoDescr;

package/lib/json-func.js

@@ -1,4 +1,4 @@
-// [v0.1.030-20250408]
+// [v0.1.032-20251126]
 
 // === module init block ===
 
@@ -7,25 +7,7 @@ const {
   saveToFile, saveToFileSync,
 } = require('./base-func');
 
-// === module extra block (helper functions) ===
-
-/**
- * a ref to the `Array.isArray()` method
- * @param {any} value - some value to verify
- * @returns {boolean}
- */
-const isArray = Array.isArray;
-
-/**
- * @function isPlainObject
- * @param {any} value - some value to verify
- * @returns {boolean}
- * @description Checks if the given value is a plain object
- * @todo consider if an instance of 'Set' or 'Map' can be treated as plain object
- */
-function isPlainObject(value = null) {
-  return value !== null && typeof value === 'object' && !isArray(value);
-};
+// === module inner block ===
 
 // === module main block ===
 
@@ -38,18 +20,18 @@ function isPlainObject(value = null) {
  */
 
 /**
+ * A result of `loadJSONFromFileSync`
  * @typedef {Object} RVAL_loadjsonff
  * @property {fsoDescr} descr - ops description
  * @property {any} obj - loaded content
- * @description A result of `loadJSONFromFileSync`
  */
 
 /**
+ * Loads a JSON-object from a file
  * @function loadJSONFromFileSync
  * @param {string} src - a path to some file
  * @param {any} [opt] - <reserved>
  * @returns {RVAL_loadjsonff}
- * @description Loads a JSON-object from a file
  */
 function loadJSONFromFileSync(src, opt) {
   const data = loadFromFileSync(src);
@@ -77,12 +59,12 @@ function loadJSONFromFileSync(src, opt) {
 };
 
 /**
+ * Loads a JSON-object from a file
  * @function loadJSONFromFile
  * @param {string} src - a path to some file
  * @param {any} [opt] - <reserved>
  * @returns {Promise<RVAL_loadjsonff, Error>}
  * @async
- * @description Loads a JSON-object from a file
  */
 function loadJSONFromFile(src, opt) {
   /**/// main part that return promise as a result
@@ -118,12 +100,12 @@ function loadJSONFromFile(src, opt) {
 };
 
 /**
+ * Saves a JSON-object to a file
  * @function saveJSONToFileSync
  * @param {string} src - a path to some file
  * @param {object} obj - some content
  * @param {any} [opt] - <reserved>
  * @returns {fsoDescr}
- * @description Saves a JSON-object to a file
  */
 function saveJSONToFileSync(src, obj, opt) {
   /** @type {fsoDescr} */
@@ -150,6 +132,7 @@ function saveJSONToFileSync(src, obj, opt) {
 };
 
 /**
+ * Saves a JSON-object to a file
  * @function saveJSONToFile
  * @param {string} src - a path to some file
  * @param {object} obj - some content
@@ -157,7 +140,6 @@ function saveJSONToFileSync(src, obj, opt) {
  * @returns {Promise<fsoDescr, Error>}
  * @throws {Error}
  * @async
- * @description Saves a JSON-object to a file
  */
 function saveJSONToFile(src, obj, opt) {
   /**/// main part that return promise as a result

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/file-helper",
-  "version": "0.0.1",
+  "version": "0.0.2-b",
   "description": "A small helper library to load/save file content",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -9,25 +9,31 @@
     "url": "git+https://gitlab.com/cntwg/file-helper.git"
   },
   "main": "./index.js",
+  "types": "./index.d.ts",
   "files": [
     "doc/file-helper.md",
     "lib/base-func.js",
     "lib/json-func.js",
+    "lib/*.d.ts",
     "index.js",
+    "index.d.ts",
     "CHANGELOG.md"
   ],
   "scripts": {
     "test": "jest",
     "build-doc-md": "jsdoc2md",
-    "build-doc-html": "jsdoc"
+    "build-doc-html": "jsdoc",
+    "gen-dts": "npx -p typescript tsc"
   },
   "imports": {
     "#lib/*": "./lib/*",
     "#test-dir/*": "./__test__/*"
   },
   "devDependencies": {
-    "jest": "^29.7.0",
-    "jsdoc-to-markdown": "^9.1.1",
-    "minimist": "^1.2.8"
+    "@ygracs/test-helper": "^0.0.1-b",
+    "jest": "^30.2.0",
+    "jsdoc-to-markdown": "^9.1.3",
+    "minimist": "^1.2.8",
+    "typescript": "~5.9.3"
   }
 }