feat(utils): add WriteAheadLog classes #1210

BioPhoton · 2026-01-09T21:39:57Z

Related: #1197

This PR includes:

types for source sink flows
wal.ts - general WriteAheadLog and sharded WAL inc format and filenames
wal-trace-json.ts traceEvent specific login for a WAL
profiler constants to control WAL leader
moved trace utils into profiler

Note

This PR addresses a comment related to logging.
It could also be used as file output for the logger

Warning

All filesystem operations in WAL—and indirectly in the profiler—are synchronous by design.
The eslint rules are disables over file name pattern

Why synchronous fs is used for WAL code?

Profilers are side-channels, not business logic
Data must never be lost, reordered, or partially written
process.on('exit') cannot safely run async I/O
Sync writes guarantee ordering + durability
Profiler I/O volume is small → overhead is negligible
Crash-safety > throughput

Note

Introduces a synchronous Write-Ahead Log system and integrates it with profiler trace generation.

New wal.ts: WriteAheadLogFile, ShardedWal, codecs (stringCodec, createTolerantCodec), sharding IDs/paths, finalize/cleanup helpers, and AppendableSink interface
Profiler: add getProfilerId, new constants, and move/expand trace utils (trace-file-utils.ts) with encode/decode helpers, metadata, and entryToTraceEvents
New wal-json-trace.ts: generate complete Chrome trace content and expose traceEventWalFormat
Refactor PerformanceObserverSink to use AppendableSink.append and update mocks/tests; remove legacy sink-source.type.ts
Set realistic time origin in tests; add many unit/integration tests
ESLint: disable n/no-sync for wal*.ts files

^{Written by Cursor Bugbot for commit 953a3e7. This will update automatically on new commits. Configure here.}

nx-cloud · 2026-01-09T21:41:17Z

View your CI Pipeline Execution ↗ for commit 953a3e7

Command	Status	Duration	Result
`nx affected -t int-test --parallel=3`	✅ Succeeded	1m 32s	View ↗
`nx affected -t unit-test --parallel=3`	✅ Succeeded	43s	View ↗

☁️ Nx Cloud last updated this comment at 2026-01-26 22:21:37 UTC

pkg-pr-new · 2026-01-09T21:41:34Z

Open in StackBlitz

@code-pushup/ci

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/ci@1210

@code-pushup/cli

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/cli@1210

@code-pushup/core

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/core@1210

@code-pushup/create-cli

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/create-cli@1210

@code-pushup/models

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/models@1210

@code-pushup/nx-plugin

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/nx-plugin@1210

@code-pushup/axe-plugin

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/axe-plugin@1210

@code-pushup/coverage-plugin

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/coverage-plugin@1210

@code-pushup/eslint-plugin

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/eslint-plugin@1210

@code-pushup/js-packages-plugin

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/js-packages-plugin@1210

@code-pushup/jsdocs-plugin

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/jsdocs-plugin@1210

@code-pushup/lighthouse-plugin

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/lighthouse-plugin@1210

@code-pushup/typescript-plugin

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/typescript-plugin@1210

@code-pushup/utils

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/utils@1210

commit: 953a3e7

github-actions · 2026-01-09T21:48:09Z

Code PushUp

🤨 Code PushUp report has both improvements and regressions – compared current commit 276ae6b with previous commit ea27cdc.

🕵️ See full comparison in Code PushUp portal 🔍

🏷️ Categories

🏷️ Category	⭐ Previous score	⭐ Current score	🔄 Score change
Performance	🔴 29	🔴 33
Documentation	🔴 42	🔴 46
Code coverage	🟢 92	🟢 93
Bug prevention	🟡 75	🟡 75
Axe Accessibility	🟡 88	🟡 88
Code style	🟢 100	🟢 100	–
Security	🔴 47	🔴 47	–
Updates	🟡 78	🟡 78	–
Type Safety	🟡 67	🟡 67	–
Miscellaneous	🟡 67	🟡 67	–
Accessibility	🟢 92	🟢 92	–
Best Practices	🟢 100	🟢 100	–
SEO	🟢 92	🟢 92	–

