princejs 1.9.2 → 1.9.4

package/Readme.md

@@ -105,6 +105,55 @@ const app = prince();
 app.plugin(usersPlugin, { prefix: "/api" });
 ```
 
+### OpenAPI + Scalar Docs
+
+Auto-generate an OpenAPI 3.0 spec and serve a beautiful [Scalar](https://scalar.com) API reference UI — all from a single `app.openapi()` call. Routes, validation, and docs stay in sync automatically.
+
+```ts
+import { prince } from "princejs";
+import { z } from "zod";
+
+const app = prince();
+
+const api = app.openapi({ title: "My API", version: "1.0.0" }, "/docs", { theme: "moon" });
+
+api.route("GET", "/users/:id", {
+  summary: "Get user by ID",
+  tags: ["users"],
+  schema: {
+    response: z.object({ id: z.string(), name: z.string() }),
+  },
+}, (req) => ({ id: req.params!.id, name: "Alice" }));
+
+api.route("POST", "/users", {
+  summary: "Create user",
+  tags: ["users"],
+  schema: {
+    body:     z.object({ name: z.string().min(2), email: z.string().email() }),
+    response: z.object({ id: z.string(), name: z.string(), email: z.string() }),
+  },
+}, (req) => ({ id: crypto.randomUUID(), ...req.parsedBody }));
+
+app.listen(3000);
+// → GET /docs       Scalar UI
+// → GET /docs.json  Raw OpenAPI JSON
+```
+
+**`api.route()` does three things at once:**
+- Registers the route on PrinceJS (same as `app.get()` / `app.post()`)
+- Auto-wires `validate(schema.body)` middleware — no separate import needed
+- Writes the full OpenAPI spec entry including path params, request body, query params, and response schema
+
+| `schema` key | Runtime effect | Scalar docs |
+|---|---|---|
+| `body` | ✅ Validates & strips via `validate()` | ✅ requestBody model |
+| `query` | ❌ docs only | ✅ typed query params |
+| `response` | ❌ docs only | ✅ 200 response model |
+
+Routes registered with `app.get()` / `app.post()` directly never appear in the docs — useful for internal health checks, webhooks, and admin endpoints.
+
+**Available themes:** `default` · `moon` · `purple` · `solarized` · `bluePlanet` · `deepSpace` · `saturn` · `kepler` · `mars`
+
 ### Database (SQLite)
 
 ### End to End Type-Safety
@@ -203,7 +252,7 @@ import { prince } from "princejs";
 import { cors, logger, rateLimit, auth, apiKey, jwt, session, compress, serve } from "princejs/middleware";
 import { validate } from "princejs/validation";
 import { cache, upload, sse } from "princejs/helpers";
-import { cron } from "princejs/scheduler";
+import { cron, openapi } from "princejs/scheduler";
 import { Html, Head, Body, H1, P, render } from "princejs/jsx"
 import { db } from "princejs/db";
 import { z } from "zod";
@@ -285,6 +334,17 @@ app.get("/users", () => users.query("SELECT * FROM users"));
 
 cron("*/1 * * * *", () => console.log("PrinceJS heartbeat"));
 
+// OpenAPI + Scalar
+const api = app.openapi({ title: "PrinceJS App", version: "1.0.0" }, "/docs");
+api.route("GET", "/items", {
+  summary: "List items",
+  tags: ["items"],
+  schema: {
+    query:    z.object({ q: z.string().optional() }),
+    response: z.array(z.object({ id: z.string(), name: z.string() })),
+  },
+}, () => [{ id: "1", name: "Widget" }]);
+
 app.listen(3000);
 ```
 

package/dist/prince.d.ts

@@ -1,3 +1,5 @@
+import type { OpenAPIBuilder, ScalarOptions } from "./scheduler";
+import { z } from "zod";
 type Next = () => Promise<Response>;
 type Middleware = (req: PrinceRequest, next: Next) => Promise<Response | undefined> | Response | undefined;
 type HandlerResult = Response | Record<string, any> | string | Uint8Array;
