Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Minigugus/bazx

🐚️ zx on 💊️ steroids
https://github.com/Minigugus/bazx

Last synced: 13 days ago
JSON representation

🐚️ zx on 💊️ steroids

Awesome Lists containing this project

README

        

BAZX

> 🐚️ [zx](https://github.com/google/zx) on 💊️ steroids

> You are seeing the code of an upcoming release. The `main` branch contains the latest released code.
> Code on this branch is still under discussion and documentation is not completed yet.

## Main differences with ZX

* Written from scratch
* **0 dependencies** by default
* **Plateform-agnostic** (not limited to *Deno* or *NodeJS*)
* Extensible (enables **remote command execution** and thus **browser support**)
* **Middlewares** support (filter allowed commands, hack input/outputs, and much more)
* [**Streams**](#streams) at the core for better performances ([no streaming support with zx](https://github.com/google/zx/issues/14#issuecomment-841672494))
* No shell by default (the `|` in ``$`echo |`;`` is not evaluated by default)
* Modern (TypeScript, Deno, ES2020)
* **MIT** vs Apache license
* Library only

## Support

* Deno: 🐥️ (working)
* NodeJS: 🥚️ (not started yet)
* QuickJS: 🥚️ (not started yet)
* Browser: 🥚️ (not started yet)
* Mock: 🐣️ (started)

## Setup

### Deno

```js
import $ from 'https://deno.land/x/bazx/deno.ts';
```

As of now, only the `--allow-run` command is required at runtime.

### Isomorphic (for testing purpose)

```js
import $ from 'https://deno.land/x/bazx/mock.ts';
```

This implementation doesn't know how to spawn a process and thus always throw.
Intended to be used along with middlewares in tests or sandboxes for instance.

### (Bring Your Own Runtime)

```ts
import { createBazx } from 'https://deno.land/x/bazx/mod.ts';

const $ = createBazx((
cmd: [string, ...string[]],
options: {
cwd?: string,
env?: Record,
stdin?: ReadableStream,
stdout?: WritableStream,
stderr?: WritableStream,
signal?: AbortSignal,
}
): PromiseLike<{ code: number }> => {
// Spawn commands here.
//
// CAUTION: This function is reponsible for closing stdin/stdout/stderr.
// Missing to do so will result in deadlocks.
}, { /* Default options (logging, colors, and so on) */ });
```

## Usage

See the [`examples`](examples/) folder for more examples

### Middlewares

Middlewares are hooks that runs a process get spawned, so that it can for instance
dynamically hack streams, change the command line, working directories and environment
variabes, never really spawn a process, spawn a process twice, and so on.

For instance, this really simple middleware wraps processes with `time`, so that some process meta are displayed:

```typescript
import { BazxMiddleware } from 'https://deno.land/x/bazx/mod.ts';

export const timeWrapperMiddleware: BazxMiddleware =
exec => (cmd, options) => exec(['time', ...cmd], options);
```

Then, it can be applied with the `$.with` function:

```typescript
import $ from 'https://deno.land/x/bazx/deno.ts';

const $$ = $.with(timeWrapperMiddleware);

await $$`echo Hello world!`.status

// $ echo Hello world!
// Hello world!
// 0.00user 0.00system 0:00.00elapsed 100%CPU (0avgtext+0avgdata 1936maxresident)k
// 0inputs+0outputs (0major+73minor)pagefaults 0swaps
```

As you can may have noticed, only the original command is printed to the user,
not the updated one with `time`. This way, middlewares are fully transparents to the user.

Each `.with` call returns a new `$` instance that use the config of the parent (`exec`, `options` and middlewares),
so that multiple `.with` calls can be chained.

### TODO

* [ ] Improve docs (README + JSDoc)
* [ ] Rollup for NodeJS and browser builds
* [ ] Add more runtime support (NodeJS at least)
* [ ] Fix bugs (some complex use case doesn't work yet)
* [X] Dynamic config update (like `set` in bash (enable/disable logs, etc.))
* [X] `NO_COLOR` support (for CI/CD)
* [ ] Pipelines starting with a stream
* [ ] `stderr` pipes
* [ ] Add benchmarks, improve perfs (audit WHATWG streams perfs)
* [ ] Discuss envrionment variables support

## FAQ

### Why is it called `bazx`?

Just like `bash` built from `sh`, there should be a `bazx` built from `zx` 😁️

### How do you prononce `bazx`?

*basix* (just like *basic* but with a *x* instead of a *c* at the end)

## License

Inspired by [zx](https://github.com/google/zx)

[MIT License](LICENSE)

Copyright 2021 Minigugus