@cntwg/file-helper 0.0.2-b → 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

@@ -2,20 +2,15 @@ import {
   checkFsError,
   loadFromFile, loadFromFileSync,
   saveToFile, saveToFileSync,
-} from './lib/base-func';
-
-import type {
-  fsoDescr, VCOR_evalerrfs,
-} from './lib/base-func';
+  type fsoDescr,
+  type VCOR_evalerrfs,
+} from "./lib/base-func";
 
 import {
   loadJSONFromFile, loadJSONFromFileSync,
   saveJSONToFile, saveJSONToFileSync,
-} from './lib/json-func';
-
-import {
-  RVAL_loadjsonff,
-} from './lib/json-func';
+  type RVAL_loadjsonff,
+} from "./lib/json-func";
 
 export {
   checkFsError,
@@ -30,6 +25,7 @@ export {
 };
 
 export type {
-  fsoDescr, VCOR_evalerrfs,
+  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

@@ -31,6 +31,7 @@ export type fsoDescr = {
    */
   content?: any;
 };
+export const fsoDescr: fsoDescr;
 /**
  * A result of an error check ops.
  */
@@ -51,13 +52,14 @@ declare const isArray: (arg: any) => arg is any[];
 /**
  * Checks if the given value is a plain object
  */
-declare function isPlainObject(value?: any): boolean;
+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: Error): VCOR_evalerrfs;
+export function checkFsError(descr: fsoDescr, err: object): VCOR_evalerrfs;
 /**
  * Loads file by a given path
+ * @throws {Error}
  */
 export function loadFromFile(src: string): Promise<fsoDescr>;
 /**
@@ -66,6 +68,7 @@ export function loadFromFile(src: string): Promise<fsoDescr>;
 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>;
 /**

package/lib/base-func.js

@@ -1,4 +1,4 @@
-// [v0.1.032-20251126]
+// [v0.1.035-20260105]
 
 // === module init block ===
 
@@ -36,10 +36,6 @@ module.exports.modHelper = {
  * (* constant definitions *)
  */
 
-/***
- * (* function definitions *)
- */
-
 /**
  * An FS-ops result descriptor.
  * @typedef {Object} fsoDescr
@@ -50,6 +46,15 @@ module.exports.modHelper = {
  * @property {string} [source] - path to file
  * @property {any} [content] - file content
  */
+/**
+ * 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.
@@ -62,12 +67,16 @@ module.exports.modHelper = {
  * 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}
  */
 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':
@@ -132,8 +141,9 @@ 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
+ * @throws {Error}
  */
 function loadFromFile(src) {
   /**/// main part that return promise as a result
@@ -231,8 +241,9 @@ function saveToFileSync(src, content = '', opt) {
  * @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
+ * @throws {Error}
  */
 function saveToFile(src, content = '', opt) {
   /**/// main part that return promise as a result

package/lib/json-func.d.ts

@@ -1,4 +1,3 @@
-import type { fsoDescr } from "./base-func";
 /**
  * A result of `loadJSONFromFileSync`
  */
@@ -14,6 +13,7 @@ export type RVAL_loadjsonff = {
 };
 /**
  * Loads a JSON-object from a file
+ * @throws {Error}
  */
 export function loadJSONFromFile(src: string, opt?: any): Promise<RVAL_loadjsonff>;
 /**
@@ -28,3 +28,5 @@ export function saveJSONToFile(src: string, obj: object, opt?: any): Promise<fso
  * 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,10 +1,12 @@
-// [v0.1.032-20251126]
+// [v0.1.034-20260105]
 
 // === module init block ===
 
 const {
   loadFromFile, loadFromFileSync,
   saveToFile, saveToFileSync,
+  // * import types definitions *
+  fsoDescr,
 } = require('./base-func');
 
 // === module inner block ===
@@ -63,8 +65,9 @@ function loadJSONFromFileSync(src, opt) {
  * @function loadJSONFromFile
  * @param {string} src - a path to some file
  * @param {any} [opt] - <reserved>
- * @returns {Promise<RVAL_loadjsonff, Error>}
+ * @returns {Promise<RVAL_loadjsonff>}
  * @async
+ * @throws {Error}
  */
 function loadJSONFromFile(src, opt) {
   /**/// main part that return promise as a result
@@ -137,9 +140,9 @@ function saveJSONToFileSync(src, obj, opt) {
  * @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
+ * @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.2-b",
+  "version": "0.0.3",
   "description": "A small helper library to load/save file content",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "#test-dir/*": "./__test__/*"
   },
   "devDependencies": {
-    "@ygracs/test-helper": "^0.0.1-b",
+    "@ygracs/test-helper": "~0.0.1-b",
     "jest": "^30.2.0",
     "jsdoc-to-markdown": "^9.1.3",
     "minimist": "^1.2.8",