runtime-resolver 0.3.12 → 0.3.14

package/layers/NodeReleaseCacheLive.js

@@ -0,0 +1,77 @@
+import { createRuntimeCache } from "./RuntimeCacheLive.js";
+import { NodeReleaseCache } from "../services/NodeReleaseCache.js";
+import { NodeRelease } from "../schemas/node-release.js";
+import { NodeSchedule } from "../schemas/node-schedule.js";
+import { Effect, Layer, Ref } from "effect";
+
+//#region src/layers/NodeReleaseCacheLive.ts
+/**
+* Low-level layer that constructs the {@link NodeReleaseCache} service backed by
+* a `SemVerVersionCache` instance from `semver-effect`.
+*
+* This layer is more complex than the Bun and Deno equivalents because it manages
+* additional LTS schedule state via an internal `Ref`. The schedule is stored
+* separately from the version list so that calling `updateSchedule` can
+* transparently rebuild all release objects with the latest phase information
+* without reloading data from the network.
+*
+* This layer wires up the cache storage but does not populate it with any
+* release data. Callers are responsible for calling `updateSchedule` and
+* `loadFromInputs` after construction. In normal usage you should prefer the
+* higher-level cache strategy layers instead of using this layer directly:
+* - {@link AutoNodeCacheLive} — API with fallback to bundled defaults
+* - {@link FreshNodeCacheLive} — API only, fails if unavailable
+* - {@link OfflineNodeCacheLive} — bundled defaults only
+*
+* @see {@link NodeReleaseCache}
+* @see {@link createRuntimeCache}
+* @internal
+*/
+const NodeReleaseCacheLive = Layer.effect(NodeReleaseCache, Effect.gen(function* () {
+	const scheduleRef = yield* Ref.make(NodeSchedule.fromData({}));
+	const inner = yield* createRuntimeCache();
+	let currentInputs = [];
+	const buildAndLoad = (inputs) => Effect.gen(function* () {
+		const releases = [];
+		for (const input of inputs) {
+			const release = yield* NodeRelease.fromInput(input, scheduleRef).pipe(Effect.catchAll(() => Effect.succeed(null)));
+			if (release) releases.push(release);
+		}
+		yield* inner.load(releases);
+	});
+	return {
+		load: (releases) => inner.load(releases),
+		resolve: (range) => inner.resolve(range),
+		releases: () => inner.releases(),
+		filter: (range) => inner.filter(range),
+		latest: () => inner.latest(),
+		latestByMajor: () => inner.latestByMajor(),
+		latestByMinor: () => inner.latestByMinor(),
+		updateSchedule: (data) => Effect.gen(function* () {
+			yield* Ref.set(scheduleRef, NodeSchedule.fromData(data));
+			if (currentInputs.length > 0) yield* buildAndLoad(currentInputs);
+		}),
+		loadFromInputs: (inputs) => Effect.gen(function* () {
+			currentInputs = inputs;
+			yield* buildAndLoad(inputs);
+		}),
+		ltsReleases: (now) => Effect.gen(function* () {
+			const all = yield* inner.releases();
+			const results = [];
+			for (const r of all) {
+				const phase = yield* r.phase(now);
+				if (phase === "active-lts" || phase === "maintenance-lts") results.push(r);
+			}
+			return results;
+		}),
+		currentReleases: (now) => Effect.gen(function* () {
+			const all = yield* inner.releases();
+			const results = [];
+			for (const r of all) if ((yield* r.phase(now)) === "current") results.push(r);
+			return results;
+		})
+	};
+}));
+
+//#endregion
+export { NodeReleaseCacheLive };

package/layers/NodeResolverLive.js

