@saasak/tool-env 1.0.2 → 1.2.0

package/src/utils-env.js

@@ -1,31 +1,71 @@
-import { decrypt, isEncrypted } from './utils-crypto.js';
+import { decrypt, isEncrypted } from "./utils-crypto.js";
 
-// ========================================
-// Helpers for core logic
-// ========================================
+/**
+ * Environment-specific values for a single variable.
+ * Keys are environment names (e.g. 'dev', 'production') or '@@' for the fallback.
+ * @typedef {Object.<string, string>} EnvVariableValue
+ */
 
+/**
+ * @typedef {Object.<string, EnvVariableValue>} EnvVariables
+ */
+
+/**
+ * @typedef {Object.<string, Object.<string, EnvVariableValue>>} EnvOverrides
+ */
+
+/**
+ * @typedef {Object} EnvConfig
+ * @property {string[]} [envs] - List of allowed environment names
+ * @property {EnvVariables} variables - Environment variables by name
+ * @property {EnvOverrides} [overrides] - Package-specific overrides
+ */
+
+/**
+ * @typedef {Object.<string, string>} EnvRecord
+ * Key-value pairs of environment variable name to value
+ */
+
+/**
+ * @typedef {Object.<string, EnvRecord>} AllEnvs
+ * Environment variables grouped by package name
+ */
+
+/**
+ * Build environment variables for all packages
+ * @param {string} secret - Secret for decrypting encrypted values
+ * @param {string} target - Target environment (e.g. 'dev', 'production')
+ * @param {EnvConfig} env - The env.json configuration object
+ * @param {string[]} names - List of package names to build env for
+ * @returns {AllEnvs} - Environment variables grouped by package name
+ */
 export function buildEnv(secret, target, env, names) {
 	const variablesForAllTargets = env.variables;
 	const overrides = env.overrides || {};
 
 	// For each variable, extract the value for the target env
-	const variables = Object.entries(variablesForAllTargets).reduce((acc, entry) => {
-		const [key, value] = entry;
-		return {
-			...acc,
-			[key]: extractValue(secret, value[target] || value['@@'] || '')
-		};
-	}, {});
+	/** @type {EnvRecord} */
+	const variables = Object.entries(variablesForAllTargets).reduce(
+		(acc, entry) => {
+			const [key, value] = entry;
+			return {
+				...acc,
+				[key]: extractValue(secret, value[target] || value["@@"] || ""),
+			};
+		},
+		{},
+	);
 
 	// For each package, get all variables
 	// compute the overrides and merge them
 	// allVars is an object with the package name as key
 	// and the variables as value like so
 	// => { [name]: { [variable]: value } }
+	/** @type {AllEnvs} */
 	const allVars = names.reduce((acc, name) => {
 		acc[name] = {
 			...variables,
-			...parseOverrides(secret, target, overrides[name], variables)
+			...parseOverrides(secret, target, overrides[name], variables),
 		};
 
 		return acc;
@@ -34,25 +74,42 @@ export function buildEnv(secret, target, env, names) {
 	return allVars;
 }
 
+/**
+ * Parse package-specific overrides for a target environment
+ * @param {string} secret - Secret for decrypting encrypted values
+ * @param {string} target - Target environment
+ * @param {Object.<string, EnvVariableValue>} overrides - Package overrides (may be undefined)
+ * @param {EnvRecord} vars - Base variables for reference substitution
+ * @returns {EnvRecord} - Parsed override values
+ */
 function parseOverrides(secret, target, overrides, vars) {
-	if (!secret) return {};
 	if (!overrides) return {};
 
 	return Object.entries(overrides).reduce((acc, entry) => {
 		const [key, val] = entry;
-		const value = extractValue(secret, val[target] || val['@@'] || '');
+		const value = extractValue(secret, val[target] || val["@@"] || "");
 
 		if (value === null) return acc;
 
 		acc[key] = Array.isArray(value)
-			? value.map(v => vars[v] || v).join('')
-			: value
+			? value
+					.map((v) =>
+						Object.prototype.hasOwnProperty.call(vars, v) ? vars[v] : v,
+					)
+					.join("")
+			: value;
 		return acc;
 	}, {});
 }
 
+/**
+ * Extract and decrypt a value if needed
+ * @param {string} secret - Secret for decryption
+ * @param {string} value - Value to extract (may be encrypted)
+ * @returns {string} - Decrypted/plain value, or empty string if no secret
+ */
 function extractValue(secret, value) {
 	if (!isEncrypted(value)) return value;
-	if (!secret) return '';
+	if (!secret) return "";
 	return decrypt(value, secret);
 }

package/src/utils-pkg.js

@@ -1,68 +1,85 @@
 import path from 'path';
 import fs from 'fs-extra';
 
-export async function findMonorepoPackages(rootDir, scope = null, maxDepth = 4) {
-	const packages = [];
-
-	async function processPackage(pkgPath, pkgDir) {
-		try {
-			const pkgContent = await fs.readFile(pkgPath, 'utf8');
-			const pkg = JSON.parse(pkgContent);
-
-			if (scope && !pkg.name?.startsWith(`${scope}/`)) {
-				return null;
-			}
-
-			return {
-				name: pkg.name,
-				dir: pkgDir,
-			};
-		} catch (err) {
+/**
+ * @typedef {Object} PackageInfo
+ * @property {string} name - Package name (e.g. '@scope/package-name')
+ * @property {string} dir - Absolute path to the package directory
+ */
+
+/**
+ * Try to read and parse a package.json, returning PackageInfo if valid and matches scope
+ * @param {string} dir - Directory containing package.json
+ * @param {string|null} scope - Package scope to filter by
+ * @returns {PackageInfo|null}
+ */
+function readPackageInfo(dir, scope) {
+	const pkgPath = path.join(dir, 'package.json');
+
+	try {
+		if (!fs.existsSync(pkgPath)) return null;
+
+		const pkg = fs.readJsonSync(pkgPath);
+
+		if (scope && !pkg.name?.startsWith(`${scope}/`)) {
 			return null;
 		}
-	}
-
-	async function traverse(dir, currentDepth = 0) {
-		if (currentDepth > maxDepth) return;
-
-		try {
-			const entries = await fs.readdir(dir, { withFileTypes: true });
-
-			for (const entry of entries) {
-				const fullPath = path.join(dir, entry.name);
-
-				if (entry.name === 'node_modules' || entry.isSymbolicLink()) {
-					continue;
-				}
-
-				if (!entry.isDirectory()) continue;
 
-				const pkgPath = path.join(fullPath, 'package.json');
-				const exists = await fs.pathExists(pkgPath);
-
-				if (exists) {
-					const pkg = await processPackage(pkgPath, fullPath);
-					packages.push(pkg);
-				}
-
-				await traverse(fullPath, currentDepth + 1);
-			}
-		} catch (err) {
-			return;
-		}
+		return { name: pkg.name, dir };
+	} catch {
+		return null;
 	}
+}
 
-	const rootPkgPath = path.join(rootDir, 'package.json');
-	const exists = await fs.pathExists(rootPkgPath);
-
-	if (!exists) return [];
+/**
+ * Get valid subdirectories (excluding node_modules and symlinks)
+ * @param {string} dir - Directory to list
+ * @returns {string[]} - Array of absolute paths to subdirectories
+ */
+function getSubdirectories(dir) {
+	try {
+		return fs
+			.readdirSync(dir, { withFileTypes: true })
+			.filter(
+				(entry) =>
+					entry.isDirectory() &&
+					!entry.isSymbolicLink() &&
+					entry.name !== 'node_modules'
+			)
+			.map((entry) => path.join(dir, entry.name));
+	} catch {
+		return [];
+	}
+}
 
-	const pkg = await processPackage(rootPkgPath, rootDir);
+/**
+ * Recursively collect packages from a directory tree
+ * @param {string} dir - Directory to search
+ * @param {string|null} scope - Package scope to filter by
+ * @param {number} depth - Remaining depth to traverse
+ * @returns {PackageInfo[]}
+ */
+function collectPackages(dir, scope, depth) {
+	if (depth < 0) return [];
+
+	return getSubdirectories(dir).flatMap((subdir) => {
+		const pkg = readPackageInfo(subdir, scope);
+		const nested = collectPackages(subdir, scope, depth - 1);
+		return pkg ? [pkg, ...nested] : nested;
+	});
+}
 
-	if (!pkg) return [];
+/**
+ * Find all packages in a monorepo by traversing the directory tree
+ * @param {string} rootDir - Root directory to start searching from
+ * @param {string|null} [scope=null] - Package scope to filter by (e.g. '@saasak')
+ * @param {number} [maxDepth=4] - Maximum directory depth to traverse
+ * @returns {PackageInfo[]} - Array of found packages (root package first, no nulls)
+ */
+export function findMonorepoPackages(rootDir, scope = null, maxDepth = 4) {
+	const rootPkg = readPackageInfo(rootDir, scope);
 
-	packages.push(pkg);
-	await traverse(rootDir, 0);
+	if (!rootPkg) return [];
 
-	return packages;
+	return [rootPkg, ...collectPackages(rootDir, scope, maxDepth)];
 }