runtime-resolver 0.3.12 → 0.3.14

package/index.js

@@ -1,121 +1,63 @@
-import { Data, Effect, Layer } from "effect";
-import { SemVerParserLive, VersionCacheLive } from "semver-effect";
-import { DenoReleaseCacheLive, BunRelease, AutoDenoCacheLive, NodeReleaseCacheLive, NodeReleaseCache, AutoNodeCacheLive, denoDefaultInputs, BunReleaseCache, nodeDefaultInputs, NodeResolverLive, BunVersionFetcherLive, DenoResolverLive, GitHubClientLive, BunVersionFetcher, NodeScheduleFetcher, DenoResolver, NodeScheduleFetcherLive, DenoVersionFetcherLive, NodeVersionFetcher, DenoReleaseCache, BunReleaseCacheLive, BunResolver, DenoRelease, bunDefaultInputs, NodeVersionFetcherLive, GitHubAutoAuth, BunResolverLive, NodeResolver, AutoBunCacheLive, DenoVersionFetcher, nodeDefaultScheduleData } from "./711.js";
-class CacheError extends Data.TaggedError("CacheError") {
-}
-class FreshnessError extends Data.TaggedError("FreshnessError") {
-}
-class InvalidInputError extends Data.TaggedError("InvalidInputError") {
-}
-const freshSetup = Effect.gen(function*() {
-    const cache = yield* BunReleaseCache;
-    const fetcher = yield* BunVersionFetcher;
-    const { inputs } = yield* fetcher.fetch().pipe(Effect.catchTags({
-        AuthenticationError: (err)=>Effect.fail(new FreshnessError({
-                strategy: "api",
-                message: `Fresh data required but authentication failed: ${err.message}`
-            })),
-        NetworkError: (err)=>Effect.fail(new FreshnessError({
-                strategy: "api",
-                message: `Fresh data required but network unavailable: ${err.message}`
-            })),
-        ParseError: (err)=>Effect.fail(new FreshnessError({
-                strategy: "api",
-                message: `Fresh data required but parse failed: ${err.message}`
-            })),
-        RateLimitError: (err)=>Effect.fail(new FreshnessError({
-                strategy: "api",
-                message: `Fresh data required but rate limit exceeded: ${err.message}`
-            }))
-    }));
-    const releases = yield* Effect.all(inputs.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));
-const FreshBunCacheLive = BaseCacheLayer.pipe(Layer.tap((ctx)=>freshSetup.pipe(Effect.provide(ctx))));
-const FreshDenoCacheLive_freshSetup = Effect.gen(function*() {
-    const cache = yield* DenoReleaseCache;
-    const fetcher = yield* DenoVersionFetcher;
-    const { inputs } = yield* fetcher.fetch().pipe(Effect.catchTags({
-        AuthenticationError: (err)=>Effect.fail(new FreshnessError({
-                strategy: "api",
-                message: `Fresh data required but authentication failed: ${err.message}`
-            })),
-        NetworkError: (err)=>Effect.fail(new FreshnessError({
-                strategy: "api",
-                message: `Fresh data required but network unavailable: ${err.message}`
-            })),
-        ParseError: (err)=>Effect.fail(new FreshnessError({
-                strategy: "api",
-                message: `Fresh data required but parse failed: ${err.message}`
-            })),
-        RateLimitError: (err)=>Effect.fail(new FreshnessError({
-                strategy: "api",
-                message: `Fresh data required but rate limit exceeded: ${err.message}`
-            }))
-    }));
-    const releases = yield* Effect.all(inputs.map((input)=>DenoRelease.fromInput(input)), {
-        concurrency: "unbounded"
-    }).pipe(Effect.orElseSucceed(()=>[]));
-    yield* cache.load(releases);
-});
-const FreshDenoCacheLive_SemVerLayer = VersionCacheLive.pipe(Layer.provide(SemVerParserLive));
-const FreshDenoCacheLive_BaseCacheLayer = DenoReleaseCacheLive.pipe(Layer.provide(FreshDenoCacheLive_SemVerLayer));
-const FreshDenoCacheLive = FreshDenoCacheLive_BaseCacheLayer.pipe(Layer.tap((ctx)=>FreshDenoCacheLive_freshSetup.pipe(Effect.provide(ctx))));
-const FreshNodeCacheLive_freshSetup = Effect.gen(function*() {
-    const cache = yield* NodeReleaseCache;
-    const versionFetcher = yield* NodeVersionFetcher;
-    const scheduleFetcher = yield* NodeScheduleFetcher;
-    const [fetchResult, scheduleData] = yield* Effect.all([
-        versionFetcher.fetch(),
-        scheduleFetcher.fetch()
-    ]).pipe(Effect.catchTags({
-        NetworkError: (err)=>Effect.fail(new FreshnessError({
-                strategy: "api",
-                message: `Fresh data required but network unavailable: ${err.message}`
-            })),
-        ParseError: (err)=>Effect.fail(new FreshnessError({
-                strategy: "api",
-                message: `Fresh data required but response could not be parsed: ${err.message}`
-            }))
-    }));
-    yield* cache.updateSchedule(scheduleData);
-    yield* cache.loadFromInputs(fetchResult.inputs);
-});
-const FreshNodeCacheLive_SemVerLayer = VersionCacheLive.pipe(Layer.provide(SemVerParserLive));
-const FreshNodeCacheLive_BaseCacheLayer = NodeReleaseCacheLive.pipe(Layer.provide(FreshNodeCacheLive_SemVerLayer));
-const FreshNodeCacheLive = FreshNodeCacheLive_BaseCacheLayer.pipe(Layer.tap((ctx)=>FreshNodeCacheLive_freshSetup.pipe(Effect.provide(ctx))));
-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 OfflineBunCacheLive_SemVerLayer = VersionCacheLive.pipe(Layer.provide(SemVerParserLive));
-const OfflineBunCacheLive_BaseCacheLayer = BunReleaseCacheLive.pipe(Layer.provide(OfflineBunCacheLive_SemVerLayer));
-const OfflineBunCacheLive = OfflineBunCacheLive_BaseCacheLayer.pipe(Layer.tap((ctx)=>offlineSetup.pipe(Effect.provide(ctx))));
-const OfflineDenoCacheLive_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 OfflineDenoCacheLive_SemVerLayer = VersionCacheLive.pipe(Layer.provide(SemVerParserLive));
-const OfflineDenoCacheLive_BaseCacheLayer = DenoReleaseCacheLive.pipe(Layer.provide(OfflineDenoCacheLive_SemVerLayer));
-const OfflineDenoCacheLive = OfflineDenoCacheLive_BaseCacheLayer.pipe(Layer.tap((ctx)=>OfflineDenoCacheLive_offlineSetup.pipe(Effect.provide(ctx))));
-const OfflineNodeCacheLive_offlineSetup = Effect.gen(function*() {
-    const cache = yield* NodeReleaseCache;
-    yield* cache.updateSchedule(nodeDefaultScheduleData);
-    yield* cache.loadFromInputs(nodeDefaultInputs);
-});
-const OfflineNodeCacheLive_SemVerLayer = VersionCacheLive.pipe(Layer.provide(SemVerParserLive));
-const OfflineNodeCacheLive_BaseCacheLayer = NodeReleaseCacheLive.pipe(Layer.provide(OfflineNodeCacheLive_SemVerLayer));
-const OfflineNodeCacheLive = OfflineNodeCacheLive_BaseCacheLayer.pipe(Layer.tap((ctx)=>OfflineNodeCacheLive_offlineSetup.pipe(Effect.provide(ctx))));
+import { BunRelease } from "./schemas/bun-release.js";
+import { BunReleaseCache } from "./services/BunReleaseCache.js";
+import { BunVersionFetcher } from "./services/BunVersionFetcher.js";
+import { createRuntimeCache } from "./layers/RuntimeCacheLive.js";
+import { BunReleaseCacheLive } from "./layers/BunReleaseCacheLive.js";
+import { AutoBunCacheLive } from "./layers/AutoBunCacheLive.js";
+import { DenoRelease } from "./schemas/deno-release.js";
+import { DenoReleaseCache } from "./services/DenoReleaseCache.js";
+import { DenoVersionFetcher } from "./services/DenoVersionFetcher.js";
+import { DenoReleaseCacheLive } from "./layers/DenoReleaseCacheLive.js";
+import { AutoDenoCacheLive } from "./layers/AutoDenoCacheLive.js";
+import { NodeReleaseCache } from "./services/NodeReleaseCache.js";
+import { NodeScheduleFetcher } from "./services/NodeScheduleFetcher.js";
+import { NodeVersionFetcher } from "./services/NodeVersionFetcher.js";
+import { NodeRelease } from "./schemas/node-release.js";
+import { NodeSchedule } from "./schemas/node-schedule.js";
+import { NodeReleaseCacheLive } from "./layers/NodeReleaseCacheLive.js";
+import { AutoNodeCacheLive } from "./layers/AutoNodeCacheLive.js";
+import { VersionNotFoundError } from "./errors/VersionNotFoundError.js";
+import { BunResolver } from "./services/BunResolver.js";
+import { BunResolverLive } from "./layers/BunResolverLive.js";
+import { GitHubClient } from "./services/GitHubClient.js";
+import { BunVersionFetcherLive } from "./layers/BunVersionFetcherLive.js";
+import { DenoResolver } from "./services/DenoResolver.js";
+import { DenoResolverLive } from "./layers/DenoResolverLive.js";
+import { DenoVersionFetcherLive } from "./layers/DenoVersionFetcherLive.js";
+import { OctokitInstance } from "./services/OctokitInstance.js";
+import { AuthenticationError } from "./errors/AuthenticationError.js";
+import { GitHubAppAuth } from "./layers/GitHubAppAuth.js";
+import { GitHubAutoAuth } from "./layers/GitHubAutoAuth.js";
+import { NetworkError } from "./errors/NetworkError.js";
+import { ParseError } from "./errors/ParseError.js";
+import { RateLimitError } from "./errors/RateLimitError.js";
+import { GitHubClientLive } from "./layers/GitHubClientLive.js";
+import { NodeResolver } from "./services/NodeResolver.js";
+import { NodeResolverLive } from "./layers/NodeResolverLive.js";
+import { NodeScheduleFetcherLive } from "./layers/NodeScheduleFetcherLive.js";
+import { NodeVersionFetcherLive } from "./layers/NodeVersionFetcherLive.js";
+import { CacheError } from "./errors/CacheError.js";
+import { FreshnessError } from "./errors/FreshnessError.js";
+import { InvalidInputError } from "./errors/InvalidInputError.js";
+import { FreshBunCacheLive } from "./layers/FreshBunCacheLive.js";
+import { FreshDenoCacheLive } from "./layers/FreshDenoCacheLive.js";
+import { FreshNodeCacheLive } from "./layers/FreshNodeCacheLive.js";
+import { GitHubTokenAuth, GitHubTokenAuthFromToken } from "./layers/GitHubTokenAuth.js";
+import { OfflineBunCacheLive } from "./layers/OfflineBunCacheLive.js";
+import { OfflineDenoCacheLive } from "./layers/OfflineDenoCacheLive.js";
+import { OfflineNodeCacheLive } from "./layers/OfflineNodeCacheLive.js";
+import { Effect, Layer } from "effect";
+
+//#region src/index.ts
+/**
+* runtime-resolver
+*
+* Resolve semver-compatible versions of Node.js, Bun, and Deno runtimes.
+* Promise-based API with offline fallback via build-time cache.
+* Also exports Effect services, layers, and errors for advanced composition.
+*
+* @packageDocumentation
+*/
 const GitHubLayer = GitHubClientLive.pipe(Layer.provide(GitHubAutoAuth));
 const NodeFetchersLayer = Layer.merge(NodeVersionFetcherLive.pipe(Layer.provide(GitHubLayer)), NodeScheduleFetcherLive.pipe(Layer.provide(GitHubLayer)));
 const NodeCacheLayer = AutoNodeCacheLive.pipe(Layer.provide(NodeFetchersLayer));
@@ -124,17 +66,101 @@ const BunCacheLayer = AutoBunCacheLive.pipe(Layer.provide(BunVersionFetcherLive.
 const BunLayer = BunResolverLive.pipe(Layer.provide(BunCacheLayer));
 const DenoCacheLayer = AutoDenoCacheLive.pipe(Layer.provide(DenoVersionFetcherLive.pipe(Layer.provide(GitHubLayer))));
 const DenoLayer = DenoResolverLive.pipe(Layer.provide(DenoCacheLayer));
-const resolveNode = (options)=>Effect.runPromise(Effect.gen(function*() {
-        const resolver = yield* NodeResolver;
-        return yield* resolver.resolve(options);
-    }).pipe(Effect.provide(NodeLayer)));
-const resolveBun = (options)=>Effect.runPromise(Effect.gen(function*() {
-        const resolver = yield* BunResolver;
-        return yield* resolver.resolve(options);
-    }).pipe(Effect.provide(BunLayer)));
-const resolveDeno = (options)=>Effect.runPromise(Effect.gen(function*() {
-        const resolver = yield* DenoResolver;
-        return yield* resolver.resolve(options);
-    }).pipe(Effect.provide(DenoLayer)));
-export { AuthenticationError, AutoBunCacheLive, AutoDenoCacheLive, AutoNodeCacheLive, BunRelease, BunReleaseCache, BunReleaseCacheLive, BunResolver, BunResolverLive, BunVersionFetcher, BunVersionFetcherLive, DenoRelease, DenoReleaseCache, DenoReleaseCacheLive, DenoResolver, DenoResolverLive, DenoVersionFetcher, DenoVersionFetcherLive, GitHubAppAuth, GitHubAutoAuth, GitHubClient, GitHubClientLive, GitHubTokenAuth, GitHubTokenAuthFromToken, NetworkError, NodeRelease, NodeReleaseCache, NodeReleaseCacheLive, NodeResolver, NodeResolverLive, NodeSchedule, NodeScheduleFetcher, NodeScheduleFetcherLive, NodeVersionFetcher, NodeVersionFetcherLive, OctokitInstance, ParseError, RateLimitError, VersionNotFoundError, createRuntimeCache } from "./711.js";
-export { CacheError, FreshBunCacheLive, FreshDenoCacheLive, FreshNodeCacheLive, FreshnessError, InvalidInputError, OfflineBunCacheLive, OfflineDenoCacheLive, OfflineNodeCacheLive, resolveBun, resolveDeno, resolveNode };
+/**
+* Resolve Node.js versions matching the given options.
+*
+* Fetches release data from the Node.js GitHub repository and the official
+* release schedule API, then filters and ranks versions according to
+* `options`. Authentication is read from `GITHUB_PERSONAL_ACCESS_TOKEN` or
+* `GITHUB_TOKEN` environment variables. Falls back to a build-time offline
+* cache when the network is unavailable.
+*
+* @param options - Filtering and ranking options. See {@link NodeResolverOptions}.
+* @returns A promise that resolves to a {@link ResolvedVersions} object
+*   containing the matched version list, the highest matching version as
+*   `latest`, and optional `lts` / `default` strings.
+*
+* @example
+* ```ts
+* import type { ResolvedVersions } from "runtime-resolver";
+* import { resolveNode } from "runtime-resolver";
+*
+* const result: ResolvedVersions = await resolveNode({
+* 	semverRange: ">=20.0.0",
+* 	phases: ["active-lts"],
+* });
+* console.log(result.latest); // e.g. "22.11.0"
+* console.log(result.versions); // all matching versions
+* ```
+*
+* @see {@link NodeResolver} for the Effect-based API
+* @see {@link NodeResolverOptions} for available options
+*
+* @public
+*/
+const resolveNode = (options) => Effect.runPromise(Effect.gen(function* () {
+	return yield* (yield* NodeResolver).resolve(options);
+}).pipe(Effect.provide(NodeLayer)));
+/**
+* Resolve Bun versions matching the given options.
+*
+* Fetches release data from the Bun GitHub repository, then filters and ranks
+* versions according to `options`. Authentication is read from
+* `GITHUB_PERSONAL_ACCESS_TOKEN` or `GITHUB_TOKEN` environment variables.
+* Falls back to a build-time offline cache when the network is unavailable.
+*
+* @param options - Filtering and ranking options. See {@link BunResolverOptions}.
+* @returns A promise that resolves to a {@link ResolvedVersions} object
+*   containing the matched version list and the highest matching version as
+*   `latest`.
+*
+* @example
+* ```ts
+* import type { ResolvedVersions } from "runtime-resolver";
+* import { resolveBun } from "runtime-resolver";
+*
+* const result: ResolvedVersions = await resolveBun({ semverRange: "^1.0.0" });
+* console.log(result.latest);
+* ```
+*
+* @see {@link BunResolver} for the Effect-based API
+* @see {@link BunResolverOptions} for available options
+*
+* @public
+*/
+const resolveBun = (options) => Effect.runPromise(Effect.gen(function* () {
+	return yield* (yield* BunResolver).resolve(options);
+}).pipe(Effect.provide(BunLayer)));
+/**
+* Resolve Deno versions matching the given options.
+*
+* Fetches release data from the Deno GitHub repository, then filters and ranks
+* versions according to `options`. Authentication is read from
+* `GITHUB_PERSONAL_ACCESS_TOKEN` or `GITHUB_TOKEN` environment variables.
+* Falls back to a build-time offline cache when the network is unavailable.
+*
+* @param options - Filtering and ranking options. See {@link DenoResolverOptions}.
+* @returns A promise that resolves to a {@link ResolvedVersions} object
+*   containing the matched version list and the highest matching version as
+*   `latest`.
+*
+* @example
+* ```ts
+* import type { ResolvedVersions } from "runtime-resolver";
+* import { resolveDeno } from "runtime-resolver";
+*
+* const result: ResolvedVersions = await resolveDeno({ semverRange: "^2.0.0" });
+* console.log(result.latest);
+* ```
+*
+* @see {@link DenoResolver} for the Effect-based API
+* @see {@link DenoResolverOptions} for available options
+*
+* @public
+*/
+const resolveDeno = (options) => Effect.runPromise(Effect.gen(function* () {
+	return yield* (yield* DenoResolver).resolve(options);
+}).pipe(Effect.provide(DenoLayer)));
+
+//#endregion
+export { AuthenticationError, AutoBunCacheLive, AutoDenoCacheLive, AutoNodeCacheLive, BunRelease, BunReleaseCache, BunReleaseCacheLive, BunResolver, BunResolverLive, BunVersionFetcher, BunVersionFetcherLive, CacheError, DenoRelease, DenoReleaseCache, DenoReleaseCacheLive, DenoResolver, DenoResolverLive, DenoVersionFetcher, DenoVersionFetcherLive, FreshBunCacheLive, FreshDenoCacheLive, FreshNodeCacheLive, FreshnessError, GitHubAppAuth, GitHubAutoAuth, GitHubClient, GitHubClientLive, GitHubTokenAuth, GitHubTokenAuthFromToken, InvalidInputError, NetworkError, NodeRelease, NodeReleaseCache, NodeReleaseCacheLive, NodeResolver, NodeResolverLive, NodeSchedule, NodeScheduleFetcher, NodeScheduleFetcherLive, NodeVersionFetcher, NodeVersionFetcherLive, OctokitInstance, OfflineBunCacheLive, OfflineDenoCacheLive, OfflineNodeCacheLive, ParseError, RateLimitError, VersionNotFoundError, createRuntimeCache, resolveBun, resolveDeno, resolveNode };

package/layers/AutoBunCacheLive.js

@@ -0,0 +1,47 @@
+import { bunDefaultInputs } from "../data/bun-defaults.js";
+import { BunRelease } from "../schemas/bun-release.js";
+import { BunReleaseCache } from "../services/BunReleaseCache.js";
+import { BunVersionFetcher } from "../services/BunVersionFetcher.js";
+import { BunReleaseCacheLive } from "./BunReleaseCacheLive.js";
+import { Effect, Layer } from "effect";
+import { SemVerParserLive, VersionCacheLive } from "semver-effect";
+
+//#region src/layers/AutoBunCacheLive.ts
+const setup = Effect.gen(function* () {
+	const cache = yield* BunReleaseCache;
+	const inputs = yield* (yield* BunVersionFetcher).fetch().pipe(Effect.map((result) => result.inputs), Effect.catchTags({
+		AuthenticationError: () => Effect.succeed(bunDefaultInputs),
+		NetworkError: () => Effect.succeed(bunDefaultInputs),
+		ParseError: () => Effect.succeed(bunDefaultInputs),
+		RateLimitError: () => Effect.succeed(bunDefaultInputs)
+	}));
+	const releases = yield* Effect.all(inputs.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 "Auto" cache strategy.
+*
+* Attempts to fetch live release data from the GitHub API via
+* {@link BunVersionFetcher}. If the fetch fails for any reason — authentication
+* errors, network errors, parse errors, or rate-limit errors — it silently falls
+* back to the bundled default release data so the layer always succeeds.
+*
+* Use this strategy when you want the freshest data when available but can
+* tolerate slightly stale bundled data in degraded environments.
+*
+* The three Bun cache strategy layers are:
+* - `AutoBunCacheLive` — tries API first, falls back to bundled defaults on any error
+* - {@link FreshBunCacheLive} — requires live API data, fails with `FreshnessError` if unavailable
+* - {@link OfflineBunCacheLive} — uses only bundled defaults, no network I/O
+*
+* @see {@link BunReleaseCache}
+* @see {@link FreshBunCacheLive}
+* @see {@link OfflineBunCacheLive}
+* @public
+*/
+const AutoBunCacheLive = BaseCacheLayer.pipe(Layer.tap((ctx) => setup.pipe(Effect.provide(ctx))));
+
+//#endregion
+export { AutoBunCacheLive };

package/layers/AutoDenoCacheLive.js

@@ -0,0 +1,47 @@
+import { denoDefaultInputs } from "../data/deno-defaults.js";
+import { DenoRelease } from "../schemas/deno-release.js";
+import { DenoReleaseCache } from "../services/DenoReleaseCache.js";
+import { DenoVersionFetcher } from "../services/DenoVersionFetcher.js";
+import { DenoReleaseCacheLive } from "./DenoReleaseCacheLive.js";
+import { Effect, Layer } from "effect";
+import { SemVerParserLive, VersionCacheLive } from "semver-effect";
+
+//#region src/layers/AutoDenoCacheLive.ts
+const setup = Effect.gen(function* () {
+	const cache = yield* DenoReleaseCache;
+	const inputs = yield* (yield* DenoVersionFetcher).fetch().pipe(Effect.map((result) => result.inputs), Effect.catchTags({
+		AuthenticationError: () => Effect.succeed(denoDefaultInputs),
+		NetworkError: () => Effect.succeed(denoDefaultInputs),
+		ParseError: () => Effect.succeed(denoDefaultInputs),
+		RateLimitError: () => Effect.succeed(denoDefaultInputs)
+	}));
+	const releases = yield* Effect.all(inputs.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 "Auto" cache strategy.
+*
+* Attempts to fetch live release data from the GitHub API via
+* {@link DenoVersionFetcher}. If the fetch fails for any reason — authentication
+* errors, network errors, parse errors, or rate-limit errors — it silently falls
+* back to the bundled default release data so the layer always succeeds.
+*
+* Use this strategy when you want the freshest data when available but can
+* tolerate slightly stale bundled data in degraded environments.
+*
+* The three Deno cache strategy layers are:
+* - `AutoDenoCacheLive` — tries API first, falls back to bundled defaults on any error
+* - {@link FreshDenoCacheLive} — requires live API data, fails with `FreshnessError` if unavailable
+* - {@link OfflineDenoCacheLive} — uses only bundled defaults, no network I/O
+*
+* @see {@link DenoReleaseCache}
+* @see {@link FreshDenoCacheLive}
+* @see {@link OfflineDenoCacheLive}
+* @public
+*/
+const AutoDenoCacheLive = BaseCacheLayer.pipe(Layer.tap((ctx) => setup.pipe(Effect.provide(ctx))));
+
+//#endregion
+export { AutoDenoCacheLive };

package/layers/AutoNodeCacheLive.js

@@ -0,0 +1,58 @@
+import { nodeDefaultInputs, nodeDefaultScheduleData } from "../data/node-defaults.js";
+import { NodeReleaseCache } from "../services/NodeReleaseCache.js";
+import { NodeScheduleFetcher } from "../services/NodeScheduleFetcher.js";
+import { NodeVersionFetcher } from "../services/NodeVersionFetcher.js";
+import { NodeReleaseCacheLive } from "./NodeReleaseCacheLive.js";
+import { Effect, Layer } from "effect";
+import { SemVerParserLive, VersionCacheLive } from "semver-effect";
+
+//#region src/layers/AutoNodeCacheLive.ts
+const setup = Effect.gen(function* () {
+	const cache = yield* NodeReleaseCache;
+	const versionFetcher = yield* NodeVersionFetcher;
+	const scheduleFetcher = yield* NodeScheduleFetcher;
+	const nodeDefaults = {
+		inputs: nodeDefaultInputs,
+		scheduleData: nodeDefaultScheduleData
+	};
+	const { inputs, scheduleData } = yield* Effect.gen(function* () {
+		const [fetchResult, schedule] = yield* Effect.all([versionFetcher.fetch(), scheduleFetcher.fetch()]);
+		return {
+			inputs: fetchResult.inputs,
+			scheduleData: schedule
+		};
+	}).pipe(Effect.catchTags({
+		NetworkError: () => Effect.succeed(nodeDefaults),
+		ParseError: () => Effect.succeed(nodeDefaults)
+	}));
+	yield* cache.updateSchedule(scheduleData);
+	yield* cache.loadFromInputs(inputs);
+});
+const SemVerLayer = VersionCacheLive.pipe(Layer.provide(SemVerParserLive));
+const BaseCacheLayer = NodeReleaseCacheLive.pipe(Layer.provide(SemVerLayer));
+/**
+* Provides the {@link NodeReleaseCache} service using the "Auto" cache strategy.
+*
+* Attempts to fetch live release data from `nodejs.org/dist/index.json` via
+* {@link NodeVersionFetcher} and the release schedule from the `nodejs/Release`
+* repository via {@link NodeScheduleFetcher}. If either fetch fails — due to
+* network errors or parse errors — the layer silently falls back to bundled
+* default data (both version list and schedule) so it always succeeds.
+*
+* Node.js requires both a version fetcher and a schedule fetcher because LTS and
+* maintenance phase information is tracked separately from the version index.
+*
+* The three Node cache strategy layers are:
+* - `AutoNodeCacheLive` — tries API first, falls back to bundled defaults on any error
+* - {@link FreshNodeCacheLive} — requires live API data, fails with `FreshnessError` if unavailable
+* - {@link OfflineNodeCacheLive} — uses only bundled defaults, no network I/O
+*
+* @see {@link NodeReleaseCache}
+* @see {@link FreshNodeCacheLive}
+* @see {@link OfflineNodeCacheLive}
+* @public
+*/
+const AutoNodeCacheLive = BaseCacheLayer.pipe(Layer.tap((ctx) => setup.pipe(Effect.provide(ctx))));
+
+//#endregion
+export { AutoNodeCacheLive };

package/layers/BunReleaseCacheLive.js

@@ -0,0 +1,25 @@
+import { BunReleaseCache } from "../services/BunReleaseCache.js";
+import { createRuntimeCache } from "./RuntimeCacheLive.js";
+import { Layer } from "effect";
+
+//#region src/layers/BunReleaseCacheLive.ts
+/**
+* Low-level layer that constructs the {@link BunReleaseCache} service backed by
+* a `SemVerVersionCache` instance from `semver-effect`.
+*
+* This layer wires up the cache storage but does not populate it with any
+* release data. Callers are responsible for loading releases after construction.
+* In normal usage you should prefer the higher-level cache strategy layers
+* instead of using this layer directly:
+* - {@link AutoBunCacheLive} — API with fallback to bundled defaults
+* - {@link FreshBunCacheLive} — API only, fails if unavailable
+* - {@link OfflineBunCacheLive} — bundled defaults only
+*
+* @see {@link BunReleaseCache}
+* @see {@link createRuntimeCache}
+* @internal
+*/
+const BunReleaseCacheLive = Layer.effect(BunReleaseCache, createRuntimeCache());
+
+//#endregion
+export { BunReleaseCacheLive };

package/layers/BunResolverLive.js

@@ -0,0 +1,85 @@
+import { BunReleaseCache } from "../services/BunReleaseCache.js";
+import { VersionNotFoundError } from "../errors/VersionNotFoundError.js";
+import { BunResolver } from "../services/BunResolver.js";
+import { Effect, Layer } from "effect";
+import { SemVer } from "semver-effect";
+
+//#region src/layers/BunResolverLive.ts
+/**
+* Provides the {@link BunResolver} service backed by a {@link BunReleaseCache}.
+*
+* This layer composes with any of the three Bun cache strategy layers to form
+* a complete resolver stack. It implements semver range filtering and increment
+* grouping (latest per major, latest per minor, or all patch versions) using
+* the releases already loaded into the cache.
+*
+* @example
+* ```ts
+* import { BunResolverLive, AutoBunCacheLive, BunVersionFetcherLive, GitHubClientLive, GitHubAutoAuth } from "runtime-resolver";
+* import type { ResolvedVersions } from "runtime-resolver";
+* import { BunResolver } from "runtime-resolver";
+* import { Effect, Layer } from "effect";
+*
+* const GitHubLayer = GitHubClientLive.pipe(Layer.provide(GitHubAutoAuth));
+* const CacheLayer = AutoBunCacheLive.pipe(Layer.provide(BunVersionFetcherLive.pipe(Layer.provide(GitHubLayer))));
+* const ResolverLayer = BunResolverLive.pipe(Layer.provide(CacheLayer));
+*
+* const program = Effect.gen(function* () {
+*   const resolver = yield* BunResolver;
+*   const result = yield* resolver.resolve({ semverRange: "^1.0.0" });
+*   console.log(result.latest);
+* });
+*
+* Effect.runPromise(program.pipe(Effect.provide(ResolverLayer)));
+* ```
+*
+* @see {@link BunResolver}
+* @see {@link BunReleaseCache}
+* @see {@link AutoBunCacheLive}
+* @see {@link FreshBunCacheLive}
+* @see {@link OfflineBunCacheLive}
+* @public
+*/
+const BunResolverLive = Layer.effect(BunResolver, Effect.gen(function* () {
+	const cache = yield* BunReleaseCache;
+	return { resolve: (options) => Effect.gen(function* () {
+		const semverRange = options?.semverRange ?? "*";
+		const increments = options?.increments ?? "latest";
+		const matching = yield* cache.filter(semverRange).pipe(Effect.catchAll(() => Effect.succeed([])));
+		let resultReleases;
+		if (increments === "latest") {
+			const groups = /* @__PURE__ */ new Map();
+			for (const r of matching) {
+				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 matching) {
+				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 = [...matching];
+		if (resultReleases.length === 0) return yield* Effect.fail(new VersionNotFoundError({
+			runtime: "bun",
+			constraint: semverRange,
+			message: `No Bun versions found matching "${semverRange}"`
+		}));
+		const versions = SemVer.rsort(resultReleases.map((r) => r.version)).map((v) => v.toString());
+		const latest = versions[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,
+			...resolvedDefault ? { default: resolvedDefault } : {}
+		};
+	}) };
+}));
+
+//#endregion
+export { BunResolverLive };

package/layers/BunVersionFetcherLive.js

@@ -0,0 +1,55 @@
+import { BunVersionFetcher } from "../services/BunVersionFetcher.js";
+import { retryOnRateLimit } from "../lib/retry.js";
+import { tryParseSemVer } from "../lib/semver.js";
+import { GitHubClient } from "../services/GitHubClient.js";
+import { Effect, Layer, Option } from "effect";
+
+//#region src/layers/BunVersionFetcherLive.ts
+/**
+* Strip bun- prefix and v/V prefix, parse to SemVer.
+*/
+const normalizeBunTag = (tagName) => {
+	const version = tagName.startsWith("bun-") ? tagName.slice(4) : tagName;
+	return tryParseSemVer(version.startsWith("v") || version.startsWith("V") ? version.slice(1) : version);
+};
+/**
+* Provides the {@link BunVersionFetcher} service using the live GitHub API.
+*
+* Fetches Bun releases from the `oven-sh/bun` GitHub repository using the
+* provided {@link GitHubClient}. Draft releases and pre-releases are excluded.
+* Tag names are normalized by stripping the `bun-` prefix and any leading `v`
+* or `V` before parsing as semver.
+*
+* This layer is a required dependency of {@link AutoBunCacheLive} and
+* {@link FreshBunCacheLive}. It is not needed by {@link OfflineBunCacheLive}.
+*
+* @see {@link BunVersionFetcher}
+* @see {@link GitHubClient}
+* @see {@link AutoBunCacheLive}
+* @see {@link FreshBunCacheLive}
+* @public
+*/
+const BunVersionFetcherLive = Layer.effect(BunVersionFetcher, Effect.gen(function* () {
+	const client = yield* GitHubClient;
+	return { fetch: () => Effect.gen(function* () {
+		const releases = yield* retryOnRateLimit(client.listReleases("oven-sh", "bun", {
+			perPage: 100,
+			pages: 3
+		}));
+		const fallbackDate = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+		const parsed = yield* Effect.forEach(releases.filter((r) => !r.draft && !r.prerelease), (release) => normalizeBunTag(release.tag_name).pipe(Effect.map((opt) => Option.isSome(opt) ? Option.some({
+			version: opt.value,
+			input: {
+				version: opt.value.toString(),
+				date: release.published_at ?? fallbackDate
+			}
+		}) : Option.none())), { concurrency: "unbounded" });
+		return {
+			versions: parsed.flatMap(Option.toArray).map(({ version }) => version),
+			inputs: parsed.flatMap(Option.toArray).map(({ input }) => input)
+		};
+	}) };
+}));
+
+//#endregion
+export { BunVersionFetcherLive };

package/layers/DenoReleaseCacheLive.js

@@ -0,0 +1,25 @@
+import { createRuntimeCache } from "./RuntimeCacheLive.js";
+import { DenoReleaseCache } from "../services/DenoReleaseCache.js";
+import { Layer } from "effect";
+
+//#region src/layers/DenoReleaseCacheLive.ts
+/**
+* Low-level layer that constructs the {@link DenoReleaseCache} service backed by
+* a `SemVerVersionCache` instance from `semver-effect`.
+*
+* This layer wires up the cache storage but does not populate it with any
+* release data. Callers are responsible for loading releases after construction.
+* In normal usage you should prefer the higher-level cache strategy layers
+* instead of using this layer directly:
+* - {@link AutoDenoCacheLive} — API with fallback to bundled defaults
+* - {@link FreshDenoCacheLive} — API only, fails if unavailable
+* - {@link OfflineDenoCacheLive} — bundled defaults only
+*
+* @see {@link DenoReleaseCache}
+* @see {@link createRuntimeCache}
+* @internal
+*/
+const DenoReleaseCacheLive = Layer.effect(DenoReleaseCache, createRuntimeCache());
+
+//#endregion
+export { DenoReleaseCacheLive };