Re-export as Stubscape from shescape/testing (#1308)

Simplify importing the default stub implementation of `Shescape` as
`Stubscape` by re-exporting it under that name.

As of writing, I'm not sure whether exporting this stub as `Shescape` or
`Stubscape` is better. I think both have pros and cons. In any case, the
export named `Shescape` can't just be removed because that would be a
breaking change - so this decision is postponed to the next major
version for now.

Per warnings by knip, `Shescape` is marked as an alias of `Stubscape` in
its JSDoc documentation. Additionally, this aligns the documentation for
`Stubscape` (and by extension `Shescape`) between the .d.ts file and the
.js file.

CHANGELOG.md

@@ -9,7 +9,7 @@ Versioning].
 
 ## [Unreleased]
 
-- _No changes yet_
+- Re-export `Shescape` as `Stubscape` from `shescape/testing`. ([#1308])
 
 ## [2.0.2] - 2023-11-19
 
@@ -326,6 +326,7 @@ Versioning].
 [#1149]: https://github.com/ericcornelissen/shescape/pull/1149
 [#1280]: https://github.com/ericcornelissen/shescape/pull/1280
 [#1285]: https://github.com/ericcornelissen/shescape/pull/1285
+[#1308]: https://github.com/ericcornelissen/shescape/pull/1308
 [552e8ea]: https://github.com/ericcornelissen/shescape/commit/552e8eab56861720b1d4e5474fb65741643358f9
 [keep a changelog]: https://keepachangelog.com/en/1.0.0/
 [semantic versioning]: https://semver.org/spec/v2.0.0.html

docs/testing.md

@@ -19,7 +19,7 @@ mocking ([for example with Jest][jest-module-mock]).
 
 ```javascript
 import assert from "node:assert";
-import { Shescape as Stubscape, Throwscape } from "shescape/testing";
+import { Stubscape, Throwscape } from "shescape/testing";
 
 // Test subject
 function functionUnderTest(Shescape) {

test/breakage/testing.test.js

@@ -8,7 +8,7 @@ import * as fc from "fast-check";
 
 import { arbitrary } from "./_.js";
 
-import { Shescape as Stubscape, Throwscape } from "shescape/testing";
+import { Stubscape, Throwscape } from "shescape/testing";
 import {
   Shescape as Previoustub,
   Throwscape as Previousthrow,

test/compat/testing.test.js

@@ -9,7 +9,7 @@ import * as fc from "fast-check";
 
 import { arbitrary } from "./_.js";
 
-import { Shescape as Stubscape, Throwscape } from "../../testing.js";
+import { Stubscape, Throwscape } from "../../testing.js";
 
 testProp(
   "Stubscape#escape",

test/integration/testing/commonjs.test.js

@@ -10,14 +10,10 @@ import * as fc from "fast-check";
 
 import { arbitrary } from "../_.js";
 
-import {
-  injectionStrings,
-  Shescape as Stubscape,
-  Throwscape,
-} from "shescape/testing";
+import { injectionStrings, Stubscape, Throwscape } from "shescape/testing";
 import {
   injectionStrings as injectionStringsCjs,
-  Shescape as StubscapeCjs,
+  Stubscape as StubscapeCjs,
   Throwscape as ThrowscapeCjs,
 } from "../../../testing.cjs";
 

test/integration/testing/functional.test.js

@@ -11,11 +11,7 @@ import * as fc from "fast-check";
 import { arbitrary } from "../_.js";
 
 import { Shescape } from "shescape";
-import {
-  injectionStrings,
-  Shescape as Stubscape,
-  Throwscape,
-} from "shescape/testing";
+import { injectionStrings, Stubscape, Throwscape } from "shescape/testing";
 
 test("injection strings", (t) => {
   t.true(Array.isArray(injectionStrings));

test/unit/testing/stubscape.test.js

@@ -9,7 +9,7 @@ import * as fc from "fast-check";
 
 import { arbitrary, constants } from "./_.js";
 
-import { Shescape as Stubscape } from "../../../testing.js";
+import { Stubscape } from "../../../testing.js";
 
 testProp(
   "escape valid arguments",

testing.d.ts

@@ -18,13 +18,30 @@ import type { Shescape as ShescapeType } from "shescape";
 export const injectionStrings: string[];
 
 /**
- * A test stub of shescape that has the same input-output profile as the real
- * shescape implementation.
+ * An optimistic test stub of Shescape that has the same input-output profile as
+ * the real Shescape implementation.
  *
  * In particular:
+ * - The constructor never fails.
  * - Returns a string for all stringable inputs.
  * - Errors on non-stringable inputs.
- * - Converts non-array inputs to single-item arrays where necessary.
+ * - Errors on non-array inputs where arrays are expected.
+ * - Errors when trying to quote when `shell: false`.
+ */
+export const Stubscape: ShescapeType;
+
+/**
+ * An optimistic test stub of Shescape that has the same input-output profile as
+ * the real Shescape implementation.
+ *
+ * In particular:
+ * - The constructor never fails.
+ * - Returns a string for all stringable inputs.
+ * - Errors on non-stringable inputs.
+ * - Errors on non-array inputs where arrays are expected.
+ * - Errors when trying to quote when `shell: false`.
+ *
+ * @alias Stubscape
  */
 export const Shescape: ShescapeType;
 

testing.js

@@ -36,7 +36,7 @@ export const injectionStrings = [
  * - Errors on non-array inputs where arrays are expected.
  * - Errors when trying to quote when `shell: false`.
  */
-export class Shescape {
+export class Stubscape {
   constructor(options = {}) {
     this.shell = options.shell;
   }
@@ -62,6 +62,21 @@ export class Shescape {
   }
 }
 
+/**
+ * An optimistic test stub of Shescape that has the same input-output profile as
+ * the real Shescape implementation.
+ *
+ * In particular:
+ * - The constructor never fails.
+ * - Returns a string for all stringable inputs.
+ * - Errors on non-stringable inputs.
+ * - Errors on non-array inputs where arrays are expected.
+ * - Errors when trying to quote when `shell: false`.
+ *
+ * @alias Stubscape
+ */
+export const Shescape = Stubscape;
+
 /**
  * A test stub of Shescape that can't be instantiated. This can be used to
  * simulate a failure to instantiate Shescape in your code.