@rsc-kit/core 0.18.0 → 0.19.0

package/dist/openapi.d.ts

@@ -0,0 +1,74 @@
+/** What the generated entry hands over for each route.ts. */
+export interface OpenApiRoute {
+    /** The route's pattern in this package's spelling: `/api/orders/[id]`. */
+    pattern: string;
+    methods: string[];
+    /** The middleware.ts files above it: a guarded route gets a security requirement. */
+    guarded: boolean;
+    /** The route module: its params, searchParams, body and openapi exports, if any. */
+    module: Record<string, unknown>;
+}
+export interface OpenApiInfo {
+    title?: string;
+    version?: string;
+    description?: string;
+}
+/**
+ * What the document says that no route can: where the API is served, and
+ * how a caller authenticates. Spread onto the document as written, so
+ * anything OpenAPI allows at the top level is allowed here.
+ */
+export interface OpenApiDocumentOptions {
+    /**
+     * Which routes the document describes. `'all'` (the default) is every
+     * route.ts that did not opt out; `'declared'` is only the ones that
+     * export `openapi`, for an app whose routes are mostly webhooks and
+     * callbacks with a handful of endpoints meant for a caller to read about.
+     */
+    include?: "all" | "declared";
+    info?: OpenApiInfo;
+    servers?: {
+        url: string;
+        description?: string;
+    }[];
+    security?: Record<string, string[]>[];
+    components?: Record<string, unknown>;
+    tags?: {
+        name: string;
+        description?: string;
+    }[];
+}
+/**
+ * What a route.ts may say about itself, beside its handler:
+ *
+ *     export const openapi = {
+ *       summary: 'Chat completions',
+ *       tags: ['Chat'],
+ *       responses: { 200: { description: 'The completion', content: { … } } },
+ *     }
+ *
+ * Merged onto every operation the file exports, or per method when keyed
+ * by one: `{ POST: { summary: … } }`. Anything OpenAPI allows on an operation.
+ * `false` leaves the route out of the document altogether; `{ DELETE: false }`
+ * leaves one method out. HEAD and OPTIONS are never documented: the engine
+ * answers them for every route.
+ */
+export type OpenApiOperationExtras = Record<string, unknown>;
+/** `/api/orders/[id]/route` → `/api/orders/{id}`, and the names it binds. */
+export declare function openApiPath(pattern: string): {
+    path: string;
+    params: string[];
+};
+/**
+ * The document.
+ *
+ * Path parameters come from the pattern, typed by the route's `params` schema
+ * where it has one and as strings otherwise; query parameters from the
+ * `searchParams` schema's properties, each optional unless the schema
+ * requires it; a request body from the `body` schema, as JSON. A guarded
+ * route names the session as its security requirement, which is what a
+ * middleware.ts above it checks.
+ */
+export declare function buildOpenApi(routes: OpenApiRoute[], options?: OpenApiDocumentOptions): Record<string, unknown>;
+/** The document, as a route answers it: JSON, cacheable, built once. */
+export declare function openApiResponse(routes: OpenApiRoute[], options?: OpenApiDocumentOptions): Response;

package/dist/openapi.js

