@effected/runtimes 0.1.0

package/internal/feeds.js

@@ -0,0 +1,84 @@
+import { getJson } from "./http.js";
+import { mapHttpFailure } from "../GitHub.js";
+import { NodeRelease } from "../NodeRelease.js";
+import { SemVer } from "@effected/semver";
+import { Effect, Option, Schema } from "effect";
+
+//#region src/internal/feeds.ts
+const NODE_DIST_URL = "https://nodejs.org/dist/index.json";
+const NODE_SCHEDULE_URL = "https://raw.githubusercontent.com/nodejs/Release/refs/heads/main/schedule.json";
+/** The subset of nodejs.org's dist index this package reads. */
+const NodeDistIndex = Schema.Array(Schema.Struct({
+	version: Schema.String,
+	date: Schema.String,
+	npm: Schema.optionalKey(Schema.Union([Schema.String, Schema.Boolean]))
+}));
+const NodeScheduleFeed = 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);
+/**
+* Parse a version string, yielding `None` rather than failing.
+*
+* The feeds carry tags this package cannot and need not understand (release
+* candidates, `bun-v1.0.0-canary`, ancient `0.0.0-N` Deno tags). One of them is
+* not a reason to fail the whole load; it is a reason to skip that entry.
+*/
+const tryParseSemVer = (raw) => SemVer.parse(raw).pipe(Effect.map(Option.some), Effect.catchTag("InvalidVersionError", () => Effect.succeed(Option.none())));
+const tryParseDate = (raw) => decodeDate(raw).pipe(Effect.map(Option.some), Effect.catch(() => Effect.succeed(Option.none())));
+/** Strip a leading `v` or `bun-v` from a tag name. */
+const stripTagPrefix = (tag) => {
+	const withoutBun = tag.startsWith("bun-") ? tag.slice(4) : tag;
+	return withoutBun.startsWith("v") || withoutBun.startsWith("V") ? withoutBun.slice(1) : withoutBun;
+};
+/** Fetch nodejs.org's dist index. Unauthenticated — this is not a GitHub API. */
+const fetchNodeReleases = () => getJson(NODE_DIST_URL, NodeDistIndex).pipe(Effect.mapError((failure) => mapHttpFailure(failure, "anonymous")), Effect.map((entries) => entries.map((entry) => ({
+	version: entry.version.replace(/^v/, ""),
+	npm: typeof entry.npm === "string" ? entry.npm : "0.0.0",
+	date: entry.date
+}))));
+/** Fetch the `nodejs/Release` schedule. Also unauthenticated: raw.githubusercontent.com. */
+const fetchNodeSchedule = () => getJson(NODE_SCHEDULE_URL, NodeScheduleFeed).pipe(Effect.mapError((failure) => mapHttpFailure(failure, "anonymous")));
+/** Build Node releases, skipping entries this package cannot parse. */
+const buildNodeReleases = (raw) => Effect.forEach(raw, (entry) => Effect.gen(function* () {
+	const version = yield* tryParseSemVer(entry.version);
+	const npm = yield* tryParseSemVer(entry.npm);
+	const date = yield* tryParseDate(entry.date);
+	if (Option.isNone(version) || Option.isNone(npm) || Option.isNone(date)) return Option.none();
+	return Option.some(NodeRelease.make({
+		version: version.value,
+		npm: npm.value,
+		date: date.value
+	}));
+})).pipe(Effect.map((results) => results.flatMap(Option.toArray)));
+/**
+* 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.
+*/
+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;
+	if (date === null) return [];
+	return [{
+		version: stripTagPrefix(release.tag_name),
+		date
+	}];
+})));
+/** Build a release list of `{ version, date }` records, skipping unparseable entries. */
+const buildReleases = (raw, make) => Effect.forEach(raw, (entry) => Effect.gen(function* () {
+	const version = yield* tryParseSemVer(entry.version);
+	const date = yield* tryParseDate(entry.date);
+	if (Option.isNone(version) || Option.isNone(date)) return Option.none();
+	return Option.some(make({
+		version: version.value,
+		date: date.value
+	}));
+})).pipe(Effect.map((results) => results.flatMap(Option.toArray)));
+
+//#endregion
+export { buildNodeReleases, buildReleases, fetchGitHubReleases, fetchNodeReleases, fetchNodeSchedule, stripTagPrefix, tryParseSemVer };

