@velajs/cloudflare 1.2.0 → 1.5.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 /openapi.json -> JSON document
+ * // GET /scalar       -> Scalar UI (loads from CDN)
+ * ```
  */
 export declare class CloudflareApplication {
     private app;
@@ -25,6 +45,40 @@ export declare class CloudflareApplication {
     constructor(app: VelaApplication);
     get fetch(): Hono['fetch'];
     getHonoApp(): Hono;
+    /**
+     * Resolve a provider from the application's DI container (delegates to
+     * `VelaApplication.get`). Handy for grabbing a service — e.g. an auth service —
+     * to use inside `createCloudflareApp({ middleware: [...] })` request middleware,
+     * which runs outside the DI request pipeline.
+     *
+     * @example
+     * ```ts
+     * const app = await createCloudflareApp(AppModule);
+     * const auth = app.get<BetterAuthService>(BetterAuthService);
+     * ```
+     */
+    get<T>(token: Parameters<VelaApplication['get']>[0]): T;
+    /**
+     * 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 `/openapi.json` and the Scalar UI (when
+     * opted in) defaults to `/scalar`. 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 /openapi.json -> { openapi: '3.1.0', ... }
+     * // GET /scalar       -> 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 /openapi.json -> JSON document
+ * // GET /scalar       -> Scalar UI (loads from CDN)
+ * ```
  */ export class CloudflareApplication {
     app;
     scheduledHandlers = [];
@@ -37,6 +49,43 @@ function invoke(instance, methodName, args) {
     getHonoApp() {
         return this.app.getHonoApp();
     }
+    /**
+   * Resolve a provider from the application's DI container (delegates to
+   * `VelaApplication.get`). Handy for grabbing a service — e.g. an auth service —
+   * to use inside `createCloudflareApp({ middleware: [...] })` request middleware,
+   * which runs outside the DI request pipeline.
+   *
+   * @example
+   * ```ts
+   * const app = await createCloudflareApp(AppModule);
+   * const auth = app.get<BetterAuthService>(BetterAuthService);
+   * ```
+   */ get(token) {
+        return this.app.get(token);
+    }
+    /**
+   * 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 `/openapi.json` and the Scalar UI (when
+   * opted in) defaults to `/scalar`. 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 /openapi.json -> { openapi: '3.1.0', ... }
+   * // GET /scalar       -> 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

@@ -1,6 +1,7 @@
 import { VelaFactory } from "@velajs/vela";
 import { BindingRef } from "./binding-ref.js";
 import { CloudflareApplication } from "./cloudflare-application.js";
+import { EnvRef } from "./env-ref.js";
 // Walks every provider registered in the container and pulls out the
 // BindingRef instances. Replaces the old module-level `bindingsRegistry`
 // global so two CloudflareApplication instances in one process don't
@@ -22,28 +23,54 @@ 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){
+                // EnvRef holds the whole env; every other ref holds one binding.
+                if (ref instanceof EnvRef) ref._initialize(env);
+                else 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/env-ref.d.ts

@@ -0,0 +1,10 @@
+import { BindingRef } from './binding-ref';
+/**
+ * Holds the entire Cloudflare Worker `env` record (bindings + vars/secrets),
+ * not a single binding. Subclasses {@link BindingRef} so createCloudflareApp's
+ * binding-init middleware collects and initializes it through the same path;
+ * the factory special-cases it to pass the full `env` instead of one binding.
+ */
+export declare class EnvRef extends BindingRef<Record<string, unknown>> {
+    constructor();
+}

package/dist/env-ref.js

@@ -0,0 +1,13 @@
+import { BindingRef } from "./binding-ref.js";
+// Sentinel binding name for the whole-env holder — never used as an env key.
+const ENV_SENTINEL = '__cf_env__';
+/**
+ * Holds the entire Cloudflare Worker `env` record (bindings + vars/secrets),
+ * not a single binding. Subclasses {@link BindingRef} so createCloudflareApp's
+ * binding-init middleware collects and initializes it through the same path;
+ * the factory special-cases it to pass the full `env` instead of one binding.
+ */ export class EnvRef extends BindingRef {
+    constructor(){
+        super(ENV_SENTINEL);
+    }
+}

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';
@@ -8,6 +10,7 @@ export { DurableObjectModule } from './modules/durable-object.module';
 export { AIModule } from './modules/ai.module';
 export { VectorizeModule } from './modules/vectorize.module';
 export { HyperdriveModule } from './modules/hyperdrive.module';
+export { EnvModule } from './modules/env.module';
 export { KVService } from './services/kv.service';
 export { D1Service } from './services/d1.service';
 export { R2Service } from './services/r2.service';
@@ -16,6 +19,7 @@ export { DurableObjectService } from './services/durable-object.service';
 export { AIService } from './services/ai.service';
 export { VectorizeService } from './services/vectorize.service';
 export { HyperdriveService } from './services/hyperdrive.service';
+export { EnvService } from './services/env.service';
 export { Env } from './decorators/env';
 export { Scheduled } from './decorators/scheduled';
 export { QueueConsumer } from './decorators/queue-consumer';

package/dist/index.js

@@ -10,6 +10,7 @@ export { DurableObjectModule } from "./modules/durable-object.module.js";
 export { AIModule } from "./modules/ai.module.js";
 export { VectorizeModule } from "./modules/vectorize.module.js";
 export { HyperdriveModule } from "./modules/hyperdrive.module.js";
+export { EnvModule } from "./modules/env.module.js";
 // Services
 export { KVService } from "./services/kv.service.js";
 export { D1Service } from "./services/d1.service.js";
@@ -19,6 +20,7 @@ export { DurableObjectService } from "./services/durable-object.service.js";
 export { AIService } from "./services/ai.service.js";
 export { VectorizeService } from "./services/vectorize.service.js";
 export { HyperdriveService } from "./services/hyperdrive.service.js";
+export { EnvService } from "./services/env.service.js";
 // Decorators
 export { Env } from "./decorators/env.js";
 export { Scheduled } from "./decorators/scheduled.js";

package/dist/modules/env.module.d.ts

@@ -0,0 +1,17 @@
+import type { DynamicModule } from '@velajs/vela';
+/**
+ * Provides {@link EnvService} GLOBALLY so any module's provider factories can
+ * `inject: [EnvService]`. Register once on the root module:
+ *
+ * ```ts
+ * @Module({ imports: [EnvModule.forRoot(), AuthModule.forRootAsync({ ... })] })
+ * class AppModule {}
+ * ```
+ *
+ * The {@link EnvRef} it provides is collected and initialized by
+ * createCloudflareApp's binding-init middleware on the first request (the
+ * factory passes it the full `env`, not a single binding).
+ */
+export declare class EnvModule {
+    static forRoot(): DynamicModule;
+}

package/dist/modules/env.module.js

@@ -0,0 +1,35 @@
+import { EnvRef } from "../env-ref.js";
+import { EnvService } from "../services/env.service.js";
+import { ENV_REF } from "../tokens.js";
+/**
+ * Provides {@link EnvService} GLOBALLY so any module's provider factories can
+ * `inject: [EnvService]`. Register once on the root module:
+ *
+ * ```ts
+ * @Module({ imports: [EnvModule.forRoot(), AuthModule.forRootAsync({ ... })] })
+ * class AppModule {}
+ * ```
+ *
+ * The {@link EnvRef} it provides is collected and initialized by
+ * createCloudflareApp's binding-init middleware on the first request (the
+ * factory passes it the full `env`, not a single binding).
+ */ export class EnvModule {
+    static forRoot() {
+        const ref = new EnvRef();
+        return {
+            module: EnvModule,
+            global: true,
+            providers: [
+                {
+                    provide: ENV_REF,
+                    useValue: ref
+                },
+                EnvService
+            ],
+            exports: [
+                EnvService,
+                ENV_REF
+            ]
+        };
+    }
+}

package/dist/services/env.service.d.ts

@@ -0,0 +1,31 @@
+import type { EnvRef } from '../env-ref';
+/**
+ * Injectable access to the full Cloudflare Worker `env` (bindings + vars +
+ * secrets).
+ *
+ * The per-binding services (`D1Service`, `KVService`, …) each expose a single
+ * binding, and the `@Env()` param decorator only works inside a request-scoped
+ * controller handler. `EnvService` fills the gap: it can be injected into
+ * PROVIDER FACTORIES — e.g. `SomeModule.forRootAsync({ inject: [EnvService] })`
+ * — so a factory can read secrets/origins without reaching for the request.
+ *
+ * Reads are lazy. `env` only exists per request, so a factory (which runs at
+ * bootstrap) must capture the `EnvService` and read inside its callback:
+ *
+ * ```ts
+ * AuthModule.forRootAsync({
+ *   inject: [EnvService],
+ *   useFactory: (env: EnvService) => buildAuth(() => env.get<string>('AUTH_SECRET')),
+ * });
+ * ```
+ *
+ * Reading eagerly at bootstrap (`env.get(...)` before any request) throws.
+ */
+export declare class EnvService {
+    private ref;
+    constructor(ref: EnvRef);
+    /** The full env record. Throws if read before the first request. */
+    get env(): Record<string, unknown>;
+    /** Read a single env entry (binding, var, or secret) by name. */
+    get<T = unknown>(key: string): T | undefined;
+}

package/dist/services/env.service.js

@@ -0,0 +1,36 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { Inject, Injectable } from "@velajs/vela";
+import { ENV_REF } from "../tokens.js";
+export class EnvService {
+    ref;
+    constructor(ref){
+        this.ref = ref;
+    }
+    /** The full env record. Throws if read before the first request. */ get env() {
+        return this.ref.value;
+    }
+    /** Read a single env entry (binding, var, or secret) by name. */ get(key) {
+        return this.ref.value[key];
+    }
+}
+EnvService = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(ENV_REF)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof EnvRef === "undefined" ? Object : EnvRef
+    ])
+], EnvService);