@@ -0,0 +1,172 @@
+// An OpenAPI document from the route tree, and a page that reads it.
+//
+// Every route.ts already says what an operation needs: the methods it
+// exports, and the params, searchParams and body schemas beside them. A
+// Standard Schema describes itself as JSON Schema (Zod 4 and ArkType do;
+// Valibot needs its converter and contributes nothing here), so the document
+// is derived rather than written - the way Elysia derives its from TypeBox.
+// Nothing is annotated twice.
+//
+// The document is built from the modules the generated entry imported, and
+// stored by the build like any other api route that reads nothing per
+// request. The page that reads it is Scalar's own package, mounted as a
+// route: `export const GET = ApiReference({ url: '/openapi.json' })`.
+const METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+/** The extras a route declared for one method: the shared ones, then that method's. */
+function extrasFor(module, method) {
+    const declared = module.openapi;
+    if (declared === null || typeof declared !== "object")
+        return {};
+    const record = declared;
+    const shared = {};
+    const own = (record[method] ?? {});
+    for (const [key, value] of Object.entries(record)) {
+        if (!METHODS.has(key))
+            shared[key] = value;
+    }
+    return { ...shared, ...own };
+}
+/** A Standard Schema's JSON Schema, or null when it cannot describe itself. */
+function jsonSchemaOf(schema) {
+    if (schema === null || typeof schema !== "object")
+        return null;
+    try {
+        const produce = schema["~standard"]?.jsonSchema?.input;
+        if (typeof produce !== "function")
+            return null;
+        // A leaf JSON Schema cannot say - a Date, a custom check - documents as
+        // `{}` rather than costing the route its whole body schema.
+        const json = produce({ target: "draft-2020-12", libraryOptions: { unrepresentable: "any" } });
+        // The dialect marker belongs on the document, not on every schema in it.
+        delete json.$schema;
+        return json;
+    }
+    catch {
+        return null;
+    }
+}
+/** `/api/orders/[id]/route` → `/api/orders/{id}`, and the names it binds. */
+export function openApiPath(pattern) {
+    const params = [];
+    const path = pattern.replace(/\[(?:\.\.\.)?(\w+)\]/g, (_, name) => {
+        params.push(name);
+        return `{${name}}`;
+    });
+    return { path, params };
+}
+const HAS_BODY = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/**
+ * The document.
+ *
+ * Path parameters come from the pattern, typed by the route's `params` schema
+ * where it has one and as strings otherwise; query parameters from the
+ * `searchParams` schema's properties, each optional unless the schema
+ * requires it; a request body from the `body` schema, as JSON. A guarded
+ * route names the session as its security requirement, which is what a
+ * middleware.ts above it checks.
+ */
+export function buildOpenApi(routes, options = {}) {
+    const { info = {}, include = "all", ...rest } = options;
+    const paths = {};
+    let anyGuarded = false;
+    for (const route of routes) {
+        // `export const openapi = false`: a route that is not part of the API -
+        // the page that renders this document, a webhook for one caller. With
+        // include: 'declared', a route with no `openapi` export is the same.
+        if (route.module.openapi === false)
+            continue;
+        if (include === "declared" && route.module.openapi === undefined)
+            continue;
+        const { path, params } = openApiPath(route.pattern);
+        const paramsSchema = jsonSchemaOf(route.module.params);
+        const searchSchema = jsonSchemaOf(route.module.searchParams);
+        const bodySchema = jsonSchemaOf(route.module.body);
+        const pathParameters = params.map((name) => ({
+            name,
+            in: "path",
+            required: true,
+            schema: paramsSchema?.properties?.[name] ?? { type: "string" },
+        }));
+        const queryParameters = Object.entries(searchSchema?.properties ?? {}).map(([name, schema]) => ({
+            name,
+            in: "query",
+            required: searchSchema?.required?.includes(name) ?? false,
+            schema,
+        }));
+        const operations = {};
+        for (const method of route.methods) {
+            // HEAD and OPTIONS are answered for every route by the engine, and a
+            // file that exports one - a CORS preflight - is not documenting an
+            // operation. `openapi: { OPTIONS: false }` drops any other method.
+            if (method === "HEAD" || method === "OPTIONS")
+                continue;
+            if ((route.module.openapi?.[method]) === false)
+                continue;
+            const operation = {
+                operationId: `${method.toLowerCase()}${path
+                    .replace(/\{(\w+)\}/g, "By$1")
+                    .split("/")
+                    .filter(Boolean)
+                    .map((part) => part[0].toUpperCase() + part.slice(1))
+                    .join("")}`,
+                parameters: [...pathParameters, ...queryParameters],
+                responses: { "200": { description: "OK" } },
+            };
+            if (bodySchema && HAS_BODY.has(method)) {
+                operation.requestBody = {
+                    required: true,
+                    content: { "application/json": { schema: bodySchema } },
+                };
+                operation.responses["422"] = {
+                    description: "The input was refused; validationErrors names each field.",
+                };
+            }
+            if (route.guarded) {
+                anyGuarded = true;
+                operation.security = [{ session: [] }];
+                operation.responses["401"] = { description: "Not signed in." };
+                operation.responses["403"] = { description: "Signed in, and still not allowed." };
+            }
+            // What the route said about itself wins over what was derived, field
+            // by field; its responses merge onto the derived ones.
+            const extras = extrasFor(route.module, method);
+            const responses = { ...operation.responses, ...(extras.responses ?? {}) };
+            operations[method.toLowerCase()] = { ...operation, ...extras, responses };
+        }
+        paths[path] = { ...(paths[path] ?? {}), ...operations };
+    }
+    const document = {
+        openapi: "3.1.0",
+        info: {
+            title: info.title ?? "API",
+            version: info.version ?? "0.0.0",
+            ...(info.description ? { description: info.description } : {}),
+        },
+        ...rest,
+        paths,
+    };
+    if (anyGuarded) {
+        const components = (rest.components ?? {});
+        const schemes = (components.securitySchemes ?? {});
+        document.components = {
+            ...components,
+            securitySchemes: {
+                session: {
+                    type: "apiKey",
+                    in: "cookie",
+                    name: "session",
+                    description: "The visitor's session, checked by the middleware.ts above the route.",
+                },
+                ...schemes,
+            },
+        };
+    }
+    return document;
+}
+/** The document, as a route answers it: JSON, cacheable, built once. */
+export function openApiResponse(routes, options = {}) {
+    return Response.json(buildOpenApi(routes, options), {
+        headers: { "Cache-Control": "public, max-age=300" },
+    });
+}
+//# sourceMappingURL=openapi.js.map

