@j-o-r/sh 1.1.23 → 1.1.24

package/README.md

@@ -64,11 +64,14 @@ The module also provides additional utilities for common tasks:
 - `sleep(duration)`: Pause execution for a specified duration.
 - `retry(count, interval, callback)`: Retry a command a specified number of times with an optional interval.
 - `readIn()`: Read from standard input.
+- `userIn(prompt)`: Prompt the user for input and return an object with `input` (Promise resolving to the user input) and `abort()` method to cancel.
 - `within(callback)`: Create an async context in a sync block.
 - `expBackoff(max, rand)`: Generate intervals for exponential backoff.
 - `jsType(any)`: Get the 'real' javascript variable type 
+- `hasProp(object, property)`: Safely check if an object has its own property (handles null/undefined objects).
 - `assert.`: Node assert library 
 - `new Test()`: A small sync/async minimal test framework 
+- `AsyncTracker`: A class for tracking asynchronous operations using Node.js async hooks.
 
 ## SHDispatch
 
@@ -118,11 +121,27 @@ This class is returned by the `SH` function. Here's a summary of its methods and
 - Retry with exponential backoff:
   ```javascript
   try {
-    const p = await retry(3, expBackoff(), () => SH`curl -s https://flipwrsi`.run());
+    const p = await retry(3, expBackoff(), () => SH`curl -s https://unreachable`.run());
   } catch (e) {
     console.error('Retry failed:', e);
   }
   ```
+
+- Prompt user for input:
+  ```javascript
+  const user = userIn('Enter your name: ');
+  const name = await user.input;
+  console.log('Hello,', name);
+  ```
+
+- Check if object has property:
+  ```javascript
+  const obj = { a: 1 };
+  console.log(hasProp(obj, 'a')); // true
+  console.log(hasProp(obj, 'b')); // false
+  console.log(hasProp(null, 'a')); // false
+  ```
+
 - Method for copying data to the clipboard:
   ```javascript
   /**

package/module.md

@@ -0,0 +1,154 @@
+# @j-o-r/sh Module Documentation
+
+## Overview
+
+**Name:** @j-o-r/sh  
+**Version:** 1.1.23  
+**Description:** Execute shell commands on Linux-based systems from javascript.  
+
+This module simplifies the execution of shell commands within JavaScript applications, providing utilities to handle shell scripts and manage their output efficiently. It is inspired by the zx library and supports features like command execution, retries, user input, and more.
+
+**Repository:** https://codeberg.org/duin/sh  
+**License:** Apache License, Version 2.0  
+
+Key features include:
+- Execute shell commands synchronously or asynchronously.
+- Utilities for changing directory, sleeping, retrying commands with backoff.
+- Parsing command-line arguments.
+- User input prompts.
+- A minimal test framework.
+- Async operation tracking.
+
+## Installation Notes
+
+The module is already installed in the current environment. For new installations, use:
+
+```sh
+npm install @j-o-r/sh
+```
+
+Requires Node.js >= 20.0.0.
+
+## API Usage Examples
+
+### Basic Usage
+
+To execute a shell command, use the `SH` function:
+
+```javascript
+import { SH } from '@j-o-r/sh';
+
+SH`your_shell_command`.run()
+  .then(output => {
+    console.log('Output:', output);
+  })
+  .catch(error => {
+    console.error('Error:', error);
+  });
+```
+
+### Advanced Usage
+
+```javascript
+import { SH, cd, within, sleep, retry, expBackoff } from '@j-o-r/sh';
+
+const res = await SH`ls -FLa | grep package.json | wc -l`.run();
+console.log(res);
+
+const ar = within(async () => {
+  const res = await Promise.all([
+    SH`sleep 1; echo 1`.run(),
+    SH`sleep 2; echo 2`.run(),
+    sleep(2),
+    SH`sleep 3; echo 3`.run()
+  ]);
+});
+
+const p = await retry(3, expBackoff(), () => SH`curl -s https://unreachable`.run());
+```
+
+### Additional Examples
+
+- Prompt user for input:
+  ```javascript
+  const user = userIn('Enter your name: ');
+  const name = await user.input;
+  console.log('Hello,', name);
+  ```
+
+- Create and run a test:
+  ```javascript
+  import { assert, jsType, Test } from '@j-o-r/sh';
+
+  const test = new Test();
+  test.add('Test is test in sync', () => {
+    assert.strictEqual(jsType(test), 'Test');
+  });
+  const report = await test.run();
+  ```
+
+## Full API Reference
+
+### Main Exports
+
+- **SH**: A template tag function that returns an `SHDispatch` object for executing shell commands.
+- **cd(dir: string)**: Changes the working directory.
+- **sleep(duration: string | number)**: Pauses execution for the specified duration (e.g., '5s').
+- **retry(count: number, a: string | number | expBackoff | Function, b?: Function)**: Retries a function with optional intervals.
+- **readIn()**: Reads from stdin as a promise.
+- **userIn(prompt: string)**: Prompts for user input, returns object with `input` promise and `abort` method.
+- **within(callback: Function)**: Creates an async context.
+- **expBackoff(max?: string, rand?: string)**: Generator for exponential backoff intervals.
+- **parseArgs(args?: string[])**: Parses command-line arguments into an object.
+- **jsType(any)**: Returns the 'real' JavaScript type.
+- **hasProp(o: any, p: string)**: Safely checks if an object has a property.
+- **Test**: Class for a minimal test framework.
+- **assert**: Node.js assert library.
+- **AsyncTracker**: Class for tracking async operations.
+
+### SHDispatch Class
+
+Returned by the `SH` template tag. Methods:
+
+- **options(options: SpawnOptions | SpawnSyncOptions, prefix?: string)**: Sets execution options.
+- **run(payload?: string)**: Executes the command asynchronously, returns Promise<string>.
+- **runSync(payload?: string)**: Executes synchronously, returns SpawnSyncReturns.
+- **kill(signal?: string)**: Kills the process.
+
+### Test Class
+
+For running tests:
+
+- **constructor(quiet?: boolean)**: Creates a test suite.
+- **syncTimeout(timeout: number)**: Sets timeout for sync tests.
+- **add(description: string, callback: Function | AsyncFunction)**: Adds a test.
+- **run(execute?: number[])**: Runs tests, returns Promise<Report>.
+- **reset()**: Clears tests.
+
+### AsyncTracker Class
+
+Tracks async operations:
+
+- **enable(type?: SystemTypes)**: Enables tracking.
+- **disable()**: Disables tracking.
+- **reset()**: Clears tracked items.
+- **report(verbose?: boolean)**: Reports unresolved async operations.
+- **getUnresolved(type?: SystemTypes)**: Gets unresolved items.
+- **getTypeDescription(type: SystemTypes)**: Gets type description.
+- **addCustomType(type: string, description: string)**: Adds custom type.
+
+### Types
+
+- **ArgsObject**: Object for parsed args, with `_` for unnamed.
+- **SpawnSyncResponse**: Result of sync spawn.
+- **SHOptions**: Options for SH execution.
+- **AsyncHookItem**: Item in async tracking.
+- **testDefinition, testReport, Report**: Types for test framework.
+
+## Dependencies
+
+**Runtime Dependencies:** None  
+
+**Dev Dependencies:**  
+- @types/node: ^22.10.10
+

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.23",
+  "version": "1.1.24",
   "description": "Execute shell commands on Linux-based systems from javascript",
   "main": "lib/SH.js",
   "types": "types/SH.d.ts",