@cntwg/file-helper 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+#### *v0.0.3*
+
+Pre-release version.
+
+> - update `file-helper.md`;
+> - some fixes.
+
 #### *v0.0.1*
 
 Pre-release version.

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2024-2025 Yuri Grachev
+Copyright (c) 2024-2026 Yuri Grachev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/doc/file-helper.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.0.1|
+>|***rev.*:**|0.0.2|
 >|:---|---:|
->|date:|2025-04-08|
+>|date:|2026-01-05|
 
 ## Introduction
 
@@ -49,7 +49,7 @@ Checks an error code of a fs ops and sets a descriptor if succeed.
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
 | `descr` | `fsoDescr` | --- | event descriptor |
-| `err` | `Error` | --- | error event |
+| `err` | `object` | --- | error event |
 
 The returned value is an `object` that contains a properties listed in a table below:
 
@@ -109,7 +109,7 @@ Saves a content to the file located by a given path.
 ### Module functions (*async*)
 
 <a name="loadFromFile"></a>
-#### **loadFromFile(src)** => `Promise<fsoDescr, Error>`
+#### **loadFromFile(src)** => `Promise<fsoDescr>`
 
 Loads a content from the file located by a given path.
 
@@ -117,8 +117,12 @@ Loads a content from the file located by a given path.
 |:---|---|---:|:---|
 | `src` | `string` | --- | a path to some file |
 
+##### ***exceptions***
+
+The function throws an error.
+
 <a name="saveToFile"></a>
-#### **saveToFile(src, content, [opt])** => `Promise<fsoDescr, Error>`
+#### **saveToFile(src, content, [opt])** => `Promise<fsoDescr>`
 
 Saves a content to the file located by a given path.
 
@@ -129,7 +133,7 @@ Saves a content to the file located by a given path.
 | `opt` | `any` | --- | <*reserved*> |
 
 <a name="loadJSONFromFile"></a>
-#### **loadJSONFromFile(src, [opt])** => `Promise<object, Error>`
+#### **loadJSONFromFile(src, [opt])** => `Promise<object>`
 
 Loads a content in JSON-format from the file located by a given path.
 
@@ -145,8 +149,12 @@ The returned value is an `object` containing a properties listed in a table belo
 | `descr` | `fsoDescr` | ops descriptor |
 | `obj` | `any` | loaded content |
 
+##### ***exceptions***
+
+The function throws an error.
+
 <a name="saveJSONToFile"></a>
-#### **saveJSONToFile(src, content, [opt])** => `Promise<fsoDescr, Error>`
+#### **saveJSONToFile(src, content, [opt])** => `Promise<fsoDescr>`
 
 Saves a content to the file located by a given path.
 

package/index.d.ts

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

package/index.js

@@ -1,4 +1,4 @@
-// [v0.1.001-20250408]
+// [v0.1.003-20260105]
 
 // === module init block ===
 
@@ -6,14 +6,16 @@ const {
   loadFromFile, loadFromFileSync,
   saveToFile, saveToFileSync,
   checkFsError,
-} = require('#lib/base-func.js');
+  // * import types definitions *
+  fsoDescr,
+} = require('./lib/base-func');
 
 const {
   loadJSONFromFile, loadJSONFromFileSync,
   saveJSONToFile, saveJSONToFileSync,
-} = require('#lib/json-func.js');
+} = require('./lib/json-func');
 
-// === module extra block (helper functions) ===
+// === module inner block ===
 
 // === module main block ===
 
@@ -28,3 +30,6 @@ module.exports.loadJSONFromFile = loadJSONFromFile;
 module.exports.loadJSONFromFileSync = loadJSONFromFileSync;
 module.exports.saveJSONToFile = saveJSONToFile;
 module.exports.saveJSONToFileSync = saveJSONToFileSync;
+
+// * export types definitions *
+module.exports.fsoDescr = fsoDescr;

package/lib/base-func.d.ts

@@ -0,0 +1,79 @@
+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;
+};
+export const fsoDescr: fsoDescr;
+/**
+ * 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): value is Record<string, any>;
+/**
+ * Checks an error code of a fs ops and sets descr info if succeed
+ */
+export function checkFsError(descr: fsoDescr, err: object): VCOR_evalerrfs;
+/**
+ * Loads file by a given path
+ * @throws {Error}
+ */
+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
+ * @throws {Error}
+ */
+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.035-20260105]
 
 // === 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,27 +15,29 @@ 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 ===
 
 /***
  * (* constant definitions *)
  */
 
-/***
- * (* function definitions *)
- */
-
 /**
+ * An FS-ops result descriptor.
  * @typedef {Object} fsoDescr
  * @property {boolean} isERR - flag
  * @property {number} [errCode] - error code
@@ -43,26 +45,38 @@ 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 virtual constant meant for support jsdoc notation:
+ * @type {fsoDescr}
+ */
+module.exports.fsoDescr = { isERR: false, errEvent: '' };
+
+/***
+ * (* function definitions *)
  */
 
 /**
+ * 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
+ * @param {Object} 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;
-  if (isPlainObject(err) && isPlainObject(descr)) {
+  if (
+    isPlainObject(descr)
+    && isPlainObject(err)
+    && typeof err.code === 'string'
+  ) {
     const id = err.code;
     switch (id) {
       case 'ENOENT':
@@ -83,10 +97,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 +138,12 @@ function loadFromFileSync(src) {
 };
 
 /**
+ * Loads file by a given path
  * @function loadFromFile
  * @param {string} src - a path to some file
- * @returns {Promise<fsoDescr, Error>}
+ * @returns {Promise<fsoDescr>}
  * @async
- * @description Loads file by a given path
+ * @throws {Error}
  */
 function loadFromFile(src) {
   /**/// main part that return promise as a result
@@ -172,12 +187,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 +236,14 @@ 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>}
+ * @returns {Promise<fsoDescr>}
  * @async
- * @description Saves a content to a file
+ * @throws {Error}
  */
 function saveToFile(src, content = '', opt) {
   /**/// main part that return promise as a result

package/lib/json-func.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A result of `loadJSONFromFileSync`
+ */
+export type RVAL_loadjsonff = {
+  /**
+   * - ops description
+   */
+  descr: fsoDescr;
+  /**
+   * - loaded content
+   */
+  obj: any;
+};
+/**
+ * Loads a JSON-object from a file
+ * @throws {Error}
+ */
+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;
+
+import { fsoDescr } from "./base-func";

package/lib/json-func.js

@@ -1,31 +1,15 @@
-// [v0.1.030-20250408]
+// [v0.1.034-20260105]
 
 // === module init block ===
 
 const {
   loadFromFile, loadFromFileSync,
   saveToFile, saveToFileSync,
+  // * import types definitions *
+  fsoDescr,
 } = 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 +22,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 +61,13 @@ 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>}
+ * @returns {Promise<RVAL_loadjsonff>}
  * @async
- * @description Loads a JSON-object from a file
+ * @throws {Error}
  */
 function loadJSONFromFile(src, opt) {
   /**/// main part that return promise as a result
@@ -118,12 +103,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,14 +135,14 @@ 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
  * @param {any} [opt] - <reserved>
- * @returns {Promise<fsoDescr, Error>}
- * @throws {Error}
+ * @returns {Promise<fsoDescr>}
  * @async
- * @description Saves a JSON-object to a file
+ * @throws {Error} (???)
  */
 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.3",
   "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"
   }
 }