👍 3 groups improved, 👍 13 audits improved, 12 audits changed without impacting score

🗃️ Groups

🔌 Plugin	🗃️ Group	⭐ Previous score	⭐ Current score
Lighthouse	Performance	🔴 29	🔴 33
JSDocs coverage	Documentation coverage	🔴 42	🔴 46
Code coverage	Code coverage metrics	🟢 92	🟢 93

31 other groups are unchanged.

🛡️ Audits

🔌 Plugin	🛡️ Audit	📏 Previous value	📏 Current value
Lighthouse	First Contentful Paint	🟥 3.9 s	🟥 3.2 s
Lighthouse	Speed Index	🟥 9.3 s	🟥 7.6 s
JSDocs coverage	Classes coverage	🟥 6 undocumented classes	🟨 6 undocumented classes
JSDocs coverage	Properties coverage	🟥 30 undocumented properties	🟥 41 undocumented properties
Lighthouse	Time to Interactive	🟥 17.7 s	🟥 13.7 s
Lighthouse	Total Blocking Time	🟥 7,300 ms	🟥 2,310 ms
JSDocs coverage	Functions coverage	🟥 579 undocumented functions	🟥 582 undocumented functions
JSDocs coverage	Types coverage	🟥 272 undocumented types	🟥 262 undocumented types
JSDocs coverage	Methods coverage	🟨 13 undocumented methods	🟨 15 undocumented methods
JSDocs coverage	Variables coverage	🟥 272 undocumented variables	🟥 280 undocumented variables
Code coverage	Branch coverage	🟨 89 %	🟨 89.2 %
Code coverage	Line coverage	🟩 92.3 %	🟩 92.6 %
Code coverage	Function coverage	🟩 94.1 %	🟩 94.3 %
Lighthouse	Minimizes main-thread work	🟥 24.2 s	🟥 11.9 s
Lighthouse	Avoids enormous network payloads	🟩 Total size was 2,098 KiB	🟩 Total size was 2,087 KiB
Lighthouse	JavaScript execution time	🟥 9.6 s	🟥 4.9 s
Lighthouse	Metrics	🟩 100%	🟩 100%
Lighthouse	Largest Contentful Paint	🟥 14.5 s	🟥 11.5 s
Lighthouse	Max Potential First Input Delay	🟥 3,650 ms	🟥 1,250 ms
Lighthouse	Server Backend Latencies	🟩 1,040 ms	🟩 300 ms
Lighthouse	Uses efficient cache policy on static assets	🟨 31 resources found	🟨 31 resources found
Lighthouse	Reduce unused CSS	🟥 Potential savings of 125 KiB	🟥 Potential savings of 125 KiB
Lighthouse	Initial server response time was short	🟩 Root document took 560 ms	🟩 Root document took 580 ms
Lighthouse	Reduce unused JavaScript	🟥 Potential savings of 226 KiB	🟥 Potential savings of 226 KiB
Lighthouse	Network Round Trip Times	🟩 20 ms	🟩 20 ms

654 other audits are unchanged.

# Conflicts: # packages/utils/src/lib/sink-source.types.ts

# Conflicts: # testing/test-utils/src/lib/utils/perf-hooks.mock.ts

github-actions · 2026-01-16T22:26:47Z

Code PushUp

🥳 Code PushUp report has improved – compared current commit 276ae6b with previous commit ea27cdc.

💼 Project `utils`

🥳 Code PushUp report has improved.

🕵️ See full comparison in Code PushUp portal 🔍

🏷️ Category	⭐ Previous score	⭐ Current score	🔄 Score change
Documentation	🔴 46	🟡 51
Code coverage	🟢 95	🟢 95

4 other categories are unchanged.

👍 2 groups improved, 👍 9 audits improved

🗃️ Groups

🔌 Plugin	🗃️ Group	⭐ Previous score	⭐ Current score	🔄 Score change
JSDocs coverage	Documentation coverage	🔴 46	🟡 51
Code coverage	Code coverage metrics	🟢 95	🟢 95

