@effected/runtimes 0.1.0

package/NodeSchedule.js

@@ -0,0 +1,217 @@
+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.
+* - `active-lts` — Long-Term Support: bug and security fixes only.
+* - `maintenance-lts` — critical security fixes only.
+* - `end-of-life` — no longer maintained.
+*
+* @public
+*/
+const NodePhase = Schema.Literals([
+	"current",
+	"active-lts",
+	"maintenance-lts",
+	"end-of-life"
+]);
+/**
+* A date in the release schedule could not be understood.
+*
+* Raised when `nodejs/Release` publishes a `schedule.json` whose dates this
+* package cannot parse — an operator-facing signal that the upstream feed
+* changed shape, not something a caller can recover from.
+*
+* @public
+*/
+var InvalidScheduleDateError = class extends Schema.TaggedErrorClass()("InvalidScheduleDateError", {
+	/** The schedule key whose entry failed, e.g. `"v20"`. */
+	key: Schema.String,
+	/** The field that failed, e.g. `"start"`. */
+	field: Schema.String,
+	/** The value that could not be parsed. */
+	value: Schema.String
+}) {};
+/**
+* The release-line key a version belongs to.
+*
+* Node's early history is the whole reason this exists. `nodejs/Release`
+* publishes `v0.8`, `v0.10` and `v0.12` as three *separate* release lines with
+* their own start and end dates — the major number does not identify them.
+* Everything from `v4` on is keyed by the major alone.
+*
+* @example
+* ```ts
+* import { nodeReleaseLine } from "@effected/runtimes";
+*
+* nodeReleaseLine({ major: 20, minor: 11 }); // "20"
+* nodeReleaseLine({ major: 0, minor: 12 });  // "0.12"
+* ```
+*
+* @public
+*/
+const nodeReleaseLine = (version) => version.major === 0 ? `0.${version.minor ?? 0}` : String(version.major);
+/**
+* One release line's lifecycle dates.
+*
+* @public
+*/
+var NodeScheduleEntry = class extends Schema.Class("NodeScheduleEntry")({
+	/**
+	* The release line as `nodejs/Release` keys it, without the `v`: `"20"`, or
+	* `"0.10"` for the three dotted early lines.
+	*/
+	line: Schema.String,
+	/** The Node.js major version number, e.g. `20`. `0` for every `0.x` line. */
+	major: Schema.Number,
+	/** The minor, for the `0.x` lines that are each their own release line. */
+	minor: Schema.optionalKey(Schema.Number),
+	/** When the line was first released. */
+	start: Schema.DateTimeUtc,
+	/** When the line entered Active LTS, absent if it never does (odd majors). */
+	lts: Schema.optionalKey(Schema.DateTimeUtc),
+	/** When the line entered Maintenance LTS. */
+	maintenance: Schema.optionalKey(Schema.DateTimeUtc),
+	/** When the line reaches end of life. */
+	end: Schema.DateTimeUtc,
+	/** The LTS codename, e.g. `"Iron"`. Empty for lines that never got one. */
+	codename: Schema.String
+}) {};
+/**
+* The raw shape of `schedule.json` as `nodejs/Release` publishes it: a map of
+* `"vNN"` to ISO date strings.
+*
+* @public
+*/
+const NodeScheduleData = Schema.Record(Schema.String, Schema.Struct({
+	start: Schema.String,
+	lts: Schema.optionalKey(Schema.String),
+	maintenance: Schema.optionalKey(Schema.String),
+	end: Schema.String,
+	codename: Schema.optionalKey(Schema.String)
+}));
+const decodeDate = Schema.decodeUnknownEffect(Schema.DateTimeUtcFromString);
+const parseDate = (key, field, value) => decodeDate(value).pipe(Effect.mapError(() => new InvalidScheduleDateError({
+	key,
+	field,
+	value
+})));
+/**
+* Ascending by major, then by minor within the `0.x` lines — so `v0.8` sorts
+* before `v0.10`, which a plain string or major-only comparison would not do.
+*/
+const byLine = Order.combine(Order.mapInput(Order.Number, (entry) => entry.major), Order.mapInput(Order.Number, (entry) => entry.minor ?? 0));
+/** `"v20"` or `"v0.10"`, and nothing else — the file has carried other keys. */
+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.
+*
+* @example
+* ```ts
+* import { NodeSchedule } from "@effected/runtimes";
+* import { DateTime, Effect, Option } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const schedule = yield* NodeSchedule.fromData({
+*     v20: { start: "2023-04-18", lts: "2023-10-24", end: "2026-04-30" },
+*   });
+*   const phase = schedule.phaseFor({ major: 20 }, DateTime.makeUnsafe("2024-01-01"));
+*   return Option.getOrNull(phase); // "active-lts"
+* });
+* ```
+*
+* @public
+*/
+var NodeSchedule = class NodeSchedule extends Schema.Class("NodeSchedule")({ 
+/** The known release lines, ascending by major. */
+entries: Schema.Array(NodeScheduleEntry) }) {
+	/**
+	* A schedule that knows nothing.
+	*
+	* `phaseFor` returns `Option.none()` for every major, which is the correct
+	* answer before a schedule has been loaded.
+	*/
+	static empty = NodeSchedule.make({ entries: [] });
+	/**
+	* Parse the raw `schedule.json` shape into a schedule.
+	*
+	* Keys that are not of the form `"vNN"` are skipped — the upstream file has
+	* historically carried non-version keys, and one of them is not a reason to
+	* fail the whole schedule. A key that *is* a version but whose dates do not
+	* parse fails with {@link InvalidScheduleDateError}.
+	*/
+	static fromData = Effect.fn("NodeSchedule.fromData")(function* (data) {
+		const entries = [];
+		for (const [key, value] of Object.entries(data)) {
+			const match = SCHEDULE_KEY.exec(key);
+			if (match === null) continue;
+			const major = Number(match[1]);
+			const minor = match[2] === void 0 ? void 0 : Number(match[2]);
+			const start = yield* parseDate(key, "start", value.start);
+			const end = yield* parseDate(key, "end", value.end);
+			const lts = value.lts === void 0 ? void 0 : yield* parseDate(key, "lts", value.lts);
+			const maintenance = value.maintenance === void 0 ? void 0 : yield* parseDate(key, "maintenance", value.maintenance);
+			entries.push(NodeScheduleEntry.make({
+				line: nodeReleaseLine({
+					major,
+					minor
+				}),
+				major,
+				start,
+				end,
+				codename: value.codename ?? "",
+				...minor !== void 0 ? { minor } : {},
+				...lts !== void 0 ? { lts } : {},
+				...maintenance !== void 0 ? { maintenance } : {}
+			}));
+		}
+		return NodeSchedule.make({ entries: entries.sort(byLine) });
+	});
+	/**
+	* The schedule entry for a version's release line, if the schedule knows it.
+	*/
+	entryFor(version) {
+		const line = nodeReleaseLine(version);
+		return Option.fromUndefinedOr(this.entries.find((entry) => entry.line === line));
+	}
+	/**
+	* The lifecycle phase of a version's release line at a point in time.
+	*
+	* `now` is an explicit parameter rather than a read of the wall clock, which
+	* is what makes every phase transition testable without mocking time.
+	*
+	* Returns `Option.none()` when the schedule does not know the line, or when
+	* `now` is before the line was released — an unreleased line has no phase.
+	*/
+	phaseFor(version, now) {
+		return this.entryFor(version).pipe(Option.flatMap((entry) => {
+			if (DateTime.isLessThan(now, entry.start)) return Option.none();
+			if (DateTime.isGreaterThanOrEqualTo(now, entry.end)) return Option.some("end-of-life");
+			if (entry.maintenance !== void 0 && DateTime.isGreaterThanOrEqualTo(now, entry.maintenance)) return Option.some("maintenance-lts");
+			if (entry.lts !== void 0 && DateTime.isGreaterThanOrEqualTo(now, entry.lts)) return Option.some("active-lts");
+			return Option.some("current");
+		}));
+	}
+};
+/**
+* Whether a phase counts as Long-Term Support.
+*
+* @public
+*/
+const isLtsPhase = (phase) => phase === "active-lts" || phase === "maintenance-lts";
+
+//#endregion
+export { InvalidScheduleDateError, NodePhase, NodeSchedule, NodeScheduleData, NodeScheduleEntry, isLtsPhase, nodeReleaseLine };