package/internal/githubRuntime.js

@@ -0,0 +1,43 @@
+import { GitHubClient } from "../GitHub.js";
+import { buildReleases, fetchGitHubReleases } from "./feeds.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.
+*
+* 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.
+*/
+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* () {
+			return yield* buildReleases(yield* fetchGitHubReleases(yield* GitHubClient, owner, repo), make$1);
+		}), buildReleases(defaults, make$1));
+		return { resolve: Effect.fn(spanName)(function* (options) {
+			const range = options?.range ?? "*";
+			yield* Effect.annotateCurrentSpan({
+				runtime,
+				range
+			});
+			return yield* resolveWith({
+				index,
+				runtime,
+				constraint: range,
+				increments: options?.increments ?? "latest",
+				defaultVersion: options?.defaultVersion,
+				defaultsToLts: false,
+				refine: (releases) => releases,
+				pickLts: () => Option.none()
+			});
+		}) };
+	}));
+};
+
+//#endregion
+export { build };

package/internal/http.js

@@ -0,0 +1,127 @@
+import { Duration, Effect, Schedule } from "effect";
+import { HttpClient } from "effect/unstable/http";
+import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+
+//#region src/internal/http.ts
+const parseHeaderInt = (raw) => {
+	if (raw === void 0) return void 0;
+	const n = Number.parseInt(raw, 10);
+	return Number.isInteger(n) ? n : void 0;
+};
+/**
+* A `retry-after` is a number a remote server chose, so it is bounded before it
+* becomes a sleep. Without this a misconfigured — or hostile — server parks the
+* caller's fiber for as long as it likes by sending one large header. A negative
+* value is discarded outright.
+*/
+const MAX_RETRY_AFTER_SECONDS = 60;
+const parseRetryAfter = (raw) => {
+	const seconds = parseHeaderInt(raw);
+	return seconds === void 0 || seconds < 0 ? void 0 : seconds;
+};
+/**
+* Map an HTTP status onto the failure ladder.
+*
+* 401 is an authentication problem and 429 is definitionally a rate limit. 403
+* is the one that has to be classified rather than assumed: GitHub returns it
+* for an exhausted rate limit, but *also* for permission and resource failures
+* ("Resource not accessible by personal access token"), which no amount of
+* backoff will fix. Treating every 403 as a rate limit retries those three times
+* and then reports a `RateLimitError` naming a quota that was never the problem.
+*
+* The two signals GitHub documents for a rate limit are the primary limit's
+* `x-ratelimit-remaining: 0` and the secondary limit's `retry-after`. A 403 with
+* neither is a permission failure, and it leaves as a `NetworkError` carrying the
+* status rather than being retried.
+*/
+const failureForStatus = (url, status, headers) => {
+	if (status === 401) return { _kind: "auth" };
+	if (status === 403 || status === 429) {
+		const remaining = parseHeaderInt(headers["x-ratelimit-remaining"]);
+		const retryAfter = parseRetryAfter(headers["retry-after"]);
+		if (status === 429 || remaining === 0 || retryAfter !== void 0) return {
+			_kind: "rateLimit",
+			...retryAfter !== void 0 ? { retryAfter } : {},
+			limit: parseHeaderInt(headers["x-ratelimit-limit"]) ?? 0,
+			remaining: remaining ?? 0
+		};
+	}
+	return {
+		_kind: "network",
+		url,
+		status,
+		cause: `HTTP ${status}`
+	};
+};
+/**
+* GET a URL and decode its JSON body with `schema`.
+*
+* Every failure mode — transport, status, malformed body — leaves through the
+* typed channel as an {@link HttpFailure}. Nothing throws.
+*/
+const getJson = (url, schema, headers = {}) => Effect.gen(function* () {
+	const response = yield* (yield* HttpClient.HttpClient).get(url, { headers }).pipe(Effect.mapError((cause) => ({
+		_kind: "network",
+		url,
+		cause
+	})));
+	if (response.status < 200 || response.status >= 300) return yield* Effect.fail(failureForStatus(url, response.status, response.headers));
+	return yield* HttpClientResponse.schemaBodyJson(schema)(response).pipe(Effect.mapError((cause) => ({
+		_kind: "parse",
+		source: url,
+		cause
+	})));
+});
+/**
+* Exponential backoff, overridden by the server's own `retry-after` when it sent
+* one.
+*
+* GitHub tells you how long to wait for a secondary rate limit, and guessing
+* `1s, 2s, 4s` against that is both ruder and less effective than doing as it
+* asked. `Schedule.passthrough` re-types the schedule's output as its *input* —
+* the failure — which is what lets `modifyDelay` see the `retryAfter` that the
+* failure is carrying and replace the computed delay with it.
+*/
+const rateLimitBackoff = Schedule.exponential("1 second").pipe(Schedule.setInputType(), Schedule.passthrough, Schedule.modifyDelay(({ duration, output: failure }) => Effect.succeed(failure._kind === "rateLimit" && failure.retryAfter !== void 0 ? Duration.seconds(Math.min(failure.retryAfter, MAX_RETRY_AFTER_SECONDS)) : duration)));
+/**
+* Retry a rate-limited effect, honoring the server's backoff.
+*
+* Only `rateLimit` failures are retried — an auth failure, a permission failure
+* or a malformed body will not fix itself, and retrying them just burns the
+* caller's quota.
+*/
+const retryOnRateLimit = (effect) => effect.pipe(Effect.retry({
+	schedule: rateLimitBackoff,
+	times: 3,
+	while: (failure) => failure._kind === "rateLimit"
+}));
+/**
+* Validate a caller-supplied numeric bound.
+*
+* `if (n < 1)` is the obvious spelling and it is wrong twice over: every
+* relational comparison against `NaN` is `false`, so `NaN` sails through, and
+* so does `2.5`. Both are developer wiring errors rather than data conditions,
+* so they die rather than entering the typed channel.
+*/
+const requirePositiveInteger = (name, value) => Number.isInteger(value) && value >= 1 ? Effect.succeed(value) : Effect.die(/* @__PURE__ */ new Error(`${name} must be a positive integer, received ${value}`));
+/**
+* Walk a paginated listing, decoding each page and stopping at a short page.
+*
+* Pagination is bounded in two places: the caller's `pages` (validated) and a
+* hard {@link PAGE_CEILING}, so a remote server cannot drive an unbounded loop.
+*/
+const paginate = (url, schema, headers, options = {}) => Effect.gen(function* () {
+	const perPage = yield* requirePositiveInteger("perPage", options.perPage ?? 100);
+	const requested = yield* requirePositiveInteger("pages", options.pages ?? 5);
+	const maxPages = Math.min(requested, 100);
+	const all = [];
+	for (let page = 1; page <= maxPages; page++) {
+		const items = yield* retryOnRateLimit(getJson(url(page, perPage), schema, headers));
+		all.push(...items);
+		if (items.length < perPage) break;
+	}
+	return all;
+});
+
+//#endregion
+export { getJson, paginate, retryOnRateLimit };

