@augment-vir/node 31.44.0 → 31.45.0

package/dist/augments/npm/npm-deps.d.ts

@@ -0,0 +1,38 @@
+/**
+ * All `package.json` keys that are parsed as direct dependencies.
+ *
+ * @category Internal
+ */
+export declare enum PackageJsonDependencyKey {
+    DevDependencies = "devDependencies",
+    Dependencies = "dependencies",
+    PeerDependencies = "peerDependencies"
+}
+/**
+ * A record of package names to package versions included in the direct dependencies. This is the
+ * output from {@link listAllDirectNpmDeps}.
+ *
+ * @category Internal
+ */
+export type NpmDeps = Record<string, NpmDep[]>;
+export type NpmDep = {
+    /** Path to the `package.json` file that depends on this. */
+    requiredBy: string;
+    dependencyKey: PackageJsonDependencyKey;
+    /**
+     * The version as it is directly noted in the `package.json` file. This might not necessarily
+     * correlate to any actually published versions.
+     */
+    versionValue: string;
+    /** If true, this dependency is part of the workspace's own packages. */
+    isWorkspace: boolean;
+};
+/**
+ * Finds all direct deps for the workspace at, or that contains, the given dir path.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws If no directory with a `package-lock.json` file is found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function listAllDirectNpmDeps(startDirPath: string): Promise<NpmDeps>;

package/dist/augments/npm/npm-deps.js

@@ -0,0 +1,47 @@
+import { check } from '@augment-vir/assert';
+import { filterMap, getEnumValues, getObjectTypedEntries, getOrSet } from '@augment-vir/common';
+import { readJsonFile } from '../fs/json.js';
+import { findAllPackageJsonFilePaths } from './package-json.js';
+/**
+ * All `package.json` keys that are parsed as direct dependencies.
+ *
+ * @category Internal
+ */
+export var PackageJsonDependencyKey;
+(function (PackageJsonDependencyKey) {
+    PackageJsonDependencyKey["DevDependencies"] = "devDependencies";
+    PackageJsonDependencyKey["Dependencies"] = "dependencies";
+    PackageJsonDependencyKey["PeerDependencies"] = "peerDependencies";
+})(PackageJsonDependencyKey || (PackageJsonDependencyKey = {}));
+/**
+ * Finds all direct deps for the workspace at, or that contains, the given dir path.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws If no directory with a `package-lock.json` file is found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function listAllDirectNpmDeps(startDirPath) {
+    const packageJsonFilePaths = await findAllPackageJsonFilePaths(startDirPath);
+    const deps = {};
+    const packageJsonFiles = await Promise.all(packageJsonFilePaths.map(async (packageJsonFilePath) => {
+        return {
+            packageJsonFilePath,
+            packageJson: (await readJsonFile(packageJsonFilePath)),
+        };
+    }));
+    const allWorkspacePackageNames = filterMap(packageJsonFiles, (packageJsonFile) => packageJsonFile.packageJson.name, check.isTruthy);
+    packageJsonFiles.forEach(({ packageJson, packageJsonFilePath }) => {
+        getEnumValues(PackageJsonDependencyKey).forEach((dependencyKey) => {
+            getObjectTypedEntries(packageJson[dependencyKey] || {}).forEach(([dependencyName, versionValue,]) => {
+                getOrSet(deps, dependencyName, () => []).push({
+                    dependencyKey,
+                    requiredBy: packageJsonFilePath,
+                    versionValue,
+                    isWorkspace: allWorkspacePackageNames.includes(dependencyName),
+                });
+            });
+        });
+    });
+    return deps;
+}

package/dist/augments/npm/package-json.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Finds all `package.json` files contained within the workspaces present in the current
+ * `startDirPath`. A workspace root dir is found by recursively looking for a parent
+ * `package-lock.json` file.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws If no directory with a `package-lock.json` file is found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function findAllPackageJsonFilePaths(startDirPath: string): Promise<string[]>;
+/**
+ * Get all workspace package.json paths starting at the given directory path. The output is string
+ * sorted to keep it stable.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws Error if there is no `package.json` file at the given `rootDirPath`.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function getWorkspacePackageJsonFilePaths(rootDirPath: string): Promise<string[]>;

package/dist/augments/npm/package-json.js

@@ -0,0 +1,48 @@
+import { check } from '@augment-vir/assert';
+import { filterMap, fromAsyncIterable } from '@augment-vir/common';
+import { existsSync } from 'node:fs';
+import { glob, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { findAncestor, joinFilesToDir } from '../path/ancestor.js';
+/**
+ * Finds all `package.json` files contained within the workspaces present in the current
+ * `startDirPath`. A workspace root dir is found by recursively looking for a parent
+ * `package-lock.json` file.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws If no directory with a `package-lock.json` file is found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function findAllPackageJsonFilePaths(startDirPath) {
+    const packageRootDir = findAncestor(startDirPath, (dir) => existsSync(join(dir, 'package-lock.json')));
+    if (!packageRootDir) {
+        throw new Error(`Cannot find all package.json files: failed to find any directory with a package-lock.json file. Started at '${startDirPath}'.`);
+    }
+    const rootPackageJsonPath = join(packageRootDir, 'package.json');
+    return [
+        rootPackageJsonPath,
+        ...(await getWorkspacePackageJsonFilePaths(packageRootDir)),
+    ];
+}
+/**
+ * Get all workspace package.json paths starting at the given directory path. The output is string
+ * sorted to keep it stable.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws Error if there is no `package.json` file at the given `rootDirPath`.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function getWorkspacePackageJsonFilePaths(rootDirPath) {
+    const packageJson = JSON.parse(await readFile(join(rootDirPath, 'package.json'), 'utf8'));
+    /* node:coverage ignore next 3: this package only uses one type of workspace */
+    const patterns = check.isArray(packageJson.workspaces)
+        ? packageJson.workspaces
+        : packageJson.workspaces?.packages || [];
+    const matchedPaths = joinFilesToDir(rootDirPath, (await Promise.all(patterns.map(async (pattern) => {
+        return await fromAsyncIterable(glob(pattern, { cwd: rootDirPath }));
+    }))).flat());
+    const workspacePackageJsonPaths = filterMap(matchedPaths, (matchedPath) => join(matchedPath, 'package.json'), (packageJsonPath) => existsSync(packageJsonPath));
+    return workspacePackageJsonPaths.sort();
+}

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export * from './augments/fs/read-file.js';
 export * from './augments/fs/symlink.js';
 export * from './augments/fs/write.js';
 export * from './augments/npm/find-bin-path.js';