package/README.md

@@ -0,0 +1,155 @@
+# @effected/runtimes
+
+[![npm](https://img.shields.io/npm/v/@effected%2Fruntimes?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/runtimes)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+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 beta. Packages graduate to
+> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
+> exactly the ones the kit is built and tested against, install
+> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
+>
+> **Stability: unstable.** This package's API surface is not yet considered
+> complete and may change across `0.x` releases. Pin an exact version — even a
+> package marked *stable* before `1.0.0` can introduce a breaking change by
+> accident, and an exact pin turns that into a type-check error rather than a
+> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Why @effected/runtimes
+
+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.
+
+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.
+
+## Install
+
+```bash
+npm install @effected/runtimes effect
+```
+
+```bash
+pnpm add @effected/runtimes effect
+```
+
+Requires Node.js >=24.11.0.
+
+`effect` v4 is the only peer dependency. `@effected/semver` is a regular dependency and comes along automatically; nothing else reaches your tree.
+
+Live resolution needs an `HttpClient`, provided at the edge with `FetchHttpClient.layer` from `effect/unstable/http` — that layer has no requirements of its own, so it works anywhere `fetch` does. If you only ever use `layerOffline`, you need no HTTP client at all.
+
+The command-line interface ships as a separate package, so this package's consumers never install `@effect/platform-node`.
+
+## Quick start
+
+```ts
+import { NodeResolver } from "@effected/runtimes";
+import { Effect } from "effect";
+import { FetchHttpClient } from "effect/unstable/http";
+
+const program = Effect.gen(function* () {
+  const node = yield* NodeResolver;
+  return yield* node.resolve({ range: ">=20", phases: ["active-lts"] });
+});
+
+Effect.runPromise(program.pipe(Effect.provide(NodeResolver.layer), Effect.provide(FetchHttpClient.layer))).then(
+  console.log,
+);
+// ResolvedVersions {
+//   source: "api",          // "cache" if the feed was unreachable and the snapshot answered
+//   versions: [...],        // every active-LTS Node matching >=20, newest first
+//   latest: "...",          // the newest of them
+//   lts: "..."              // the newest LTS pick
+// }
+```
+
+No credentials are needed for Node: both feeds it reads — nodejs.org's release index and the `nodejs/Release` schedule — are unauthenticated.
+
+## Cache strategy as layer
+
+Each of the three resolvers exposes the same three layer **constants**:
+
+| Layer | Behavior | 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 |
+
+The transport differs by runtime, and that is not an accident:
+
+| Resolver | Feed | Requires |
+| -------- | ---- | -------- |
+| `NodeResolver` | nodejs.org's release index and the `nodejs/Release` schedule — both unauthenticated | `HttpClient` |
+| `BunResolver` | GitHub releases for `oven-sh/bun` | `GitHubClient` |
+| `DenoResolver` | GitHub releases for `denoland/deno` | `GitHubClient` |
+
+`GitHubClient.layerDefault` is the batteries-included wiring: environment-detected credentials over `fetch`. Credential precedence is `GITHUB_PERSONAL_ACCESS_TOKEN`, then `GITHUB_TOKEN`, then anonymous — GitHub allows anonymous requests at a much lower rate limit. Supply your own with `GitHubAuth.token(redactedToken)`, or use `GitHubClient.layer` directly to bring both a credential and a transport:
+
+```ts
+import { BunResolver, DenoResolver, GitHubClient, NodeResolver } from "@effected/runtimes";
+import { Layer } from "effect";
+import { FetchHttpClient } from "effect/unstable/http";
+
+export const ResolversLive = Layer.mergeAll(
+  NodeResolver.layer.pipe(Layer.provide(FetchHttpClient.layer)),
+  BunResolver.layer.pipe(Layer.provide(GitHubClient.layerDefault)),
+  DenoResolver.layer.pipe(Layer.provide(GitHubClient.layerDefault)),
+);
+```
+
+`GitHubAuth.token` returns a fresh layer per call, so bind it to a const rather than calling it inline twice — layers are memoized by reference. GitHub App authentication (JWT signing plus the installation-token exchange) is deliberately not implemented, because it would mean a runtime dependency: `GitHubAuth` is a pluggable service, and an application that needs App auth supplies its own `Layer<GitHubAuth>`.
+
+## Resolving
+
+`resolve` takes a semver range, a grouping granularity and an optional default range. Node additionally takes the lifecycle phases to accept and the date to evaluate them at:
+
+```ts
+import { NodeResolver } from "@effected/runtimes";
+import { Effect } from "effect";
+
+const program = Effect.gen(function* () {
+  const node = yield* NodeResolver;
+  return yield* node.resolve({
+    range: ">=18",
+    phases: ["active-lts", "maintenance-lts"],
+    increments: "minor",
+    defaultVersion: "^22",
+  });
+}).pipe(Effect.provide(NodeResolver.layerOffline));
+// ResolvedVersions with one entry per minor line, and `default` set to the newest match for ^22.
+```
+
+`increments` groups the matches: `latest` keeps the newest version of each major line, `minor` the newest patch of each minor line, `patch` every matching release. `range` defaults to `*`, `increments` to `latest`, and Node's `phases` to `["current", "active-lts"]`. The phase evaluation date comes from `Clock` via `DateTime.now`, so `TestClock` drives it, and passing `date` pins it explicitly.
+
+The Node schedule is keyed by release *line*, not by major — `nodejs/Release` publishes `v0.8`, `v0.10` and `v0.12` as three distinct lines, and parsing them all down to major `0` collapses them onto whichever came first.
+
+## Errors
+
+| Tag | Means | Recovery |
+| --- | --- | --- |
+| `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. |
+| `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. |
+| `ResponseParseError` | A feed responded, but not with the shape this package expects. Carries `source` and the structural `cause`. | An operator-facing signal that an upstream feed changed. Malformed data fails typed, never as a defect. |
+
+## Features
+
+- `NodeResolver`, `BunResolver`, `DenoResolver` — one service per runtime, each with `layer`, `layerFresh` and `layerOffline`.
+- `ResolvedVersions` — `source`, `versions`, `latest`, and optionally `lts` and `default`. An empty match is an error, not an empty result, so `latest` is always present.
+- `NodeSchedule` / `NodePhase` / `NodeScheduleEntry` — the `nodejs/Release` lifecycle schedule, keyed by release line, with `isLtsPhase` and `nodeReleaseLine` helpers.
+- `GitHubClient` / `GitHubAuth` — a minimal GitHub REST client over `HttpClient`, with anonymous, explicit-token and environment-detected auth layers. Pagination is bounded, and a server-supplied `retry-after` is capped before it becomes a sleep.
+- `BunRelease`, `DenoRelease`, `NodeRelease` — the decoded release models, plus `GitHubTag` and `GitHubRelease` for the REST payloads they are built from.
+- Tagged errors throughout, each carrying its cause structurally.
+
+## License
+
+[MIT](LICENSE)

package/ResolvedVersions.js

@@ -0,0 +1,122 @@
+import { NodePhase } from "./NodeSchedule.js";
+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
+*/
+const Runtime = Schema.Literals([
+	"node",
+	"bun",
+	"deno"
+]);
+/**
+* Where a resolution's release data came from.
+*
+* - `api` — a live fetch of the upstream feed succeeded.
+* - `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.
+*
+* @public
+*/
+const Source = Schema.Literals(["api", "cache"]);
+/**
+* The granularity at which matching versions are grouped.
+*
+* - `latest` — the newest version of each major line.
+* - `minor` — the newest patch of each minor line.
+* - `patch` — every matching release.
+*
+* @public
+*/
+const Increments = Schema.Literals([
+	"latest",
+	"minor",
+	"patch"
+]);
+/**
+* What every resolver returns.
+*
+* @public
+*/
+var ResolvedVersions = class extends Schema.Class("ResolvedVersions")({
+	/** Whether this answer came from a live feed or the bundled snapshot. */
+	source: Source,
+	/** Every matching version, newest first. */
+	versions: Schema.Array(Schema.String),
+	/** The newest matching version. Always present — an empty match is an error, not an empty result. */
+	latest: Schema.String,
+	/** The newest matching LTS version. Node only, and only when one matches. */
+	lts: Schema.optionalKey(Schema.String),
+	/** The version the caller asked to treat as the default, resolved. */
+	default: Schema.optionalKey(Schema.String)
+}) {};
+/**
+* No release matched the constraint.
+*
+* 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
+*/
+var NoMatchingVersionError = class extends Schema.TaggedErrorClass()("NoMatchingVersionError", {
+	/** The runtime that was searched. */
+	runtime: Runtime,
+	/** The semver range that matched nothing. */
+	constraint: Schema.String,
+	/** The lifecycle phases the search was restricted to. Node only. */
+	phases: Schema.optionalKey(Schema.Array(NodePhase))
+}) {};
+/**
+* An explicit `defaultVersion` was asked for and nothing matched it.
+*
+* Distinct from {@link NoMatchingVersionError}, which says the *main* range
+* matched nothing. Here the main range resolved fine and the caller's separate
+* default range did not.
+*
+* It has to be its own failure rather than a silently dropped field. `default`
+* is `optionalKey`, so an unresolvable default could simply be omitted — and for
+* Node, whose default falls back to the LTS pick, the caller would then be handed
+* the LTS version as though they had asked for it. Naming a default that does not
+* exist is a mistake, and it reaches the caller as one.
+*
+* @public
+*/
+var UnresolvableDefaultError = class extends Schema.TaggedErrorClass()("UnresolvableDefaultError", {
+	/** The runtime that was searched. */
+	runtime: Runtime,
+	/** The range the caller asked to treat as the default. */
+	defaultVersion: Schema.String
+}) {};
+/**
+* Fresh data was required and could not be obtained.
+*
+* Raised only by the `layerFresh` strategy, at layer construction: the caller
+* asked for live data and said, by choosing that strategy, that a snapshot is
+* not an acceptable substitute.
+*
+* @public
+*/
+var FreshnessError = class extends Schema.TaggedErrorClass()("FreshnessError", {
+	/** The runtime whose feed could not be reached. */
+	runtime: Runtime,
+	/** The underlying transport or parse failure. */
+	cause: Schema.Defect()
+}) {};
+
+//#endregion
+export { FreshnessError, Increments, NoMatchingVersionError, ResolvedVersions, Runtime, Source, UnresolvableDefaultError };