@sorrell/utilities 1.2.5 → 1.2.6

package/Distribution/Types/Npm/Npm.Effect.d.mts

@@ -0,0 +1,92 @@
+/**
+ * @file      Npm.Effect.ts
+ * @author    Gage Sorrell <gage@sorrell.sh>
+ * @copyright (c) 2026 Gage Sorrell
+ * @license   MIT
+ */
+import type { EGetPackageJson, EGetPackageRootDirectory } from "./Npm.Effect.Types.mjs";
+/**
+ * Get the `package.json` of the Node.js project in which the
+ * given path, or the current working directory, resides.
+ *
+ * @param Path - The given path from which to look for a root directory.
+ *
+ * @returns {EGetPackageJson} An Effect that succeeds with the parsed `package.json`, or fails
+ * with {@link RootDirectoryNotFoundError} or {@link PackageJsonParseError}.
+ *
+ * @example
+ * Suppose `process.cwd() === "./MyPackage"`,
+ * ```typescript
+ * Effect.gen(function* ()
+ * {
+ *     const PackageJson: IPackageJson = yield* GetPackageJson();
+ *     // `PackageJson` <- *The parsed `package.json` of `MyPackage`.*
+ * }
+ * ```
+ */
+export declare function GetPackageJson(Path?: string): EGetPackageJson;
+/**
+ * Get the root directory of the Node.js project in which the
+ * current working directory resides.
+ *
+ * @param Path - *(Optional)* The given path from which to look for a root directory.
+ *
+ * @returns {EGetPackageRootDirectory} An Effect that succeeds with the package root
+ * directory, or fails with {@link RootDirectoryNotFoundError}.
+ *
+ * @example
+ * Suppose `process.cwd()` is any one of the following,
+ *   - `/home/alex/myPackage`,
+ *   - `/home/alex/myPackage/src/MyModule`,
+ *   - `/home/alex/myPackage/resource/Images`,
+ *
+ * then,
+ *
+ * ```typescript
+ * import { Effect } from "effect";
+ * const Root: string = await Effect.runPromise(GetPackageRootDirectory());
+ * // `Root` <- `"/home/alex/myPackage"`
+ * ```
+ *
+ * @example
+ * Suppose `TestPath === "/home/alex/Documents"` is *not* a NodeJS package root
+ * (of course, neither are `/home/alex` or `/home`).  Then,
+ *
+ * ```typescript
+ * import { Effect } from "effect";
+ * const TestPath: string = "/home/alex/Documents";
+ * let Root: string | undefined = undefined;
+ * try
+ * {
+ *     Root = await Effect.runPromise(
+ *         GetPackageRootDirectory(TestPath)
+ *     );
+ * }
+ * catch (Error: unknown)
+ * {
+ *      // `Error instanceof RootDirectoryNotFound`
+ * }
+ *
+ * // `Root` <- `undefined`
+ * ```
+ *
+ * @example
+ * Suppose `process.cwd() === /home/alex/Downloads`, which is *not* a NodeJS package
+ * (of course, neither are `/home/alex` or `/home`).  Then,
+ *
+ * ```typescript
+ * import { Effect } from "effect";
+ * let Root: string | undefined = undefined;
+ * try
+ * {
+ *     Root = await Effect.runPromise(GetPackageRootDirectory());
+ * }
+ * catch (Error: unknown)
+ * {
+ *      // `Error instanceof RootDirectoryNotFound`
+ * }
+ * // `Root` <- `undefined`
+ * ```
+ */
+export declare function GetPackageRootDirectory(Path?: string): EGetPackageRootDirectory;
+//# sourceMappingURL=Npm.Effect.d.mts.map

package/Distribution/Types/Npm/Npm.Effect.d.mts.map

@@ -0,0 +1,10 @@
+{
+    "version": 3,
+    "file": "Npm.Effect.d.mts",
+    "sourceRoot": "",
+    "sources": [
+        "../../../Source/Npm/Npm.Effect.ts"
+    ],
+    "names": [],
+    "mappings": "AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AASvF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,eAAe,CAyB7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,wBAAwB,CA6C/E"
+}

