printable-shell-command 0.1.1 → 0.1.3

package/Makefile

@@ -1,13 +1,20 @@
 .PHONY: lint
-lint:
+lint: setup
 	bun x @biomejs/biome check
 
 .PHONY: format
-format:
+format: setup
 	bun x @biomejs/biome check --write
 
 # https://github.com/lgarron/repo
-REPO_COMMANDS = setup publish
+REPO_COMMANDS = publish
 
+publish: setup
+
+.PHONY: ${REPO_COMMANDS}
 ${REPO_COMMANDS}:
 	repo $@
+
+.PHONY: setup
+setup:
+	bun install --frozen-lockfile

package/README.md

@@ -2,7 +2,7 @@
 
 A helper class to construct shell commands in a way that allows printing them.
 
-The goal is to make it easy to print commands that are bring run by a program, in a way that makes it easy and safe for a user to copy-and-paste.
+The goal is to make it easy to print commands that are being run by a program, in a way that makes it easy and safe for a user to copy-and-paste.
 
 ## Goals
 
@@ -43,19 +43,20 @@ ffmpeg \
 ### Spawn a process in `node`
 
 ```typescript
-import { command } from "./example";
+import { PrintableShellCommand } from "printable-shell-command";
 import { spawn } from "node:child_process";
 
-// Note the `...`
-const child_process = spawn(...command.toCommandWithFlatArgs());
+const command = new PrintableShellCommand(/* … */);
+const child_process = spawn(...command.toCommandWithFlatArgs()); // Note the `...`
 ```
 
 ### Spawn a process in `bun`
 
 ```typescript
-import { command } from "./example";
+import { PrintableShellCommand } from "printable-shell-command";
 import { spawn } from "bun";
 
+const command = new PrintableShellCommand(/* … */);
 await spawn(command.toFlatCommand()).exited;
 ```
 

package/bun.lock

