feat(runtime): ✨ Add a a new module module (#34)

Author: xeho91

.changeset/khaki-trainers-impress.md

@@ -0,0 +1,5 @@
+---
+"@terminal-nerds/snippets-runtime": minor
+---
+
+✨ Added a module `module` for snippets related to module, dependencies and packages.

package.json

@@ -54,21 +54,23 @@
 		"@types/node": "18.13.0",
 		"browserslist": "4.21.5",
 		"bun-types": "0.5.7",
-		"concurrently": "7.6.0",
-		"del-cli": "5.0.0",
 		"depcheck": "1.4.3",
 		"eslint": "8.33.0",
-		"husky": "8.0.3",
-		"lint-staged": "13.1.0",
 		"markdownlint-cli": "0.33.0",
 		"prettier": "2.8.3",
-		"prettier-plugin-sort-markdown-table": "^1.0.1",
+		"prettier-plugin-sort-markdown-table": "1.0.2",
 		"pretty-quick": "3.1.3",
 		"syncpack": "8.4.11",
 		"tsup": "6.5.0",
-		"tsx": "^3.12.3",
 		"turbo": "1.7.4",
 		"typescript": "4.9.5",
 		"vitest": "0.28.4"
+	},
+	"optionalDependencies": {
+		"concurrently": "7.6.0",
+		"del-cli": "5.0.0",
+		"husky": "8.0.3",
+		"lint-staged": "13.1.0",
+		"tsx": "3.12.3"
 	}
 }

packages/runtime/README.md

@@ -20,6 +20,7 @@
 | Name                                             | Size                                                            |
 | ------------------------------------------------ | --------------------------------------------------------------- |
 | [`@terminal-nerds/snippets-runtime/environment`] | ![environment size gzip badge] ![environment size brotli badge] |
+| [`@terminal-nerds/snippets-runtime/module`]      | ![module size gzip badge] ![module size brotli badge]           |
 | [`@terminal-nerds/snippets-runtime/scope`]       | ![scope size gzip badge] ![scope size brotli badge]             |
 | [`@terminal-nerds/snippets-runtime/variable`]    | ![variable size gzip badge] ![variable size brotli badge]       |
 
@@ -29,6 +30,10 @@
 [environment size gzip badge]: https://badgen.net/badgesize/gzip/file-url/unpkg.com/@terminal-nerds/snippets-runtime/dist/environment/environment.js?label=gzip
 [environment size brotli badge]: https://badgen.net/badgesize/brotli/file-url/unpkg.com/@terminal-nerds/snippets-runtime/dist/environment/environment.js?label=brotli
 
+[`@terminal-nerds/snippets-runtime/module`]: https://github.com/terminal-nerds/snippets/blob/main/packages/runtime/source/module/module.ts
+[module size gzip badge]: https://badgen.net/badgesize/gzip/file-url/unpkg.com/@terminal-nerds/snippets-runtime/dist/module/module.js?label=gzip
+[module size brotli badge]: https://badgen.net/badgesize/brotli/file-url/unpkg.com/@terminal-nerds/snippets-runtime/dist/module/module.js?label=brotli
+
 [`@terminal-nerds/snippets-runtime/scope`]: https://github.com/terminal-nerds/snippets/blob/main/packages/runtime/source/scope/scope.ts
 [scope size gzip badge]: https://badgen.net/badgesize/gzip/file-url/unpkg.com/@terminal-nerds/snippets-runtime/dist/scope/scope.js?label=gzip
 [scope size brotli badge]: https://badgen.net/badgesize/brotli/file-url/unpkg.com/@terminal-nerds/snippets-runtime/dist/scope/scope.js?label=brotli

packages/runtime/package.json

@@ -64,6 +64,9 @@
 	},
 	"dependencies": {
 		"@terminal-nerds/snippets-error": "workspace:*",
+		"local-pkg": "^0.4.3",
+		"read-pkg-up": "^9.1.0",
+		"type-fest": "3.5.7",
 		"zod": "3.20.6"
 	},
 	"peerDependenciesMeta": {
@@ -72,8 +75,8 @@
 		}
 	},
 	"devDependencies": {
-		"@terminal-nerds/snippets-test": "workspace:*",
 		"@edge-runtime/vm": "2.1.2",
+		"@terminal-nerds/snippets-test": "workspace:*",
 		"happy-dom": "8.9.0",
 		"jsdom": "21.1.0"
 	}

packages/runtime/source/main.ts

@@ -1,4 +1,5 @@
 /* MODULES */
 export * from "./environment/environment.js";
+export * from "./module/module.js";
 export * from "./scope/scope.js";
 export * from "./variable/variable.js";

packages/runtime/source/module/module.test.ts

