@jsnw/srv-utils 1.3.2 → 2.1.0

package/README.md

@@ -9,20 +9,10 @@ npm install @jsnw/srv-utils
 ```
 
 Optional dependencies:
-- `module-alias` for `useTsconfigPaths`
 - `@nestjs/core` and `@nestjs/common` for `withNest`
 
 ## Exports
 
-### useTsconfigPaths(fromPath, tsconfigPath)
-Loads `compilerOptions.paths` from a tsconfig file and registers them via `module-alias`.
-
-```ts
-import {useTsconfigPaths} from '@jsnw/srv-utils';
-
-useTsconfigPaths(__dirname, './tsconfig.json');
-```
-
 ### getRootPackageDirnameSync()
 Finds the highest directory (from the current module) that still has a readable `package.json`.
 

package/dist/index.cjs

@@ -0,0 +1,349 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let node_fs_promises = require("node:fs/promises");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+let zod = require("zod");
+let yaml = require("yaml");
+let ms = require("ms");
+ms = __toESM(ms);
+let node_crypto = require("node:crypto");
+//#region src/file-exists.ts
+/**
+* @param {string} path
+* @param {number} [mode]
+* @returns {boolean}
+*/
+async function fileExists(path, mode = node_fs.constants.F_OK | node_fs.constants.R_OK) {
+	try {
+		await (0, node_fs_promises.access)(path, mode);
+		return true;
+	} catch (e) {
+		return false;
+	}
+}
+/**
+* @param {string} path
+* @param {number} [mode]
+* @returns {boolean}
+*/
+function fileExistsSync(path, mode = node_fs.constants.F_OK | node_fs.constants.R_OK) {
+	try {
+		(0, node_fs.accessSync)(path, mode);
+		return true;
+	} catch (e) {
+		return false;
+	}
+}
+//#endregion
+//#region src/getRootPackageDirname.ts
+let cachedRootPackageDirname = null;
+/**
+* @returns {string}
+*/
+function getRootPackageDirnameSync() {
+	if (cachedRootPackageDirname !== null) return cachedRootPackageDirname;
+	let path = (0, node_path.resolve)(__dirname, ".."), lastValidPath = path;
+	if (/[\\\/]node_modules[\\\/]/i.test(path)) {
+		const pieces = path.split(/[\\\/]node_modules[\\\/]/i);
+		if (pieces.length > 0) path = pieces[0];
+	}
+	while (true) {
+		const packageJsonPath = (0, node_path.resolve)(path, "package.json");
+		try {
+			(0, node_fs.accessSync)(packageJsonPath, node_fs.constants.F_OK | node_fs.constants.R_OK);
+		} catch (e) {
+			break;
+		}
+		lastValidPath = path;
+		path = (0, node_path.resolve)(path, "..");
+	}
+	cachedRootPackageDirname = lastValidPath;
+	return lastValidPath;
+}
+//#endregion
+//#region src/config/config-loader.ts
+const PKG_ROOT_REGEX = /^%pkgroot(?:[\/\\]|$)/i;
+const ENV_VAR_REGEX = /^%env:(?<var_name>[A-Za-z0-9_]+)(?:[\/\\]|$)/i;
+var ConfigLoader = class ConfigLoader {
+	static _instance;
+	/**
+	* @returns {ConfigLoader}
+	*/
+	static instance() {
+		if (!ConfigLoader._instance) ConfigLoader._instance = new ConfigLoader();
+		return ConfigLoader._instance;
+	}
+	/**
+	* @template {z.ZodObject} S
+	* @template {object} P
+	* @param {string} path You can use %pkgroot prefix for automatic project root resolution by AppConfigLoader.
+	* Also, you can use %env:ENV_VARIABLE to resolve config path based on environment variable
+	* Example 1: %pkgroot/config.yml
+	* Example 2: %env:CONFIG_PATH/config.yml
+	* @param {S} schema
+	* @param {P} [addProps]
+	* @returns {ResolvedConfig<S, P>}
+	*/
+	static loadConfig(path, schema, addProps) {
+		const loader = ConfigLoader.instance();
+		const [yaml$1, loadError] = loader.loadYamlFile(path);
+		if (loadError) {
+			console.error(loadError.message);
+			process.exit(1);
+		}
+		const [processedYaml, directiveErrors] = loader.processDirectives((0, node_path.dirname)(loader.resolveFilePath(path)), yaml$1);
+		if (directiveErrors && directiveErrors.length > 0) {
+			for (const err of directiveErrors) console.error(`directive error: ${err.message}`);
+			process.exit(1);
+		}
+		const [validatedYaml, validateError] = loader.validateYaml(processedYaml, schema);
+		if (validateError) {
+			console.error(validateError.message);
+			process.exit(1);
+		}
+		validatedYaml["isDev"] = (process?.env?.APP_CONTEXT ?? process?.env?.APPLICATION_CONTEXT ?? process?.env?.NODE_ENV ?? "").toLowerCase() !== "production";
+		return {
+			...validatedYaml,
+			...addProps ?? {}
+		};
+	}
+	constructor() {}
+	/**
+	* @param {string} path
+	* @returns {ErrorResult<any, Error>}
+	* @protected
+	*/
+	loadYamlFile(path) {
+		path = this.resolveFilePath(path);
+		if (!fileExistsSync(path)) return [null, /* @__PURE__ */ new Error(`YAML file does not exists at path: ${path}`)];
+		let data = void 0, parsedYml = void 0;
+		try {
+			data = (0, node_fs.readFileSync)(path, "utf-8");
+		} catch (e) {
+			return [null, /* @__PURE__ */ new Error(`Failed to read config file at path: ${path}`)];
+		}
+		try {
+			parsedYml = (0, yaml.parse)(data, { prettyErrors: true });
+		} catch (e) {
+			return [null, /* @__PURE__ */ new Error(`Failed to parse YAML file at path: ${path}`)];
+		}
+		return [parsedYml, null];
+	}
+	/**
+	* @template {z.ZodTypeAny} T
+	* @param data
+	* @param {T} schema
+	* @returns {ErrorResult<output<T>, Error>}
+	* @protected
+	*/
+	validateYaml(data, schema) {
+		const { data: parsed, error, success } = schema.safeParse(data);
+		if (!success) {
+			if (error && error instanceof zod.ZodError) return [null, /* @__PURE__ */ new Error(`Failed to validate yaml (#1). Error message: ${zod.z.prettifyError(error)}`)];
+			return [null, /* @__PURE__ */ new Error(`Failed to validate yaml (#2)`)];
+		}
+		return [parsed, null];
+	}
+	/**
+	* @param {string} mainYamlDirname
+	* @param yaml
+	* @returns {ErrorResult<any, Error[]>}
+	* @protected
+	*/
+	processDirectives(mainYamlDirname, yaml$2) {
+		if (typeof yaml$2 !== "object") return yaml$2;
+		const nodesToVisit = [yaml$2], errors = [];
+		for (let i = 0; i < nodesToVisit.length; i++) {
+			const node = nodesToVisit[i];
+			if (typeof node !== "object" || Array.isArray(node)) continue;
+			const nodeFields = Object.keys(node);
+			for (const field of nodeFields) if (field === "$include") {
+				const $includePaths = [];
+				if (typeof node["$include"] === "string") $includePaths.push(node["$include"]);
+				else if (Array.isArray(node["$include"])) $includePaths.push(...node["$include"].filter((v) => v && typeof v === "string" && v.trim() !== ""));
+				delete node["$include"];
+				for (const path of $includePaths) {
+					const [loadedYaml, loadError] = this.loadYamlFile(this.resolveIncludePath(mainYamlDirname, path));
+					if (loadError) errors.push(loadError);
+					else for (const [k, v] of Object.entries(loadedYaml)) node[k] = v;
+				}
+			} else if (typeof node[field] === "string" && /^\s*\$[A-Z0-9_]+$/.test(node[field])) node[field] = process.env?.[node[field].trim().slice(1)] ?? "";
+			for (const k of Object.keys(node)) if (Object.hasOwn(node, k) && typeof node[k] === "object" && !Array.isArray(node[k])) nodesToVisit.push(node[k]);
+		}
+		return [yaml$2, errors];
+	}
+	resolveFilePath(path) {
+		const initialPath = path;
+		while (ENV_VAR_REGEX.test(path)) {
+			const m = path.match(ENV_VAR_REGEX);
+			if (m.groups?.["var_name"]) if (process.env?.[m.groups["var_name"]]) path = path.replace(ENV_VAR_REGEX, process.env[m.groups["var_name"]].replace(/[\/\\]+$/, "") + node_path.sep);
+			else throw new Error(`Failed to resolve path: "${initialPath}"`);
+		}
+		if (PKG_ROOT_REGEX.test(path)) path = path.replace(PKG_ROOT_REGEX, getRootPackageDirnameSync() + node_path.sep);
+		return (0, node_path.resolve)(path);
+	}
+	/**
+	* @param {string} fromDirname
+	* @param {string} toPath
+	* @returns {string}
+	* @private
+	*/
+	resolveIncludePath(fromDirname, toPath) {
+		return (0, node_path.resolve)(this.resolveFilePath(fromDirname), toPath);
+	}
+};
+//#endregion
+//#region src/config/predefined-schemas/timestring.schema.ts
+const TIMESTRING_REGEX = new RegExp(`\\d+\\s*(?:${[
+	"Years",
+	"Year",
+	"Yrs",
+	"Yr",
+	"Y",
+	"Weeks",
+	"Week",
+	"W",
+	"Days",
+	"Day",
+	"D",
+	"Hours",
+	"Hour",
+	"Hrs",
+	"Hr",
+	"H",
+	"Minutes",
+	"Minute",
+	"Mins",
+	"Min",
+	"M",
+	"Seconds",
+	"Second",
+	"Secs",
+	"Sec",
+	"s",
+	"Milliseconds",
+	"Millisecond",
+	"Msecs",
+	"Msec",
+	"Ms"
+].map((unit) => unit.toLowerCase()).join("|")})`, "i");
+const timeStringSchema = zod.z.string().nonempty().regex(TIMESTRING_REGEX).transform((v) => (0, ms.default)(v));
+//#endregion
+//#region src/config/predefined-schemas/connection.schema.ts
+const connectionSchema = zod.z.object({
+	host: zod.z.string().nonempty(),
+	port: zod.z.coerce.number().min(1).max(65535),
+	user: zod.z.string(),
+	pass: zod.z.string()
+});
+//#endregion
+//#region src/config/predefined-schemas/index.ts
+const configSchemas = {
+	timeString: timeStringSchema,
+	connection: connectionSchema,
+	mongodbConnection: connectionSchema.extend({
+		db: zod.z.string().nonempty(),
+		authDb: zod.z.string().optional(),
+		connectTimeout: timeStringSchema.default(5e3)
+	}).transform((v) => ({
+		...v,
+		authDb: v.authDb || v.db,
+		dsn: `mongodb://${v.host}:${v.port}/${v.db}`
+	})),
+	mysqlConnection: connectionSchema.extend({ dbname: zod.z.string().nonempty() }),
+	redisConnection: connectionSchema.extend({
+		db: zod.z.number().min(0).default(0),
+		keyPrefix: zod.z.string().default("")
+	}),
+	rabbitConnection: connectionSchema.extend({ vhost: zod.z.string().default("/") })
+};
+//#endregion
+//#region src/withNest.ts
+/**
+* Executes a given function within the context of a NestJS application.
+*
+* This asynchronous function initializes a NestJS application context using the specified
+* module class and then executes the provided function `fn` with the application instance.
+* The application context is automatically closed upon completion of the function execution,
+* unless the function execution requests otherwise by invoking a callback.
+*
+* @param {any} moduleCls - The module class to be used for creating the NestJS application context.
+* @param {WithNestFn} fn - The function to be executed with the NestJS application context.
+*                             It receives the application instance and a callback to prevent
+*                             automatic application context closure.
+* @param {NestApplicationContextOptions} [options]
+* @returns {Promise<void>} A promise that resolves when the function execution is complete.
+* @throws - Will throw an error if the `@nestjs/core` and/or `@nestjs/common` library is not found.
+* @throws - Will propagate any error thrown by the executed function `fn`.
+*/
+async function withNest(moduleCls, fn, options) {
+	let nestFactory = null;
+	try {
+		nestFactory = (await import("@nestjs/core"))?.NestFactory;
+		if (!nestFactory) throw new Error("NestFactory not found");
+	} catch (e) {
+		throw new Error("@nestjs/core and @nestjs/common are required for this function to work");
+	}
+	const app = await nestFactory.createApplicationContext(moduleCls, options);
+	let closeApplication = true;
+	let _e = void 0;
+	try {
+		await fn(app, () => {
+			closeApplication = false;
+		});
+	} catch (e) {
+		console.error("Error caught while executing the WithNestFn. Error:", e);
+		_e = e;
+	}
+	try {
+		if (closeApplication) await app.close();
+	} catch (e) {
+		console.error("Failed to close application. Error:", e);
+	}
+	if (_e) throw _e;
+}
+//#endregion
+//#region src/create-random-string.ts
+/**
+* @param {number} length The length of the string
+* @return {Promise<string>}
+*/
+function createRandomString(length) {
+	if (length <= 0) return Promise.resolve("");
+	return new Promise((resolve, reject) => {
+		(0, node_crypto.randomBytes)(Math.ceil(length / 2), (err, buff) => {
+			if (err) return reject(err);
+			return resolve(buff.toString("hex").slice(0, length));
+		});
+	});
+}
+//#endregion
+exports.ConfigLoader = ConfigLoader;
+exports.configSchemas = configSchemas;
+exports.createRandomString = createRandomString;
+exports.fileExists = fileExists;
+exports.fileExistsSync = fileExistsSync;
+exports.getRootPackageDirnameSync = getRootPackageDirnameSync;
+exports.withNest = withNest;