@@ -0,0 +1,42 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "printable-shell-command",
+      "devDependencies": {
+        "@biomejs/biome": "^1.9.4",
+        "@types/bun": "^1.1.14",
+        "@types/node": "^22.10.2",
+      },
+    },
+  },
+  "packages": {
+    "@biomejs/biome": ["@biomejs/biome@1.9.4", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "1.9.4", "@biomejs/cli-darwin-x64": "1.9.4", "@biomejs/cli-linux-arm64": "1.9.4", "@biomejs/cli-linux-arm64-musl": "1.9.4", "@biomejs/cli-linux-x64": "1.9.4", "@biomejs/cli-linux-x64-musl": "1.9.4", "@biomejs/cli-win32-arm64": "1.9.4", "@biomejs/cli-win32-x64": "1.9.4" }, "bin": { "biome": "bin/biome" } }, "sha512-1rkd7G70+o9KkTn5KLmDYXihGoTaIGO9PIIN2ZB7UJxFrWw04CZHPYiMRjYsaDvVV7hP1dYNRLxSANLaBFGpog=="],
+
+    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@1.9.4", "", { "os": "darwin", "cpu": "arm64" }, "sha512-bFBsPWrNvkdKrNCYeAp+xo2HecOGPAy9WyNyB/jKnnedgzl4W4Hb9ZMzYNbf8dMCGmUdSavlYHiR01QaYR58cw=="],
+
+    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@1.9.4", "", { "os": "darwin", "cpu": "x64" }, "sha512-ngYBh/+bEedqkSevPVhLP4QfVPCpb+4BBe2p7Xs32dBgs7rh9nY2AIYUL6BgLw1JVXV8GlpKmb/hNiuIxfPfZg=="],
+
+    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@1.9.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-fJIW0+LYujdjUgJJuwesP4EjIBl/N/TcOX3IvIHJQNsAqvV2CHIogsmA94BPG6jZATS4Hi+xv4SkBBQSt1N4/g=="],
+
+    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@1.9.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-v665Ct9WCRjGa8+kTr0CzApU0+XXtRgwmzIf1SeKSGAv+2scAlW6JR5PMFo6FzqqZ64Po79cKODKf3/AAmECqA=="],
+
+    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@1.9.4", "", { "os": "linux", "cpu": "x64" }, "sha512-lRCJv/Vi3Vlwmbd6K+oQ0KhLHMAysN8lXoCI7XeHlxaajk06u7G+UsFSO01NAs5iYuWKmVZjmiOzJ0OJmGsMwg=="],
+
+    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@1.9.4", "", { "os": "linux", "cpu": "x64" }, "sha512-gEhi/jSBhZ2m6wjV530Yy8+fNqG8PAinM3oV7CyO+6c3CEh16Eizm21uHVsyVBEB6RIM8JHIl6AGYCv6Q6Q9Tg=="],
+
+    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@1.9.4", "", { "os": "win32", "cpu": "arm64" }, "sha512-tlbhLk+WXZmgwoIKwHIHEBZUwxml7bRJgk0X2sPyNR3S93cdRq6XulAZRQJ17FYGGzWne0fgrXBKpl7l4M87Hg=="],
+
+    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@1.9.4", "", { "os": "win32", "cpu": "x64" }, "sha512-8Y5wMhVIPaWe6jw2H+KlEm4wP/f7EW3810ZLmDlrEEy5KvBsb9ECEfu/kMWD484ijfQ8+nIi0giMgu9g1UAuuA=="],
+
+    "@types/bun": ["@types/bun@1.2.4", "", { "dependencies": { "bun-types": "1.2.4" } }, "sha512-QtuV5OMR8/rdKJs213iwXDpfVvnskPXY/S0ZiFbsTjQZycuqPbMW8Gf/XhLfwE5njW8sxI2WjISURXPlHypMFA=="],
+
+    "@types/node": ["@types/node@22.13.9", "", { "dependencies": { "undici-types": "~6.20.0" } }, "sha512-acBjXdRJ3A6Pb3tqnw9HZmyR3Fiol3aGxRCK1x3d+6CDAMjl7I649wpSd+yNURCjbOUGu9tqtLKnTGxmK6CyGw=="],
+
+    "@types/ws": ["@types/ws@8.5.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-bd/YFLW+URhBzMXurx7lWByOu+xzU9+kb3RboOteXYDfW+tr+JZa99OyNmPINEGB/ahzKrEuc8rcv4gnpJmxTw=="],
+
+    "bun-types": ["bun-types@1.2.4", "", { "dependencies": { "@types/node": "*", "@types/ws": "~8.5.10" } }, "sha512-nDPymR207ZZEoWD4AavvEaa/KZe/qlrbMSchqpQwovPZCKc7pwMoENjEtHgMKaAjJhy+x6vfqSBA1QU3bJgs0Q=="],
+
+    "undici-types": ["undici-types@6.20.0", "", {}, "sha512-Ny6QZ2Nju20vw1SRHe3d9jVu6gJ+4e3+MMpqu7pqE5HT6WsTSlce++GQmK5UXS8mzV8DSYHrQH+Xrf2jVcuKNg=="],
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "printable-shell-command",
-	"version": "0.1.1",
+	"version": "0.1.3",
 	"main": "./src/index.ts",
 	"type": "module",
 	"exports": {
@@ -9,7 +9,7 @@
 			"import": "./src/index.ts"
 		}
 	},
