@node-projects/speedscope 0.0.0-stage → 2.0.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.
@@ -0,0 +1,94 @@
1
+ # Large trace performance follow-up
2
+
3
+ Baseline: `eb93425`, reviewed 2026-11-18. These changes continue the open-issue
4
+ review, prioritizing large profiles and the export request in issue #89.
5
+
6
+ ## Changes
7
+
8
+ - Both profile builders index grouped children once a node reaches 16 children.
9
+ Narrow nodes keep the small linear scan; construction indexes are released at
10
+ build completion. Wide/inverted trees no longer scan thousands of siblings for
11
+ every sample. Existing frame identities are reused without allocating candidates.
12
+ - Evented builders skip frame/node weight updates when the timestamp delta is zero.
13
+ Deep enter/leave sequences at identical timestamps avoid repeated depth scans.
14
+ - Folded input produces samples one at a time. Text readers also yield lines
15
+ lazily across decoded chunks, avoiding arrays of every line/sample in the file.
16
+ - V8 heap profiles use an iterative, allocation-driven traversal instead of
17
+ recursive indexing/size passes and materialized ancestor paths. Empty branches
18
+ stay empty, and the importer no longer retains call-frame objects in a global
19
+ cache. A 20,000-level heap regression verifies depth handling and byte totals.
20
+ - Interactive export uses a lazy call-event iterator and JSON Blob chunks. It
21
+ yields every 16,384 events and 4,096 source frames using message tasks (with a
22
+ timer fallback), reports progress and supports
23
+ cancellation. It does not construct another full event-object tree or a single
24
+ trace-sized JSON string. Downloads release their object URLs after starting.
25
+ - Known aggregate importers (folded, Callgrind, pprof, Haskell, PMCStat, Instruments
26
+ table copies and V8 heap trees) and derived aggregate profiles disable Time Order. Optional
27
+ `isChronological` and `isDerived` fields in this fork's file format retain those
28
+ properties through export/reimport. Existing files default to chronological,
29
+ original captures when metadata is absent. Cloning/export no longer loses derived provenance and causes
30
+ combined views to be counted again when originals are combined.
31
+
32
+ ## Local measurements
33
+
34
+ Single-process Node smoke measurements on this Windows machine; timings and
35
+ garbage collection vary. The PLC capture contains 1,039,851 input events and four
36
+ profiles. Its export contains 1,039,656 call events and 17,510 source frames.
37
+ Private capture data is not committed.
38
+
39
+ | Operation | Baseline | Updated |
40
+ | --- | ---: | ---: |
41
+ | Combine PLC profiles | 427 ms | 368 ms |
42
+ | Invert combined PLC stacks | 5,315 ms | 562 ms |
43
+ | Group combined PLC stacks by file | 29 ms | 26 ms |
44
+ | Import 500,000 repeated folded stacks | 657 ms | 451 ms |
45
+ | Folded import heap at completion | 276 MiB | 62 MiB |
46
+ | Folded process peak RSS | 449 MiB | 177 MiB |
47
+
48
+ The folded fixture is 500,000 repetitions of `root;main;worker;leaf 1`. It
49
+ isolates temporary parsing allocations; real captures with many distinct stacks
50
+ retain more call-tree data. Both implementations produce total weight 500,000.
51
+ The PLC transformations preserve the combined busy weight exactly.
52
+
53
+ For the 52,619,139-byte PLC JSON export, the legacy blocking serializer on the
54
+ current profile model took 410 ms with sampled peak JS heap of 301 MiB. The new
55
+ cooperative serializer took 857 ms with sampled peak heap of 237 MiB and 73
56
+ progress updates. Starting heap after forced collection was 131 MiB in each case.
57
+ This reduces sampled additional export heap from 170 to 106 MiB, with higher elapsed
58
+ time in exchange for responsive progress and cancellation. Process peak RSS stayed
59
+ around 984–987 MiB because input parsing dominates it. These samples do not prove
60
+ a hard memory bound or a cross-browser speedup.
61
+
62
+ To reproduce against an available capture:
63
+
64
+ ```powershell
65
+ node scripts/benchmark-profile.mjs "C:\path\capture.trace.gz" all
66
+ node scripts/benchmark-profile.mjs "C:\path\capture.trace.gz" import
67
+ node scripts/benchmark-profile.mjs "C:\path\capture.trace.gz" legacy-export
68
+ node scripts/benchmark-profile.mjs "C:\path\capture.trace.gz" export
69
+ ```
70
+
71
+ The wrapper bundles the existing importer with embedded WASM and runs a separate
72
+ Node process. `all` measures aggregate transforms; `import` reports completion heap
73
+ and peak RSS. Export modes force collection after import before measuring export.
74
+ Run benchmarks without other CPU/memory-heavy jobs. `legacy-export` remains a
75
+ benchmark comparison; interactive downloads use cooperative serialization.
76
+
77
+ ## Verification and remaining limits
78
+
79
+ Regression tests cover wide-node lookup bounds and frame identity, restarting
80
+ construction after sorting, deep recursive weight accounting, lazy Unicode line
81
+ iteration, exact JSON/export round trips, cancellation before/during event and
82
+ source-frame batches, URL cleanup, aggregate navigation and persisted provenance.
83
+
84
+ Browser testing with the PLC capture verified visible progress, cancellation,
85
+ completed download, disabled Time Order for aggregates and combined-stack
86
+ inversion. The downloaded JSON was compared exactly with the standard exporter,
87
+ then reimported with all profile totals preserved.
88
+
89
+ Import parsing and derived transformations still run on the main thread. They
90
+ remain in-memory operations; lazy folded parsing does not make JSON or binary
91
+ imports streaming. Export retains the final Blob bytes and source profile, while
92
+ bounding temporary serialization chunks (apart from an individually huge string).
93
+ Worker-backed import/transforms, cancellation during import, signed comparisons
94
+ and synchronized multitrack timelines remain separate architectural follow-ups.
@@ -0,0 +1,113 @@
1
+ # Hosting and publishing
2
+
3
+ Repository: [node-projects/speedscope](https://github.com/node-projects/speedscope).
4
+ Package: [`@node-projects/speedscope`](https://www.npmjs.com/package/@node-projects/speedscope).
5
+ Hosted application: [node-projects.github.io/speedscope](https://node-projects.github.io/speedscope/).
6
+ The npm command remains `speedscope`; Node.js 22+ is required for the CLI.
7
+
8
+ ## GitHub Actions
9
+
10
+ | Workflow | Trigger | Result |
11
+ | --- | --- | --- |
12
+ | [ci.yml](../.github/workflows/ci.yml) | PR, push to `main`, manual | Tests Node.js 22/24 on Linux/Windows, checks npm contents and uploads offline ZIPs. |
13
+ | [pages.yml](../.github/workflows/pages.yml) | Push to `main`, manual | Tests, builds `dist/pages` and deploys GitHub Pages. |
14
+ | [release.yml](../.github/workflows/release.yml) | Published GitHub release, manual retry | Uses the release tag as the npm version, tests, packs, attaches archives and publishes to npm. |
15
+
16
+ ## Pages setup
17
+
18
+ In repository **Settings → Pages → Build and deployment**, select **GitHub Actions**
19
+ as the source. This repository is configured for workflow deployment. The deploy
20
+ job uses the `github-pages` environment with `pages: write` and `id-token: write`.
21
+ No custom domain or upstream `speedscope.app` CNAME is installed.
22
+
23
+ The site uses relative asset URLs and works at the `/speedscope/` project path.
24
+ `npm run build:pages` creates the HTTP site, schema and release metadata in
25
+ `dist/pages`. It does not overwrite the offline npm build in `dist/release`.
26
+ Local profile imports stay in the browser; profileURL requests fetch from the
27
+ explicitly requested host and require that host's CORS permission.
28
+
29
+ To redeploy the current `main`, use the Actions page or:
30
+
31
+ ```sh
32
+ gh workflow run pages.yml --repo node-projects/speedscope --ref main
33
+ ```
34
+
35
+ ## First publication: 2.0.0
36
+
37
+ The first fork version is **2.0.0**, published manually by the maintainer. After
38
+ the package has been prepared and checked, sign in to npm with an account allowed
39
+ to publish under `@node-projects`, then run:
40
+
41
+ ```sh
42
+ npm ci
43
+ npm test
44
+ npm publish --access public
45
+ ```
46
+
47
+ `prepack` builds the offline app automatically. This first publication does not
48
+ require GitHub OIDC. Once it succeeds, configure the trusted publisher below.
49
+ Creating a `v2.0.0` GitHub release afterward is safe: the workflow detects the
50
+ existing npm version, attaches its standalone ZIP and skips re-publishing npm.
51
+ For a new version, it attaches the newly built npm tarball as well.
52
+
53
+ ## npm trusted publishing after the first publication
54
+
55
+ The workflow is prepared for npm trusted publishing (OIDC), with Node.js 24 and
56
+ `id-token: write`. Configure the package's trusted publisher on npm with:
57
+
58
+ - Organization/user: `node-projects`
59
+ - Repository: `speedscope`
60
+ - Workflow filename: `release.yml`
61
+ - Environment: leave empty (the npm job does not use an environment)
62
+ - Allow the `npm publish` action.
63
+
64
+ See [npm's trusted publisher setup](https://docs.npmjs.com/trusted-publishers/).
65
+ The repository URL in package.json points to this fork, as required for provenance.
66
+
67
+ The workflow uses OIDC and needs no npm token secret. The npm account setup can
68
+ only be completed after the package exists and by an authorized npm maintainer.
69
+ Keep the workflow filename and repository settings exact. Allow direct `npm publish`
70
+ for this publisher. There is no npm credential included in this repository.
71
+
72
+ The npm version badge and installation command become available after the first
73
+ successful publication. Creating workflows alone does not register an npm package.
74
+
75
+ ## Publish a release
76
+
77
+ 1. Merge the desired code, including these workflows, to `main` and wait for CI.
78
+ 2. Create a GitHub release pointing to that commit with a new tag such as `v2.0.1`
79
+ (or `2.0.1`). Release titles are descriptive; the **tag** determines the version.
80
+ 3. Publish the release. The workflow checks out the tag, sets package.json and
81
+ package-lock.json to `2.0.1` in the runner, tests and packs the application.
82
+ 4. The workflow attaches `speedscope-2.0.1.zip` and the scoped npm `.tgz` to the
83
+ GitHub release, then publishes the same tarball to npm with provenance.
84
+
85
+ Use a canonical SemVer tag, optionally prefixed by lowercase `v`. Versions with
86
+ prerelease identifiers (for example `v2.1.0-rc.1`) use npm's `next` dist-tag.
87
+ Marking a GitHub release as a prerelease also selects `next`. Stable releases use
88
+ `latest`. Build metadata (`+...`), abbreviated versions and leading-zero numeric
89
+ identifiers are rejected. Draft releases do not publish.
90
+
91
+ The checked-in package version is a development baseline. Release version changes
92
+ are confined to the runner; the workflow does not create another commit or tag.
93
+ npm versions are immutable: choose a new version for changed release contents.
94
+ Pages follows `main` independently, so publishing an older release cannot roll
95
+ the hosted site back.
96
+
97
+ If publishing fails after archives were attached (for example before npm auth was
98
+ configured), fix authorization and manually run **Publish npm release**, supplying
99
+ the existing release tag. The release must already exist and be non-draft. Retry
100
+ with the existing tag. If that npm version already exists, the workflow skips npm
101
+ publishing and leaves its immutable contents and distribution tags unchanged.
102
+
103
+ For local packaging checks without publishing:
104
+
105
+ ```sh
106
+ npm test
107
+ npm run prepack
108
+ npm pack --dry-run --ignore-scripts
109
+ ```
110
+
111
+ The offline archive includes local fonts and embedded JFR WASM. Extract the ZIP
112
+ and open `index.html`. The published npm package includes the CLI, offline app and
113
+ `FileFormat` types, with the upstream MIT license retained.
package/package.json CHANGED
@@ -1,6 +1,117 @@
1
1
  {
2
2
  "name": "@node-projects/speedscope",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "2.0.0",
4
+ "description": "A fast, interactive performance profile viewer with large-trace improvements, an accessible call tree and offline CLI.",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/node-projects/speedscope.git"
8
+ },
9
+ "homepage": "https://node-projects.github.io/speedscope/",
10
+ "bugs": {
11
+ "url": "https://github.com/node-projects/speedscope/issues"
12
+ },
13
+ "engines": {
14
+ "node": ">=22"
15
+ },
16
+ "publishConfig": {
17
+ "access": "public",
18
+ "registry": "https://registry.npmjs.org/"
19
+ },
20
+ "types": "src/lib/file-format-spec.ts",
21
+ "bin": {
22
+ "speedscope": "./bin/cli.mjs"
23
+ },
24
+ "scripts": {
25
+ "build:pages": "node scripts/prepare-release.mjs --protocol http",
26
+ "deploy": "gh workflow run pages.yml --ref main",
27
+ "release:version": "node scripts/set-release-version.mjs",
28
+ "prepack": "node scripts/prepare-release.mjs",
29
+ "prettier": "prettier --write \"src/**/*.ts\" \"src/**/*.tsx\"",
30
+ "lint": "eslint \"src/**/*.ts\" \"src/**/*.tsx\"",
31
+ "jest": "node scripts/test-setup.mjs && jest --runInBand",
32
+ "coverage": "npm run jest -- --coverage",
33
+ "typecheck": "tsc --noEmit",
34
+ "test:node": "node --test bin/server.test.mjs scripts/set-release-version.test.mjs",
35
+ "schema:check": "node scripts/generate-file-format-schema-json.js --check",
36
+ "test": "npm run typecheck && npm run lint && npm run jest && npm run test:node && npm run schema:check",
37
+ "serve": "tsx scripts/dev-server.ts"
38
+ },
39
+ "files": [
40
+ "src/lib/file-format-spec.ts",
41
+ "docs/RELEASING.md",
42
+ "docs/LARGE_TRACE_PERFORMANCE.md",
43
+ "bin/cli.mjs",
44
+ "bin/server.mjs",
45
+ "dist/release/**",
46
+ "!*.map"
47
+ ],
48
+ "browserslist": [
49
+ "last 2 Chrome versions",
50
+ "last 2 Firefox versions"
51
+ ],
52
+ "author": {
53
+ "name": "node-projects",
54
+ "url": "https://github.com/node-projects"
55
+ },
56
+ "license": "MIT",
57
+ "devDependencies": {
58
+ "@types/jest": "22.2.3",
59
+ "@types/jszip": "3.1.4",
60
+ "@types/node": "14.0.1",
61
+ "@types/pako": "1.0.0",
62
+ "@typescript-eslint/eslint-plugin": "6.16.0",
63
+ "@typescript-eslint/parser": "6.16.0",
64
+ "acorn": "7.2.0",
65
+ "aphrodite": "2.1.0",
66
+ "esbuild": "0.27.0",
67
+ "esbuild-jest": "0.5.0",
68
+ "eslint": "8.0.0",
69
+ "eslint-plugin-prettier": "5.1.2",
70
+ "eslint-plugin-react-hooks": "4.6.0",
71
+ "jest": "30.2.0",
72
+ "jest-environment-jsdom": "29.7.0",
73
+ "jfrview": "0.2.0",
74
+ "jsverify": "0.8.3",
75
+ "jszip": "3.1.5",
76
+ "pako": "1.0.6",
77
+ "preact": "10.4.1",
78
+ "prettier": "3.1.1",
79
+ "protobufjs": "6.8.8",
80
+ "source-map": "0.6.1",
81
+ "ts-jest": "29.4.6",
82
+ "tsx": "4.19.2",
83
+ "typescript": "5.9.3",
84
+ "typescript-json-schema": "0.67.0",
85
+ "uglify-es": "3.2.2",
86
+ "uint8array-json-parser": "0.0.2"
87
+ },
88
+ "jest": {
89
+ "testEnvironment": "jsdom",
90
+ "transform": {
91
+ "^.+\\.tsx?$": "ts-jest",
92
+ "^.+\\.js$": "esbuild-jest"
93
+ },
94
+ "transformIgnorePatterns": [],
95
+ "setupFilesAfterEnv": [
96
+ "./src/jest-setup.js"
97
+ ],
98
+ "moduleNameMapper": {
99
+ "\\jfrview_bg.wasm$": "<rootDir>/src/import/java-flight-record.mock.ts"
100
+ },
101
+ "testRegex": "\\.test\\.tsx?$",
102
+ "collectCoverageFrom": [
103
+ "**/*.{ts,tsx}",
104
+ "!**/*.d.{ts,tsx}"
105
+ ],
106
+ "moduleFileExtensions": [
107
+ "ts",
108
+ "tsx",
109
+ "js",
110
+ "jsx",
111
+ "json"
112
+ ]
113
+ },
114
+ "dependencies": {
115
+ "open": "10.1.0"
116
+ }
117
+ }
@@ -0,0 +1,150 @@
1
+ // This file contains types which specify the speedscope file format.
2
+
3
+ export namespace FileFormat {
4
+ export type Profile = EventedProfile | SampledProfile
5
+
6
+ export interface File {
7
+ $schema: 'https://www.speedscope.app/file-format-schema.json'
8
+
9
+ // Data shared between profiles
10
+ shared: {
11
+ frames: Frame[]
12
+ }
13
+
14
+ // List of profile definitions
15
+ profiles: Profile[]
16
+
17
+ // The name of the contained profile group. If omitted, will use the name of
18
+ // the file itself.
19
+ // Added in 0.6.0
20
+ name?: string
21
+
22
+ // The index into the `profiles` array that should be displayed upon file
23
+ // load. If omitted, will default to displaying the first profile in the
24
+ // file.
25
+ //
26
+ // Added in 0.6.0
27
+ activeProfileIndex?: number
28
+
29
+ // The name of the the program which exported this profile. This isn't
30
+ // consumed but can be helpful for debugging generated data by seeing what
31
+ // was generating it! Recommended format is "name@version". e.g. when the
32
+ // file was exported by speedscope v0.6.0 itself, it will be
33
+ // "speedscope@0.6.0"
34
+ //
35
+ // Added in 0.6.0
36
+ exporter?: string
37
+ }
38
+
39
+ export interface Frame {
40
+ name: string
41
+ file?: string
42
+ line?: number
43
+ col?: number
44
+ }
45
+
46
+ export enum ProfileType {
47
+ EVENTED = 'evented',
48
+ SAMPLED = 'sampled',
49
+ }
50
+
51
+ export interface IProfile {
52
+ // Optional fork metadata. Aggregate-only profiles have no time-order axis.
53
+ // Omitted values preserve compatibility with existing speedscope files.
54
+ isChronological?: boolean
55
+ // Derived profiles are excluded when combining original captures again.
56
+ isDerived?: boolean
57
+ // Type of profile. This will future proof the file format to allow many
58
+ // different kinds of profiles to be contained and each type to be part of
59
+ // a discriminated union.
60
+ type: ProfileType
61
+ }
62
+
63
+ export interface EventedProfile extends IProfile {
64
+ type: ProfileType.EVENTED
65
+
66
+ // Name of the profile. Typically a filename for the source of the profile.
67
+ name: string
68
+
69
+ // Unit which all value are specified using in the profile.
70
+ unit: ValueUnit
71
+
72
+ // The starting value of the profile. This will typically be a timestamp.
73
+ // All event values will be displayed relative to this startValue.
74
+ startValue: number
75
+
76
+ // The final value of the profile. This will typically be a timestamp. This
77
+ // must be greater than or equal to the startValue. This is useful in
78
+ // situations where the recorded profile extends past the end of the recorded
79
+ // events, which may happen if nothing was happening at the end of the
80
+ // profile.
81
+ endValue: number
82
+
83
+ // List of events that occured as part of this profile.
84
+ // The "at" field of every event must be in non-decreasing order.
85
+ events: (OpenFrameEvent | CloseFrameEvent)[]
86
+ }
87
+
88
+ // List of indices into the frame array
89
+ type SampledStack = number[]
90
+
91
+ export interface SampledProfile extends IProfile {
92
+ type: ProfileType.SAMPLED
93
+
94
+ // Name of the profile. Typically a filename for the source of the profile.
95
+ name: string
96
+
97
+ // Unit which all value are specified using in the profile.
98
+ unit: ValueUnit
99
+
100
+ // The starting value of the profile. This will typically be a timestamp.
101
+ // All event values will be displayed relative to this startValue.
102
+ startValue: number
103
+
104
+ // The final value of the profile. This will typically be a timestamp. This
105
+ // must be greater than or equal to the startValue. This is useful in
106
+ // situations where the recorded profile extends past the end of the recorded
107
+ // events, which may happen if nothing was happening at the end of the
108
+ // profile.
109
+ endValue: number
110
+
111
+ // List of stacks
112
+ samples: SampledStack[]
113
+
114
+ // The weight of the sample at the given index. Should have
115
+ // the same length as the samples array.
116
+ weights: number[]
117
+ }
118
+
119
+ export type ValueUnit =
120
+ | 'none'
121
+ | 'nanoseconds'
122
+ | 'microseconds'
123
+ | 'milliseconds'
124
+ | 'seconds'
125
+ | 'bytes'
126
+
127
+ export enum EventType {
128
+ OPEN_FRAME = 'O',
129
+ CLOSE_FRAME = 'C',
130
+ }
131
+
132
+ interface IEvent {
133
+ type: EventType
134
+ at: number
135
+ }
136
+
137
+ // Indicates a stack frame opened. Every opened stack frame must have a
138
+ // corresponding close frame event, and the ordering must be balanced.
139
+ interface OpenFrameEvent extends IEvent {
140
+ type: EventType.OPEN_FRAME
141
+ // An index into the frames array in the shared data within the profile
142
+ frame: number
143
+ }
144
+
145
+ interface CloseFrameEvent extends IEvent {
146
+ type: EventType.CLOSE_FRAME
147
+ // An index into the frames array in the shared data within the profile
148
+ frame: number
149
+ }
150
+ }