feat: export experimental ctx wrapper

README.md

@@ -52,6 +52,33 @@ temporaryFile()       // '/private/var/folders/p0/p7xckky93s30rshd51gs4pdc0000gn
 temporaryDirectory()  // '/private/var/folders/p0/p7xckky93s30rshd51gs4pdc0000gn/T/1b7e9277860eb90b94aad816d4f66f8e'
 ```
 
+### `ctx`
+[async_hooks](https://nodejs.org/api/async_hooks.html)-driven scope isolator.
+Creates a separate zx-context for the specified function.
+
+```js
+import {ctx} from 'zx/experimental'
+
+const _$ = $
+ctx(async ($) => {
+  await sleep(10)
+  cd('/foo')
+  // $.cwd refers to /foo
+  // _$.cwd === $.cwd
+})
+
+ctx(async ($) => {
+  await sleep(20)
+  // _$.cwd refers to /foo
+  // but _$.cwd !== $.cwd
+})
+
+const ref = $.bind(null)
+ctx(($) => {
+  ref === $ // true
+}, ref)
+```
+
 ### `$.preferLocal`
 In npm run scripts you can execute locally installed binaries by name. This enables the same for zx.
 ```js

package.json

@@ -37,12 +37,12 @@
   "dependencies": {
     "@qiwi/deep-proxy": "^2.0.1",
     "@types/ip": "^1.1.0",
-    "@types/node": "^17.0.40",
+    "@types/node": "^17.0.42",
     "@types/semver": "^7.3.9",
     "ip": "^1.1.8",
     "is-reachable": "^5.2.0",
     "npm-run-path": "^5.1.0",
     "tempy": "^3.0.0",
-    "zx": "^6.2.3"
+    "zx": "^6.2.5"
   }
 }

src/main/js/index.mjs

@@ -1,5 +1,5 @@
 import {$ as _$, quiet, ProcessPromise} from 'zx'
-import {ctx} from 'zx/experimental'
+import {ctx as _ctx} from 'zx/experimental'
 import {isTemplateSignature, randomId} from './util.mjs'
 import {npmRunPath} from 'npm-run-path'
 import {DeepProxy} from '@qiwi/deep-proxy'
@@ -24,6 +24,8 @@ export const $ = new DeepProxy(_$, ({DEFAULT, target: t, trapName, args}) => {
   return DEFAULT
 })
 
+export const ctx = (cb, ref = $.bind(null)) => _ctx(cb, ref)
+
 $.raw = async (...args) => {
   const q = $.quote
   $.quote = v => v

src/test/js/test.mjs

@@ -1,5 +1,5 @@
 import {strict as assert} from 'node:assert'
-import {$, semver, createHook, ip, tempy, tcping, sleep} from '../../main/js/index.mjs'
+import {$, semver, createHook, ip, tempy, tcping, sleep, ctx} from '../../main/js/index.mjs'
 
 // $.raw
 {
@@ -122,3 +122,23 @@ import {$, semver, createHook, ip, tempy, tcping, sleep} from '../../main/js/ind
   assert(await tcping('example.com:443'))
   assert(!(await tcping('unknown:1234')))
 }
+
+// ctx()
+{
+  await ctx(async ($) => {
+    $.verbose = 0
+    assert(typeof $.raw === 'function')
+
+    await ctx(async ($) => {
+      await ctx(async ($) => {
+        assert($.verbose === 0)
+        assert(typeof $.raw === 'function')
+
+        await $`echo e`
+      })
+    })
+
+    await $`echo c`
+    $.verbose = 2
+  })
+}