Merge pull request #99 from thefrontside/tm/try-v4

### Motivation

All `@effectionx` extensions were migrated to v3 in #87, but we now want to ensure compatibility with effection v4. This PR adds the infrastructure to run tests against both v3 and v4 versions of effection, and prepares all packages for publishing with dual version support.

### Changes

#### Import Map Generation
- Created `tasks/generate-importmap.ts` that **dynamically fetches the latest v4 version** from the npm registry at generation time
- The import map automatically collects all external dependencies from workspace packages
- Maps `@effectionx/*` packages to their local paths for testing

#### CI Workflow Updates
- Refactored `.github/workflows/verify-posix.yaml` and `.github/workflows/verify-windows.yaml` to use `workflow_call` for reusability
- CI now runs both **V3 Tests** and **V4 Tests** on every PR and push to main
- Added `--trace-leaks` flag to v4 tests for better debugging
- Updated publish workflow to require verification jobs before publishing

#### NPM Peer Dependency
- Updated `tasks/build-npm.ts` to use `"effection": "^3 || ^4.0.0-0"` to support v4 prereleases

#### Version Bumps
All 16 packages received minor version bumps to publish with v3/v4 compatibility:

| Package | New Version |
|---------|-------------|
| @effectionx/context-api | 0.2.0 |
| @effectionx/deno-deploy | 0.3.0 |
| @effectionx/bdd | 0.3.0 |
| @effectionx/jsonl-store | 0.3.0 |
| @effectionx/fx | 0.3.0 |
| @effectionx/raf | 0.1.0 |
| @effectionx/task-buffer | 1.2.0 |
| @effectionx/test-adapter | 0.6.0 |
| @effectionx/timebox | 0.3.0 |
| @effectionx/tinyexec | 0.3.0 |
| @effectionx/watch | 0.3.0 |
| @effectionx/websocket | 2.2.0 |
| @effectionx/worker | 0.3.0 |
| @effectionx/stream-helpers | 0.4.0 |
| @effectionx/signals | 0.4.0 |
| @effectionx/process | 0.6.0 |

#### Test Adapter Enhancements
- Added sanitization options to test functions for disabling operation and resource sanitization when needed

#### Resource Refactoring
- Converted process to use resource pattern (required for v4 compatibility)
- Refactored inspector into a resource

#### Test Compatibility Fixes
Multiple test files were updated to work with both v3 and v4:
- Added `sleep(0)` calls to give the operation tree time to set up subscriptions
- Wrapped operations in `spawn` where v4's stricter lifecycle management requires it
- Fixed `batch` stream completion handling for proper done state propagation

#### Documentation
- Added testing instructions to root `README.md` for running v3 and v4 tests
- Rewrote `process/README.md` with comprehensive documentation

### How to Use

1. Generate the v4 import map:
   ```bash
   deno task generate-importmap
   ```

2. Run tests with v4:
   ```bash
   deno test --import-map v4.importmap.json -A
   ```

3. Run tests with v3 (default):
   ```bash
   deno test -A
   ```

### Summary

- **53 files changed**, 1,211 insertions(+), 489 deletions(-)
- Key packages affected: `stream-helpers`, `signals`, `task-buffer`, `watch`, `process`, `test-adapter`, `fx`

Author: taras

.github/workflows/publish.yaml

@@ -5,7 +5,14 @@ on:
       - main
 
 jobs:
+  verify-posix:
+    uses: ./.github/workflows/verify-posix.yaml
+
+  verify-windows:
+    uses: ./.github/workflows/verify-windows.yaml
+
   generate-matrix:
+    needs: [verify-posix, verify-windows]
     name: Generate Job Matrix
     runs-on: ubuntu-latest
     outputs:
@@ -23,7 +30,7 @@ jobs:
         id: set-matrix
 
   jsr:
-    if: fromJSON(needs.generate-matrix.outputs.exists)
+    if: github.ref == 'refs/heads/main' && fromJSON(needs.generate-matrix.outputs.exists)
     name: Publish ${{ matrix.name }}@${{matrix.version}} to JSR
     runs-on: ubuntu-latest
 
@@ -46,7 +53,7 @@ jobs:
         working-directory: ${{ matrix.workspace }}
 
   npm:
-    if: fromJSON(needs.generate-matrix.outputs.exists)
+    if: github.ref == 'refs/heads/main' && fromJSON(needs.generate-matrix.outputs.exists)
     name: Publish ${{ matrix.name }}@${{matrix.version}} to NPM
     runs-on: ubuntu-latest
 
@@ -77,7 +84,7 @@ jobs:
           NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
 
   tag:
-    if: fromJSON(needs.generate-matrix.outputs.exists)
+    if: github.ref == 'refs/heads/main' && fromJSON(needs.generate-matrix.outputs.exists)
     name: "Tag Release"
     runs-on: ubuntu-latest
     needs: [generate-matrix, jsr, npm]

.github/workflows/verify-posix.yaml

