@augment-vir/node 31.2.1 → 31.3.0

package/dist/augments/path/ancestor.d.ts

@@ -1,6 +1,31 @@
 import { type MaybePromise } from '@augment-vir/common';
-export declare function findAncestor(currentPath: string, callback: (path: string) => Promise<boolean>): Promise<string | undefined>;
-export declare function findAncestor(currentPath: string, callback: (path: string) => boolean): string | undefined;
+/**
+ * Find an ancestor file path that matches the given `callback`. If no matches are found all the way
+ * up until the system root, this returns `undefined`.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function findAncestor(currentPath: string, callback: (path: string) => Promise<boolean>): Promise<string | undefined>; /**
+ * Find an ancestor file path that matches the given `callback`. If no matches are found all the
+ * way up until the system root, this returns `undefined`.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function findAncestor(currentPath: string, callback: (path: string) => boolean): string | undefined; /**
+ * Find an ancestor file path that matches the given `callback`. If no matches are found all the
+ * way up until the system root, this returns `undefined`.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export declare function findAncestor(currentPath: string, callback: (path: string) => MaybePromise<boolean>): MaybePromise<string | undefined>;
 /**
  * Join a list of paths to the given `parentDirPath`. This is particularly useful for getting full

package/dist/augments/path/resolve-import.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Determines the path that will be imported into the given `startingPoint` from the given
+ * `importPath`. Resolves symlinks, tries to map `.js` extensions to `.ts` extensions when needed,
+ * and tries to find the best `node_modules` import for package imports.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function resolveImportPath(importerFilePath: string, importPath: string): string | undefined;

package/dist/augments/path/resolve-import.js

@@ -0,0 +1,78 @@
+import { check } from '@augment-vir/assert';
+import { filterMap, getObjectTypedEntries } from '@augment-vir/common';
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { readTsconfig } from '../typescript/read-tsconfig.js';
+import { findAncestor } from './ancestor.js';
+import { replaceWithWindowsPathIfNeeded } from './os-path.js';
+/**
+ * Determines the path that will be imported into the given `startingPoint` from the given
+ * `importPath`. Resolves symlinks, tries to map `.js` extensions to `.ts` extensions when needed,
+ * and tries to find the best `node_modules` import for package imports.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function resolveImportPath(importerFilePath, importPath) {
+    const foundTsconfig = readTsconfig(importerFilePath);
+    const mappedImportPath = foundTsconfig
+        ? mapImportPath(importPath, foundTsconfig.tsconfig, foundTsconfig.path)
+        : importPath;
+    if (mappedImportPath.startsWith(sep) || mappedImportPath.startsWith('/')) {
+        /** Absolute import */
+        return mapFilePath(replaceWithWindowsPathIfNeeded(mappedImportPath));
+    }
+    else if (mappedImportPath.startsWith('.')) {
+        /** Relative import */
+        return mapFilePath(resolve(dirname(importerFilePath), replaceWithWindowsPathIfNeeded(mappedImportPath)));
+    }
+    else {
+        /** Package import */
+        const isOrgPackage = mappedImportPath.startsWith('@');
+        const importPathParts = mappedImportPath.split('/');
+        const packagePath = isOrgPackage
+            ? join(...importPathParts.slice(0, 2))
+            : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                importPathParts[0];
+        const relevantNodeModulesParent = findAncestor(importerFilePath, (ancestorPath) => {
+            const isMatch = existsSync(join(ancestorPath, 'node_modules', packagePath));
+            return isMatch;
+        });
+        if (!relevantNodeModulesParent) {
+            return undefined;
+        }
+        return mapFilePath(join(relevantNodeModulesParent, 'node_modules', replaceWithWindowsPathIfNeeded(mappedImportPath)));
+    }
+}
+function mapFilePath(path) {
+    if (existsSync(path)) {
+        return realpathSync(path);
+    }
+    const tsPath = path.replace(/\.js$/, '.ts');
+    if (path.endsWith('.js') && existsSync(tsPath)) {
+        return realpathSync(tsPath);
+    }
+    return path;
+}
+function mapImportPath(importPath, tsconfig, tsconfigPath) {
+    const paths = tsconfig.options.paths;
+    if (!paths) {
+        return importPath;
+    }
+    const mappedPaths = filterMap(getObjectTypedEntries(paths), ([alias, paths]) => {
+        const aliasRegex = new RegExp('^' + String(alias).replace(/\*/g, '(.*)') + '$');
+        const match = importPath.match(aliasRegex);
+        if (!match) {
+            return undefined;
+        }
+        /** An empty paths is invalid anyway. */
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        return paths[0].replace(/\*/g, match[1]);
+    }, check.isTruthy);
+    if (!mappedPaths[0]) {
+        return importPath;
+    }
+    return resolve(tsconfig.options.baseUrl || dirname(tsconfigPath), mappedPaths[0]);
+}

