npm - @ultimat3/render - Versions diffs - 1.2.0 → 2.0.0 - Mend

@ultimat3/render 1.2.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/src/route.ts CHANGED Viewed

@@ -3,15 +3,22 @@
  * offline strategy, hydration timing and metadata, and it hands back a descriptor that is
  * already normalized: `meta` always awaits, `budget` is always there.
  *
- * `offline`, `hydrate` and `meta` are REQUIRED BY THE TYPE. That is axiom 3 — enforced,
- * not documented — expressed in the type system: a route that forgets its offline
- * strategy or its `<head>` is a compile error, not a checklist item nobody reads.
+ * `offline` and `meta` are REQUIRED BY THE TYPE. That is axiom 3 — enforced, not documented —
+ * expressed in the type system: a route that forgets its offline strategy or its `<head>` is a
+ * compile error, not a checklist item nobody reads.
+ *
+ * `hydrate` is not on that list, since 1.2.0: it is the one key the framework can work out from
+ * the page's own declarations, and requiring a value it already knows is not enforcement, it is a
+ * second place to get one thing wrong.
  */
 import type { CacheTag } from '@ultimat3/cache';
 import { serializeTags } from '@ultimat3/cache';
+import type { Translator } from '@ultimat3/i18n';
 import type { RouteMeta } from '@ultimat3/seo';
-import { RouteMetaMissingError, RouteOfflineMissingError } from './errors';
+import { RouteLoadInvalidError, RouteMetaMissingError, RouteOfflineMissingError } from './errors';
+import type { IslandSpec } from './island';
+import { drainDeclaredIslands } from './island';
 import { assertModeShape } from './modes';
 export type RenderMode = 'static' | 'isr' | 'ssr' | 'stream' | 'spa';
@@ -21,6 +28,15 @@ export type HydrateStrategy = 'idle' | 'visible' | 'interaction' | 'never';
 export const OFFLINE_STRATEGIES = ['precache', 'runtime', 'network-only'] as const;
 export const HYDRATE_STRATEGIES = ['idle', 'visible', 'interaction', 'never'] as const;
+/**
+ * What a page that declares an island hydrates as when it says nothing. The most conservative of
+ * the three that ship JavaScript: nothing runs until the visitor acts, and `interaction` is the
+ * only one that also replays the event that woke the island, so the first click is answered rather
+ * than swallowed. An island wanting `visible` (an infinite scroll) still says so once — on the
+ * route, the same key that overrides this one, never a second declaration on the island itself.
+ */
+export const DEFAULT_ISLAND_HYDRATE: HydrateStrategy = 'interaction';
 export type RouteParams = Readonly<Record<string, string>>;
 export type RouteData = Readonly<Record<string, unknown>>;
@@ -50,25 +66,102 @@ export interface RouteGuard {
   readonly permission: string;
 }