@@ -32,13 +34,30 @@ declare class ResponseBuilder {
     redirect(url: string, status?: number): Response;
     build(): Response;
 }
+export interface RouteSchema {
+    /** Zod schema for the request body — auto-wires validate() middleware */
+    body?: z.ZodTypeAny;
+    /** Zod schema for query parameters — written into the OpenAPI spec */
+    query?: z.ZodObject<any>;
+    /** Zod schema for the response body — written into the OpenAPI spec */
+    response?: z.ZodTypeAny;
+}
+export interface RouteOperation {
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    /** Attach Zod schemas to auto-generate request/response models in Scalar */
+    schema?: RouteSchema;
+    responses?: Record<string, unknown>;
+    [key: string]: unknown;
+}
 export declare class Prince {
     private devMode;
     private rawRoutes;
     private middlewares;
     private errorHandler?;
     private wsRoutes;
-    private openapiData;
+    private openapiSpec;
     private router;
     private staticRoutes;
     private staticMiddlewares;
@@ -77,6 +96,37 @@ export declare class Prince {
     private executeHandler;
     handleFetch(req: Request): Promise<Response>;
     fetch(req: Request): Promise<Response>;
+    /**
+     * Mounts an OpenAPI spec + Scalar UI onto this Prince app.
+     *
+     * Calling this method returns an `OpenAPIBuilder` whose `.route()` method
+     * registers a route on the Prince app **and** writes the matching path entry
+     * into the OpenAPI spec simultaneously — so the two can never drift.
+     *
+     * Two routes are auto-registered:
+     *   GET `docsPath`        → Scalar UI  (e.g. /docs)
+     *   GET `docsPath`.json   → Raw spec   (e.g. /docs.json)
+     *
+     * @example
+     * const app = prince();
+     * const api = app.openapi({ title: "My API", version: "1.0.0" }, "/docs");
+     *
+     * // Registers GET /hello on Prince AND adds it to the OpenAPI spec
+     * api.route("GET", "/hello", {
+     *   summary: "Say hello",
+     *   responses: { 200: { description: "OK" } },
+     * }, (req) => ({ message: "hello" }));
+     *
+     * app.listen(3000);
+     * // → GET /docs      → Scalar UI
+     * // → GET /docs.json → raw OpenAPI JSON
+     */
+    openapi(info: {
+        title: string;
+        version: string;
+    }, docsPath?: string, scalarOptions?: ScalarOptions): OpenAPIBuilder & {
+        route: (method: string, path: string, operation: Record<string, unknown>, ...args: (RouteHandler | Middleware)[]) => OpenAPIBuilder;
+    };
     listen(port?: number): void;
 }
 export declare const prince: (dev?: boolean) => Prince;

package/dist/prince.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prince.d.ts","sourceRoot":"","sources":["../src/prince.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"prince.d.ts","sourceRoot":"","sources":["../src/prince.ts"],"names":[],"mappings":"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"}

package/dist/prince.js

@@ -1,4 +1,123 @@
 // @bun
