@statewalker/webrun-files-node 0.10.2 → 0.10.3

package/README.md

@@ -1,167 +1,118 @@
 # @statewalker/webrun-files-node
 
-Node.js filesystem implementation of the `FilesApi` interface from `@statewalker/webrun-files`.
+## What it is
 
-## Overview
+`NodeFilesApi`, an implementation of `FilesApi` from `@statewalker/webrun-files` over Node.js
+`fs/promises`. Virtual paths (`/users/alice.json`) are mapped to real files under a root directory.
 
-This package provides a `FilesApi` implementation that works with the real filesystem using Node.js `fs/promises`. It maps virtual paths (starting with `/`) to a root directory on disk.
+## Why it exists
 
-## Installation
+Server code, CLIs and tests that work against `FilesApi` need a backend that stores real files on
+disk. With this package the same code that runs on `MemFilesApi` in tests, or on S3 in production,
+reads and writes a local directory.
+
+## How to use
 
 ```bash
-npm install @statewalker/webrun-files-node @statewalker/webrun-files
+pnpm add @statewalker/webrun-files-node @statewalker/webrun-files
 ```
 
-## Usage
-
-### Basic Usage
+One entry point, `@statewalker/webrun-files-node`: ESM (`dist/esm/index.js`), CommonJS
+(`dist/cjs/index.cjs`), types (`dist/index.d.ts`); sources in `src/`. Node.js only (it imports
+`node:fs/promises`).
 
 ```typescript
-import { NodeFilesApi } from '@statewalker/webrun-files-node';
-import { readText, writeText } from '@statewalker/webrun-files';
-
-// Create API rooted at a specific directory
-const files = new NodeFilesApi({ rootDir: '/var/app/data' });
+import { NodeFilesApi, type NodeFilesApiOptions } from '@statewalker/webrun-files-node';
 
-// Write a file - creates /var/app/data/config.json
-await writeText(files, '/config.json', '{"debug": true}');
-
-// Read it back
-const content = await readText(files, '/config.json');
-console.log(content); // {"debug": true}
+const files = new NodeFilesApi({ rootDir: '/var/app/data' }); // rootDir defaults to process.cwd()
+```
 
-// List files
-for await (const entry of files.list('/')) {
-  if (entry.kind === 'file') {
-    console.log(entry.name, entry.kind, entry.size, entry.lastModified);
-  } else {
-    console.log(entry.name, entry.kind); // directories carry no size or time
-  }
-}
+```
+rootDir:      /var/app/data
+virtual path: /users/alice.json
+real path:    /var/app/data/users/alice.json
 ```
 
-### Default Root Directory
+## Examples
 
-If no `rootDir` is specified, the current working directory is used:
+### Read, write, list
 
 ```typescript
 import { NodeFilesApi } from '@statewalker/webrun-files-node';
+import { readText, writeText } from '@statewalker/webrun-files';
 
-const files = new NodeFilesApi();
-// Virtual path /data/file.txt maps to ./data/file.txt
-```
-
-### Path Mapping
-
-Virtual paths are mapped directly to the filesystem:
-
-```
-rootDir: "/var/app/data"
-virtual path: "/users/alice.json"
-real path: "/var/app/data/users/alice.json"
-```
-
-Paths are appended to `rootDir` without confinement: `..` segments are kept, not resolved, so a
-virtual path such as `/../etc/passwd` reaches outside `rootDir`. Do not pass untrusted paths.
-
-## API Reference
-
-### NodeFilesApi
+const files = new NodeFilesApi({ rootDir: '/var/app/data' });
 
