🎉 v0.6.0 (#1)

Author: jaandrle

README.md

@@ -1,7 +1,9 @@
-# NodeJS Script – write cross-platform scripts with ease
-This package provides very similar functionality such as [google/zx](https://github.com/google/zx).
-The key difference is to provide unix shell commands in cross-platform compatible way and suitable for javascript.
-This is done by using [shelljs/shelljs](https://github.com/shelljs/shelljs) library.
+**The package is in early stage, some changes (in API) may be made until version 1.0.0.!**
+
+# NodeJS Script – Easy cross-platform scripting
+This package serves as an alternative to [google/zx](https://github.com/google/zx) for example.
+The key difference is to provide Unix shell commands in a cross-platform compatible way and usable inside JavaScript.
+This is primarily achieved by using [shelljs/shelljs](https://github.com/shelljs/shelljs) library.
 
 You can compare the final script code to `zx` example:
 ```javascript
@@ -21,17 +23,20 @@ s.mkdir(join(s.tempdir(), name));
 ```
 
 ## Installation
-**For now experiment!!!**
 
-1. you need nodejs >=v17.0.1 ⇒ follow [nvm-sh/nvm: Node Version Manager](https://github.com/nvm-sh/nvm)[^node]
+1. tested/used on *NodeJS*: `node@v16.13.0` and `node@v17.9.1` ⇒ for installation follow [nvm-sh/nvm: Node Version Manager](https://github.com/nvm-sh/nvm)[^OR]
 1. `npm install https://github.com/jaandrle/nodejsscript --global`
 
 ## Goods
-[s (shelljs)](#shelljs) · [cli()](#cli) · [ansi-colors](#ansi-colors-package) · [fetch()](#fetch) · [pipe()](#pipe) · [question()](#question) · [echo()](#echo) · [stdin()](#stdin) · [config](#config)
-
+[s #shelljs](./docs/modules/s.md)
+ · [cli](./docs/modules/cli.md) ([cli.api() #sade](./docs/modules/cli.md#api), [cli.read()](./docs/modules/cli.md#read), …)
+ · [echo()](./docs/README.md#echo)
+ · [fetch() #node-fetch](./docs/README.md#fetch)
+ · [style #ansi-colors](./docs/modules/style.md)
+ · [pipe()](./docs/README.md#pipe)
+ · [cyclicLoop()](./docs/README.md#cyclicloop)
 
 ## Documentation
-
 Write your scripts in a file with an `.mjs` extension in order to
 use `await` at the top level. If you prefer the `.js` extension,
 wrap your scripts in something like `(async function () {...})()`.
@@ -57,116 +62,13 @@ All function (`shelljs`, `fetch`, …) are exported by library, so use:
 ```javascript
 import { … } from "nodejsscript";
 ```
+… *The entry point for documentation of all exported (**Public**) items is in the* [**docs/**](./docs/README.md).
 
-### shelljs
-The `shelljs` extension is available as `s`. For docs visits [shelljs/shelljs](https://github.com/shelljs/shelljs).
-You can pipe commands when make sense by chaining, see **[Pipes](https://github.com/shelljs/shelljs#pipes)**.
-Available commands: [cat](https://github.com/shelljs/shelljs#catoptions-file--file-) · [cd](https://github.com/shelljs/shelljs#cddir) · [chmod](https://github.com/shelljs/shelljs#chmodoptions-octal_mode--octal_string-file) · [cp](https://github.com/shelljs/shelljs#cpoptions-source--source--dest)
- · [pushd](https://github.com/shelljs/shelljs#pushdoptions-dir---n--n) · [popd](https://github.com/shelljs/shelljs#popdoptions--n--n) · [dirs](https://github.com/shelljs/shelljs#dirsoptions--n---n) · [exec](https://github.com/shelljs/shelljs#execcommand--options--callback)
- · [find](https://github.com/shelljs/shelljs#findpath--path-) · [grep](https://github.com/shelljs/shelljs#grepoptions-regex_filter-file--file-) · [head](https://github.com/shelljs/shelljs#head-n-num-file--file-) · [ln](https://github.com/shelljs/shelljs#lnoptions-source-dest)
- · [ls](https://github.com/shelljs/shelljs#lsoptions-path-) · [mkdir](https://github.com/shelljs/shelljs#mkdiroptions-dir--dir-) · [mv](https://github.com/shelljs/shelljs#mvoptions--source--source--dest) · [pwd](https://github.com/shelljs/shelljs#pwd)
- · [rm](https://github.com/shelljs/shelljs#rmoptions-file--file-) · [sed](https://github.com/shelljs/shelljs#sedoptions-search_regex-replacement-file--file-) · [sort](https://github.com/shelljs/shelljs#sortoptions-file--file-)
- · [tail](https://github.com/shelljs/shelljs#tail-n-num-file--file-) · [tempdir](https://github.com/shelljs/shelljs#tempdir) · [test](https://github.com/shelljs/shelljs#testexpression) · [touch](https://github.com/shelljs/shelljs#touchoptions-file--file-)
- · [uniq](https://github.com/shelljs/shelljs#uniqoptions-input-output) · [which](https://github.com/shelljs/shelljs#whichcommand) · [exit](https://github.com/shelljs/shelljs#exitcode) · [error](https://github.com/shelljs/shelljs#error) · [errorCode](https://github.com/shelljs/shelljs#errorcode) 
-
-```js
-s.cat("./package.json").grep("version");
-```
-… this library adds two function `xargs` and `$`:
-#### `xargs(cmd, ...cmd_args)`
-#### `xargs("-I", pattern, cmd, ...cmd_args)`
-```js
-s.exec("git branch --show-current").xargs(s.exec, "dep deploy --branch={}");
-s.exec("git branch --show-current").xargs("-I", "§", s.exec, "dep deploy --branch=§");
-```
-
-#### `$()`
-#### `$("-svf")`
-Modifies config for next command in chain. The `$()` runs next command in silent mode (compare to bash `var=$(echo Hi)`).
-
-```js
-const branch= s.$().exec("git branch --show-current");
-echo(branch);
-
-s.$("-vf").exec("gyt branch --show-current");
-```
-
-### `pipe()`
-Function similar to [Ramda `R.pipe`](https://ramdajs.com/docs/#pipe)). Provides functional way to combine commands/functions.
-
-```js
-pipe(
-	Number,
-	v=> style.greenBright(v+1),
-	v=> `Result is: ${v}`,
-	echo
-)(await question("Choose number:"));
-```
-
-### `cli()`
-A wrapper around the [lukeed/sade: Smooth (CLI) Operator 🎶](https://github.com/lukeed/sade) package.
-In addition to the origin, `cli()` supports to fill script name from script file name.
-This should be good balance between [commander - npm](https://www.npmjs.com/package/commander) and parsing arguments and writing help texts by hand.
-For more complex scripts just create full npm package.
-
-```js
-cli("", true)
-	.version("0.1.0")
-	.describe("NodeJS Script cli test")
-	.action(echo);
-```
-
-### `fetch()`
-A wrapper around the [node-fetch](https://www.npmjs.com/package/node-fetch) package.
-
-```js
-const resp= await fetch('https://medv.io')
-```
-
-### `question()`
-A wrapper around the [readline](https://nodejs.org/api/readline.html) package.
-
-```js
-const bear= await question('What kind of bear is best? ')
-```
-
-### `echo()`
-A `console.log()` alternative optimized for scripting.
-
-```js
-const branch= exec$("git branch --show-current");
-echo('Current branch is', branch);
-```
-
-### `stdin()`
-Returns the stdin as a string.
-
-```js
-const content= JSON.parse(await stdin());
-```
-
-### `config`
-Read/write global configuration.
-
-- `silent` [`false`]: Suppresses all command output if `true`, except for `echo()` call.
-- `verbose` [`false`]: Will print each executed command to the screen.
-- `fatal` [`false`]: If `true`, the script will throw a JavaScript error when any `shell.js` command encounters an error. This is analogous to Bash's `set -e`.
-- `noglob` [`false`]: Disable filename expansion (globbing)
-- `globOptions` [`{}`]: Options for [`glob.sync()`](https://github.com/isaacs/node-glob/tree/af57da21c7722bb6edb687ccd4ad3b99d3e7a333#options).
-
-```js
-const { verbose, fatal, noglob }= config;
-config.silent= true;
-const config.assign({ verbose: true, silent: false });
-
-```
-
-### `ansi-colors` package
-The [doowb/ansi-colors](https://github.com/doowb/ansi-colors) package as `style`.
-
+Note that there are also built-in `'node:*'` modules:
 ```js
-style.theme({ info: style.blue });
-echo(style.info('Hello world!'));
+import { setTimeout } from "node:timers/promises";
+import { join, resolve } from "node:path";
 ```
+…and more, see [Node.js v17.9.1 Documentation](https://nodejs.org/docs/latest-v17.x/api/documentation.html#stability-overview).
 
-[^node]: Alternatively `curl -sL install-node.vercel.app/17.0.1 | bash`
+[^OR]: Alternatively `curl -sL install-node.vercel.app/16.13.0 | bash`

bin/cli.mjs

@@ -4,8 +4,52 @@
 import { resolve } from "node:path";
 import { argv } from "node:process";
 import url from "node:url";
+import { echo, exit, style, s, cli } from "../index.js";
 
-const candidate= argv.splice(2, 1)[0];
-const filepath= candidate.startsWith('/') ? candidate : ( candidate.startsWith('file:///') ? url.fileURLToPath(candidate) : resolve(candidate) );
-argv[1]= filepath;
-await import(url.pathToFileURL(filepath).toString());
+(async function main(){
+	const candidate= argv.splice(2, 1)[0];
+	if(candidate[0]==="-") handleMyArgvs(candidate);
+
+	const filepath= candidate.startsWith('/') ? candidate : ( candidate.startsWith('file:///') ? url.fileURLToPath(candidate) : resolve(candidate) );
+	argv[1]= filepath;
+	try{
+		if(!s.test("-f", filepath)) cli.error(`File '${candidate}' not found.`);
+		await import(url.pathToFileURL(filepath).toString());
+	} catch(e){
+		const error= e instanceof cli.Error ? e.message : e;
+		console.error(error);
+		exit(1);
+	}
+})();
+
+function handleMyArgvs(candidate){
+	if(['--version', '-v', '-V'].includes(candidate)){
+		echo(info("version")[0]);
+		return exit(0);
+	}
+	if(['--help', '-h'].includes(candidate))
+		return printUsage();
+}
+function printUsage(){
+	style.theme({ n: style.blueBright, v: style.greenBright, info: style.yellow, code: style.italic });
+	const [ n, v, d ]= info("name", "version", "description");
+	echo(`
+ ${style.n(n)}@${style.v(v)}
+	${d}
+ ${style.info("Usage")}:
+	${n} [options] <script>
+ ${style.info('Options')}:
+	--version, -v       print current zx version
+	--help, -h          print help
+ ${style.info('Examples')}:
+	${n} script.js
+	${n} --help
+ ${style.info('Usage in scripts')}:
+	Just start the file with: ${style.code('#!/usr/bin/env nodejsscript')}
+`);
+	exit(0);
+}
+function info(...keys){
+	const info= s.cat("package.json").xargs(JSON.parse);
+	return keys.map(key=> Reflect.get(info, key));
+}

docs/.nojekyll

@@ -0,0 +1 @@
+TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.