package/Distribution/Types/Npm/Npm.Effect.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @file      Npm.Effect.ts
+ * @author    Gage Sorrell <gage@sorrell.sh>
+ * @copyright (c) 2026 Gage Sorrell
+ * @license   MIT
+ */
+import type { EGetPackageJson, EGetPackageRootDirectory } from "./Npm.Effect.Types.ts";
+/**
+ * Get the `package.json` of the Node.js project in which the
+ * given path, or the current working directory, resides.
+ *
+ * @param Path - The given path from which to look for a root directory.
+ *
+ * @returns {EGetPackageJson} An Effect that succeeds with the parsed `package.json`, or fails
+ * with {@link RootDirectoryNotFoundError} or {@link PackageJsonParseError}.
+ *
+ * @example
+ * Suppose `process.cwd() === "./MyPackage"`,
+ * ```typescript
+ * Effect.gen(function* ()
+ * {
+ *     const PackageJson: IPackageJson = yield* GetPackageJson();
+ *     // `PackageJson` <- *The parsed `package.json` of `MyPackage`.*
+ * }
+ * ```
+ */
+export declare function GetPackageJson(Path?: string): EGetPackageJson;
+/**
+ * Get the root directory of the Node.js project in which the
+ * current working directory resides.
+ *
+ * @param Path - *(Optional)* The given path from which to look for a root directory.
+ *
+ * @returns {EGetPackageRootDirectory} An Effect that succeeds with the package root
+ * directory, or fails with {@link RootDirectoryNotFoundError}.
+ *
+ * @example
+ * Suppose `process.cwd()` is any one of the following,
+ *   - `/home/alex/myPackage`,
+ *   - `/home/alex/myPackage/src/MyModule`,
+ *   - `/home/alex/myPackage/resource/Images`,
+ *
+ * then,
+ *
+ * ```typescript
+ * import { Effect } from "effect";
+ * const Root: string = await Effect.runPromise(GetPackageRootDirectory());
+ * // `Root` <- `"/home/alex/myPackage"`
+ * ```
+ *
+ * @example
+ * Suppose `TestPath === "/home/alex/Documents"` is *not* a NodeJS package root
+ * (of course, neither are `/home/alex` or `/home`).  Then,
+ *
+ * ```typescript
+ * import { Effect } from "effect";
+ * const TestPath: string = "/home/alex/Documents";
+ * let Root: string | undefined = undefined;
+ * try
+ * {
+ *     Root = await Effect.runPromise(
+ *         GetPackageRootDirectory(TestPath)
+ *     );
+ * }
+ * catch (Error: unknown)
+ * {
+ *      // `Error instanceof RootDirectoryNotFound`
+ * }
+ *
+ * // `Root` <- `undefined`
+ * ```
+ *
+ * @example
+ * Suppose `process.cwd() === /home/alex/Downloads`, which is *not* a NodeJS package
+ * (of course, neither are `/home/alex` or `/home`).  Then,
+ *
+ * ```typescript
+ * import { Effect } from "effect";
+ * let Root: string | undefined = undefined;
+ * try
+ * {
+ *     Root = await Effect.runPromise(GetPackageRootDirectory());
+ * }
+ * catch (Error: unknown)
+ * {
+ *      // `Error instanceof RootDirectoryNotFound`
+ * }
+ * // `Root` <- `undefined`
+ * ```
+ */
+export declare function GetPackageRootDirectory(Path?: string): EGetPackageRootDirectory;
+//# sourceMappingURL=Npm.Effect.d.ts.map

package/Distribution/Types/Npm/Npm.Effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Npm.Effect.d.ts","sourceRoot":"","sources":["../../../Source/Npm/Npm.Effect.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AASvF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,eAAe,CAyB7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,wBAAwB,CA6C/E"}

package/Distribution/Types/Npm/Npm.Error.d.cts

@@ -0,0 +1,36 @@
+/**
+ * @file      Npm.Error.ts
+ * @author    Gage Sorrell <gage@sorrell.sh>
+ * @copyright (c) 2026 Gage Sorrell
+ * @license   MIT
+ */
+declare const PackageJsonParseError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "PackageJsonParseError";
+} & Readonly<A>;
+/**
+ * An error describing that {@link GetPackageJson} failed to parse the discovered `package.json` file.
+ *
+ * @property {string | undefined} Path - The `Path` argument passed to the effect returning this error,
+ * if one was given.
+ * @property {unknown} Cause - The cause of this error.
+ */
+export declare class PackageJsonParseError extends PackageJsonParseError_base<{
+    readonly Path: string | undefined;
+    readonly Cause: unknown;
+}> {
+}
+declare const RootDirectoryNotFoundError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "RootDirectoryNotFound";
+} & Readonly<A>;
+/**
+ * An error describing that {@link GetPackageRootDirectory} failed.
+ *
+ * @property {string | undefined} Path - The `Path` argument passed to the effect returning
+ * this error, if one was given.
+ */
+export declare class RootDirectoryNotFoundError extends RootDirectoryNotFoundError_base<{
+    readonly Path: string | undefined;
+}> {
+}
+export {};
+//# sourceMappingURL=Npm.Error.d.cts.map