package/dist/tokens.d.ts

@@ -1,5 +1,6 @@
 import { InjectionToken } from '@velajs/vela';
 import type { BindingRef } from './binding-ref';
+import type { EnvRef } from './env-ref';
 export declare const KV_BINDING_REF: InjectionToken<BindingRef<unknown>>;
 export declare const D1_BINDING_REF: InjectionToken<BindingRef<unknown>>;
 export declare const R2_BINDING_REF: InjectionToken<BindingRef<unknown>>;
@@ -8,3 +9,4 @@ export declare const DO_BINDING_REF: InjectionToken<BindingRef<unknown>>;
 export declare const AI_BINDING_REF: InjectionToken<BindingRef<unknown>>;
 export declare const VECTORIZE_BINDING_REF: InjectionToken<BindingRef<unknown>>;
 export declare const HYPERDRIVE_BINDING_REF: InjectionToken<BindingRef<unknown>>;
+export declare const ENV_REF: InjectionToken<EnvRef>;

package/dist/tokens.js

@@ -8,3 +8,5 @@ export const DO_BINDING_REF = new InjectionToken('CF_DO_BINDING_REF');
 export const AI_BINDING_REF = new InjectionToken('CF_AI_BINDING_REF');
 export const VECTORIZE_BINDING_REF = new InjectionToken('CF_VECTORIZE_BINDING_REF');
 export const HYPERDRIVE_BINDING_REF = new InjectionToken('CF_HYPERDRIVE_BINDING_REF');
