@faasjs/node-utils 8.0.0-beta.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019--present, Zhu Feng
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# @faasjs/node-utils
+
+FaasJS Node.js utility toolkit.
+
+[![License: MIT](https://img.shields.io/npm/l/@faasjs/node-utils.svg)](https://github.com/faasjs/faasjs/blob/main/packages/node-utils/LICENSE)
+[![NPM Version](https://img.shields.io/npm/v/@faasjs/node-utils.svg)](https://www.npmjs.com/package/@faasjs/node-utils)
+
+## Install
+
+```sh
+npm install @faasjs/node-utils
+```
+
+## Functions
+
+- [deepMerge](functions/deepMerge.md)
+- [detectNodeRuntime](functions/detectNodeRuntime.md)
+- [loadConfig](functions/loadConfig.md)
+- [loadFunc](functions/loadFunc.md)
+- [loadPackage](functions/loadPackage.md)
+- [resetRuntime](functions/resetRuntime.md)
+- [streamToObject](functions/streamToObject.md)
+- [streamToText](functions/streamToText.md)
+
+## Type Aliases
+
+- [NodeRuntime](type-aliases/NodeRuntime.md)
+
+## Variables
+
+- [streamToString](variables/streamToString.md)

package/dist/index.cjs

@@ -0,0 +1,221 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+let _faasjs_logger = require("@faasjs/logger");
+let js_yaml = require("js-yaml");
+
+//#region src/deep_merge.ts
+const shouldMerge = (item) => {
+	const type = Object.prototype.toString.call(item);
+	return type === "[object Object]" || type === "[object Array]";
+};
+/**
+* Deep merge two objects or arrays.
+*
+* Features:
+* * All objects will be cloned before merging.
+* * Merging order is from right to left.
+* * If an array include same objects, it will be unique to one.
+*
+* ```ts
+* deepMerge({ a: 1 }, { a: 2 }) // { a: 2 }
+* deepMerge([1, 2], [2, 3]) // [1, 2, 3]
+* ```
+*/
+function deepMerge(...sources) {
+	let acc = Object.create(null);
+	for (const source of sources) if (Array.isArray(source)) {
+		if (!Array.isArray(acc)) acc = [];
+		acc = [...new Set(source.concat(...acc))];
+	} else if (shouldMerge(source)) for (const [key, value] of Object.entries(source)) {
+		let val;
+		if (shouldMerge(value)) val = deepMerge(acc[key], value);
+		else val = value;
+		acc = {
+			...acc,
+			[key]: val
+		};
+	}
+	return acc;
+}
+
+//#endregion
+//#region src/load_config.ts
+function isObject(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function createConfigError(filePath, keyPath, reason) {
+	return Error(`[loadConfig] Invalid faas.yaml ${filePath} at "${keyPath}": ${reason}`);
+}
+function validateServerConfig(filePath, staging, server) {
+	if (!isObject(server)) throw createConfigError(filePath, `${staging}.server`, "must be an object");
+	if (typeof server.root !== "undefined" && typeof server.root !== "string") throw createConfigError(filePath, `${staging}.server.root`, "must be a string");
+	if (typeof server.base !== "undefined" && typeof server.base !== "string") throw createConfigError(filePath, `${staging}.server.base`, "must be a string");
+}
+function validateFaasYaml(filePath, config) {
+	if (typeof config === "undefined" || config === null) return Object.create(null);
+	if (!isObject(config)) throw createConfigError(filePath, "<root>", "must be an object");
+	for (const staging in config) {
+		if (staging === "types") throw createConfigError(filePath, "types", "has been removed, move related settings out of faas.yaml");
+		const stageConfig = config[staging];
+		if (typeof stageConfig === "undefined" || stageConfig === null) continue;
+		if (!isObject(stageConfig)) throw createConfigError(filePath, staging, "must be an object");
+		if (Object.hasOwn(stageConfig, "types")) throw createConfigError(filePath, `${staging}.types`, "has been removed, move related settings out of faas.yaml");
+		if (Object.hasOwn(stageConfig, "server")) validateServerConfig(filePath, staging, stageConfig.server);
+	}
+	return config;
+}
+/**
+* Load configuration from faas.yaml
+*/
+var Config = class {
+	root;
+	filename;
+	origin;
+	defaults;
+	logger;
+	constructor(root, filename, logger) {
+		this.logger = new _faasjs_logger.Logger(logger?.label ? `${logger.label}] [config` : "config");
+		this.root = root;
+		if (!this.root.endsWith(node_path.sep)) this.root += node_path.sep;
+		this.filename = filename;
+		this.logger.debug("load %s in %s", filename, root);
+		const configs = [];
+		[this.root, "."].concat((0, node_path.dirname)(filename.replace(root, "")).split(node_path.sep)).reduce((base, path) => {
+			const root = (0, node_path.join)(base, path);
+			if (root === base) return base;
+			const faas = (0, node_path.join)(root, "faas.yaml");
+			if ((0, node_fs.existsSync)(faas)) configs.push(validateFaasYaml(faas, (0, js_yaml.load)((0, node_fs.readFileSync)(faas).toString())));
+			return root;
+		});
+		this.origin = deepMerge(...configs);
+		this.defaults = deepMerge(this.origin.defaults || {});
+		for (const key in this.origin) {
+			if (key !== "defaults") this[key] = deepMerge(this.defaults, this.origin[key]);
+			const data = this[key];
+			if (data.plugins) for (const pluginKey in data.plugins) {
+				const plugin = data.plugins[pluginKey];
+				plugin.name = pluginKey;
+			}
+		}
+	}
+	get(key) {
+		return this[key] || this.defaults || Object.create(null);
+	}
+};
+/**
+* Load configuration from faas.yaml
+*/
+function loadConfig(root, filename, staging, logger) {
+	return new Config(root, filename, logger).get(staging);
+}
+
+//#endregion
+//#region src/load_package.ts
+let _runtime = null;
+function resetRuntime() {
+	_runtime = null;
+}
+/**
+* Detect current JavaScript runtime environment.
+*
+* This function checks for presence of `require` first, then falls back to
+* Node.js ESM detection via `process.versions.node`.
+*
+* @returns {NodeRuntime} Returns `module` for ESM and `commonjs` for CJS.
+* @throws {Error} Throws an error if runtime cannot be determined.
+*/
+function detectNodeRuntime() {
+	if (_runtime) return _runtime;
+	if (typeof globalThis.require === "function" && typeof module !== "undefined") return _runtime = "commonjs";
+	if (typeof process !== "undefined" && process.versions?.node) return _runtime = "module";
+	throw Error("Unknown runtime");
+}
+/**
+* Asynchronously loads a package by its name, supporting both ESM and CJS.
+*
+* @template T The type of module to be loaded.
+* @param name The package name to load.
+* @param defaultNames Preferred export keys used to resolve default values.
+* @returns Loaded module or resolved default export.
+*/
+async function loadPackage(name, defaultNames = "default") {
+	const runtime = detectNodeRuntime();
+	let module;
+	if (runtime === "module") {
+		module = await import(name);
+		if (typeof defaultNames === "string") return defaultNames in module ? module[defaultNames] : module;
+		for (const key of defaultNames) if (key in module) return module[key];
+		return module;
+	}
+	if (runtime === "commonjs") {
+		module = globalThis.require(name);
+		if (typeof defaultNames === "string") return defaultNames in module ? module[defaultNames] : module;
+		for (const key of defaultNames) if (key in module) return module[key];
+		return module;
+	}
+	throw Error("Unknown runtime");
+}
+
+//#endregion
+//#region src/load_func.ts
+/**
+* Load a FaasJS function and its configuration, returning the handler.
+*
+* @param root Project root directory used to resolve configuration.
+* @param filename Path to the packaged FaasJS function file to load.
+* @param staging Staging directory name (used when locating config).
+* @returns A promise that resolves to the function handler.
+*
+* @example
+* ```ts
+* import { loadFunc } from '@faasjs/node-utils'
+*
+* const handler = await loadFunc(
+*   process.cwd(),
+*   __dirname + '/example.func.ts',
+*   'development'
+* )
+*
+* const result = await handler(event, context)
+* console.log(result)
+* ```
+*/
+async function loadFunc(root, filename, staging) {
+	const func = await loadPackage(filename);
+	func.config = await loadConfig(root, filename, staging);
+	return func.export().handler;
+}
+
+//#endregion
+//#region src/stream.ts
+/**
+* Convert ReadableStream to text.
+*
+* @throws {TypeError} If stream is not a ReadableStream instance.
+*/
+async function streamToText(stream) {
+	if (!(stream instanceof ReadableStream)) throw new TypeError("stream must be a ReadableStream instance");
+	return new Response(stream).text();
+}
+/**
+* Convert ReadableStream to object.
+*
+* @throws {TypeError} If stream is not a ReadableStream instance.
+*/
+async function streamToObject(stream) {
+	if (!(stream instanceof ReadableStream)) throw new TypeError("stream must be a ReadableStream instance");
+	return new Response(stream).json();
+}
+const streamToString = streamToText;
+
+//#endregion
+exports.deepMerge = deepMerge;
+exports.detectNodeRuntime = detectNodeRuntime;
+exports.loadConfig = loadConfig;
+exports.loadFunc = loadFunc;
+exports.loadPackage = loadPackage;
+exports.resetRuntime = resetRuntime;
+exports.streamToObject = streamToObject;
+exports.streamToString = streamToString;
+exports.streamToText = streamToText;

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+import { Config, ExportedHandler } from "@faasjs/func";
+import { Logger } from "@faasjs/logger";
+
+//#region src/deep_merge.d.ts
+/**
+ * Deep merge two objects or arrays.
+ *
+ * Features:
+ * * All objects will be cloned before merging.
+ * * Merging order is from right to left.
+ * * If an array include same objects, it will be unique to one.
+ *
+ * ```ts
+ * deepMerge({ a: 1 }, { a: 2 }) // { a: 2 }
+ * deepMerge([1, 2], [2, 3]) // [1, 2, 3]
+ * ```
+ */
+declare function deepMerge(...sources: any[]): any;
+//#endregion
+//#region src/load_config.d.ts
+/**
+ * Load configuration from faas.yaml
+ */
+declare function loadConfig(root: string, filename: string, staging: string, logger?: Logger): Config;
+//#endregion
+//#region src/load_func.d.ts
+/**
+ * Load a FaasJS function and its configuration, returning the handler.
+ *
+ * @param root Project root directory used to resolve configuration.
+ * @param filename Path to the packaged FaasJS function file to load.
+ * @param staging Staging directory name (used when locating config).
+ * @returns A promise that resolves to the function handler.
+ *
+ * @example
+ * ```ts
+ * import { loadFunc } from '@faasjs/node-utils'
+ *
+ * const handler = await loadFunc(
+ *   process.cwd(),
+ *   __dirname + '/example.func.ts',
+ *   'development'
+ * )
+ *
+ * const result = await handler(event, context)
+ * console.log(result)
+ * ```
+ */
+declare function loadFunc<TEvent = any, TContext = any, TResult = any>(root: string, filename: string, staging: string): Promise<ExportedHandler<TEvent, TContext, TResult>>;
+//#endregion
+//#region src/load_package.d.ts
+type NodeRuntime = 'commonjs' | 'module';
+declare function resetRuntime(): void;
+/**
+ * Detect current JavaScript runtime environment.
+ *
+ * This function checks for presence of `require` first, then falls back to
+ * Node.js ESM detection via `process.versions.node`.
+ *
+ * @returns {NodeRuntime} Returns `module` for ESM and `commonjs` for CJS.
+ * @throws {Error} Throws an error if runtime cannot be determined.
+ */
+declare function detectNodeRuntime(): NodeRuntime;
+/**
+ * Asynchronously loads a package by its name, supporting both ESM and CJS.
+ *
+ * @template T The type of module to be loaded.
+ * @param name The package name to load.
+ * @param defaultNames Preferred export keys used to resolve default values.
+ * @returns Loaded module or resolved default export.
+ */
+declare function loadPackage<T = unknown>(name: string, defaultNames?: string | string[]): Promise<T>;
+//#endregion
+//#region src/stream.d.ts
+/**
+ * Convert ReadableStream to text.
+ *
+ * @throws {TypeError} If stream is not a ReadableStream instance.
+ */
+declare function streamToText(stream: ReadableStream<Uint8Array>): Promise<string>;
+/**
+ * Convert ReadableStream to object.
+ *
+ * @throws {TypeError} If stream is not a ReadableStream instance.
+ */
+declare function streamToObject<T = any>(stream: ReadableStream<Uint8Array>): Promise<T>;
+declare const streamToString: typeof streamToText;
+//#endregion
+export { type NodeRuntime, deepMerge, detectNodeRuntime, loadConfig, loadFunc, loadPackage, resetRuntime, streamToObject, streamToString, streamToText };

package/dist/index.mjs

@@ -0,0 +1,212 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
+import { Logger } from "@faasjs/logger";
+import { load } from "js-yaml";
+
+//#region src/deep_merge.ts
+const shouldMerge = (item) => {
+	const type = Object.prototype.toString.call(item);
+	return type === "[object Object]" || type === "[object Array]";
+};
+/**
+* Deep merge two objects or arrays.
+*
+* Features:
+* * All objects will be cloned before merging.
+* * Merging order is from right to left.
+* * If an array include same objects, it will be unique to one.
+*
+* ```ts
+* deepMerge({ a: 1 }, { a: 2 }) // { a: 2 }
+* deepMerge([1, 2], [2, 3]) // [1, 2, 3]
+* ```
+*/
+function deepMerge(...sources) {
+	let acc = Object.create(null);
+	for (const source of sources) if (Array.isArray(source)) {
+		if (!Array.isArray(acc)) acc = [];
+		acc = [...new Set(source.concat(...acc))];
+	} else if (shouldMerge(source)) for (const [key, value] of Object.entries(source)) {
+		let val;
+		if (shouldMerge(value)) val = deepMerge(acc[key], value);
+		else val = value;
+		acc = {
+			...acc,
+			[key]: val
+		};
+	}
+	return acc;
+}
+
+//#endregion
+//#region src/load_config.ts
+function isObject(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function createConfigError(filePath, keyPath, reason) {
+	return Error(`[loadConfig] Invalid faas.yaml ${filePath} at "${keyPath}": ${reason}`);
+}
+function validateServerConfig(filePath, staging, server) {
+	if (!isObject(server)) throw createConfigError(filePath, `${staging}.server`, "must be an object");
+	if (typeof server.root !== "undefined" && typeof server.root !== "string") throw createConfigError(filePath, `${staging}.server.root`, "must be a string");
+	if (typeof server.base !== "undefined" && typeof server.base !== "string") throw createConfigError(filePath, `${staging}.server.base`, "must be a string");
+}
+function validateFaasYaml(filePath, config) {
+	if (typeof config === "undefined" || config === null) return Object.create(null);
+	if (!isObject(config)) throw createConfigError(filePath, "<root>", "must be an object");
+	for (const staging in config) {
+		if (staging === "types") throw createConfigError(filePath, "types", "has been removed, move related settings out of faas.yaml");
+		const stageConfig = config[staging];
+		if (typeof stageConfig === "undefined" || stageConfig === null) continue;
+		if (!isObject(stageConfig)) throw createConfigError(filePath, staging, "must be an object");
+		if (Object.hasOwn(stageConfig, "types")) throw createConfigError(filePath, `${staging}.types`, "has been removed, move related settings out of faas.yaml");
+		if (Object.hasOwn(stageConfig, "server")) validateServerConfig(filePath, staging, stageConfig.server);
+	}
+	return config;
+}
+/**
+* Load configuration from faas.yaml
+*/
+var Config = class {
+	root;
+	filename;
+	origin;
+	defaults;
+	logger;
+	constructor(root, filename, logger) {
+		this.logger = new Logger(logger?.label ? `${logger.label}] [config` : "config");
+		this.root = root;
+		if (!this.root.endsWith(sep)) this.root += sep;
+		this.filename = filename;
+		this.logger.debug("load %s in %s", filename, root);
+		const configs = [];
+		[this.root, "."].concat(dirname(filename.replace(root, "")).split(sep)).reduce((base, path) => {
+			const root = join(base, path);
+			if (root === base) return base;
+			const faas = join(root, "faas.yaml");
+			if (existsSync(faas)) configs.push(validateFaasYaml(faas, load(readFileSync(faas).toString())));
+			return root;
+		});
+		this.origin = deepMerge(...configs);
+		this.defaults = deepMerge(this.origin.defaults || {});
+		for (const key in this.origin) {
+			if (key !== "defaults") this[key] = deepMerge(this.defaults, this.origin[key]);
+			const data = this[key];
+			if (data.plugins) for (const pluginKey in data.plugins) {
+				const plugin = data.plugins[pluginKey];
+				plugin.name = pluginKey;
+			}
+		}
+	}
+	get(key) {
+		return this[key] || this.defaults || Object.create(null);
+	}
+};
+/**
+* Load configuration from faas.yaml
+*/
+function loadConfig(root, filename, staging, logger) {
+	return new Config(root, filename, logger).get(staging);
+}
+
+//#endregion
+//#region src/load_package.ts
+let _runtime = null;
+function resetRuntime() {
+	_runtime = null;
+}
+/**
+* Detect current JavaScript runtime environment.
+*
+* This function checks for presence of `require` first, then falls back to
+* Node.js ESM detection via `process.versions.node`.
+*
+* @returns {NodeRuntime} Returns `module` for ESM and `commonjs` for CJS.
+* @throws {Error} Throws an error if runtime cannot be determined.
+*/
+function detectNodeRuntime() {
+	if (_runtime) return _runtime;
+	if (typeof globalThis.require === "function" && typeof module !== "undefined") return _runtime = "commonjs";
+	if (typeof process !== "undefined" && process.versions?.node) return _runtime = "module";
+	throw Error("Unknown runtime");
+}
+/**
+* Asynchronously loads a package by its name, supporting both ESM and CJS.
+*
+* @template T The type of module to be loaded.
+* @param name The package name to load.
+* @param defaultNames Preferred export keys used to resolve default values.
+* @returns Loaded module or resolved default export.
+*/
+async function loadPackage(name, defaultNames = "default") {
+	const runtime = detectNodeRuntime();
+	let module;
+	if (runtime === "module") {
+		module = await import(name);
+		if (typeof defaultNames === "string") return defaultNames in module ? module[defaultNames] : module;
+		for (const key of defaultNames) if (key in module) return module[key];
+		return module;
+	}
+	if (runtime === "commonjs") {
+		module = globalThis.require(name);
+		if (typeof defaultNames === "string") return defaultNames in module ? module[defaultNames] : module;
+		for (const key of defaultNames) if (key in module) return module[key];
+		return module;
+	}
+	throw Error("Unknown runtime");
+}
+
+//#endregion
+//#region src/load_func.ts
+/**
+* Load a FaasJS function and its configuration, returning the handler.
+*
+* @param root Project root directory used to resolve configuration.
+* @param filename Path to the packaged FaasJS function file to load.
+* @param staging Staging directory name (used when locating config).
+* @returns A promise that resolves to the function handler.
+*
+* @example
+* ```ts
+* import { loadFunc } from '@faasjs/node-utils'
+*
+* const handler = await loadFunc(
+*   process.cwd(),
+*   __dirname + '/example.func.ts',
+*   'development'
+* )
+*
+* const result = await handler(event, context)
+* console.log(result)
+* ```
+*/
+async function loadFunc(root, filename, staging) {
+	const func = await loadPackage(filename);
+	func.config = await loadConfig(root, filename, staging);
+	return func.export().handler;
+}
+
+//#endregion
+//#region src/stream.ts
+/**
+* Convert ReadableStream to text.
+*
+* @throws {TypeError} If stream is not a ReadableStream instance.
+*/
+async function streamToText(stream) {
+	if (!(stream instanceof ReadableStream)) throw new TypeError("stream must be a ReadableStream instance");
+	return new Response(stream).text();
+}
+/**
+* Convert ReadableStream to object.
+*
+* @throws {TypeError} If stream is not a ReadableStream instance.
+*/
+async function streamToObject(stream) {
+	if (!(stream instanceof ReadableStream)) throw new TypeError("stream must be a ReadableStream instance");
+	return new Response(stream).json();
+}
+const streamToString = streamToText;
+
+//#endregion
+export { deepMerge, detectNodeRuntime, loadConfig, loadFunc, loadPackage, resetRuntime, streamToObject, streamToString, streamToText };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@faasjs/node-utils",
+  "version": "8.0.0-beta.7",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "homepage": "https://faasjs.com/doc/node-utils",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/faasjs/faasjs.git",
+    "directory": "packages/node-utils"
+  },
+  "bugs": {
+    "url": "https://github.com/faasjs/faasjs/issues"
+  },
+  "funding": "https://github.com/sponsors/faasjs",
+  "scripts": {
+    "build": "tsdown src/index.ts --config ../../tsdown.config.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@faasjs/func": ">=8.0.0-beta.7",
+    "@faasjs/logger": ">=8.0.0-beta.7",
+    "js-yaml": "*"
+  },
+  "devDependencies": {
+    "@faasjs/func": ">=8.0.0-beta.7",
+    "@faasjs/logger": ">=8.0.0-beta.7",
+    "@types/js-yaml": "*",
+    "js-yaml": "*"
+  },
+  "engines": {
+    "node": ">=24.0.0",
+    "npm": ">=11.0.0"
+  }
+}