@j-o-r/sh 1.1.3 → 1.1.5

package/lib/SH.js

@@ -31,27 +31,34 @@ import SHDispatch from './SHDispatch.js';
 import Test from './Test.js'
 
 /**
- * @typedef {Function} RejectCallback
- * @param {Error} error - The error object passed to the callback.
- */
+* @typedef {Object.<string, string>} ArgsObject
+* @property {string} [key: string] - Any string key maps to an object
+* @property {string[]} _ - Array of strings, unnamed parameters
+* @description Parsed parameters result.
+*/
+
 /**
- * @typedef {Function} ResolveCallback
- * @param {any} [param] - Optional callback any value
- */
+* @typedef {Function} RejectCallback
+* @param {Error} error - The error object passed to the callback.
+*/
 /**
- * Creates a new SHDispatch object that represents a command to be executed.
- *
- * @typedef {Function} Shell
- * @property {function(Array, ...*): ProcessPromise} execute - The function to execute the command.
- *
- * @param {Array} pieces - An array of string literals from a template literal.
- * @param {...*} args - The values to be interpolated into the string literals.
- * @returns {SHDispatch} Trigger for the command.
- * @throws {Error} Throws an error if any of the string literals in `pieces` is undefined.
- *
- * @example
- * const command = await SH`echo 'Hello, world!'`.run();
- */
+* @typedef {Function} ResolveCallback
+* @param {any} [param] - Optional callback any value
+*/
+/**
+* Creates a new SHDispatch object that represents a command to be executed.
+*
+* @typedef {Function} Shell
+* @property {function(Array, ...*): ProcessPromise} execute - The function to execute the command.
+*
+* @param {Array} pieces - An array of string literals from a template literal.
+* @param {...*} args - The values to be interpolated into the string literals.
+* @returns {SHDispatch} Trigger for the command.
+* @throws {Error} Throws an error if any of the string literals in `pieces` is undefined.
+*
+* @example
+* const command = await SH`echo 'Hello, world!'`.run();
+*/
 
 /**
 * Determine a javascript type
@@ -259,7 +266,7 @@ function* expBackoff(max = '60s', rand = '100ms') {
 * All unrecognized arguments are collected in an array under the `_` property.
 *
 * @param {string[]} args - An array of command-line arguments.
-* @returns {object} An object where:
+* @returns {ArgsObject} An object where:
 *   - Each key corresponds to an argument that starts with `--`,
 *   - The value is either the next argument or `true` if no value is provided,
 *   - The `_` property contains an array of unbound arguments.

package/lib/Test.js

@@ -103,6 +103,7 @@ class Test {
 	* @param {string} description
 	* @param {Function|AsyncFunction} callback - sync / async function
 	* @throws Error when conditions are not met
+	* @returns {Test}
 	*/
 	add(description, callback) {
 		if (jsType(description) !== 'String') {
@@ -112,6 +113,7 @@ class Test {
 			throw new Error(`'callback' should be a (async) Function`)
 		}
 		this.#tests.push({ description, callback });
+		return this;
 	}
 	/**
 	* Execute tests

package/package.json

@@ -2,7 +2,7 @@
   "name": "@j-o-r/sh",
   "author": "Jorrit Duin <j-o-r@duin.work>",
   "type": "module",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Execute shell commands on Linux-based systems from javascript",
   "main": "lib/SH.js",
   "types": "types/SH.d.ts",

package/types/SH.d.ts

@@ -1,3 +1,6 @@
+export type ArgsObject = {
+    [x: string]: ApiMethod;
+};
 export type RejectCallback = Function;
 export type ResolveCallback = Function;
 /**
@@ -83,34 +86,40 @@ export function expBackoff(max?: string | undefined, rand?: string | undefined):
 * All unrecognized arguments are collected in an array under the `_` property.
 *
 * @param {string[]} args - An array of command-line arguments.
-* @returns {object} An object where:
+* @returns {ArgsObject} An object where:
 *   - Each key corresponds to an argument that starts with `--`,
 *   - The value is either the next argument or `true` if no value is provided,
 *   - The `_` property contains an array of unbound arguments.
 */
-export function parseArgs(args: string[]): object;
+export function parseArgs(args: string[]): ArgsObject;
 /**
- * @typedef {Function} RejectCallback
- * @param {Error} error - The error object passed to the callback.
- */
+* @typedef {Object.<string, ApiMethod>} ArgsObject
+* @property {string} [key: string] - Any string key maps to an object
+* @property {string[]} _ - Array of strings, unnamed parameters
+* @description Parse parameters result.
+*/
 /**
- * @typedef {Function} ResolveCallback
- * @param {any} [param] - Optional callback any value
- */
+* @typedef {Function} RejectCallback
+* @param {Error} error - The error object passed to the callback.
+*/
 /**
- * Creates a new SHDispatch object that represents a command to be executed.
- *
- * @typedef {Function} Shell
- * @property {function(Array, ...*): ProcessPromise} execute - The function to execute the command.
- *
- * @param {Array} pieces - An array of string literals from a template literal.
- * @param {...*} args - The values to be interpolated into the string literals.
- * @returns {SHDispatch} Trigger for the command.
- * @throws {Error} Throws an error if any of the string literals in `pieces` is undefined.
- *
- * @example
- * const command = await SH`echo 'Hello, world!'`.run();
- */
+* @typedef {Function} ResolveCallback
+* @param {any} [param] - Optional callback any value
+*/
+/**
+* Creates a new SHDispatch object that represents a command to be executed.
+*
+* @typedef {Function} Shell
+* @property {function(Array, ...*): ProcessPromise} execute - The function to execute the command.
+*
+* @param {Array} pieces - An array of string literals from a template literal.
+* @param {...*} args - The values to be interpolated into the string literals.
+* @returns {SHDispatch} Trigger for the command.
+* @throws {Error} Throws an error if any of the string literals in `pieces` is undefined.
+*
+* @example
+* const command = await SH`echo 'Hello, world!'`.run();
+*/
 /**
 * Determine a javascript type
 *

package/types/Test.d.ts

@@ -50,8 +50,9 @@ declare class Test {
     * @param {string} description
     * @param {Function|AsyncFunction} callback - sync / async function
     * @throws Error when conditions are not met
+    * @returns {Test}
     */
-    add(description: string, callback: Function | AsyncFunction): void;
+    add(description: string, callback: Function | AsyncFunction): Test;
     /**
     * Execute tests
     * @param {number[]} [execute] - limit the execution tests