package/dist/index.d.cts

@@ -0,0 +1,169 @@
+import { z } from "zod";
+import { ErrorResult } from "@jsnw/common-utils";
+import { INestApplicationContext } from "@nestjs/common";
+import { NestApplicationContextOptions } from "@nestjs/common/interfaces/nest-application-context-options.interface";
+
+//#region src/file-exists.d.ts
+/**
+ * @param {string} path
+ * @param {number} [mode]
+ * @returns {boolean}
+ */
+declare function fileExists(path: string, mode?: number): Promise<boolean>;
+/**
+ * @param {string} path
+ * @param {number} [mode]
+ * @returns {boolean}
+ */
+declare function fileExistsSync(path: string, mode?: number): boolean;
+//#endregion
+//#region src/getRootPackageDirname.d.ts
+/**
+ * @returns {string}
+ */
+declare function getRootPackageDirnameSync(): string;
+//#endregion
+//#region src/config/config-loader.types.d.ts
+type ResolvedConfig<T extends z.ZodObject, P extends object | undefined = undefined> = z.output<T> & {
+  isDev: boolean;
+} & (P extends undefined ? {} : P);
+//#endregion
+//#region src/config/config-loader.d.ts
+declare class ConfigLoader {
+  private static _instance;
+  /**
+   * @returns {ConfigLoader}
+   */
+  static instance(): ConfigLoader;
+  /**
+   * @template {z.ZodObject} S
+   * @template {object} P
+   * @param {string} path You can use %pkgroot prefix for automatic project root resolution by AppConfigLoader.
+   * Also, you can use %env:ENV_VARIABLE to resolve config path based on environment variable
+   * Example 1: %pkgroot/config.yml
+   * Example 2: %env:CONFIG_PATH/config.yml
+   * @param {S} schema
+   * @param {P} [addProps]
+   * @returns {ResolvedConfig<S, P>}
+   */
+  static loadConfig<S extends z.ZodObject, P extends object | undefined = undefined>(path: string, schema: S, addProps?: P): ResolvedConfig<S, P>;
+  private constructor();
+  /**
+   * @param {string} path
+   * @returns {ErrorResult<any, Error>}
+   * @protected
+   */
+  protected loadYamlFile(path: string): ErrorResult<any, Error>;
+  /**
+   * @template {z.ZodTypeAny} T
+   * @param data
+   * @param {T} schema
+   * @returns {ErrorResult<output<T>, Error>}
+   * @protected
+   */
+  protected validateYaml<T extends z.ZodTypeAny>(data: any, schema: T): ErrorResult<z.infer<T>, Error>;
+  /**
+   * @param {string} mainYamlDirname
+   * @param yaml
+   * @returns {ErrorResult<any, Error[]>}
+   * @protected
+   */
+  protected processDirectives(mainYamlDirname: string, yaml: any): ErrorResult<any, Error[]>;
+  private resolveFilePath;
+  /**
+   * @param {string} fromDirname
+   * @param {string} toPath
+   * @returns {string}
+   * @private
+   */
+  private resolveIncludePath;
+}
+//#endregion
+//#region src/config/predefined-schemas/index.d.ts
+declare const configSchemas: {
+  timeString: import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<number, string>>;
+  connection: import("zod").ZodObject<{
+    host: import("zod").ZodString;
+    port: import("zod").ZodCoercedNumber<unknown>;
+    user: import("zod").ZodString;
+    pass: import("zod").ZodString;
+  }, import("zod/v4/core").$strip>;
+  mongodbConnection: import("zod").ZodPipe<import("zod").ZodObject<{
+    host: import("zod").ZodString;
+    port: import("zod").ZodCoercedNumber<unknown>;
+    user: import("zod").ZodString;
+    pass: import("zod").ZodString;
+    db: import("zod").ZodString;
+    authDb: import("zod").ZodOptional<import("zod").ZodString>;
+    connectTimeout: import("zod").ZodDefault<import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<number, string>>>;
+  }, import("zod/v4/core").$strip>, import("zod").ZodTransform<{
+    authDb: string;
+    dsn: string;
+    host: string;
+    port: number;
+    user: string;
+    pass: string;
+    db: string;
+    connectTimeout: number;
+  }, {
+    host: string;
+    port: number;
+    user: string;
+    pass: string;
+    db: string;
+    connectTimeout: number;
+    authDb?: string;
+  }>>;
+  mysqlConnection: import("zod").ZodObject<{
+    host: import("zod").ZodString;
+    port: import("zod").ZodCoercedNumber<unknown>;
+    user: import("zod").ZodString;
+    pass: import("zod").ZodString;
+    dbname: import("zod").ZodString;
+  }, import("zod/v4/core").$strip>;
+  redisConnection: import("zod").ZodObject<{
+    host: import("zod").ZodString;
+    port: import("zod").ZodCoercedNumber<unknown>;
+    user: import("zod").ZodString;
+    pass: import("zod").ZodString;
+    db: import("zod").ZodDefault<import("zod").ZodNumber>;
+    keyPrefix: import("zod").ZodDefault<import("zod").ZodString>;
+  }, import("zod/v4/core").$strip>;
+  rabbitConnection: import("zod").ZodObject<{
+    host: import("zod").ZodString;
+    port: import("zod").ZodCoercedNumber<unknown>;
+    user: import("zod").ZodString;
+    pass: import("zod").ZodString;
+    vhost: import("zod").ZodDefault<import("zod").ZodString>;
+  }, import("zod/v4/core").$strip>;
+};
+//#endregion
+//#region src/withNest.d.ts
+type WithNestFn = (app: INestApplicationContext, preventClosing: () => void) => Promise<void>;
+/**
+ * Executes a given function within the context of a NestJS application.
+ *
+ * This asynchronous function initializes a NestJS application context using the specified
+ * module class and then executes the provided function `fn` with the application instance.
+ * The application context is automatically closed upon completion of the function execution,
+ * unless the function execution requests otherwise by invoking a callback.
+ *
+ * @param {any} moduleCls - The module class to be used for creating the NestJS application context.
+ * @param {WithNestFn} fn - The function to be executed with the NestJS application context.
+ *                             It receives the application instance and a callback to prevent
+ *                             automatic application context closure.
+ * @param {NestApplicationContextOptions} [options]
+ * @returns {Promise<void>} A promise that resolves when the function execution is complete.
+ * @throws - Will throw an error if the `@nestjs/core` and/or `@nestjs/common` library is not found.
+ * @throws - Will propagate any error thrown by the executed function `fn`.
+ */
+declare function withNest(moduleCls: any, fn: WithNestFn, options?: NestApplicationContextOptions): Promise<void>;
+//#endregion
+//#region src/create-random-string.d.ts
+/**
+ * @param {number} length The length of the string
+ * @return {Promise<string>}
+ */
+declare function createRandomString(length: number): Promise<string>;
+//#endregion
+export { ConfigLoader, type ResolvedConfig, configSchemas, createRandomString, fileExists, fileExistsSync, getRootPackageDirnameSync, withNest };

