breaking(runtime): remove $s shorthand for statusCode (#75)

Author: c4spar

README.md

@@ -200,23 +200,6 @@ notes.
   }
   ```
 
-- `` $s`command` ``: Executes a shell command and _only returns its exit code_
-  (without throwing an error)
-
-  ```ts
-  const trueStatus = await $s`true`);
-  console.log(trueStatus); // -> 0
-  ```
-
-  If the executed program returns a non-zero exit code, no error will be thrown.
-  Either the non-zero code will be the return value, or a `1` will be returned
-  by default.
-
-  ```ts
-  const falseStatus = await $s`false`);
-  console.log(falseStatus); // -> 1
-  ```
-
 - `` $o`command` ``: Executes a shell command and _only returns its trimmed
   stdout_ (without throwing an error)
 

src/runtime/exec.ts

@@ -19,26 +19,6 @@ export function exec(
   });
 }
 
-/**
- * Run a command and return only its exit code
- *
- * If the command throws an error or fails in some way,
- * this method will not re-throw that error. It will
- * either return the exit code from the process, or `1`
- * if no exit code is produced (due to an error)
- *
- * If you want assurance that a failure in the child process
- * will throw an error, use `$`
- * @see $
- */
-export const statusOnly = async (
-  pieces: TemplateStringsArray,
-  ...args: Array<string | number | ProcessOutput>
-): Promise<number> =>
-  await exec(pieces, ...args)
-    .then((o) => (o instanceof ProcessOutput ? o.status.code : 0))
-    .catch((e) => (e instanceof ProcessError ? e.status.code : 1));
-
 /**
  * Run a command and return only its trimmed stdout
  *

src/runtime/mod.ts

@@ -1,5 +1,5 @@
 export { async, flags, fs, io, log, path, streams } from "./deps.ts";
-export { $, $e, $o, $s } from "./shell.ts";
+export { $, $e, $o } from "./shell.ts";
 export { cd } from "./cd.ts";
 export { quote } from "./quote.ts";
 export { ProcessError } from "./process_error.ts";

src/runtime/process.ts

@@ -70,6 +70,21 @@ export class Process implements Promise<ProcessOutput> {
     return this;
   }
 
+  /**
+   * Execute the shell command and _only returns its exit code_.
+   * This calls internally `.noThrow` to catch the error and return the exit code.
+   *
+   * ```ts
+   * const trueStatus = await $`true`.statusCode;
+   * console.log(trueStatus); // -> 0
+   *
+   * const falseStatus = await $`false`.statusCode;
+   * console.log(falseStatus); // -> 1
+   *
+   * const exitStatus = await $`exit 2`.statusCode;
+   * console.log(exitStatus); // -> 2
+   * ```
+   */
   get statusCode(): Promise<number> {
     return this.noThrow.#resolve().then(({ status }) => status.code);
   }

src/runtime/shell.ts

@@ -1,5 +1,5 @@
 import { colors, shq } from "./deps.ts";
-import { exec, statusOnly, stderrOnly, stdoutOnly } from "./exec.ts";
+import { exec, stderrOnly, stdoutOnly } from "./exec.ts";
 
 export type $ = typeof exec & typeof colors & {
   get mainModule(): string;
@@ -18,7 +18,6 @@ export type $ = typeof exec & typeof colors & {
 };
 
 export const $: $ = exec as $;
-export const $s: typeof statusOnly = statusOnly;
 export const $o: typeof stdoutOnly = stdoutOnly;
 export const $e: typeof stderrOnly = stderrOnly;
 

test.ts

@@ -7,25 +7,14 @@ import {
   assertStringIncludes,
 } from "./dev_deps.ts";
 
-import { $, $e, $o, $s, cd, path, ProcessError } from "./mod.ts";
+import { $, $e, $o, cd, path, ProcessError } from "./mod.ts";
 
 Deno.test("$ works", async () => {
   const result = await $`echo hello`;
 
   assertEquals(result.stdout, "hello\n");
 });
 
-Deno.test("$s works", async () => {
-  const result1 = await $s`echo hello`;
-  assertEquals(result1, 0);
-
-  const result2 = await $s`echo hello >&2`;
-  assertEquals(result2, 0);
-
-  const result3 = await $s`echo hello; exit 1;`;
-  assertEquals(result3, 1);
-});
-
 Deno.test("$o works", async () => {
   const result1 = await $o`echo hello`;
   assertEquals(result1, "hello");
@@ -185,7 +174,7 @@ Deno.test({
 // @TODO: tests are flaky on github actions.
 // Test runner is green but throws: No such file or directory (os error 2)
 // But they don't fail while uncommenting all other tests.
-//  Locally all tests pass.
+// Locally all tests pass.
 Deno.test({
   name: "$ should have a pid",
   ignore: !!Deno.env.get("CI"),

types.d.ts

@@ -2,7 +2,6 @@ import type {
   $ as _$,
   $e as _$e,
   $o as _$o,
-  $s as _$s,
   async as _async,
   cd as _cd,
   flags as _flags,
@@ -47,20 +46,6 @@ declare global {
    */
   const $: _$;
 
-  /**
-   * Run a command and return only its exit code.
-   *
-   * If the command throws an error or fails in some way,
-   * this method will not re-throw that error. It will
-   * either return the exit code from the process, or `1`
-   * if no exit code is produced (due to an error).
-   *
-   * If you want assurance that a failure in the child process
-   * will throw an error, use `$`.
-   * @see $
-   */
-  const $s: typeof _$s;
-
   /**
    * Run a command and return only its trimmed stdout.
    *
@@ -151,7 +136,6 @@ declare global {
   interface Window {
     // dzx
     $: _$;
-    $s: typeof _$s;
     $o: typeof _$o;
     $e: typeof _$e;
     cd: typeof _cd;
@@ -170,7 +154,6 @@ declare global {
   interface WorkerGlobalScope {
     // dzx
     $: _$;
-    $s: typeof _$s;
     $o: typeof _$o;
     $e: typeof _$e;
     cd: typeof _cd;