package/dist/openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"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","sourcesContent":["// An OpenAPI document from the route tree, and a page that reads it.\n//\n// Every route.ts already says what an operation needs: the methods it\n// exports, and the params, searchParams and body schemas beside them. A\n// Standard Schema describes itself as JSON Schema (Zod 4 and ArkType do;\n// Valibot needs its converter and contributes nothing here), so the document\n// is derived rather than written - the way Elysia derives its from TypeBox.\n// Nothing is annotated twice.\n//\n// The document is built from the modules the generated entry imported, and\n// stored by the build like any other api route that reads nothing per\n// request. The page that reads it is Scalar's own package, mounted as a\n// route: `export const GET = ApiReference({ url: '/openapi.json' })`.\n\ntype JsonSchema = Record<string, unknown> & {\n  type?: string | string[];\n  properties?: Record<string, JsonSchema>;\n  required?: string[];\n};\n\ntype WithJsonSchema = {\n  \"~standard\"?: {\n    jsonSchema?: {\n      input?: (options: { target: string; libraryOptions?: Record<string, unknown> }) => unknown;\n    };\n  };\n};\n\n/** What the generated entry hands over for each route.ts. */\nexport interface OpenApiRoute {\n  /** The route's pattern in this package's spelling: `/api/orders/[id]`. */\n  pattern: string;\n  methods: string[];\n  /** The middleware.ts files above it: a guarded route gets a security requirement. */\n  guarded: boolean;\n  /** The route module: its params, searchParams, body and openapi exports, if any. */\n  module: Record<string, unknown>;\n}\n\nconst METHODS = new Set([\"GET\", \"POST\", \"PUT\", \"PATCH\", \"DELETE\"]);\n\n/** The extras a route declared for one method: the shared ones, then that method's. */\nfunction extrasFor(module: Record<string, unknown>, method: string): OpenApiOperationExtras {\n  const declared = module.openapi;\n\n  if (declared === null || typeof declared !== \"object\") return {};\n\n  const record = declared as Record<string, unknown>;\n  const shared: Record<string, unknown> = {};\n  const own = (record[method] ?? {}) as Record<string, unknown>;\n\n  for (const [key, value] of Object.entries(record)) {\n    if (!METHODS.has(key)) shared[key] = value;\n  }\n\n  return { ...shared, ...own };\n}\n\nexport interface OpenApiInfo {\n  title?: string;\n  version?: string;\n  description?: string;\n}\n\n/**\n * What the document says that no route can: where the API is served, and\n * how a caller authenticates. Spread onto the document as written, so\n * anything OpenAPI allows at the top level is allowed here.\n */\nexport interface OpenApiDocumentOptions {\n  /**\n   * Which routes the document describes. `'all'` (the default) is every\n   * route.ts that did not opt out; `'declared'` is only the ones that\n   * export `openapi`, for an app whose routes are mostly webhooks and\n   * callbacks with a handful of endpoints meant for a caller to read about.\n   */\n  include?: \"all\" | \"declared\";\n  info?: OpenApiInfo;\n  servers?: { url: string; description?: string }[];\n  security?: Record<string, string[]>[];\n  components?: Record<string, unknown>;\n  tags?: { name: string; description?: string }[];\n}\n\n/**\n * What a route.ts may say about itself, beside its handler:\n *\n *     export const openapi = {\n *       summary: 'Chat completions',\n *       tags: ['Chat'],\n *       responses: { 200: { description: 'The completion', content: { … } } },\n *     }\n *\n * Merged onto every operation the file exports, or per method when keyed\n * by one: `{ POST: { summary: … } }`. Anything OpenAPI allows on an operation.\n * `false` leaves the route out of the document altogether; `{ DELETE: false }`\n * leaves one method out. HEAD and OPTIONS are never documented: the engine\n * answers them for every route.\n */\nexport type OpenApiOperationExtras = Record<string, unknown>;\n\n/** A Standard Schema's JSON Schema, or null when it cannot describe itself. */\nfunction jsonSchemaOf(schema: unknown): JsonSchema | null {\n  if (schema === null || typeof schema !== \"object\") return null;\n\n  try {\n    const produce = (schema as WithJsonSchema)[\"~standard\"]?.jsonSchema?.input;\n\n    if (typeof produce !== \"function\") return null;\n\n    // A leaf JSON Schema cannot say - a Date, a custom check - documents as\n    // `{}` rather than costing the route its whole body schema.\n    const json = produce({ target: \"draft-2020-12\", libraryOptions: { unrepresentable: \"any\" } }) as JsonSchema;\n\n    // The dialect marker belongs on the document, not on every schema in it.\n    delete json.$schema;\n\n    return json;\n  } catch {\n    return null;\n  }\n}\n\n/** `/api/orders/[id]/route` → `/api/orders/{id}`, and the names it binds. */\nexport function openApiPath(pattern: string): { path: string; params: string[] } {\n  const params: string[] = [];\n  const path = pattern.replace(/\\[(?:\\.\\.\\.)?(\\w+)\\]/g, (_, name: string) => {\n    params.push(name);\n\n    return `{${name}}`;\n  });\n\n  return { path, params };\n}\n\nconst HAS_BODY = new Set([\"POST\", \"PUT\", \"PATCH\", \"DELETE\"]);\n\n/**\n * The document.\n *\n * Path parameters come from the pattern, typed by the route's `params` schema\n * where it has one and as strings otherwise; query parameters from the\n * `searchParams` schema's properties, each optional unless the schema\n * requires it; a request body from the `body` schema, as JSON. A guarded\n * route names the session as its security requirement, which is what a\n * middleware.ts above it checks.\n */\nexport function buildOpenApi(routes: OpenApiRoute[], options: OpenApiDocumentOptions = {}): Record<string, unknown> {\n  const { info = {}, include = \"all\", ...rest } = options;\n  const paths: Record<string, Record<string, unknown>> = {};\n  let anyGuarded = false;\n\n  for (const route of routes) {\n    // `export const openapi = false`: a route that is not part of the API -\n    // the page that renders this document, a webhook for one caller. With\n    // include: 'declared', a route with no `openapi` export is the same.\n    if (route.module.openapi === false) continue;\n    if (include === \"declared\" && route.module.openapi === undefined) continue;\n\n    const { path, params } = openApiPath(route.pattern);\n    const paramsSchema = jsonSchemaOf(route.module.params);\n    const searchSchema = jsonSchemaOf(route.module.searchParams);\n    const bodySchema = jsonSchemaOf(route.module.body);\n\n    const pathParameters = params.map((name) => ({\n      name,\n      in: \"path\",\n      required: true,\n      schema: paramsSchema?.properties?.[name] ?? { type: \"string\" },\n    }));\n\n    const queryParameters = Object.entries(searchSchema?.properties ?? {}).map(([name, schema]) => ({\n      name,\n      in: \"query\",\n      required: searchSchema?.required?.includes(name) ?? false,\n      schema,\n    }));\n\n    const operations: Record<string, unknown> = {};\n\n    for (const method of route.methods) {\n      // HEAD and OPTIONS are answered for every route by the engine, and a\n      // file that exports one - a CORS preflight - is not documenting an\n      // operation. `openapi: { OPTIONS: false }` drops any other method.\n      if (method === \"HEAD\" || method === \"OPTIONS\") continue;\n      if (((route.module.openapi as Record<string, unknown> | undefined)?.[method]) === false) continue;\n\n      const operation: Record<string, unknown> = {\n        operationId: `${method.toLowerCase()}${path\n          .replace(/\\{(\\w+)\\}/g, \"By$1\")\n          .split(\"/\")\n          .filter(Boolean)\n          .map((part) => part[0].toUpperCase() + part.slice(1))\n          .join(\"\")}`,\n        parameters: [...pathParameters, ...queryParameters],\n        responses: { \"200\": { description: \"OK\" } },\n      };\n\n      if (bodySchema && HAS_BODY.has(method)) {\n        operation.requestBody = {\n          required: true,\n          content: { \"application/json\": { schema: bodySchema } },\n        };\n        (operation.responses as Record<string, unknown>)[\"422\"] = {\n          description: \"The input was refused; validationErrors names each field.\",\n        };\n      }\n\n      if (route.guarded) {\n        anyGuarded = true;\n        operation.security = [{ session: [] }];\n        (operation.responses as Record<string, unknown>)[\"401\"] = { description: \"Not signed in.\" };\n        (operation.responses as Record<string, unknown>)[\"403\"] = { description: \"Signed in, and still not allowed.\" };\n      }\n\n      // What the route said about itself wins over what was derived, field\n      // by field; its responses merge onto the derived ones.\n      const extras = extrasFor(route.module, method);\n      const responses = { ...(operation.responses as object), ...((extras.responses as object) ?? {}) };\n\n      operations[method.toLowerCase()] = { ...operation, ...extras, responses };\n    }\n\n    paths[path] = { ...(paths[path] ?? {}), ...operations };\n  }\n\n  const document: Record<string, unknown> = {\n    openapi: \"3.1.0\",\n    info: {\n      title: info.title ?? \"API\",\n      version: info.version ?? \"0.0.0\",\n      ...(info.description ? { description: info.description } : {}),\n    },\n    ...rest,\n    paths,\n  };\n\n  if (anyGuarded) {\n    const components = (rest.components ?? {}) as Record<string, unknown>;\n    const schemes = (components.securitySchemes ?? {}) as Record<string, unknown>;\n\n    document.components = {\n      ...components,\n      securitySchemes: {\n        session: {\n          type: \"apiKey\",\n          in: \"cookie\",\n          name: \"session\",\n          description: \"The visitor's session, checked by the middleware.ts above the route.\",\n        },\n        ...schemes,\n      },\n    };\n  }\n\n  return document;\n}\n\n/** The document, as a route answers it: JSON, cacheable, built once. */\nexport function openApiResponse(routes: OpenApiRoute[], options: OpenApiDocumentOptions = {}): Response {\n  return Response.json(buildOpenApi(routes, options), {\n    headers: { \"Cache-Control\": \"public, max-age=300\" },\n  });\n}\n"]}

package/dist/prerender.js

@@ -51,6 +51,7 @@ const DEFAULT_PRERENDER_CONCURRENCY = 4;
 const RUNTIME_OWN = new Set([
     "DefaultRouteError",
     "DocumentTitle",
+    "LoadingBoundary",
     "PathnameProvider",
     "RouteErrorBoundary",
     "SegmentBoundary",