-```typescript
-interface NodeFilesApiOptions {
-  /**
-   * Root directory for file operations.
-   * Virtual paths are appended to this directory (see "Path Mapping" for `..`).
-   * Defaults to current working directory if not specified.
-   */
-  rootDir?: string;
-}
+await writeText(files, '/deep/nested/config.json', '{"debug": true}'); // parents are created
+console.log(await readText(files, '/deep/nested/config.json'));
 
-class NodeFilesApi implements FilesApi {
-  constructor(options?: NodeFilesApiOptions);
-
-  // All FilesApi methods
-  read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
-  write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;
-  mkdir(path: string): Promise<void>;
-  list(path: string, options?: ListOptions): AsyncIterable<FileInfo>;
-  stats(path: string): Promise<FileStats | undefined>;
-  exists(path: string): Promise<boolean>;
-  remove(path: string): Promise<boolean>;
-  move(source: string, target: string): Promise<boolean>;
-  copy(source: string, target: string): Promise<boolean>;
+for await (const entry of files.list('/', { recursive: true })) {
+  console.log(entry.path, entry.kind, entry.kind === 'file' ? entry.size : '');
 }
 ```
 
-## Features
-
-### Efficient Streaming
-
-Large files are read in chunks without loading entirely into memory:
+### Stream a range
 
 ```typescript
-// Stream a large file
-for await (const chunk of files.read('/large-video.mp4')) {
-  // Process each chunk (default 8KB chunks)
-}
-
-// Read a specific range
 for await (const chunk of files.read('/large-file.bin', { start: 1000, length: 500 })) {
-  // Only bytes 1000-1499
+  // bytes 1000-1499, in chunks of at most 8 KiB
 }
 ```
 
-### Automatic Directory Creation
-
-Parent directories are created automatically when writing files:
+### A temporary directory per test
 
 ```typescript
-// Creates /var/app/data/deep/nested/path/ automatically
-await writeText(files, '/deep/nested/path/file.txt', 'content');
-```
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { NodeFilesApi } from '@statewalker/webrun-files-node';
 
-### Ordered Listings
+const rootDir = await mkdtemp(join(tmpdir(), 'test-'));
+const files = new NodeFilesApi({ rootDir });
+try {
+  // ...
+} finally {
+  await rm(rootDir, { recursive: true, force: true });
+}
+```
 
-`readdir` returns names in no guaranteed order, so `list()` reads each directory, stats its entries
-and yields them in path order (as every `FilesApi` does). A recursive listing reads a directory only
-when the listing reaches it, and with `{ after }` skips any directory whose whole subtree sorts at
-or before the cursor.
+## Internals
 
-### Recursive Operations
+### How each call maps to `fs`
 
-Copy and remove work recursively on directories. `move()` is a single `fs.rename`: when the rename
-fails — for example across devices — it returns `false` rather than falling back to copying.
+| Call | Implementation |
+| --- | --- |
+| `read` | `fs.open` + positioned `handle.read` in 8 KiB buffers, only the requested range |
+| `write` | `fs.mkdir(parent, { recursive: true })`, then collects every chunk and calls `fs.writeFile` once |
+| `list` | `fs.readdir` + `fs.stat` per entry, walked through `listInPathOrder` |
+| `move` | `fs.rename` after creating the target's parent |
+| `copy` | `fs.cp(..., { recursive: true })` |
+| `remove` | `fs.rm(..., { recursive: true, force: true })` for a directory, `fs.unlink` for a file |
 
-```typescript
-// Copy entire directory tree
-await files.copy('/source', '/destination');
+### Why listings stat every entry
 