package/dist/augments/typescript/read-tsconfig.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Finds the closest `tsconfig.json` file and parses it.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no tsconfig was found or if a found tsconfig fails to parse.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export declare function readTsconfig(startingPath: string): {
+    tsconfig: import("typescript").ParsedCommandLine;
+    path: string;
+} | undefined;

package/dist/augments/typescript/read-tsconfig.js

@@ -0,0 +1,32 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { parseJsonConfigFileContent, readConfigFile, sys } from 'typescript';
+import { findAncestor } from '../path/ancestor.js';
+/**
+ * Finds the closest `tsconfig.json` file and parses it.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no tsconfig was found or if a found tsconfig fails to parse.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function readTsconfig(startingPath) {
+    const tsconfigDirPath = findAncestor(startingPath, (ancestorPath) => existsSync(join(ancestorPath, 'tsconfig.json')));
+    const tsconfigPath = tsconfigDirPath ? join(tsconfigDirPath, 'tsconfig.json') : undefined;
+    if (!tsconfigPath) {
+        return undefined;
+    }
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    const { config, error } = readConfigFile(tsconfigPath, sys.readFile);
+    if (error) {
+        return undefined;
+    }
+    const parsedConfig = parseJsonConfigFileContent(config, sys, dirname(tsconfigPath));
+    if (parsedConfig.errors.length) {
+        return undefined;
+    }
+    return {
+        tsconfig: parsedConfig,
+        path: tsconfigPath,
+    };
+}

package/dist/index.d.ts

@@ -11,9 +11,11 @@ export * from './augments/npm/read-package-json.js';
 export * from './augments/os/operating-system.js';
 export * from './augments/path/ancestor.js';
 export * from './augments/path/os-path.js';
+export * from './augments/path/resolve-import.js';
 export * from './augments/path/root.js';
 export * from './augments/prisma.js';
 export * from './augments/terminal/question.js';
 export * from './augments/terminal/relevant-args.js';
 export * from './augments/terminal/run-cli-script.js';
 export * from './augments/terminal/shell.js';
+export * from './augments/typescript/read-tsconfig.js';

package/dist/index.js

@@ -11,9 +11,11 @@ export * from './augments/npm/read-package-json.js';
 export * from './augments/os/operating-system.js';
 export * from './augments/path/ancestor.js';
 export * from './augments/path/os-path.js';
+export * from './augments/path/resolve-import.js';
 export * from './augments/path/root.js';
 export * from './augments/prisma.js';
 export * from './augments/terminal/question.js';
 export * from './augments/terminal/relevant-args.js';
 export * from './augments/terminal/run-cli-script.js';
 export * from './augments/terminal/shell.js';
+export * from './augments/typescript/read-tsconfig.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/node",
-    "version": "31.2.1",
+    "version": "31.3.0",
     "description": "A collection of augments, helpers types, functions, and classes only for Node.js (backend) JavaScript environments.",
     "keywords": [
         "augment",
@@ -37,27 +37,31 @@
         "test:update": "npm test"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.2.1",
-        "@augment-vir/common": "^31.2.1",
-        "@date-vir/duration": "^7.0.1",
+        "@augment-vir/assert": "^31.3.0",
+        "@augment-vir/common": "^31.3.0",
+        "@date-vir/duration": "^7.1.1",
         "ansi-styles": "^6.2.1",
         "terminate": "^2.8.0",
-        "type-fest": "^4.29.0",
+        "type-fest": "^4.31.0",
         "typed-event-target": "^4.0.2"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.2.1",
-        "@prisma/client": "^5.22.0",
-        "@types/node": "^22.10.0",
+        "@augment-vir/test": "^31.3.0",
+        "@prisma/client": "^6.1.0",
+        "@types/node": "^22.10.2",
         "@web/dev-server-esbuild": "^1.0.3",
         "@web/test-runner": "^0.19.0",
         "@web/test-runner-commands": "^0.9.0",
         "@web/test-runner-playwright": "^0.11.0",
         "@web/test-runner-visual-regression": "^0.10.0",
-        "c8": "^10.1.2",
-        "concurrently": "^9.1.0",
+        "c8": "^10.1.3",
+        "concurrently": "^9.1.2",
         "istanbul-smart-text-reporter": "^1.1.5",
-        "prisma": "^5.22.0"
+        "prisma": "^6.1.0",
+        "typescript": "^5.7.2"
+    },
+    "peerDependencies": {
+        "typescript": "*"
     },
     "engines": {
         "node": ">=22"

package/src/augments/path/ancestor.ts

@@ -3,14 +3,39 @@ import {type MaybePromise} from '@augment-vir/common';
 import {dirname, join} from 'node:path';
 import {systemRootPath} from './root.js';
 
+/**
+ * Find an ancestor file path that matches the given `callback`. If no matches are found all the way
+ * up until the system root, this returns `undefined`.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export function findAncestor(
     currentPath: string,
     callback: (path: string) => Promise<boolean>,
-): Promise<string | undefined>;
+): Promise<string | undefined>; /**
+ * Find an ancestor file path that matches the given `callback`. If no matches are found all the
+ * way up until the system root, this returns `undefined`.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export function findAncestor(
     currentPath: string,
     callback: (path: string) => boolean,
-): string | undefined;
+): string | undefined; /**
+ * Find an ancestor file path that matches the given `callback`. If no matches are found all the
+ * way up until the system root, this returns `undefined`.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
 export function findAncestor(
     currentPath: string,
     callback: (path: string) => MaybePromise<boolean>,

package/src/augments/path/resolve-import.ts

@@ -0,0 +1,116 @@
+import {check} from '@augment-vir/assert';
+import {filterMap, getObjectTypedEntries} from '@augment-vir/common';
+import {existsSync, realpathSync} from 'node:fs';
+import {dirname, join, resolve, sep} from 'node:path';
+import {ParsedCommandLine} from 'typescript';
+import {readTsconfig} from '../typescript/read-tsconfig.js';
+import {findAncestor} from './ancestor.js';
+import {replaceWithWindowsPathIfNeeded} from './os-path.js';
+
+/**
+ * Determines the path that will be imported into the given `startingPoint` from the given
+ * `importPath`. Resolves symlinks, tries to map `.js` extensions to `.ts` extensions when needed,
+ * and tries to find the best `node_modules` import for package imports.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no matches are found.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function resolveImportPath(
+    importerFilePath: string,
+    importPath: string,
+): string | undefined {
+    const foundTsconfig = readTsconfig(importerFilePath);
+
+    const mappedImportPath = foundTsconfig
+        ? mapImportPath(importPath, foundTsconfig.tsconfig, foundTsconfig.path)
+        : importPath;
+
+    if (mappedImportPath.startsWith(sep) || mappedImportPath.startsWith('/')) {
+        /** Absolute import */
+
+        return mapFilePath(replaceWithWindowsPathIfNeeded(mappedImportPath));
+    } else if (mappedImportPath.startsWith('.')) {
+        /** Relative import */
+        return mapFilePath(
+            resolve(dirname(importerFilePath), replaceWithWindowsPathIfNeeded(mappedImportPath)),
+        );
+    } else {
+        /** Package import */
+
+        const isOrgPackage = mappedImportPath.startsWith('@');
+        const importPathParts = mappedImportPath.split('/');
+
+        const packagePath: string = isOrgPackage
+            ? join(...importPathParts.slice(0, 2))
+            : // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+              importPathParts[0]!;
+
+        const relevantNodeModulesParent = findAncestor(importerFilePath, (ancestorPath) => {
+            const isMatch = existsSync(join(ancestorPath, 'node_modules', packagePath));
+
+            return isMatch;
+        });
+
+        if (!relevantNodeModulesParent) {
+            return undefined;
+        }
+
+        return mapFilePath(
+            join(
+                relevantNodeModulesParent,
+                'node_modules',
+                replaceWithWindowsPathIfNeeded(mappedImportPath),
+            ),
+        );
+    }
+}
+
+function mapFilePath(path: string): string {
+    if (existsSync(path)) {
+        return realpathSync(path);
+    }
+
+    const tsPath = path.replace(/\.js$/, '.ts');
+
+    if (path.endsWith('.js') && existsSync(tsPath)) {
+        return realpathSync(tsPath);
+    }
+
+    return path;
+}
+
+function mapImportPath(
+    importPath: string,
+    tsconfig: ParsedCommandLine,
+    tsconfigPath: string,
+): string {
+    const paths = tsconfig.options.paths;
+    if (!paths) {
+        return importPath;
+    }
+
+    const mappedPaths = filterMap(
+        getObjectTypedEntries(paths),
+        ([alias, paths]) => {
+            const aliasRegex = new RegExp('^' + String(alias).replace(/\*/g, '(.*)') + '$');
+            const match = importPath.match(aliasRegex);
+
+            if (!match) {
+                return undefined;
+            }
+
+            /** An empty paths is invalid anyway. */
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            return paths[0]!.replace(/\*/g, match[1]!);
+        },
+        check.isTruthy,
+    );
+
+    if (!mappedPaths[0]) {
+        return importPath;
+    }
+
+    return resolve(tsconfig.options.baseUrl || dirname(tsconfigPath), mappedPaths[0]);
+}