+// src/scheduler.ts
+var openapi = (info) => {
+  const spec = { openapi: "3.0.0", info, paths: {} };
+  const renderScalarHtml = (options = {}) => {
+    const {
+      pageTitle = spec.info.title,
+      theme = "default",
+      layout = "modern",
+      hideDownloadButton = false,
+      customCss = ""
+    } = options;
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${pageTitle}</title>
+    ${customCss ? `<style>${customCss}</style>` : ""}
+  </head>
+  <body>
+    <script
+      id="api-reference"
+      type="application/json"
+      data-theme="${theme}"
+      data-layout="${layout}"
+      ${hideDownloadButton ? 'data-hide-download-button="true"' : ""}
+    >${JSON.stringify(spec)}</script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  </body>
+</html>`;
+  };
+  return {
+    spec,
+    get openapi() {
+      return spec.openapi;
+    },
+    get info() {
+      return spec.info;
+    },
+    get paths() {
+      return spec.paths;
+    },
+    scalar(options = {}) {
+      return (_req, res) => {
+        const html = renderScalarHtml(options);
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(html);
+      };
+    },
+    json() {
+      return (_req, res) => {
+        res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+        res.end(JSON.stringify(spec, null, 2));
+      };
+    }
+  };
+};
+
+// src/prince.ts
+import { z } from "zod";
+
+// src/middleware.ts
+import { jwtVerify, SignJWT } from "jose";
+var validate = (schema) => {
+  return async (req, next) => {
+    let bodyData = req.parsedBody;
+    let bodyParsed = false;
+    if (!bodyData && ["POST", "PUT", "PATCH"].includes(req.method)) {
+      const ct = req.headers.get("content-type") || "";
+      if (ct.includes("application/json")) {
+        try {
+          const clonedReq = req.clone();
+          const text = await clonedReq.text();
+          if (text) {
+            bodyData = JSON.parse(text);
+            bodyParsed = true;
+          }
+        } catch (parseError) {
+          return new Response(JSON.stringify({ error: "Invalid JSON" }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+      } else if (ct.includes("application/x-www-form-urlencoded")) {
+        try {
+          const clonedReq = req.clone();
+          const text = await clonedReq.text();
+          bodyData = Object.fromEntries(new URLSearchParams(text));
+          bodyParsed = true;
+        } catch (parseError) {
+          return new Response(JSON.stringify({ error: "Invalid form data" }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+      }
+    }
+    if (bodyData) {
+      const result = schema.safeParse(bodyData);
+      if (!result.success) {
+        if (bodyParsed) {
+          req.parsedBody = bodyData;
+        }
+        return new Response(JSON.stringify({
+          error: "Validation failed",
+          details: result.error.issues.map((e) => ({
+            path: e.path.join("."),
+            message: e.message
+          }))
+        }), {
+          status: 400,
+          headers: { "Content-Type": "application/json" }
+        });
+      }
+      req.parsedBody = result.data;
+      Object.defineProperty(req, "body", {
+        value: result.data,
+        writable: true,
+        configurable: true
+      });
+    }
+    return next();
+  };
+};
+
 // src/prince.ts
 class ResponseBuilder {
   _status = 200;
@@ -36,6 +155,149 @@ class ResponseBuilder {
     return new Response(this._body, { status: this._status, headers: this._headers });
   }
 }
+function zodToJsonSchema(schema) {
+  const d = schema._def;
+  const typeName = d?.typeName ?? d?.type ?? "";
+  if (schema instanceof z.ZodString || typeName === "ZodString") {
+    const s = { type: "string" };
+    const checks = d.checks ?? [];
+    for (const c of checks) {
+      if (c.kind === "min")
+        s.minLength = c.value;
+      if (c.kind === "max")
+        s.maxLength = c.value;
+      if (c.kind === "email")
+        s.format = "email";
+      if (c.kind === "url")
+        s.format = "uri";
+      if (c.kind === "uuid")
+        s.format = "uuid";
+      if (c.kind === "regex")
+        s.pattern = c.regex?.source ?? c.pattern;
+      const def = c._zod?.def ?? {};
+      if (def.check === "min_length")
+        s.minLength = def.minimum;
+      if (def.check === "max_length")
+        s.maxLength = def.maximum;
+      if (def.check === "string_format") {
+        if (def.format === "email")
+          s.format = "email";
+        if (def.format === "url")
+          s.format = "uri";
+        if (def.format === "uuid")
+          s.format = "uuid";
+        if (def.format === "regex")
+          s.pattern = def.pattern;
+      }
+    }
+    return s;
+  }
+  if (schema instanceof z.ZodNumber || typeName === "ZodNumber") {
+    const s = { type: "number" };
+    const checks = d.checks ?? [];
+    for (const c of checks) {
+      if (c.kind === "min")
+        s.minimum = c.value ?? c.minimum;
+      if (c.kind === "max")
+        s.maximum = c.value ?? c.maximum;
+      if (c.kind === "int")
+        s.type = "integer";
+      if (c.kind === "multipleOf")
+        s.multipleOf = c.value;
+      const def = c._zod?.def ?? {};
+      if (def.check === "greater_than" || def.check === "greater_than_or_equal")
+        s.minimum = def.value;
+      if (def.check === "less_than" || def.check === "less_than_or_equal")
+        s.maximum = def.value;
+      if (def.check === "number_format" && (def.format === "safeint" || def.format === "int32" || def.format === "int64"))
+        s.type = "integer";
+      if (def.check === "multiple_of")
+        s.multipleOf = def.value;
+    }
+    return s;
+  }
+  if (schema instanceof z.ZodBoolean || typeName === "ZodBoolean")
+    return { type: "boolean" };
+  if (schema instanceof z.ZodNull || typeName === "ZodNull")
+    return { type: "null" };
+  if (schema instanceof z.ZodLiteral || typeName === "ZodLiteral") {
+    const val = d.value ?? d.values?.[0];
+    return { enum: [val] };
+  }
+  if (schema instanceof z.ZodEnum || typeName === "ZodEnum") {
+    const vals = d.values ?? (d.entries ? Object.values(d.entries) : undefined) ?? d.options ?? [];
+    return { type: "string", enum: vals };
+  }
+  if (schema instanceof z.ZodArray || typeName === "ZodArray") {
+    const items = d.element ?? d.type ?? d.items;
+    return { type: "array", items: items ? zodToJsonSchema(items) : {} };
+  }
+  if (schema instanceof z.ZodOptional || typeName === "ZodOptional" || schema instanceof z.ZodNullable || typeName === "ZodNullable") {
+    return zodToJsonSchema(d.innerType ?? d.type);
+  }
+  if (schema instanceof z.ZodDefault || typeName === "ZodDefault") {
+    const inner = zodToJsonSchema(d.innerType ?? d.type);
+    const dv = d.defaultValue ?? d.default;
+    return { ...inner, default: typeof dv === "function" ? dv() : dv };
+  }
+  if (schema instanceof z.ZodObject || typeName === "ZodObject") {
+    const shape = d.shape ?? {};
+    const properties = {};
+    const required = [];
+    for (const [key, val] of Object.entries(shape)) {
+      const v = val;
+      const vd = v._def;
+      const vType = vd?.typeName ?? vd?.type ?? "";
+      properties[key] = zodToJsonSchema(v);
+      const isOptional = v instanceof z.ZodOptional || vType === "ZodOptional" || v instanceof z.ZodDefault || vType === "ZodDefault";
+      if (!isOptional)
+        required.push(key);
+    }
+    return { type: "object", properties, ...required.length ? { required } : {} };
+  }
+  if (schema instanceof z.ZodUnion || typeName === "ZodUnion") {
+    return { oneOf: (d.options ?? []).map(zodToJsonSchema) };
+  }
+  if (schema instanceof z.ZodIntersection || typeName === "ZodIntersection") {
+    return { allOf: [d.left, d.right].map(zodToJsonSchema) };
+  }
+  if (schema instanceof z.ZodRecord || typeName === "ZodRecord") {
+    const valueSchema = d.valueType ?? d.valueSchema ?? d.element ?? (d.keyType && !d.valueType ? d.keyType : undefined);
+    return { type: "object", additionalProperties: valueSchema ? zodToJsonSchema(valueSchema) : {} };
+  }
+  return {};
+}
+function zodObjectToQueryParams(schema) {
+  const d = schema._def;
+  const shape = d.shape ?? {};
+  return Object.entries(shape).map(([name, val]) => {
+    const v = val;
+    const vTypeName = v._def?.typeName ?? v._def?.type ?? "";
+    const isOptional = v instanceof z.ZodOptional || vTypeName === "ZodOptional" || v instanceof z.ZodDefault || vTypeName === "ZodDefault";
+    return {
+      name,
+      in: "query",
+      required: !isOptional,
+      schema: zodToJsonSchema(v)
+    };
+  });
+}
+function buildResponses(responseSchema, existingResponses) {
+  const base = existingResponses ?? {};
+  if (!responseSchema)
+    return Object.keys(base).length ? base : { 200: { description: "OK" } };
+  return {
+    200: {
+      description: "OK",
+      content: {
+        "application/json": {
+          schema: zodToJsonSchema(responseSchema)
+        }
+      }
+    },
+    ...base
+  };
+}
 
 class Prince {
   devMode;
@@ -43,7 +305,7 @@ class Prince {
   middlewares = [];
   errorHandler;
   wsRoutes = {};
-  openapiData = null;
+  openapiSpec = null;
   router = null;
   staticRoutes = new Map;
   staticMiddlewares = new Map;
@@ -383,6 +645,56 @@ class Prince {
       return this.json({ error: "Internal Server Error" }, 500);
     }
   }
+  openapi(info, docsPath = "/docs", scalarOptions = {}) {
+    const builder = openapi(info);
+    this.openapiSpec = builder.spec;
+    const toOpenAPIPath = (p) => p.replace(/:([^/]+)/g, "{$1}");
+    this.get(docsPath, (req) => {
+      return new Response(renderScalarHTML(builder.spec, scalarOptions), { headers: { "Content-Type": "text/html; charset=utf-8" } });
+    });
+    const jsonPath = docsPath.replace(/\/$/, "") + ".json";
+    this.get(jsonPath, (_req) => new Response(JSON.stringify(builder.spec, null, 2), {
+      headers: { "Content-Type": "application/json; charset=utf-8" }
+    }));
+    const self = this;
+    builder.route = function(method, path, operation, ...args) {
+      const m = method.toUpperCase();
+      const { schema, responses: manualResponses, ...operationRest } = operation;
+      const middlewares = [];
+      if (schema?.body) {
+        middlewares.push(validate(schema.body));
+      }
+      middlewares.push(...args);
+      self.add(m, path, middlewares);
+      const oaPath = toOpenAPIPath(path);
+      if (!builder.spec.paths[oaPath])
+        builder.spec.paths[oaPath] = {};
+      const pathParams = [...path.matchAll(/:([^/]+)/g)].map(([, name]) => ({
+        name,
+        in: "path",
+        required: true,
+        schema: { type: "string" }
+      }));
+      const queryParams = schema?.query ? zodObjectToQueryParams(schema.query) : [];
+      const requestBody = schema?.body ? {
+        required: true,
+        content: {
+          "application/json": {
+            schema: zodToJsonSchema(schema.body)
+          }
+        }
+      } : undefined;
+      const responses = buildResponses(schema?.response, manualResponses);
+      builder.spec.paths[oaPath][m.toLowerCase()] = {
+        parameters: [...pathParams, ...queryParams],
+        ...requestBody ? { requestBody } : {},
+        responses,
+        ...operationRest
+      };
+      return builder;
+    };
+    return builder;
+  }
   listen(port = 3000) {
     const self = this;
     Bun.serve({
@@ -426,6 +738,34 @@ class Prince {
     console.log(`\uD83D\uDE80 PrinceJS running on http://localhost:${port}`);
   }
 }
