typeshi 1.7.11 → 1.7.12

package/dist/utils/argumentValidation.d.ts

@@ -18,8 +18,12 @@ export declare function stringArgument(source: string, arg2: string | {
  * @param labeledStrings `Record<string, any>` - map name of string param to value passed in for it
  */
 export declare function multipleStringArguments(source: string, labeledStrings: Record<string, any>): void;
-export declare function multipleExistingFileArguments(source: string, extension: string | string[], labeledFilePaths: Record<string, string>): void;
-export declare function existingFileArgument(source: string, extension: string | string[], arg3: string | {
+export declare function multipleExistingFileArguments(source: string, extension: FileExtension | FileExtension[] | string | string[], labeledFilePaths: Record<string, string>): void;
+/**
+ * common file extensions handled as input/output
+ */
+type FileExtension = '.csv' | '.tsv' | '.txt' | '.json' | '.xlsx' | '.xls' | '.xml' | '.yaml' | '.yml';
+export declare function existingFileArgument(source: string, extension: FileExtension | FileExtension[] | string | string[], arg3: string | {
     [label: string]: any;
 }, value?: any): void;
 export declare function existingDirectoryArgument(source: string, arg2: string | {

package/dist/utils/io/reading.d.ts

@@ -1,9 +1,9 @@
 import { StringCaseOptions, StringPadOptions, StringStripOptions, CleanStringOptions } from "../regex";
-import { FileData } from "./types/Io";
+import { FileData, FileExtension } from "./types/Io";
 import { DelimiterCharacterEnum } from "./types";
-/** for testing if `pathString (value)` points to an existing directory */
+/** checks if `pathString (value)` points to an existing directory */
 export declare function isDirectory(value: any): value is string;
-/** for testing if `pathString (value)` points to an existing file */
+/** checks if `pathString (value)` points to an existing file */
 export declare function isFile(value: string): value is string;
 /**
  * Determines the proper delimiter based on file type or extension
@@ -19,17 +19,34 @@ export declare function getDelimiterFromFilePath(filePath: string): DelimiterCha
  */
 export declare const readJsonSync: typeof readJsonFileAsObject;
 /**
+ * a.k.a. `readJsonSync`
  * @param filePath `string`
- * @returns **`jsonData`** — `Record<string, any>`
- * - JSON data as an object
+ * @returns **`jsonData`** — `T extends Record<string, any>` - JSON data as an object
+ * @note returns empty object if error occurred while reading `filepath` or parsing json
+ * - use {@link readJsonSyncOrThrow} if throwing error is desired behavior
+ */
+export declare function readJsonFileAsObject<T extends Record<string, any> = {}>(filePath: string): T;
+/**
+ * @param filePath `string`
+ * @returns **`jsonData`** — `T extends Record<string, any>`
+ * @throws {Error} if error occurred while reading `filepath` or parsing json
+ */
+export declare function readJsonSyncOrThrow<T extends Record<string, any> = {}>(filePath: string): T;
+/**
+ * @param filePath `string`
+ * @param separator `string | RegExp` `default` = `/\r?\n/` (i.e. each line is an individual element in the array)
+ * @param encoding {@link BufferEncoding} `default` = `'utf8'`
+ * @returns **`arr`** `string[]` - the file content separated by specified param value
+ * - returns empty array if error occurs while reading file.
  */
-export declare function readJsonFileAsObject(filePath: string): Record<string, any>;
+export declare function readFileToArraySync(filePath: string, separator?: string | RegExp, encoding?: BufferEncoding): string[];
 /**
+ * @description adds `'.${expectedExtension}'` to end of `filePath` if not already present
  * @param filePath `string`
- * @param expectedExtension `string`
+ * @param expectedExtension `string | `{@link FileExtension}
  * @returns **`validatedFilePath`** `string`
  */
-export declare function coerceFileExtension(filePath: string, expectedExtension: string): string;
+export declare function coerceFileExtension(filePath: string, expectedExtension: string | FileExtension): string;
 /**
  * - {@link getDirectoryFiles}
  * @param arg1 `Array<`{@link FileData}` | string> | string`

package/dist/utils/io/reading.js

@@ -41,6 +41,8 @@ exports.isDirectory = isDirectory;
 exports.isFile = isFile;
 exports.getDelimiterFromFilePath = getDelimiterFromFilePath;
 exports.readJsonFileAsObject = readJsonFileAsObject;
+exports.readJsonSyncOrThrow = readJsonSyncOrThrow;
+exports.readFileToArraySync = readFileToArraySync;
 exports.coerceFileExtension = coerceFileExtension;
 exports.concatenateFiles = concatenateFiles;
 exports.getRows = getRows;
@@ -75,13 +77,13 @@ const types_1 = require("./types");
 const typeValidation_1 = require("../typeValidation");
 const validate = __importStar(require("../argumentValidation"));
 const logging_1 = require("./logging");
-/** for testing if `pathString (value)` points to an existing directory */
+/** checks if `pathString (value)` points to an existing directory */
 function isDirectory(value) {
     return ((0, typeValidation_1.isNonEmptyString)(value)
         && fs_1.default.existsSync(value)
         && fs_1.default.statSync(value).isDirectory());
 }
-/** for testing if `pathString (value)` points to an existing file */
+/** checks if `pathString (value)` points to an existing file */
 function isFile(value) {
     return ((0, typeValidation_1.isNonEmptyString)(value)
         && fs_1.default.existsSync(value)
@@ -112,9 +114,11 @@ function getDelimiterFromFilePath(filePath) {
  */
 exports.readJsonSync = readJsonFileAsObject;
 /**
+ * a.k.a. `readJsonSync`
  * @param filePath `string`
- * @returns **`jsonData`** — `Record<string, any>`
- * - JSON data as an object
+ * @returns **`jsonData`** — `T extends Record<string, any>` - JSON data as an object
+ * @note returns empty object if error occurred while reading `filepath` or parsing json
+ * - use {@link readJsonSyncOrThrow} if throwing error is desired behavior
  */
 function readJsonFileAsObject(filePath) {
     const source = (0, logging_1.getSourceString)(__filename, readJsonFileAsObject.name);
@@ -124,17 +128,60 @@ function readJsonFileAsObject(filePath) {
         const jsonData = JSON.parse(data);
         return jsonData;
     }
+    catch (error) {
+        config_1.typeshiLogger.error([`${source} Error reading JSON file, returning empty object`,
+            `Given filePath: '${filePath}'`,
+            `caught error: ${error}`,
+        ].join(config_1.INDENT_LOG_LINE));
+        return {};
+    }
+}
+/**
+ * @param filePath `string`
+ * @returns **`jsonData`** — `T extends Record<string, any>`
+ * @throws {Error} if error occurred while reading `filepath` or parsing json
+ */
+function readJsonSyncOrThrow(filePath) {
+    const source = (0, logging_1.getSourceString)(__filename, readJsonSyncOrThrow.name);
+    try {
+        filePath = coerceFileExtension(filePath, 'json');
+        const data = fs_1.default.readFileSync(filePath, 'utf8');
+        const jsonData = JSON.parse(data);
+        return jsonData;
+    }
     catch (error) {
         config_1.typeshiLogger.error([`${source} Error reading JSON file`,
             `Given filePath: '${filePath}'`,
-            `error: `, JSON.stringify(error, null, 4)
+            `caught error: ${error}`,
         ].join(config_1.INDENT_LOG_LINE));
         throw new Error(JSON.stringify(error));
     }
 }
 /**
  * @param filePath `string`
- * @param expectedExtension `string`
+ * @param separator `string | RegExp` `default` = `/\r?\n/` (i.e. each line is an individual element in the array)
+ * @param encoding {@link BufferEncoding} `default` = `'utf8'`
+ * @returns **`arr`** `string[]` - the file content separated by specified param value
+ * - returns empty array if error occurs while reading file.
+ */
+function readFileToArraySync(filePath, separator = /\r?\n/, encoding = 'utf8') {
+    const source = (0, logging_1.getSourceString)(__filename, readFileToArraySync.name);
+    try {
+        const content = fs_1.default.readFileSync(filePath, { encoding });
+        return content.split(separator);
+    }
+    catch (error) {
+        config_1.typeshiLogger.error([`${source} Error reading file, returning empty array`,
+            `Given filePath: '${filePath}'`,
+            `caught error: ${error}`,
+        ].join(config_1.INDENT_LOG_LINE));
+        return [];
+    }
+}
+/**
+ * @description adds `'.${expectedExtension}'` to end of `filePath` if not already present
+ * @param filePath `string`
+ * @param expectedExtension `string | `{@link FileExtension}
  * @returns **`validatedFilePath`** `string`
  */
 function coerceFileExtension(filePath, expectedExtension) {

package/dist/utils/io/types/Csv.d.ts

@@ -12,7 +12,7 @@ export type RowSourceMetaData = {
  * @enum {string} **`DelimitedFileTypeEnum`**
  * @property {string} CSV = `'csv'` Comma-separated values -> `.csv` file.
  * @property {string} TSV = `'tsv'` Tab-separated values -> `.tsv` file.
- * @property {string} AUTO = `'auto'`- call {@link getDelimiterFromFilePath}(filePath, fileType) to detect file type based on file extension.
+ * @property {string} AUTO = `'auto'`- call `getDelimiterFromFilePath(filePath, fileType)` to detect file type based on file extension.
  */
 export declare enum DelimitedFileTypeEnum {
     CSV = "csv",

package/dist/utils/io/types/Csv.js

@@ -8,7 +8,7 @@ exports.DelimiterCharacterEnum = exports.DelimitedFileTypeEnum = void 0;
  * @enum {string} **`DelimitedFileTypeEnum`**
  * @property {string} CSV = `'csv'` Comma-separated values -> `.csv` file.
  * @property {string} TSV = `'tsv'` Tab-separated values -> `.tsv` file.
- * @property {string} AUTO = `'auto'`- call {@link getDelimiterFromFilePath}(filePath, fileType) to detect file type based on file extension.
+ * @property {string} AUTO = `'auto'`- call `getDelimiterFromFilePath(filePath, fileType)` to detect file type based on file extension.
  */
 var DelimitedFileTypeEnum;
 (function (DelimitedFileTypeEnum) {

package/dist/utils/io/types/Io.d.ts

@@ -47,3 +47,7 @@ export type ParseOneToManyOptions = {
     keyPadOptions?: StringPadOptions;
     valuePadOptions?: StringPadOptions;
 };
+/**
+ * common file extensions handled as input/output
+ */
+export type FileExtension = '.csv' | '.tsv' | '.txt' | '.json' | '.xlsx' | '.xls' | '.xml' | '.yaml' | '.yml';

package/dist/utils/typeValidation.d.ts

@@ -208,19 +208,19 @@ export declare function isFunction(value: any): value is Function;
  */
 export declare function isUndefined(value: any): value is undefined;
 export declare function isUndefinedOrNull(value: unknown): value is undefined | null;
-export type NumberKeys<T, Required extends true | false = false> = {
+export type NumberKeys<T, Required extends boolean = false> = {
     [K in keyof T]: Required extends true ? (T[K] extends number ? K : never) : (T[K] extends number | undefined ? K : never);
 }[keyof T][];
-export type ArrayKeys<T, Required extends true | false = false> = {
+export type ArrayKeys<T, Required extends boolean = false> = {
     [K in keyof T]: Required extends true ? (T[K] extends Array<any> ? K : never) : (T[K] extends Array<any> | undefined ? K : never);
 }[keyof T][];
-export type ArrayOfTypeKeys<T, U, Required extends true | false = false> = {
+export type ArrayOfTypeKeys<T, U, Required extends boolean = false> = {
     [K in keyof T]: Required extends true ? (T[K] extends Array<U> ? K : never) : (T[K] extends Array<U> | undefined ? K : never);
 }[keyof T][];
-export type StringKeys<T, Required extends true | false = false> = {
+export type StringKeys<T, Required extends boolean = false> = {
     [K in keyof T]: Required extends true ? (T[K] extends string ? K : never) : (T[K] extends string | undefined ? K : never);
 }[keyof T][];
-export type PrimitiveKeys<T, Required extends true | false = false> = {
+export type PrimitiveKeys<T, Required extends boolean = false> = {
     [K in keyof T]: Required extends true ? (T[K] extends string | number | boolean | null ? K : never) : (T[K] extends string | number | boolean | null | undefined ? K : never);
 }[keyof T][];
 export type Primitive = string | number | boolean | null | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "typeshi",
-    "version": "1.7.11",
+    "version": "1.7.12",
     "description": "TypeScript utility modules",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",