+/**
+ * What a loader and a `meta` function are told about the request. `url` is a string because that
+ * is what `ld.*` embeds and what `meta` already received before `load` existed.
+ *
+ * An alias rather than an `interface`, deliberately: absent a `load` this object IS the route's
+ * data, and only an alias carries the implicit index signature that makes it a `RouteData`. As an
+ * interface the compiler could not see that, so the one place it mattered — `routeDataFor`'s
+ * fallback — laundered it through `as unknown as TData` and checked nothing at all.
+ */
+export type RouteContext = {
+  readonly params: RouteParams;
+  readonly url: string;
+};
+/**
+ * The route's server-side data, resolved ONCE per render and handed to both `meta` and the page.
+ *
+ * This is not a ninth concern bolted onto the contract — it completes the one `meta` already
+ * declares. `RouteMetaFn<TData>` has always taken a `TData`, and until this existed nothing could
+ * ever supply one richer than `{ url, params }`: the page component was passed the same two
+ * fields, so a page that fetched its own data could not share it with `meta`. The consequence was
+ * silent and severe — a `site/` route's `<title>` and `description` could never reflect its
+ * content, on the surface whose entire purpose is SEO, and a page written against `props.data`
+ * rendered an empty list with a 200 rather than an error.
+ *
+ * Sync or async, whichever the page's data needs.
+ */
+export type RouteLoadFn<TData = RouteData> = (ctx: RouteContext) => TData | Promise<TData>;
+/** What the descriptor hands back. One shape, so no consumer branches on a thenable. */
+export type RouteLoadAsyncFn<TData = RouteData> = (ctx: RouteContext) => Promise<TData>;
+/**
+ * What `meta` is given: the loaded data, the request, and the translator.
+ *
+ * A context rather than the bare data, because a `<title>` needs all three — the data for the
+ * content, `url` for the canonical, and `t` because no user-facing string may be hardcoded. It is
+ * a strict SUPERSET of what `meta` received before `load` existed (`{ params, url }`), and both
+ * keys keep their names, so every route that reads `data.url` or `data.params` keeps working.
+ */
+export interface RouteMetaContext<TData = RouteData> {
+  readonly data: TData;
+  readonly params: RouteParams;
+  readonly url: string;
+  /** The request's own translator. Never a hardcoded string in a `<title>`. */
+  readonly t: Translator;
+}
 /** What an author writes. Sync or async, whichever the page's data needs. */
-export type RouteMetaFn<TData = RouteData> = (data: TData) => RouteMeta | Promise<RouteMeta>;
+export type RouteMetaFn<TData = RouteData> = (
+  ctx: RouteMetaContext<TData>,
+) => RouteMeta | Promise<RouteMeta>;
 /** What the descriptor hands back. One shape, so no consumer branches on a thenable. */
-export type RouteMetaAsyncFn<TData = RouteData> = (data: TData) => Promise<RouteMeta>;
+export type RouteMetaAsyncFn<TData = RouteData> = (
+  ctx: RouteMetaContext<TData>,
+) => Promise<RouteMeta>;
 /** Returns the params to build at deploy time. Bare strings fill a single dynamic param. */
 export type PrerenderFn = () =>
   | readonly (string | RouteParams)[]
   | Promise<readonly (string | RouteParams)[]>;
-/** The input shape of `defineRoute` — exactly the contract's eight keys, nothing else. */
+/**
+ * The rule that makes the no-`load` fallback true: a route that loads nothing renders
+ * `{ params, url }`, so its `meta` may only read what the context itself supplies. Any richer
+ * `TData` has to come from a loader, and this intersection is what says so — `nothing` when the
+ * context already satisfies `TData`, a required `load` when it does not.
+ *
+ * Enforced, not documented (axiom 3): a `meta` reading `data.post` off a route that declares no
+ * `load` is a compile error here, rather than `undefined` in a `<title>` on the surface whose
+ * entire purpose is SEO.
+ */
+export type LoadRequirement<TData> = RouteContext extends TData
+  ? unknown
+  : { readonly load: RouteLoadFn<TData> };
+/** The input shape of `defineRoute` — exactly the contract's nine keys, nothing else. */
 export interface RouteDefinition<TData = RouteData> {
   readonly render: RenderMode;
   readonly revalidate?: RevalidateConfig;
   readonly prerender?: PrerenderFn;
   readonly offline: OfflineStrategy;
-  readonly hydrate: HydrateStrategy;
+  /**
+   * Optional since 1.2.0, and derived when omitted: a page that declares an island hydrates
+   * (`DEFAULT_ISLAND_HYDRATE`), a page that declares none ships nothing (`'never'`). Stating it is
+   * still the one override, and still the only way to say `visible` or `idle`.
+   *
+   * It was required, and the two failures that made it worth deriving were both the framework
+   * asking for a value it could already work out: an island on a route still at `'never'` is
+   * `X_ISLAND_NOT_HYDRATED`, and a `site/` route off `'never'` with no `budget.js` is refused at
+   * registration. Two punishments for one omission the declaration above already answered.
+   */
+  readonly hydrate?: HydrateStrategy;
   readonly budget?: RouteBudget;
+  readonly load?: RouteLoadFn<TData>;
   readonly meta: RouteMetaFn<TData>;
   readonly policy?: RouteGuard;
 }
