profiler-md 0.0.2 → 0.1.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/dist/index.d.mts CHANGED
@@ -1,38 +1,48 @@
1
- //#region src/v8/common.d.ts
2
- /** A single table row in a rendered V8 profile. */
3
- type V8ProfileRow = {
4
- /** The name of the entity corresponding to the row. */name: string;
1
+ //#region src/location.d.ts
2
+ /** A {@link URL} to a file, potentially with line and column information. */
3
+ type ProfileLocation = {
4
+ url: URL; /** The 1-based line number in the file at {@link ProfileLocation.url}. */
5
+ line?: number; /** The 1-based column number in the file at {@link ProfileLocation.url}. */
6
+ column?: number;
7
+ };
8
+ //#endregion
9
+ //#region src/options.d.ts
10
+ /** A single entry in a rendered profile. */
11
+ type ProfileEntry = {
5
12
  /**
6
- * The URL of the script this frame belongs to, or undefined if it's native
7
- * code.
13
+ * The name of the entity corresponding to this entry (e.g. a function name).
8
14
  */
9
- location?: string;
15
+ name: string;
16
+ /**
17
+ * The location where the entity corresponding to this entry was defined, or
18
+ * undefined if it's unknown.
19
+ */
20
+ location?: ProfileLocation;
10
21
  };
11
- /** Options for V8 profile converters. */
12
- type V8ProfileToMdOptions = {
22
+ /** Options for profile to Markdown converters. */
23
+ type ProfileToMdOptions = {
13
24
  /**
14
25
  * The number of entries to display when computing the "top N" by some metric.
15
26
  *
27
+ * This value is also be used to limit subsection entry count by dividing it
28
+ * by a constant.
29
+ *
16
30
  * Defaults to 20.
17
31
  */
18
32
  topN?: number;
19
33
  /**
20
- * Whether to include the given call frame in the Markdown output.
34
+ * Whether to include the given entry in the Markdown output.
21
35
  *
22
- * Excluding a call frame does not exclude it from metric computations.
23
- *
24
- * Defaults to {@link defaultIncludeRow}.
36
+ * Excluding an entry does not exclude it from metric computations.
25
37
  */
26
- includeRow?: (row: V8ProfileRow) => boolean;
38
+ includeEntry?: (entry: ProfileEntry) => boolean;
27
39
  /**
28
- * Whether the given URL points to third-party code.
40
+ * Whether the given entry points to third-party code.
29
41
  *
30
42
  * This is used to compute summaries in the Markdown output and make other
31
43
  * decisions about what's important to display.
32
- *
33
- * Defaults to {@link defaultIsThirdPartyURL}.
34
44
  */
35
- isThirdPartyURL?: (url: URL) => boolean;
45
+ isThirdPartyEntry?: (entry: ProfileEntry) => boolean;
36
46
  /**
37
47
  * The current working directory to use to make file paths relative in the
38
48
  * Markdown output.
@@ -45,27 +55,56 @@ type V8ProfileToMdOptions = {
45
55
  cwd?: string | null;
46
56
  };
47
57
  /**
48
- * Returns whether to include the given row in the Markdown output.
49
- *
50
- * This is the default value for {@link V8ProfileToMdOptions.includeRow}.
58
+ * Returns whether to include the given entry in the Markdown output.
51
59
  *
52
- * It makes reasonable assumptions about which rows are uninteresting to
53
- * display. For example, Node internals related to ESM loading are excluded.
60
+ * Excludes synthetic profile data and redundant internals by default.
54
61
  */
55
- declare const defaultIncludeRow: ({
62
+ declare const defaultIncludeEntry: ({
56
63
  name,
57
64
  location
58
- }: V8ProfileRow) => boolean;
65
+ }: ProfileEntry) => boolean;
59
66
  /**
60
- * Returns whether the given URL points to third-party code.
61
- *
62
- * This is the default value for {@link V8ProfileToMdOptions.isThirdPartyURL}.
67
+ * Returns whether the given entry points to third-party code.
63
68
  *
64
69
  * Excludes `node_modules` only by default.
65
70
  */
66
- declare const defaultIsThirdPartyURL: (url: URL) => boolean;
71
+ declare const defaultIsThirdPartyEntry: (entry: ProfileEntry) => boolean;
72
+ //#endregion
73
+ //#region src/formats/pprof/index.d.ts
74
+ /**
75
+ * Converts the given pprof to Markdown.
76
+ *
77
+ * It is assumed that {@link data} is a valid pprof (raw protobuf). The behavior
78
+ * of this function is undefined for invalid profiles.
79
+ *
80
+ * pprof can be generated by many tools, including:
81
+ * - Go's [`runtime/pprof`](https://pkg.go.dev/runtime/pprof) package
82
+ * - Node.js's [`pprof`](https://www.npmjs.com/package/pprof) npm package
83
+ * - Python's [`py-spy`](https://github.com/benfred/py-spy)
84
+ * - Rust's [`pprof-rs`](https://github.com/tikv/pprof-rs)
85
+ * - Java/Kotlin's [`async-profiler`](https://github.com/async-profiler/async-profiler)
86
+ * - C/C++'s [`gperftools`](https://github.com/gperftools/gperftools) (via `pprof --proto`)
87
+ */
88
+ declare const pprofToMd: (data: Uint8Array, options?: ProfileToMdOptions) => string;
89
+ //#endregion
90
+ //#region src/formats/speedscope/index.d.ts
91
+ /**
92
+ * Converts the given speedscope profile to Markdown.
93
+ *
94
+ * It is assumed that {@link data} is a valid speedscope JSON file. The behavior
95
+ * of this function is undefined for invalid profiles.
96
+ *
97
+ * Speedscope profiles can be generated by many tools, including:
98
+ * - [speedscope](https://www.speedscope.app) (drag and drop any supported profile)
99
+ * - [rbspy](https://rbspy.github.io) for Ruby
100
+ * - [py-spy](https://github.com/benfred/py-spy) for Python (`--format speedscope`)
101
+ * - [pprof-rs](https://github.com/tikv/pprof-rs) for Rust
102
+ * - [async-profiler](https://github.com/async-profiler/async-profiler) for Java/Kotlin (`-o speedscope`)
103
+ * - [phpspy](https://github.com/adsr/phpspy) for PHP (`--output-format=speedscope`)
104
+ */
105
+ declare const speedscopeProfileToMd: (data: string | Uint8Array, options?: ProfileToMdOptions) => string;
67
106
  //#endregion
68
- //#region src/v8/cpu-profile/index.d.ts
107
+ //#region src/formats/v8/cpu-profile/index.d.ts
69
108
  /**
70
109
  * Converts the given V8 CPU profile to Markdown.
71
110
  *
@@ -74,14 +113,21 @@ declare const defaultIsThirdPartyURL: (url: URL) => boolean;
74
113
  *
75
114
  * You can generate a V8 CPU profile in several ways:
76
115
  * - [`node --cpu-prof`](https://nodejs.org/api/cli.html#cpu-prof)
77
- * - [`deno --cpu-prof`](https://docs.deno.com/runtime/fundamentals/debugging/#cpu-profiling)
116
+ * - [`deno run --cpu-prof`](https://docs.deno.com/runtime/fundamentals/debugging/#cpu-profiling)
78
117
  * - [`bun --cpu-prof`](https://bun.com/docs/project/benchmarking#cpu-profiling)
118
+ * (NOTE: output was incorrect until
119
+ * [v1.3.13](https://bun.com/blog/bun-v1.3.13#node-js-compatibility-improvements))
120
+ * - [`node --inspect`](https://nodejs.org/api/debugger.html#v8-inspector-integration-for-nodejs),
121
+ * [`deno run --inspect`](https://docs.deno.com/runtime/fundamentals/debugging/#--inspect),
122
+ * or [`bun --inspect`](https://bun.com/docs/runtime/debugger#inspect) with
123
+ * [Chrome DevTools](https://developer.chrome.com/docs/devtools/performance/nodejs)
124
+ * - [Chrome DevTools directly](https://developer.chrome.com/docs/devtools/performance#record)
79
125
  *
80
126
  * Lower the sampling interval to capture more granular data.
81
127
  */
82
- declare const v8CpuProfileToMd: (data: string | Buffer, options?: V8ProfileToMdOptions) => string;
128
+ declare const v8CpuProfileToMd: (data: string | Uint8Array, options?: ProfileToMdOptions) => string;
83
129
  //#endregion
84
- //#region src/v8/heap-profile/index.d.ts
130
+ //#region src/formats/v8/heap-profile/index.d.ts
85
131
  /**
86
132
  * Converts the given V8 sampling heap profile to Markdown.
87
133
  *
@@ -90,14 +136,18 @@ declare const v8CpuProfileToMd: (data: string | Buffer, options?: V8ProfileToMdO
90
136
  *
91
137
  * You can generate a V8 heap profile in several ways:
92
138
  * - [`node --heap-prof`](https://nodejs.org/api/cli.html#--heap-prof)
93
- * - [`v8.writeHeapProfileSync()`](https://nodejs.org/api/v8.html#v8writeheapprofilesyncfilename)
139
+ * - [`node --inspect`](https://nodejs.org/api/debugger.html#v8-inspector-integration-for-nodejs),
140
+ * [`deno run --inspect`](https://docs.deno.com/runtime/fundamentals/debugging/#--inspect),
141
+ * or [`bun --inspect`](https://bun.com/docs/runtime/debugger#inspect) with
142
+ * [Chrome DevTools](https://developer.chrome.com/docs/devtools/memory-problems/allocation-profiler)
143
+ * - [Chrome DevTools directly](https://developer.chrome.com/docs/devtools/memory-problems/allocation-profiler)
94
144
  *
95
145
  * Note that [`bun --heap-prof`](https://bun.com/docs/project/benchmarking#heap-profiling)
96
146
  * generates a heap _snapshot_ on exit, not a heap _profile_.
97
147
  */
98
- declare const v8HeapProfileToMd: (data: string | Buffer, options?: V8ProfileToMdOptions) => string;
148
+ declare const v8HeapProfileToMd: (data: string | Uint8Array, options?: ProfileToMdOptions) => string;
99
149
  //#endregion
100
- //#region src/v8/heap-snapshot/index.d.ts
150
+ //#region src/formats/v8/heap-snapshot/index.d.ts
101
151
  /**
102
152
  * Converts the given V8 heap snapshot to Markdown.
103
153
  *
@@ -105,9 +155,16 @@ declare const v8HeapProfileToMd: (data: string | Buffer, options?: V8ProfileToMd
105
155
  * function is undefined for invalid snapshots.
106
156
  *
107
157
  * You can generate a V8 heap snapshot in several ways:
158
+ * - [`node --heapsnapshot-near-heap-limit=1`](https://nodejs.org/api/cli.html#heapsnapshot-near-heap-limitmax-count)
108
159
  * - [`node --heapsnapshot-signal`](https://nodejs.org/api/cli.html#--heapsnapshot-signalsignal)
160
+ * - [`bun --heap-prof`](https://bun.com/docs/project/benchmarking#heap-profiling)
109
161
  * - [`v8.writeHeapSnapshot()`](https://nodejs.org/api/v8.html#v8writeheapsnapshotfilename)
162
+ * - [`node --inspect`](https://nodejs.org/api/debugger.html#v8-inspector-integration-for-nodejs),
163
+ * [`deno run --inspect`](https://docs.deno.com/runtime/fundamentals/debugging/#--inspect),
164
+ * or [`bun --inspect`](https://bun.com/docs/runtime/debugger#inspect) with
165
+ * [Chrome DevTools](https://developer.chrome.com/docs/devtools/memory-problems/heap-snapshots)
166
+ * - [Chrome DevTools directly](https://developer.chrome.com/docs/devtools/memory-problems/heap-snapshots)
110
167
  */
111
- declare const v8HeapSnapshotToMd: (data: string | Buffer, options?: V8ProfileToMdOptions) => string;
168
+ declare const v8HeapSnapshotToMd: (data: string | Uint8Array, options?: ProfileToMdOptions) => string;
112
169
  //#endregion
113
- export { V8ProfileRow, V8ProfileToMdOptions, defaultIncludeRow, defaultIsThirdPartyURL, v8CpuProfileToMd, v8HeapProfileToMd, v8HeapSnapshotToMd };
170
+ export { type ProfileEntry, type ProfileToMdOptions, defaultIncludeEntry, defaultIsThirdPartyEntry, pprofToMd, speedscopeProfileToMd, v8CpuProfileToMd, v8HeapProfileToMd, v8HeapSnapshotToMd };