-// Remove directory and all contents
-await files.remove('/old-data');
-```
+`readdir` returns names in no guaranteed order, and every `FilesApi` must list in `comparePaths`
+order with `after` support. `list()` therefore reads each directory, stats its entries and yields
+them sorted. A recursive listing reads a directory only when the listing reaches it, and skips any
+directory whose whole subtree sorts at or before `after`.
 
-## Testing with Temporary Directories
+### What breaks, and how it looks
 
-```typescript
-import { mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { NodeFilesApi } from '@statewalker/webrun-files-node';
-import { writeText } from '@statewalker/webrun-files';
+- **A path that leaves `rootDir` is refused.** `..` segments are resolved against `rootDir`; when
+  the result is outside it, the call throws
+  `NodeFilesApi: path is outside rootDir: /../etc/passwd` (reads throw when iterated). `..` that
+  stays inside (`/a/../b.txt`) is fine. Symbolic links inside `rootDir` are followed as the
+  operating system follows them, so a link pointing out of `rootDir` still leads out.
+- **`write` holds the whole file in memory** before writing it, so a very large upload costs its
+  full size in RAM. Reads stream.
+- **`move` across devices returns `false`.** It is a single `fs.rename`; when that fails (`EXDEV`,
+  permissions) the method returns `false` instead of falling back to copy and delete.
+- **Unreadable reads look like missing files.** `read` swallows every error (missing file,
+  permission denied, a directory) and yields nothing; `copy` and `move` return `false`.
 
-// Create a temp directory for testing
-const tempDir = await mkdtemp(join(tmpdir(), 'test-'));
-const files = new NodeFilesApi({ rootDir: tempDir });
+### Dependencies
 
-try {
-  // Run tests...
-  await writeText(files, '/test.txt', 'test content');
-} finally {
-  // Cleanup
-  await rm(tempDir, { recursive: true, force: true });
-}
-```
+`@statewalker/webrun-files` for the types and path helpers; Node.js built-ins otherwise.
 
 ## License
 

package/dist/cjs/index.cjs

@@ -23,6 +23,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = __toESM(node_fs_promises, 1);
+let node_path = require("node:path");
+node_path = __toESM(node_path, 1);
 //#region ../webrun-files/dist/esm/index.js
 /**
 * The order every `FilesApi.list()` yields: paths compared by Unicode code
@@ -147,11 +149,13 @@ function dirname(path) {
 var NodeFilesApi = class {
 	rootDir;
 	constructor(options) {
-		this.rootDir = options?.rootDir ?? process.cwd();
+		this.rootDir = node_path.resolve(options?.rootDir ?? process.cwd());
 	}
+	/** The real path of a virtual one; throws when `..` segments would take it outside rootDir. */
 	resolvePath(virtualPath) {
-		const normalized = normalizePath(virtualPath);
-		return this.rootDir + normalized;
+		const real = node_path.resolve(this.rootDir, `.${normalizePath(virtualPath)}`);
+		if (real !== this.rootDir && !real.startsWith(this.rootDir + node_path.sep)) throw new Error(`NodeFilesApi: path is outside rootDir: ${virtualPath}`);
+		return real;
 	}
 	async *read(path, options) {
 		const realPath = this.resolvePath(path);
@@ -186,7 +190,7 @@ var NodeFilesApi = class {
 	async write(path, content) {
 		const realPath = this.resolvePath(path);
 		const normalized = normalizePath(path);
-		const dir = this.rootDir + dirname(normalized);
+		const dir = this.resolvePath(dirname(normalized));
 		await node_fs_promises.mkdir(dir, { recursive: true });
 		const chunks = [];
 		let totalLength = 0;
@@ -287,7 +291,7 @@ var NodeFilesApi = class {
 			return false;
 		}
 		try {
-			const targetDir = this.rootDir + dirname(normalizedTarget);
+			const targetDir = this.resolvePath(dirname(normalizedTarget));
 			await node_fs_promises.mkdir(targetDir, { recursive: true });
 			await node_fs_promises.rename(sourcePath, targetPath);
 			return true;
@@ -305,7 +309,7 @@ var NodeFilesApi = class {
 			return false;
 		}
 		try {
-			const targetDir = this.rootDir + dirname(normalizedTarget);
+			const targetDir = this.resolvePath(dirname(normalizedTarget));
 			await node_fs_promises.mkdir(targetDir, { recursive: true });
 			await node_fs_promises.cp(sourcePath, targetPath, { recursive: true });
 			return true;

package/dist/esm/index.js

@@ -1,4 +1,5 @@
 import * as fs from "node:fs/promises";
+import * as nodePath from "node:path";
 //#region ../webrun-files/dist/esm/index.js
 /**
 * The order every `FilesApi.list()` yields: paths compared by Unicode code
@@ -123,11 +124,13 @@ function dirname(path) {
 var NodeFilesApi = class {
 	rootDir;
 	constructor(options) {
-		this.rootDir = options?.rootDir ?? process.cwd();
+		this.rootDir = nodePath.resolve(options?.rootDir ?? process.cwd());
 	}
+	/** The real path of a virtual one; throws when `..` segments would take it outside rootDir. */
 	resolvePath(virtualPath) {
-		const normalized = normalizePath(virtualPath);
-		return this.rootDir + normalized;
+		const real = nodePath.resolve(this.rootDir, `.${normalizePath(virtualPath)}`);
+		if (real !== this.rootDir && !real.startsWith(this.rootDir + nodePath.sep)) throw new Error(`NodeFilesApi: path is outside rootDir: ${virtualPath}`);
+		return real;
 	}
 	async *read(path, options) {
 		const realPath = this.resolvePath(path);
@@ -162,7 +165,7 @@ var NodeFilesApi = class {
 	async write(path, content) {
 		const realPath = this.resolvePath(path);
 		const normalized = normalizePath(path);
-		const dir = this.rootDir + dirname(normalized);
+		const dir = this.resolvePath(dirname(normalized));
 		await fs.mkdir(dir, { recursive: true });
 		const chunks = [];
 		let totalLength = 0;
@@ -263,7 +266,7 @@ var NodeFilesApi = class {
 			return false;
 		}
 		try {
-			const targetDir = this.rootDir + dirname(normalizedTarget);
+			const targetDir = this.resolvePath(dirname(normalizedTarget));
 			await fs.mkdir(targetDir, { recursive: true });
 			await fs.rename(sourcePath, targetPath);
 			return true;
@@ -281,7 +284,7 @@ var NodeFilesApi = class {
 			return false;
 		}
 		try {
-			const targetDir = this.rootDir + dirname(normalizedTarget);
+			const targetDir = this.resolvePath(dirname(normalizedTarget));
 			await fs.mkdir(targetDir, { recursive: true });
 			await fs.cp(sourcePath, targetPath, { recursive: true });
 			return true;

package/dist/node-files-api.d.ts

@@ -1,8 +1,8 @@
 import type { FileInfo, FileStats, FilesApi, ListOptions, ReadOptions } from "@statewalker/webrun-files";
 export interface NodeFilesApiOptions {
     /**
-     * Root directory for file operations. All paths are resolved relative to this.
-     * Defaults to current working directory if not specified.
+     * Root directory for file operations. All paths are resolved relative to this, and a path
+     * whose `..` segments would leave it is refused. Defaults to the current working directory.
      */
     rootDir?: string;
 }
@@ -13,6 +13,7 @@ export interface NodeFilesApiOptions {
 export declare class NodeFilesApi implements FilesApi {
     private rootDir;
     constructor(options?: NodeFilesApiOptions);
+    /** The real path of a virtual one; throws when `..` segments would take it outside rootDir. */
     private resolvePath;
     read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;
     write(path: string, content: Iterable<Uint8Array> | AsyncIterable<Uint8Array>): Promise<void>;

package/dist/node-files-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-files-api.d.ts","sourceRoot":"","sources":["../src/node-files-api.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,YAAa,YAAW,QAAQ;IAC3C,OAAO,CAAC,OAAO,CAAS;IAExB,YAAY,OAAO,CAAC,EAAE,mBAAmB,EAExC;IAED,OAAO,CAAC,WAAW;IAKZ,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAyC1E;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAuBf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvC;IAED,qFAAqF;IAC9E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAExE;IAED,mFAAmF;YACrE,YAAY;IAgCpB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAkBxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAS3C;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAc3C;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB3D;CACF"}
+{"version":3,"file":"node-files-api.d.ts","sourceRoot":"","sources":["../src/node-files-api.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,YAAa,YAAW,QAAQ;IAC3C,OAAO,CAAC,OAAO,CAAS;IAExB,YAAY,OAAO,CAAC,EAAE,mBAAmB,EAExC;IAED,+FAA+F;IAC/F,OAAO,CAAC,WAAW;IAQZ,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAyC1E;IAEK,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAuBf;IAEK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvC;IAED,qFAAqF;IAC9E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,QAAQ,CAAC,CAExE;IAED,mFAAmF;YACrE,YAAY;IAgCpB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAkBxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAS3C;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAc3C;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB3D;CACF"}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@statewalker/webrun-files-node",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "private": false,
   "type": "module",
   "description": "Node.js FilesApi implementation",
-  "homepage": "https://github.com/statewalker/webrun-files",
+  "bugs": {
+    "url": "https://github.com/statewalker/webrun-files/issues"
+  },
+  "homepage": "https://github.com/statewalker/webrun-files/tree/main/packages/webrun-files-node#readme",
   "author": {
     "name": "Mikhail Kotelnikov",
     "email": "mikhail.kotelnikov@gmail.com"
@@ -12,7 +15,8 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git@github.com:statewalker/webrun-files.git"
+    "url": "git+https://github.com/statewalker/webrun-files.git",
+    "directory": "packages/webrun-files-node"
   },
   "main": "./dist/cjs/index.cjs",
   "module": "./dist/esm/index.js",
@@ -30,7 +34,7 @@
     "src"
   ],
   "dependencies": {
-    "@statewalker/webrun-files": "^0.10.1"
+    "@statewalker/webrun-files": "^0.10.2"
   },
   "devDependencies": {
     "@types/node": "^26.6.4",

package/src/node-files-api.ts

@@ -1,5 +1,6 @@
 import type { Dirent, Stats } from "node:fs";
 import * as fs from "node:fs/promises";
+import * as nodePath from "node:path";
 import type {
   FileInfo,
   FileStats,
@@ -11,8 +12,8 @@ import { dirname, joinPath, listInPathOrder, normalizePath } from "@statewalker/
 
 export interface NodeFilesApiOptions {
   /**
-   * Root directory for file operations. All paths are resolved relative to this.
-   * Defaults to current working directory if not specified.
+   * Root directory for file operations. All paths are resolved relative to this, and a path
+   * whose `..` segments would leave it is refused. Defaults to the current working directory.
    */
   rootDir?: string;
 }
@@ -25,12 +26,16 @@ export class NodeFilesApi implements FilesApi {
   private rootDir: string;
 
   constructor(options?: NodeFilesApiOptions) {
-    this.rootDir = options?.rootDir ?? process.cwd();
+    this.rootDir = nodePath.resolve(options?.rootDir ?? process.cwd());
   }
 
+  /** The real path of a virtual one; throws when `..` segments would take it outside rootDir. */
   private resolvePath(virtualPath: string): string {
-    const normalized = normalizePath(virtualPath);
-    return this.rootDir + normalized;
+    const real = nodePath.resolve(this.rootDir, `.${normalizePath(virtualPath)}`);
+    if (real !== this.rootDir && !real.startsWith(this.rootDir + nodePath.sep)) {
+      throw new Error(`NodeFilesApi: path is outside rootDir: ${virtualPath}`);
+    }
+    return real;
   }
 
   async *read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array> {
@@ -82,7 +87,7 @@ export class NodeFilesApi implements FilesApi {
   ): Promise<void> {
     const realPath = this.resolvePath(path);
     const normalized = normalizePath(path);
-    const dir = this.rootDir + dirname(normalized);
+    const dir = this.resolvePath(dirname(normalized));
 
     await fs.mkdir(dir, { recursive: true });
 
@@ -206,7 +211,7 @@ export class NodeFilesApi implements FilesApi {
     }
 
     try {
-      const targetDir = this.rootDir + dirname(normalizedTarget);
+      const targetDir = this.resolvePath(dirname(normalizedTarget));
       await fs.mkdir(targetDir, { recursive: true });
       await fs.rename(sourcePath, targetPath);
       return true;
@@ -227,7 +232,7 @@ export class NodeFilesApi implements FilesApi {
     }
 
     try {
-      const targetDir = this.rootDir + dirname(normalizedTarget);
+      const targetDir = this.resolvePath(dirname(normalizedTarget));
       await fs.mkdir(targetDir, { recursive: true });
       await fs.cp(sourcePath, targetPath, { recursive: true });
       return true;