@effected/runtimes 0.9.0 → 0.10.0

package/BunResolver.js

@@ -31,7 +31,14 @@ const BunResolverOptions = Schema.Struct({
 	defaultVersion: Schema.optionalKey(Schema.String)
 });
 /**
-* The Bun resolver.
+* Resolves a semver range to concrete Bun versions, with release data from GitHub
+* (`oven-sh/bun`) or a bundled snapshot.
+*
+* @remarks
+* Choose a strategy with the layer: `layer` tries GitHub and falls back to the
+* snapshot, `layerFresh` fails rather than fall back, and `layerOffline` uses
+* only the snapshot. `resolve` fails with `InvalidRangeError`,
+* `NoMatchingVersionError`, `UnresolvableDefaultError` or `FreshnessError`.
 *
 * @example
 * ```ts

package/DenoResolver.js

@@ -31,7 +31,14 @@ const DenoResolverOptions = Schema.Struct({
 	defaultVersion: Schema.optionalKey(Schema.String)
 });
 /**
-* The Deno resolver.
+* Resolves a semver range to concrete Deno versions, with release data from GitHub
+* (`denoland/deno`) or a bundled snapshot.
+*
+* @remarks
+* Choose a strategy with the layer: `layer` tries GitHub and falls back to the
+* snapshot, `layerFresh` fails rather than fall back, and `layerOffline` uses
+* only the snapshot. `resolve` fails with `InvalidRangeError`,
+* `NoMatchingVersionError`, `UnresolvableDefaultError` or `FreshnessError`.
 *
 * @example
 * ```ts

package/GitHub.js

@@ -4,16 +4,6 @@ import { FetchHttpClient, HttpClient } from "effect/http";
 
 //#region src/GitHub.ts
 /**
-* Talking to GitHub: pluggable authentication, a REST client, and the typed
-* failure ladder that every network fetch in this package reports through.
-*
-* The two nodejs.org feeds reuse this ladder rather than minting a parallel
-* one, so the module is named for its dominant user rather than for the
-* lowest common denominator.
-*
-* @packageDocumentation
-*/
-/**
 * GitHub rejected the credentials.
 *
 * @public
@@ -70,10 +60,8 @@ var ResponseParseError = class extends Schema.TaggedError()("ResponseParseError"
 * records and this is the single place they become errors. That is what keeps
 * the transport layer free of the facade and the import graph acyclic.
 *
-* `method` is what the *caller* actually sent, not a guess. Hardcoding it to
-* `"token"` made the `"anonymous"` arm of `AuthenticationError` unreachable and
-* mislabelled every anonymous rejection — the same shape of lie as v3's
-* hardcoded `source: "api"`.
+* `method` is what the *caller* actually sent, not a guess, so the
+* `"anonymous"` arm of `AuthenticationError` is reachable.
 *
 * @internal
 */