13 other groups are unchanged.

🛡️ Audits

🔌 Plugin	🛡️ Audit	📏 Previous value	📏 Current value
JSDocs coverage	Classes coverage	🟨 3 undocumented classes	🟨 3 undocumented classes
JSDocs coverage	Properties coverage	🟥 27 undocumented properties	🟥 38 undocumented properties
JSDocs coverage	Types coverage	🟥 66 undocumented types	🟨 56 undocumented types
JSDocs coverage	Functions coverage	🟥 241 undocumented functions	🟥 244 undocumented functions
JSDocs coverage	Methods coverage	🟨 13 undocumented methods	🟨 15 undocumented methods
JSDocs coverage	Variables coverage	🟥 49 undocumented variables	🟥 57 undocumented variables
Code coverage	Branch coverage	🟩 91.7 %	🟩 92.2 %
Code coverage	Function coverage	🟩 95.7 %	🟩 96 %
Code coverage	Line coverage	🟩 97.7 %	🟩 97.9 %

435 other audits are unchanged.

13 other projects are unchanged.

hanna-skryl

The justification for sync file operations is well-reasoned 👍 I've added a few minor suggestions and comments.

packages/utils/src/lib/wal.ts

packages/utils/mocks/sink.mock.ts

packages/utils/src/lib/profiler/wal-json-trace.unit.test.ts

packages/utils/src/lib/wal.ts

Co-authored-by: Hanna Skryl <80118140+hanna-skryl@users.noreply.github.com>

packages/utils/src/lib/profiler/wal-json-trace.unit.test.ts

packages/utils/src/lib/profiler/wal-json-trace.ts

# Conflicts: # packages/utils/src/lib/performance-observer.int.test.ts # packages/utils/src/lib/profiler/profiler.unit.test.ts

packages/utils/src/lib/wal.ts

packages/utils/src/lib/profiler/wal-json-trace.ts

packages/utils/src/lib/wal.ts

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is ON, but it could not run because Privacy Mode (Legacy) is turned on. To enable Bugbot Autofix, switch your privacy mode in the Cursor dashboard.}

packages/utils/src/lib/profiler/wal-json-trace.ts

packages/utils/eslint.config.js

packages/utils/src/lib/sink-source.type.ts

packages/utils/src/lib/wal.ts

John Doe added 2 commits January 8, 2026 20:11

refactor: add general file sink logic

c03b2c4

feat: add file sink classes

756f8c0

github-actions bot assigned BioPhoton Jan 9, 2026

github-actions bot added 🔬 testing writing tests 🧩 utils labels Jan 9, 2026

BioPhoton mentioned this pull request Jan 9, 2026

feat(utils): add performance observer #1206

Merged

BioPhoton mentioned this pull request Jan 10, 2026

Implement performance profiling and trace file generation #1197

Open

John Doe and others added 16 commits January 10, 2026 01:51

Merge branch 'main' into feat/utils/file-sink

4c95897

# Conflicts: # packages/utils/src/lib/sink-source.types.ts

refactor: add trace json file

b0c9cc4

refactor: wip

1f6e326

refactor: wip

6bcb73b

Merge remote-tracking branch 'origin/main' into feat/utils/file-sink

dfb43be

refactor: wip arc

3fe6871

refactor: fix lint

67e004c

Merge branch 'main' into feat/utils/file-sink

a4a9f10

# Conflicts: # testing/test-utils/src/lib/utils/perf-hooks.mock.ts

refactor: wip

0b1fd3a

refactor: wip

bf0ecb9

refactor: wip

c88ffe9

refactor: wip

d6e75e6

refactor: wip

21575b3

refactor: wip

09437a9

refactor: wip

4705394

refactor: wip

e0c210e

BioPhoton added 3 commits January 17, 2026 20:34

refactor: wip

29016b0

refactor: wip

e60ea2b

refactor: wip

5ea2ac4

BioPhoton requested a review from matejchalk January 17, 2026 22:34

