@effected/runtimes 0.1.5 → 0.2.0

package/BunResolver.js

@@ -47,11 +47,26 @@ const BunResolverOptions = Schema.Struct({
 * @public
 */
 var BunResolver = class extends Context.Service()("@effected/runtimes/BunResolver") {
-	/** Try GitHub, fall back to the bundled snapshot. */
+	/**
+	* Try GitHub, fall back to the bundled snapshot.
+	*
+	* Lazy: building the layer performs no IO. The feed is fetched by the first
+	* `resolve` and shared by every later (and concurrent) one; a fallback to
+	* the snapshot is memoized like any other successful population.
+	*/
 	static layer = mk(this, (index, live, offline) => populateAuto(index, "bun", live, offline));
-	/** GitHub or nothing. Fails with `FreshnessError` when it cannot be reached. */
+	/**
+	* GitHub or nothing.
+	*
+	* Lazy: building the layer performs no IO, so an unreachable feed surfaces
+	* as a `FreshnessError` from `resolve`, not from layer acquisition. A failed
+	* fetch is not memoized — the next `resolve` retries; a successful one is.
+	*/
 	static layerFresh = mk(this, (index, live) => populateFresh(index, "bun", live));
-	/** The bundled snapshot only. Performs no IO and requires nothing. */
+	/**
+	* The bundled snapshot only. Requires nothing and performs no IO — the
+	* snapshot is decoded lazily by the first `resolve`, like the live layers.
+	*/
 	static layerOffline = mk(this, (index, _live, offline) => populateOffline(index, offline));
 };
 /**

package/DenoResolver.js

@@ -47,11 +47,26 @@ const DenoResolverOptions = Schema.Struct({
 * @public
 */
 var DenoResolver = class extends Context.Service()("@effected/runtimes/DenoResolver") {
-	/** Try GitHub, fall back to the bundled snapshot. */
+	/**
+	* Try GitHub, fall back to the bundled snapshot.
+	*
+	* Lazy: building the layer performs no IO. The feed is fetched by the first
+	* `resolve` and shared by every later (and concurrent) one; a fallback to
+	* the snapshot is memoized like any other successful population.
+	*/
 	static layer = mk(this, (index, live, offline) => populateAuto(index, "deno", live, offline));
-	/** GitHub or nothing. Fails with `FreshnessError` when it cannot be reached. */
+	/**
+	* GitHub or nothing.
+	*
+	* Lazy: building the layer performs no IO, so an unreachable feed surfaces
+	* as a `FreshnessError` from `resolve`, not from layer acquisition. A failed
+	* fetch is not memoized — the next `resolve` retries; a successful one is.
+	*/
 	static layerFresh = mk(this, (index, live) => populateFresh(index, "deno", live));
-	/** The bundled snapshot only. Performs no IO and requires nothing. */
+	/**
+	* The bundled snapshot only. Requires nothing and performs no IO — the
+	* snapshot is decoded lazily by the first `resolve`, like the live layers.
+	*/
 	static layerOffline = mk(this, (index, _live, offline) => populateOffline(index, offline));
 };
 /**

package/NodeResolver.js

@@ -1,5 +1,6 @@
 import { NodePhase, NodeSchedule } from "./NodeSchedule.js";
 import { buildNodeReleases, fetchNodeReleases, fetchNodeSchedule } from "./internal/feeds.js";
+import { once } from "./internal/once.js";
 import { make } from "./internal/releaseIndex.js";
 import { Increments } from "./ResolvedVersions.js";
 import { resolveWith } from "./internal/resolve.js";
@@ -47,25 +48,40 @@ var NodeResolver = class extends Context.Service()("@effected/runtimes/NodeResol
 	/**
 	* Try the live feeds, fall back to the bundled snapshot.
 	*
-	* A fallback is recorded as `source: "cache"` and logged, so a caller can
+	* Lazy: building the layer performs no IO. The feeds are fetched by the
+	* first `resolve` and shared by every later (and concurrent) one; a
+	* fallback to the snapshot is memoized like any other successful
+	* population, recorded as `source: "cache"` and logged, so a caller can
 	* always tell a live answer from a snapshot.
 	*/
 	static layer = build(this, (index, live, offline) => populateAuto(index, "node", live, offline));
 	/**
-	* Live feeds or nothing. Fails with `FreshnessError` when they cannot be reached.
+	* Live feeds or nothing.
+	*
+	* Lazy: building the layer performs no IO, so unreachable feeds surface as
+	* a `FreshnessError` from `resolve`, not from layer acquisition. A failed
+	* fetch is not memoized — the next `resolve` retries; a successful one is.
 	*/
 	static layerFresh = build(this, (index, live) => populateFresh(index, "node", live));
 	/**
-	* The bundled snapshot only. Performs no IO and requires nothing.
+	* The bundled snapshot only. Requires nothing and performs no IO — the
+	* snapshot is decoded lazily by the first `resolve`, like the live layers.
 	*/
 	static layerOffline = build(this, (index, _live, offline) => populateOffline(index, offline));
 };
 /**
-* Assemble a Node resolver layer around a strategy.
+* Assemble a **lazy** Node resolver layer around a strategy.
+*
+* Acquisition performs no IO: it builds the empty index, captures the
+* strategy's requirements from the layer scope, and gates the strategy behind
+* a run-once memo (see `internal/once.ts`). The first `resolve` runs the
+* population; concurrent first resolves share it; success is memoized for the
+* layer's lifetime while a failure (only the fresh strategy can produce one)
+* is retried by the next resolve.
 *
-* The strategy's own error and requirement channels flow straight out into the
-* layer's, so `layerOffline` genuinely requires nothing and `layer` genuinely
-* cannot fail — no casts, and the types say what is true.
+* The strategy's requirement channel still flows straight out into the
+* layer's, so `layerOffline` genuinely requires nothing, and its error channel
+* flows into `resolve`'s — no casts, and the types say what is true.
 *
 * The tag arrives as `this`: a static initializer runs while the module-scope
 * `NodeResolver` binding is still in its temporal dead zone, so naming the class
@@ -75,15 +91,16 @@ function build(tag, strategy) {
 	return Layer.effect(tag, Effect.gen(function* () {
 		const index = yield* make();
 		const scheduleRef = yield* Ref.make(NodeSchedule.empty);
-		yield* strategy(index, Effect.gen(function* () {
+		const populate = yield* once(strategy(index, Effect.gen(function* () {
 			const [raw, scheduleData] = yield* Effect.all([fetchNodeReleases(), fetchNodeSchedule()]);
 			yield* Ref.set(scheduleRef, yield* NodeSchedule.fromData(scheduleData));
 			return yield* buildNodeReleases(raw);
 		}).pipe(Effect.catchTag("InvalidVersionError", (cause) => Effect.die(cause))), Effect.gen(function* () {
 			yield* Ref.set(scheduleRef, yield* NodeSchedule.fromData(nodeScheduleDefaults));
 			return yield* buildNodeReleases(nodeDefaults);
-		}).pipe(Effect.orDie));
+		}).pipe(Effect.orDie)));
 		return { resolve: Effect.fn("NodeResolver.resolve")(function* (options) {
+			yield* populate;
 			const range = options?.range ?? "*";
 			const phases = options?.phases ?? DEFAULT_PHASES;
 			const now = options?.date ?? (yield* DateTime.now);

package/README.md

@@ -23,7 +23,7 @@ Resolve semver-compatible Node.js, Bun and Deno versions from the live release f
 
 Every answer carries an honest `source`. A resolver that fetches live data, silently fails, serves a snapshot and reports `source: "api"` is worse than one that never had a snapshot — you cannot tell a fresh answer from a stale one, and a CI job pinning its toolchain will happily install a version that was current last quarter. Here the field is set by whichever strategy actually populated the index: `"api"` when the feed answered, `"cache"` when the snapshot did, including when the automatic strategy fell back to it, and the fallback logs a warning on the way through.
 
-The freshness policy is a layer, not a flag, and the types follow: `layerOffline` has no error channel and no requirements, because a snapshot read cannot fail and does no IO. `layerFresh` fails with `FreshnessError` and nothing else, because you chose it to say a snapshot is not an acceptable substitute. A single resolver switching on a strategy enum would union all three error channels together and force the offline layer to advertise a failure it cannot have.
+The freshness policy is a layer, not a flag, and the layers are lazy: building one performs no IO, the first `resolve` fetches the feed, and every later resolve shares that population. The types follow: `layerOffline` requires nothing, because a snapshot read needs no transport. Under `layerFresh`, `resolve` fails with `FreshnessError`, because you chose it to say a snapshot is not an acceptable substitute — and because the fetch happens at resolve time, that failure arrives where you can catch it, retry it or fall back, not buried in layer construction.
 
 There is no HTTP client in the dependency tree either. The v3 library carried Octokit and `@octokit/auth-app` to fund exactly two REST GETs; this one goes through `HttpClient` from `effect/unstable/http` and lets you supply the transport. `@effected/semver` is the only runtime dependency, and it is first-party.
 
@@ -76,12 +76,14 @@ No credentials are needed for Node: both feeds it reads — nodejs.org's release
 
 Each of the three resolvers exposes the same three layer **constants**:
 
-| Layer | Behavior | Fails with | Requires |
-| ----- | -------- | ---------- | -------- |
+| Layer | Behavior | `resolve` fails with | Requires |
+| ----- | -------- | -------------------- | -------- |
 | `layer` | Fetch live; on failure fall back to the bundled snapshot, log a warning and report `source: "cache"` | never | the resolver's transport |
 | `layerFresh` | Live data or nothing | `FreshnessError` | the resolver's transport |
 | `layerOffline` | The bundled snapshot only. No IO. | never | nothing |
 
+Every layer is **lazy**: building it performs no IO, so merging all three resolvers costs nothing until you actually resolve one. The first `resolve` fetches the feed, and later and concurrent resolves share that one population for the layer's lifetime — including the automatic strategy's snapshot fallback, which counts as a successful population and is not re-fetched. Only a *failed* population is not memoized: a `layerFresh` resolve that fails with `FreshnessError` leaves the next resolve free to retry. The lazy timing is also why `FreshnessError` sits in `resolve`'s error channel rather than the layer's — building `layerFresh` cannot fail; resolving through it can.
+
 The transport differs by runtime, and that is not an accident:
 
 | Resolver | Feed | Requires |
@@ -137,7 +139,7 @@ The Node schedule is keyed by release *line*, not by major — `nodejs/Release`
 | `InvalidRangeError` | The semver range is malformed. Raised by `@effected/semver` and imported from there. | A typo in a range is a typo, not a not-found. Report it as one. |
 | `NoMatchingVersionError` | The range is fine and nothing matched it. Carries `runtime`, `constraint` and the `phases` searched. | Widen the range, or accept more phases. |
 | `UnresolvableDefaultError` | An explicit `defaultVersion` was asked for and nothing matched it. Carries `runtime` and `defaultVersion`. | Distinct from the above, because Node's default otherwise falls back to the LTS pick — silently dropping it would hand you LTS as though you had asked for it. |
-| `FreshnessError` | `layerFresh` could not reach the feed. Carries `runtime` and the structural `cause`. | Retry, or fall back to `layer` and accept a snapshot. |
+| `FreshnessError` | A `resolve` under `layerFresh` could not reach the feed. Carries `runtime` and the structural `cause`. | Retry the resolve (a failed fetch is not memoized), or fall back to `layer` and accept a snapshot. |
 | `RateLimitError` | GitHub's rate limit is exhausted. Carries `limit`, `remaining` and, when GitHub said, `retryAfter` in seconds. | Authenticate, or back off by `retryAfter`. A `403` is classified from the response headers, never guessed from the body. |
 | `AuthenticationError` | GitHub rejected the credential. Carries `method` — `"token"` or `"anonymous"`. | Check the token, or supply one. |
 | `NetworkError` | The request failed, or returned a status that is neither auth nor rate limit. Carries `url`, the `status` where there was one, and the structural `cause`. | A permission `403` lands here and is not retried. |

package/index.d.ts

@@ -338,7 +338,7 @@ declare const BunResolverOptions: Schema.Struct<{
  */
 type BunResolverOptions = typeof BunResolverOptions.Type;
 declare const BunResolver_base: Context.ServiceClass<BunResolver, "@effected/runtimes/BunResolver", {
-  readonly resolve: (options?: BunResolverOptions) => Effect.Effect<ResolvedVersions, InvalidRangeError | NoMatchingVersionError | UnresolvableDefaultError>;
+  readonly resolve: (options?: BunResolverOptions) => Effect.Effect<ResolvedVersions, InvalidRangeError | NoMatchingVersionError | UnresolvableDefaultError | FreshnessError>;
 }>;
 /**
  * The Bun resolver.
@@ -357,11 +357,26 @@ declare const BunResolver_base: Context.ServiceClass<BunResolver, "@effected/run
  * @public
  */
 declare class BunResolver extends BunResolver_base {
-  /** Try GitHub, fall back to the bundled snapshot. */
+  /**
+   * Try GitHub, fall back to the bundled snapshot.
+   *
+   * Lazy: building the layer performs no IO. The feed is fetched by the first
+   * `resolve` and shared by every later (and concurrent) one; a fallback to
+   * the snapshot is memoized like any other successful population.
+   */
   static readonly layer: Layer.Layer<BunResolver, never, GitHubClient>;
-  /** GitHub or nothing. Fails with `FreshnessError` when it cannot be reached. */
-  static readonly layerFresh: Layer.Layer<BunResolver, FreshnessError, GitHubClient>;
-  /** The bundled snapshot only. Performs no IO and requires nothing. */
+  /**
+   * GitHub or nothing.
+   *
+   * Lazy: building the layer performs no IO, so an unreachable feed surfaces
+   * as a `FreshnessError` from `resolve`, not from layer acquisition. A failed
+   * fetch is not memoized — the next `resolve` retries; a successful one is.
+   */
+  static readonly layerFresh: Layer.Layer<BunResolver, never, GitHubClient>;
+  /**
+   * The bundled snapshot only. Requires nothing and performs no IO — the
+   * snapshot is decoded lazily by the first `resolve`, like the live layers.
+   */
   static readonly layerOffline: Layer.Layer<BunResolver>;
 }
 //#endregion
@@ -398,7 +413,7 @@ declare const DenoResolverOptions: Schema.Struct<{
  */
 type DenoResolverOptions = typeof DenoResolverOptions.Type;
 declare const DenoResolver_base: Context.ServiceClass<DenoResolver, "@effected/runtimes/DenoResolver", {
-  readonly resolve: (options?: DenoResolverOptions) => Effect.Effect<ResolvedVersions, InvalidRangeError | NoMatchingVersionError | UnresolvableDefaultError>;
+  readonly resolve: (options?: DenoResolverOptions) => Effect.Effect<ResolvedVersions, InvalidRangeError | NoMatchingVersionError | UnresolvableDefaultError | FreshnessError>;
 }>;
 /**
  * The Deno resolver.
@@ -417,11 +432,26 @@ declare const DenoResolver_base: Context.ServiceClass<DenoResolver, "@effected/r
  * @public
  */
 declare class DenoResolver extends DenoResolver_base {
-  /** Try GitHub, fall back to the bundled snapshot. */
+  /**
+   * Try GitHub, fall back to the bundled snapshot.
+   *
+   * Lazy: building the layer performs no IO. The feed is fetched by the first
+   * `resolve` and shared by every later (and concurrent) one; a fallback to
+   * the snapshot is memoized like any other successful population.
+   */
   static readonly layer: Layer.Layer<DenoResolver, never, GitHubClient>;
-  /** GitHub or nothing. Fails with `FreshnessError` when it cannot be reached. */
-  static readonly layerFresh: Layer.Layer<DenoResolver, FreshnessError, GitHubClient>;
-  /** The bundled snapshot only. Performs no IO and requires nothing. */
+  /**
+   * GitHub or nothing.
+   *
+   * Lazy: building the layer performs no IO, so an unreachable feed surfaces
+   * as a `FreshnessError` from `resolve`, not from layer acquisition. A failed
+   * fetch is not memoized — the next `resolve` retries; a successful one is.
+   */
+  static readonly layerFresh: Layer.Layer<DenoResolver, never, GitHubClient>;
+  /**
+   * The bundled snapshot only. Requires nothing and performs no IO — the
+   * snapshot is decoded lazily by the first `resolve`, like the live layers.
+   */
   static readonly layerOffline: Layer.Layer<DenoResolver>;
 }
 //#endregion
@@ -696,7 +726,7 @@ declare const NodeResolverOptions: Schema.Struct<{
  */
 type NodeResolverOptions = typeof NodeResolverOptions.Type;
 declare const NodeResolver_base: Context.ServiceClass<NodeResolver, "@effected/runtimes/NodeResolver", {
-  readonly resolve: (options?: NodeResolverOptions) => Effect.Effect<ResolvedVersions, InvalidRangeError | NoMatchingVersionError | UnresolvableDefaultError>;
+  readonly resolve: (options?: NodeResolverOptions) => Effect.Effect<ResolvedVersions, InvalidRangeError | NoMatchingVersionError | UnresolvableDefaultError | FreshnessError>;
 }>;
 /**
  * The Node.js resolver.
@@ -719,16 +749,24 @@ declare class NodeResolver extends NodeResolver_base {
   /**
    * Try the live feeds, fall back to the bundled snapshot.
    *
-   * A fallback is recorded as `source: "cache"` and logged, so a caller can
+   * Lazy: building the layer performs no IO. The feeds are fetched by the
+   * first `resolve` and shared by every later (and concurrent) one; a
+   * fallback to the snapshot is memoized like any other successful
+   * population, recorded as `source: "cache"` and logged, so a caller can
    * always tell a live answer from a snapshot.
    */
   static readonly layer: Layer.Layer<NodeResolver, never, HttpClient.HttpClient>;
   /**
-   * Live feeds or nothing. Fails with `FreshnessError` when they cannot be reached.
+   * Live feeds or nothing.
+   *
+   * Lazy: building the layer performs no IO, so unreachable feeds surface as
+   * a `FreshnessError` from `resolve`, not from layer acquisition. A failed
+   * fetch is not memoized — the next `resolve` retries; a successful one is.
    */
-  static readonly layerFresh: Layer.Layer<NodeResolver, FreshnessError, HttpClient.HttpClient>;
+  static readonly layerFresh: Layer.Layer<NodeResolver, never, HttpClient.HttpClient>;
   /**
-   * The bundled snapshot only. Performs no IO and requires nothing.
+   * The bundled snapshot only. Requires nothing and performs no IO — the
+   * snapshot is decoded lazily by the first `resolve`, like the live layers.
    */
   static readonly layerOffline: Layer.Layer<NodeResolver>;
 }

package/internal/githubRuntime.js

@@ -1,25 +1,34 @@
 import { GitHubClient } from "../GitHub.js";
 import { buildReleases, fetchGitHubReleases } from "./feeds.js";
+import { once } from "./once.js";
 import { make } from "./releaseIndex.js";
 import { resolveWith } from "./resolve.js";
 import { Effect, Layer, Option } from "effect";
 
 //#region src/internal/githubRuntime.ts
 /**
-* Build a layer for a GitHub-hosted runtime around a strategy.
+* Build a **lazy** layer for a GitHub-hosted runtime around a strategy.
 *
-* The strategy's channels flow out into the layer's, so `layerOffline` requires
-* no `GitHubClient` and `layer` cannot fail — stated by the types, not asserted
-* by a cast.
+* Acquisition performs no IO: it builds the empty index, captures the
+* strategy's requirements from the layer scope, and gates the strategy behind
+* a run-once memo (see `internal/once.ts`). The first `resolve` runs the
+* population; concurrent first resolves share it; success is memoized for the
+* layer's lifetime while a failure (only the fresh strategy can produce one)
+* is retried by the next resolve.
+*
+* The strategy's requirements still flow out into the layer's (`layerOffline`
+* requires no `GitHubClient`), and its error channel flows into `resolve`'s —
+* stated by the types, not asserted by a cast.
 */
 const build = (spec, strategy) => {
 	const { tag, runtime, owner, repo, spanName, defaults, make: make$1 } = spec;
 	return Layer.effect(tag, Effect.gen(function* () {
 		const index = yield* make();
-		yield* strategy(index, Effect.gen(function* () {
+		const populate = yield* once(strategy(index, Effect.gen(function* () {
 			return yield* buildReleases(yield* fetchGitHubReleases(yield* GitHubClient, owner, repo), make$1);
-		}), buildReleases(defaults, make$1));
+		}), buildReleases(defaults, make$1)));
 		return { resolve: Effect.fn(spanName)(function* (options) {
+			yield* populate;
 			const range = options?.range ?? "*";
 			yield* Effect.annotateCurrentSpan({
 				runtime,

package/internal/once.js

@@ -0,0 +1,50 @@
+import { Effect, Ref, Semaphore } from "effect";
+
+//#region src/internal/once.ts
+/**
+* A run-at-most-once gate for deferred layer population.
+*
+* The resolver layers are lazy: acquiring one performs no IO, and the feed
+* fetch happens on the first `resolve`. This helper is the memoization behind
+* that contract, chosen over `Effect.cached` deliberately — `cached` memoizes
+* the *Exit*, so a transient network failure (or an interrupted first resolve)
+* would poison the resolver for the layer's whole lifetime.
+*
+* Semantics, exactly:
+*
+* - **Success is memoized.** The first successful run flips the gate; every
+*   later and every concurrently-waiting caller skips the work.
+* - **Concurrent first callers share one run.** A semaphore serializes entry;
+*   waiters re-check the gate under the permit and skip when the winner
+*   succeeded.
+* - **Failure is not memoized.** The gate only flips after success, so a
+*   failed run leaves it open and the next caller retries. Same for an
+*   interrupted run — `withPermits` releases the permit on interruption.
+*
+* The effect's requirements are captured from the *acquiring* scope
+* (`Effect.context`), so the gated effect needs nothing at call time — which
+* is what lets a lazy `resolve` keep `R = never` while the layer still
+* honestly advertises the strategy's requirements.
+*
+* @internal
+*/
+/**
+* Capture `effect`'s requirements now; return a gated effect that runs it at
+* most once successfully, retrying after failure or interruption.
+*/
+const once = (effect) => Effect.gen(function* () {
+	const context = yield* Effect.context();
+	const done = yield* Ref.make(false);
+	const run = (yield* Semaphore.make(1)).withPermits(1)(Effect.gen(function* () {
+		if (yield* Ref.get(done)) return;
+		yield* Effect.provideContext(effect, context);
+		yield* Ref.set(done, true);
+	}));
+	return Effect.gen(function* () {
+		if (yield* Ref.get(done)) return;
+		yield* run;
+	});
+});
+
+//#endregion
+export { once };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/runtimes",
-	"version": "0.1.5",
+	"version": "0.2.0",
 	"private": false,
 	"description": "Resolve semver-compatible Node.js, Bun and Deno runtime versions with offline fallback.",
 	"keywords": [