From 139c99daa88853b1406d5e0b48678a88a92d8c54 Mon Sep 17 00:00:00 2001 From: Carbon Date: Fri, 2 Oct 2026 19:01:25 +0800 Subject: [PATCH] docs: document the verified 0.1.1 release --- CHANGELOG.md | 9 ++--- README.md | 14 +++---- README.zh-CN.md | 10 ++--- docs/content/api/compatibility.mdx | 6 +-- docs/content/api/cp.mdx | 2 +- docs/content/api/glob.mdx | 2 +- docs/content/api/index.mdx | 2 +- docs/content/api/read-file.mdx | 6 +-- docs/content/api/readdir.mdx | 2 +- docs/content/api/rm.mdx | 2 +- docs/content/api/scan.mdx | 2 +- docs/content/guide/batch-evidence.mdx | 5 ++- docs/content/guide/competitor-evidence.mdx | 2 +- docs/content/guide/migration.mdx | 7 ++-- docs/content/guide/native-overheads.mdx | 2 +- docs/content/guide/quick-start.mdx | 45 ++++++++++------------ docs/content/guide/troubleshooting.mdx | 36 ++++++++--------- docs/content/guide/use-cases.mdx | 4 +- docs/content/index.mdx | 7 ++-- 19 files changed, 79 insertions(+), 86 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1f45375..574a8c4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,10 +6,7 @@ All notable Vooya FS changes are documented here. The format follows ## [Unreleased] -## [@vooya/fs 0.1.1] - Release candidate - -Prepared for publication; npm 0.1.0 remains the latest published release until the -Release workflow succeeds. The changes below are included in this candidate. +## [@vooya/fs 0.1.1] - 2026-10-02 ### Added @@ -147,8 +144,8 @@ Release workflow succeeds. The changes below are included in this candidate. --- -[Unreleased]: https://github.com/vooyajs/fs/compare/fs-v0.1.0...HEAD -[@vooya/fs 0.1.1]: https://github.com/vooyajs/fs/compare/fs-v0.1.0...release/fs-0-1-1 +[Unreleased]: https://github.com/vooyajs/fs/compare/fs-v0.1.1...HEAD +[@vooya/fs 0.1.1]: https://github.com/vooyajs/fs/releases/tag/fs-v0.1.1 [@vooya/fs 0.1.0]: https://github.com/vooyajs/fs/releases/tag/fs-v0.1.0 [@rush-fs/core 0.1.0]: https://github.com/vooyajs/fs/compare/v0.0.5...v0.1.0 [0.0.5]: https://github.com/vooyajs/fs/compare/v0.0.4...v0.0.5 diff --git a/README.md b/README.md index fd77097..48e3f14 100644 --- a/README.md +++ b/README.md @@ -22,17 +22,17 @@ It is not intended to make every `node:fs` call faster. Tiny operations such as walks, globbing, recursive copy/removal, and combined traversal + metadata work. > [!IMPORTANT] -> npm already contains `@vooya/fs@0.1.0`. The 0.1.1 release candidate in this -> checkout is unreleased; build from source to test the new behaviors described here. +> Install `@vooya/fs@0.1.1` for the compatibility fixes described here. +> See the [0.1.0 → 0.1.1 comparison](https://rush-fs-docs.vercel.app/guide/quick-start#published-release-and-source-differences) when upgrading. ## Install and run -Use Node.js 22 or newer. Prebuilt 0.1.0 binaries support macOS arm64/x64, +Use Node.js 22 or newer. Prebuilt 0.1.1 binaries support macOS arm64/x64, Linux x64 with glibc, and Windows x64. Supported prebuilt installs do not need Rust. Keep optional dependencies enabled so npm can install the matching binary. ```sh -npm install @vooya/fs@0.1.0 +npm install @vooya/fs@0.1.1 ``` Save this as `scan.mjs` in your project, then run `node scan.mjs`: @@ -54,13 +54,13 @@ try { } ``` -This example works with npm 0.1.0 and the source checkout. Results contain paths +This example works with npm 0.1.1. Results contain paths relative to the scanned directory; an empty array is valid when no files match. For CommonJS, import with `const { scan } = require('@vooya/fs')` and call it from an async function. [Quick Start](https://rush-fs-docs.vercel.app/guide/quick-start) covers both install -paths. Check the [release/source differences](https://rush-fs-docs.vercel.app/guide/quick-start#published-release-and-source-differences) +paths. Check the [0.1.0 → 0.1.1 differences](https://rush-fs-docs.vercel.app/guide/quick-start#published-release-and-source-differences) before using newer options, or follow [native binding troubleshooting](https://rush-fs-docs.vercel.app/guide/troubleshooting#cannot-find-the-native-binding) if the import fails. @@ -154,7 +154,7 @@ The package also exposes promise and sync variants for `access`, `appendFile`, `readFile`, `readlink`, `realpath`, `rename`, `rmdir`, `stat`, `symlink`, `truncate`, `unlink`, `utimes`, and `writeFile`. -Compatibility is deliberately scoped. The unreleased batch entry accepts string, +Compatibility is deliberately scoped. The 0.1.1 batch entry accepts string, Buffer and file URL paths, and routes advanced Node options to Node when needed. Callback-style APIs are not provided. See the [compatibility policy](./docs/content/api/compatibility.mdx) and conformance SDDs under diff --git a/README.zh-CN.md b/README.zh-CN.md index 3f499ee..72f2581 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -21,16 +21,16 @@ JavaScript → Rust 调用，替代成千上万次 JS 与文件系统之间的 “遍历 + 过滤 + metadata”这类可以在原生侧合并完成的工作。 > [!IMPORTANT] -> npm 已发布 `@vooya/fs@0.1.0`。本工作区为 0.1.1 候选版本，尚未发布；验证这些新行为请从源码构建。 +> 安装 `@vooya/fs@0.1.1` 即可使用这里说明的兼容性修复；从旧版升级时请查看 [0.1.0 → 0.1.1 差异](https://rush-fs-docs.vercel.app/guide/quick-start#published-release-and-source-differences)。 ## 安装并运行 -使用 Node.js 22 或更新版本。0.1.0 提供 macOS arm64/x64、Linux x64 glibc +使用 Node.js 22 或更新版本。0.1.1 提供 macOS arm64/x64、Linux x64 glibc 和 Windows x64 预编译包；这些平台直接安装使用不需要 Rust。 请启用 optional dependencies，以便 npm 安装对应平台的原生包。 ```sh -npm install @vooya/fs@0.1.0 +npm install @vooya/fs@0.1.1 ``` 在项目中将以下内容保存为 `scan.mjs`，然后运行 `node scan.mjs`： @@ -52,12 +52,12 @@ try { } ``` -该示例适用于 npm 0.1.0 和源码工作区。返回的路径相对于扫描目录；没有匹配文件时， +该示例适用于 npm 0.1.1。返回的路径相对于扫描目录；没有匹配文件时， 空数组是正常结果。CommonJS 可以用 `const { scan } = require('@vooya/fs')` 导入，并在 async 函数中调用。 [快速上手（英文）](https://rush-fs-docs.vercel.app/guide/quick-start) 说明两种安装方式。 -使用新选项前请查看[发布版与源码差异](https://rush-fs-docs.vercel.app/guide/quick-start#published-release-and-source-differences)； +使用新选项前请查看[0.1.0 → 0.1.1 差异](https://rush-fs-docs.vercel.app/guide/quick-start#published-release-and-source-differences)； 导入失败时请按[原生绑定排错步骤](https://rush-fs-docs.vercel.app/guide/troubleshooting#cannot-find-the-native-binding)检查。 ## 产品方向与开发约束 diff --git a/docs/content/api/compatibility.mdx b/docs/content/api/compatibility.mdx index 0df3cee..17c8dca 100644 --- a/docs/content/api/compatibility.mdx +++ b/docs/content/api/compatibility.mdx @@ -1,11 +1,11 @@ # Node compatibility and execution policy -This unreleased iteration targets common filesystem batches on Node 22 and 24. +Version 0.1.1 targets common filesystem batches on Node 22 and 24. The public entry point is `@vooya/fs`. `index.js` remains the generated native binding and is not a supported alternate package entry point. -Installed npm 0.1.0? Check the [release/source comparison](/guide/quick-start#published-release-and-source-differences) -before applying this unreleased API policy. +Installed npm 0.1.0? Check the [0.1.0 → 0.1.1 comparison](/guide/quick-start#published-release-and-source-differences) +before applying this 0.1.1 API policy. The baseline is the [Node filesystem API](https://nodejs.org/docs/latest-v22.x/api/fs.html). Compatibility tests call Node on independent fixtures and compare results, side diff --git a/docs/content/api/cp.mdx b/docs/content/api/cp.mdx index 8893c68..e19c223 100644 --- a/docs/content/api/cp.mdx +++ b/docs/content/api/cp.mdx @@ -1,6 +1,6 @@ # cp -> This page describes unreleased checkout changes. See [Node compatibility and execution policy](/api/compatibility) for native fast paths, Node routes and verified limits. +> This page describes `@vooya/fs@0.1.1`. See [Node compatibility and execution policy](/api/compatibility) for native fast paths, Node routes and verified limits. Copy files and directories recursively. Supports **concurrency** (Vooya FS extension) for faster tree copy. diff --git a/docs/content/api/glob.mdx b/docs/content/api/glob.mdx index f65f9ec..c0fa00c 100644 --- a/docs/content/api/glob.mdx +++ b/docs/content/api/glob.mdx @@ -1,6 +1,6 @@ # glob -> This page describes unreleased checkout changes. See [Node compatibility and execution policy](/api/compatibility) for native fast paths, Node routes and verified limits. +> This page describes `@vooya/fs@0.1.1`. See [Node compatibility and execution policy](/api/compatibility) for native fast paths, Node routes and verified limits. Match files and directories by glob pattern (e.g. `**/*.js`). Supports **concurrency** and **gitIgnore** (Vooya FS extensions). Vooya FS uses [ignore](https://github.com/BurntSushi/ripgrep/tree/master/crates/ignore) for matching, while compatibility tests use Node's built-in `fs.promises.glob` / `fs.globSync` as the oracle. diff --git a/docs/content/api/index.mdx b/docs/content/api/index.mdx index c522e94..d8c3908 100644 --- a/docs/content/api/index.mdx +++ b/docs/content/api/index.mdx @@ -11,7 +11,7 @@ marketing. Core batch APIs accept string, Buffer and file URL paths. A public compatibility layer uses Node for options outside the measured native path. Other exports retain their documented subsets; callback API forms remain absent. -This page describes main, including unreleased changes. See [Quick Start](/guide/quick-start) +This page describes the published 0.1.1 API. See [Quick Start](/guide/quick-start) for the release boundary and installation instructions. See the [Node compatibility policy](/api/compatibility) for remaining API and behavioral gaps. diff --git a/docs/content/api/read-file.mdx b/docs/content/api/read-file.mdx index 8ce6854..b7374d8 100644 --- a/docs/content/api/read-file.mdx +++ b/docs/content/api/read-file.mdx @@ -1,6 +1,6 @@ # readFile -> This page describes unreleased checkout changes. See [Node compatibility and execution policy](/api/compatibility) for native fast paths, Node routes and verified limits. +> This page describes `@vooya/fs@0.1.1`. See [Node compatibility and execution policy](/api/compatibility) for native fast paths, Node routes and verified limits. Read the entire contents of a file. Returns a `Buffer` or a decoded string depending on `encoding`. @@ -40,9 +40,9 @@ line. Selected lines are joined with `\n`, without a final line terminator. Omitting the encoding (or using `encoding: null`) returns the **whole file as a Buffer**, so it does not limit how much content your caller receives. -Main preserves blank lines in the selected range. The published 0.1.0 release +Version 0.1.1 preserves blank lines in the selected range. The published 0.1.0 release can drop leading blank lines from the excerpt; its missing-file errors also lack -main's structured fields. See [version-specific troubleshooting](/guide/troubleshooting#why-does-a-line-range-return-the-whole-file). +0.1.1's structured fields. See [version-specific troubleshooting](/guide/troubleshooting#why-does-a-line-range-return-the-whole-file). ## Methods diff --git a/docs/content/api/readdir.mdx b/docs/content/api/readdir.mdx index e314906..d08d5c4 100644 --- a/docs/content/api/readdir.mdx +++ b/docs/content/api/readdir.mdx @@ -1,6 +1,6 @@ # readdir -> This page describes unreleased checkout changes. See [Node compatibility and execution policy](/api/compatibility) for native fast paths, Node routes and verified limits. +> This page describes `@vooya/fs@0.1.1`. See [Node compatibility and execution policy](/api/compatibility) for native fast paths, Node routes and verified limits. Read the contents of a directory. Supports non-recursive and recursive modes; recursive mode uses parallel traversal and benefits most from Vooya FS. diff --git a/docs/content/api/rm.mdx b/docs/content/api/rm.mdx index 224a9e1..c1b27fd 100644 --- a/docs/content/api/rm.mdx +++ b/docs/content/api/rm.mdx @@ -1,6 +1,6 @@ # rm -> This page describes unreleased checkout changes. See [Node compatibility and execution policy](/api/compatibility) for native fast paths, Node routes and verified limits. +> This page describes `@vooya/fs@0.1.1`. See [Node compatibility and execution policy](/api/compatibility) for native fast paths, Node routes and verified limits. Remove files and directories. Supports recursive removal with optional **concurrency** (Vooya FS extension) for tuning recursive deletion. diff --git a/docs/content/api/scan.mdx b/docs/content/api/scan.mdx index 5ef1790..ba8f20f 100644 --- a/docs/content/api/scan.mdx +++ b/docs/content/api/scan.mdx @@ -1,6 +1,6 @@ # scan -> This page describes unreleased checkout changes. See [Node compatibility and execution policy](/api/compatibility) for native fast paths, Node routes and verified limits. +> This page describes `@vooya/fs@0.1.1`. See [Node compatibility and execution policy](/api/compatibility) for native fast paths, Node routes and verified limits. Walk a directory tree, apply rooted include/exclude patterns, and return metadata in one native operation. `scan` is a Vooya FS extension, not a Node `fs` compatibility diff --git a/docs/content/guide/batch-evidence.mdx b/docs/content/guide/batch-evidence.mdx index 0420500..4db188f 100644 --- a/docs/content/guide/batch-evidence.mdx +++ b/docs/content/guide/batch-evidence.mdx @@ -1,7 +1,8 @@ # Batch API evidence -This report covers the unreleased Node 22/24 compatibility iteration. The npm -release remains `@vooya/fs@0.1.0`; build this checkout to use the changes. +This historical report measures the source-build Node 22/24 compatibility +iteration included in 0.1.1. It is not a fresh benchmark of the npm artifact; +retain the measured revisions and environment below when comparing results. ## Scope and execution policy diff --git a/docs/content/guide/competitor-evidence.mdx b/docs/content/guide/competitor-evidence.mdx index fdd334f..d6e7280 100644 --- a/docs/content/guide/competitor-evidence.mdx +++ b/docs/content/guide/competitor-evidence.mdx @@ -1,7 +1,7 @@ # Competitor benchmark evidence This compares overlapping workloads adapted from fdir and tinyglobby's own -benchmarks against the current unreleased Vooya public entry. It is a baseline +benchmarks against the measured pre-release Vooya public entry. It is a baseline for choosing optimizations. These reports measure the reviewed release build, including the documented glob compatibility corrections. diff --git a/docs/content/guide/migration.mdx b/docs/content/guide/migration.mdx index f126d1e..e6d2321 100644 --- a/docs/content/guide/migration.mdx +++ b/docs/content/guide/migration.mdx @@ -20,9 +20,10 @@ The Rust crate is `vooya_fs`, and the native binary basename is ## Release boundary -`@vooya/fs@0.1.0` is published. This site follows main and also documents newer, -unreleased compatibility fixes. Do not assume those fixes are present in 0.1.0; -check the [release source](https://github.com/vooyajs/fs/tree/fs-v0.1.0). +`@vooya/fs@0.1.1` includes the compatibility fixes described in the API guide. +They are not all present in 0.1.0; check the +[version comparison](/guide/quick-start#published-release-and-source-differences) +and the [0.1.1 release source](https://github.com/vooyajs/fs/tree/fs-v0.1.1). Legacy versions remain separate packages. npm deprecation, if applied, displays a warning; it does not redirect imports or install a replacement. The old packages diff --git a/docs/content/guide/native-overheads.mdx b/docs/content/guide/native-overheads.mdx index 84f79a8..7775204 100644 --- a/docs/content/guide/native-overheads.mdx +++ b/docs/content/guide/native-overheads.mdx @@ -1,6 +1,6 @@ # Native overhead evidence -This unreleased iteration builds on `db835af` (the Node compatibility PR). It +This historical source-build measurement builds on `db835af` (the Node compatibility PR). It changes three existing native paths: compatible glob patterns share a walk, workers collect glob results locally, and Buffer writes avoid redundant copies. Public signatures and native/Node routing are unchanged. diff --git a/docs/content/guide/quick-start.mdx b/docs/content/guide/quick-start.mdx index 717aedf..287ca26 100644 --- a/docs/content/guide/quick-start.mdx +++ b/docs/content/guide/quick-start.mdx @@ -1,24 +1,22 @@ # Quick Start -This site documents **the 0.1.1 release candidate, not yet released to npm**. The -published package is [`@vooya/fs@0.1.0`](https://www.npmjs.com/package/@vooya/fs). -Its [release source](https://github.com/vooyajs/fs/tree/fs-v0.1.0) is the reference -for that version. The current compatibility policy and benchmark tables describe -the newer checkout; installing 0.1.0 does not install those changes. See the -[release/source comparison](#published-release-and-source-differences) for common tasks. +Install [`@vooya/fs@0.1.1`](https://www.npmjs.com/package/@vooya/fs), the published +release covered by this guide. Its [release source](https://github.com/vooyajs/fs/tree/fs-v0.1.1) +identifies the implementation. Upgrading from 0.1.0? Check the +[version comparison](#published-release-and-source-differences) for common tasks. ## Requirements Use Node.js **22 or newer**; the current conformance matrix checks Node 22 and 24. -Prebuilt 0.1.0 packages cover macOS arm64/x64, Linux x64 with glibc, and Windows +Prebuilt 0.1.1 packages cover macOS arm64/x64, Linux x64 with glibc, and Windows x64. Rust is needed to build a checkout, not to use a supported prebuilt package. Linux arm64 and Alpine/musl do not have published binaries in this release. ## Install the published release ```sh -npm install @vooya/fs@0.1.0 -# Or: pnpm add @vooya/fs@0.1.0 +npm install @vooya/fs@0.1.1 +# Or: pnpm add @vooya/fs@0.1.1 ``` Keep optional dependencies enabled: the package manager selects the native binary @@ -28,7 +26,7 @@ the module cannot load. ## Run your first scan Save this as `scan.mjs` in the project where you installed the package. This -string-path example works with 0.1.0 and the current checkout: +string-path example works with 0.1.1: ```js import { scan } from '@vooya/fs' @@ -63,29 +61,28 @@ async function or with `.then()`. Promise methods are exported directly from `@vooya/fs`; there is no `@vooya/fs/promises` entry. Synchronous variants such as `scanSync` block the JavaScript thread. -## Published release and source differences + -Use this small comparison when choosing between npm 0.1.0 and the 0.1.1 release candidate -source. It covers the operations below, not every API/option combination. +## Upgrading from 0.1.0 to 0.1.1 -| Task | npm `@vooya/fs@0.1.0` | 0.1.1 candidate source | +Use this small comparison when upgrading from npm 0.1.0 to 0.1.1. It covers the operations below, not every API/option combination. + +| Task | npm `@vooya/fs@0.1.0` | npm `@vooya/fs@0.1.1` | | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | Run the [string-path scan example](#run-your-first-scan) | Supported | Supported | | Read lines with `encoding: 'utf8'` | Supported, but can drop leading blank lines in the selected range | Preserves selected blank lines | | Pass `lines` without an encoding | Returns the whole file as a Buffer | Returns the whole file as a Buffer | | Handle a missing file from `readFile` / `readFileSync` | `code: 'GenericFailure'`; ENOENT appears in the message, without structured `path`, `syscall` or `errno` | `code: 'ENOENT'` with those structured fields | -The read behavior above was checked in both sync and Promise forms against the -installed npm 0.1.0 package and the source entry on Node 22, macOS arm64. It is not -cross-platform runtime verification. See the [line-range example](/api/read-file#read-a-line-range) +The read behavior above was checked in both sync and Promise forms against +separate registry installations of 0.1.0 and 0.1.1 on Node 22, macOS arm64. +The 0.1.1 acceptance also ran on Node 24. This is local runtime verification, +not a new cross-platform performance result. See the [line-range example](/api/read-file#read-a-line-range) and [error guidance](/guide/troubleshooting#why-does-a-missing-file-have-code-genericfailure). -The [release source](https://github.com/vooyajs/fs/tree/fs-v0.1.0) identifies the -published implementation; use the [source instructions](#try-the-current-source) -for the newer behavior. The version string alone cannot distinguish these builds. ## Try the current source -To use the compatibility fixes and reproduce the published benchmark evidence, +To develop changes or reproduce the source-build benchmark evidence, install Git, Rust stable and pnpm 9, then build a release binding: ```sh @@ -97,9 +94,9 @@ node --input-type=module -e "import { scan } from '@vooya/fs'; console.log((awai ``` Run that command from the repository root: the package's self-reference resolves -the local public entry. Record `git rev-parse HEAD` when comparing results. The -checkout carries candidate version 0.1.1. That version string does not confirm -npm publication; use the published-release instructions above for registry installs. +the local public entry. Record `git rev-parse HEAD` when comparing results. A +checkout can contain changes beyond the published version; record the commit as +well as the package version when reporting its behavior. ## Adopt one operation at a time diff --git a/docs/content/guide/troubleshooting.mdx b/docs/content/guide/troubleshooting.mdx index fbe673c..049cb8f 100644 --- a/docs/content/guide/troubleshooting.mdx +++ b/docs/content/guide/troubleshooting.mdx @@ -2,11 +2,10 @@ ## Which version does this site describe? -The site follows main. npm currently provides `@vooya/fs@0.1.0`; main includes -additional compatibility fixes and newer measurements. Use the -[release source](https://github.com/vooyajs/fs/tree/fs-v0.1.0) for 0.1.0 and the -[checkout instructions](/guide/quick-start#try-the-current-source) to try main. -For common tasks, start with the [release/source comparison](/guide/quick-start#published-release-and-source-differences). +The API guide covers `@vooya/fs@0.1.1`. Use its +[release source](https://github.com/vooyajs/fs/tree/fs-v0.1.1) to identify the shipped +implementation. Historical benchmark reports retain their measured revisions and +limits. For common tasks, start with the [0.1.0 → 0.1.1 comparison](/guide/quick-start#published-release-and-source-differences). ## Cannot find the native binding @@ -17,7 +16,7 @@ node -p "process.version + ' ' + process.platform + '/' + process.arch" npm ls @vooya/fs ``` -Version 0.1.0 ships binaries for macOS arm64/x64, Linux x64 glibc and Windows x64. +Version 0.1.1 ships binaries for macOS arm64/x64, Linux x64 glibc and Windows x64. The architecture is that of the Node process, which can differ from the host under emulation. Ensure your package manager installs optional dependencies and install on the target platform; copying `node_modules` from a different OS is not portable. @@ -25,7 +24,7 @@ on the target platform; copying `node_modules` from a different OS is not portab Check the platform package as well as the main package. Choose the name for your **Node process** from this table, then run `npm ls` with that name: -| Node platform / architecture | 0.1.0 platform package | +| Node platform / architecture | 0.1.1 platform package | | ---------------------------- | -------------------------- | | `darwin arm64` | `@vooya/fs-darwin-arm64` | | `darwin x64` | `@vooya/fs-darwin-x64` | @@ -42,13 +41,13 @@ If the matching package is missing on a supported platform, run this in the application directory to include optional packages, then verify the import: ```sh -npm install --include=optional @vooya/fs@0.1.0 +npm install --include=optional @vooya/fs@0.1.1 node -e "require('@vooya/fs'); console.log('native binding loaded')" ``` Keep your lockfile. If the package is present but loading still fails, retain the full error and the two `npm ls` outputs when reporting it. Linux arm64 and -Alpine/musl have no 0.1.0 prebuilt package; enabling optional dependencies cannot +Alpine/musl have no 0.1.1 prebuilt package; enabling optional dependencies cannot add support for those targets. There is no WASM fallback or automatic Node-only fallback when the addon is missing. @@ -74,7 +73,7 @@ The [per-API tables](/guide/all-api-evidence) include losses, and ## Does async mean streaming or bounded memory? -No. Promise operations return complete results. In particular, main's `glob` +No. Promise operations return complete results. In particular, 0.1.1's `glob` iterator still materializes the full array; `scan` returns sorted metadata for all matches. Prefer Node streams or iterators when incremental consumption and backpressure are the requirement. Async native work runs off the JavaScript @@ -84,33 +83,32 @@ thread, but conversion and consumption of a large result can still affect it. The public entry selects Node for combinations outside a native fast path, such as copy filters or some glob patterns. This preserves the documented behavior. -On main, `cpSync` and `rmSync` always use Node. A successful call or a speed ratio +In 0.1.1, `cpSync` and `rmSync` always use Node. A successful call or a speed ratio alone is not proof of Rust acceleration; consult the [execution policy](/api/compatibility). ## Why does a line range return the whole file? The `readFile` / `readFileSync` extension needs an explicit text encoding: -`{ encoding: 'utf8', lines: { from: 110, to: 120 } }`. With no encoding, it returns the entire file as a Buffer on both npm 0.1.0 and main. +`{ encoding: 'utf8', lines: { from: 110, to: 120 } }`. With no encoding, it returns the entire file as a Buffer on both npm 0.1.0 and 0.1.1. Explicit `encoding: null` rejects with `InvalidArg` on npm 0.1.0; omit the encoding for Buffer reads on that release. See the [line-range example](/api/read-file#read-a-line-range). There are also release-specific limits. Given `one\n\nthree\n`, lines 2–3 -with UTF-8 return `"three"` on npm 0.1.0, but `"\nthree"` on main. Main's -blank-line fix is not yet published. If exact line content matters, use the -[source checkout](/guide/quick-start#try-the-current-source) or an existing Node -implementation until a release includes the fix. +with UTF-8 return `"three"` on npm 0.1.0, but `"\nthree"` on npm 0.1.1. +Upgrade to 0.1.1 to preserve selected blank lines and accept explicit +`encoding: null` for whole-file Buffer reads. ## Why does a missing file have code GenericFailure? In npm 0.1.0, `readFile` and `readFileSync` report a missing file with `code: 'GenericFailure'` and an ENOENT message; `path`, `syscall` and `errno` are -absent. Main's public entry reports `code: 'ENOENT'` with those structured fields. -Do not assume the main-only fields exist in the installed release. Catch the +absent. Version 0.1.1 reports `code: 'ENOENT'` with those structured fields. +Do not assume the newer fields exist when maintaining a 0.1.0 installation. Catch the Promise rejection (or the synchronous exception), log the complete error, and record the package version when reporting it. Applications that require Node's structured error handling can keep this operation on `node:fs` / `node:fs/promises` -or verify the source checkout before adopting it. +or upgrade to 0.1.1 and verify their expected error handling. ## Report a mismatch or performance regression diff --git a/docs/content/guide/use-cases.mdx b/docs/content/guide/use-cases.mdx index 32e8d51..729c6fe 100644 --- a/docs/content/guide/use-cases.mdx +++ b/docs/content/guide/use-cases.mdx @@ -6,8 +6,8 @@ calls in `node:fs`. ## Choose by the result you need These are candidates to measure against your existing implementation. Evidence -below comes from the unreleased checkout on macOS; it is not a speed guarantee for -npm 0.1.0 or another operating system. +below comes from historical source builds on macOS; it is not a speed guarantee +for an npm installation or another operating system. | Needed result | Candidate | Check before adopting | | ------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/docs/content/index.mdx b/docs/content/index.mdx index 387a38d..aad9e6b 100644 --- a/docs/content/index.mdx +++ b/docs/content/index.mdx @@ -5,15 +5,14 @@ It continues the former Rush-FS project under the Vooya name, with a narrower an focused promise: keep familiar Node APIs and prioritize native optimizations where substantial I/O, recursive or fused work can amortize the boundary cost. -> **Documentation version: main (unreleased changes).** `@vooya/fs@0.1.0` is -> available on npm. The compatibility fixes and benchmark results on this site -> describe the newer source checkout, not that published package. +> **API documentation version: 0.1.1.** Install `@vooya/fs@0.1.1` from npm. +> Benchmark reports retain their source-build revisions and measurement limits. > [Install the release or try main](/guide/quick-start). ## Start here [中文介绍与源码构建说明](https://github.com/vooyajs/fs/blob/main/README.zh-CN.md)。 -本站 API 文档以英文为主，描述尚未发布的 main 分支；npm 版本的安装与支持平台请见 +本站 API 文档以英文为主，描述已发布的 0.1.1 版本；npm 版本的安装与支持平台请见 [Quick Start](/guide/quick-start)。 - [Install and run your first scan](/guide/quick-start)