@@ -0,0 +1,107 @@
+import { NodeReleaseCache } from "../services/NodeReleaseCache.js";
+import { VersionNotFoundError } from "../errors/VersionNotFoundError.js";
+import { NodeResolver } from "../services/NodeResolver.js";
+import { DateTime, Effect, Layer } from "effect";
+import { SemVer } from "semver-effect";
+
+//#region src/layers/NodeResolverLive.ts
+/**
+* Provides the {@link NodeResolver} service backed by a {@link NodeReleaseCache}.
+*
+* This layer composes with any of the three Node cache strategy layers to form
+* a complete resolver stack. In addition to semver range filtering and increment
+* grouping, it supports filtering by Node.js release phase (e.g., `"current"`,
+* `"active-lts"`, `"maintenance-lts"`, `"end-of-life"`) and automatically
+* determines the current LTS version from the loaded schedule data.
+*
+* @example
+* ```ts
+* import {
+*   NodeResolverLive, AutoNodeCacheLive,
+*   NodeVersionFetcherLive, NodeScheduleFetcherLive,
+*   GitHubClientLive, GitHubAutoAuth,
+* } from "runtime-resolver";
+* import { NodeResolver } from "runtime-resolver";
+* import { Effect, Layer } from "effect";
+*
+* const GitHubLayer = GitHubClientLive.pipe(Layer.provide(GitHubAutoAuth));
+* const FetchersLayer = Layer.merge(
+*   NodeVersionFetcherLive.pipe(Layer.provide(GitHubLayer)),
+*   NodeScheduleFetcherLive.pipe(Layer.provide(GitHubLayer)),
+* );
+* const CacheLayer = AutoNodeCacheLive.pipe(Layer.provide(FetchersLayer));
+* const ResolverLayer = NodeResolverLive.pipe(Layer.provide(CacheLayer));
+*
+* const program = Effect.gen(function* () {
+*   const resolver = yield* NodeResolver;
+*   // Resolve only active-LTS and maintenance-LTS releases in the ^20 range
+*   const result = yield* resolver.resolve({
+*     semverRange: "^20.0.0",
+*     phases: ["active-lts", "maintenance-lts"],
+*   });
+*   console.log(result.lts);
+* });
+*
+* Effect.runPromise(program.pipe(Effect.provide(ResolverLayer)));
+* ```
+*
+* @see {@link NodeResolver}
+* @see {@link NodeReleaseCache}
+* @see {@link AutoNodeCacheLive}
+* @see {@link FreshNodeCacheLive}
+* @see {@link OfflineNodeCacheLive}
+* @public
+*/
+const NodeResolverLive = Layer.effect(NodeResolver, Effect.gen(function* () {
+	const cache = yield* NodeReleaseCache;
+	return { resolve: (options) => Effect.gen(function* () {
+		const semverRange = options?.semverRange ?? "*";
+		const phases = options?.phases ?? ["current", "active-lts"];
+		const increments = options?.increments ?? "latest";
+		const now = options?.date ? DateTime.unsafeMake(options.date) : DateTime.unsafeMake(/* @__PURE__ */ new Date());
+		const matching = yield* cache.filter(semverRange).pipe(Effect.catchAll(() => Effect.succeed([])));
+		const phaseFiltered = [];
+		for (const r of matching) {
+			const phase = yield* r.phase(now);
+			if (phase && phases.includes(phase)) phaseFiltered.push(r);
+		}
+		let resultReleases;
+		if (increments === "latest") {
+			const groups = /* @__PURE__ */ new Map();
+			for (const r of phaseFiltered) {
+				const existing = groups.get(r.version.major);
+				if (!existing || SemVer.gt(r.version, existing.version)) groups.set(r.version.major, r);
+			}
+			resultReleases = [...groups.values()];
+		} else if (increments === "minor") {
+			const groups = /* @__PURE__ */ new Map();
+			for (const r of phaseFiltered) {
+				const key = `${r.version.major}.${r.version.minor}`;
+				const existing = groups.get(key);
+				if (!existing || SemVer.gt(r.version, existing.version)) groups.set(key, r);
+			}
+			resultReleases = [...groups.values()];
+		} else resultReleases = phaseFiltered;
+		if (resultReleases.length === 0) return yield* Effect.fail(new VersionNotFoundError({
+			runtime: "node",
+			constraint: semverRange,
+			message: `No Node.js versions found matching "${semverRange}" with phases [${phases.join(", ")}]`
+		}));
+		const versions = SemVer.rsort(resultReleases.map((r) => r.version)).map((v) => resultReleases.find((r) => SemVer.equal(r.version, v))).filter((r) => r !== void 0).map((r) => r.version.toString());
+		const latest = versions[0];
+		const ltsVersions = (yield* cache.ltsReleases(now)).filter((r) => versions.includes(r.version.toString())).map((r) => r.version);
+		const lts = ltsVersions.length > 0 ? SemVer.rsort(ltsVersions)[0].toString() : void 0;
+		let resolvedDefault;
+		if (options?.defaultVersion) resolvedDefault = yield* cache.resolve(options.defaultVersion).pipe(Effect.map((r) => r.version.toString()), Effect.catchAll(() => Effect.succeed(void 0)));
+		return {
+			source: "api",
+			versions,
+			latest,
+			...lts ? { lts } : {},
+			...resolvedDefault ? { default: resolvedDefault } : { ...lts ? { default: lts } : {} }
+		};
+	}) };
+}));
+
+//#endregion
+export { NodeResolverLive };

