Offer a "oneshot" module that doesn't require initializing a class

.eslintrc.yml

@@ -742,5 +742,7 @@ ignorePatterns:
   - node_modules/
   - index.cjs
   - index.d.cts
+  - oneshot.cjs
+  - oneshot.d.cts
   - testing.cjs
   - testing.d.cts

.gitignore

@@ -7,6 +7,8 @@ _reports/
 crash-*
 index.cjs
 index.d.cts
+oneshot.cjs
+oneshot.d.cts
 testing.cjs
 testing.d.cts
 

.npmignore

@@ -9,6 +9,10 @@
 !index.d.cts
 !index.d.ts
 !index.js
+!oneshot.cjs
+!oneshot.d.cts
+!oneshot.d.ts
+!oneshot.js
 !package.json
 !LICENSE
 !README.md

index.d.ts

@@ -8,7 +8,7 @@
  *
  * @since 2.0.0
  */
-interface ShescapeOptions {
+export interface ShescapeOptions {
   /**
    * Whether or not to protect against flag and option (such as `--verbose`)
    * injection

oneshot.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @overview Contains TypeScript type definitions for Shescape's oneshot
+ * alternative.
+ * @license MPL-2.0
+ */
+
+import type { ShescapeOptions } from "shescape";
+
+/**
+ * Take a single value, the argument, and escape any dangerous characters.
+ *
+ * Non-string inputs will be converted to strings using a `toString()` method.
+ *
+ * @example
+ * import { spawn } from "node:child_process";
+ * spawn(
+ *   "echo",
+ *   ["Hello", shescape.escape(userInput, { shell: false })],
+ *   null // `options.shell` MUST be falsy
+ * );
+ * @param {string} arg The argument to escape.
+ * @param {object} [options] The escape options.
+ * @param {boolean} [options.flagProtection=true] Is flag protection enabled.
+ * @param {boolean | string} [options.shell=true] The shell to escape for.
+ * @returns {string} The escaped argument.
+ * @throws {TypeError} The argument is not stringable.
+ * @throws {Error} The shell is not supported.
+ * @since 0.1.0
+ */
+export function escape(arg: string, options?: ShescapeOptions): string;
+
+/**
+ * Take an array of values, the arguments, and escape any dangerous characters
+ * in every argument.
+ *
+ * Non-array inputs will be converted to one-value arrays and non-string values
+ * will be converted to strings using a `toString()` method.
+ *
+ * @example
+ * import { spawn } from "node:child_process";
+ * spawn(
+ *   "echo",
+ *   shescape.escapeAll(["Hello", userInput], { shell: false }),
+ *   null // `options.shell` MUST be falsy
+ * );
+ * @param {string[]} args The arguments to escape.
+ * @param {object} [options] The escape options.
+ * @param {boolean} [options.flagProtection=true] Is flag protection enabled.
+ * @param {boolean | string} [options.shell=true] The shell to escape for.
+ * @returns {string[]} The escaped arguments.
+ * @throws {TypeError} One of the arguments is not stringable.
+ * @throws {Error} The shell is not supported.
+ * @since 1.1.0
+ */
+export function escapeAll(args: string[], options?: ShescapeOptions): string[];
+
+/**
+ * Take a single value, the argument, put shell-specific quotes around it and
+ * escape any dangerous characters.
+ *
+ * Non-string inputs will be converted to strings using a `toString()` method.
+ *
+ * @example
+ * import { spawn } from "node:child_process";
+ * const spawnOptions = { shell: true }; // `options.shell` SHOULD be truthy
+ * spawn(
+ *   "echo",
+ *   ["Hello", shescape.quote(userInput, { shell: spawnOptions.shell })],
+ *   spawnOptions
+ * );
+ * @param {string} arg The argument to quote and escape.
+ * @param {object} [options] The escape options.
+ * @param {boolean} [options.flagProtection=true] Is flag protection enabled.
+ * @param {boolean | string} [options.shell=true] The shell to escape for.
+ * @returns {string} The quoted and escaped argument.
+ * @throws {TypeError} The argument is not stringable.
+ * @throws {Error} The shell is not supported.
+ * @throws {Error} Quoting is not supported with `shell: false`.
+ * @since 0.3.0
+ */
+export function quote(arg: string, options?: ShescapeOptions): string;
+
+/**
+ * Take an array of values, the arguments, put shell-specific quotes around
+ * every argument and escape any dangerous characters in every argument.
+ *
+ * Non-array inputs will be converted to one-value arrays and non-string
+ * values will be converted to strings using a `toString()` method.
+ *
+ * @example
+ * import { spawn } from "node:child_process";
+ * const spawnOptions = { shell: true }; // `options.shell` SHOULD be truthy
+ * spawn(
+ *   "echo",
+ *   shescape.quoteAll(["Hello", userInput], { shell: spawnOptions.shell }),
+ *   spawnOptions
+ * );
+ * @param {string[]} args The arguments to quote and escape.
+ * @param {object} [options] The escape options.
+ * @param {boolean} [options.flagProtection=true] Is flag protection enabled.
+ * @param {boolean | string} [options.shell=true] The shell to escape for.
+ * @returns {string[]} The quoted and escaped arguments.
+ * @throws {TypeError} One of the arguments is not stringable.
+ * @throws {Error} The shell is not supported.
+ * @throws {Error} Quoting is not supported with `shell: false`.
+ * @since 0.4.0
+ */
+export function quoteAll(args: string[], options?: ShescapeOptions): string[];

oneshot.js

@@ -0,0 +1,119 @@
+/**
+ * @overview Alternative entrypoint for the library requiring no setup.
+ * @license MPL-2.0
+ */
+
+import { Shescape } from "./index.js";
+
+/**
+ * Take a single value, the argument, and escape any dangerous characters.
+ *
+ * Non-string inputs will be converted to strings using a `toString()` method.
+ *
+ * @example
+ * import { spawn } from "node:child_process";
+ * spawn(
+ *   "echo",
+ *   ["Hello", shescape.escape(userInput, { shell: false })],
+ *   null // `options.shell` MUST be falsy
+ * );
+ * @param {string} arg The argument to escape.
+ * @param {object} [options] The escape options.
+ * @param {boolean} [options.flagProtection=true] Is flag protection enabled.
+ * @param {boolean | string} [options.shell=true] The shell to escape for.
+ * @returns {string} The escaped argument.
+ * @throws {TypeError} The argument is not stringable.
+ * @throws {Error} The shell is not supported.
+ * @since 0.1.0
+ */
+export function escape(arg, options) {
+  const shescape = new Shescape(options);
+  return shescape.escape(arg);
+}
+
+/**
+ * Take an array of values, the arguments, and escape any dangerous characters
+ * in every argument.
+ *
+ * Non-array inputs will be converted to one-value arrays and non-string values
+ * will be converted to strings using a `toString()` method.
+ *
+ * @example
+ * import { spawn } from "node:child_process";
+ * spawn(
+ *   "echo",
+ *   shescape.escapeAll(["Hello", userInput], { shell: false }),
+ *   null // `options.shell` MUST be falsy
+ * );
+ * @param {string[]} args The arguments to escape.
+ * @param {object} [options] The escape options.
+ * @param {boolean} [options.flagProtection=true] Is flag protection enabled.
+ * @param {boolean | string} [options.shell=true] The shell to escape for.
+ * @returns {string[]} The escaped arguments.
+ * @throws {TypeError} One of the arguments is not stringable.
+ * @throws {Error} The shell is not supported.
+ * @since 1.1.0
+ */
+export function escapeAll(args, options) {
+  const shescape = new Shescape(options);
+  return shescape.escapeAll(args);
+}
+
+/**
+ * Take a single value, the argument, put shell-specific quotes around it and
+ * escape any dangerous characters.
+ *
+ * Non-string inputs will be converted to strings using a `toString()` method.
+ *
+ * @example
+ * import { spawn } from "node:child_process";
+ * const spawnOptions = { shell: true }; // `options.shell` SHOULD be truthy
+ * spawn(
+ *   "echo",
+ *   ["Hello", shescape.quote(userInput, { shell: spawnOptions.shell })],
+ *   spawnOptions
+ * );
+ * @param {string} arg The argument to quote and escape.
+ * @param {object} [options] The escape options.
+ * @param {boolean} [options.flagProtection=true] Is flag protection enabled.
+ * @param {boolean | string} [options.shell=true] The shell to escape for.
+ * @returns {string} The quoted and escaped argument.
+ * @throws {TypeError} The argument is not stringable.
+ * @throws {Error} The shell is not supported.
+ * @throws {Error} Quoting is not supported with `shell: false`.
+ * @since 0.3.0
+ */
+export function quote(arg, options) {
+  const shescape = new Shescape(options);
+  return shescape.quote(arg);
+}
+
+/**
+ * Take an array of values, the arguments, put shell-specific quotes around
+ * every argument and escape any dangerous characters in every argument.
+ *
+ * Non-array inputs will be converted to one-value arrays and non-string
+ * values will be converted to strings using a `toString()` method.
+ *
+ * @example
+ * import { spawn } from "node:child_process";
+ * const spawnOptions = { shell: true }; // `options.shell` SHOULD be truthy
+ * spawn(
+ *   "echo",
+ *   shescape.quoteAll(["Hello", userInput], { shell: spawnOptions.shell }),
+ *   spawnOptions
+ * );
+ * @param {string[]} args The arguments to quote and escape.
+ * @param {object} [options] The escape options.
+ * @param {boolean} [options.flagProtection=true] Is flag protection enabled.
+ * @param {boolean | string} [options.shell=true] The shell to escape for.
+ * @returns {string[]} The quoted and escaped arguments.
+ * @throws {TypeError} One of the arguments is not stringable.
+ * @throws {Error} The shell is not supported.
+ * @throws {Error} Quoting is not supported with `shell: false`.
+ * @since 0.4.0
+ */
+export function quoteAll(args, options) {
+  const shescape = new Shescape(options);
+  return shescape.quoteAll(args);
+}

package.json

@@ -16,6 +16,16 @@
         "default": "./index.cjs"
       }
     },