@@ -145,8 +133,8 @@ var GitHubAuth = class GitHubAuth extends Context.Service()("@effected/runtimes/
 	* Detect a credential from the environment, preferring an explicit PAT.
 	*
 	* Precedence is `GITHUB_PERSONAL_ACCESS_TOKEN`, then `GITHUB_TOKEN`, then
-	* unauthenticated — the v3 policy, kept, but read through `Config` so a test
-	* can swap the `ConfigProvider` instead of mutating `process.env`.
+	* unauthenticated. The variables are read through `Config`, so a test can swap
+	* the `ConfigProvider` instead of mutating `process.env`.
 	*/
 	static layer = Layer.effect(GitHubAuth, Effect.gen(function* () {
 		const pat = yield* patConfig;
@@ -169,9 +157,9 @@ const GITHUB_HEADERS = {
 /**
 * A GitHub REST client over `HttpClient`.
 *
-* v3 reached for `octokit` here, which cost two large dependency graphs to fund
-* two GET requests. Programming against `HttpClient` from `effect` core keeps
-* the package boundary tier and lets a consumer supply any transport.
+* Programs against `HttpClient` from `effect` core, so the package stays
+* boundary tier and a consumer can supply any transport. It lists a
+* repository's tags and releases, and fails with the {@link GitHubError} ladder.
 *
 * @public
 */

package/NodeRelease.js

@@ -4,22 +4,15 @@ import { Option, Schema } from "effect";
 
 //#region src/NodeRelease.ts
 /**
-* A published Node.js release.
+* One published Node.js release: its version, bundled npm version and release date.
 *
-* @packageDocumentation
-*/
-/**
-* One Node.js release.
-*
-* Unlike its v3 ancestor this is an ordinary immutable value. v3's `NodeRelease`
-* carried a `Ref<NodeSchedule>` so that `release.phase()` could reach the
-* schedule, which meant every release held shared mutable state and could not be
-* a data class at all. Phase is now a question you ask *with* a schedule rather
-* than a property the release drags around.
+* An ordinary immutable value. Phase is a question you ask *with* a schedule
+* (`release.phase(schedule, now)`) rather than a property the release carries.
 *
 * @example
 * ```ts
 * import { NodeRelease, NodeSchedule } from "@effected/runtimes";
+* import { SemVer } from "@effected/semver";
 * import { DateTime, Effect } from "effect";
 *
 * const program = Effect.gen(function* () {

package/NodeResolver.js

@@ -28,7 +28,15 @@ const NodeResolverOptions = Schema.Struct({
 });
 const DEFAULT_PHASES = ["current", "active-lts"];
 /**
-* The Node.js resolver.
+* Resolves a semver range to concrete Node.js versions, filtered by lifecycle
+* phase, with release data from the nodejs.org feeds or a bundled snapshot.
+*
+* @remarks
+* Choose a strategy with the layer: `layer` tries the live feeds and falls back
+* to the snapshot (recorded as `source: "cache"`), `layerFresh` fails rather
+* than fall back, and `layerOffline` uses only the snapshot. `resolve` fails
+* with `InvalidRangeError`, `NoMatchingVersionError`, `UnresolvableDefaultError`
+* or `FreshnessError`.
 *
 * @example
 * ```ts

package/NodeSchedule.js

@@ -2,11 +2,6 @@ import { DateTime, Effect, Option, Order, Schema } from "effect";
 
 //#region src/NodeSchedule.ts
 /**
-* The Node.js release schedule and the lifecycle phases derived from it.
-*
-* @packageDocumentation
-*/
-/**
 * Lifecycle phase of a Node.js major release line.
 *
 * - `current` — actively receiving features and bug fixes.
@@ -113,11 +108,9 @@ const SCHEDULE_KEY = /^v?(\d+)(?:\.(\d+))?$/;
 /**
 * An immutable snapshot of the Node.js release schedule.
 *
-* In v3 a `Ref<NodeSchedule>` was threaded *into every `NodeRelease`* so that
-* `release.phase()` could reach the schedule — mutable service state inside an
-* immutable domain value, which is why `NodeRelease` could not be a data class.
-* Here the schedule is a value the caller passes in: phase is a function of
-* `(release, schedule, now)`, and nothing in the model is mutable.
+* The schedule is a value the caller passes in: phase is a function of
+* `(release, schedule, now)`, so nothing in the model is mutable and
+* {@link NodeRelease} stays a plain data class.
 *
 * @example
 * ```ts

package/README.md

@@ -7,10 +7,10 @@
 
 Resolve semver-compatible Node.js, Bun and Deno versions from the live release feeds, with a bundled offline snapshot as a fallback. Ask for `>=20` in the `active-lts` phase and get back every match, newest first, plus the LTS pick and whatever you nominated as the default. Node's lifecycle phases come from the real `nodejs/Release` schedule and are evaluated against the clock, so `current`, `active-lts`, `maintenance-lts` and `end-of-life` mean what they mean today rather than on the day the package was published.
 
-> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 prerelease. Packages graduate to
-> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
-> exactly the ones the kit is built and tested against, install
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
 >
 > **Stability: unstable.** This package's API surface is not yet considered

package/ResolvedVersions.js

@@ -3,11 +3,6 @@ import { Schema } from "effect";
 
 //#region src/ResolvedVersions.ts
 /**
-* The shared vocabulary of resolution: what a resolver returns, and how it fails.
-*
-* @packageDocumentation
-*/
-/**
 * The JavaScript runtime a resolver targets.
 *
 * @public
@@ -24,10 +19,8 @@ const Runtime = Schema.Literals([
 * - `cache` — the bundled snapshot was used, either because the offline
 *   strategy was chosen or because the auto strategy fell back to it.
 *
-* This is honest provenance. In v3 the field existed, was advertised as a
-* headline feature, and was hardcoded to `"api"` by every resolver — so a
-* caller could not tell a live answer from a snapshot served after a silent
-* network failure.
+* This is honest provenance: a caller can always tell a live answer from a
+* snapshot served after a network failure.
 *
 * @public
 */
@@ -47,7 +40,7 @@ const Increments = Schema.Literals([
 	"patch"
 ]);
 /**
-* What every resolver returns.
+* What every resolver returns: the matching versions, the newest one, and where the data came from.
 *
 * @public
 */
@@ -68,8 +61,6 @@ var ResolvedVersions = class extends Schema.Class("ResolvedVersions")({
 *
 * Distinct from an invalid constraint: `@effected/semver`'s `InvalidRangeError`
 * says the range is malformed, this says the range is fine and nothing matched.
-* v3 collapsed the former into the latter, so a typo in a range surfaced to the
-* user as "no versions found".
 *
 * @public
 */

package/index.d.ts

@@ -121,8 +121,8 @@ export declare class GitHubAuth extends GitHubAuth_base {
    * Detect a credential from the environment, preferring an explicit PAT.
    *
    * Precedence is `GITHUB_PERSONAL_ACCESS_TOKEN`, then `GITHUB_TOKEN`, then
-   * unauthenticated — the v3 policy, kept, but read through `Config` so a test
-   * can swap the `ConfigProvider` instead of mutating `process.env`.
+   * unauthenticated. The variables are read through `Config`, so a test can swap
+   * the `ConfigProvider` instead of mutating `process.env`.
    */
   static readonly layer: Layer.Layer<GitHubAuth>;
 }
@@ -159,9 +159,9 @@ declare const GitHubClient_base: Context.ServiceClass<GitHubClient, "@effected/r
 /**
  * A GitHub REST client over `HttpClient`.
  *
- * v3 reached for `octokit` here, which cost two large dependency graphs to fund
- * two GET requests. Programming against `HttpClient` from `effect` core keeps
- * the package boundary tier and lets a consumer supply any transport.
+ * Programs against `HttpClient` from `effect` core, so the package stays
+ * boundary tier and a consumer can supply any transport. It lists a
+ * repository's tags and releases, and fails with the {@link GitHubError} ladder.
  *
  * @public
  */
@@ -199,10 +199,8 @@ export type Runtime = typeof Runtime.Type;
  * - `cache` — the bundled snapshot was used, either because the offline
  *   strategy was chosen or because the auto strategy fell back to it.
  *
- * This is honest provenance. In v3 the field existed, was advertised as a
- * headline feature, and was hardcoded to `"api"` by every resolver — so a
- * caller could not tell a live answer from a snapshot served after a silent
- * network failure.
+ * This is honest provenance: a caller can always tell a live answer from a
+ * snapshot served after a network failure.
  *
  * @public
  */
@@ -242,7 +240,7 @@ declare const ResolvedVersions_base: Schema.Class<ResolvedVersions, Schema.Struc
   readonly default: Schema.optionalKey<Schema.String>;
 }>, {}>;
 /**
- * What every resolver returns.
+ * What every resolver returns: the matching versions, the newest one, and where the data came from.
  *
  * @public
  */
@@ -260,8 +258,6 @@ declare const NoMatchingVersionError_base: Schema.Class<NoMatchingVersionError,
  *
  * Distinct from an invalid constraint: `@effected/semver`'s `InvalidRangeError`
  * says the range is malformed, this says the range is fine and nothing matched.
- * v3 collapsed the former into the latter, so a typo in a range surfaced to the
- * user as "no versions found".
  *
  * @public
  */
@@ -338,10 +334,18 @@ export declare const BunResolverOptions: Schema.Struct<{
  */
 export type BunResolverOptions = typeof BunResolverOptions.Type;
 declare const BunResolver_base: Context.ServiceClass<BunResolver, "@effected/runtimes/BunResolver", {
+  /** Resolve a range to the matching versions, newest first. */
   readonly resolve: (options?: BunResolverOptions) => Effect.Effect<ResolvedVersions, InvalidRangeError | NoMatchingVersionError | UnresolvableDefaultError | FreshnessError>;
 }>;
 /**
- * The Bun resolver.
+ * Resolves a semver range to concrete Bun versions, with release data from GitHub
+ * (`oven-sh/bun`) or a bundled snapshot.
+ *
+ * @remarks
+ * Choose a strategy with the layer: `layer` tries GitHub and falls back to the
+ * snapshot, `layerFresh` fails rather than fall back, and `layerOffline` uses
+ * only the snapshot. `resolve` fails with `InvalidRangeError`,
+ * `NoMatchingVersionError`, `UnresolvableDefaultError` or `FreshnessError`.
  *
  * @example
  * ```ts
@@ -413,10 +417,18 @@ export declare const DenoResolverOptions: Schema.Struct<{
  */
 export type DenoResolverOptions = typeof DenoResolverOptions.Type;
 declare const DenoResolver_base: Context.ServiceClass<DenoResolver, "@effected/runtimes/DenoResolver", {
+  /** Resolve a range to the matching versions, newest first. */
   readonly resolve: (options?: DenoResolverOptions) => Effect.Effect<ResolvedVersions, InvalidRangeError | NoMatchingVersionError | UnresolvableDefaultError | FreshnessError>;
 }>;
 /**
- * The Deno resolver.
+ * Resolves a semver range to concrete Deno versions, with release data from GitHub
+ * (`denoland/deno`) or a bundled snapshot.
+ *
+ * @remarks
+ * Choose a strategy with the layer: `layer` tries GitHub and falls back to the
+ * snapshot, `layerFresh` fails rather than fall back, and `layerOffline` uses
+ * only the snapshot. `resolve` fails with `InvalidRangeError`,
+ * `NoMatchingVersionError`, `UnresolvableDefaultError` or `FreshnessError`.
  *
  * @example
  * ```ts
@@ -576,11 +588,9 @@ declare const NodeSchedule_base: Schema.Class<NodeSchedule, Schema.Struct<{
 /**
  * An immutable snapshot of the Node.js release schedule.
  *
- * In v3 a `Ref<NodeSchedule>` was threaded *into every `NodeRelease`* so that
- * `release.phase()` could reach the schedule — mutable service state inside an
- * immutable domain value, which is why `NodeRelease` could not be a data class.
- * Here the schedule is a value the caller passes in: phase is a function of
- * `(release, schedule, now)`, and nothing in the model is mutable.
+ * The schedule is a value the caller passes in: phase is a function of
+ * `(release, schedule, now)`, so nothing in the model is mutable and
+ * {@link NodeRelease} stays a plain data class.
  *
  * @example
  * ```ts
@@ -655,17 +665,15 @@ declare const NodeRelease_base: Schema.Class<NodeRelease, Schema.Struct<{
   readonly date: Schema.DateTimeUtc;
 }>, {}>;
 /**
- * One Node.js release.
+ * One published Node.js release: its version, bundled npm version and release date.
  *
- * Unlike its v3 ancestor this is an ordinary immutable value. v3's `NodeRelease`
- * carried a `Ref<NodeSchedule>` so that `release.phase()` could reach the
- * schedule, which meant every release held shared mutable state and could not be
- * a data class at all. Phase is now a question you ask *with* a schedule rather
- * than a property the release drags around.
+ * An ordinary immutable value. Phase is a question you ask *with* a schedule
+ * (`release.phase(schedule, now)`) rather than a property the release carries.
  *
  * @example
  * ```ts
  * import { NodeRelease, NodeSchedule } from "@effected/runtimes";
+ * import { SemVer } from "@effected/semver";
  * import { DateTime, Effect } from "effect";
  *
  * const program = Effect.gen(function* () {
@@ -726,10 +734,19 @@ export declare const NodeResolverOptions: Schema.Struct<{
  */
 export type NodeResolverOptions = typeof NodeResolverOptions.Type;
 declare const NodeResolver_base: Context.ServiceClass<NodeResolver, "@effected/runtimes/NodeResolver", {
+  /** Resolve a range to the matching versions, newest first. */
   readonly resolve: (options?: NodeResolverOptions) => Effect.Effect<ResolvedVersions, InvalidRangeError | NoMatchingVersionError | UnresolvableDefaultError | FreshnessError>;
 }>;
 /**
- * The Node.js resolver.
+ * Resolves a semver range to concrete Node.js versions, filtered by lifecycle
+ * phase, with release data from the nodejs.org feeds or a bundled snapshot.
+ *
+ * @remarks
+ * Choose a strategy with the layer: `layer` tries the live feeds and falls back
+ * to the snapshot (recorded as `source: "cache"`), `layerFresh` fails rather
+ * than fall back, and `layerOffline` uses only the snapshot. `resolve` fails
+ * with `InvalidRangeError`, `NoMatchingVersionError`, `UnresolvableDefaultError`
+ * or `FreshnessError`.
  *
  * @example
  * ```ts

package/internal/feeds.js

@@ -62,8 +62,7 @@ const buildNodeReleases = (raw) => Effect.gen(function* () {
 /**
 * Fetch a runtime's releases from GitHub, dropping drafts and prereleases.
 *
-* Bun and Deno differ by a repository name and a tag prefix. v3 had two fetcher
-* services, two service files and two `*Live` layers for that difference.
+* Bun and Deno differ only by a repository name and a tag prefix.
 */
 const fetchGitHubReleases = (client, owner, repo) => client.listReleases(owner, repo).pipe(Effect.map((releases) => releases.filter((release) => !release.draft && !release.prerelease).flatMap((release) => {
 	const date = release.published_at;

package/internal/once.js

@@ -2,33 +2,6 @@ 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.
 */

package/internal/strategy.js

@@ -3,22 +3,6 @@ import { Effect } from "effect";
 
 //#region src/internal/strategy.ts
 /**
-* The three cache strategies, parameterized once.
-*
-* v3 shipped nine layer files for this: {auto, fresh, offline} × {node, bun,
-* deno}, where the Bun and Deno "fresh" layers differed by a repository name.
-* The strategy is a property of *how the index is populated*, not of which
-* runtime it holds, so it is one function per strategy taking a loader.
-*
-* Each is typed exactly, which is the point: `offline` requires nothing and
-* cannot fail, `auto` requires the feed but still cannot fail, and only `fresh`
-* carries a `FreshnessError`. A single function switching on a kind would union
-* all three channels together and force every layer to advertise failures it
-* cannot have.
-*
-* @internal
-*/
-/**
 * Load the bundled snapshot. No IO, no failure, no requirements.
 */
 const populateOffline = (index, offline) => offline.pipe(Effect.flatMap((releases) => index.load(releases, "cache")));
@@ -36,8 +20,7 @@ const populateFresh = (index, runtime, live) => live.pipe(Effect.mapError((cause
 * Try the live feed; fall back to the bundled snapshot.
 *
 * The fallback is **visible**: provenance becomes `"cache"` and a warning is
-* logged. v3 fell back silently and then reported the result as `source: "api"`,
-* so a caller had no way to tell a live answer from a stale one served after a
+* logged, so a caller can tell a live answer from a stale one served after a
 * network failure.
 */
 const populateAuto = (index, runtime, live, offline) => live.pipe(Effect.flatMap((releases) => index.load(releases, "api")), Effect.catch((cause) => Effect.gen(function* () {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/runtimes",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"private": false,
 	"description": "Resolve semver-compatible Node.js, Bun and Deno runtime versions with offline fallback.",
 	"keywords": [
@@ -40,10 +40,10 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/semver": "^0.10.0"
+		"@effected/semver": "^0.11.0"
 	},
 	"peerDependencies": {
-		"effect": "4.0.0-rc.118"
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"