@velajs/cloudflare 1.2.0 → 1.3.0

package/dist/cloudflare-application.d.ts

@@ -1,12 +1,22 @@
 import type { Hono } from 'hono';
 import { type VelaApplication } from '@velajs/vela';
 import type { CloudflareEnv } from './types';
+/**
+ * Options accepted by {@link CloudflareApplication.mountOpenApi}.
+ *
+ * Re-exposes vela's `MountOpenApiOptions` type — derived structurally from
+ * the underlying `VelaApplication.mountOpenApi` signature so consumers don't
+ * have to reach into vela's internal subpaths to type the argument.
+ */
+export type MountOpenApiOptions = Parameters<VelaApplication['mountOpenApi']>[0];
 /**
  * Wraps VelaApplication with Cloudflare-specific handlers:
  * - `fetch` — HTTP request handler (from Hono)
  * - `scheduled` — Cron trigger handler (matches `@Scheduled()` decorators
  *                 AND vela's own `@Cron()` jobs)
  * - `queue` — Queue consumer handler (matches `@QueueConsumer()` decorators)
+ * - `mountOpenApi` — Serve an OpenAPI document (and optional Scalar UI) on
+ *                    the underlying Hono app
  *
  * @example
  * ```ts
@@ -17,6 +27,16 @@ import type { CloudflareEnv } from './types';
  *   queue: app.queue.bind(app),
  * };
  * ```
+ *
+ * @example
+ * ```ts
+ * // Serve OpenAPI docs alongside your routes
+ * const app = await createCloudflareApp(AppModule);
+ * const document = createOpenApiDocument(AppModule);
+ * app.mountOpenApi({ document, ui: 'scalar' });
+ * // GET /docs.json -> JSON document
+ * // GET /docs      -> Scalar UI (loads from CDN)
+ * ```
  */
 export declare class CloudflareApplication {
     private app;
@@ -25,6 +45,27 @@ export declare class CloudflareApplication {
     constructor(app: VelaApplication);
     get fetch(): Hono['fetch'];
     getHonoApp(): Hono;
+    /**
+     * Serve a pre-built OpenAPI document (and optionally a Scalar UI) on the
+     * underlying Hono app. Delegates verbatim to `VelaApplication.mountOpenApi`,
+     * so the JSON endpoint defaults to `/docs.json` and the Scalar UI (when
+     * opted in) defaults to `/docs`. Edge-safe — the UI HTML loads Scalar from
+     * a CDN at runtime, nothing is bundled server-side.
+     *
+     * @example
+     * ```ts
+     * import { createOpenApiDocument } from '@velajs/vela';
+     *
+     * const app = await createCloudflareApp(AppModule);
+     * const document = createOpenApiDocument(AppModule, {
+     *   info: { title: 'My API', version: '1.0.0' },
+     * });
+     * app.mountOpenApi({ document, ui: 'scalar' });
+     * // GET /docs.json -> { openapi: '3.1.0', ... }
+     * // GET /docs      -> Scalar UI HTML
+     * ```
+     */
+    mountOpenApi(options: MountOpenApiOptions): this;
     /** @internal — scans instances for @Scheduled, @Cron, and @QueueConsumer metadata */
     scanInstances(instances: unknown[]): void;
     /**

package/dist/cloudflare-application.js

@@ -14,6 +14,8 @@ function invoke(instance, methodName, args) {
  * - `scheduled` — Cron trigger handler (matches `@Scheduled()` decorators
  *                 AND vela's own `@Cron()` jobs)
  * - `queue` — Queue consumer handler (matches `@QueueConsumer()` decorators)
+ * - `mountOpenApi` — Serve an OpenAPI document (and optional Scalar UI) on
+ *                    the underlying Hono app
  *
  * @example
  * ```ts
@@ -24,6 +26,16 @@ function invoke(instance, methodName, args) {
  *   queue: app.queue.bind(app),
  * };
  * ```
+ *
+ * @example
+ * ```ts
+ * // Serve OpenAPI docs alongside your routes
+ * const app = await createCloudflareApp(AppModule);
+ * const document = createOpenApiDocument(AppModule);
+ * app.mountOpenApi({ document, ui: 'scalar' });
+ * // GET /docs.json -> JSON document
+ * // GET /docs      -> Scalar UI (loads from CDN)
+ * ```
  */ export class CloudflareApplication {
     app;
     scheduledHandlers = [];
@@ -37,6 +49,29 @@ function invoke(instance, methodName, args) {
     getHonoApp() {
         return this.app.getHonoApp();
     }
+    /**
+   * Serve a pre-built OpenAPI document (and optionally a Scalar UI) on the
+   * underlying Hono app. Delegates verbatim to `VelaApplication.mountOpenApi`,
+   * so the JSON endpoint defaults to `/docs.json` and the Scalar UI (when
+   * opted in) defaults to `/docs`. Edge-safe — the UI HTML loads Scalar from
+   * a CDN at runtime, nothing is bundled server-side.
+   *
+   * @example
+   * ```ts
+   * import { createOpenApiDocument } from '@velajs/vela';
+   *
+   * const app = await createCloudflareApp(AppModule);
+   * const document = createOpenApiDocument(AppModule, {
+   *   info: { title: 'My API', version: '1.0.0' },
+   * });
+   * app.mountOpenApi({ document, ui: 'scalar' });
+   * // GET /docs.json -> { openapi: '3.1.0', ... }
+   * // GET /docs      -> Scalar UI HTML
+   * ```
+   */ mountOpenApi(options) {
+        this.app.mountOpenApi(options);
+        return this;
+    }
     /** @internal — scans instances for @Scheduled, @Cron, and @QueueConsumer metadata */ scanInstances(instances) {
         for (const instance of instances){
             if (!instance || typeof instance !== 'object') continue;

package/dist/cloudflare-factory.d.ts

@@ -1,15 +1,74 @@
+import type { MiddlewareHandler } from 'hono';
 import type { Type } from '@velajs/vela';
 import { CloudflareApplication } from './cloudflare-application';
+/**
+ * Options for {@link createCloudflareApp}.
+ *
+ * Mirrors a tight subset of vela's `BootstrapOptions` — only the surface
+ * that makes sense for a Workers consumer is re-exposed.
+ */
+export interface CreateCloudflareAppOptions {
+    /**
+     * Forwarded to `VelaFactory.create({ globalPrefix })`. Prepended to every
+     * route registered by `@Controller(...)` (and any other route emitter)
+     * inside the application, so a value of `'/v1'` turns `@Controller('/users')`
+     * into `/v1/users`.
+     *
+     * @example
+     * ```ts
+     * const app = await createCloudflareApp(AppModule, { globalPrefix: '/v1' });
+     * ```
+     */
+    globalPrefix?: string;
+    /**
+     * Extra Hono middleware to register on the underlying Hono app. Runs
+     * AFTER the one-time binding-init middleware this adapter mounts
+     * internally, so any handler in `middleware` can safely read from
+     * `BindingRef` instances and Cloudflare env bindings.
+     *
+     * @example
+     * ```ts
+     * const app = await createCloudflareApp(AppModule, {
+     *   middleware: [
+     *     async (c, next) => {
+     *       c.set('requestId', crypto.randomUUID());
+     *       await next();
+     *     },
+     *   ],
+     * });
+     * ```
+     */
+    middleware?: MiddlewareHandler[];
+}
 /**
  * Create a Cloudflare Workers application.
  *
  * Sets up a one-time Hono middleware that captures `c.env` on the first
- * request and initializes all configured binding refs.
+ * request and initializes all configured binding refs. Optional
+ * {@link CreateCloudflareAppOptions} are forwarded to the underlying
+ * `VelaFactory.create` so consumers don't have to wrap the resulting
+ * application in an outer Hono just to set a `globalPrefix` or attach
+ * extra request middleware.
  *
  * @example
  * ```ts
+ * // Minimal — backwards compatible
  * const app = await createCloudflareApp(AppModule);
  * export default app; // has .fetch, .scheduled, .queue
  * ```
+ *
+ * @example
+ * ```ts
+ * // With a global prefix and outer middleware
+ * const app = await createCloudflareApp(AppModule, {
+ *   globalPrefix: '/v1',
+ *   middleware: [
+ *     async (c, next) => {
+ *       c.set('tenantId', c.req.header('x-tenant-id') ?? 'public');
+ *       await next();
+ *     },
+ *   ],
+ * });
+ * ```
  */
-export declare function createCloudflareApp(rootModule: Type): Promise<CloudflareApplication>;
+export declare function createCloudflareApp(rootModule: Type, options?: CreateCloudflareAppOptions): Promise<CloudflareApplication>;

package/dist/cloudflare-factory.js

@@ -22,28 +22,52 @@ function collectBindingRefs(container) {
  * Create a Cloudflare Workers application.
  *
  * Sets up a one-time Hono middleware that captures `c.env` on the first
- * request and initializes all configured binding refs.
+ * request and initializes all configured binding refs. Optional
+ * {@link CreateCloudflareAppOptions} are forwarded to the underlying
+ * `VelaFactory.create` so consumers don't have to wrap the resulting
+ * application in an outer Hono just to set a `globalPrefix` or attach
+ * extra request middleware.
  *
  * @example
  * ```ts
+ * // Minimal — backwards compatible
  * const app = await createCloudflareApp(AppModule);
  * export default app; // has .fetch, .scheduled, .queue
  * ```
- */ export async function createCloudflareApp(rootModule) {
+ *
+ * @example
+ * ```ts
+ * // With a global prefix and outer middleware
+ * const app = await createCloudflareApp(AppModule, {
+ *   globalPrefix: '/v1',
+ *   middleware: [
+ *     async (c, next) => {
+ *       c.set('tenantId', c.req.header('x-tenant-id') ?? 'public');
+ *       await next();
+ *     },
+ *   ],
+ * });
+ * ```
+ */ export async function createCloudflareApp(rootModule, options = {}) {
     let initialized = false;
     let refs;
+    const bindingInit = async (c, next)=>{
+        if (!initialized) {
+            initialized = true;
+            const env = c.env ?? {};
+            for (const ref of refs){
+                ref._initialize(env[ref.bindingName]);
+            }
+        }
+        await next();
+    };
+    // IMPORTANT: keep the binding-init middleware FIRST so user middleware
+    // can safely read binding refs / `c.env` derivatives on the first request.
     const velaApp = await VelaFactory.create(rootModule, {
+        globalPrefix: options.globalPrefix,
         middleware: [
-            async (c, next)=>{
-                if (!initialized) {
-                    initialized = true;
-                    const env = c.env ?? {};
-                    for (const ref of refs){
-                        ref._initialize(env[ref.bindingName]);
-                    }
-                }
-                await next();
-            }
+            bindingInit,
+            ...options.middleware ?? []
         ]
     });
     refs = collectBindingRefs(velaApp.getContainer());

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { createCloudflareApp } from './cloudflare-factory';
+export type { CreateCloudflareAppOptions } from './cloudflare-factory';
 export { CloudflareApplication } from './cloudflare-application';
+export type { MountOpenApiOptions } from './cloudflare-application';
 export { KVModule } from './modules/kv.module';
 export { D1Module } from './modules/d1.module';
 export { R2Module } from './modules/r2.module';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/cloudflare",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Cloudflare Workers integration for Vela framework",
   "type": "module",
   "main": "./dist/index.js",