@webjsdev/core 0.7.6 → 0.7.8

package/src/routes.d.ts

@@ -0,0 +1,136 @@
+/**
+ * TypeScript overlay for typed page / layout / route-handler props plus an
+ * opt-in, generated route union that types `navigate()` and catches bad
+ * hrefs at tsserver time (#258).
+ *
+ * webjs identity holds: NO build step, NO runtime cost, types-only, opt-in
+ * for JSDoc apps. The mechanism mirrors Next 15's `typedRoutes` but via
+ * interface declaration-merging instead of a bundler.
+ *
+ *     import type { PageProps, LayoutProps } from '@webjsdev/core';
+ *     export default function Post({ params }: PageProps<'/blog/[slug]'>) { … }
+ *
+ * Two augmentation targets, `WebjsRoutes` and `RouteParamMap`, are EMPTY by
+ * default, so an un-generated app sees `Route = string` and `params =
+ * Record<string, string>` (non-breaking). Running `webjs types` writes
+ * `.webjs/routes.d.ts`, which augments both with one key per route literal,
+ * narrowing `Route` to the concrete app routes and giving every page typed
+ * `params`.
+ *
+ * The shapes mirror what packages/server/src/ssr.js actually constructs for
+ * the page / layout context and what packages/server/src/api.js passes a
+ * route handler, NOT a guess. Zero runtime cost: nothing here ships to the
+ * browser.
+ */
+
+import type { TemplateResult } from './html.js';
+
+/**
+ * The augmentation target the generated `.webjs/routes.d.ts` fills with one
+ * key per route literal (e.g. `'/blog/[slug]': true`). Empty by default so an
+ * un-generated app keeps `Route = string`. App code (or the generator)
+ * augments it via `declare module '@webjsdev/core'`.
+ */
+export interface WebjsRoutes {}
+
+/**
+ * The augmentation target mapping a dynamic route key to its params object
+ * (`'/blog/[slug]': { slug: string }`). Emitted by the generator with the
+ * exact `string` / `string[]` / optional shapes known at generation time,
+ * which is far more robust than deep template-literal inference. Empty by
+ * default; a static route is never given an entry here, so its params fall
+ * through to `Record<string, string>` (the runtime default), not `{}`.
+ */
+export interface RouteParamMap {}
+
+/** True once either augmentation target carries at least one key. */
+type _HasRoutes = keyof WebjsRoutes extends never ? false : true;
+
+/**
+ * Turn a route key into the set of concrete path patterns it matches by
+ * replacing each dynamic segment with `${string}`. The optional catch-all
+ * `[[...x]]` is handled by the GENERATOR, which emits BOTH the with-segment
+ * and without-segment keys as separate `WebjsRoutes` entries (so `/docs` and
+ * `/docs/a/b` both satisfy a `/docs/[[...slug]]` route). Keeping that collapse
+ * in the generator (not in pure types) avoids the fragile `//`-collapse, so
+ * `RoutePattern` only ever needs the single-segment `[x]` and catch-all
+ * `[...x]` cases.
+ */
+type RoutePattern<K extends string> =
+  K extends `${infer A}[...${string}]${infer B}`
+    ? `${A}${string}${RoutePattern<B>}`
+    : K extends `${infer A}[${string}]${infer B}`
+      ? `${A}${string}${RoutePattern<B>}`
+      : K;
+
+/**
+ * The valid-href type. `string` when no routes are generated (so `navigate()`
+ * and JSDoc apps are never broken); once `WebjsRoutes` is augmented it is the
+ * union of every static route literal PLUS a template-literal pattern per
+ * dynamic route.
+ */
+export type Route = _HasRoutes extends true
+  ? { [K in keyof WebjsRoutes]: RoutePattern<K & string> }[keyof WebjsRoutes]
+  : string;
+
+/**
+ * The params object for a route key. A generated dynamic route resolves to
+ * its `RouteParamMap` entry (`{ slug: string }`, `{ rest: string[] }`,
+ * `{ slug?: string[] }`); anything else (a static route, or any route in an
+ * un-generated app) resolves to `Record<string, string>`, the runtime
+ * default the SSR pipeline produces.
+ */
+export type RouteParams<R extends string> = R extends keyof RouteParamMap
+  ? RouteParamMap[R]
+  : Record<string, string>;
+
+/**
+ * The argument a page default-export receives. Mirrors the `ctx` object
+ * packages/server/src/ssr.js builds: `{ params, searchParams, url,
+ * actionData }`.
+ *
+ * `searchParams` is typed `Record<string, string | string[]>` to match the
+ * established page-context convention, even though the runtime builds it with
+ * `Object.fromEntries(url.searchParams.entries())` (so a repeated key is
+ * last-wins `string`, never an array). The wider type keeps a future
+ * multi-value reader source-compatible.
+ */
+export interface PageProps<R extends string = string> {
+  /**
+   * Path params. A generated dynamic route narrows this to its exact shape
+   * (`{ slug: string }`); a static or un-generated route is
+   * `Record<string, string>`.
+   */
+  params: R extends keyof RouteParamMap ? RouteParamMap[R] : Record<string, string>;
+  /** Query string, as an object. Repeated keys are last-wins at runtime. */
+  searchParams: Record<string, string | string[]>;
+  /** The full request URL string. */
+  url: string;
+  /**
+   * Present ONLY on the re-render after a failed page `action` submission
+   * (#244). `undefined` on a normal GET render. Read `actionData.fieldErrors`
+   * / `actionData.values` to surface validation errors and repopulate inputs.
+   */
+  actionData?: unknown;
+}
+
+/**
+ * The argument a layout default-export receives: every `PageProps` field plus
+ * the rendered `children`. Mirrors the `{ children, params, searchParams, url
+ * }` object packages/server/src/ssr.js passes a layout.
+ */
+export interface LayoutProps<R extends string = string> extends PageProps<R> {
+  /** The nested page / inner-layout content this layout must embed. */
+  children: TemplateResult;
+}
+
+/**
+ * The 2nd argument a `route.{js,ts}` `GET` / `POST` / … handler receives.
+ * Mirrors what packages/server/src/api.js passes: `{ params }`. The params
+ * are a plain `Record<string, string>` at the handler layer (the route table
+ * decodes each captured segment to a string), with an optional `R` generic to
+ * narrow them against a generated route the same way `PageProps` does.
+ */
+export interface RouteHandlerContext<R extends string = string> {
+  params: R extends keyof RouteParamMap ? RouteParamMap[R] : Record<string, string>;
+}

