Skip to content

docs(file-storage): explain local write failures - #3597

Merged
kamilmysliwiec merged 2 commits into
nestjs:masterfrom
rafaself:docs/local-disk-write-failures
Oct 12, 2026
Merged

kamilmysliwiec merged 2 commits into
nestjs:masterfrom
rafaself:docs/local-disk-write-failures

Conversation

@rafaself

@rafaself rafaself commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

PR Checklist

PR Type

  • Bugfix
  • Feature
  • Code style update (formatting, local variables)
  • Refactoring (no functional changes, no api changes)
  • Build related changes
  • Docs
  • Other... Please describe:

What is the current behavior?

The file-storage tutorial describes atomic writes but does not explain the LocalDisk zero-progress and persisted-size checks added by nestjs/storage#19.

What is the new behavior?

Add a short paragraph beside the put() explanation documenting temporary-file cleanup, preservation of an existing file on a failed filesystem write, and direct StorageError failures when writing makes no progress or the persisted size differs from the bytes written.

All existing examples and other content remain unchanged.

Does this PR introduce a breaking change?

  • Yes
  • No

Other information

Dependency: nestjs/storage#19 is still open. Keep this PR in draft until the corresponding implementation has landed and the documentation can describe the available behavior.

This follows the documentation recommendation in nestjs/storage#19 (review).

Validation with Node 22.23.3:

  • npm run build passes, including documentation and LLM-file generation.
  • npm test -- --watch=false: 58 tests pass.
  • Verified the generated HTML contains the complete note once as a single paragraph, and source comparison confirms only the intended note changed.
  • git diff --check passes.
  • npm run lint reports 30 existing errors in unchanged TypeScript files.

The initial npm ci attempt reported missing chokidar@3.6.0 and glob-parent@5.1.2 lockfile entries. Dependencies were installed with npm install --package-lock=false; no dependency files are changed.

Describe zero-progress and persisted-size errors, temporary-file cleanup,
and preservation of existing files when a local write fails.

Follow up nestjs/storage#19.
@rafaself
rafaself marked this pull request as ready for review October 11, 2026 23:53
@kamilmysliwiec
kamilmysliwiec merged commit 14d941e into nestjs:master Oct 12, 2026
4 checks passed
@rafaself
rafaself deleted the docs/local-disk-write-failures branch October 12, 2026 12:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants