@statewalker/webrun-files-composite 0.10.2 → 0.10.4

package/README.md

@@ -29,7 +29,7 @@ the types `PathFilter`, `FileGuard`, `FileOperation`, `CowOptions` and
 
 ## Why it exists
 
-Real filesystems are rarely flat. Workbench-style apps need to combine
+Real file systems are rarely flat. Applications need to combine
 storage backends (local FS for projects, in-memory FS for transient data,
 remote FS for shared documents), forbid writes to system folders, and hide
 implementation-detail paths from end users. Implementing all of this inside
@@ -49,9 +49,13 @@ three concerns are deliberately split across separate classes:
 ## How to use
 
 ```bash
-pnpm add @statewalker/webrun-files-composite
+pnpm add @statewalker/webrun-files-composite @statewalker/webrun-files
 ```
 
+One entry point, `@statewalker/webrun-files-composite`: ESM (`dist/esm/index.js`), CommonJS
+(`dist/cjs/index.cjs`), types (`dist/index.d.ts`); sources in `src/`. No runtime-specific
+imports: browsers, workers, Node.js.
+
 The decorators all implement `FilesApi`, so they compose freely. A typical
 stack: a composite root that mounts a few backends, wrapped first with a
 filter to hide internals, then with guards to forbid writes to system
@@ -185,9 +189,26 @@ to gate these flows by composite path:
 await fs.move("/cache/draft.md", "/docs/draft.md"); // memFs → s3Fs
 ```
 
+### Read-only, overlay and copy-on-write views
+
+```ts
+import { cow, overlay, readOnly } from "@statewalker/webrun-files-composite";
+import { MemFilesApi } from "@statewalker/webrun-files-mem";
+
+const ro = readOnly(sourceFiles);
+await ro.write("/a.txt", data); // throws "read-only: /a.txt"
+
+// userFiles shadows defaultFiles; the union is read-only
+const view = overlay(userFiles, defaultFiles);
+
+// Changes land in the MemFilesApi; templateFiles is never modified
+const draft = cow(templateFiles, new MemFilesApi());
+await draft.remove("/obsolete.md"); // recorded as /.wh.obsolete.md in the writable layer
+```
+
 ## Internals
 
-### Architecture
+### How the decorators stack
 
 ```
 +---------------------+
@@ -255,7 +276,7 @@ multiple operation lists.
 | `move` / `copy`     | `false` (no side effect) |
 | `write` / `mkdir`   | throws `"Path is hidden"` (silent drop would lose data) |
 
-### Constraints
+### What it refuses, and what is not atomic
 
 - The root mount (`/`) is fixed at construction; you cannot remount it.
 - Mount points are immutable — `remove()` on a mount point throws.

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@statewalker/webrun-files-composite",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "private": false,
   "type": "module",
   "description": "Composite FilesApi with mount points and access guards",
-  "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-composite#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-composite"
   },
   "main": "./dist/cjs/index.cjs",
   "module": "./dist/esm/index.js",
@@ -30,16 +34,16 @@
     "src"
   ],
   "dependencies": {
-    "@statewalker/webrun-files": "^0.10.1"
+    "@statewalker/webrun-files": "^0.10.4"
   },
   "devDependencies": {
     "@types/node": "^26.6.4",
     "rimraf": "^6.1.3",
     "rolldown": "^1.2.12",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.3",
+    "vitest": "^4.1.4 || ^5.0.3",
     "@statewalker/webrun-files-tests": "^3.0.0",
-    "@statewalker/webrun-files-mem": "^0.10.2"
+    "@statewalker/webrun-files-mem": "^0.10.4"
   },
   "sideEffects": false,
   "publishConfig": {