@nubbin/next 0.1.0 → 0.2.0

package/README.md

@@ -25,6 +25,5 @@ await publishRoute(store, "/promotions/summer", hash);   // pointer, then revali
 page in the gap, and the publish appears to have silently not happened. A store rejection
 propagates without invalidating, so a failed publish never purges a working page.
 
-**Release candidate.** Requires Next 16 or newer.
-
-<https://effekt.github.io/nubbin/>. MIT.
+Requires Next.js 16 or newer. Read the [Nubbin documentation](https://nubbin.io) for the
+complete Next.js integration reference. MIT.

package/dist/index.d.ts

@@ -2,31 +2,48 @@ import { Artifact, FieldHintData, ArtifactStore } from '@nubbin/core';
 import { Metadata } from 'next';
 
 /**
- * Maps a compiled artifact's `meta` onto Next's `Metadata`, so the mapping is owned by the
- * binding rather than re-decided in every consumer's `generateMetadata` — the same reason
- * `holeFetchOptions` owns the hole-lifecycle mapping.
+ * Turns a resolved artifact into the `Metadata` Next emits into the document head, so the title
+ * and meta tags a page carries come from the document that was published rather than from the
+ * code serving it.
  *
- * `compile` has written `meta` into every artifact since the first one, and until this existed
- * nothing read it: a published page could not set its own title. The shapes differ in one place
- * — a document's `canonical` is a flat field, and Next reads a canonical URL from
- * `alternates.canonical` — so that is the only thing this translates rather than copies.
- *
- * A null artifact returns an empty object rather than a title, because the caller is about to
- * render a 404 and the layout's own metadata is the right answer for it.
- *
- * Optional fields are assigned only when present. `exactOptionalPropertyTypes` is on, and a
- * `description: undefined` sent to Next is an instruction to emit an empty tag rather than an
- * absence.
+ * @param artifact - What `resolveArtifact` answered with. `null` is the unpublished case and
+ *   belongs here, so a caller resolves once and hands the same value to the page and to
+ *   `generateMetadata`.
+ * @returns `title` always, `description` and `robots` when the document carried them, and
+ *   `canonical` moved under `alternates`, which is where Next reads one. A field the document
+ *   omitted is omitted here rather than set to `undefined`. A `null` artifact answers `{}`,
+ *   leaving the layout's own metadata standing for the 404 the page is about to render.
+ * @example
+ * ```ts
+ * export async function generateMetadata({
+ *   params,
+ * }: { params: Promise<{ slug?: string[] }> }): Promise<Metadata> {
+ *   const { slug } = await params;
+ *   return artifactMetadata(await resolveArtifact(store, slug));
+ * }
+ * ```
  */
 declare function artifactMetadata(artifact: Artifact | null): Metadata;
 
 /**
- * Maps a hole's declared lifecycle onto Next's fetch cache, so the mapping is owned by the
- * binding rather than re-decided in every consumer's resolver.
+ * Turns a hole's declared lifecycle into the `fetch` options Next reads, for a `resolveHole`
+ * fetching the value that fills it.
  *
- * Takes core's `FieldHintData` directly. An earlier plan derived a local `HoleSpec` from
- * `ArtifactNode["holes"]` so two packages would not import each other; core exports the type
- * by name, so both import it from core and neither derivation is needed.
+ * @param spec - The hole's `FieldHintData`, as `compile` copied it from the block's `ui.fields`
+ *   hint into the artifact node's `holes`. Pass it through rather than choosing an interval at
+ *   the call site: the published artifact is what says how live the value is.
+ * @returns `{ next: { revalidate: spec.revalidate } }`, ready to spread into a `fetch` call.
+ *   `0` reaches Next as `0` rather than being read as absent, which is Next's instruction not to
+ *   cache the response at all.
+ * @example
+ * ```ts
+ * import type { HoleResolver } from "@nubbin/react";
+ *
+ * const resolveHole: HoleResolver = async ({ spec }) => {
+ *   const response = await fetch(`${origin}/api/price`, holeFetchOptions(spec));
+ *   return response.json();
+ * };
+ * ```
  */
 declare function holeFetchOptions(spec: FieldHintData): RequestInit & {
     next: {
@@ -35,31 +52,122 @@ declare function holeFetchOptions(spec: FieldHintData): RequestInit & {
 };
 
 /**
- * Pointer first, invalidation second. The reverse order re-caches the outgoing page during
- * the gap, and the publish appears to have silently not happened. The store's own publish
- * rejects a hash that was never written, so a failed publish never purges a working page.
+ * Points a route at an artifact and invalidates that one page, in that order — the body of the
+ * `POST /api/nubbin/publish` handler an application exposes, which is where `nubbin publish
+ * --origin <url>` sends `{ route, hash }`.
+ *
+ * `revalidatePath` reaches only the cache of the process that runs it, so this has to run inside
+ * the server that serves the page. Moving the pointer from a terminal instead leaves that server
+ * answering from its cache until it restarts.
+ *
+ * @param store - The store serving the application. `publish` is the only method called.
+ * @param route - The route to serve, exactly as it was compiled — `resolveArtifact` matches a
+ *   pointer by its route string, so a route published under a different spelling never resolves.
+ * @param hash - The artifact to serve there. Write it first: this moves a pointer and never
+ *   stores anything, and a pointer at a hash nothing has written is a live 404.
+ * @returns Nothing. Publishing the same route and hash twice is a no-op in the store and
+ *   invalidates the page again, so a retried publish is safe.
+ * @throws Whatever `store.publish` raises, before anything is invalidated — a store rejecting an
+ *   unwritten hash or an unaddressable route leaves the page that is live untouched.
+ * @example
+ * ```ts
+ * export async function POST(request: Request) {
+ *   const { route, hash } = (await request.json()) as { route: string; hash: string };
+ *   await publishRoute(store, route, hash);
+ *   return Response.json({ ok: true, route, hash });
+ * }
+ * ```
  */
 declare function publishRoute(store: ArtifactStore, route: string, hash: string): Promise<void>;
 
 /**
- * The whole production read path: one pointer read, one artifact read. Null means the caller
- * renders a real 404 — an unpublished route has no pointer, which is what makes unpublish a
- * server 404 rather than an empty page.
+ * Resolves whatever is published at a catch-all route: one pointer read, then one artifact read.
+ * The page component and `generateMetadata` both want the same answer, so wrap the call in
+ * React's `cache` rather than reading the store twice per request.
+ *
+ * @param store - The store the route was published through. Only `pointer` and `read` are
+ *   called, so a read-only implementation serves the whole render path.
+ * @param slug - The catch-all param for the request, passed through `routeFromSlug`. `undefined`
+ *   and the empty array are the root route.
+ * @returns The artifact serving that route, or `null` — for a route with no pointer, and for a
+ *   pointer naming a hash the store no longer holds. Absence is a value rather than a failure:
+ *   it is what the caller turns into `notFound()`, and it is why unpublishing produces a server
+ *   404 instead of an empty page.
+ * @throws Whatever the store raises. Both calls answer absence with `null`, so anything thrown
+ *   from here is storage failing rather than a route that is not published.
+ * @example
+ * ```tsx
+ * export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
+ *   const artifact = await resolveArtifact(store, (await params).slug);
+ *   if (!artifact) notFound();
+ *   return <Renderer artifact={artifact} registry={blockRegistry} resolveHole={resolveHole} />;
+ * }
+ * ```
  */
 declare function resolveArtifact(store: ArtifactStore, slug: readonly string[] | undefined): Promise<Artifact | null>;
 
-/** Catch-all params to the route string artifacts and pointers are keyed by. */
+/**
+ * Turns a Next catch-all param into the route string a store keys pointers and artifacts by.
+ *
+ * @param slug - The `slug` param of a `[...slug]` or `[[...slug]]` segment, as Next resolves it.
+ *   `undefined` and the empty array both mean the root, which only the optional form matches.
+ * @returns `"/"` for an absent or empty slug, and otherwise the segments joined with `/` under a
+ *   leading slash. Segments pass through as Next handed them over — nothing is encoded, trimmed
+ *   or lower-cased, so the string matches the route `compile` stamped on the artifact only when
+ *   the document was published under the same spelling.
+ * @example
+ * ```ts
+ * routeFromSlug(undefined); // "/"
+ * routeFromSlug([]); // "/"
+ * routeFromSlug(["promotions", "summer"]); // "/promotions/summer"
+ * ```
+ */
 declare function routeFromSlug(slug: readonly string[] | undefined): string;
 
 /**
- * generateStaticParams source. manifest() is an advisory read for exactly this — no request
- * ever goes through it. Non-exact pointers are excluded until #5 settles pattern routing.
+ * Every published route that can be prebuilt, shaped as the params a catch-all segment's
+ * `generateStaticParams` returns.
+ *
+ * @param store - The store the routes were published through. Only `manifest` is called, and it
+ *   is read once per build rather than per request.
+ * @returns One `{ slug }` per exact pointer, in whatever order the manifest came back in; the
+ *   root route is `{ slug: [] }`. A `param` or `prefix` pointer — `/guides/[city]`, `/docs/*` —
+ *   is left out, because its route string is a pattern rather than a path and prebuilding it
+ *   would name a page that does not exist.
+ * @throws Whatever the store raises reading its manifest. An empty manifest is an empty array,
+ *   which is a build that prebuilds nothing rather than a failure.
+ * @example
+ * ```ts
+ * export const generateStaticParams = () => staticRouteParams(store);
+ * ```
  */
 declare function staticRouteParams(store: ArtifactStore): Promise<{
     slug: string[];
 }[]>;
 
-/** Pointer removed, then that one route invalidated — the next request renders a real 404. */
+/**
+ * Takes a route offline and invalidates that one page — the body of the
+ * `POST /api/nubbin/unpublish` handler an application exposes, which is where `nubbin unpublish
+ * --origin <url>` sends `{ route }`.
+ *
+ * Like `publishRoute`, it has to run inside the serving process: `revalidatePath` reaches only
+ * that process's cache, so a pointer dropped from a terminal leaves the page still being served.
+ *
+ * @param store - The store serving the application. `unpublish` is the only method called.
+ * @param route - The route to stop serving, exactly as it was published.
+ * @returns Nothing. The artifact stays readable at its hash — only the pointer goes — so
+ *   restoring the route is a `publishRoute` at the same hash.
+ * @throws Whatever `store.unpublish` raises, before anything is invalidated. Unpublishing a
+ *   route with no pointer is a no-op rather than a refusal.
+ * @example
+ * ```ts
+ * export async function POST(request: Request) {
+ *   const { route } = (await request.json()) as { route: string };
+ *   await unpublishRoute(store, route);
+ *   return Response.json({ ok: true, route });
+ * }
+ * ```
+ */
 declare function unpublishRoute(store: ArtifactStore, route: string): Promise<void>;
 
 export { artifactMetadata, holeFetchOptions, publishRoute, resolveArtifact, routeFromSlug, staticRouteParams, unpublishRoute };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubbin/next",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The Next.js binding for Nubbin: resolve a published artifact for a route, prebuild the ones that exist, and publish or unpublish a single route.",
   "keywords": [
     "nubbin",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@nubbin/core": "0.1.0"
+    "@nubbin/core": "0.2.0"
   },
   "peerDependencies": {
     "next": ">=16.0.0"