@@ -1,9 +1,7 @@
 name: Verify (POSIX)
 
 on:
-  push:
-    branches:
-      - main
+  workflow_call:
   pull_request:
     branches:
       - main
@@ -34,5 +32,11 @@ jobs:
       - run: deno fmt --check
 
       - run: deno lint
+      - run: deno task generate-importmap "^3" v3.importmap.json
+      - run: deno task generate-importmap v4 v4.importmap.json
+
+      - name: V3 Tests
+        run: deno test --import-map v3.importmap.json --allow-net --allow-read --allow-write --allow-env --allow-run --allow-ffi
 
-      - run: deno test --allow-net --allow-read --allow-write --allow-env --allow-run --allow-ffi
+      - name: V4 Tests
+        run: deno test --import-map v4.importmap.json --allow-net --allow-read --allow-write --allow-env --allow-run --allow-ffi --trace-leaks

.github/workflows/verify-windows.yaml

@@ -1,9 +1,7 @@
 name: Verify (Windows)
 
 on:
-  push:
-    branches:
-      - main
+  workflow_call:
   pull_request:
     branches:
       - main
@@ -41,20 +39,41 @@ jobs:
 
       - run: deno lint
 
-      - name: "Test (${{matrix.shell}})"
+      - run: deno task generate-importmap "^3" v3.importmap.json
+      - run: deno task generate-importmap v4 v4.importmap.json
+
+      - name: "Test V3 (${{matrix.shell}})"
+        if: matrix.shell == 'powershell' || matrix.shell == 'pwsh'
+        run: |
+          $env:SHELL = "${{matrix.shell}}"
+          deno test --import-map v3.importmap.json --allow-net --allow-read --allow-write --allow-env --allow-run --allow-ffi --trace-leaks
+
+      - name: "Test V4 (${{matrix.shell}})"
         if: matrix.shell == 'powershell' || matrix.shell == 'pwsh'
         run: |
           $env:SHELL = "${{matrix.shell}}"
-          deno test --allow-net --allow-read --allow-write --allow-env --allow-run --allow-ffi --trace-leaks
+          deno test --import-map v4.importmap.json --allow-net --allow-read --allow-write --allow-env --allow-run --allow-ffi --trace-leaks
 
-      - name: "Test (${{matrix.shell}})"
+      - name: "Test V3 (${{matrix.shell}})"
         if: matrix.shell == 'cmd'
         run: |
           set SHELL=${{matrix.shell}}
-          deno test --allow-net --allow-read --allow-write --allow-env --allow-run --allow-ffi --trace-leaks
+          deno test --import-map v3.importmap.json --allow-net --allow-read --allow-write --allow-env --allow-run --allow-ffi --trace-leaks
+
+      - name: "Test V4 (${{matrix.shell}})"
+        if: matrix.shell == 'cmd'
+        run: |
+          set SHELL=${{matrix.shell}}
+          deno test --import-map v4.importmap.json --allow-net --allow-read --allow-write --allow-env --allow-run --allow-ffi --trace-leaks
+
+      - name: "Test V3 (${{matrix.shell}})"
+        if: matrix.shell == 'bash'
+        run: |
+          export SHELL=${{matrix.shell}}
+          deno test --import-map v3.importmap.json --allow-net --allow-read --allow-write --allow-env --allow-run --allow-ffi --trace-leaks
 
-      - name: "Test (${{matrix.shell}})"
+      - name: "Test V4 (${{matrix.shell}})"
         if: matrix.shell == 'bash'
         run: |
           export SHELL=${{matrix.shell}}
-          deno test --allow-net --allow-read --allow-write --allow-env --allow-run --allow-ffi --trace-leaks
+          deno test --import-map v4.importmap.json --allow-net --allow-read --allow-write --allow-env --allow-run --allow-ffi --trace-leaks

.gitignore

@@ -1,4 +1,6 @@
 /deno.lock
 /**/build/
+/v3.importmap.json
+/v4.importmap.json
 
 .vscode

README.md

@@ -15,6 +15,33 @@ more than a few times are welcome.
 5. Add doc strings to your source code - they will be used for documentation on
    the site.
 