package/Distribution/Types/Npm/Npm.Error.d.cts.map

@@ -0,0 +1,10 @@
+{
+    "version": 3,
+    "file": "Npm.Error.d.cts",
+    "sourceRoot": "",
+    "sources": [
+        "../../../Source/Npm/Npm.Error.ts"
+    ],
+    "names": [],
+    "mappings": "AAAA;;;;;GAKG;;;;AAIH;;;;;;GAMG;AACH,qBAAa,qBACT,SAAQ,2BAA0C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CAC3B,CAAC;CAAI;;;;AAEV;;;;;GAKG;AACH,qBAAa,0BACT,SAAQ,gCAA0C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC,CAAC;CAAI"
+}

package/Distribution/Types/Npm/Npm.Error.d.mts

@@ -0,0 +1,36 @@
+/**
+ * @file      Npm.Error.ts
+ * @author    Gage Sorrell <gage@sorrell.sh>
+ * @copyright (c) 2026 Gage Sorrell
+ * @license   MIT
+ */
+declare const PackageJsonParseError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "PackageJsonParseError";
+} & Readonly<A>;
+/**
+ * An error describing that {@link GetPackageJson} failed to parse the discovered `package.json` file.
+ *
+ * @property {string | undefined} Path - The `Path` argument passed to the effect returning this error,
+ * if one was given.
+ * @property {unknown} Cause - The cause of this error.
+ */
+export declare class PackageJsonParseError extends PackageJsonParseError_base<{
+    readonly Path: string | undefined;
+    readonly Cause: unknown;
+}> {
+}
+declare const RootDirectoryNotFoundError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "RootDirectoryNotFound";
+} & Readonly<A>;
+/**
+ * An error describing that {@link GetPackageRootDirectory} failed.
+ *
+ * @property {string | undefined} Path - The `Path` argument passed to the effect returning
+ * this error, if one was given.
+ */
+export declare class RootDirectoryNotFoundError extends RootDirectoryNotFoundError_base<{
+    readonly Path: string | undefined;
+}> {
+}
+export {};
+//# sourceMappingURL=Npm.Error.d.mts.map

package/Distribution/Types/Npm/Npm.Error.d.mts.map

@@ -0,0 +1,10 @@
+{
+    "version": 3,
+    "file": "Npm.Error.d.mts",
+    "sourceRoot": "",
+    "sources": [
+        "../../../Source/Npm/Npm.Error.ts"
+    ],
+    "names": [],
+    "mappings": "AAAA;;;;;GAKG;;;;AAIH;;;;;;GAMG;AACH,qBAAa,qBACT,SAAQ,2BAA0C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CAC3B,CAAC;CAAI;;;;AAEV;;;;;GAKG;AACH,qBAAa,0BACT,SAAQ,gCAA0C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC,CAAC;CAAI"
+}

package/Distribution/Types/Npm/Npm.Error.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file      Npm.Error.ts
+ * @author    Gage Sorrell <gage@sorrell.sh>
+ * @copyright (c) 2026 Gage Sorrell
+ * @license   MIT
+ */
+declare const PackageJsonParseError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "PackageJsonParseError";
+} & Readonly<A>;
+/**
+ * An error describing that {@link GetPackageJson} failed to parse the discovered `package.json` file.
+ *
+ * @property {string | undefined} Path - The `Path` argument passed to the effect returning this error,
+ * if one was given.
+ * @property {unknown} Cause - The cause of this error.
+ */
+export declare class PackageJsonParseError extends PackageJsonParseError_base<{
+    readonly Path: string | undefined;
+    readonly Cause: unknown;
+}> {
+}
+declare const RootDirectoryNotFoundError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "RootDirectoryNotFound";
+} & Readonly<A>;
+/**
+ * An error describing that {@link GetPackageRootDirectory} failed.
+ *
+ * @property {string | undefined} Path - The `Path` argument passed to the effect returning
+ * this error, if one was given.
+ */
+export declare class RootDirectoryNotFoundError extends RootDirectoryNotFoundError_base<{
+    readonly Path: string | undefined;
+}> {
+}
+export {};
+//# sourceMappingURL=Npm.Error.d.ts.map

