@theholocron/pkg-utils 1.11.0 → 1.12.0

package/dist/index.d.mts

@@ -0,0 +1,69 @@
+//#region src/package-json.type.d.ts
+/** The `package.json` fields these utils and their callers read; any other field passes through untyped. */
+interface PackageJson {
+  name?: string;
+  version?: string;
+  private?: boolean;
+  packageManager?: string;
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  [field: string]: unknown;
+}
+//#endregion
+//#region src/dependency-names.d.ts
+export type DependencyField = "dependencies" | "devDependencies" | "peerDependencies" | "optionalDependencies";
+/**
+ * Every package name declared in `pkg`'s dependency maps — `dependencies` and
+ * `devDependencies` unless `fields` says otherwise. An absent `pkg`, a missing
+ * map, an array or any other non-object contributes nothing.
+ */
+export declare function dependencyNames(pkg: PackageJson | undefined, fields?: readonly DependencyField[]): ReadonlySet<string>;
+//#endregion
+//#region src/detect-package-manager.d.ts
+export type PackageManager = "pnpm" | "npm" | "yarn" | "bun";
+export interface DetectPackageManagerOptions {
+  /** Replaces the `package.json` read — for callers with an injected or in-memory filesystem. */
+  readFile?: (path: string) => string;
+  /** Replaces the lockfile existence check. */
+  fileExists?: (path: string) => boolean;
+  /** Returned when neither `package.json` nor a lockfile says. Defaults to `"pnpm"`. */
+  fallback?: PackageManager;
+}
+/**
+ * The package manager `dir` uses: the name in `package.json#packageManager`
+ * (`pnpm@10.0.0` → `pnpm`) when it's one of pnpm, npm, yarn or bun, else the
+ * first lockfile found, else `options.fallback`.
+ */
+export declare function detectPackageManager(dir: string, options?: DetectPackageManagerOptions): PackageManager;
+//#endregion
+//#region src/parse-package-json.d.ts
+/**
+ * Parses `package.json` text. Returns `undefined` for anything that isn't a
+ * JSON object — invalid JSON, or valid JSON of another type (an array, `null`,
+ * a string) — rather than throwing. A leading byte-order mark is ignored, as
+ * npm does.
+ *
+ * The fields {@link PackageJson} types are checked, so the result honours its
+ * type: a recognized field of the wrong type (a numeric `name`, an array
+ * `dependencies`) is left out, and the string-map fields keep only their
+ * string-valued entries. Every other field passes through untouched.
+ */
+export declare function parsePackageJson(text: string): PackageJson | undefined;
+//#endregion
+//#region src/read-package-json.d.ts
+export interface ReadPackageJsonOptions {
+  /** Replaces the file read — for callers with an injected or in-memory filesystem. */
+  readFile?: (path: string) => string;
+}
+/**
+ * The parsed `<dir>/package.json`, or `undefined` when it is missing,
+ * unreadable or not a JSON object.
+ */
+export declare function readPackageJson(dir: string): Promise<PackageJson | undefined>;
+/** Synchronous twin of {@link readPackageJson}, with an injectable `readFile`. */
+export declare function readPackageJsonSync(dir: string, options?: ReadPackageJsonOptions): PackageJson | undefined;
+//#endregion
+export type { PackageJson };