BioPhoton added 3 commits January 18, 2026 00:35

refactor: wip

a19070e

refactor: wip

4f8cd2d

refactor: wip

bc86d08

BioPhoton changed the title ~~feat(utils): add file sink classes~~ feat(utils): add WriteAheadLog classes Jan 18, 2026

BioPhoton added 4 commits January 18, 2026 23:46

refactor: wip

a530134

refactor: remove path logic

d9eb84b

refactor: fix lint

67f0c1e

refactor: fix unit tests on windows

a3641d3

hanna-skryl reviewed Jan 19, 2026

View reviewed changes

BioPhoton and others added 3 commits January 19, 2026 21:48

Update packages/utils/src/lib/wal.ts

f7bf8e8

Co-authored-by: Hanna Skryl <80118140+hanna-skryl@users.noreply.github.com>

Update packages/utils/src/lib/wal.ts

d658b0f

Co-authored-by: Hanna Skryl <80118140+hanna-skryl@users.noreply.github.com>

Update packages/utils/src/lib/wal.ts

f34ef73

Co-authored-by: Hanna Skryl <80118140+hanna-skryl@users.noreply.github.com>

matejchalk reviewed Jan 26, 2026

View reviewed changes

packages/utils/src/lib/profiler/wal-json-trace.unit.test.ts Outdated Show resolved Hide resolved

packages/utils/src/lib/profiler/wal-json-trace.ts Outdated Show resolved Hide resolved

BioPhoton added 2 commits January 26, 2026 22:05

Merge branch 'main' into feat/utils/file-sink

42dd944

# Conflicts: # packages/utils/src/lib/performance-observer.int.test.ts # packages/utils/src/lib/profiler/profiler.unit.test.ts

refactor: remove vitest imports

a952dfe

cursor bot reviewed Jan 26, 2026

View reviewed changes

packages/utils/src/lib/wal.ts Show resolved Hide resolved

packages/utils/src/lib/profiler/wal-json-trace.ts Outdated Show resolved Hide resolved

refactor: fix targets

cadc7ee

cursor bot reviewed Jan 26, 2026

View reviewed changes

packages/utils/src/lib/wal.ts Outdated Show resolved Hide resolved

BioPhoton added 3 commits January 26, 2026 22:39

refactor: wip

e4f66d5

refactor: wip

b6f2bb6

refactor: wip

cb766a7

cursor bot reviewed Jan 26, 2026

View reviewed changes

packages/utils/src/lib/profiler/wal-json-trace.ts Show resolved Hide resolved

packages/utils/eslint.config.js Show resolved Hide resolved

refactor: wip

953a3e7

BioPhoton requested a review from hanna-skryl January 26, 2026 22:03

hanna-skryl reviewed Jan 26, 2026

View reviewed changes

packages/utils/src/lib/sink-source.type.ts Show resolved Hide resolved

packages/utils/src/lib/wal.ts Show resolved Hide resolved

BioPhoton requested a review from hanna-skryl January 26, 2026 23:37

hanna-skryl approved these changes Jan 26, 2026

View reviewed changes

BioPhoton merged commit e677d4f into main Jan 26, 2026
36 of 38 checks passed

BioPhoton deleted the feat/utils/file-sink branch January 26, 2026 23:41

feat(utils): add WriteAheadLog classes #1210

feat(utils): add WriteAheadLog classes #1210

Uh oh!

Conversation

BioPhoton commented Jan 9, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nx-cloud bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code PushUp

🏷️ Categories

🗃️ Groups

🛡️ Audits

Uh oh!

github-actions bot commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code PushUp

💼 Project utils

🗃️ Groups

🛡️ Audits

Uh oh!

hanna-skryl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

BioPhoton commented Jan 9, 2026 •

edited by cursor bot

Loading

nx-cloud bot commented Jan 9, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 9, 2026 •

edited

Loading

github-actions bot commented Jan 9, 2026 •

edited

Loading

github-actions bot commented Jan 16, 2026 •

edited

Loading

💼 Project `utils`