package/internal/releaseIndex.js

@@ -0,0 +1,46 @@
+import { Effect, Option, Ref } from "effect";
+
+//#region src/internal/releaseIndex.ts
+/** Newest first. */
+const byVersionDescending = (releases) => [...releases].sort((a, b) => b.version.compare(a.version));
+/**
+* Build an empty index.
+*
+* The index starts empty and `"cache"`: an index nobody loaded has certainly
+* not been served from an API.
+*/
+const make = () => Effect.gen(function* () {
+	const state = yield* Ref.make({
+		releases: [],
+		source: "cache"
+	});
+	const filter = (range) => Ref.get(state).pipe(Effect.map(({ releases }) => releases.filter((r) => range.test(r.version))));
+	return {
+		load: (releases, source) => Ref.set(state, {
+			releases: byVersionDescending(releases),
+			source
+		}),
+		releases: Ref.get(state).pipe(Effect.map(({ releases }) => releases)),
+		source: Ref.get(state).pipe(Effect.map(({ source }) => source)),
+		filter,
+		resolve: (range) => filter(range).pipe(Effect.map((matches) => Option.fromUndefinedOr(matches[0])))
+	};
+});
+/**
+* Collapse releases to one per major, one per minor, or leave every patch.
+*
+* Input is newest-first, so the first release seen for a group key is that
+* group's winner and later ones are older — no comparison needed.
+*/
+const groupByIncrements = (releases, increments) => {
+	if (increments === "patch") return releases;
+	const seen = /* @__PURE__ */ new Map();
+	for (const release of releases) {
+		const key = increments === "latest" ? String(release.version.major) : `${release.version.major}.${release.version.minor}`;
+		if (!seen.has(key)) seen.set(key, release);
+	}
+	return [...seen.values()];
+};
+
+//#endregion
+export { groupByIncrements, make };

