feat(shell): exec and sh

README.md

@@ -9,3 +9,32 @@ Install via npm:
 ```sh
 npm i @sebalon/scripting
 ```
+
+Then import the functions you need into your scripts.
+
+```ts
+import { /* ... */ } from '@sebalon/scripting';
+```
+
+### Shell
+
+Run shell commands using `sh`. It returns a `Promise` for the command's output.
+
+```ts
+const output = await sh('echo hello');
+// => 'hello'
+```
+
+By default, leading and trailing whitespace is trimmed from the output. You can disable this by passing `trim: false` in the options.
+
+```ts
+const output = await sh('echo hello', { trim: false });
+// => 'hello\n'
+```
+
+If you also need to inspect `stderr`, use `exec` which is the promisified version of [Node's `child_process.exec`](https://nodejs.org/api/child_process.html#child_processexeccommand-options-callback).
+
+```ts
+const output = await exec('echo hello');
+// => { stdout: 'hello\n', stderr: '' }
+```

package.json

@@ -28,11 +28,13 @@
     "@comicrelief/eslint-config": "^2.0.3",
     "@istanbuljs/nyc-config-typescript": "^1.0.2",
     "@types/chai": "^4.3.4",
+    "@types/chai-as-promised": "^7.1.5",
     "@types/mocha": "^10.0.1",
     "@types/node": "^18.15.13",
     "@typescript-eslint/eslint-plugin": "^5.59.0",
     "@typescript-eslint/parser": "^5.59.0",
     "chai": "^4.3.7",
+    "chai-as-promised": "^7.1.1",
     "eslint": "^8.38.0",
     "eslint-plugin-import": "^2.27.5",
     "eslint-plugin-jsdoc": "^39.9.1",

src/index.ts

@@ -1,8 +1 @@
-/**
- * Returns a greeting.
- *
- * @param name Optional name to greet.
- */
-export function greet(name?: string): string {
-  return `Hello ${name || 'world'}!`;
-}
+export * from './shell';

src/shell.ts

@@ -0,0 +1,55 @@
+import { ExecOptions, exec as execWithCallback } from 'child_process';
+import { promisify } from 'util';
+
+/**
+ * Promisified version of `child_process.exec`.
+ *
+ * Executes `command` within a shell and return an object containing stdout and
+ * stderr, or throws an error if `command` completes with a non-zero exit code.
+ *
+ * See the official Node documentation here for more details:
+ * https://nodejs.org/api/child_process.html#child_processexeccommand-options-callback
+ *
+ * ```ts
+ * import { exec } from '@sebalon/scripting';
+ *
+ * const output = await exec('echo hello');
+ * // => { stdout: 'hello\n', stderr: '' }
+ * ```
+ */
+export const exec = promisify(execWithCallback);
+
+/**
+ * Options for `sh`.
+ */
+export type ShOptions = ExecOptions & {
+  /**
+   * Trim leading and trailing whitespace from the output.
+   *
+   * Default: true
+   */
+  trim?: boolean;
+};
+
+/**
+ * Executes `command` within a shell and returns its output (stdout), or throws
+ * an error if `command` completes with a non-zero exit code.
+ *
+ * ```ts
+ * import { sh } from '@sebalon/scripting';
+ *
+ * const output = await sh('echo hello');
+ * // => 'hello'
+ * ```
+ *
+ * @param command Command to run.
+ * @param options Options to be passed to `exec`.
+ */
+export async function sh(command: string, options?: ShOptions): Promise<string> {
+  const result = await exec(command, options);
+  let output = result.stdout.toString();
+  if (options?.trim ?? true) {
+    output = output.trim();
+  }
+  return output;
+}

tests/setup.ts

@@ -1 +1,4 @@
-// add test setup here, e.g. load dotenv, register chai plugins, ...
+import chai from 'chai';
+import chaiAsPromised from 'chai-as-promised';
+
+chai.use(chaiAsPromised);

tests/shell.spec.ts

@@ -0,0 +1,38 @@
+import { expect } from 'chai';
+
+import { exec, sh } from '@/src';
+
+describe('exec', () => {
+  it('should run a command and return stdout and stderr', async () => {
+    const output = await exec('echo "hello stdout"; echo "hello stderr" >&2');
+    expect(output.stdout).to.equal('hello stdout\n');
+    expect(output.stderr).to.equal('hello stderr\n');
+  });
+
+  it('should throw if the command fails', async () => {
+    await expect(exec('false')).to.eventually.be.rejected;
+  });
+});
+
+describe('sh', () => {
+  it('should run a command and return its stdout, trimmed by default', async () => {
+    const output = await sh('echo hello');
+    expect(output).to.equal('hello');
+  });
+
+  it('should throw if the command fails', async () => {
+    await expect(sh('false')).to.eventually.be.rejected;
+  });
+
+  describe('options.trim', () => {
+    it('if true, should remove leading and trailing spaces', async () => {
+      const output = await sh('echo " hello "', { trim: true });
+      expect(output).to.equal('hello');
+    });
+
+    it('if false, should keep leading and trailing spaces', async () => {
+      const output = await sh('echo " hello "', { trim: false });
+      expect(output).to.equal(' hello \n');
+    });
+  });
+});