package/src/webjs-config.d.ts

@@ -0,0 +1,179 @@
+/**
+ * TypeScript overlay for the `webjs` config block in a webjs app's
+ * package.json.
+ *
+ *     // package.json is JSON, so author it there, but a typed reference
+ *     // helps an agent or a human author the block correctly:
+ *     import type { WebjsConfig } from '@webjsdev/core';
+ *     const config: WebjsConfig = { trailingSlash: 'never', csp: true };
+ *
+ * The server reads this object key by key. Without a type or schema a
+ * typo'd key (e.g. `redirect` for `redirects`) was silently dropped and
+ * the feature stayed at its default with no diagnostic. This type plus
+ * the published JSON Schema close that gap.
+ *
+ * LOCKSTEP: this file, the JSON Schema at
+ * packages/server/webjs-config.schema.json, and the server reader
+ * functions MUST stay in sync. The readers are: readElideEnabled
+ * (dev.js, elide), compileHeaderRules (headers.js, headers),
+ * compileRedirectRules / readTrailingSlashPolicy (redirects.js,
+ * redirects / trailingSlash), readBasePath (base-path.js, basePath),
+ * readCspConfig (csp.js, csp), and
+ * readBodyLimits / computeServerTimeouts (body-limit.js, the byte caps
+ * and timeouts). Adding a `webjs.*` key means updating all three places.
+ * See packages/server/AGENTS.md for the one documented procedure.
+ *
+ * Every key is optional (the whole block is optional and every key has a
+ * default). Zero runtime cost: nothing in this file ships to the browser.
+ */
+
+/** One header directive in a `webjs.headers` rule. */
+export interface WebjsHeaderDirective {
+  /** Header name, e.g. `X-Frame-Options`. */
+  key: string;
+  /**
+   * Header value. A `null` or `false` value REMOVES the header on a
+   * match, the escape hatch that drops a secure default on a path.
+   * `true` is intentionally not allowed (the runtime would stringify it
+   * to the literal `"true"`, which is never a useful header value).
+   */
+  value?: string | null | false;
+}
+
+/** One per-path response-header rule in `webjs.headers`. */
+export interface WebjsHeaderRule {
+  /**
+   * Path pattern matched with the native URLPattern API, so `:param` and
+   * `:rest*` syntax works.
+   */
+  source: string;
+  /** Header directives applied on a match. */
+  headers: WebjsHeaderDirective[];
+}
+
+/** One declarative redirect rule in `webjs.redirects`. */
+export interface WebjsRedirectRule {
+  /**
+   * Path pattern matched with the native URLPattern API, so `:param` and
+   * `:rest*` syntax works.
+   */
+  source: string;
+  /**
+   * Target path, a path referencing named groups captured by `source`,
+   * or an absolute URL. The incoming query string is preserved and
+   * merged onto the destination.
+   */
+  destination: string;
+  /**
+   * `true` (the default) is a 308 Permanent Redirect, `false` is a 307
+   * Temporary Redirect. Both preserve the request method and body.
+   * `statusCode` wins over this when set.
+   */
+  permanent?: boolean;
+  /**
+   * Explicit redirect status, for a tool needing a legacy code. Wins
+   * over `permanent`. One of 301, 302, 303, 307, 308.
+   */
+  statusCode?: 301 | 302 | 303 | 307 | 308;
+}
+
+/** The trailing-slash canonicalization policy in `webjs.trailingSlash`. */
+export type WebjsTrailingSlash = 'never' | 'always' | 'ignore';
+
+/** The object form of `webjs.csp` (the non-boolean shape). */
+export interface WebjsCspConfig {
+  /**
+   * Directive map merged over the strict defaults, e.g.
+   * `{ 'connect-src': "'self' https://api.example.com" }`. A `null` /
+   * `false` / `''` value drops a default directive. A `__NONCE__` token
+   * in a value is replaced with the per-request nonce.
+   */
+  directives?: Record<string, string | null | boolean>;
+  /**
+   * `true` emits `Content-Security-Policy-Report-Only` instead of the
+   * enforcing header (the staged-rollout path).
+   */
+  reportOnly?: boolean;
+}
+
+/**
+ * The `webjs` object in a webjs app's package.json. Every key is
+ * optional. Mirrors what the server readers actually consume, NOT a
+ * Next.js superset.
+ */
+export interface WebjsConfig {
+  /**
+   * Display-only and inert-route dead-JS elision switch. Default `true`.
+   * Set to `false` to ship every module's JS app-wide. The `WEBJS_ELIDE`
+   * env override wins over this.
+   */
+  elide?: boolean;
+
+  /** Per-path response-header rules, shaped like Next's. */
+  headers?: WebjsHeaderRule[];
+
+  /** Declarative permanent / temporary redirects for moved URLs. */
+  redirects?: WebjsRedirectRule[];
+
+  /**
+   * Trailing-slash canonicalization policy. Default `'ignore'` (no-op).
+   * `'never'` strips a trailing slash, `'always'` adds one (both via a
+   * 308 redirect).
+   */
+  trailingSlash?: WebjsTrailingSlash;
+
+  /**
+   * Sub-path deployment prefix for an app mounted under
+   * `example.com/app/` behind a proxy that does NOT strip the prefix.
+   * `'app'`, `'/app'`, and `'/app/'` all normalize to `'/app'`; an empty
+   * value (the default) is a root mount and a pure no-op. The prefix is
+   * stripped from the incoming path at ingress and prepended to every
+   * framework-emitted URL (importmap targets, modulepreload hints, boot
+   * module specifiers, the dev reload src). Author-written `<a href>`
+   * links and client-router navigation are NOT auto-prefixed (a
+   * documented follow-up).
+   */
+  basePath?: string;
+
+  /**
+   * Content-Security-Policy config. Off by default. `true` enables a
+   * strict nonce-based default policy. An object customizes directives
+   * and report-only mode.
+   */
+  csp?: boolean | WebjsCspConfig;
+
+  /**
+   * JSON / RPC request body cap in bytes. Default 1048576 (1 MiB). `0`
+   * disables the cap. The `WEBJS_MAX_BODY_BYTES` env override wins.
+   */
+  maxBodyBytes?: number;
+
+  /**
+   * Form / multipart request body cap in bytes. Default 10485760 (10
+   * MiB). `0` disables the cap. The `WEBJS_MAX_MULTIPART_BYTES` env
+   * override wins.
+   */
+  maxMultipartBytes?: number;
+
+  /**
+   * Max time in ms to receive the ENTIRE request (headers plus body).
+   * Default 30000. `0` disables the timeout. The
+   * `WEBJS_REQUEST_TIMEOUT_MS` env override wins.
+   */
+  requestTimeoutMs?: number;
+
+  /**
+   * Max time in ms to receive just the request headers. Default 20000.
+   * Clamped strictly under `requestTimeoutMs` per node semantics. `0`
+   * disables the timeout. The `WEBJS_HEADERS_TIMEOUT_MS` env override
+   * wins.
+   */
+  headersTimeoutMs?: number;
+
+  /**
+   * Idle time in ms before a kept-alive socket is closed. Default 5000.
+   * `0` disables the timeout. The `WEBJS_KEEP_ALIVE_TIMEOUT_MS` env
+   * override wins.
+   */
+  keepAliveTimeoutMs?: number;
+}