@effected/walker 0.14.1 → 0.15.0

package/Descend.js

@@ -12,6 +12,7 @@ import { Effect, FileSystem, Path, Schema } from "effect";
 var DescendError = class extends Schema.TaggedError()("DescendError", {
 	/** The glob pattern's source text. */
 	pattern: Schema.String,
+	/** Why the walk failed: a directory could not be read, or the walk went past `maxDepth`. */
 	reason: Schema.Literals(["unreadableDirectory", "depthExceeded"]),
 	/** The offending directory, relative to `cwd` (`""` is the walk's base). */
 	path: Schema.String,

package/Expand.js

@@ -69,13 +69,18 @@ var GlobExpansionError = class extends Schema.TaggedError()("GlobExpansionError"
 *
 * @example
 * ```ts
-* import { compileAndExpand } from "@effected/walker"
-* import { GlobPatternOptions } from "@effected/glob"
+* import { GlobPatternOptions } from "@effected/glob";
+* import { compileAndExpand } from "@effected/walker";
+* import { Effect } from "effect";
 *
-* const files = yield* compileAndExpand("packages/*​/src/**​/*.ts", {
-*   cwd: "/repo",
-*   glob: GlobPatternOptions.make({ dot: true })
-* })
+* const program = Effect.gen(function* () {
+* 	// Sorted, cwd-relative POSIX paths; fails with `GlobExpansionError`.
+* 	return yield* compileAndExpand("src/*.ts", {
+* 		cwd: "/repo",
+* 		glob: GlobPatternOptions.make({ dot: true }),
+* 	});
+* });
+* // Requires `FileSystem` and `Path` from the platform layer.
 * ```
 *
 * @public

package/README.md

@@ -7,10 +7,10 @@
 
 Path traversal as Effect primitives. `Walker.ascend` gives you the directory chain from a starting path to the filesystem root; `Walker.findUpward` returns the nearest existing file among per-directory candidates; `Walker.findRoot` returns the nearest directory a marker predicate accepts. Every probe absorbs its own failure, so a single unreadable ancestor cannot hide a valid `.git` or `pnpm-workspace.yaml` above it. Going the other way, `descend` expands a compiled [`@effected/glob`](https://www.npmjs.com/package/@effected/glob) pattern under a directory into the matching file paths — sorted, symlink-safe, and typed about unreadable subtrees instead of silently swallowing them. `FileSystem` and `Path` arrive from `effect` core, so no platform package is pulled in — not even in tests.
 
-> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 prerelease. Packages graduate to
-> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
-> exactly the ones the kit is built and tested against, install
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
 >
 > **Stability: unstable.** This package's API surface is not yet considered

package/Walker.js

@@ -49,7 +49,8 @@ const findUpward = (dirs, candidatesFor) => Effect.gen(function* () {
 });
 const findRoot = (dirs, isRoot) => firstMatch(dirs, isRoot);
 /**
-* Upward path traversal primitives.
+* Upward path traversal primitives: the directory chain from a start path to the
+* root, and first-match scans over it.
 *
 * @public
 */
@@ -69,13 +70,25 @@ var Walker = class {
 	* a pathological `Path` implementation that never reaches one.
 	*
 	* `stopAt` is compared in normalized form — see {@link AscendOptions.stopAt}.
-	* Raw string equality made the ceiling fail OPEN: an unnormalized ceiling
-	* matched nothing and the ascent ran silently to the filesystem root, which is
-	* the unbounded walk the option exists to prevent, with no error to notice it
-	* by. A relative ceiling **dies** for the same reason — resolving one against
-	* `process.cwd()` would reintroduce the silent-wrong-walk failure through a
-	* different door. See {@link AscendOptions.stopAt} for why that is a defect
-	* rather than a typed error; the error channel stays `never`.
+	* Comparing raw strings would let an unnormalized ceiling match nothing and
+	* the ascent run silently to the filesystem root, which is the unbounded walk
+	* the option exists to prevent. A relative ceiling **dies** for the same
+	* reason — resolving one against `process.cwd()` would reintroduce the
+	* silent-wrong-walk failure through a different door. See
+	* {@link AscendOptions.stopAt} for why that is a defect rather than a typed
+	* error; the error channel stays `never`.
+	*
+	* @example
+	* ```ts
+	* import { Walker } from "@effected/walker";
+	* import { Effect } from "effect";
+	*
+	* const program = Effect.gen(function* () {
+	* 	// => ["/repo/packages/app", "/repo/packages", "/repo"]
+	* 	return yield* Walker.ascend("/repo/packages/app", { stopAt: "/repo" });
+	* });
+	* // Requires `Path` from the platform layer.
+	* ```
 	*/
 	static ascend = ascend;
 	/**

package/index.d.ts

@@ -109,6 +109,7 @@ interface DescendResult {
 declare const DescendError_base: Schema.Class<DescendError, Schema.TaggedStruct<"DescendError", {
   /** The glob pattern's source text. */
   readonly pattern: Schema.String;
+  /** Why the walk failed: a directory could not be read, or the walk went past `maxDepth`. */
   readonly reason: Schema.Literals<readonly ["unreadableDirectory", "depthExceeded"]>;
   /** The offending directory, relative to `cwd` (`""` is the walk's base). */
   readonly path: Schema.String;
@@ -182,6 +183,20 @@ export declare function descend(pattern: GlobPattern, options: DescendRecordOpti
  * Passing `onUnreadable: "record"` resolves to a {@link DescendResult}
  * instead — see that overload.
  *
+ * @example
+ * ```ts
+ * import { GlobPattern } from "@effected/glob";
+ * import { descend } from "@effected/walker";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const pattern = yield* GlobPattern.compile("src/*.ts");
+ * 	// Sorted, cwd-relative POSIX paths of the matching files.
+ * 	return yield* descend(pattern, { cwd: "/repo" });
+ * });
+ * // Requires `FileSystem` and `Path` from the platform layer.
+ * ```
+ *
  * @public
  */
 export declare function descend(pattern: GlobPattern, options: DescendOptions): Effect.Effect<ReadonlyArray<string>, DescendError, FileSystem.FileSystem | Path.Path>;
@@ -271,13 +286,18 @@ export declare class GlobExpansionError extends GlobExpansionError_base {
  *
  * @example
  * ```ts
- * import { compileAndExpand } from "@effected/walker"
- * import { GlobPatternOptions } from "@effected/glob"
+ * import { GlobPatternOptions } from "@effected/glob";
+ * import { compileAndExpand } from "@effected/walker";
+ * import { Effect } from "effect";
  *
- * const files = yield* compileAndExpand("packages/*​/src/**​/*.ts", {
- *   cwd: "/repo",
- *   glob: GlobPatternOptions.make({ dot: true })
- * })
+ * const program = Effect.gen(function* () {
+ * 	// Sorted, cwd-relative POSIX paths; fails with `GlobExpansionError`.
+ * 	return yield* compileAndExpand("src/*.ts", {
+ * 		cwd: "/repo",
+ * 		glob: GlobPatternOptions.make({ dot: true }),
+ * 	});
+ * });
+ * // Requires `FileSystem` and `Path` from the platform layer.
  * ```
  *
  * @public
@@ -341,7 +361,8 @@ interface AscendOptions {
   readonly maxDepth?: number;
 }
 /**
- * Upward path traversal primitives.
+ * Upward path traversal primitives: the directory chain from a start path to the
+ * root, and first-match scans over it.
  *
  * @public
  */
@@ -361,13 +382,25 @@ export declare class Walker {
    * a pathological `Path` implementation that never reaches one.
    *
    * `stopAt` is compared in normalized form — see {@link AscendOptions.stopAt}.
-   * Raw string equality made the ceiling fail OPEN: an unnormalized ceiling
-   * matched nothing and the ascent ran silently to the filesystem root, which is
-   * the unbounded walk the option exists to prevent, with no error to notice it
-   * by. A relative ceiling **dies** for the same reason — resolving one against
-   * `process.cwd()` would reintroduce the silent-wrong-walk failure through a
-   * different door. See {@link AscendOptions.stopAt} for why that is a defect
-   * rather than a typed error; the error channel stays `never`.
+   * Comparing raw strings would let an unnormalized ceiling match nothing and
+   * the ascent run silently to the filesystem root, which is the unbounded walk
+   * the option exists to prevent. A relative ceiling **dies** for the same
+   * reason — resolving one against `process.cwd()` would reintroduce the
+   * silent-wrong-walk failure through a different door. See
+   * {@link AscendOptions.stopAt} for why that is a defect rather than a typed
+   * error; the error channel stays `never`.
+   *
+   * @example
+   * ```ts
+   * import { Walker } from "@effected/walker";
+   * import { Effect } from "effect";
+   *
+   * const program = Effect.gen(function* () {
+   * 	// => ["/repo/packages/app", "/repo/packages", "/repo"]
+   * 	return yield* Walker.ascend("/repo/packages/app", { stopAt: "/repo" });
+   * });
+   * // Requires `Path` from the platform layer.
+   * ```
    */
   static readonly ascend: (start: string, options?: AscendOptions) => Effect.Effect<ReadonlyArray<string>, never, Path.Path>;
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/walker",
-	"version": "0.14.1",
+	"version": "0.15.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.9.0",
-		"effect": "4.0.0-rc.118"
+		"@effected/glob": "^0.10.0",
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"