package/layers/NodeScheduleFetcherLive.js

@@ -0,0 +1,37 @@
+import { NodeScheduleFetcher } from "../services/NodeScheduleFetcher.js";
+import { GitHubClient } from "../services/GitHubClient.js";
+import { ParseError } from "../errors/ParseError.js";
+import { NodeReleaseSchedule } from "../schemas/node.js";
+import { Effect, Layer, Schema } from "effect";
+
+//#region src/layers/NodeScheduleFetcherLive.ts
+const NODE_SCHEDULE_URL = "https://raw.githubusercontent.com/nodejs/Release/refs/heads/main/schedule.json";
+const decodeSchedule = (input) => Schema.decodeUnknown(NodeReleaseSchedule)(input).pipe(Effect.mapError((e) => new ParseError({
+	source: NODE_SCHEDULE_URL,
+	message: `Schema validation failed: ${e.message}`
+})), Effect.map((data) => data));
+/**
+* Provides the {@link NodeScheduleFetcher} service using the live Node.js release schedule.
+*
+* Fetches the Node.js release schedule from the raw GitHub content URL for
+* `nodejs/Release` (`schedule.json` on the `main` branch) using the HTTP client
+* on the provided {@link GitHubClient} service. The schedule data maps major
+* version codenames to their start, LTS, and end-of-life dates and is used by
+* {@link NodeReleaseCache} to compute per-release lifecycle phases.
+*
+* This layer is a required dependency of {@link AutoNodeCacheLive} and
+* {@link FreshNodeCacheLive}. It is not needed by {@link OfflineNodeCacheLive}.
+*
+* @see {@link NodeScheduleFetcher}
+* @see {@link GitHubClient}
+* @see {@link AutoNodeCacheLive}
+* @see {@link FreshNodeCacheLive}
+* @public
+*/
+const NodeScheduleFetcherLive = Layer.effect(NodeScheduleFetcher, Effect.gen(function* () {
+	const client = yield* GitHubClient;
+	return { fetch: () => client.getJson(NODE_SCHEDULE_URL, { decode: decodeSchedule }) };
+}));
+
+//#endregion
+export { NodeScheduleFetcherLive };

package/layers/NodeVersionFetcherLive.js

@@ -0,0 +1,55 @@
+import { NodeVersionFetcher } from "../services/NodeVersionFetcher.js";
+import { tryParseSemVer } from "../lib/semver.js";
+import { GitHubClient } from "../services/GitHubClient.js";
+import { ParseError } from "../errors/ParseError.js";
+import { NodeDistIndex } from "../schemas/node.js";
+import { Effect, Layer, Option, Schema } from "effect";
+
+//#region src/layers/NodeVersionFetcherLive.ts
+const NODE_DIST_URL = "https://nodejs.org/dist/index.json";
+const decodeDistIndex = (input) => Schema.decodeUnknown(NodeDistIndex)(input).pipe(Effect.mapError((e) => new ParseError({
+	source: NODE_DIST_URL,
+	message: `Schema validation failed: ${e.message}`
+})));
+/**
+* Provides the {@link NodeVersionFetcher} service using the live Node.js dist index.
+*
+* Fetches the full Node.js version list from `https://nodejs.org/dist/index.json`
+* using the HTTP client on the provided {@link GitHubClient} service. Version
+* strings are normalized by stripping the leading `v` before parsing as semver.
+* Entries with non-string `npm` fields (present in very old releases prior to
+* v0.6.3) are substituted with the sentinel version `"0.0.0"`.
+*
+* This layer is a required dependency of {@link AutoNodeCacheLive} and
+* {@link FreshNodeCacheLive}. It is not needed by {@link OfflineNodeCacheLive}.
+*
+* @see {@link NodeVersionFetcher}
+* @see {@link GitHubClient}
+* @see {@link AutoNodeCacheLive}
+* @see {@link FreshNodeCacheLive}
+* @public
+*/
+const NodeVersionFetcherLive = Layer.effect(NodeVersionFetcher, Effect.gen(function* () {
+	const client = yield* GitHubClient;
+	return { fetch: () => Effect.gen(function* () {
+		const allVersions = yield* client.getJson(NODE_DIST_URL, { decode: decodeDistIndex });
+		const parsed = yield* Effect.forEach(allVersions, (entry) => {
+			const clean = entry.version.replace(/^v/, "");
+			return tryParseSemVer(clean).pipe(Effect.map((opt) => Option.isSome(opt) ? Option.some({
+				version: opt.value,
+				input: {
+					version: clean,
+					npm: typeof entry.npm === "string" ? entry.npm : "0.0.0",
+					date: entry.date
+				}
+			}) : Option.none()));
+		}, { concurrency: "unbounded" });
+		return {
+			versions: parsed.flatMap(Option.toArray).map(({ version }) => version),
+			inputs: parsed.flatMap(Option.toArray).map(({ input }) => input)
+		};
+	}) };
+}));
+
+//#endregion
+export { NodeVersionFetcherLive };