+## Testing
+
+All packages are tested against both effection v3 and v4 to ensure
+compatibility.
+
+### Generate import maps
+
+```bash
+# Generate v3 import map
+deno task generate-importmap "^3" v3.importmap.json
+
+# Generate v4 import map (fetches latest v4 from npm)
+deno task generate-importmap v4 v4.importmap.json
+```
+
+### Running tests with v3
+
+```bash
+deno test --import-map v3.importmap.json -A
+```
+
+### Running tests with v4
+
+```bash
+deno test --import-map v4.importmap.json -A
+```
+
 ## To publish a new project
 
 1. Member of [jsr.io/@effectionx](https://jsr.io/@effectionx) has to add that

bdd/deno.json

@@ -1,11 +1,11 @@
 {
   "name": "@effectionx/bdd",
   "exports": "./mod.ts",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "license": "MIT",
   "imports": {
     "effection": "npm:effection@^3",
-    "@effectionx/test-adapter": "jsr:@effectionx/test-adapter@^0.1.0",
+    "@effectionx/test-adapter": "jsr:@effectionx/test-adapter@^0.5.1",
     "@std/testing": "jsr:@std/testing@^1"
   }
 }

bdd/mod.ts

@@ -6,24 +6,65 @@ import {
   it as $it,
 } from "@std/testing/bdd";
 
+/**
+ * Sanitization options for test cases and test suites.
+ * These options control Deno's test sanitizers.
+ */
+export interface SanitizeOptions {
+  /** Ensure the test case does not prematurely cause the process to exit. Defaults to true. */
+  sanitizeExit?: boolean;
+  /** Check that the number of async completed ops after the test is the same as number of dispatched ops. Defaults to true. */
+  sanitizeOps?: boolean;
+  /** Ensure the test case does not "leak" resources - ie. the resource table after the test has exactly the same contents as before the test. Defaults to true. */
+  sanitizeResources?: boolean;
+}
+
 let current: TestAdapter | undefined;
 
-export function describe(name: string, body: () => void) {
+export function describe(
+  name: string,
+  body: () => void,
+  options?: SanitizeOptions,
+) {
   const original = current;
   try {
     const child = current = createTestAdapter({ name, parent: original });
 
-    $describe(name, () => {
-      $afterAll(() => child.destroy());
-      body();
+    $describe({
+      name,
+      fn: () => {
+        $afterAll(() => child.destroy());
+        body();
+      },
+      ...options,
     });
   } finally {
     current = original;
   }
 }
 
 describe.skip = $describe.skip;
-describe.only = $describe.only;
+describe.only = function (
+  name: string,
+  body: () => void,
+  options?: SanitizeOptions,
+): void {
+  const original = current;
+  try {
+    const child = current = createTestAdapter({ name, parent: original });
+
+    $describe.only({
+      name,
+      fn: () => {
+        $afterAll(() => child.destroy());
+        body();
+      },
+      ...options,
+    });
+  } finally {
+    current = original;
+  }
+};
 
 export function beforeAll(body: () => Operation<void>) {
   current?.addOnetimeSetup(body);
@@ -33,17 +74,25 @@ export function beforeEach(body: () => Operation<void>) {
   current?.addSetup(body);
 }
 
-export function it(desc: string, body?: () => Operation<void>): void {
+export function it(
+  desc: string,
+  body?: () => Operation<void>,
+  options?: SanitizeOptions,
+): void {
   const adapter = current!;
   if (!body) {
     $it.skip(desc, () => {});
     return;
   }
-  $it(desc, async () => {
-    const result = await adapter.runTest(body);
-    if (!result.ok) {
-      throw result.error;
-    }
+  $it({
+    name: desc,
+    fn: async () => {
+      const result = await adapter.runTest(body);
+      if (!result.ok) {
+        throw result.error;
+      }
+    },
+    ...options,
   });
 }
 
@@ -52,12 +101,20 @@ it.skip = (...args: Parameters<typeof it>): ReturnType<typeof it> => {
   return $it.skip(desc, () => {});
 };
 
-it.only = (desc: string, body: () => Operation<void>): void => {
+it.only = (
+  desc: string,
+  body: () => Operation<void>,
+  options?: SanitizeOptions,
+): void => {
   const adapter = current!;
-  $it.only(desc, async () => {
-    const result = await adapter.runTest(body);
-    if (!result.ok) {
-      throw result.error;
-    }
+  $it.only({
+    name: desc,
+    fn: async () => {
+      const result = await adapter.runTest(body);
+      if (!result.ok) {
+        throw result.error;
+      }
+    },
+    ...options,
   });
 };

context-api/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectionx/context-api",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT",
   "exports": "./mod.ts",
   "imports": {

deno-deploy/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectionx/deno-deploy",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "exports": "./mod.ts",
   "license": "MIT",
   "imports": {

deno.json

@@ -3,7 +3,8 @@
     "effection": "npm:effection@^3",
     "@deno/dnt": "jsr:@deno/[email protected]",
     "@std/path": "jsr:@std/path@^1",
-    "zod": "npm:[email protected]"
+    "zod": "npm:[email protected]",
+    "@std/fs": "jsr:@std/fs@^1"
   },
   "compilerOptions": {
     "lib": [
@@ -20,7 +21,10 @@
         "prefer-const",
         "require-yield"
       ]
-    }
+    },
+    "exclude": [
+      "tasks"
+    ]
   },
   "workspace": [
     "./context-api",
@@ -39,5 +43,8 @@
     "./stream-helpers",
     "./signals",
     "./process"
-  ]
+  ],
+  "tasks": {
+    "generate-importmap": "deno run --allow-read --allow-write --allow-net tasks/generate-importmap.ts"
+  }
 }