@paulirish/trace_engine 0.0.67-beta.0 → 0.0.67-beta.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/README.md CHANGED
@@ -8,46 +8,84 @@ But the breakages should be obvious exceptions or type failures.
8
8
  ## API quickstart
9
9
 
10
10
  ```js
11
- import * as TraceModel from '@paulirish/trace_engine';
11
+ import * as Trace from '@paulirish/trace_engine';
12
12
 
13
- const engine = TraceModel.Processor.TraceProcessor.createWithAllHandlers();
13
+ const model = Trace.TraceModel.Model.createWithAllHandlers();
14
+ await model.parse(traceEvents);
14
15
 
15
- await engine.parse(traceEvents);
16
- console.log(engine.data) // TraceParseData
16
+ const parsedTrace = model.parsedTrace();
17
+ console.log(parsedTrace.data); // Handlers data (Meta, Screenshots, LayoutShifts, etc.)
18
+ console.log(parsedTrace.insights); // Insight models
17
19
  ```
18
20
 
19
- See the included `analyze-trace.mjs` for a runnable invocation.
21
+ See the included `analyze-trace.mjs` for a runnable CLI script.
20
22
 
21
- ### Types & Submodule Imports
23
+ ### Imports & TypeScript Types
22
24
 
23
- All `models/trace/**` submodules exported by `trace.ts` (including `models/trace/types/TraceEvents.js`, `models/trace/lantern/lantern.js`, `models/trace/insights/*.js`, and `models/trace/extras/ThirdParties.js`) have both `.d.ts` declarations and runtime `.js` ESM proxies:
25
+ All runtime values and types are imported directly from the root package entrypoint (`@paulirish/trace_engine`):
24
26
 
25
- @type {import('@paulirish/trace_engine').Types.Events.Event[]}
26
- @type {import('@paulirish/trace_engine').Handlers.Types.HandlerData}
27
+ ```js
28
+ import * as TraceEngine from '@paulirish/trace_engine';
29
+ // Or via named imports:
30
+ import {Types, Lantern, Insights, Processor, Handlers, Helpers, Extras} from '@paulirish/trace_engine';
31
+
32
+ // Enums & Event Types
33
+ const {Phase, Name} = Types.Events;
34
+ const {Milli, Micro} = Types.Timing;
35
+
36
+ // Lantern
37
+ const {Graph, Simulation} = Lantern;
38
+
39
+ // Insights
40
+ const {UIStrings} = Insights.Models.ImageDelivery;
41
+ ```
42
+
43
+ TypeScript declarations (`.d.ts`) mirror DevTools' own types through the root namespace:
44
+
45
+ ```ts
46
+ import type {Types, Insights, Lantern} from '@paulirish/trace_engine';
47
+
48
+ type TraceEvent = Types.Events.Event;
49
+ type SyntheticNetworkRequest = Types.Events.SyntheticNetworkRequest;
50
+ type InsightSet = Insights.Types.InsightSet;
51
+ ```
52
+
53
+ #### Migrating from Legacy Deep Subpaths
54
+
55
+ Older versions of `@paulirish/trace_engine` exposed individual files inside `models/trace/...`. These deep paths are deprecated in favor of the canonical root exports:
56
+
57
+ | Old Deep Path | Canonical Import (`@paulirish/trace_engine`) |
58
+ | :--- | :--- |
59
+ | `.../models/trace/lantern/lantern.js` | `import { Lantern } from '@paulirish/trace_engine';` |
60
+ | `.../models/trace/types/types.js` | `import { Types } from '@paulirish/trace_engine';` |
61
+ | `.../models/trace/types/TraceEvents.js` | `import { Types } from '@paulirish/trace_engine'; const { Events } = Types;` |
62
+ | `.../models/trace/types/Timing.js` | `import { Types } from '@paulirish/trace_engine'; const { Timing } = Types;` |
63
+ | `.../models/trace/insights/<Insight>.js` | `import { Insights } from '@paulirish/trace_engine'; const { UIStrings } = Insights.Models.<Insight>;` |
64
+ | `.../models/trace/extras/ThirdParties.js` | `import { Extras } from '@paulirish/trace_engine'; const { ThirdParties } = Extras;` |
27
65
 