package/layers/OfflineBunCacheLive.js

@@ -0,0 +1,40 @@
+import { bunDefaultInputs } from "../data/bun-defaults.js";
+import { BunRelease } from "../schemas/bun-release.js";
+import { BunReleaseCache } from "../services/BunReleaseCache.js";
+import { BunReleaseCacheLive } from "./BunReleaseCacheLive.js";
+import { Effect, Layer } from "effect";
+import { SemVerParserLive, VersionCacheLive } from "semver-effect";
+
+//#region src/layers/OfflineBunCacheLive.ts
+const offlineSetup = Effect.gen(function* () {
+	const cache = yield* BunReleaseCache;
+	const releases = yield* Effect.all(bunDefaultInputs.map((input) => BunRelease.fromInput(input)), { concurrency: "unbounded" }).pipe(Effect.orElseSucceed(() => []));
+	yield* cache.load(releases);
+});
+const SemVerLayer = VersionCacheLive.pipe(Layer.provide(SemVerParserLive));
+const BaseCacheLayer = BunReleaseCacheLive.pipe(Layer.provide(SemVerLayer));
+/**
+* Provides the {@link BunReleaseCache} service using the "Offline" cache strategy.
+*
+* Uses only the bundled default Bun release data that was baked in at build time.
+* Makes no network requests and has no runtime dependencies. This layer always
+* succeeds immediately.
+*
+* Use this strategy in environments where network access is unavailable or
+* undesirable (e.g., air-gapped systems, hermetic test environments, or any
+* context where version data from the bundle is sufficient).
+*
+* The three Bun cache strategy layers are:
+* - {@link AutoBunCacheLive} — tries API first, falls back to bundled defaults on any error
+* - {@link FreshBunCacheLive} — requires live API data, fails with `FreshnessError` if unavailable
+* - `OfflineBunCacheLive` — uses only bundled defaults, no network I/O
+*
+* @see {@link BunReleaseCache}
+* @see {@link AutoBunCacheLive}
+* @see {@link FreshBunCacheLive}
+* @public
+*/
+const OfflineBunCacheLive = BaseCacheLayer.pipe(Layer.tap((ctx) => offlineSetup.pipe(Effect.provide(ctx))));
+
+//#endregion
+export { OfflineBunCacheLive };

package/layers/OfflineDenoCacheLive.js