+    "./oneshot": {
+      "import": {
+        "types": "./oneshot.d.ts",
+        "default": "./oneshot.js"
+      },
+      "require": {
+        "types": "./oneshot.d.cts",
+        "default": "./oneshot.cjs"
+      }
+    },
     "./testing": {
       "import": {
         "types": "./testing.d.ts",

rollup.config.js

@@ -18,6 +18,14 @@ export default [
     },
     external,
   },
+  {
+    input: "oneshot.js",
+    output: {
+      file: "oneshot.cjs",
+      format: "cjs",
+    },
+    external,
+  },
   {
     input: "testing.js",
     output: {

script/clean.js

@@ -9,7 +9,14 @@ import path from "node:path";
 
 import { common } from "./_.js";
 
-const files = ["index.cjs", "index.d.cts", "testing.cjs", "testing.d.cts"];
+const files = [
+  "index.cjs",
+  "index.d.cts",
+  "oneshot.cjs",
+  "oneshot.d.cts",
+  "testing.cjs",
+  "testing.d.cts",
+];
 const folders = [".corpus/", ".nyc_output/", ".temp/", "_reports/"];
 
 for (const file of files) {

script/create-d-cts.js

@@ -8,7 +8,7 @@ import path from "node:path";
 
 import { common } from "./_.js";
 
-const files = ["index.d.ts", "testing.d.ts"];
+const files = ["index.d.ts", "oneshot.d.ts", "testing.d.ts"];
 
 for (const file of files) {
   const copy = file.replace(".d.ts", ".d.cts");