@statewalker/webrun-files-composite 0.7.1 → 0.8.0

package/dist/esm/index.js

@@ -23,9 +23,42 @@ function joinPath(...segments) {
 }
 //#endregion
 //#region src/composite-files-api.ts
+/**
+* Composite `FilesApi` that routes calls to one of several backends based
+* on a path prefix. Mounts are matched by **longest prefix wins**, so a
+* mount at `/a/b` takes precedence over a mount at `/a` for paths under
+* `/a/b/...`. The mount point itself appears in listings as a synthetic
+* directory and cannot be removed.
+*
+* Each backend can use a sub-directory of its own filesystem as the mount
+* root via `fsPath` (constructor `rootPath` for the implicit root mount,
+* `fsPath` argument for additional mounts). Cross-mount `move` is
+* implemented as copy-then-delete; there is no atomicity guarantee.
+*
+* Access control and visibility filtering are intentionally **not** part of
+* this class — wrap with {@link GuardedFilesApi} or {@link FilteredFilesApi}
+* (or both) instead.
+*
+* @example
+* ```ts
+* const fs = new CompositeFilesApi(localFs, "/projects")
+*   .mount("/docs", s3Fs, "/documentation")
+*   .mount("/cache", memFs);
+* await fs.write("/readme.md", data); // → localFs:/projects/readme.md
+* await fs.write("/docs/api.md", data); // → s3Fs:/documentation/api.md
+* ```
+*/
 var CompositeFilesApi = class {
 	mounts;
-	guards = [];
+	/**
+	* @param root Default backend used for any path that does not match a
+	*   more specific mount. All paths are routed here unless `mount()`
+	*   intercepts them.
+	* @param rootPath Optional sub-directory of the root backend to use as
+	*   the composite filesystem's `/`. For example, `rootPath = "/projects"`
+	*   makes the composite path `/readme.md` resolve to `/projects/readme.md`
+	*   in the root backend. Defaults to `"/"` (no remapping).
+	*/
 	constructor(root, rootPath) {
 		this.mounts = [{
 			prefix: "/",
@@ -33,6 +66,22 @@ var CompositeFilesApi = class {
 			basePath: normalizePath(rootPath ?? "/")
 		}];
 	}
+	/**
+	* Attaches a backend to handle every composite path under `path`. The
+	* mount prefix is normalized; paths under it are resolved against the
+	* mount's `fsPath` sub-directory (defaulting to `"/"`).
+	*
+	* @param path Composite-namespace prefix (e.g. `"/docs"`). Mounting at
+	*   `"/"` is forbidden — use the constructor `root` argument instead.
+	* @param api The backend `FilesApi` to delegate to for paths under
+	*   `path`. Wrap it in {@link FilteredFilesApi} / {@link GuardedFilesApi}
+	*   first if you want mount-local filtering or guards.
+	* @param fsPath Sub-directory of the mounted backend used as its mount
+	*   root, e.g. `mount("/docs", s3, "/documentation")` makes
+	*   `/docs/api.md` resolve to `/documentation/api.md` on `s3`.
+	* @returns `this`, for chaining.
+	* @throws If `path` normalizes to `"/"`.
+	*/
 	mount(path, api, fsPath) {
 		const prefix = normalizePath(path);
 		if (prefix === "/") throw new Error("Cannot mount at root — root is set via constructor");
@@ -44,14 +93,6 @@ var CompositeFilesApi = class {
 		this.mounts.sort((a, b) => b.prefix.length - a.prefix.length);
 		return this;
 	}
-	guard(operations, check, message) {
-		this.guards.push({
-			operations,
-			check,
-			message
-		});
-		return this;
-	}
 	resolve(path) {
 		const normalized = normalizePath(path);
 		for (const mount of this.mounts) {
@@ -89,33 +130,19 @@ var CompositeFilesApi = class {
 		}
 		return result;
 	}
-	checkGuard(operation, path) {
-		const normalized = normalizePath(path);
-		for (const guard of this.guards) {
-			if (!guard.operations.includes(operation)) continue;
-			if (!guard.check(normalized)) {
-				const msg = guard.message ?? "Access denied";
-				throw new Error(`${msg}: ${normalized}`);
-			}
-		}
-	}
 	read(path, options) {
-		this.checkGuard("read", path);
 		const { api, resolvedPath } = this.resolve(path);
 		return api.read(resolvedPath, options);
 	}
 	async write(path, content) {
-		this.checkGuard("write", path);
 		const { api, resolvedPath } = this.resolve(path);
 		return api.write(resolvedPath, content);
 	}
 	async mkdir(path) {
-		this.checkGuard("mkdir", path);
 		const { api, resolvedPath } = this.resolve(path);
 		return api.mkdir(resolvedPath);
 	}
 	async *list(path, options) {
-		this.checkGuard("list", path);
 		const normalized = normalizePath(path);
 		const { api, resolvedPath } = this.resolve(path);
 		const childMounts = this.childMountPrefixes(normalized);
@@ -180,13 +207,10 @@ var CompositeFilesApi = class {
 	async remove(path) {
 		const normalized = normalizePath(path);
 		if (this.isMountPoint(normalized)) throw new Error(`Cannot remove mount point: ${normalized}`);
-		this.checkGuard("remove", path);
 		const { api, resolvedPath } = this.resolve(path);
 		return api.remove(resolvedPath);
 	}
 	async move(source, target) {
-		this.checkGuard("move", source);
-		this.checkGuard("move", target);
 		const src = this.resolve(source);
 		const tgt = this.resolve(target);
 		if (src.api === tgt.api) return src.api.move(src.resolvedPath, tgt.resolvedPath);
@@ -195,8 +219,6 @@ var CompositeFilesApi = class {
 		return copied;
 	}
 	async copy(source, target) {
-		this.checkGuard("copy", source);
-		this.checkGuard("copy", target);
 		const src = this.resolve(source);
 		const tgt = this.resolve(target);
 		if (src.api === tgt.api) return src.api.copy(src.resolvedPath, tgt.resolvedPath);
@@ -235,4 +257,402 @@ var CompositeFilesApi = class {
 	}
 };
 //#endregion
-export { CompositeFilesApi };
+//#region src/glob-to-regexp.ts
+/**
+* Compiles a glob pattern into a `RegExp`.
+*
+* @example
+* ```ts
+* globToRegExp("*.js");                       // /^.*\.js$/
+* globToRegExp("*.js", { globstar: true });   // /^([^/]*)\.js$/
+* globToRegExp("/foo/**", { globstar: true }) // /^\/foo\/((?:[^/]*(?:\/|$))*)$/
+* globToRegExp("foo{bar,baz}", { extended: true }); // /^foo(bar|baz)$/
+* ```
+*/
+function globToRegExp(glob, opts = {}) {
+	if (typeof glob !== "string") throw new TypeError("Expected a string");
+	const str = String(glob);
+	let reStr = "";
+	const extended = !!opts.extended;
+	const globstar = !!opts.globstar;
+	let inGroup = false;
+	const flags = typeof opts.flags === "string" ? opts.flags : "";
+	for (let i = 0; i < str.length; i++) {
+		const c = str[i];
+		switch (c) {
+			case "/":
+			case "$":
+			case "^":
+			case "+":
+			case ".":
+			case "(":
+			case ")":
+			case "=":
+			case "!":
+			case "|":
+				reStr += `\\${c}`;
+				break;
+			case "?":
+				reStr += extended ? "." : `\\${c}`;
+				break;
+			case "[":
+			case "]":
+				reStr += extended ? c : `\\${c}`;
+				break;
+			case "{":
+				if (extended) {
+					inGroup = true;
+					reStr += "(";
+				} else reStr += `\\${c}`;
+				break;
+			case "}":
+				if (extended) {
+					inGroup = false;
+					reStr += ")";
+				} else reStr += `\\${c}`;
+				break;
+			case ",":
+				if (inGroup) reStr += "|";
+				else reStr += `\\${c}`;
+				break;
+			case "*": {
+				const prevChar = str[i - 1];
+				let starCount = 1;
+				while (str[i + 1] === "*") {
+					starCount++;
+					i++;
+				}
+				const nextChar = str[i + 1];
+				if (!globstar) reStr += ".*";
+				else if (starCount > 1 && (prevChar === "/" || prevChar === void 0) && (nextChar === "/" || nextChar === void 0)) {
+					reStr += "((?:[^/]*(?:\\/|$))*)";
+					i++;
+				} else reStr += "([^/]*)";
+				break;
+			}
+			default: reStr += c;
+		}
+	}
+	if (!flags?.includes("g")) reStr = `^${reStr}$`;
+	return new RegExp(reStr, flags);
+}
+//#endregion
+//#region src/filtered-files-api.ts
+/**
+* Builds a {@link PathFilter} that hides any path whose normalized form
+* equals one of the provided prefixes or lives under `${prefix}/`.
+*
+* Prefixes are normalized through `normalizePath` (so `"foo"`, `"/foo"`, and
+* `"/foo/"` are equivalent). Empty / root entries are dropped — they would
+* otherwise hide every path.
+*
+* Matching is **boundary-aware**: the prefix `"/priv"` does not match the
+* path `"/private"` because there is no `/` boundary between them.
+*
+* @param pathPrefixes Path prefixes whose contents (and the prefix itself)
+*   should be hidden. Pass none to hide nothing.
+*
+* @example
+* ```ts
+* const filter = newPathFilter("/.git", "/node_modules");
+* filter("/src/index.ts"); // true
+* filter("/.git");         // false
+* filter("/.git/HEAD");    // false
+* filter("/notgit");       // true (boundary-aware, no false match)
+* ```
+*/
+function newPathFilter(...pathPrefixes) {
+	const normalized = pathPrefixes.map((p) => normalizePath(p)).filter((p) => p !== "/");
+	return (path) => {
+		const target = normalizePath(path);
+		for (const prefix of normalized) {
+			if (target === prefix) return false;
+			if (target.startsWith(`${prefix}/`)) return false;
+		}
+		return true;
+	};
+}
+/**
+* Builds a {@link PathFilter} that hides any path whose normalized form
+* matches at least one of the provided regular expressions.
+*
+* The path is normalized through `normalizePath` before matching, so a
+* regexp anchored on `^/` always sees a leading slash and never a trailing
+* one. The regexp's `lastIndex` is irrelevant — the filter calls `test`
+* via a fresh evaluation each time, but stateful (`/g`, `/y`) regexps
+* still mutate `lastIndex` across calls; pass non-stateful regexps unless
+* you know what you are doing.
+*
+* @param pathRegexps Regular expressions whose match means "hide this
+*   path". Pass none to hide nothing.
+*
+* @example
+* ```ts
+* // Hide every dotfile and every *.log file
+* const filter = newRegexpPathFilter(/\/\.[^/]+$/, /\.log$/);
+* filter("/src/index.ts"); // true
+* filter("/.env");         // false (matches /\/\.[^/]+$/)
+* filter("/build.log");    // false (matches /\.log$/)
+* ```
+*/
+function newRegexpPathFilter(...pathRegexps) {
+	return (path) => {
+		const target = normalizePath(path);
+		for (const regexp of pathRegexps) if (regexp.test(target)) return false;
+		return true;
+	};
+}
+/**
+* Builds a {@link PathFilter} that hides any path whose normalized form
+* matches at least one of the provided glob patterns.
+*
+* Each glob is compiled with `extended: true` and `globstar: true`, the
+* standard "filesystem-style" mode:
+*
+* - `*` matches any number of characters within a single path segment
+*   (does **not** cross `/`).
+* - `**` between slashes matches zero or more whole path segments.
+* - `?` matches exactly one character.
+* - `[abc]` / `[a-z]` matches a single character in the set / range.
+* - `{a,b,c}` matches one of the alternatives.
+*
+* Because matching is done on the **normalized** path (which always starts
+* with `/`), patterns that should match anywhere in the tree need a
+* leading `**​/`, e.g. `**​/*.log` to hide every `.log` file at any depth.
+*
+* Gotcha: `/foo/**` matches descendants of `/foo` but **not** `/foo`
+* itself, because the glob requires a `/` after `foo` before `**` can
+* match. To hide both the directory and its contents, list both prefixes:
+* `newGlobPathFilter("/foo", "/foo/**")`. {@link newPathFilter} doesn't
+* have this problem and may be a better fit for prefix-only hiding.
+*
+* @param pathGlobs Glob patterns whose match means "hide this path". Pass
+*   none to hide nothing.
+*
+* @example
+* ```ts
+* const filter = newGlobPathFilter("**​/*.log", "/.git", "/.git/**");
+* filter("/src/index.ts"); // true
+* filter("/build.log");    // false (matches **​/*.log)
+* filter("/.git");         // false (matches /.git)
+* filter("/.git/HEAD");    // false (matches /.git/**)
+* ```
+*/
+function newGlobPathFilter(...pathGlobs) {
+	return newRegexpPathFilter(...pathGlobs.map((glob) => globToRegExp(glob, {
+		extended: true,
+		globstar: true
+	})));
+}
+/**
+* `FilesApi` decorator that hides every path the supplied {@link PathFilter}
+* rejects. Hidden paths are treated as if they do not exist:
+*
+* - `read` / `list` yield empty iterables.
+* - `stats` returns `undefined`; `exists` returns `false`.
+* - `remove` returns `false` (no error, nothing changed).
+* - `move` / `copy` return `false` if either endpoint is hidden.
+* - `write` / `mkdir` reject with an `Error` (since silently dropping a
+*   write would lose data).
+* - `list` recursively skips entries whose paths are hidden, so iterating a
+*   visible parent never reveals a hidden child.
+*
+* Wrap any `FilesApi` to scope its visibility without changing the
+* underlying storage; the wrapped instance still holds the data, it is just
+* not reachable through this decorator.
+*
+* Pair with one of the built-in {@link PathFilter} factories
+* ({@link newPathFilter}, {@link newRegexpPathFilter},
+* {@link newGlobPathFilter}) or pass any predicate of shape
+* `(path) => boolean | Promise<boolean>`.
+*
+* @example
+* ```ts
+* import {
+*   FilteredFilesApi,
+*   newGlobPathFilter,
+*   newPathFilter,
+*   newRegexpPathFilter,
+* } from "@statewalker/webrun-files-composite";
+*
+* // Hide by path prefix
+* const noVcs = new FilteredFilesApi(sourceFiles, newPathFilter("/.git", "/.cache"));
+* await noVcs.exists("/.git");        // false
+* await noVcs.write("/.git/x", data); // throws "Path is hidden"
+*
+* // Hide by regexp
+* const noLogs = new FilteredFilesApi(sourceFiles, newRegexpPathFilter(/\.log$/));
+*
+* // Hide by glob (extended + globstar mode)
+* const noJunk = new FilteredFilesApi(
+*   sourceFiles,
+*   newGlobPathFilter("**​/*.log", "/.git", "/.git/**"),
+* );
+* ```
+*/
+var FilteredFilesApi = class {
+	source;
+	pathFilter;
+	/**
+	* @param source The underlying `FilesApi` whose paths will be selectively
+	*   hidden. Operations always delegate to this instance; the decorator
+	*   only adds the visibility check.
+	* @param pathFilter Predicate that decides per-call whether a normalized
+	*   path is visible. See {@link PathFilter}.
+	*/
+	constructor(source, pathFilter) {
+		this.source = source;
+		this.pathFilter = pathFilter;
+	}
+	async isHidden(path) {
+		return await this.pathFilter(normalizePath(path)) === false;
+	}
+	async *read(path, options) {
+		if (await this.isHidden(path)) return;
+		yield* this.source.read(path, options);
+	}
+	async write(path, content) {
+		if (await this.isHidden(path)) throw new Error(`Path is hidden: ${path}`);
+		await this.source.write(path, content);
+	}
+	async mkdir(path) {
+		if (await this.isHidden(path)) throw new Error(`Path is hidden: ${path}`);
+		await this.source.mkdir(path);
+	}
+	async *list(path, options) {
+		if (await this.isHidden(path)) return;
+		for await (const entry of this.source.list(path, options)) {
+			if (await this.isHidden(entry.path)) continue;
+			yield entry;
+		}
+	}
+	async stats(path) {
+		if (await this.isHidden(path)) return void 0;
+		return this.source.stats(path);
+	}
+	async exists(path) {
+		if (await this.isHidden(path)) return false;
+		return this.source.exists(path);
+	}
+	async remove(path) {
+		if (await this.isHidden(path)) return false;
+		return this.source.remove(path);
+	}
+	async move(source, target) {
+		if (await this.isHidden(source) || await this.isHidden(target)) return false;
+		return this.source.move(source, target);
+	}
+	async copy(source, target) {
+		if (await this.isHidden(source) || await this.isHidden(target)) return false;
+		return this.source.copy(source, target);
+	}
+};
+//#endregion
+//#region src/guarded-files-api.ts
+/**
+* `FilesApi` decorator that runs every call through an ordered list of
+* {@link FileGuard}s. A guard fires when its `operations` set intersects the
+* effective operation(s) for the current call. The first guard whose
+* `check` returns `false` aborts the call by throwing an `Error` with that
+* guard's `message` (defaulting to `"Access denied"`) followed by the
+* normalized path.
+*
+* Effective operations per call:
+*
+* | Method        | Operations checked                                  |
+* | ------------- | --------------------------------------------------- |
+* | `read`        | `read`                                              |
+* | `write`       | `write`                                             |
+* | `mkdir`       | `mkdir`                                             |
+* | `remove`      | `remove`                                            |
+* | `list`        | `list` on the path AND on each directory entry      |
+* | `stats`       | `list` (a stat reveals existence like a tiny list)  |
+* | `exists`      | `read` (existence is a read of metadata)            |
+* | `move(s, t)`  | `move`+`read` on source; `move`+`write` on target   |
+* | `copy(s, t)`  | `copy`+`read` on source; `copy`+`write` on target   |
+*
+* The expanded checks for `move`/`copy` mean a guard that blocks `read` on
+* a path also prevents move/copy *from* that path, and a `write`-blocking
+* guard prevents move/copy *to* it. Likewise, an `exists` call respects any
+* read guard, and `stats` respects any list guard.
+*
+* @example
+* ```ts
+* const api = new GuardedFilesApi(source, [
+*   {
+*     operations: ["write", "remove", "move", "mkdir"],
+*     check: (p) => !p.startsWith("/.system/"),
+*     message: "system folder is read-only",
+*   },
+* ]);
+* await api.write("/.system/cfg", data); // throws "system folder is read-only: /.system/cfg"
+* ```
+*/
+var GuardedFilesApi = class {
+	source;
+	guards;
+	/**
+	* @param source The underlying `FilesApi` whose calls will be policed.
+	*   Allowed operations delegate straight through.
+	* @param guards Ordered list of access policies. The wrapper takes a
+	*   defensive copy, so mutating the array afterwards has no effect.
+	*   An empty list disables every check (the wrapper becomes a passthrough).
+	*/
+	constructor(source, guards) {
+		this.source = source;
+		this.guards = [...guards];
+	}
+	checkGuard(path, ...operations) {
+		const normalized = normalizePath(path);
+		for (const guard of this.guards) {
+			if (!operations.some((op) => guard.operations.includes(op))) continue;
+			if (!guard.check(normalized)) {
+				const msg = guard.message ?? "Access denied";
+				throw new Error(`${msg}: ${normalized}`);
+			}
+		}
+	}
+	read(path, options) {
+		this.checkGuard(path, "read");
+		return this.source.read(path, options);
+	}
+	async write(path, content) {
+		this.checkGuard(path, "write");
+		return this.source.write(path, content);
+	}
+	async mkdir(path) {
+		this.checkGuard(path, "mkdir");
+		return this.source.mkdir(path);
+	}
+	async *list(path, options) {
+		this.checkGuard(path, "list");
+		for await (const info of this.source.list(path, options)) {
+			if (info.kind === "directory") this.checkGuard(info.path, "list");
+			yield info;
+		}
+	}
+	stats(path) {
+		this.checkGuard(path, "list");
+		return this.source.stats(path);
+	}
+	exists(path) {
+		this.checkGuard(path, "read");
+		return this.source.exists(path);
+	}
+	async remove(path) {
+		this.checkGuard(path, "remove");
+		return this.source.remove(path);
+	}
+	async move(source, target) {
+		this.checkGuard(source, "move", "read");
+		this.checkGuard(target, "move", "write");
+		return this.source.move(source, target);
+	}
+	async copy(source, target) {
+		this.checkGuard(source, "copy", "read");
+		this.checkGuard(target, "copy", "write");
+		return this.source.copy(source, target);
+	}
+};
+//#endregion
+export { CompositeFilesApi, FilteredFilesApi, GuardedFilesApi, globToRegExp, newGlobPathFilter, newPathFilter, newRegexpPathFilter };