@provino/env-node 0.0.0-stage → 0.1.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Pixel Perfect Software
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,9 @@
1
- # Temporary Holding Version
1
+ # @provino/env-node
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The Node test environment: test code sees the worker's own global, and after each file the environment puts the global back exactly as it was, down to property descriptors.
4
+
5
+ This package is a building block of [Provino](https://github.com/pixel-perfect-software/provino), a test runner for Jest projects, on npm as [`provino`](https://www.npmjs.com/package/provino). The `provino` package ships every `@provino/*` package inlined in one bundle, so you install `provino`, not this package.
6
+
7
+ **Versioning:** this package's public API is held to semver before 1.0: its API report is committed in the repository, under `etc/`, and a change to a `@public` signature needs a changeset.
8
+
9
+ [MIT](https://github.com/pixel-perfect-software/provino/blob/main/LICENSE)
@@ -0,0 +1,47 @@
1
+ import { Environment } from "@provino/types";
2
+ /**
3
+ * The Node test environment.
4
+ *
5
+ * `setup` returns the worker's `globalThis` and remembers every own property of it, string and
6
+ * symbol keys, with its descriptor. `teardown` puts the global back: it deletes the keys added
7
+ * since, and redefines every key whose descriptor changed or that was deleted, comparing values
8
+ * and accessor functions by identity and the flags (`writable`, `enumerable`, `configurable`) by
9
+ * value. Afterwards the global's property names and every original descriptor equal the ones
10
+ * `setup` saw. A key that was deleted and restored moves to the end of its group (string keys,
11
+ * then symbols); the order of every key that was never deleted is kept.
12
+ *
13
+ * An assignment to a get/set accessor whose value lives in a closure (Node's `process`, `Buffer`
14
+ * and `performance`) leaves the descriptor unchanged, so `setup` wraps those setters: the first
15
+ * assignment records the old value, `teardown` assigns it back and puts the original setter back.
16
+ *
17
+ * With `processObject: 'per-file'` in the context, `setup` installs a copy of the worker's
18
+ * `process` for the file (`createFileProcess`: listeners and an `env` of its own, as Jest gives
19
+ * each file), and `teardown` puts the worker's back.
20
+ *
21
+ * A key that cannot be restored (an added property that is not configurable, so `delete` fails)
22
+ * is a warning, not a failure (decision D22): `teardown` restores everything else, then returns
23
+ * an `EnvironmentTeardownReport` that names the keys in `leakedGlobals`. The file passes; the
24
+ * worker warns and tells the coordinator, which recycles the worker. A clean teardown returns
25
+ * nothing. The isolation tier `realm` gives each file its own global.
26
+ *
27
+ * Call it once per file (scope `file`) or once per worker (scope `worker`). Only the `worker`
28
+ * realm is supported: `setup` throws `ENV_NODE_REALM_UNSUPPORTED` for `context`.
29
+ * @public
30
+ */
31
+ export declare const nodeEnvironment: Environment<"node">;
32
+ /**
33
+ * Stable codes for `@provino/env-node` errors, so callers and tests assert on the code, not the
34
+ * text.
35
+ * @public
36
+ */
37
+ type NodeEnvironmentErrorCode = "ENV_NODE_REALM_UNSUPPORTED";
38
+ /**
39
+ * An error from the Node environment. A global it cannot restore is not an error: `teardown`
40
+ * reports those (decision D22).
41
+ * @public
42
+ */
43
+ export declare class NodeEnvironmentError extends Error {
44
+ readonly code: NodeEnvironmentErrorCode;
45
+ constructor(code: NodeEnvironmentErrorCode, message: string);
46
+ }
47
+ export type { NodeEnvironmentErrorCode };
package/dist/index.js ADDED
@@ -0,0 +1,64 @@
1
+ import { createFileProcess, leakReport, snapshotProperties } from "@provino/env-shared";
2
+
3
+ // src/errors.ts
4
+ /**
5
+ * An error from the Node environment. A global it cannot restore is not an error: `teardown`
6
+ * reports those (decision D22).
7
+ * @public
8
+ */
9
+ var NodeEnvironmentError = class extends Error {
10
+ code;
11
+ constructor(code, message) {
12
+ super(message);
13
+ this.name = "NodeEnvironmentError";
14
+ this.code = code;
15
+ }
16
+ };
17
+
18
+ // src/environment.ts
19
+ /**
20
+ * The Node test environment.
21
+ *
22
+ * `setup` returns the worker's `globalThis` and remembers every own property of it, string and
23
+ * symbol keys, with its descriptor. `teardown` puts the global back: it deletes the keys added
24
+ * since, and redefines every key whose descriptor changed or that was deleted, comparing values
25
+ * and accessor functions by identity and the flags (`writable`, `enumerable`, `configurable`) by
26
+ * value. Afterwards the global's property names and every original descriptor equal the ones
27
+ * `setup` saw. A key that was deleted and restored moves to the end of its group (string keys,
28
+ * then symbols); the order of every key that was never deleted is kept.
29
+ *
30
+ * An assignment to a get/set accessor whose value lives in a closure (Node's `process`, `Buffer`
31
+ * and `performance`) leaves the descriptor unchanged, so `setup` wraps those setters: the first
32
+ * assignment records the old value, `teardown` assigns it back and puts the original setter back.
33
+ *
34
+ * With `processObject: 'per-file'` in the context, `setup` installs a copy of the worker's
35
+ * `process` for the file (`createFileProcess`: listeners and an `env` of its own, as Jest gives
36
+ * each file), and `teardown` puts the worker's back.
37
+ *
38
+ * A key that cannot be restored (an added property that is not configurable, so `delete` fails)
39
+ * is a warning, not a failure (decision D22): `teardown` restores everything else, then returns
40
+ * an `EnvironmentTeardownReport` that names the keys in `leakedGlobals`. The file passes; the
41
+ * worker warns and tells the coordinator, which recycles the worker. A clean teardown returns
42
+ * nothing. The isolation tier `realm` gives each file its own global.
43
+ *
44
+ * Call it once per file (scope `file`) or once per worker (scope `worker`). Only the `worker`
45
+ * realm is supported: `setup` throws `ENV_NODE_REALM_UNSUPPORTED` for `context`.
46
+ * @public
47
+ */
48
+ const nodeEnvironment = {
49
+ name: "node",
50
+ realms: ["worker"],
51
+ setup(context) {
52
+ if (context.realm !== "worker") throw new NodeEnvironmentError("ENV_NODE_REALM_UNSUPPORTED", `The node environment supports the 'worker' realm only, not '${context.realm}'. A vm-context global needs the 'realm' isolation tier (T2.8).`);
53
+ const snapshot = snapshotProperties(globalThis);
54
+ if (context.processObject === "per-file") globalThis.process = createFileProcess();
55
+ return {
56
+ global: globalThis,
57
+ teardown() {
58
+ return leakReport(snapshot.restore());
59
+ }
60
+ };
61
+ }
62
+ };
63
+
64
+ export { NodeEnvironmentError, nodeEnvironment };
package/package.json CHANGED
@@ -1,6 +1,38 @@
1
1
  {
2
2
  "name": "@provino/env-node",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0-rc.1",
4
+ "description": "Provino's Node test environment: the worker's own global, put back exactly as it was after each file.",
5
+ "homepage": "https://github.com/pixel-perfect-software/provino#readme",
6
+ "bugs": {
7
+ "url": "https://github.com/pixel-perfect-software/provino/issues"
8
+ },
9
+ "repository": {
10
+ "type": "git",
11
+ "url": "git+https://github.com/pixel-perfect-software/provino.git",
12
+ "directory": "packages/env-node"
13
+ },
14
+ "license": "MIT",
15
+ "type": "module",
16
+ "sideEffects": false,
17
+ "exports": {
18
+ ".": {
19
+ "provino-source": "./src/index.ts",
20
+ "types": "./dist/index.d.ts",
21
+ "import": "./dist/index.js"
22
+ }
23
+ },
24
+ "files": [
25
+ "dist"
26
+ ],
27
+ "engines": {
28
+ "node": "^22.15.0 || >=24"
29
+ },
30
+ "dependencies": {
31
+ "@provino/env-shared": "0.1.0-rc.1",
32
+ "@provino/types": "0.1.0-rc.1"
33
+ },
34
+ "scripts": {
35
+ "build": "tsdown --config ../../tooling/packaging/tsdown.config.ts",
36
+ "test": "node --test --conditions=provino-source \"src/**/*.test.ts\""
37
+ }
6
38
  }