@effected/walker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @effected/walker
+
+[![npm](https://img.shields.io/npm/v/@effected%2Fwalker?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/walker)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+Upward 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. `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 beta. 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
+> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
+>
+> **Stability: unstable.** This package's API surface is not yet considered
+> complete and may change across `0.x` releases. Pin an exact version — even a
+> package marked *stable* before `1.0.0` can introduce a breaking change by
+> accident, and an exact pin turns that into a type-check error rather than a
+> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Why @effected/walker
+
+Walking up a directory tree looks like four lines of code until you meet the edges, and the edges are where the hand-rolled version quietly gets it wrong. If a probe on one ancestor fails — an `EACCES` on a directory you had no business reading anyway — the naive loop propagates that error and the whole search fails, so an unreadable directory hides the workspace root sitting one level above it. Walker absorbs each probe individually: a failed probe means "this candidate did not match", never "abort the scan". Every public error channel is `never` as a result, and the trade is stated up front rather than discovered later — not-found and cannot-look are deliberately indistinguishable, because discovery is best-effort.
+
+The other edges get the same treatment. Absorption uses `Effect.catch`, which catches failures and not defects, so a predicate that *throws* is still programmer error and still surfaces. `findUpward` scans directory-major — every candidate in the nearest directory is exhausted before ascending — so a distant ancestor's `.apprc` can never beat a nearer `config/.apprc`. `maxDepth` must be a positive integer: `NaN`, `2.5` and `0` are defects rather than a silently empty chain, which is the failure mode that looks exactly like "nothing found". And `start` is required — walker never reads `process.cwd()` on your behalf.
+
+## Install
+
+```bash
+npm install @effected/walker effect
+```
+
+```bash
+pnpm add @effected/walker effect
+```
+
+Requires Node.js >=24.11.0. `effect` v4 is a peer dependency, and it is the only one — walker has no runtime dependencies of its own.
+
+`Path` and `FileSystem` come from `effect` core, not from a platform package, so a consumer provides them once at the edge (`@effect/platform-node` on Node, `@effect/platform-bun` on Bun) and a test provides `Path.layer` and `FileSystem.layerNoop` straight from core with nothing else installed.
+
+## Quick start
+
+Ascend from a directory, then look for a file in each rung of the chain:
+
+```ts
+import { Walker } from "@effected/walker";
+import { NodeFileSystem, NodePath } from "@effect/platform-node";
+import { Effect, Layer, Option, Path } from "effect";
+
+const findConfig = Effect.gen(function* () {
+  const path = yield* Path.Path;
+  const dirs = yield* Walker.ascend(process.cwd());
+  return yield* Walker.findUpward(dirs, (dir) => [path.join(dir, ".apprc")]);
+});
+
+const PlatformLive = Layer.mergeAll(NodeFileSystem.layer, NodePath.layer);
+
+Effect.runPromise(findConfig.pipe(Effect.provide(PlatformLive))).then((found) => console.log(Option.getOrNull(found)));
+// the path of the nearest ".apprc" at or above the cwd, e.g. "/home/you/project/.apprc"
+// null when no ancestor had one — or when the one that did could not be read
+```
+
+`findRoot` is the same loop over the directories themselves, with a marker predicate instead of a filename:
+
+```ts
+import { Walker } from "@effected/walker";
+import { Effect, FileSystem, Path } from "effect";
+
+const findGitRoot = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const dirs = yield* Walker.ascend(process.cwd());
+  return yield* Walker.findRoot(dirs, (dir) => fs.exists(path.join(dir, ".git")));
+});
+// Effect<Option<string>, never, FileSystem | Path> — the predicate's failures are absorbed per directory
+```
+
+The predicate can be expensive — reading and parsing a `package.json` to decide whether a directory is a workspace root, say — because the scan short-circuits at the first match and never probes the rest.
+
+## Features
+
+- `Walker.ascend(start, options?)` — the directory chain from `start` toward the filesystem root, nearest first. `stopAt` halts the ascent inclusively, `maxDepth` (default 256) caps it. Lexical, not physical: `Path.dirname` does not resolve symlinks, so ascending out of a symlinked directory follows the path you were given.
+- `Walker.firstMatch(candidates, predicate)` — the first candidate the predicate accepts. Absorbs each predicate failure individually and short-circuits at the first match.
+- `Walker.findUpward(dirs, candidatesFor)` — the first existing path, directory-major: every candidate in the nearest directory is tried before ascending.
+- `Walker.findRoot(dirs, isRoot)` — the nearest directory a marker predicate accepts. `firstMatch` where the candidate expansion is the identity.
+
+## License
+
+[MIT](LICENSE)

package/Walker.js

@@ -0,0 +1,94 @@
+import { Effect, FileSystem, Option, Path } from "effect";
+
+//#region src/Walker.ts
+/**
+* Ascend from `start` toward the filesystem root, yielding each directory,
+* nearest first.
+*
+* @remarks
+* Lexical, not physical: `Path.dirname` does not resolve symlinks, so ascending
+* out of a symlinked directory follows the path you were given rather than the
+* real filesystem parent. That is deliberate — config discovery wants the file
+* nearest the path the user named.
+*
+* Bounded twice over: `dirname` is a fixpoint at the root, and `maxDepth` guards
+* a pathological `Path` implementation that never reaches one.
+*
+* @public
+*/
+const ascend = (start, options) => Effect.gen(function* () {
+	const path = yield* Path.Path;
+	const maxDepth = options?.maxDepth ?? 256;
+	if (!Number.isInteger(maxDepth) || maxDepth < 1) return yield* Effect.die(/* @__PURE__ */ new Error(`Walker.ascend: maxDepth must be a positive integer, received ${maxDepth}`));
+	const dirs = [];
+	let current = start;
+	for (let depth = 0; depth < maxDepth; depth++) {
+		dirs.push(current);
+		if (options?.stopAt !== void 0 && current === options.stopAt) break;
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	return dirs;
+});
+/**
+* The first candidate whose `predicate` reports true, or `Option.none()`.
+*
+* @remarks
+* Each predicate is absorbed **individually**: a failure on one candidate is
+* treated as "this candidate did not match" and the scan continues. One
+* unreadable ancestor must never abort the walk, or a permission error deep in
+* the tree would hide a valid root above it. Not-found and cannot-look are
+* therefore indistinguishable to the caller; discovery is best-effort.
+*
+* `Effect.catch` catches failures, **not defects**. A predicate that throws is
+* programmer error and surfaces as a defect. Do not change this to
+* `Effect.catchCause` — the distinction is load-bearing.
+*
+* @public
+*/
+const firstMatch = (candidates, predicate) => Effect.gen(function* () {
+	for (const candidate of candidates) if (yield* Effect.catch(predicate(candidate), () => Effect.succeed(false))) return Option.some(candidate);
+	return Option.none();
+});
+/**
+* The first existing path among the candidates `candidatesFor` produces for each
+* directory in `dirs`, scanned in order. Nearer directories win.
+*
+* @remarks
+* Candidates materialize up front, bounded by `dirs.length × candidatesFor`'s
+* output — a few hundred strings under the default `maxDepth`.
+*
+* @public
+*/
+const findUpward = (dirs, candidatesFor) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const candidates = [];
+	for (const dir of dirs) candidates.push(...candidatesFor(dir));
+	return yield* firstMatch(candidates, (candidate) => fs.exists(candidate));
+});
+/**
+* The first directory in `dirs` that `isRoot` accepts.
+*
+* @remarks
+* `firstMatch` over the directories themselves — the candidate expansion is the
+* identity. `isRoot` is a caller-supplied marker test (a `.git` entry, a
+* `pnpm-workspace.yaml`), and its failures are absorbed per directory.
+*
+* @public
+*/
+const findRoot = (dirs, isRoot) => firstMatch(dirs, isRoot);
+/**
+* Upward path traversal primitives.
+*
+* @public
+*/
+const Walker = {
+	ascend,
+	firstMatch,
+	findUpward,
+	findRoot
+};
+
+//#endregion
+export { Walker };

package/index.d.ts

@@ -0,0 +1,27 @@
+import { Effect, FileSystem, Option, Path } from "effect";
+//#region src/Walker.d.ts
+/**
+ * Options for {@link Walker.ascend}.
+ *
+ * @public
+ */
+interface AscendOptions {
+  /** Stop after this directory, inclusive. */
+  readonly stopAt?: string;
+  /** Hard cap on chain length. Defaults to 256. */
+  readonly maxDepth?: number;
+}
+/**
+ * Upward path traversal primitives.
+ *
+ * @public
+ */
+declare const Walker: {
+  readonly ascend: (start: string, options?: AscendOptions) => Effect.Effect<ReadonlyArray<string>, never, Path.Path>;
+  readonly firstMatch: <E, R>(candidates: ReadonlyArray<string>, predicate: (candidate: string) => Effect.Effect<boolean, E, R>) => Effect.Effect<Option.Option<string>, never, R>;
+  readonly findUpward: (dirs: ReadonlyArray<string>, candidatesFor: (dir: string) => ReadonlyArray<string>) => Effect.Effect<Option.Option<string>, never, FileSystem.FileSystem>;
+  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, Walker };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,3 @@
+import { Walker } from "./Walker.js";
+
+export { Walker };

package/package.json

@@ -0,0 +1,44 @@
+{
+	"name": "@effected/walker",
+	"version": "0.1.0",
+	"private": false,
+	"description": "Upward path traversal as Effect primitives: ascend a directory chain and return the first candidate satisfying a predicate.",
+	"keywords": [
+		"path",
+		"traversal",
+		"walk",
+		"find-up",
+		"effect",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/walker#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/walker"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"effect": "4.0.0-beta.98"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.9"
+    }
+  ]
+}