package/Distribution/Types/Npm/Npm.Error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Npm.Error.d.ts","sourceRoot":"","sources":["../../../Source/Npm/Npm.Error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;;;;AAIH;;;;;;GAMG;AACH,qBAAa,qBACT,SAAQ,2BAA0C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CAC3B,CAAC;CAAI;;;;AAEV;;;;;GAKG;AACH,qBAAa,0BACT,SAAQ,gCAA0C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC,CAAC;CAAI"}

package/Distribution/Types/Npm/Npm.d.cts

@@ -0,0 +1,91 @@
+/**
+ * @file      Npm.ts
+ * @author    Gage Sorrell <gage@sorrell.sh>
+ * @copyright (c) 2026 Gage Sorrell
+ * @license   MIT
+ */
+import type { IPackageJson } from "package-json-type";
+/**
+ * Get the `package.json` of the Node.js project in which the
+ * given path, or the current working directory, resides.
+ *
+ * @param Path - The given path from which to look for a root directory.
+ *
+ * @throws {RootDirectoryNotFoundError | PackageJsonParseError} An error
+ * describing either failure to identify a root directory, or failing to
+ * parse the discovered `package.json`.
+ *
+ * @returns {Promise<IPackageJson>} The {@link IPackageJson} of {@link Path}
+ * if provided, otherwise of `process.cwd()`.
+ *
+ * @example
+ * Suppose `process.cwd() === "./MyPackage"`,
+ * ```typescript
+ * const PackageJson: IPackageJson = await GetPackageJson();
+ * // `PackageJson` <- *The parsed `package.json` of `MyPackage`.*
+ * ```
+ */
+export declare function GetPackageJson(Path?: string): Promise<IPackageJson>;
+/**
+ * Get the root directory of the Node.js project in which the
+ * current working directory resides.
+ *
+ * @param Path - The given path from which to look for a root directory.
+ *
+ * @throws {RootDirectoryNotFoundError} An error iff the root directory
+ * of a NodeJS package could not be found.
+ *
+ * @returns {Promise<string>} The path to the root directory of the package
+ * containing {@link Path} if specified, otherwise containing `process.cwd()`.
+ *
+ * @example
+ * Suppose `process.cwd()` is any one of the following,
+ *   - `/home/alex/myPackage`,
+ *   - `/home/alex/myPackage/src/MyModule`,
+ *   - `/home/alex/myPackage/resource/Images`,
+ *
+ * then,
+ *
+ * ```typescript
+ * const Root: string = await GetPackageRootDirectory();
+ * // `Root` <- `"/home/alex/myPackage"`
+ * ```
+ *
+ * @example
+ * Suppose `TestPath === "/home/alex/Documents"` is *not* a NodeJS package root
+ * (of course, neither are `/home/alex` or `/home`).  Then,
+ *
+ * ```typescript
+ * const TestPath: string = "/home/alex/Documents";
+ * let Root: string | undefined = undefined;
+ * try
+ * {
+ *     Root = await GetPackageRootDirectory(TestPath);
+ * }
+ * catch (Error: unknown)
+ * {
+ *      // `Error instanceof RootDirectoryNotFound`
+ * }
+ *
+ * // `Root` <- `undefined`
+ * ```
+ *
+ * @example
+ * Suppose `process.cwd() === /home/alex/Downloads`, which is *not* a NodeJS package
+ * (of course, neither are `/home/alex` or `/home`).  Then,
+ *
+ * ```typescript
+ * let Root: string | undefined = undefined;
+ * try
+ * {
+ *     Root = await GetPackageRootDirectory();
+ * }
+ * catch (Error: unknown)
+ * {
+ *      // `Error instanceof RootDirectoryNotFound`
+ * }
+ * // `Root` <- `undefined`
+ * ```
+ */
+export declare function GetPackageRootDirectory(Path?: string): Promise<string>;
+//# sourceMappingURL=Npm.d.cts.map

package/Distribution/Types/Npm/Npm.d.cts.map

