🐛 Fix API reference showing alpha instead of stable release (#1130)

Author: Taras Mankovski

www/components/api/api-page.tsx

@@ -63,14 +63,16 @@ export function* ApiPage({
         ),
         linkResolver: createSibling,
         versionToggle: yield* (function* () {
-          const { series: SERIES } = yield* useConfig();
+          const { series } = yield* useConfig();
+          // Only show stable series in version toggle (no prereleases)
+          const stableSeries = series.filter((s) => !s.includePrerelease);
           const currentSeries = `v${major(pkg.version)}`;
 
           const links = yield* all(
-            SERIES.map(function* (s) {
+            stableSeries.map(function* (s) {
               const seriesPkg = yield* usePackage({
                 type: "worktree",
-                series: s,
+                series: s.name,
               });
               const seriesDocs = yield* seriesPkg.docs();
               const hasSymbol = seriesDocs["."].some((node) =>
@@ -81,9 +83,9 @@ export function* ApiPage({
 
               return (
                 <a
-                  href={yield* createRootUrl(`api/${s}`)(current)}
+                  href={yield* createRootUrl(`api/${s.name}`)(current)}
                   class={`text-base ${
-                    s === currentSeries
+                    s.name === currentSeries
                       ? "font-bold text-sky-500"
                       : "text-gray-600 dark:text-gray-400 hover:text-sky-500"
                   }`}

www/context/config.ts

@@ -1,21 +1,56 @@
 import { createContext, type Operation } from "effection";
 
-export interface SiteConfig<T extends string = string> {
-  series: T[];
-  current: NoInfer<T>;
+export interface SeriesConfig {
+  /** Series identifier used in URLs, e.g., "v4", "v4-next" */
+  name: string;
+  /** Major version number for semver matching */
+  major: number;
+  /** Include prerelease versions when finding latest tag */
+  includePrerelease?: boolean;
+  /** Parent series name for grouping (e.g., "v4-next" -> "v4") */
+  parent?: string;
+}
+
+export interface SiteConfig {
+  series: SeriesConfig[];
+  current: string;
 }
 
 const ConfigContext = createContext<SiteConfig>("site-config", {
-  series: ["v3", "v4"],
+  series: [
+    { name: "v3", major: 3 },
+    { name: "v4", major: 4 },
+    { name: "v4-next", major: 4, includePrerelease: true, parent: "v4" },
+  ],
   current: "v4",
 });
 
-export function* initConfig<T extends string>(
-  config: SiteConfig<T>,
+export function* initConfig(
+  config: SiteConfig,
 ): Operation<void> {
   yield* ConfigContext.set(config);
 }
 
 export function* useConfig(): Operation<SiteConfig> {
   return yield* ConfigContext.expect();
 }
+
+/**
+ * Find a series configuration by name
+ */
+export function findSeries(
+  config: SiteConfig,
+  name: string,
+): SeriesConfig | undefined {
+  return config.series.find((s) => s.name === name);
+}
+
+/**
+ * Get series that are children of a parent series
+ */
+export function getChildSeries(
+  config: SiteConfig,
+  parentName: string,
+): SeriesConfig[] {
+  return config.series.filter((s) => s.parent === parentName);
+}

www/lib/package.ts

@@ -3,7 +3,7 @@ import { relative } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import z from "zod";
-import { SiteConfig } from "../context/config.ts";
+import { findSeries, type SeriesConfig, useConfig } from "../context/config.ts";
 import { useJSRClient } from "../context/jsr.ts";
 import { LocalDocsPages, useDocPages } from "../hooks/use-deno-doc.tsx";
 import { useDescription, useTitle } from "../hooks/use-description-parse.tsx";
@@ -19,7 +19,10 @@ import { useWorktree } from "./worktrees.ts";
 
 export type WorkTreePackageOptions = {
   type: "worktree";
-  series: SiteConfig["series"][number];
+  /** Series name, e.g., "v4", "v4-next" */
+  series: string;
+  /** Override series config (optional, will look up from SiteConfig if not provided) */
+  seriesConfig?: SeriesConfig;
 };
 
 export type ClonePackageOptions = {
@@ -72,9 +75,26 @@ export function* usePackage(options: PackageOptions): Operation<Package> {
   if (options.type === "worktree") {
     let repo = createRepo({ name: "effection", owner: "thefrontside" });
 
-    let tags = yield* repo.tags(new RegExp(`effection-${options.series}.*`));
+    // Get series config from options or look it up
+    let seriesConfig = options.seriesConfig;
+    if (!seriesConfig) {
+      let config = yield* useConfig();
+      seriesConfig = findSeries(config, options.series);
+      if (!seriesConfig) {
+        throw new Error(`unknown series: ${options.series}`);
+      }
+    }
+
+    // Fetch all tags for this major version
+    let tags = yield* repo.tags(
+      new RegExp(`effection-v${seriesConfig.major}.*`),
+    );
 
-    let ref = findLatestSemverTag(tags);
+    // Use semver range to find latest (excludes prereleases unless configured)
+    let range = `${seriesConfig.major}.x`;
+    let ref = findLatestSemverTag(tags, range, {
+      includePrerelease: seriesConfig.includePrerelease,
+    });
 
     if (!ref) {
       throw new Error(`unable to find package ref for ${options.series}`);

www/lib/semver.ts

@@ -1,6 +1,6 @@
-export { compare, major, minor, rsort } from "semver";
+export { compare, gt, major, maxSatisfying, minor, rsort } from "semver";
 
-import { rsort } from "semver";
+import { maxSatisfying, rsort } from "semver";
 
 export function extractVersion(input: string) {
   let parts = input.match(
@@ -14,14 +14,33 @@ export function extractVersion(input: string) {
   }
 }
 
+export interface FindLatestSemverTagOptions {
+  includePrerelease?: boolean;
+}
+
 /**
  * Find the latest Semver tag from an array of tags
  * @param tags - Array of tag objects with name property
+ * @param range - Optional semver range to filter tags (e.g., "4.x", ">=3.0.0")
+ * @param options - Optional settings like includePrerelease
  * @returns Latest semver tag if found, undefined otherwise
  */
 export function findLatestSemverTag<T extends { name: string }>(
   tags: T[],
+  range?: string,
+  options?: FindLatestSemverTagOptions,
 ): T | undefined {
-  let [latest] = rsort(tags.map((tag) => tag.name).map(extractVersion));
+  let versions = tags.map((tag) => tag.name).map(extractVersion);
+
+  let latest: string | undefined;
+  if (range) {
+    // Use semver range matching (excludes prereleases by default)
+    latest = maxSatisfying(versions, range, options) ?? undefined;
+  } else {
+    // Fallback to current behavior: sort all and take first
+    [latest] = rsort(versions);
+  }
+
+  if (!latest) return undefined;
   return tags.find((tag) => tag.name.endsWith(latest));
 }

www/main.tsx

@@ -37,11 +37,16 @@ if (import.meta.main) {
   await main(function* () {
     let { current, series } = yield* useConfig();
 
+    // Get stable series (no prereleases) for guides
+    let stableSeries = series.filter((s) => !s.includePrerelease);
+
     yield* initClones("build/clones");
     yield* initWorktrees("build/worktrees");
     yield* initGuides({
       current,
-      worktrees: series.filter((s) => s !== current),
+      worktrees: stableSeries
+        .filter((s) => s.name !== current)
+        .map((s) => s.name),
     });
 
     yield* initBlog();
@@ -58,17 +63,22 @@ if (import.meta.main) {
         route("/search", searchRoute()),
         route("/docs", redirectIndexRoute(firstPage(current))),
         route("/docs/:id", redirectDocsRoute(current)),
-        ...series.map((s) =>
-          route(`/guides/${s}`, redirectIndexRoute(firstPage(s)))
+        // Guides only for stable series (no prereleases)
+        ...stableSeries.map((s) =>
+          route(`/guides/${s.name}`, redirectIndexRoute(firstPage(s.name)))
         ),
         route("/guides/:series/:id", guidesRoute({ search: true })),
         route("/contrib", xIndexRedirect()),
         route("/contrib/:workspacePath", xPackageRedirect()),
         route("/x", xIndexRoute({ search: true })),
         route("/x/:workspacePath", xPackageRoute({ search: true })),
         route("/api", apiIndexRoute({ search: true })),
+        // API docs for all series including prereleases
         ...series.map((s) =>
-          route(`/api/${s}/:symbol`, apiReferenceRoute(s, { search: true }))
+          route(
+            `/api/${s.name}/:symbol`,
+            apiReferenceRoute(s.name, { search: true }),
+          )
         ),
         route("/blog", blogIndexRoute({ search: true })),
         route("/blog/feed.xml", blogFeedRoute()),

www/routes/api-index-route.tsx

@@ -4,6 +4,7 @@ import { Icon } from "../components/type/icon.tsx";
 import { DocPage } from "../hooks/use-deno-doc.tsx";
 import { ResolveLinkFunction } from "../hooks/use-markdown.tsx";
 import { usePackage } from "../lib/package.ts";
+import { gt } from "../lib/semver.ts";
 import { SitemapRoute } from "../plugins/sitemap.ts";
 import { useAppHtml } from "./app.html.tsx";
 import { createChildURL } from "../lib/links-resolvers.ts";
@@ -26,6 +27,18 @@ export function apiIndexRoute(
         series: "v4",
       });
 
+      let v4Next = yield* usePackage({
+        type: "worktree",
+        series: "v4-next",
+      });
+
+      // Only show prerelease link if it's newer than stable
+      let showV4Prerelease = gt(v4Next.version, v4.version);
+
+      // Get first symbol for prerelease link
+      let v4NextDocs = showV4Prerelease ? yield* v4Next.docs() : null;
+      let v4NextFirstSymbol = v4NextDocs?.["."]?.[0]?.name ?? "run";
+
       let docs = {
         v3: yield* v3.docs(),
         v4: yield* v4.docs(),
@@ -43,6 +56,18 @@ export function apiIndexRoute(
             <section>
               <h3 id={v4.version} class="group scroll-mt-[200px]">
                 {v4.version}
+                {showV4Prerelease && (
+                  <span class="text-sm font-normal text-gray-500 dark:text-gray-400 ml-2">
+                    ·{" "}
+                    <a
+                      href={`/api/v4-next/${v4NextFirstSymbol}`}
+                      class="text-blue-600 dark:text-blue-400 hover:underline"
+                    >
+                      {v4Next.version}
+                    </a>{" "}
+                    also available
+                  </span>
+                )}
                 <a
                   href={`#${v4.version}`}
                   class="opacity-0 group-hover:opacity-100 after:content-['#'] after:ml-1.5 no-underline"

www/routes/api-reference-route.tsx

@@ -6,9 +6,8 @@ import { useAppHtml } from "./app.html.tsx";
 import { ApiPage } from "../components/api/api-page.tsx";
 import { usePackage } from "../lib/package.ts";
 import { createSibling } from "../lib/links-resolvers.ts";
-import { SiteConfig } from "../context/config.ts";
 
-export function apiReferenceRoute(series: SiteConfig["series"][number], {
+export function apiReferenceRoute(series: string, {
   search,
 }: {
   search: boolean;

www/routes/guides-route.tsx

@@ -30,23 +30,27 @@ export function guidesRoute({
 }): SitemapRoute<JSXElement> {
   return {
     *routemap(pathname) {
-      let { series: SERIES } = yield* useConfig();
-      let paths = SERIES.map(function* (series) {
+      let { series } = yield* useConfig();
+      // Only stable series have guides (no prereleases)
+      let stableSeries = series.filter((s) => !s.includePrerelease);
+      let paths = stableSeries.map(function* (s) {
         let paths: RoutePath[] = [];
 
-        let pages = yield* useGuides(series);
+        let pages = yield* useGuides(s.name);
 
         for (let page of yield* pages.all()) {
           paths.push({
-            pathname: pathname({ id: page.id, series }),
+            pathname: pathname({ id: page.id, series: s.name }),
           });
         }
         return paths;
       });
       return (yield* all(paths)).flat();
     },
     *handler(req) {
-      let { series: SERIES, current } = yield* useConfig();
+      let { series: allSeries, current } = yield* useConfig();
+      // Only stable series have guides (no prereleases)
+      let stableSeries = allSeries.filter((s) => !s.includePrerelease);
 
       let { id, series = current } = yield* useParams<{
         id: string | undefined;
@@ -114,21 +118,21 @@ export function guidesRoute({
       }
 
       let versionToggle = yield* all(
-        SERIES.map(function* (s) {
-          let target = yield* useGuides(s);
+        stableSeries.map(function* (s) {
+          let target = yield* useGuides(s.name);
           let targetPage = yield* target.get(page.id);
-          let base = current === s ? "docs" : `guides/${s}`;
+          let base = current === s.name ? "docs" : `guides/${s.name}`;
           let url = yield* createRootUrl(base)(targetPage ? page.id : "/");
           return (
             <a
               href={url}
               class={`text-base ${
-                s === series
+                s.name === series
                   ? "font-bold text-sky-500"
                   : "text-gray-600 dark:text-gray-400 hover:text-sky-500"
               }`}
             >
-              {s}
+              {s.name}
             </a>
           );
         }),