+// Token for the whole-env holder (full c.env), backing EnvService.
+export const ENV_REF = new InjectionToken('CF_ENV_REF');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/cloudflare",
-  "version": "1.2.0",
+  "version": "1.5.0",
   "description": "Cloudflare Workers integration for Vela framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,6 +17,13 @@
     "LICENSE",
     "CHANGELOG.md"
   ],
+  "scripts": {
+    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepare": "swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
+    "prepublishOnly": "pnpm run typecheck && pnpm test"
+  },
   "sideEffects": false,
   "keywords": [
     "vela",
@@ -45,22 +52,24 @@
   },
   "peerDependencies": {
     "@cloudflare/workers-types": ">=4",
-    "@velajs/vela": ">=1.5.0",
+    "@velajs/vela": ">=1.8.5",
     "hono": ">=4"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4",
-    "@swc/cli": "^0.8.0",
-    "@swc/core": "^1.15.11",
-    "@velajs/vela": "^1.5.0",
-    "hono": "^4",
-    "typescript": "^5",
+    "@cloudflare/workers-types": "^4.20260624.1",
+    "@swc/cli": "^0.8.1",
+    "@swc/core": "^1.15.43",
+    "@velajs/vela": "^1.8.5",
+    "hono": "^4.12.27",
+    "typescript": "^6.0.3",
     "unplugin-swc": "^1.5.9",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.9"
   },
-  "scripts": {
-    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+  "packageManager": "pnpm@10.20.0",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@swc/core",
+      "esbuild"
+    ]
   }
-}
+}