-	"dependencies": {
+	"devDependencies": {
 		"@biomejs/biome": "^1.9.4",
 		"@types/bun": "^1.1.14",
 		"@types/node": "^22.10.2"

package/src/index.ts

@@ -49,17 +49,20 @@ const SPECIAL_SHELL_CHARACTERS = new Set([
 
 // https://mywiki.wooledge.org/BashGuide/SpecialCharacters
 const SPECIAL_SHELL_CHARACTERS_FOR_MAIN_COMMAND =
-	SPECIAL_SHELL_CHARACTERS.union(new Set(["="]));
+	// biome-ignore lint/suspicious/noExplicitAny: Workaround to make this package easier to use in a project that otherwise only uses ES2022.)
+	(SPECIAL_SHELL_CHARACTERS as unknown as any).union(new Set(["="]));
 
 export class PrintableShellCommand {
+	#commandName: string;
 	constructor(
-		private commandName: string,
+		commandName: string,
 		private args: Args = [],
 	) {
 		if (!isString(commandName)) {
 			// biome-ignore lint/suspicious/noExplicitAny: We want to print this, no matter what it is.
 			throw new Error("Command name is not a string:", commandName as any);
 		}
+		this.#commandName = commandName;
 		if (typeof args === "undefined") {
 			return;
 		}
@@ -83,19 +86,62 @@ export class PrintableShellCommand {
 		}
 	}
 
+	get commandName(): string {
+		return this.#commandName;
+	}
+
+	// For use with `bun`.
+	//
+	// Usage example:
+	//
+	//     import { PrintableShellCommand } from "printable-shell-command";
+	//     import { spawn } from "bun";
+	//
+	//     const command = new PrintableShellCommand(/* … */);
+	//     await spawn(command.toFlatCommand()).exited;
+	//
 	public toFlatCommand(): string[] {
 		return [this.commandName, ...this.args.flat()];
 	}
 
 	// Convenient alias for `toFlatCommand()`.
+	//
+	// Usage example:
+	//
+	//     import { PrintableShellCommand } from "printable-shell-command";
+	//     import { spawn } from "bun";
+	//
+	//     const command = new PrintableShellCommand(/* … */);
+	//     await spawn(command.forBun()).exited;
+	//
 	public forBun(): string[] {
 		return this.toFlatCommand();
 	}
+
 	// For use with `node:child_process`
+	//
+	// Usage example:
+	//
+	//     import { PrintableShellCommand } from "printable-shell-command";
+	//    import { spawn } from "node:child_process";
+	//
+	//    const command = new PrintableShellCommand(/* … */);
+	//    const child_process = spawn(...command.toCommandWithFlatArgs()); // Note the `...`
+	//
 	public toCommandWithFlatArgs(): [string, string[]] {
 		return [this.commandName, this.args.flat()];
 	}
 
+	// For use with `node:child_process`
+	//
+	// Usage example:
+	//
+	//     import { PrintableShellCommand } from "printable-shell-command";
+	//    import { spawn } from "node:child_process";
+	//
+	//    const command = new PrintableShellCommand(/* … */);
+	//    const child_process = spawn(...command.forNode()); // Note the `...`
+	//
 	// Convenient alias for `toCommandWithFlatArgs()`.
 	public forNode(): [string, string[]] {
 		return this.toCommandWithFlatArgs();
@@ -104,7 +150,7 @@ export class PrintableShellCommand {
 	#escapeArg(
 		arg: string,
 		isMainCommand: boolean,
-		options: PrintOptions,
+		options?: PrintOptions,
 	): string {
 		const argCharacters = new Set(arg);
 		const specialShellCharacters = isMainCommand
@@ -112,7 +158,9 @@ export class PrintableShellCommand {
 			: SPECIAL_SHELL_CHARACTERS;
 		if (
 			options?.quoting === "extra-safe" ||
-			argCharacters.intersection(specialShellCharacters).size > 0
+			// biome-ignore lint/suspicious/noExplicitAny: Workaround to make this package easier to use in a project that otherwise only uses ES2022.)
+			(argCharacters as unknown as any).intersection(specialShellCharacters)
+				.size > 0
 		) {
 			// Use single quote to reduce the need to escape (and therefore reduce the chance for bugs/security issues).
 			const escaped = arg.replaceAll("\\", "\\\\").replaceAll("'", "\\'");