@@ -0,0 +1,10 @@
+{
+    "version": 3,
+    "file": "Npm.d.cts",
+    "sourceRoot": "",
+    "sources": [
+        "../../../Source/Npm/Npm.ts"
+    ],
+    "names": [],
+    "mappings": "AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmC5E"
+}

package/Distribution/Types/Npm/Npm.d.mts

@@ -0,0 +1,91 @@
+/**
+ * @file      Npm.ts
+ * @author    Gage Sorrell <gage@sorrell.sh>
+ * @copyright (c) 2026 Gage Sorrell
+ * @license   MIT
+ */
+import type { IPackageJson } from "package-json-type";
+/**
+ * Get the `package.json` of the Node.js project in which the
+ * given path, or the current working directory, resides.
+ *
+ * @param Path - The given path from which to look for a root directory.
+ *
+ * @throws {RootDirectoryNotFoundError | PackageJsonParseError} An error
+ * describing either failure to identify a root directory, or failing to
+ * parse the discovered `package.json`.
+ *
+ * @returns {Promise<IPackageJson>} The {@link IPackageJson} of {@link Path}
+ * if provided, otherwise of `process.cwd()`.
+ *
+ * @example
+ * Suppose `process.cwd() === "./MyPackage"`,
+ * ```typescript
+ * const PackageJson: IPackageJson = await GetPackageJson();
+ * // `PackageJson` <- *The parsed `package.json` of `MyPackage`.*
+ * ```
+ */
+export declare function GetPackageJson(Path?: string): Promise<IPackageJson>;
+/**
+ * Get the root directory of the Node.js project in which the
+ * current working directory resides.
+ *
+ * @param Path - The given path from which to look for a root directory.
+ *
+ * @throws {RootDirectoryNotFoundError} An error iff the root directory
+ * of a NodeJS package could not be found.
+ *
+ * @returns {Promise<string>} The path to the root directory of the package
+ * containing {@link Path} if specified, otherwise containing `process.cwd()`.
+ *
+ * @example
+ * Suppose `process.cwd()` is any one of the following,
+ *   - `/home/alex/myPackage`,
+ *   - `/home/alex/myPackage/src/MyModule`,
+ *   - `/home/alex/myPackage/resource/Images`,
+ *
+ * then,
+ *
+ * ```typescript
+ * const Root: string = await GetPackageRootDirectory();
+ * // `Root` <- `"/home/alex/myPackage"`
+ * ```
+ *
+ * @example
+ * Suppose `TestPath === "/home/alex/Documents"` is *not* a NodeJS package root
+ * (of course, neither are `/home/alex` or `/home`).  Then,
+ *
+ * ```typescript
+ * const TestPath: string = "/home/alex/Documents";
+ * let Root: string | undefined = undefined;
+ * try
+ * {
+ *     Root = await GetPackageRootDirectory(TestPath);
+ * }
+ * catch (Error: unknown)
+ * {
+ *      // `Error instanceof RootDirectoryNotFound`
+ * }
+ *
+ * // `Root` <- `undefined`
+ * ```
+ *
+ * @example
+ * Suppose `process.cwd() === /home/alex/Downloads`, which is *not* a NodeJS package
+ * (of course, neither are `/home/alex` or `/home`).  Then,
+ *
+ * ```typescript
+ * let Root: string | undefined = undefined;
+ * try
+ * {
+ *     Root = await GetPackageRootDirectory();
+ * }
+ * catch (Error: unknown)
+ * {
+ *      // `Error instanceof RootDirectoryNotFound`
+ * }
+ * // `Root` <- `undefined`
+ * ```
+ */
+export declare function GetPackageRootDirectory(Path?: string): Promise<string>;
+//# sourceMappingURL=Npm.d.mts.map

package/Distribution/Types/Npm/Npm.d.mts.map

@@ -0,0 +1,10 @@
+{
+    "version": 3,
+    "file": "Npm.d.mts",
+    "sourceRoot": "",
+    "sources": [
+        "../../../Source/Npm/Npm.ts"
+    ],
+    "names": [],
+    "mappings": "AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmC5E"
+}