+function renderScalarHTML(spec, options = {}) {
+  const {
+    pageTitle = spec.info.title ?? "API Reference",
+    theme = "default",
+    layout = "modern",
+    hideDownloadButton = false,
+    customCss = ""
+  } = options;
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${pageTitle}</title>
+    ${customCss ? `<style>${customCss}</style>` : ""}
+  </head>
+  <body>
+    <script
+      id="api-reference"
+      type="application/json"
+      data-theme="${theme}"
+      data-layout="${layout}"
+      ${hideDownloadButton ? 'data-hide-download-button="true"' : ""}
+    >${JSON.stringify(spec)}</script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  </body>
+</html>`;
+}
 var prince = (dev = false) => new Prince(dev);
 export {
   prince,

package/dist/scheduler.d.ts

@@ -1,13 +1,90 @@
 export declare const cron: (pattern: string, task: () => void) => void;
-export declare const openapi: (info: {
-    title: string;
-    version: string;
-}) => {
+export interface OpenAPISpec {
     openapi: string;
     info: {
         title: string;
         version: string;
+        [key: string]: unknown;
     };
-    paths: {};
-};
+    paths: Record<string, unknown>;
+    components?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface ScalarOptions {
+    /** Scalar theme. Options: "default" | "alternate" | "moon" | "purple" | "solarized" | "bluePlanet" | "deepSpace" | "saturn" | "kepler" | "mars" | "none" */
+    theme?: string;
+    /** Page title shown in the browser tab. Defaults to the spec's info.title. */
+    pageTitle?: string;
+    /** Layout mode. "modern" (default) or "classic" */
+    layout?: "modern" | "classic";
+    /** Hide the spec download button. */
+    hideDownloadButton?: boolean;
+    /** Custom CSS injected into the page. */
+    customCss?: string;
+}
+export interface OpenAPIBuilder {
+    /** The raw spec object — mutate this to add paths, components, etc. */
+    spec: OpenAPISpec;
+    /** Backward-compatible direct accessors — mirrors spec.openapi / .info / .paths */
+    readonly openapi: string;
+    readonly info: OpenAPISpec["info"];
+    readonly paths: OpenAPISpec["paths"];
+    /**
+     * Returns a plain-function route handler that serves the Scalar UI.
+     * Mount it on any path in your router.
+     *
+     * Works with any framework that uses `(req, res) => void` handlers
+     * (Node http, Express, Fastify inject, etc.).
+     *
+     * @example
+     * // Plain Node http
+     * server.on("request", (req, res) => {
+     *   if (req.url === "/docs")  return api.scalar()(req, res);
+     *   if (req.url === "/openapi.json") return api.json()(req, res);
+     * });
+     *
+     * @example
+     * // Express / Hono-style
+     * app.get("/docs", api.scalar({ theme: "moon" }));
+     * app.get("/openapi.json", api.json());
+     */
+    scalar(options?: ScalarOptions): (req: unknown, res: {
+        writeHead(status: number, headers: Record<string, string>): void;
+        end(body: string): void;
+    }) => void;
+    /**
+     * Returns a route handler that serves the raw OpenAPI spec as JSON.
+     *
+     * @example
+     * app.get("/openapi.json", api.json());
+     */
+    json(): (req: unknown, res: {
+        writeHead(status: number, headers: Record<string, string>): void;
+        end(body: string): void;
+    }) => void;
+}
+/**
+ * Creates an OpenAPI builder with a `.scalar()` and `.json()` route handler,
+ * mirroring the Hono / @scalar/hono-api-reference middleware pattern —
+ * but framework-agnostic.
+ *
+ * @example
+ * import http from "http";
+ * import { openapi } from "./scheduler";
+ *
+ * const api = openapi({ title: "My API", version: "1.0.0" });
+ *
+ * api.spec.paths["/hello"] = {
+ *   get: { summary: "Say hello", responses: { 200: { description: "OK" } } },
+ * };
+ *
+ * http.createServer((req, res) => {
+ *   if (req.url === "/docs")         return api.scalar({ theme: "moon" })(req, res);
+ *   if (req.url === "/openapi.json") return api.json()(req, res);
+ * }).listen(3000);
+ */
+export declare const openapi: (info: {
+    title: string;
+    version: string;
+}) => OpenAPIBuilder;
 //# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,IAAI,GAAI,SAAS,MAAM,EAAE,MAAM,MAAM,IAAI,SAiCrD,CAAC;AAGF,eAAO,MAAM,OAAO,GAAI,MAAM;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;;;eAAzB,MAAM;iBAAW,MAAM;;;CAE7D,CAAC"}
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,IAAI,GAAI,SAAS,MAAM,EAAE,MAAM,MAAM,IAAI,SAiCrD,CAAC;AAIF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IACjE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,4JAA4J;IAC5J,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC9B,qCAAqC;IACrC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,IAAI,EAAE,WAAW,CAAC;IAElB,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAErC;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE;QACnD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;QACjE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;KACzB,KAAK,IAAI,CAAC;IAEX;;;;;OAKG;IACH,IAAI,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE;QAC1B,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;QACjE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;KACzB,KAAK,IAAI,CAAC;CACZ;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,KAAG,cAyDlE,CAAC"}

package/dist/scheduler.js

@@ -23,7 +23,60 @@ var cron = (pattern, task) => {
   setInterval(check, 60000);
 };
 var openapi = (info) => {
-  return { openapi: "3.0.0", info, paths: {} };
+  const spec = { openapi: "3.0.0", info, paths: {} };
+  const renderScalarHtml = (options = {}) => {
+    const {
+      pageTitle = spec.info.title,
+      theme = "default",
+      layout = "modern",
+      hideDownloadButton = false,
+      customCss = ""
+    } = options;
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${pageTitle}</title>
+    ${customCss ? `<style>${customCss}</style>` : ""}
+  </head>
+  <body>
+    <script
+      id="api-reference"
+      type="application/json"
+      data-theme="${theme}"
+      data-layout="${layout}"
+      ${hideDownloadButton ? 'data-hide-download-button="true"' : ""}
+    >${JSON.stringify(spec)}</script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  </body>
+</html>`;
+  };
+  return {
+    spec,
+    get openapi() {
+      return spec.openapi;
+    },
+    get info() {
+      return spec.info;
+    },
+    get paths() {
+      return spec.paths;
+    },
+    scalar(options = {}) {
+      return (_req, res) => {
+        const html = renderScalarHtml(options);
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(html);
+      };
+    },
+    json() {
+      return (_req, res) => {
+        res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+        res.end(JSON.stringify(spec, null, 2));
+      };
+    }
+  };
 };
 export {
   openapi,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "princejs",
-  "version": "1.9.2",
+  "version": "1.9.4",
   "description": "An easy and fast backend framework that is among the top three — by a 13yo developer, for developers.",
   "main": "dist/prince.js",
   "types": "dist/prince.d.ts",
@@ -111,7 +111,7 @@
     "jose": "^6.1.2"
   },
   "scripts": {
-    "build:js": "bun build src/prince.ts --outdir dist --target bun && bun build src/middleware.ts --outdir dist --target bun && bun build src/helpers.ts --outdir dist --target bun && bun build src/scheduler.ts --outdir dist --target bun && bun build bin/create.ts --outdir dist --target bun && bun build src/jsx.ts --outdir dist --target bun && bun build src/db.ts --outdir dist --target bun --format esm && bun build src/client.ts --outdir dist --format esm && bun build src/adapters/vercel.ts --outdir dist/adapters --format esm && bun build src/adapters/cloudflare.ts --outdir dist/adapters --format esm && bun build src/adapters/deno.ts --outdir dist/adapters --format esm",
+    "build:js": "bun build src/prince.ts --outdir dist --target bun --external zod --external jose && bun build src/middleware.ts --outdir dist --target bun && bun build src/helpers.ts --outdir dist --target bun && bun build src/scheduler.ts --outdir dist --target bun && bun build bin/create.ts --outdir dist --target bun && bun build src/jsx.ts --outdir dist --target bun && bun build src/db.ts --outdir dist --target bun --format esm && bun build src/client.ts --outdir dist --format esm && bun build src/adapters/vercel.ts --outdir dist/adapters --format esm && bun build src/adapters/cloudflare.ts --outdir dist/adapters --format esm && bun build src/adapters/deno.ts --outdir dist/adapters --format esm",
     "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
     "build": "bun run build:js && bun run build:types",
     "test": "bun test",