package/src/augments/typescript/read-tsconfig.ts

@@ -0,0 +1,41 @@
+import {existsSync} from 'node:fs';
+import {dirname, join} from 'node:path';
+import {parseJsonConfigFileContent, readConfigFile, sys} from 'typescript';
+import {findAncestor} from '../path/ancestor.js';
+
+/**
+ * Finds the closest `tsconfig.json` file and parses it.
+ *
+ * @category Path : Node
+ * @category Package : @augment-vir/node
+ * @returns `undefined` if no tsconfig was found or if a found tsconfig fails to parse.
+ * @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
+ */
+export function readTsconfig(startingPath: string) {
+    const tsconfigDirPath = findAncestor(startingPath, (ancestorPath) =>
+        existsSync(join(ancestorPath, 'tsconfig.json')),
+    );
+    const tsconfigPath = tsconfigDirPath ? join(tsconfigDirPath, 'tsconfig.json') : undefined;
+
+    if (!tsconfigPath) {
+        return undefined;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    const {config, error} = readConfigFile(tsconfigPath, sys.readFile);
+
+    if (error) {
+        return undefined;
+    }
+
+    const parsedConfig = parseJsonConfigFileContent(config, sys, dirname(tsconfigPath));
+
+    if (parsedConfig.errors.length) {
+        return undefined;
+    }
+
+    return {
+        tsconfig: parsedConfig,
+        path: tsconfigPath,
+    };
+}

package/src/index.ts

@@ -11,9 +11,11 @@ export * from './augments/npm/read-package-json.js';
 export * from './augments/os/operating-system.js';
 export * from './augments/path/ancestor.js';
 export * from './augments/path/os-path.js';
+export * from './augments/path/resolve-import.js';
 export * from './augments/path/root.js';
 export * from './augments/prisma.js';
 export * from './augments/terminal/question.js';
 export * from './augments/terminal/relevant-args.js';
 export * from './augments/terminal/run-cli-script.js';
 export * from './augments/terminal/shell.js';
+export * from './augments/typescript/read-tsconfig.js';