refactor: introduce internal bound context

[antongolub]

Introduces bound context to pass it down to helpers (verbose, quiet, timeout, etc).

Later we can add smth like:

$.o({spawn: customSpawn, quoute: v => v, nothrow: true})`cmd ${arg}`
$.quiet = $.o({verbose: false})

• Tests pass

[antonmedv]

I didn’t get it) What problem does it solve? Everything seems more complicated with this.

[antongolub]

For example, bound ctx lets us to configure logger params just once at the top level and do not pass this options directly from fn to fn to fn. I wanted to split it into several commits, but it might be better to add everything at once. Stay tuned.

[antonmedv]

I still now get it.

[antongolub]

AsyncLocalStorage is pure magic!

Here's what we can end up with:

// run with default settings
await $`cmd `
await $`cmd1 ...`

// all nested are verbosed
await profile({verbose: false}, async () => {
   await $`cmd`
   await $`cmd`
   await $`cmd`
})

// all nested dont throw
await profile({nothrow: true, spawn: mockedSpawn}, async () => {
   await $`cmd`
   await $`cmd`
   await $`cmd`
   
   await profile({quote: customQuote, retry: 5}, async () => {
        // customQuotes, noThrow, mocked spawn and 5 attempts for each
       await $`cmd`
       await $`cmd`
   })
})
// regular call
await $`cmd`

[antongolub]

With this improvement we can also provide a convenient testing API. As a separate pkg maybe.

[antonmedv]

But do we really need it? Testing right now works as well.

[antonmedv]

I like goods idea though

[antongolub]

I can continue pushing commits here, but it will be hard to review. Should I add contextify API as part of this PR?

[antonmedv]

I’m not convinced what this API should be provided.

[antongolub]

It's ok. But let's introduce als ctx, so we can add contextify as an extension on our own side.

[antonmedv]

But why? I still not understand. What problem does it solve?

[antongolub]

1. In the curr impl If we need to pass opts to $ factory we have to mutate its fields and then roll back.

$.spawn = spawn
const custom = $`cmd`
$.spawn = default

For both builtins or custom $-wraps.

2. To extract and reuse helpers like printCmd, printStd, fetch.
3. To bind log config when creating ProcessPromise instance and apply these settings down to the flow. (I think custom logger may appear in the near future)
4. To decouple $ factory and ProcessPromise
5. For bulk tweak ups.

// before
const $1 = (...args) => {$.smth = 'a'; const p = $(...args); $.smth = ''; return p}
const $2 = (...args) => {...}
const $2 = (...args) => {...}

// after
await profile({extra: 'npm_config_yes=true;'}, async () => {
   const ctx = getCtx()
   await $`cmd`
   await $`cmd`
   await $`${extra} cmd`
   await $`${extra} cmd`
})

6. To implement tracing.
7. To reduce complexity.
8. To pass cwd w/o cd

Meaningful changes:
1.

import {AsyncLocalStorage} from "node:async_hooks";

export const als = new AsyncLocalStorage()
export const boundCtx = Symbol('AsyncLocalStorage bound ctx')
export const getCtx = () => als.getStore()

2. $.something → getCtx().something
3. $ itself is a root lvl ctx:

als.enterWith($)

[antongolub]

@antonmedv

https://www.youtube.com/watch?v=eTAxFWzc1n4&t=5s

we use zx to operate monorepos, so we need to perform cwd/env-bound cmd queues — for each workspace in parallel

[antongolub]

async_hooks is a modern native alternative to cls-hooked. In our experience it doesnt significantly affect performance.

[antongolub]

async_hooks here is a little pinch of ioc/di, that significantly expands the customization options. I haven't refactored the tests to prove that the existing API contract hasn't changed in any way. Backward compatibility is not broken.

[antongolub]

Give a chance to this API, and I'll show the true power of improvement in next pull requests.

[antonmedv]

Researching this right now.

What about

asyncLocalStorage.enterWith(store)#

Added in: v13.11.0, v12.17.0
Stability: 1 - ExperimentalasyncLocalStorage.enterWith(store)#

Added in: v13.11.0, v12.17.0
Stability: 1 - Experimental

[antongolub]

Api details may be changed. But I don't remember any case when the added API was withdrawn at all (except punycode). async_hooks are intended for building large enterprise apps — for tracing, resource consumption measurements, low coupled configuration, etc. So I have no worries about its future.

In the worst case:

1. cls / cls-hooked
2. reset getCtx()back to $

[antongolub]

npm publish beta --no-git-tag-version?

[antonmedv]

I need little time to review a bit.

[antonmedv]

Please, rebase on master.

[antonmedv]

Congratulations 🎉 =))