@@ -0,0 +1,40 @@
+import { denoDefaultInputs } from "../data/deno-defaults.js";
+import { DenoRelease } from "../schemas/deno-release.js";
+import { DenoReleaseCache } from "../services/DenoReleaseCache.js";
+import { DenoReleaseCacheLive } from "./DenoReleaseCacheLive.js";
+import { Effect, Layer } from "effect";
+import { SemVerParserLive, VersionCacheLive } from "semver-effect";
+
+//#region src/layers/OfflineDenoCacheLive.ts
+const offlineSetup = Effect.gen(function* () {
+	const cache = yield* DenoReleaseCache;
+	const releases = yield* Effect.all(denoDefaultInputs.map((input) => DenoRelease.fromInput(input)), { concurrency: "unbounded" }).pipe(Effect.orElseSucceed(() => []));
+	yield* cache.load(releases);
+});
+const SemVerLayer = VersionCacheLive.pipe(Layer.provide(SemVerParserLive));
+const BaseCacheLayer = DenoReleaseCacheLive.pipe(Layer.provide(SemVerLayer));
+/**
+* Provides the {@link DenoReleaseCache} service using the "Offline" cache strategy.
+*
+* Uses only the bundled default Deno release data that was baked in at build time.
+* Makes no network requests and has no runtime dependencies. This layer always
+* succeeds immediately.
+*
+* Use this strategy in environments where network access is unavailable or
+* undesirable (e.g., air-gapped systems, hermetic test environments, or any
+* context where version data from the bundle is sufficient).
+*
+* The three Deno cache strategy layers are:
+* - {@link AutoDenoCacheLive} — tries API first, falls back to bundled defaults on any error
+* - {@link FreshDenoCacheLive} — requires live API data, fails with `FreshnessError` if unavailable
+* - `OfflineDenoCacheLive` — uses only bundled defaults, no network I/O
+*
+* @see {@link DenoReleaseCache}
+* @see {@link AutoDenoCacheLive}
+* @see {@link FreshDenoCacheLive}
+* @public
+*/
+const OfflineDenoCacheLive = BaseCacheLayer.pipe(Layer.tap((ctx) => offlineSetup.pipe(Effect.provide(ctx))));
+
+//#endregion
+export { OfflineDenoCacheLive };

package/layers/OfflineNodeCacheLive.js

@@ -0,0 +1,39 @@
+import { nodeDefaultInputs, nodeDefaultScheduleData } from "../data/node-defaults.js";
+import { NodeReleaseCache } from "../services/NodeReleaseCache.js";
+import { NodeReleaseCacheLive } from "./NodeReleaseCacheLive.js";
+import { Effect, Layer } from "effect";
+import { SemVerParserLive, VersionCacheLive } from "semver-effect";
+
+//#region src/layers/OfflineNodeCacheLive.ts
+const offlineSetup = Effect.gen(function* () {
+	const cache = yield* NodeReleaseCache;
+	yield* cache.updateSchedule(nodeDefaultScheduleData);
+	yield* cache.loadFromInputs(nodeDefaultInputs);
+});
+const SemVerLayer = VersionCacheLive.pipe(Layer.provide(SemVerParserLive));
+const BaseCacheLayer = NodeReleaseCacheLive.pipe(Layer.provide(SemVerLayer));
+/**
+* Provides the {@link NodeReleaseCache} service using the "Offline" cache strategy.
+*
+* Uses only the bundled default Node.js release data and schedule data that were
+* baked in at build time. Makes no network requests and has no runtime
+* dependencies. This layer always succeeds immediately.
+*
+* Use this strategy in environments where network access is unavailable or
+* undesirable (e.g., air-gapped systems, hermetic test environments, or any
+* context where version data from the bundle is sufficient).
+*
+* The three Node cache strategy layers are:
+* - {@link AutoNodeCacheLive} — tries API first, falls back to bundled defaults on any error
+* - {@link FreshNodeCacheLive} — requires live API data, fails with `FreshnessError` if unavailable
+* - `OfflineNodeCacheLive` — uses only bundled defaults, no network I/O
+*
+* @see {@link NodeReleaseCache}
+* @see {@link AutoNodeCacheLive}
+* @see {@link FreshNodeCacheLive}
+* @public
+*/
+const OfflineNodeCacheLive = BaseCacheLayer.pipe(Layer.tap((ctx) => offlineSetup.pipe(Effect.provide(ctx))));
+
+//#endregion
+export { OfflineNodeCacheLive };

package/layers/RuntimeCacheLive.js