28
66
  ## Maintainer cheatsheet
29
67
 
30
- `@paulirish/trace_engine` wraps the pre-bundled `DevTools.TraceEngine` shipped in `chrome-devtools-mcp` and emits the exact matching `.d.ts` declarations from `devtools-frontend` (using the commit SHA recorded in `chrome-devtools-mcp/build/src/third_party/bundled-packages.json`).
68
+ `@paulirish/trace_engine` wraps the pre-bundled `DevTools.TraceEngine` shipped in `chrome-devtools-mcp` and emits matching `.d.ts` declarations and locales from `devtools-frontend` (using the commit SHA recorded in `chrome-devtools-mcp/build/src/third_party/bundled-packages.json`).
31
69
 
32
- - `scripts/build.ts` automatically pins the exact `chrome-devtools-mcp` version in `package.json` so runtime code and `.d.ts` declarations never drift.
33
- - Exported `const enum`s under `models/trace` (such as `Types.Events.Name`, `Types.Events.Phase`, `Handlers.Threads.ThreadType`, etc.) are materialized as runtime enum objects so plain JS and `--experimental-strip-types` consumers can reference them at runtime. (`const enum`s in other internal DevTools modules remain type-only.)
34
- - Importing `@paulirish/trace_engine` initializes the `DevToolsLocale` singleton to `'en-US'` if it has not already been initialized in the current process.
70
+ - `models/trace/trace.js` is a static runtime wrapper that initializes `DevToolsLocale` ('en-US') and intercepts `LocalizedStringSet.prototype.getLocalizedString` so calls from `models/trace/` return `{i18nId, values, formattedDefault}` for Lighthouse's multi-locale pipeline.
71
+ - Exported `const enum`s under `models/trace` (such as `Types.Events.Phase`, `Handlers.Threads.ThreadType`, etc.) are materialized at runtime in `models/trace/trace.js` until [CL 8539952](https://chromium-review.git.corp.google.com/c/devtools/devtools-frontend/+/8539952) lands upstream in `devtools-frontend`.
72
+ - `scripts/build.ts` extracts `front_end/` via `git archive` from the local `devtools-frontend` checkout at the exact SHA and runs `tsc --emitDeclarationOnly` in ~2 seconds.
35
73
 
36
74
  ```sh
37
75
  cd $HOME/code/trace_engine
38
76
 
39
- # Update chrome-devtools-mcp to latest, regenerate .d.ts & wrapper, and run tests + type-check
40
- npm i chrome-devtools-mcp@latest
77
+ # 1. Update chrome-devtools-mcp to latest (exact version)
78
+ npm i chrome-devtools-mcp@latest --save-exact
79
+
80
+ # 2. Re-emit .d.ts declarations and locales (~2s)
41
81
  npm run build
42
- npm test
43
82
 
44
- # Bump version and dry-run publish
45
- npm version patch
46
- npm publish --access public --dry-run
83
+ # 3. Run test suite and type check
84
+ npm test
47
85
 
48
- # Auth and publish
49
- npm whoami --registry https://registry.npmjs.org/ || npm login --registry https://registry.npmjs.org/
50
- npm publish --access public --registry https://registry.npmjs.org/
86
+ # 4. Bump version and publish (use --tag beta for testing)
87
+ npm version prerelease --preid=beta # e.g. 0.0.67-beta.0
88
+ npm publish --tag beta
51
89
  ```
52
90
 
53
91
  ## High level architecture
package/index.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ export * from './models/trace/trace.js';
2
+ export {default} from './models/trace/trace.js';