runtime-resolver 0.1.0 → 0.3.0

package/README.md

@@ -2,20 +2,21 @@
 
 [![npm version](https://img.shields.io/npm/v/runtime-resolver)](https://www.npmjs.com/package/runtime-resolver)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A520-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Effect](https://img.shields.io/badge/Effect-3.x-6644CC)](https://effect.website/)
 
-Resolve semver-compatible versions of Node.js, Bun, and Deno runtimes. Fetches available versions from GitHub with automatic offline fallback via a build-time cache.
+Resolve semver-compatible versions of Node.js, Bun and Deno runtimes. Fetches available versions from GitHub with automatic offline fallback via a build-time cache.
 
 ## Features
 
-- Resolve matching versions for Node.js, Bun, and Deno with a single call
+- Resolve matching versions for Node.js, Bun and Deno with a single call
 - Filter Node.js results by release phase (current, active-lts, maintenance-lts)
 - Control version granularity with increment levels (latest, minor, patch) for all runtimes
-- Resolve a single version from a semver range with `resolveVersion`
-- Control data freshness with `freshness` option (`"auto"`, `"api"`, or `"cache"`)
 - Track data provenance with the `source` field (`"api"` or `"cache"`)
-- Input validation with typed `InvalidInputError` for all resolvers
 - Offline fallback using bundled version data when GitHub is unreachable
 - CLI with structured JSON output for CI/CD pipelines
+- Full Effect API for custom layer composition and typed error handling
 
 ## Installation
 
@@ -37,8 +38,7 @@ const bun = await resolveBun({ semverRange: ">=1.1", increments: "minor" });
 const deno = await resolveDeno({ semverRange: ">=2", increments: "minor" });
 ```
 
-Set a `GITHUB_TOKEN` or `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable
-for authenticated requests. Without one, the resolver falls back to cached data.
+Set a `GITHUB_TOKEN` or `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable for authenticated requests. Without one, the resolver falls back to cached data.
 
 ### CLI
 
@@ -52,64 +52,6 @@ Output is structured JSON with a `$schema` reference for editor auto-complete. P
 npx runtime-resolver --schema
 ```
 
-#### Useful `jq` recipes
-
-```bash
-# Get the latest resolved Node.js version
-npx runtime-resolver --node ">=22" | jq -r '.results.node.latest'
-
-# List all matching versions as plain lines
-npx runtime-resolver --deno ">=2" | jq -r '.results.deno.versions[]'
-
-# Exit non-zero when any runtime fails to resolve
-npx runtime-resolver --node ">=22" --bun "^1" | jq -e '.ok'
-
-# Extract only the LTS version for Node.js
-npx runtime-resolver --node ">=20" --node-phases active-lts | jq -r '.results.node.lts'
-
-# Build a comma-separated matrix for GitHub Actions
-npx runtime-resolver --node ">=20" --increments minor \
-  | jq -r '[.results.node.versions[]] | join(",")'
-```
-
-### Effect API
-
-Power users can compose resolvers with custom layers and typed error handling instead of the Promise wrappers.
-
-```typescript
-import { Effect, Layer } from "effect";
-import {
-  NodeResolver,
-  NodeResolverLive,
-  GitHubClientLive,
-  GitHubTokenAuth,
-  VersionCacheLive,
-} from "runtime-resolver";
-
-const program = Effect.gen(function* () {
-  const resolver = yield* NodeResolver;
-  return yield* resolver.resolve({
-    semverRange: ">=22",
-    phases: ["active-lts"],
-  });
-});
-
-const layer = NodeResolverLive.pipe(
-  Layer.provide(Layer.merge(
-    GitHubClientLive.pipe(Layer.provide(GitHubTokenAuth)),
-    VersionCacheLive,
-  )),
-);
-
-Effect.runPromise(program.pipe(Effect.provide(layer)));
-```
-
-All services (`NodeResolver`, `BunResolver`, `DenoResolver`, `GitHubClient`,
-`VersionCache`), live layers, auth layers (`GitHubTokenAuth`, `GitHubAppAuth`,
-`GitHubAutoAuth`), and typed errors (`AuthenticationError`, `NetworkError`,
-`RateLimitError`, `VersionNotFoundError`, etc.) are exported from the package
-root.
-
 ## Documentation
 
 For configuration, API reference, and advanced usage, see [docs](./docs/).

package/bin/runtime-resolver.js

@@ -1,13 +1,23 @@
 #!/usr/bin/env node
 import { Command, Options } from "@effect/cli";
 import { NodeContext, NodeRuntime } from "@effect/platform-node";
+import { Cause, Console, Effect, Layer, Option } from "effect";
 import { readFileSync } from "node:fs";
-import { BunResolver, Console, NodeResolverLive, Layer, GitHubAppAuth, GitHubAutoAuth, BunResolverLive, DenoResolverLive, GitHubClientLive, Cause, Effect, GitHubTokenAuthFromToken, VersionCacheLive, Option, NodeResolver, DenoResolver } from "../969.js";
+import { NodeScheduleFetcherLive, AutoDenoCacheLive, DenoVersionFetcherLive, AutoNodeCacheLive, BunResolver, NodeResolver, NodeVersionFetcherLive, NodeResolverLive, GitHubAutoAuth, BunResolverLive, BunVersionFetcherLive, GitHubClientLive, DenoResolverLive, GitHubTokenAuthFromToken, GitHubAppAuth, AutoBunCacheLive, DenoResolver } from "../711.js";
 const GitHubLayer = GitHubClientLive.pipe(Layer.provide(GitHubAutoAuth));
-const SharedLayer = Layer.merge(GitHubLayer, VersionCacheLive);
-const NodeLayer = NodeResolverLive.pipe(Layer.provide(SharedLayer));
-const BunLayer = BunResolverLive.pipe(Layer.provide(SharedLayer));
-const DenoLayer = DenoResolverLive.pipe(Layer.provide(SharedLayer));
+const makeNodeLayer = (authOverride)=>{
+    const ghLayer = authOverride ? GitHubClientLive.pipe(Layer.provide(authOverride)) : GitHubLayer;
+    const fetchersLayer = Layer.merge(NodeVersionFetcherLive.pipe(Layer.provide(ghLayer)), NodeScheduleFetcherLive.pipe(Layer.provide(ghLayer)));
+    return NodeResolverLive.pipe(Layer.provide(AutoNodeCacheLive.pipe(Layer.provide(fetchersLayer))));
+};
+const makeBunLayer = (authOverride)=>{
+    const ghLayer = authOverride ? GitHubClientLive.pipe(Layer.provide(authOverride)) : GitHubLayer;
+    return BunResolverLive.pipe(Layer.provide(AutoBunCacheLive.pipe(Layer.provide(BunVersionFetcherLive.pipe(Layer.provide(ghLayer))))));
+};
+const makeDenoLayer = (authOverride)=>{
+    const ghLayer = authOverride ? GitHubClientLive.pipe(Layer.provide(authOverride)) : GitHubLayer;
+    return DenoResolverLive.pipe(Layer.provide(AutoDenoCacheLive.pipe(Layer.provide(DenoVersionFetcherLive.pipe(Layer.provide(ghLayer))))));
+};
 const SCHEMA_URL = "https://raw.githubusercontent.com/spencerbeggs/runtime-resolver/main/runtime-resolver.schema.json";
 const nodeOption = Options.text("node").pipe(Options.optional);
 const bunOption = Options.text("bun").pipe(Options.optional);
@@ -17,7 +27,6 @@ const incrementsOption = Options.text("increments").pipe(Options.optional);
 const nodeDefaultOption = Options.text("node-default").pipe(Options.optional);
 const bunDefaultOption = Options.text("bun-default").pipe(Options.optional);
 const denoDefaultOption = Options.text("deno-default").pipe(Options.optional);
-const freshnessOption = Options.text("freshness").pipe(Options.optional);
 const nodeDateOption = Options.text("node-date").pipe(Options.optional);
 const prettyOption = Options.boolean("pretty").pipe(Options.withDefault(false));
 const schemaOption = Options.boolean("schema").pipe(Options.withDefault(false));
@@ -36,11 +45,6 @@ const VALID_INCREMENTS = [
     "minor",
     "patch"
 ];
-const VALID_FRESHNESS = [
-    "auto",
-    "api",
-    "cache"
-];
 const validatePhases = (raw)=>{
     const phases = raw.split(",").map((s)=>s.trim());
     for (const p of phases)if (!VALID_PHASES.includes(p)) throw new Error(`Invalid phase: "${p}". Valid values: ${VALID_PHASES.join(", ")}`);
@@ -50,10 +54,6 @@ const validateIncrements = (raw)=>{
     if (!VALID_INCREMENTS.includes(raw)) throw new Error(`Invalid increments value: "${raw}". Valid values: ${VALID_INCREMENTS.join(", ")}`);
     return raw;
 };
-const validateFreshness = (raw)=>{
-    if (!VALID_FRESHNESS.includes(raw)) throw new Error(`Invalid freshness value: "${raw}". Valid values: ${VALID_FRESHNESS.join(", ")}`);
-    return raw;
-};
 const serializeError = (error)=>{
     if (error && "object" == typeof error && "_tag" in error && "message" in error) {
         const { _tag, message, ...rest } = error;
@@ -92,7 +92,7 @@ const toError = (name, error)=>[
             error: serializeError(error)
         }
     ];
-const resolveNode = (semverRange, phases, increments, defaultVersion, date, freshness, authOverride)=>Effect.gen(function*() {
+const resolveNode = (semverRange, phases, increments, defaultVersion, date, authOverride)=>Effect.gen(function*() {
         const resolver = yield* NodeResolver;
         const result = yield* resolver.resolve({
             semverRange,
@@ -107,14 +107,11 @@ const resolveNode = (semverRange, phases, increments, defaultVersion, date, fres
             } : {},
             ...date ? {
                 date
-            } : {},
-            ...freshness ? {
-                freshness
             } : {}
         });
         return toSuccess("node", result);
-    }).pipe(Effect.provide(authOverride ? NodeResolverLive.pipe(Layer.provide(Layer.merge(GitHubClientLive.pipe(Layer.provide(authOverride)), VersionCacheLive))) : NodeLayer), Effect.catchAll((error)=>Effect.succeed(toError("node", error))));
-const resolveBun = (semverRange, increments, defaultVersion, freshness, authOverride)=>Effect.gen(function*() {
+    }).pipe(Effect.provide(makeNodeLayer(authOverride)), Effect.catchAll((error)=>Effect.succeed(toError("node", error))));
+const resolveBun = (semverRange, increments, defaultVersion, authOverride)=>Effect.gen(function*() {
         const resolver = yield* BunResolver;
         const result = yield* resolver.resolve({
             semverRange,
@@ -123,14 +120,11 @@ const resolveBun = (semverRange, increments, defaultVersion, freshness, authOver
             } : {},
             ...defaultVersion ? {
                 defaultVersion
-            } : {},
-            ...freshness ? {
-                freshness
             } : {}
         });
         return toSuccess("bun", result);
-    }).pipe(Effect.provide(authOverride ? BunResolverLive.pipe(Layer.provide(Layer.merge(GitHubClientLive.pipe(Layer.provide(authOverride)), VersionCacheLive))) : BunLayer), Effect.catchAll((error)=>Effect.succeed(toError("bun", error))));
-const resolveDeno = (semverRange, increments, defaultVersion, freshness, authOverride)=>Effect.gen(function*() {
+    }).pipe(Effect.provide(makeBunLayer(authOverride)), Effect.catchAll((error)=>Effect.succeed(toError("bun", error))));
+const resolveDeno = (semverRange, increments, defaultVersion, authOverride)=>Effect.gen(function*() {
         const resolver = yield* DenoResolver;
         const result = yield* resolver.resolve({
             semverRange,
@@ -139,13 +133,10 @@ const resolveDeno = (semverRange, increments, defaultVersion, freshness, authOve
             } : {},
             ...defaultVersion ? {
                 defaultVersion
-            } : {},
-            ...freshness ? {
-                freshness
             } : {}
         });
         return toSuccess("deno", result);
-    }).pipe(Effect.provide(authOverride ? DenoResolverLive.pipe(Layer.provide(Layer.merge(GitHubClientLive.pipe(Layer.provide(authOverride)), VersionCacheLive))) : DenoLayer), Effect.catchAll((error)=>Effect.succeed(toError("deno", error))));
+    }).pipe(Effect.provide(makeDenoLayer(authOverride)), Effect.catchAll((error)=>Effect.succeed(toError("deno", error))));
 const formatResponse = (ok, results, pretty)=>{
     const response = {
         $schema: SCHEMA_URL,
@@ -162,7 +153,6 @@ const resolveHandler = (args)=>Effect.gen(function*() {
                 args.deno,
                 args.nodePhases,
                 args.increments,
-                args.freshness,
                 args.nodeDefault,
                 args.bunDefault,
                 args.denoDefault,
@@ -174,9 +164,7 @@ const resolveHandler = (args)=>Effect.gen(function*() {
             ];
             const hasResolveFlags = resolveFlags.some((f)=>Option.isSome(f));
             if (hasResolveFlags) return void (yield* Console.error("Error: --schema cannot be combined with resolve flags (--node, --bun, --deno, etc.)"));
-            const { cliJsonSchema } = yield* Effect.promise(()=>import("../235.js").then((mod)=>({
-                        cliJsonSchema: mod.cliJsonSchema
-                    })));
+            const { cliJsonSchema } = yield* Effect.promise(()=>import("../json-schema.js").then((m)=>m.json_schema_namespaceObject));
             yield* Console.log(JSON.stringify(cliJsonSchema, null, 2));
             return;
         }
@@ -227,13 +215,6 @@ const resolveHandler = (args)=>Effect.gen(function*() {
             yield* Console.error(e.message);
             return;
         }
-        let validatedFreshness;
-        if (Option.isSome(args.freshness)) try {
-            validatedFreshness = validateFreshness(args.freshness.value);
-        } catch (e) {
-            yield* Console.error(e.message);
-            return;
-        }
         let nodeDate;
         if (Option.isSome(args.nodeDate)) {
             nodeDate = new Date(args.nodeDate.value);
@@ -242,15 +223,15 @@ const resolveHandler = (args)=>Effect.gen(function*() {
         const tasks = [];
         if (hasNode) {
             const nodeDefaultVersion = Option.isSome(args.nodeDefault) ? args.nodeDefault.value : void 0;
-            tasks.push(resolveNode(args.node.value, validatedPhases, validatedIncrements, nodeDefaultVersion, nodeDate, validatedFreshness, authLayerOverride));
+            tasks.push(resolveNode(args.node.value, validatedPhases, validatedIncrements, nodeDefaultVersion, nodeDate, authLayerOverride));
         }
         if (hasBun) {
             const bunDefaultVersion = Option.isSome(args.bunDefault) ? args.bunDefault.value : void 0;
-            tasks.push(resolveBun(args.bun.value, validatedIncrements, bunDefaultVersion, validatedFreshness, authLayerOverride));
+            tasks.push(resolveBun(args.bun.value, validatedIncrements, bunDefaultVersion, authLayerOverride));
         }
         if (hasDeno) {
             const denoDefaultVersion = Option.isSome(args.denoDefault) ? args.denoDefault.value : void 0;
-            tasks.push(resolveDeno(args.deno.value, validatedIncrements, denoDefaultVersion, validatedFreshness, authLayerOverride));
+            tasks.push(resolveDeno(args.deno.value, validatedIncrements, denoDefaultVersion, authLayerOverride));
         }
         const entries = yield* Effect.all(tasks, {
             concurrency: "unbounded"
@@ -265,7 +246,6 @@ const rootCommand = Command.make("runtime-resolver", {
     deno: denoOption,
     nodePhases: nodePhasesOption,
     increments: incrementsOption,
-    freshness: freshnessOption,
     nodeDefault: nodeDefaultOption,
     bunDefault: bunDefaultOption,
     denoDefault: denoDefaultOption,
@@ -279,7 +259,7 @@ const rootCommand = Command.make("runtime-resolver", {
 }, resolveHandler);
 const cli = Command.run(rootCommand, {
     name: "runtime-resolver",
-    version: "0.1.0"
+    version: "0.3.0"
 });
 const main = Effect.suspend(()=>cli(process.argv)).pipe(Effect.provide(NodeContext.layer), Effect.catchAllCause((cause)=>{
     const defects = Cause.defects(cause);