@provino/env-node 0.0.0-stage → 0.1.0-rc.0
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 +21 -0
- package/README.md +8 -2
- package/dist/index.d.ts +47 -0
- package/dist/index.js +64 -0
- package/package.json +35 -3
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
|
-
#
|
|
1
|
+
# @provino/env-node
|
|
2
2
|
|
|
3
|
-
|
|
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 that is pre-alpha and not on npm yet. 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)
|
package/dist/index.d.ts
ADDED
|
@@ -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
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.1.0-rc.0",
|
|
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.0",
|
|
32
|
+
"@provino/types": "0.1.0-rc.0"
|
|
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
|
}
|