Skip to content

docs: capability layers, atomic writes, memfs limitations#12

Merged
mojatter merged 1 commit into
mainfrom
docs/readme-capabilities
Apr 7, 2026
Merged

docs: capability layers, atomic writes, memfs limitations#12
mojatter merged 1 commit into
mainfrom
docs/readme-capabilities

Conversation

@mojatter
Copy link
Copy Markdown
Owner

@mojatter mojatter commented Apr 7, 2026

Summary

  • Document the new `RenameFS` / `SyncWriterFile` capability interfaces alongside the existing `WriteFileFS` / `RemoveFileFS` ones.
  • Add a Capability layers table mapping each capability to its interface and top-level helper.
  • Add a worked `atomicWrite` example showing how `RenameFS` + `SyncWriterFile` combine for crash-safe writes that work unchanged on both `osfs` and `memfs`.
  • Add a memfs limitations section: writes are visible only after `Close`, `Sync` is a no-op, `Rename` supports files only.

Part of v0.5.0 release prep.

Test plan

  • Render README on github and confirm the table and code blocks look right

The README only described the original Write/Remove interfaces. Add
the new RenameFS and SyncWriterFile capability interfaces, a Capability
layers table that maps each capability to its interface and helper, and
a worked atomicWrite example showing how the two new capabilities
combine for crash-safe writes. Also call out the memfs behaviors that
differ from osfs (Close-publishes-writes, Sync-is-noop, file-only
Rename) so callers porting code between backends are not surprised.
@mojatter mojatter force-pushed the docs/readme-capabilities branch from cd24233 to 4fcdd3d Compare April 7, 2026 09:46
@mojatter mojatter merged commit 1a4bde9 into main Apr 7, 2026
3 checks passed
@mojatter mojatter deleted the docs/readme-capabilities branch April 7, 2026 09:47
@mojatter mojatter mentioned this pull request Apr 7, 2026
2 tasks
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.

1 participant