package/internal/resolve.js

@@ -0,0 +1,44 @@
+import { groupByIncrements } from "./releaseIndex.js";
+import { NoMatchingVersionError, ResolvedVersions, UnresolvableDefaultError } from "../ResolvedVersions.js";
+import { Range } from "@effected/semver";
+import { Effect, Option } from "effect";
+
+//#region src/internal/resolve.ts
+/**
+* Filter, group, rank and package a resolution.
+*
+* `refine` is where Node's phase filter plugs in; Bun and Deno pass everything
+* through. `pickLts` likewise: only Node has an LTS notion.
+*/
+const resolveWith = (args) => Effect.gen(function* () {
+	const { index, runtime, constraint, increments, defaultVersion, refine, pickLts, defaultsToLts, phases } = args;
+	const range = yield* Range.parse(constraint);
+	const grouped = groupByIncrements(refine(yield* index.filter(range)), increments);
+	if (grouped.length === 0) return yield* new NoMatchingVersionError({
+		runtime,
+		constraint,
+		...phases !== void 0 ? { phases } : {}
+	});
+	const versions = grouped.map((release) => release.version.toString());
+	const lts = pickLts(grouped).pipe(Option.map((release) => release.version.toString()));
+	const chosenDefault = yield* Option.match(Option.fromUndefinedOr(defaultVersion), {
+		onNone: () => Effect.succeed(defaultsToLts ? lts : Option.none()),
+		onSome: (raw) => Range.parse(raw).pipe(Effect.flatMap((defaultRange) => index.resolve(defaultRange)), Effect.flatMap(Option.match({
+			onNone: () => Effect.fail(new UnresolvableDefaultError({
+				runtime,
+				defaultVersion: raw
+			})),
+			onSome: (release) => Effect.succeed(Option.some(release.version.toString()))
+		})))
+	});
+	return ResolvedVersions.make({
+		source: yield* index.source,
+		versions,
+		latest: versions[0],
+		...Option.isSome(lts) ? { lts: lts.value } : {},
+		...Option.isSome(chosenDefault) ? { default: chosenDefault.value } : {}
+	});
+});
+
+//#endregion
+export { resolveWith };

package/internal/strategy.js

@@ -0,0 +1,53 @@
+import { FreshnessError } from "../ResolvedVersions.js";
+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")));
+/**
+* Live data or a typed failure.
+*
+* The caller chose this strategy to say that a snapshot is not an acceptable
+* substitute, so the feed's failure becomes theirs.
+*/
+const populateFresh = (index, runtime, live) => live.pipe(Effect.mapError((cause) => new FreshnessError({
+	runtime,
+	cause
+})), Effect.flatMap((releases) => index.load(releases, "api")));
+/**
+* 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
+* network failure.
+*/
+const populateAuto = (index, runtime, live, offline) => live.pipe(Effect.flatMap((releases) => index.load(releases, "api")), Effect.catch((cause) => Effect.gen(function* () {
+	yield* Effect.logWarning("Live release feed unavailable; falling back to the bundled snapshot", {
+		runtime,
+		cause
+	});
+	const releases = yield* offline;
+	yield* index.load(releases, "cache");
+})));
+
+//#endregion
+export { populateAuto, populateFresh, populateOffline };

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@effected/runtimes",
+	"version": "0.1.0",
+	"private": false,
+	"description": "Resolve semver-compatible Node.js, Bun and Deno runtime versions with offline fallback.",
+	"keywords": [
+		"node",
+		"bun",
+		"deno",
+		"runtime",
+		"version",
+		"semver",
+		"resolver",
+		"effect",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/runtimes#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/runtimes"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"dependencies": {
+		"@effected/semver": "0.1.0"
+	},
+	"peerDependencies": {
+		"effect": "4.0.0-beta.98"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.9"
+    }
+  ]
+}