+export * from './augments/npm/npm-deps.js';
+export * from './augments/npm/package-json.js';
 export * from './augments/npm/query-workspace.js';
 export * from './augments/npm/read-package-json.js';
 export * from './augments/os/operating-system.js';

package/dist/index.js

@@ -6,6 +6,8 @@ export * from './augments/fs/read-file.js';
 export * from './augments/fs/symlink.js';
 export * from './augments/fs/write.js';
 export * from './augments/npm/find-bin-path.js';
+export * from './augments/npm/npm-deps.js';
+export * from './augments/npm/package-json.js';
 export * from './augments/npm/query-workspace.js';
 export * from './augments/npm/read-package-json.js';
 export * from './augments/os/operating-system.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/node",
-    "version": "31.44.0",
+    "version": "31.45.0",
     "description": "A collection of augments, helpers types, functions, and classes only for Node.js (backend) JavaScript environments.",
     "keywords": [
         "augment",
@@ -38,8 +38,8 @@
         "test:update": "npm test"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.44.0",
-        "@augment-vir/common": "^31.44.0",
+        "@augment-vir/assert": "^31.45.0",
+        "@augment-vir/common": "^31.45.0",
         "@date-vir/duration": "^8.0.0",
         "ansi-styles": "^6.2.3",
         "sanitize-filename": "^1.6.3",
@@ -49,7 +49,7 @@
         "typed-event-target": "^4.1.0"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.44.0",
+        "@augment-vir/test": "^31.45.0",
         "@types/node": "^24.9.1",
         "@web/dev-server-esbuild": "^1.0.4",
         "@web/test-runner": "^0.20.2",

package/src/augments/npm/npm-deps.ts

@@ -0,0 +1,85 @@
+import {check} from '@augment-vir/assert';
+import {filterMap, getEnumValues, getObjectTypedEntries, getOrSet} from '@augment-vir/common';
+import {type PackageJson} from 'type-fest';
+import {readJsonFile} from '../fs/json.js';
+import {findAllPackageJsonFilePaths} from './package-json.js';
+
+/**
+ * All `package.json` keys that are parsed as direct dependencies.
+ *
+ * @category Internal
+ */
+export enum PackageJsonDependencyKey {
+    DevDependencies = 'devDependencies',
+    Dependencies = 'dependencies',
+    PeerDependencies = 'peerDependencies',
+}
+
+/**
+ * A record of package names to package versions included in the direct dependencies. This is the
+ * output from {@link listAllDirectNpmDeps}.
+ *
+ * @category Internal
+ */
+export type NpmDeps = Record<string, NpmDep[]>;
+export type NpmDep = {
+    /** Path to the `package.json` file that depends on this. */
+    requiredBy: string;
+    dependencyKey: PackageJsonDependencyKey;
+    /**
+     * The version as it is directly noted in the `package.json` file. This might not necessarily
+     * correlate to any actually published versions.
+     */
+    versionValue: string;
+    /** If true, this dependency is part of the workspace's own packages. */
+    isWorkspace: boolean;
+};
+
+/**
+ * Finds all direct deps for the workspace at, or that contains, the given dir path.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws If no directory with a `package-lock.json` file is found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function listAllDirectNpmDeps(startDirPath: string): Promise<NpmDeps> {
+    const packageJsonFilePaths = await findAllPackageJsonFilePaths(startDirPath);
+
+    const deps: NpmDeps = {};
+
+    const packageJsonFiles = await Promise.all(
+        packageJsonFilePaths.map(async (packageJsonFilePath) => {
+            return {
+                packageJsonFilePath,
+                packageJson: (await readJsonFile(packageJsonFilePath)) as PackageJson,
+            };
+        }),
+    );
+
+    const allWorkspacePackageNames = filterMap(
+        packageJsonFiles,
+        (packageJsonFile) => packageJsonFile.packageJson.name,
+        check.isTruthy,
+    );
+
+    packageJsonFiles.forEach(({packageJson, packageJsonFilePath}) => {
+        getEnumValues(PackageJsonDependencyKey).forEach((dependencyKey) => {
+            getObjectTypedEntries(packageJson[dependencyKey] || {}).forEach(
+                ([
+                    dependencyName,
+                    versionValue,
+                ]) => {
+                    getOrSet(deps, dependencyName, () => []).push({
+                        dependencyKey,
+                        requiredBy: packageJsonFilePath,
+                        versionValue,
+                        isWorkspace: allWorkspacePackageNames.includes(dependencyName),
+                    });
+                },
+            );
+        });
+    });
+
+    return deps;
+}

package/src/augments/npm/package-json.ts

@@ -0,0 +1,75 @@
+import {check} from '@augment-vir/assert';
+import {filterMap, fromAsyncIterable} from '@augment-vir/common';
+import {existsSync} from 'node:fs';
+import {glob, readFile} from 'node:fs/promises';
+import {join} from 'node:path';
+import {type PackageJson} from 'type-fest';
+import {findAncestor, joinFilesToDir} from '../path/ancestor.js';
+
+/**
+ * Finds all `package.json` files contained within the workspaces present in the current
+ * `startDirPath`. A workspace root dir is found by recursively looking for a parent
+ * `package-lock.json` file.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws If no directory with a `package-lock.json` file is found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function findAllPackageJsonFilePaths(startDirPath: string) {
+    const packageRootDir = findAncestor(startDirPath, (dir) =>
+        existsSync(join(dir, 'package-lock.json')),
+    );
+
+    if (!packageRootDir) {
+        throw new Error(
+            `Cannot find all package.json files: failed to find any directory with a package-lock.json file. Started at '${startDirPath}'.`,
+        );
+    }
+
+    const rootPackageJsonPath = join(packageRootDir, 'package.json');
+
+    return [
+        rootPackageJsonPath,
+        ...(await getWorkspacePackageJsonFilePaths(packageRootDir)),
+    ];
+}
+
+/**
+ * Get all workspace package.json paths starting at the given directory path. The output is string
+ * sorted to keep it stable.
+ *
+ * @category Node : Npm
+ * @category Package : @augment-vir/node
+ * @throws Error if there is no `package.json` file at the given `rootDirPath`.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export async function getWorkspacePackageJsonFilePaths(rootDirPath: string): Promise<string[]> {
+    const packageJson: PackageJson = JSON.parse(
+        await readFile(join(rootDirPath, 'package.json'), 'utf8'),
+    );
+
+    /* node:coverage ignore next 3: this package only uses one type of workspace */
+    const patterns = check.isArray(packageJson.workspaces)
+        ? packageJson.workspaces
+        : packageJson.workspaces?.packages || [];
+
+    const matchedPaths: string[] = joinFilesToDir(
+        rootDirPath,
+        (
+            await Promise.all(
+                patterns.map(async (pattern) => {
+                    return await fromAsyncIterable(glob(pattern, {cwd: rootDirPath}));
+                }),
+            )
+        ).flat(),
+    );
+
+    const workspacePackageJsonPaths = filterMap(
+        matchedPaths,
+        (matchedPath) => join(matchedPath, 'package.json'),
+        (packageJsonPath) => existsSync(packageJsonPath),
+    );
+
+    return workspacePackageJsonPaths.sort();
+}

package/src/index.ts

@@ -6,6 +6,8 @@ export * from './augments/fs/read-file.js';
 export * from './augments/fs/symlink.js';
 export * from './augments/fs/write.js';
 export * from './augments/npm/find-bin-path.js';
+export * from './augments/npm/npm-deps.js';
+export * from './augments/npm/package-json.js';
 export * from './augments/npm/query-workspace.js';
 export * from './augments/npm/read-package-json.js';
 export * from './augments/os/operating-system.js';