package/package.json

@@ -1,23 +1,16 @@
 {
   "name": "@jsnw/srv-utils",
-  "version": "1.3.2",
+  "version": "2.1.0",
   "description": "Server-side utilities for Node.js/TypeScript: tsconfig paths, Nest helpers, and config loading.",
-  "main": "./dist/index.js",
-  "types": "./dist/types/index.d.ts",
+  "engines": {
+    "node": ">=20"
+  },
   "exports": {
-    ".": {
-      "require": "./dist/index.js",
-      "types": "./dist/types/index.d.ts"
+    "node": {
+      "default": "./dist/index.cjs",
+      "types": "./dist/index.d.cts"
     }
   },
-  "scripts": {
-    "clean": "rimraf ./dist",
-    "build": "npm run clean && tsc -p tsconfig.json",
-    "test": "jest --passWithNoTests",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
-    "prepublishOnly": "npm run build"
-  },
   "files": [
     "./dist",
     "README.md"
@@ -42,25 +35,26 @@
   "dependencies": {
     "@jsnw/common-utils": "^1.0.0",
     "ms": "^2.1.3",
-    "yaml": "^2.8.2",
-    "zod": "^4.3.6"
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
   },
   "optionalDependencies": {
-    "@nestjs/common": "^11.1.12",
-    "@nestjs/core": "^11.1.12",
-    "module-alias": "^2.3.3"
+    "@nestjs/common": "^11.1.27",
+    "@nestjs/core": "^11.1.27"
   },
   "devDependencies": {
-    "@nestjs/common": "^11.1.12",
-    "@nestjs/core": "^11.1.12",
     "@types/jest": "^30.0.0",
-    "@types/module-alias": "^2.0.4",
     "@types/ms": "^2.1.0",
-    "jest": "^30.2.0",
-    "module-alias": "^2.3.3",
-    "rimraf": "^6.1.2",
-    "ts-jest": "^29.4.6",
-    "tslib": "^2.8.1",
+    "@types/node": "^24.13.2",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "tsdown": "^0.22.3",
     "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
   }
-}
+}