Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/webpod/zurk

A generic process spawner
https://github.com/webpod/zurk

Last synced: about 13 hours ago
JSON representation

A generic process spawner

Awesome Lists containing this project

README 

        
# zurk





– cute sounds but never friendly. 


– eats all kinds of materials.




# 🔬🧫



> This subproject is a kind of experiment, addressed to the [google/zx/issues/589](https://github.com/google/zx/issues/589).

Just a testing ground for verifying ideas and approaches aimed at improve the [zx's](https://github.com/google/zx) architecture.



## Concepts

* **Layered** architecture:

  * `spawn` builds a configurable exec context around the `node:child_process` API.

  * `zurk` implements the API for sync and async executions.

  * `x` provides the basic template-string API.

* **Granularity**: the package provides several entry points to help user to choose the right level of abstraction and/or to assist with tree-shaking.

* **Extensibility**: 

  * The context object at every layer is accessible fo modify.

  * Typings are mostly represented by interfaces, so it's easy to tweak up if necessary. 



## Requirements

* **OS**

  * Linux

  * MacOS

  * Windows

* **JS Runtime**

  * Node.js >= 6 (CJS)

  * Node.js >= 12 (ESM)

  * Bun >= 1.0.0

  * Deno >= 1.7.0



## Install

```bash

yarn add zurk

```



## API



```ts

import {$, exec, zurk} from 'zurk'



const r1 = exec({sync: true, cmd: 'echo foo'})

const r2 = await zurk({sync: false, cmd: 'echo foo'})

const r3 = await $`echo foo`

```



## Proposals

- [x] Promises in cmd literals

```ts

const foo = $`echo foo`

const foobarbaz = (await $`echo ${foo} ${$`echo bar`} ${await $`echo baz`}`)

```



- [x] Both sync and async executions

```ts

const p1 = $`echo foo`

const p2 = $({sync: true})`echo foo`



const o1 = (await p1).toString()  // foo

const o2 = await p1.stdout        // foo

const o3 = p2.stdout              // foo

```



- [x] Configurable input

```ts

const input = '{"name": "foo"}'

const name = await $({input})`jq -r .name` // foo



const stdin = fs.createReadStream(path.join(fixtures, 'foo.json'))

const data = await $({stdin})`jq -r .data` // foo



const p = $`echo "5\\n3\\n1\\n4\\n2"`

const sorted = $({input: p})`sort`          // 1\n2\n3\n4\n5

```



- [x] Pipe literals

```ts

const result = $`echo "5\\n3\\n1\\n4\\n2"`



const piped0 = result.pipe`sort | cat`     // '1\n2\n3\n4\n5'

const piped1 = result.pipe`sort`.pipe`cat` // ...

const piped2 = (await result).pipe`sort`

const piped3 = result.pipe($`sort`)

```



- [x] Pipe splitting

```ts

const result = $`echo 1; sleep 1; echo 2; sleep 1; echo 3`

const piped1 = result.pipe`cat`

let piped2: any



setTimeout(() => {

  piped2 = result.pipe`cat`

}, 1500)



await piped1

assert.equal((await piped1).toString(), '1\n2\n3')

assert.equal((await piped2).toString(), '1\n2\n3')

```



- [x] Presets

```ts

const $$ = $({sync: true, cmd: 'echo foo'})

const $$$ = $$({cmd: 'echo bar'})



const p1 = $$()           // foo

const p2 = $$$()          // bar

const p3 = $$`echo baz`   // baz

```



- [x] AbortController

```ts

const ac = new AbortController()

const p = $({nothrow: true, ac})`sleep 10`

setTimeout(() => {

  ac.signal.abort() // or just `p.abort()`

}, 500)



const { error } = await p

error.message // 'The operation was aborted'

```



- [x] Stdout limit



```ts

import {type TSpawnStore, $} from 'zurk'



const getFixedSizeArray = (size: number) => {

  const arr: any[] = []

  return new Proxy(arr, {

    get: (target: any, prop) =>

      prop === 'push' && arr.length >= size

        ? () => {}

        : target[prop]

  })

}

const store: TSpawnStore = {

  stdout: getFixedSizeArray(1),

  stderr: getFixedSizeArray(2),

  stdall: getFixedSizeArray(0)

}



const result = await $({store})`echo hello`

result.stdout // 'hello\n'

result.stdall // ''

```



## License

[MIT](./LICENSE)