Provide a stateless API (#1130)

Add a separate module which provides a stateless version of the shescape
API. It exposes the same API as an instance of the `Shescape` class,
allowing usage without instantiating a class. This is mostly useful for
use cases where escaping only needs to be done once, e.g. CLI tools.

.github/codecov.yml

@@ -39,18 +39,21 @@ flags:
     paths:
       - src/
       - index.js
+      - stateless.js
       - testing.js
   integration-Ubuntu:
     carryforward: true
     paths:
       - src/
       - index.js
+      - stateless.js
       - testing.js
   integration-Windows:
     carryforward: true
     paths:
       - src/
       - index.js
+      - stateless.js
       - testing.js
   unit:
     carryforward: true

.gitignore

@@ -8,6 +8,8 @@ checksums.txt
 crash-*
 index.cjs
 index.d.cts
+stateless.cjs
+stateless.d.cts
 testing.cjs
 testing.d.cts
 

.npmignore

@@ -13,6 +13,10 @@
 !LICENSE
 !README.md
 !SECURITY.md
+!stateless.cjs
+!stateless.d.cts
+!stateless.d.ts
+!stateless.js
 !testing.cjs
 !testing.d.cts
 !testing.d.ts

CHANGELOG.md

@@ -9,6 +9,7 @@ Versioning].
 
 ## [Unreleased]
 
+- Add `shescape/stateless` module with v1-like API. ([#1130])
 - Re-export `Shescape` as `Stubscape` from `shescape/testing`. ([#1308])
 
 ## [2.0.2] - 2023-11-19
@@ -321,6 +322,7 @@ Versioning].
 [#1082]: https://github.com/ericcornelissen/shescape/pull/1082
 [#1083]: https://github.com/ericcornelissen/shescape/pull/1083
 [#1094]: https://github.com/ericcornelissen/shescape/pull/1094
+[#1130]: https://github.com/ericcornelissen/shescape/pull/1130
 [#1137]: https://github.com/ericcornelissen/shescape/pull/1137
 [#1142]: https://github.com/ericcornelissen/shescape/pull/1142
 [#1149]: https://github.com/ericcornelissen/shescape/pull/1149

config/c8/breakage.json

@@ -1,6 +1,6 @@
 {
   "all": true,
-  "include": ["src/", "index.js", "testing.js"],
+  "include": ["src/", "index.js", "stateless.js", "testing.js"],
   "exclude": [],
   "check-coverage": false,
   "reports-dir": "_reports/coverage/breakage",

config/c8/compat.json

@@ -1,6 +1,6 @@
 {
   "all": true,
-  "include": ["src/", "index.js", "testing.js"],
+  "include": ["src/", "index.js", "stateless.js", "testing.js"],
   "exclude": [],
   "check-coverage": false,
   "reports-dir": "_reports/coverage/compat",

config/c8/integration-unix.json

@@ -1,6 +1,6 @@
 {
   "all": true,
-  "include": ["src/", "index.js", "testing.js"],
+  "include": ["src/", "index.js", "stateless.js", "testing.js"],
   "exclude": ["src/win/", "src/win.js"],
   "check-coverage": false,
   "reports-dir": "_reports/coverage/integration",

config/c8/integration-win.json

@@ -1,6 +1,6 @@
 {
   "all": true,
-  "include": ["src/", "index.js", "testing.js"],
+  "include": ["src/", "index.js", "stateless.js", "testing.js"],
   "exclude": ["src/unix/", "src/unix.js"],
   "check-coverage": false,
   "reports-dir": "_reports/coverage/integration",

config/eslint.yml

@@ -755,5 +755,7 @@ ignorePatterns:
   - script/maybe-run.js
   - index.cjs
   - index.d.cts
+  - stateless.cjs
+  - stateless.d.cts
   - testing.cjs
   - testing.d.cts

config/rollup.js

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

config/stryker/integration.js

@@ -3,7 +3,7 @@
 export default {
   coverageAnalysis: "perTest",
   inPlace: false,
-  mutate: ["index.js", "testing.js"],
+  mutate: ["index.js", "stateless.js", "testing.js"],
   testRunner: "tap",
   tap: {
     testFiles: ["test/integration/**/*.test.js"],

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

package.json

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

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",
+  "stateless.cjs",
+  "stateless.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", "stateless.d.ts", "testing.d.ts"];
 
 for (const file of files) {
   const copy = file.replace(".d.ts", ".d.cts");

stateless.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @overview Contains TypeScript type definitions for Shescape's stateless
+ * 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 or could not be found.
+ * @since 2.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 or could not be found.
+ * @since 2.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 or could not be found.
+ * @throws {Error} Quoting is not supported with `shell: false`.
+ * @since 2.1.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 or could not be found.
+ * @throws {Error} Quoting is not supported with `shell: false`.
+ * @since 2.1.0
+ */
+export function quoteAll(args: string[], options?: ShescapeOptions): string[];