@@ -0,0 +1,78 @@
+import { Effect } from "effect";
+import { Range, VersionCache } from "semver-effect";
+
+//#region src/layers/RuntimeCacheLive.ts
+/**
+* Factory that creates a {@link RuntimeCache} implementation backed by
+* `semver-effect`'s `VersionCache`.
+*
+* The returned `Effect` must be executed within an Effect context that provides
+* a `SemVerVersionCache` service (i.e., it requires `SemVerVersionCache` in its
+* environment). The cache maintains an internal lookup map from version string
+* to the full release object so that resolved semver versions can be
+* round-tripped back to their typed release records.
+*
+* This factory is used internally by {@link BunReleaseCacheLive},
+* {@link DenoReleaseCacheLive}, and {@link NodeReleaseCacheLive} to build their
+* respective cache service implementations. Prefer those higher-level layers
+* over calling this factory directly.
+*
+* Note: `load` is not concurrency-safe. Callers must not invoke it concurrently.
+* In practice this constraint is upheld because `load` is only called from layer
+* setup and `NodeReleaseCacheLive.loadFromInputs`, both of which are serialized
+* by the Effect runtime.
+*
+* @typeParam R - The runtime release type stored in the cache. Must extend
+*   {@link RuntimeRelease}.
+*
+* @see {@link RuntimeCache}
+* @see {@link BunReleaseCacheLive}
+* @see {@link DenoReleaseCacheLive}
+* @see {@link NodeReleaseCacheLive}
+* @public
+*/
+const createRuntimeCache = () => Effect.gen(function* () {
+	const innerCache = yield* VersionCache;
+	const lookupMap = /* @__PURE__ */ new Map();
+	return {
+		load: (releases) => Effect.gen(function* () {
+			lookupMap.clear();
+			const versions = [];
+			for (const r of releases) {
+				const key = r.version.toString();
+				lookupMap.set(key, r);
+				versions.push(r.version);
+			}
+			yield* innerCache.load(versions);
+		}),
+		resolve: (range) => Effect.gen(function* () {
+			const parsed = yield* Range.parse(range);
+			const resolved = yield* innerCache.resolve(parsed);
+			const release = lookupMap.get(resolved.toString());
+			if (!release) return yield* Effect.die(/* @__PURE__ */ new Error(`Cache inconsistency: ${resolved.toString()} not in lookup map`));
+			return release;
+		}),
+		releases: () => Effect.gen(function* () {
+			return (yield* innerCache.versions.pipe(Effect.catchTag("EmptyCacheError", () => Effect.succeed([])))).map((v) => lookupMap.get(v.toString())).filter((r) => r !== void 0);
+		}),
+		filter: (range) => Effect.gen(function* () {
+			const parsed = yield* Range.parse(range);
+			return (yield* innerCache.filter(parsed).pipe(Effect.catchTag("EmptyCacheError", () => Effect.succeed([])))).map((v) => lookupMap.get(v.toString())).filter((r) => r !== void 0);
+		}),
+		latest: () => Effect.gen(function* () {
+			const version = yield* innerCache.latest();
+			const release = lookupMap.get(version.toString());
+			if (!release) return yield* Effect.die(/* @__PURE__ */ new Error(`Cache inconsistency: ${version.toString()} not in lookup map`));
+			return release;
+		}),
+		latestByMajor: () => Effect.gen(function* () {
+			return (yield* innerCache.latestByMajor().pipe(Effect.catchTag("EmptyCacheError", () => Effect.succeed([])))).map((v) => lookupMap.get(v.toString())).filter((r) => r !== void 0);
+		}),
+		latestByMinor: () => Effect.gen(function* () {
+			return (yield* innerCache.latestByMinor().pipe(Effect.catchTag("EmptyCacheError", () => Effect.succeed([])))).map((v) => lookupMap.get(v.toString())).filter((r) => r !== void 0);
+		})
+	};
+});
+
+//#endregion
+export { createRuntimeCache };

package/lib/retry.js

@@ -0,0 +1,27 @@
+import { Effect, Predicate, Schedule } from "effect";
+
+//#region src/lib/retry.ts
+/**
+* Wraps an effect with automatic retry logic for {@link RateLimitError}.
+*
+* When the wrapped effect fails with a `RateLimitError` the retry schedule
+* applies exponential backoff starting at a 1-second base delay, doubling on
+* each attempt, for a maximum of 3 retries. Errors with any other tag are
+* re-raised immediately without retrying.
+*
+* The predicate used for the `while` condition is
+* `Predicate.isTagged("RateLimitError")`, so only errors whose `_tag` field
+* equals `"RateLimitError"` trigger a retry; all other error types propagate
+* unchanged.
+*
+* @see {@link RateLimitError}
+*
+* @internal
+*/
+const retryOnRateLimit = (effect) => effect.pipe(Effect.retry({
+	schedule: Schedule.exponential("1 second").pipe(Schedule.compose(Schedule.recurs(3))),
+	while: Predicate.isTagged("RateLimitError")
+}));
+
+//#endregion
+export { retryOnRateLimit };