package/dist/index.mjs

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+//#region src/dependency-names.ts
+/**
+* Every package name declared in `pkg`'s dependency maps — `dependencies` and
+* `devDependencies` unless `fields` says otherwise. An absent `pkg`, a missing
+* map, an array or any other non-object contributes nothing.
+*/
+function dependencyNames(pkg, fields = ["dependencies", "devDependencies"]) {
+	const names = /* @__PURE__ */ new Set();
+	for (const field of fields) {
+		const map = pkg?.[field];
+		if (typeof map === "object" && map !== null && !Array.isArray(map)) for (const name of Object.keys(map)) names.add(name);
+	}
+	return names;
+}
+//#endregion
+//#region src/parse-package-json.ts
+const STRING_FIELDS = [
+	"name",
+	"version",
+	"packageManager"
+];
+const MAP_FIELDS = [
+	"scripts",
+	"dependencies",
+	"devDependencies",
+	"peerDependencies",
+	"optionalDependencies"
+];
+/** A plain object's string-valued entries; `undefined` for anything that isn't a plain object. */
+function stringMap(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "string"));
+}
+/**
+* Parses `package.json` text. Returns `undefined` for anything that isn't a
+* JSON object — invalid JSON, or valid JSON of another type (an array, `null`,
+* a string) — rather than throwing. A leading byte-order mark is ignored, as
+* npm does.
+*
+* The fields {@link PackageJson} types are checked, so the result honours its
+* type: a recognized field of the wrong type (a numeric `name`, an array
+* `dependencies`) is left out, and the string-map fields keep only their
+* string-valued entries. Every other field passes through untouched.
+*/
+function parsePackageJson(text) {
+	let value;
+	try {
+		value = JSON.parse(text.charCodeAt(0) === 65279 ? text.slice(1) : text);
+	} catch {
+		return;
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	const raw = value;
+	const pkg = { ...raw };
+	for (const field of STRING_FIELDS) if (typeof raw[field] !== "string") delete pkg[field];
+	if (typeof raw["private"] !== "boolean") delete pkg["private"];
+	for (const field of MAP_FIELDS) {
+		const map = stringMap(raw[field]);
+		if (map) pkg[field] = map;
+		else delete pkg[field];
+	}
+	return pkg;
+}
+//#endregion
+//#region src/detect-package-manager.ts
+const MANAGERS = [
+	"pnpm",
+	"npm",
+	"yarn",
+	"bun"
+];
+/** Checked in this order; the first lockfile present wins. */
+const LOCKFILES = [
+	["pnpm-lock.yaml", "pnpm"],
+	["bun.lockb", "bun"],
+	["bun.lock", "bun"],
+	["yarn.lock", "yarn"],
+	["npm-shrinkwrap.json", "npm"],
+	["package-lock.json", "npm"]
+];
+/**
+* The package manager `dir` uses: the name in `package.json#packageManager`
+* (`pnpm@10.0.0` → `pnpm`) when it's one of pnpm, npm, yarn or bun, else the
+* first lockfile found, else `options.fallback`.
+*/
+function detectPackageManager(dir, options = {}) {
+	const read = options.readFile ?? ((path) => readFileSync(path, "utf8"));
+	const exists = options.fileExists ?? existsSync;
+	let declared;
+	try {
+		const field = parsePackageJson(read(join(dir, "package.json")))?.packageManager;
+		declared = typeof field === "string" ? field.split("@")[0] : void 0;
+	} catch {}
+	if (declared && MANAGERS.includes(declared)) return declared;
+	for (const [file, manager] of LOCKFILES) if (exists(join(dir, file))) return manager;
+	return options.fallback ?? "pnpm";
+}
+//#endregion
+//#region src/read-package-json.ts
+/**
+* The parsed `<dir>/package.json`, or `undefined` when it is missing,
+* unreadable or not a JSON object.
+*/
+async function readPackageJson(dir) {
+	try {
+		return parsePackageJson(await readFile(join(dir, "package.json"), "utf8"));
+	} catch {
+		return;
+	}
+}
+/** Synchronous twin of {@link readPackageJson}, with an injectable `readFile`. */
+function readPackageJsonSync(dir, options = {}) {
+	const read = options.readFile ?? ((path) => readFileSync(path, "utf8"));
+	try {
+		return parsePackageJson(read(join(dir, "package.json")));
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { dependencyNames, detectPackageManager, parsePackageJson, readPackageJson, readPackageJsonSync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/pkg-utils",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Read package.json, list its dependencies and detect the package manager.",
   "keywords": [
     "package.json",