package/Distribution/Types/Npm/Npm.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @file      Npm.ts
+ * @author    Gage Sorrell <gage@sorrell.sh>
+ * @copyright (c) 2026 Gage Sorrell
+ * @license   MIT
+ */
+import type { IPackageJson } from "package-json-type";
+/**
+ * Get the `package.json` of the Node.js project in which the
+ * given path, or the current working directory, resides.
+ *
+ * @param Path - The given path from which to look for a root directory.
+ *
+ * @throws {RootDirectoryNotFoundError | PackageJsonParseError} An error
+ * describing either failure to identify a root directory, or failing to
+ * parse the discovered `package.json`.
+ *
+ * @returns {Promise<IPackageJson>} The {@link IPackageJson} of {@link Path}
+ * if provided, otherwise of `process.cwd()`.
+ *
+ * @example
+ * Suppose `process.cwd() === "./MyPackage"`,
+ * ```typescript
+ * const PackageJson: IPackageJson = await GetPackageJson();
+ * // `PackageJson` <- *The parsed `package.json` of `MyPackage`.*
+ * ```
+ */
+export declare function GetPackageJson(Path?: string): Promise<IPackageJson>;
+/**
+ * Get the root directory of the Node.js project in which the
+ * current working directory resides.
+ *
+ * @param Path - The given path from which to look for a root directory.
+ *
+ * @throws {RootDirectoryNotFoundError} An error iff the root directory
+ * of a NodeJS package could not be found.
+ *
+ * @returns {Promise<string>} The path to the root directory of the package
+ * containing {@link Path} if specified, otherwise containing `process.cwd()`.
+ *
+ * @example
+ * Suppose `process.cwd()` is any one of the following,
+ *   - `/home/alex/myPackage`,
+ *   - `/home/alex/myPackage/src/MyModule`,
+ *   - `/home/alex/myPackage/resource/Images`,
+ *
+ * then,
+ *
+ * ```typescript
+ * const Root: string = await GetPackageRootDirectory();
+ * // `Root` <- `"/home/alex/myPackage"`
+ * ```
+ *
+ * @example
+ * Suppose `TestPath === "/home/alex/Documents"` is *not* a NodeJS package root
+ * (of course, neither are `/home/alex` or `/home`).  Then,
+ *
+ * ```typescript
+ * const TestPath: string = "/home/alex/Documents";
+ * let Root: string | undefined = undefined;
+ * try
+ * {
+ *     Root = await GetPackageRootDirectory(TestPath);
+ * }
+ * catch (Error: unknown)
+ * {
+ *      // `Error instanceof RootDirectoryNotFound`
+ * }
+ *
+ * // `Root` <- `undefined`
+ * ```
+ *
+ * @example
+ * Suppose `process.cwd() === /home/alex/Downloads`, which is *not* a NodeJS package
+ * (of course, neither are `/home/alex` or `/home`).  Then,
+ *
+ * ```typescript
+ * let Root: string | undefined = undefined;
+ * try
+ * {
+ *     Root = await GetPackageRootDirectory();
+ * }
+ * catch (Error: unknown)
+ * {
+ *      // `Error instanceof RootDirectoryNotFound`
+ * }
+ * // `Root` <- `undefined`
+ * ```
+ */
+export declare function GetPackageRootDirectory(Path?: string): Promise<string>;
+//# sourceMappingURL=Npm.d.ts.map

package/Distribution/Types/Npm/Npm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Npm.d.ts","sourceRoot":"","sources":["../../../Source/Npm/Npm.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmC5E"}

package/Distribution/Types/Npm/index.d.cts

@@ -0,0 +1,15 @@
+/**
+ * @file      index.ts
+ * @author    Gage Sorrell <gage@sorrell.sh>
+ * @copyright (c) 2026 Gage Sorrell
+ * @license   MIT
+ */
+/**
+ * @module Npm
+ * Utilities for working with `npm` (NodeJS) packages.
+ * Many of these likely work with packages of other NodeJS
+ * package managers and adjacent runtimes (*e.g.*, `bun` or `deno`).
+ */
+export * from "./Npm.cjs";
+export * from "./Npm.Error.cjs";
+//# sourceMappingURL=index.d.cts.map

package/Distribution/Types/Npm/index.d.cts.map

@@ -0,0 +1,10 @@
+{
+    "version": 3,
+    "file": "index.d.cts",
+    "sourceRoot": "",
+    "sources": [
+        "../../../Source/Npm/index.ts"
+    ],
+    "names": [],
+    "mappings": "AAAA;;;;;GAKG;AAEH;;;;;GAKG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC"
+}