@effected/walker 0.5.0 → 0.7.0

package/Descend.js

@@ -2,7 +2,7 @@ import { Effect, FileSystem, Path, Schema } from "effect";
 
 //#region src/Descend.ts
 /**
-* Typed failure raised by {@link descend}: a directory mid-walk was unreadable
+* Typed failure raised by `descend`: a directory mid-walk was unreadable
 * (under `onUnreadable: "fail"`), or the walk descended past `maxDepth`. Depth
 * exhaustion is a typed failure, never a truncation — silent truncation
 * silently changes match semantics.
@@ -41,57 +41,32 @@ const escapesCwd = (relative) => {
 	}
 	return false;
 };
-/**
-* Expand a compiled glob pattern against the filesystem, returning matching
-* FILE paths relative to `cwd` (POSIX separators), sorted by relative path.
-*
-* @remarks
-* A literal pattern (no magic, not negated) fast-paths to a single stat: the
-* result is `[source]` when it resolves to a file, `[]` otherwise — a missing
-* path is zero matches, not an error. A magic pattern walks from its literal
-* directory prefix (`GlobPattern.enumerationPrefix`); a NEGATED pattern can
-* match paths outside that prefix, so it walks from `cwd` itself. A missing
-* base directory is likewise an empty result, because zero matches is a
-* normal glob answer — as is any pattern that lexically climbs above `cwd`
-* via `..` segments (walked paths never contain `..`, and the walk never
-* reads outside its documented root). Only an unreadable directory mid-walk
-* (under the default `onUnreadable: "fail"`) or a walk past `maxDepth` fails,
-* typed as {@link DescendError}.
-*
-* Only files match. A symlink counts when it stat-resolves to a file
-* (`FileSystem.stat` follows links, as node's does); a symlinked directory is
-* never descended into (cycle safety — detected by a `readLink` probe); a
-* dangling symlink is not a match. A directory that vanishes between its
-* parent's listing and its own read is a benign race and reads as empty. A
-* pattern that cannot match below one level (no globstar, no mid-pattern
-* magic segment) reads a single level and never descends.
-*
-* The descent is a worklist, not a recursion — it cannot overflow the stack —
-* dequeued by head index, never `Array.shift()`. Like `ascend`, `maxDepth`
-* must be a positive integer: anything else is a defect, never a
-* silently-empty result.
-*
-* @public
-*/
-const descend = Effect.fn("Walker.descend")(function* (pattern, options) {
+/** Not exported — `descend`'s overloads below carry the public documentation. */
+const descendImpl = Effect.fn("Walker.descend")(function* (pattern, options) {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	const maxDepth = options.maxDepth ?? 256;
 	if (!Number.isInteger(maxDepth) || maxDepth < 1) return yield* Effect.die(/* @__PURE__ */ new Error(`Walker.descend: maxDepth must be a positive integer, received ${maxDepth}`));
 	const prune = new Set(options.prune ?? DEFAULT_PRUNE);
 	const onUnreadable = options.onUnreadable ?? "fail";
+	const unreadable = [];
 	/** The stat-resolved type of `absolute`, or `undefined` when it does not resolve (missing, dangling symlink, unstatable). */
 	const typeOf = (absolute) => fs.stat(absolute).pipe(Effect.map((info) => info.type), Effect.orElseSucceed(() => void 0));
 	/** Whether `absolute` is itself a symlink. `readLink` succeeds only on links; any failure means "not one". */
 	const isSymbolicLink = (absolute) => fs.readLink(absolute).pipe(Effect.map(() => true), Effect.orElseSucceed(() => false));
+	/** Wrap the walk's success value per `onUnreadable`: a plain array unless "record" asked for the pair. */
+	const finish = (matches) => onUnreadable === "record" ? {
+		matches,
+		unreadable
+	} : matches;
 	if (!pattern.hasMagic && !pattern.negated) {
-		if (escapesCwd(pattern.source)) return [];
-		return (yield* typeOf(path.join(options.cwd, pattern.source))) === "File" ? [pattern.source] : [];
+		if (escapesCwd(pattern.source)) return finish([]);
+		return finish((yield* typeOf(path.join(options.cwd, pattern.source))) === "File" ? [pattern.source] : []);
 	}
 	const base = pattern.negated ? "" : pattern.enumerationPrefix.replace(/\/+$/, "");
-	if (escapesCwd(base)) return [];
+	if (escapesCwd(base)) return finish([]);
 	const absoluteBase = base === "" ? options.cwd : path.join(options.cwd, base);
-	if ((yield* typeOf(absoluteBase)) !== "Directory") return [];
+	if ((yield* typeOf(absoluteBase)) !== "Directory") return finish([]);
 	const deep = pattern.crossesSegments || pattern.negated;
 	const results = [];
 	const frames = [{
@@ -102,11 +77,16 @@ const descend = Effect.fn("Walker.descend")(function* (pattern, options) {
 	for (let head = 0; head < frames.length; head += 1) {
 		const frame = frames[head];
 		if (frame === void 0) break;
-		const entries = yield* fs.readDirectory(frame.absolute).pipe(Effect.catch((error) => error.reason._tag === "NotFound" || onUnreadable === "skip" ? Effect.succeed([]) : Effect.fail(new DescendError({
-			pattern: pattern.source,
-			reason: "unreadableDirectory",
-			path: frame.relative
-		}))));
+		const entries = yield* fs.readDirectory(frame.absolute).pipe(Effect.catch((error) => {
+			if (error.reason._tag === "NotFound") return Effect.succeed([]);
+			if (onUnreadable === "fail") return Effect.fail(new DescendError({
+				pattern: pattern.source,
+				reason: "unreadableDirectory",
+				path: frame.relative
+			}));
+			if (onUnreadable === "record") unreadable.push(frame.relative);
+			return Effect.succeed([]);
+		}));
 		for (const entry of entries) {
 			const relative = frame.relative === "" ? entry : `${frame.relative}/${entry}`;
 			const absolute = path.join(frame.absolute, entry);
@@ -132,8 +112,11 @@ const descend = Effect.fn("Walker.descend")(function* (pattern, options) {
 		}
 	}
 	results.sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
-	return results;
+	return finish(results);
 });
+function descend(pattern, options) {
+	return descendImpl(pattern, options);
+}
 
 //#endregion
 export { DescendError, descend };

package/Expand.js

@@ -45,7 +45,7 @@ var GlobExpansionError = class extends Schema.TaggedError()("GlobExpansionError"
 * matching FILE paths relative to `options.cwd`, POSIX separators, sorted.
 *
 * @remarks
-* The recipe form of {@link descend}. Everything `descend` documents about
+* The recipe form of `descend`. Everything `descend` documents about
 * traversal holds unchanged — the literal fast-path, the negated-pattern walk
 * from `cwd`, files-only matching, symlink and prune handling, `maxDepth`,
 * `onUnreadable` — because this delegates to it. What this adds is the seam:

package/index.d.ts

@@ -2,7 +2,7 @@ import { GlobPattern, GlobPatternError, GlobPatternOptions } from "@effected/glo
 import { Effect, FileSystem, Option, Path, Schema } from "effect";
 //#region src/Descend.d.ts
 /**
- * Options for {@link descend}.
+ * Options for `descend`.
  *
  * @public
  */
@@ -17,10 +17,61 @@ interface DescendOptions {
    * What an unreadable directory mid-walk does. `"fail"` (the default) fails
    * typed — downward enumeration must not silently swallow a subtree, or the
    * answer is silently missing membership dressed as an empty one. `"skip"`
-   * absorbs the failure and continues.
+   * absorbs the failure and continues, discarding which directory it was.
+   * To collect the offending directories instead of discarding them, pass
+   * {@link DescendRecordOptions} — `"record"` is deliberately NOT a member
+   * here, because this type is the options contract of the overload that
+   * returns a bare match array.
    */
   readonly onUnreadable?: "fail" | "skip";
 }
+/**
+ * Options for `descend` under `onUnreadable: "record"`: every
+ * {@link DescendOptions} field, with `onUnreadable` fixed to `"record"`.
+ *
+ * @remarks
+ * A separate type rather than `DescendOptions & { onUnreadable: "record" }`,
+ * because the two options types are the discriminator between two different
+ * RETURN types. If `DescendOptions` itself admitted `"record"`, a value
+ * widened to `DescendOptions` — annotated as such, or passed through a
+ * function taking it — would select the array-returning overload at compile
+ * time while the implementation resolved a {@link DescendResult} at runtime,
+ * and every array method on that result would fail with no type error
+ * anywhere. Keeping `"record"` out of `DescendOptions` makes that
+ * unrepresentable.
+ *
+ * @public
+ */
+interface DescendRecordOptions extends Omit<DescendOptions, "onUnreadable"> {
+  /** Collect every unreadable directory rather than failing or discarding it. */
+  readonly onUnreadable: "record";
+}
+/**
+ * `descend`'s success value under `onUnreadable: "record"`: the matched
+ * FILE paths plus the `cwd`-relative path of every mid-walk directory whose
+ * `readDirectory` failed for a reason other than `NotFound` (a vanished
+ * directory stays a benign race in every mode and is never recorded).
+ *
+ * @public
+ */
+interface DescendResult {
+  /** Matching FILE paths relative to `cwd`, POSIX separators, sorted — identical in shape to the `"fail"`/`"skip"` success value. */
+  readonly matches: ReadonlyArray<string>;
+  /**
+   * `cwd`-relative paths of directories that could not be read, in walk order.
+   *
+   * @remarks
+   * **The walk base appears as the empty string `""`**, since its own
+   * `cwd`-relative path is empty — so an unreadable base yields
+   * `{ matches: [], unreadable: [""] }`. Code matching these entries as
+   * ordinary paths will not expect that; special-case it.
+   *
+   * No cause travels with an entry. A caller that must report WHY a directory
+   * was unreadable has to re-read it to obtain the `PlatformError`, which is
+   * a second syscall for information this walk had and discarded.
+   */
+  readonly unreadable: ReadonlyArray<string>;
+}
 declare const DescendError_base: Schema.Class<DescendError, Schema.TaggedStruct<"DescendError", {
   /** The glob pattern's source text. */
   readonly pattern: Schema.String;
@@ -31,16 +82,28 @@ declare const DescendError_base: Schema.Class<DescendError, Schema.TaggedStruct<
   readonly limit: Schema.optionalKey<Schema.Number>;
 }>, import("effect/Cause").YieldableError>;
 /**
- * Typed failure raised by {@link descend}: a directory mid-walk was unreadable
+ * Typed failure raised by `descend`: a directory mid-walk was unreadable
  * (under `onUnreadable: "fail"`), or the walk descended past `maxDepth`. Depth
  * exhaustion is a typed failure, never a truncation — silent truncation
  * silently changes match semantics.
  *
  * @public
  */
-declare class DescendError extends DescendError_base {
+export declare class DescendError extends DescendError_base {
   get message(): string;
 }
+/**
+ * Expand a compiled glob pattern against the filesystem under
+ * `onUnreadable: "record"`, resolving to a {@link DescendResult} — the
+ * matched FILE paths relative to `cwd` (POSIX separators, sorted) plus the
+ * `cwd`-relative path of every mid-walk directory whose `readDirectory`
+ * failed for a reason other than `NotFound`. The walk continues past each
+ * such directory exactly as `"skip"` does; it never aborts and it never
+ * discards the offending path.
+ *
+ * @public
+ */
+export declare function descend(pattern: GlobPattern, options: DescendRecordOptions): Effect.Effect<DescendResult, DescendError, FileSystem.FileSystem | Path.Path>;
 /**
  * Expand a compiled glob pattern against the filesystem, returning matching
  * FILE paths relative to `cwd` (POSIX separators), sorted by relative path.
@@ -71,9 +134,12 @@ declare class DescendError extends DescendError_base {
  * must be a positive integer: anything else is a defect, never a
  * silently-empty result.
  *
+ * Passing `onUnreadable: "record"` resolves to a {@link DescendResult}
+ * instead — see that overload.
+ *
  * @public
  */
-declare const descend: (pattern: GlobPattern, options: DescendOptions) => Effect.Effect<ReadonlyArray<string>, DescendError, FileSystem.FileSystem | Path.Path>;
+export declare function descend(pattern: GlobPattern, options: DescendOptions): Effect.Effect<ReadonlyArray<string>, DescendError, FileSystem.FileSystem | Path.Path>;
 //#endregion
 //#region src/Expand.d.ts
 /**
@@ -122,7 +188,7 @@ declare const GlobExpansionError_base: Schema.Class<GlobExpansionError, Schema.T
  *
  * @public
  */
-declare class GlobExpansionError extends GlobExpansionError_base {
+export declare class GlobExpansionError extends GlobExpansionError_base {
   /**
    * Which phase failed — `"compile"` when the pattern itself was rejected,
    * `"descend"` when the filesystem walk failed. A convenience over
@@ -136,7 +202,7 @@ declare class GlobExpansionError extends GlobExpansionError_base {
  * matching FILE paths relative to `options.cwd`, POSIX separators, sorted.
  *
  * @remarks
- * The recipe form of {@link descend}. Everything `descend` documents about
+ * The recipe form of `descend`. Everything `descend` documents about
  * traversal holds unchanged — the literal fast-path, the negated-pattern walk
  * from `cwd`, files-only matching, symlink and prune handling, `maxDepth`,
  * `onUnreadable` — because this delegates to it. What this adds is the seam:
@@ -171,7 +237,7 @@ declare class GlobExpansionError extends GlobExpansionError_base {
  *
  * @public
  */
-declare const compileAndExpand: (pattern: string, options: CompileAndExpandOptions) => Effect.Effect<ReadonlyArray<string>, GlobExpansionError, FileSystem.FileSystem | Path.Path>;
+export declare const compileAndExpand: (pattern: string, options: CompileAndExpandOptions) => Effect.Effect<ReadonlyArray<string>, GlobExpansionError, FileSystem.FileSystem | Path.Path>;
 //#endregion
 //#region src/Walker.d.ts
 /**
@@ -229,7 +295,7 @@ interface AscendOptions {
  *
  * @public
  */
-declare class Walker {
+export declare class Walker {
   private constructor();
   /**
    * Ascend from `start` toward the filesystem root, yielding each directory,
@@ -289,5 +355,5 @@ declare class Walker {
   static readonly findRoot: <E, R>(dirs: ReadonlyArray<string>, isRoot: (dir: string) => Effect.Effect<boolean, E, R>) => Effect.Effect<Option.Option<string>, never, R>;
 }
 //#endregion
-export { type AscendOptions, type CompileAndExpandOptions, DescendError, type DescendOptions, GlobExpansionError, Walker, compileAndExpand, descend };
+export type { AscendOptions, CompileAndExpandOptions, DescendOptions, DescendRecordOptions, DescendResult };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/walker",
-	"version": "0.5.0",
+	"version": "0.7.0",
 	"private": false,
 	"description": "Path traversal as Effect primitives: ascend a directory chain to the first matching candidate, or descend a tree expanding a glob against the filesystem.",
 	"keywords": [
@@ -37,8 +37,8 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/glob": "^0.4.0",
-		"effect": "4.0.0-rc.109"
+		"@effected/glob": "^0.5.0",
+		"effect": "4.0.0-rc.112"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.58.12"
+      "packageVersion": "7.59.0"
     }
   ]
 }