@@ -0,0 +1,81 @@
+import { returns } from "@terminal-nerds/snippets-test/unit";
+import { describe, expect, it } from "vitest";
+
+import { getDependenciesMap, getPackagesNames, hasModule } from "./module.js";
+
+describe(`hasModule(name)`, () => {
+	const nonExistingModuleName = "terminal-nerdss";
+
+	it(returns(false).on(`non-existing module`).sample(nonExistingModuleName), () => {
+		expect(hasModule(nonExistingModuleName)).toBe(false);
+	});
+
+	const moduleName = "typescript";
+
+	it(returns(true).on(`existing module`).sample(moduleName), () => {
+		expect(hasModule(moduleName)).toBe(true);
+	});
+});
+
+describe(`getDependenciesMap()`, () => {
+	const map = getDependenciesMap();
+
+	it(returns(map).on(`the current package directory`), () => {
+		expect(map).toBeInstanceOf(Map);
+	});
+
+	const expectedKeys = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"] as const;
+
+	it(`has keys: ${JSON.stringify(expectedKeys, undefined, 1)}`, () => {
+		expect([...map.keys()]).toStrictEqual(expectedKeys);
+	});
+
+	/**
+	 * NOTE: This is apparently an expected behaviour...?
+	 *
+	 * @see {@link https://github.com/npm/cli/issues/1886}
+	 */
+	it.fails(`'dependencies' at the root is '${undefined}'`, () => {
+		expect(map.get("dependencies")).toBeUndefined();
+	});
+
+	// eslint-disable-next-line unicorn/prevent-abbreviations
+	const expectedDevDependencyName = "eslint";
+
+	it(`'devDeependencies' at the root has '${expectedDevDependencyName}'`, () => {
+		expect(map.get("devDependencies")).toHaveProperty(expectedDevDependencyName);
+	});
+
+	it(`'peerDeependencies' at the root has '${undefined}'`, () => {
+		expect(map.get("peerDependencies")).toBeUndefined();
+	});
+
+	const expectedOptionalDependencyName = "husky";
+
+	it(`'optionalDeependencies' at the root has '${expectedOptionalDependencyName}'`, () => {
+		expect(map.get("optionalDependencies")).toHaveProperty(expectedOptionalDependencyName);
+	});
+});
+
+describe(`getAllPackagesNames()`, () => {
+	const packages = getPackagesNames();
+
+	it(returns(packages).on(`the current repository with all package names`), () => {
+		expect(packages).toBeInstanceOf(Set);
+		expect(packages).toContain("typescript");
+	});
+});
+
+describe(`hasPackage(name)`, () => {
+	const nonExistingPackageName = "terminal-nerdss";
+
+	it(returns(false).on(`non-existing package name in any of dependencies`).sample(nonExistingPackageName), () => {
+		expect(hasModule(nonExistingPackageName)).toBe(false);
+	});
+
+	const packageName = "typescript";
+
+	it(returns(true).on(`existing package name in any of dependencies`).sample(packageName), () => {
+		expect(hasModule(packageName)).toBe(true);
+	});
+});

packages/runtime/source/module/module.ts

@@ -0,0 +1,66 @@
+import { RuntimeError } from "@terminal-nerds/snippets-error";
+import { resolveModule } from "local-pkg";
+import { type NormalizedPackageJson, readPackageUpSync } from "read-pkg-up";
+import type { KebabCase } from "type-fest/source/kebab-case.js";
+
+import { IN_BROWSER } from "../environment/environment.js";
+
+/** @see {@link https://nodejs.org/api/modules.html#modules-commonjs-modules} CommonJS Module */
+export const IN_CJS = typeof globalThis.require === "function";
+
+/** @see {@link https://nodejs.org/api/esm.html#modules-ecmascript-modules} ECMAScript Module */
+export const IN_ESM = !IN_CJS && Boolean(import.meta);
+
+export function hasModule(name: string): boolean {
+	if (IN_BROWSER) throw new RuntimeError(`You cannot check for module existence in the browser.`);
+
+	return Boolean(resolveModule(name));
+}
+
+export type PackageName<T extends string = string> = KebabCase<T>;
+// TODO: Add typings for SemVer and other doable stuff, e.g. `workspace:*`
+export type PackageVersion = string;
+
+export function readPackageJSON(): NormalizedPackageJson {
+	if (IN_BROWSER) throw new RuntimeError(`You cannot read the package.json inside the browser.`);
+
+	const file = readPackageUpSync();
+
+	if (file) {
+		return file.packageJson;
+	} else {
+		throw new Error('Cannot locate nearest "package.json" file!');
+	}
+}
+
+export type DepedencyType = "dependencies" | "devDependencies" | "optionalDependencies" | "peerDependencies";
+export type Depedencies = Partial<Record<PackageName, PackageVersion>>;
+
+export function getDependenciesMap(): Map<DepedencyType, Depedencies | undefined> {
+	const { dependencies, devDependencies, optionalDependencies, peerDependencies } = readPackageJSON();
+
+	return new Map(
+		Object.entries({
+			dependencies,
+			devDependencies,
+			optionalDependencies,
+			peerDependencies,
+		}) as Array<[DepedencyType, Depedencies]>,
+	);
+}
+
+/** TODO: Add targetting, for better debugging (required, dev, optional or peer) */
+export function getDepedencies(): Depedencies {
+	const { dependencies, devDependencies, optionalDependencies, peerDependencies } = readPackageJSON();
+
+	return { ...dependencies, ...devDependencies, ...optionalDependencies, ...peerDependencies };
+}
+
+export function getPackagesNames(): Set<PackageName> {
+	return new Set(Object.keys(getDepedencies()));
+}
+
+/** TODO: Add targetting, for better debugging (required, dev, optional or peer) */
+export function hasPackage(name: string): boolean {
+	return getPackagesNames().has(name);
+}