@esposter/shared-node 4.3.3 โ 4.5.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/README.md +19 -52
- package/dist/cache.d.ts +2 -1
- package/dist/cache.js +17 -9
- package/dist/child-process.d.ts +1 -0
- package/dist/child-process.js +5 -2
- package/dist/reporter.js +1 -2
- package/package.json +8 -8
package/README.md
CHANGED
|
@@ -5,37 +5,31 @@
|
|
|
5
5
|
[![NPM downloads][badge-npm-downloads]][url-npm]
|
|
6
6
|
[![NPM Unpacked Size (with version)][badge-npm-unpacked-size]][url-npm]
|
|
7
7
|
|
|
8
|
-
Node-only
|
|
8
|
+
Provides the Node-only tools that Esposter packages share: a machine-wide download cache, hidden-window child processes and benchmark reporting.
|
|
9
|
+
|
|
10
|
+
Design notes live in [the specs](https://github.com/Esposter/Esposter/tree/main/openspec/specs).
|
|
9
11
|
|
|
10
12
|
## Table of Contents
|
|
11
13
|
|
|
12
14
|
- ๐ [Getting Started](#getting-started)
|
|
13
|
-
-
|
|
15
|
+
- ๐งฉ [Key Exports](#key-exports)
|
|
14
16
|
- โ๏ธ [License](#license)
|
|
15
17
|
|
|
16
18
|
---
|
|
17
19
|
|
|
18
20
|
## <a name="getting-started">๐ Getting Started</a>
|
|
19
21
|
|
|
20
|
-
|
|
21
|
-
pnpm i @esposter/shared-node
|
|
22
|
-
```
|
|
22
|
+
Import this package only in a server or build environment, never in browser code.
|
|
23
23
|
|
|
24
|
-
|
|
25
|
-
import { spawnSync } from "@esposter/shared-node/child-process";
|
|
24
|
+
1. Install the package.
|
|
26
25
|
|
|
27
|
-
|
|
26
|
+
```bash
|
|
27
|
+
pnpm i @esposter/shared-node
|
|
28
28
|
```
|
|
29
29
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
We highly recommend you take a look at the [documentation](https://github.com/Esposter/Esposter/tree/main/openspec/specs) to level up.
|
|
33
|
-
|
|
34
|
-
### What's Included
|
|
35
|
-
|
|
36
|
-
The machine-wide download cache, the hidden-window child process wrappers, and the benchmark reporting toolkit consumed by the repo's `vitest bench` runs (see the `bench` skill).
|
|
30
|
+
Check: `package.json` lists `@esposter/shared-node` in its dependencies.
|
|
37
31
|
|
|
38
|
-
|
|
32
|
+
2. Run this code.
|
|
39
33
|
|
|
40
34
|
```ts
|
|
41
35
|
import { spawnSync } from "@esposter/shared-node/child-process";
|
|
@@ -43,43 +37,16 @@ import { spawnSync } from "@esposter/shared-node/child-process";
|
|
|
43
37
|
spawnSync("pnpm", ["install"], { stdio: "inherit" });
|
|
44
38
|
```
|
|
45
39
|
|
|
46
|
-
|
|
40
|
+
## <a name="key-exports">๐งฉ Key Exports</a>
|
|
47
41
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
)
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
| Export | Description |
|
|
58
|
-
| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
|
|
59
|
-
| `BenchmarkMarkdownReporter` | Vitest reporter โ writes `Foo.bench.md` + `Foo.bench.json` beside `Foo.bench.ts` |
|
|
60
|
-
| `BENCHMARK_RUN_OPTIONS` | Run options every `bench.compare` passes, fixing the iteration count |
|
|
61
|
-
| `buildBenchmarkFileReport` | Projects a module's reported tests into a structured `BenchmarkReport` |
|
|
62
|
-
| `formatBenchmarkMarkdown` | Renders a `BenchmarkReport` to Markdown tables |
|
|
63
|
-
| `writeBenchmarkReport` | Persists the JSON + Markdown report artifacts |
|
|
64
|
-
| `readBenchmarkEnvironment` | Captures CPU/OS/runtime metadata for reproducible results |
|
|
65
|
-
| `BenchmarkFile` ยท `BenchmarkGroup` ยท `BenchmarkReport` ยท `BenchmarkResult` ยท `BenchmarkTestCase` | Report data models |
|
|
66
|
-
|
|
67
|
-
### Architecture Notes
|
|
68
|
-
|
|
69
|
-
- **Node-only**: depends on Node built-ins (`fs`, `os`) โ must not be bundled into the browser app.
|
|
70
|
-
- Depends on `@esposter/shared` for shared types and utilities.
|
|
71
|
-
- Wired into `vitest bench` via `BenchmarkMarkdownReporter`; the emitted artifacts are committed and diffed offline as the speed gate.
|
|
72
|
-
|
|
73
|
-
### Commands
|
|
74
|
-
|
|
75
|
-
Run from `packages/shared-node/`:
|
|
76
|
-
|
|
77
|
-
```bash
|
|
78
|
-
pnpm build # compile to dist/
|
|
79
|
-
pnpm test # vitest watch mode (coverage is run from the repo root)
|
|
80
|
-
pnpm lint:fix # auto-fix lint
|
|
81
|
-
pnpm typecheck # type check
|
|
82
|
-
```
|
|
42
|
+
| Export | Description |
|
|
43
|
+
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
44
|
+
| `BENCHMARK_RUN_OPTIONS` (`/bench`) | Run options that every `bench.compare` call passes. They fix the iteration count. |
|
|
45
|
+
| `BenchmarkMarkdownReporter` (default export, `/reporter`) | Vitest reporter. Writes `Foo.bench.md` and `Foo.bench.json` beside `Foo.bench.ts`. |
|
|
46
|
+
| `spawn`, `spawnSync`, `execFile`, `execFileSync`, `execSync` (`/child-process`) | Node's own child-process functions. Each forces `windowsHide: true`, so a console child never opens a window of its own. |
|
|
47
|
+
| `execFileAsync` (`/child-process`) | The promisified `execFile`, with the same window flag. Resolves `{ stdout, stderr }`. |
|
|
48
|
+
| `CACHE_ROOT`, `readContentAddressedObject` (`/cache`) | The download cache folder that every checkout shares. A read-through cache for objects named by the hex SHA-256 of their bytes. |
|
|
49
|
+
| `writePartialThenMove` (`/cache`) | Writes a file whole. A partial file is written beside the path and renamed onto it once written, and it is removed when either step fails. |
|
|
83
50
|
|
|
84
51
|
## <a name="license">โ๏ธ License</a>
|
|
85
52
|
|
package/dist/cache.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
1
|
export declare const CACHE_ROOT: string;
|
|
2
2
|
export declare const CONTENT_CACHE_DIRECTORY: string;
|
|
3
|
-
export declare const readContentAddressedObject: (hash: string, download: () => Promise<Uint8Array>, directory?: string) => Promise<Buffer>;
|
|
3
|
+
export declare const readContentAddressedObject: (hash: string, download: () => Promise<Uint8Array>, directory?: string) => Promise<Buffer>;
|
|
4
|
+
export declare const writePartialThenMove: (path: string, write: (partialPath: string) => Promise<void>) => Promise<void>;
|
package/dist/cache.js
CHANGED
|
@@ -1,12 +1,24 @@
|
|
|
1
1
|
import { InvalidOperationError, Operation, SITE_NAME, getResultAsync, noop } from "@esposter/shared";
|
|
2
2
|
import { homedir } from "node:os";
|
|
3
|
-
import { join } from "node:path";
|
|
3
|
+
import { dirname, join } from "node:path";
|
|
4
|
+
import { existsSync, rmSync } from "node:fs";
|
|
5
|
+
import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
|
|
4
6
|
import { createHash } from "node:crypto";
|
|
5
|
-
import { existsSync } from "node:fs";
|
|
6
|
-
import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
|
|
7
7
|
// src/services/cache/constants.ts
|
|
8
8
|
const CACHE_ROOT = join(homedir(), SITE_NAME, "cache");
|
|
9
9
|
const CONTENT_CACHE_DIRECTORY = join(CACHE_ROOT, "content");
|
|
10
|
+
// src/services/cache/writePartialThenMove.ts
|
|
11
|
+
const writePartialThenMove = async (path, write) => {
|
|
12
|
+
await mkdir(dirname(path), { recursive: true });
|
|
13
|
+
const partialPath = `${path}.${crypto.randomUUID()}.part`;
|
|
14
|
+
(await getResultAsync(async () => {
|
|
15
|
+
await write(partialPath);
|
|
16
|
+
await rename(partialPath, path);
|
|
17
|
+
})).match(noop, (error) => {
|
|
18
|
+
rmSync(partialPath, { force: true });
|
|
19
|
+
throw error;
|
|
20
|
+
});
|
|
21
|
+
};
|
|
10
22
|
// src/services/cache/readContentAddressedObject.ts
|
|
11
23
|
const SHA_256_HEX_REGEX = /^[0-9a-f]{64}$/u;
|
|
12
24
|
const readContentAddressedObject = async (hash, download, directory = CONTENT_CACHE_DIRECTORY) => {
|
|
@@ -15,13 +27,9 @@ const readContentAddressedObject = async (hash, download, directory = CONTENT_CA
|
|
|
15
27
|
if (existsSync(path)) return readFile(path);
|
|
16
28
|
const bytes = Buffer.from(await download());
|
|
17
29
|
if (createHash("sha256").update(bytes).digest("hex") !== hash) throw new InvalidOperationError(Operation.Read, hash, "does not hash to its name");
|
|
18
|
-
await
|
|
19
|
-
const temporaryPath = `${path}.${crypto.randomUUID()}.part`;
|
|
20
|
-
await writeFile(temporaryPath, bytes);
|
|
21
|
-
await getResultAsync(() => rename(temporaryPath, path)).match(noop, async (error) => {
|
|
22
|
-
await rm(temporaryPath, { force: true });
|
|
30
|
+
await getResultAsync(() => writePartialThenMove(path, (partialPath) => writeFile(partialPath, bytes))).match(noop, (error) => {
|
|
23
31
|
if (!existsSync(path)) throw error;
|
|
24
32
|
});
|
|
25
33
|
return bytes;
|
|
26
34
|
};
|
|
27
|
-
export { CACHE_ROOT, CONTENT_CACHE_DIRECTORY, readContentAddressedObject };
|
|
35
|
+
export { CACHE_ROOT, CONTENT_CACHE_DIRECTORY, readContentAddressedObject, writePartialThenMove };
|
package/dist/child-process.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { execFile as execFile$1, execFileSync as execFileSync$1, execSync as execSync$1, spawn as spawn$1, spawnSync as spawnSync$1 } from "node:child_process";
|
|
2
2
|
export declare const execFile: typeof execFile$1;
|
|
3
|
+
export declare const execFileAsync: typeof execFile$1.__promisify__;
|
|
3
4
|
export declare const execFileSync: typeof execFileSync$1;
|
|
4
5
|
export declare const execSync: typeof execSync$1;
|
|
5
6
|
export declare const spawn: typeof spawn$1;
|
package/dist/child-process.js
CHANGED
|
@@ -3,11 +3,14 @@ import { execFile as execFile$1, execFileSync as execFileSync$1, spawn as spawn$
|
|
|
3
3
|
import { promisify } from "node:util";
|
|
4
4
|
// src/services/childProcess/execFile.ts
|
|
5
5
|
const execFile = ((file, ...parameters) => execFile$1(file, ...withHiddenWindow(parameters)));
|
|
6
|
-
Object.defineProperty(execFile, promisify.custom, { value: (file, ...parameters) =>
|
|
6
|
+
Object.defineProperty(execFile, promisify.custom, { value: (file, ...parameters) => {
|
|
7
|
+
return promisify(execFile$1)(file, ...withHiddenWindow(parameters));
|
|
8
|
+
} });
|
|
9
|
+
const execFileAsync = promisify(execFile);
|
|
7
10
|
// src/services/childProcess/execFileSync.ts
|
|
8
11
|
const execFileSync = ((file, ...parameters) => execFileSync$1(file, ...withHiddenWindow(parameters)));
|
|
9
12
|
// src/services/childProcess/spawn.ts
|
|
10
13
|
const spawn = ((file, ...parameters) => spawn$1(file, ...withHiddenWindow(parameters)));
|
|
11
14
|
// src/services/childProcess/spawnSync.ts
|
|
12
15
|
const spawnSync = ((file, ...parameters) => spawnSync$1(file, ...withHiddenWindow(parameters)));
|
|
13
|
-
export { execFile, execFileSync, execSync, spawn, spawnSync };
|
|
16
|
+
export { execFile, execFileAsync, execFileSync, execSync, spawn, spawnSync };
|
package/dist/reporter.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import "./bench.js";
|
|
2
1
|
import { t as execSync } from "./execSync-DCcbOCo8.js";
|
|
2
|
+
import "./bench.js";
|
|
3
3
|
import { GIBIBYTE, InvalidOperationError, Operation, getResult, getResultAsync, noop, normalizeString, takeOne } from "@esposter/shared";
|
|
4
4
|
import { arch, cpus, platform, release, totalmem } from "node:os";
|
|
5
5
|
import { writeFile } from "node:fs/promises";
|
|
@@ -11,7 +11,6 @@ const readCommit = () => getResult(() => execSync("git rev-parse --short HEAD",
|
|
|
11
11
|
const readBenchmarkEnvironment = () => {
|
|
12
12
|
const cpu = cpus();
|
|
13
13
|
return [
|
|
14
|
-
`- Date: ${(/* @__PURE__ */ new Date()).toISOString()}`,
|
|
15
14
|
`- Commit: ${readCommit()}`,
|
|
16
15
|
`- Node: ${process.version}`,
|
|
17
16
|
`- OS: ${platform()} ${release()} (${arch()})`,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@esposter/shared-node",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.5.0",
|
|
4
4
|
"description": "Node-only shared tooling: the machine-wide download cache, hidden-window child processes, and benchmark reporting reused across packages.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"benchmark",
|
|
@@ -47,23 +47,23 @@
|
|
|
47
47
|
"lint": "eslint .",
|
|
48
48
|
"lint:fix": "eslint --fix .",
|
|
49
49
|
"test": "vitest",
|
|
50
|
-
"typecheck": "
|
|
50
|
+
"typecheck": "tsrs --fast"
|
|
51
51
|
},
|
|
52
52
|
"dependencies": {
|
|
53
|
-
"@esposter/shared": "4.
|
|
53
|
+
"@esposter/shared": "4.5.0"
|
|
54
54
|
},
|
|
55
55
|
"devDependencies": {
|
|
56
|
-
"@esposter/configuration": "4.
|
|
57
|
-
"@types/node": "^26.6.
|
|
58
|
-
"tsdown": "^0.23.
|
|
56
|
+
"@esposter/configuration": "4.5.0",
|
|
57
|
+
"@types/node": "^26.6.6",
|
|
58
|
+
"tsdown": "^0.23.5"
|
|
59
59
|
},
|
|
60
60
|
"peerDependencies": {
|
|
61
|
-
"vitest": "^5.0
|
|
61
|
+
"vitest": "^5.1.0"
|
|
62
62
|
},
|
|
63
63
|
"peerDependenciesMeta": {
|
|
64
64
|
"vitest": {
|
|
65
65
|
"optional": true
|
|
66
66
|
}
|
|
67
67
|
},
|
|
68
|
-
"gitHead": "
|
|
68
|
+
"gitHead": "e30c001f3b4b15693e75fb53092d62a97ade4d2b"
|
|
69
69
|
}
|