package/lib/semver.js

@@ -0,0 +1,21 @@
+import { Effect, Option } from "effect";
+import { SemVer } from "semver-effect";
+
+//#region src/lib/semver.ts
+/**
+* Attempts to parse a raw version string into a {@link SemVer}, returning
+* `Option.none()` when the string is not a valid semver value.
+*
+* Unlike `SemVer.parse` — which fails the effect on an unparseable input —
+* this helper absorbs parse failures and promotes them into the `Option` channel
+* so that callers can handle invalid versions without short-circuiting the
+* surrounding effect pipeline.
+*
+* @see {@link SemVer.parse}
+*
+* @internal
+*/
+const tryParseSemVer = (raw) => SemVer.parse(raw).pipe(Effect.map(Option.some), Effect.catchAll(() => Effect.succeed(Option.none())));
+
+//#endregion
+export { tryParseSemVer };

package/package.json

@@ -1,70 +1,59 @@
 {
-  "name": "runtime-resolver",
-  "version": "0.3.12",
-  "private": false,
-  "description": "Resolve semver-compatible versions of Node.js, Bun, and Deno runtimes with Effect-based architecture and offline fallback.",
-  "keywords": [
-    "node",
-    "bun",
-    "deno",
-    "runtime",
-    "version",
-    "semver",
-    "resolver",
-    "ci",
-    "github-actions",
-    "effect",
-    "cli"
-  ],
-  "homepage": "https://github.com/spencerbeggs/runtime-resolver#readme",
-  "bugs": {
-    "url": "https://github.com/spencerbeggs/runtime-resolver/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/spencerbeggs/runtime-resolver.git"
-  },
-  "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"
-    }
-  },
-  "bin": {
-    "runtime-resolver": "bin/runtime-resolver.js"
-  },
-  "dependencies": {
-    "@octokit/auth-app": "^8.2.0",
-    "octokit": "^5.0.5",
-    "semver-effect": "^0.2.1"
-  },
-  "peerDependencies": {
-    "@effect/cli": ">=0.75.1",
-    "@effect/platform": ">=0.96.0",
-    "@effect/platform-node": ">=0.106.0",
-    "effect": ">=3.21.0"
-  },
-  "files": [
-    "!runtime-resolver.api.json",
-    "!tsconfig.json",
-    "!tsdoc.json",
-    "612.js",
-    "711.js",
-    "LICENSE",
-    "README.md",
-    "bin/runtime-resolver.js",
-    "index.d.ts",
-    "index.js",
-    "json-schema.js",
-    "package.json",
-    "tsdoc-metadata.json"
-  ]
+	"name": "runtime-resolver",
+	"version": "0.3.14",
+	"private": false,
+	"description": "Resolve semver-compatible versions of Node.js, Bun, and Deno runtimes with Effect-based architecture and offline fallback.",
+	"keywords": [
+		"node",
+		"bun",
+		"deno",
+		"runtime",
+		"version",
+		"semver",
+		"resolver",
+		"ci",
+		"github-actions",
+		"effect",
+		"cli"
+	],
+	"homepage": "https://github.com/spencerbeggs/runtime-resolver#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/runtime-resolver/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/runtime-resolver.git"
+	},
+	"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"
+	},
+	"bin": {
+		"runtime-resolver": "bin/runtime-resolver.js"
+	},
+	"dependencies": {
+		"@octokit/auth-app": "^8.2.0",
+		"octokit": "^5.0.5",
+		"semver-effect": "^0.2.1"
+	},
+	"peerDependencies": {
+		"@effect/cli": ">=0.75.2",
+		"@effect/platform": ">=0.96.0",
+		"@effect/platform-node": ">=0.107.0",
+		"effect": ">=3.21.0"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
 }