@@ -76,15 +169,24 @@ export interface RouteDefinition<TData = RouteData> {
 /**
  * The frozen descriptor. `kind` lets the registry reject non-route exports.
  *
- * Two fields are narrower here than in the declaration so every consumer reads one shape:
- * `meta` always returns a promise, and `budget` is always an object. Its *fields* stay
- * optional — `budget.js === undefined` still means "this route declared no JS budget",
- * which is exactly what `modes.ts` fails a hydrating `site/` route on.
+ * Three fields are narrower here than in the declaration so every consumer reads one shape:
+ * `meta` always returns a promise, `budget` is always an object, and `hydrate` is always one of
+ * the four strategies — resolved, so nothing downstream repeats the derivation. `budget`'s
+ * *fields* stay optional; `budget.js === undefined` still means "no JS budget declared", which is
+ * what `registry.ts` fills in for an island route and `modes.ts` fails a hydrating `site/` route on.
  */
 export interface RouteConfig<TData = RouteData> extends RouteDefinition<TData> {
   readonly kind: 'route';
   readonly meta: RouteMetaAsyncFn<TData>;
+  readonly load?: RouteLoadAsyncFn<TData>;
+  readonly hydrate: HydrateStrategy;
   readonly budget: RouteBudget;
+  /**
+   * The islands this module declared, in declaration order. Never written by an author — drained
+   * from `island()`, and the reason `hydrate` and `budget.js` do not have to be. Also what finally
+   * populates `RouteEntry.islands`, which `routeJsBytes` has always read and nothing ever filled.
+   */
+  readonly islands: readonly IslandSpec[];
 }
 /** What every render mode hands back to `@ultimat3/http`'s `html()` / `stream()`. */
@@ -106,9 +208,12 @@ export function tagKeys(tags: readonly CacheTag[] | undefined): readonly string[
  * Declare a route. Validates the shape (for JS callers who bypass the types) and the
  * mode-local invariants immediately, so a bad route fails at module evaluation — build
  * time — rather than on the first request in production.
+ *
+ * `LoadRequirement` is the half the compiler owns: a `meta` reading data the context cannot
+ * supply forces a `load`, which is what lets `routeDataFor` hand the context back as the data.
  */
 export function defineRoute<TData = RouteData>(
-  definition: RouteDefinition<TData>,
+  definition: RouteDefinition<TData> & LoadRequirement<TData>,
 ): RouteConfig<TData> {
   const def = definition as Partial<RouteDefinition<TData>>;
@@ -131,19 +236,36 @@ export function defineRoute<TData = RouteData>(
     );
   }
+  if (def.load !== undefined && typeof def.load !== 'function') {
+    throw new RouteLoadInvalidError(
+      `load: ${JSON.stringify(def.load)} is not a function`,
+      'make load a function of ({ params, url }) returning the page data, or remove it',
+    );
+  }
   const declaredMeta = def.meta;
+  const declaredLoad = def.load;
+  // Drained unconditionally, even when `hydrate` is stated: the list must not survive into the
+  // next route defined in this process, and `RouteEntry.islands` wants it either way.
+  const islands = drainDeclaredIslands();
   const config: RouteConfig<TData> = {
     kind: 'route',
     render: def.render as RenderMode,
     offline: def.offline,
-    hydrate: def.hydrate as HydrateStrategy,
+    islands,
+    // Declared wins, always — including `hydrate: 'never'` on a page that has an island, which is
+    // a contradiction an author stated on purpose and `X_ISLAND_NOT_HYDRATED` still refuses.
+    hydrate: def.hydrate ?? (islands.length > 0 ? DEFAULT_ISLAND_HYDRATE : 'never'),
     // Wrapped rather than stored: the declaration may be sync, the descriptor never is.
     // A meta that throws synchronously becomes a rejection here, so `await config.meta(d)`
     // is the one way to fail as well as the one way to succeed.
-    meta: async (data: TData) => declaredMeta(data),
+    meta: async (metaCtx: RouteMetaContext<TData>) => declaredMeta(metaCtx),
     // Always an object. `budget.js` is the only reach a consumer needs, so an undeclared
     // budget is `{}` instead of a second undefined-check at every call site.
     budget: def.budget ?? {},
+    // Wrapped exactly as `meta` is, and for the same reason: the declaration may be sync, the
+    // descriptor never is, so `await config.load(ctx)` is the one way to fail as well as succeed.
+    ...(declaredLoad ? { load: async (ctx: RouteContext) => declaredLoad(ctx) } : {}),
     ...(def.revalidate ? { revalidate: def.revalidate } : {}),
     ...(def.prerender ? { prerender: def.prerender } : {}),
     ...(def.policy ? { policy: def.policy } : {}),

package/src/surfaces.ts CHANGED Viewed

@@ -61,11 +61,30 @@ export const SURFACE_SPECS: Readonly<Record<Surface, SurfaceSpec>> = Object.free
 const SURFACE_SEGMENT = /(?:^|\/)(site|app|api|shared)\//;
+/** Where the surface segment is, and what follows it — the two halves of one match. */
+export interface SurfaceLocation {
+  readonly surface: Surface;
+  /** Everything after `<surface>/`. `apps/myapp/app/dashboard/page.tsx` → `dashboard/page.tsx`. */
+  readonly rest: string;
+}
+/**
+ * The ONE reader of the surface segment, because the two readers disagreed: this regex is
+ * anchored on a path separator, and the route table's `indexOf('app/')` was not — so
+ * `apps/myapp/app/page.tsx` took its surface from here and its URL from the `app/` inside
+ * `myapp/`, and served every route in that app one segment too deep (`/app` instead of `/`).
+ */
+export function locateSurface(file: string): SurfaceLocation | null {
+  const normalized = normalize(file);
+  const match = SURFACE_SEGMENT.exec(normalized);
+  const found = match?.[1];
+  if (found === undefined || match === null) return null;
+  return { surface: found as Surface, rest: normalized.slice(match.index + match[0].length) };
+}
 /** `apps/web/site/pricing/page.tsx` → `site`. Returns null for files outside a surface. */
 export function surfaceOf(file: string): Surface | null {
-  const match = SURFACE_SEGMENT.exec(normalize(file));
-  const found = match?.[1];
-  return found === undefined ? null : (found as Surface);
+  return locateSurface(file)?.surface ?? null;
 }
 function normalize(file: string): string {

package/src/type-pins.tsx ADDED Viewed

@@ -0,0 +1,101 @@
+// Compile-time pins for the route's data seam and for island JSX. Source, not a `.test.ts`, on
+// purpose: `tsconfig.json` excludes `src/**/*.test.ts`, so `tsc -b` never reads a test file and a
+// type-level claim written in one can never fail. This module emits nothing and exports nothing
+// anybody imports — a regression here is a build error, the only enforcement that counts.
+//
+// `.tsx`, not `.ts`, since 1.2.0: half of what is pinned here is only decidable by writing the JSX
+// an author writes. `jsxImportSource` is `solid-js` in `tsconfig.base.json` and in both tracked
+// apps, so the `<ContactSales />` below is checked against the SAME `JSX.Element` a page is —
+// which is the only way a regression to `IslandNode` fails a build rather than a reader's review.
+import type { IslandComponent } from './island';
+import { island } from './island';
+import type { JsonValue } from './island-props';
+import type { LoadRequirement, RouteContext, RouteData, RouteDefinition } from './route';
+/** Fails to compile when `T` is anything but `true`. The whole mechanism. */
+type Assert<T extends true> = T;
+type BlogPost = { readonly post: { readonly title: string } };
+/**
+ * What makes `routeDataFor`'s no-`load` branch sound. `RouteContext` has to BE a `RouteData` —
+ * an `interface` is not, because only an alias gets the implicit index signature, and declaring
+ * it as one is what turned that branch's `as unknown as TData` into a checked narrowing.
+ */
+export type _ContextIsRouteData = Assert<RouteContext extends RouteData ? true : false>;
+/**
+ * A route that loads nothing still declares nothing extra. `LoadRequirement` collapses to
+ * `unknown` for the default `TData`, so every route that shipped before `load` existed — and
+ * every route that only reads `data.url` / `data.params` — keeps compiling untouched.
+ */
+export type _DefaultDataNeedsNoLoad = Assert<
+  RouteDefinition extends RouteDefinition & LoadRequirement<RouteData> ? true : false
+>;
+/**
+ * …and a `meta` reading a field the context cannot supply forces one. Pinned as the required
+ * `load` key rather than "does not compile", because that is the exact thing the intersection
+ * adds: without it, `defineRoute<BlogPost>({ meta: (c) => c.data.post.title })` type-checked and
+ * rendered `undefined` in a `<title>`.
+ */
+export type _RicherDataRequiresALoad = Assert<
+  undefined extends LoadRequirement<BlogPost>['load'] ? false : true
+>;
+type ContactModal = IslandComponent<readonly ['subject']>;
+type ContactModalProps = Parameters<ContactModal>[0];
+/**
+ * The declared prop is required and typed, so the call site that forgets it does not compile.
+ * `props: ['subject']` is the whole declaration — there is no second place to state the shape.
+ */
+export type _DeclaredPropIsRequired = Assert<
+  ContactModalProps extends { readonly subject: JsonValue } ? true : false
+>;
+/**
+ * An island's props are exactly what it declared. Anything else has no type here, which is what
+ * makes `<Modal {…row} />` a compile error before it is the runtime error that names the column.
+ */
+export type _UndeclaredPropHasNoType = Assert<
+  'passwordHash' extends keyof ContactModalProps ? false : true
+>;
+/**
+ * The children are the server-rendered shell and never JSON: they stay `unknown`, so nothing in
+ * the type system suggests a component or a handler could travel to the browser inside them.
+ */
+export type _ChildrenAreNotJson = Assert<
+  ContactModalProps['children'] extends JsonValue | undefined ? false : true
+>;
+/** A value the browser could never receive is not a `JsonValue`, so the prop never type-checks. */
+export type _AHandleIsNotJson = Assert<(() => void) extends JsonValue ? false : true>;
+const ContactSales: ContactModal = island({
+  src: './contact-sales.island.tsx',
+  props: ['subject'],
+});
+/**
+ * The pin that a `.ts` file cannot carry: an island used the way every author reaches for it.
+ *
+ * `island()` returned a plain object node until 1.2.0, and every `<ContactSales />` in an app was
+ * TS2786 — "its return type 'IslandNode' is not a valid JSX element" — while `h(ContactSales, …)`
+ * compiled, which is why the framework's own island tests never saw it. The configured
+ * `JSX.Element` is `solid-js`'s, a type ALIAS and therefore unaugmentable, whose only
+ * object-shaped member is `ArrayElement`. `IslandNode` is that array, and this function is what
+ * says so in a form `tsc` reads.
+ *
+ * Not `: JSX.Element` — render must not import `solid-js`. `unknown` is enough: the error lands on
+ * the element, never on the return.
+ */
+export function _IslandIsAJsxComponent(): unknown {
+  return (
+    <ContactSales subject="pricing">
+      <p>the server-rendered shell</p>
+    </ContactSales>
+  );
+}