@velajs/cloudflare 1.5.0 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.7.0 (2026-07-04)
+
+- `cloudflareAdapter()` exported (createCloudflareApp composes vela RuntimeAdapter); `@QueueConsumer`/`@Scheduled` declare open entrypoint kinds; queue/scheduled dispatch runs per-event in a request scope through PipelineRunner (consumer-scoped guards/interceptors/filters; request-scoped deps rebuild per batch); DO WebSocket reads `app.entrypoints`. Requires `@velajs/vela >=1.11.0`.
+
+
+## 1.6.0 (2026-07-01)
+
+### Added
+
+- **Multi-disk `StorageModule` over R2** (`StorageService.put/get/delete/exists/url`, per-disk templated roots, bucket-by-name via `EnvService`, `R2StorageDriver`) + a signature-gated `StorageController` presign-proxy.
+- **`KVCacheStore`** implementing vela's `AsyncCacheStore` — pair with `TieredCacheStore` for a memory→KV cache.
+- WebSocket transport for vela's WebSocket gateways (Durable Object backed).
+
+### Fixed
+
+- **Multiple same-type bindings** (e.g. two `KVModule.forRoot` with different bindings) now all initialize — `collectBindingRefs` enumerates every binding ref across module buckets instead of resolving each token once.
+
 ## 0.2.0 (2026-04-28)
 
 ### Breaking changes

package/README.md

@@ -34,7 +34,7 @@ class HyperdriveService { readonly binding: Hyperdrive; }
 
 ```ts
 import { Controller, Get, Module, Injectable, Param } from '@velajs/vela';
-import { CloudflareFactory, KVModule, KVService, D1Module, D1Service } from '@velajs/cloudflare';
+import { createCloudflareApp, KVModule, KVService, D1Module, D1Service } from '@velajs/cloudflare';
 
 @Injectable()
 class UserService {
@@ -73,7 +73,7 @@ class UserController {
 })
 class AppModule {}
 
-export default await CloudflareFactory.create(AppModule);
+export default await createCloudflareApp(AppModule);
 ```
 
 The `binding` string matches the binding name in your `wrangler.toml`:
@@ -327,14 +327,14 @@ class EmailWorker {
 }
 ```
 
-## CloudflareFactory
+## createCloudflareApp
 
-Use `CloudflareFactory.create()` instead of `VelaFactory.create()` for Cloudflare apps. It sets up a one-time middleware that captures `c.env` on the first request and initializes all binding modules.
+Use `createCloudflareApp()` instead of `VelaFactory.create()` for Cloudflare apps. It sets up a one-time middleware that captures `c.env` on the first request and initializes all binding modules.
 
 ```ts
-import { CloudflareFactory } from '@velajs/cloudflare';
+import { createCloudflareApp } from '@velajs/cloudflare';
 
-const app = await CloudflareFactory.create(AppModule);
+const app = await createCloudflareApp(AppModule);
 export default app;
 ```
 
@@ -343,7 +343,7 @@ export default app;
 To use scheduled triggers and queue consumers, export the handlers explicitly:
 
 ```ts
-const app = await CloudflareFactory.create(AppModule);
+const app = await createCloudflareApp(AppModule);
 
 export default {
   fetch: app.fetch,
@@ -371,7 +371,7 @@ const rawHD = hdService.binding;       // Hyperdrive
 
 Cloudflare Workers only provide bindings (`env.DB`, `env.MY_KV`, etc.) at request time via the `env` parameter. They are stable across requests within an isolate.
 
-`CloudflareFactory` handles this by:
+`createCloudflareApp` handles this by:
 
 1. Each `XModule.forRoot()` creates a `BindingRef` (mutable holder) and registers it in the DI container
 2. Services are constructed at boot time with the `BindingRef` — no binding access yet

package/dist/cloudflare-application.d.ts

@@ -1,5 +1,6 @@
 import type { Hono } from 'hono';
 import { type VelaApplication } from '@velajs/vela';
+import { type WsGatewayRoute } from './websocket/websocket-routing';
 import type { CloudflareEnv } from './types';
 /**
  * Options accepted by {@link CloudflareApplication.mountOpenApi}.
@@ -40,8 +41,7 @@ export type MountOpenApiOptions = Parameters<VelaApplication['mountOpenApi']>[0]
  */
 export declare class CloudflareApplication {
     private app;
-    private scheduledHandlers;
-    private queueConsumers;
+    private wsGatewayRoutes;
     constructor(app: VelaApplication);
     get fetch(): Hono['fetch'];
     getHonoApp(): Hono;
@@ -79,11 +79,20 @@ export declare class CloudflareApplication {
      * ```
      */
     mountOpenApi(options: MountOpenApiOptions): this;
-    /** @internal — scans instances for @Scheduled, @Cron, and @QueueConsumer metadata */
+    /**
+     * @internal — scans instances for `@WebSocketGateway({ path, binding })`
+     * upgrade routes. Queue/scheduled handlers are NOT scanned anymore: they
+     * come from `app.entrypoints` (`cf:queue` / `cf:scheduled` / `cf:vela-cron`
+     * kinds) at dispatch time.
+     */
     scanInstances(instances: unknown[]): void;
+    /** @internal — upgrade routes discovered from `@WebSocketGateway({ path, binding })`. */
+    getWsGatewayRoutes(): WsGatewayRoute[];
     /**
      * Handle Cloudflare scheduled (cron) events.
-     * Matches the event's cron expression to `@Scheduled()` and vela `@Cron()` handlers.
+     * Matches the event's cron expression to `@Scheduled()` and vela `@Cron()`
+     * handlers read from `app.entrypoints`; each handler runs inside a fresh
+     * request-scoped child (request-scoped providers rebuild per tick).
      */
     scheduled(event: {
         cron: string;
@@ -91,9 +100,20 @@ export declare class CloudflareApplication {
     }, env: CloudflareEnv, ctx: {
         waitUntil: (promise: Promise<unknown>) => void;
     }): Promise<void>;
+    /**
+     * Run one entrypoint handler inside a fresh request scope, through the
+     * shared guard → interceptor pipeline (components declared with
+     * `@UseGuards`/`@UseInterceptors`/`@UseFilters` on the consumer class or
+     * method). HTTP-global components deliberately do NOT apply — an HTTP auth
+     * guard has no business rejecting a queue batch. Unclaimed errors rethrow
+     * so the platform's retry semantics stay intact.
+     */
+    private dispatchEntrypoint;
     /**
      * Handle Cloudflare Queue consumer events.
-     * Matches the batch queue name to `@QueueConsumer()` handlers.
+     * Matches the batch queue name to `@QueueConsumer()` handlers read from
+     * `app.entrypoints`; each batch is processed inside a fresh request-scoped
+     * child (request-scoped providers rebuild per batch — no boot-time captives).
      */
     queue(batch: {
         queue: string;

package/dist/cloudflare-application.js

@@ -1,6 +1,14 @@
-import { CRON_METADATA, getMetadata } from "@velajs/vela";
-import { getScheduledMetadata } from "./decorators/scheduled.js";
-import { getQueueConsumerMetadata } from "./decorators/queue-consumer.js";
+import { CRON_METADATA, PipelineRunner, buildEntrypointExecutionContext, registerEntrypointKind, runInEntrypointScope, shouldFilterCatch } from "@velajs/vela";
+import { ComponentManager } from "@velajs/vela/internal";
+import { collectWsGatewayRoutes } from "./websocket/websocket-routing.js";
+// vela's own @Cron jobs run via the same Workers cron trigger — declare an
+// entrypoint kind over vela's metadata key (the open-kind system makes
+// cross-package declarations first-class).
+registerEntrypointKind({
+    kind: 'cf:vela-cron',
+    metaKey: CRON_METADATA,
+    level: 'method'
+});
 function invoke(instance, methodName, args) {
     const method = instance[methodName];
     if (typeof method !== 'function') {
@@ -38,8 +46,7 @@ function invoke(instance, methodName, args) {
  * ```
  */ export class CloudflareApplication {
     app;
-    scheduledHandlers = [];
-    queueConsumers = [];
+    wsGatewayRoutes = [];
     constructor(app){
         this.app = app;
     }
@@ -86,51 +93,88 @@ function invoke(instance, methodName, args) {
         this.app.mountOpenApi(options);
         return this;
     }
-    /** @internal — scans instances for @Scheduled, @Cron, and @QueueConsumer metadata */ scanInstances(instances) {
+    /**
+   * @internal — scans instances for `@WebSocketGateway({ path, binding })`
+   * upgrade routes. Queue/scheduled handlers are NOT scanned anymore: they
+   * come from `app.entrypoints` (`cf:queue` / `cf:scheduled` / `cf:vela-cron`
+   * kinds) at dispatch time.
+   */ scanInstances(instances) {
         for (const instance of instances){
             if (!instance || typeof instance !== 'object') continue;
-            for (const meta of getScheduledMetadata(instance)){
-                this.scheduledHandlers.push({
-                    instance,
-                    methodName: meta.methodName,
-                    cron: meta.cron
-                });
-            }
-            // vela's @Cron jobs run via the same Workers cron trigger.
-            const cronMeta = getMetadata(CRON_METADATA, instance.constructor) ?? [];
-            for (const meta of cronMeta){
-                this.scheduledHandlers.push({
-                    instance,
-                    methodName: meta.methodName,
-                    cron: meta.expression
-                });
-            }
-            for (const meta of getQueueConsumerMetadata(instance)){
-                this.queueConsumers.push({
-                    instance,
-                    methodName: meta.methodName,
-                    queueName: meta.queueName
-                });
-            }
+            this.wsGatewayRoutes.push(...collectWsGatewayRoutes(instance));
         }
     }
+    /** @internal — upgrade routes discovered from `@WebSocketGateway({ path, binding })`. */ getWsGatewayRoutes() {
+        return this.wsGatewayRoutes;
+    }
     /**
    * Handle Cloudflare scheduled (cron) events.
-   * Matches the event's cron expression to `@Scheduled()` and vela `@Cron()` handlers.
+   * Matches the event's cron expression to `@Scheduled()` and vela `@Cron()`
+   * handlers read from `app.entrypoints`; each handler runs inside a fresh
+   * request-scoped child (request-scoped providers rebuild per tick).
    */ async scheduled(event, env, ctx) {
-        const matching = this.scheduledHandlers.filter((h)=>h.cron === event.cron);
-        await Promise.all(matching.map((h)=>invoke(h.instance, h.methodName, [
+        const handlers = [
+            ...this.app.entrypoints.ofKind('cf:scheduled').map((ep)=>({
+                    ep,
+                    cron: ep.meta.cron
+                })),
+            ...this.app.entrypoints.ofKind('cf:vela-cron').map((ep)=>({
+                    ep,
+                    cron: ep.meta.expression
+                }))
+        ].filter((h)=>h.cron === event.cron);
+        await Promise.all(handlers.map(({ ep })=>this.dispatchEntrypoint(ep, [
                 event,
                 env,
                 ctx
             ])));
     }
     /**
+   * Run one entrypoint handler inside a fresh request scope, through the
+   * shared guard → interceptor pipeline (components declared with
+   * `@UseGuards`/`@UseInterceptors`/`@UseFilters` on the consumer class or
+   * method). HTTP-global components deliberately do NOT apply — an HTTP auth
+   * guard has no business rejecting a queue batch. Unclaimed errors rethrow
+   * so the platform's retry semantics stay intact.
+   */ async dispatchEntrypoint(ep, args) {
+        const targetClass = ep.token;
+        const methodName = String(ep.methodName);
+        const context = buildEntrypointExecutionContext(ep.kind, targetClass, methodName, args[0]);
+        await runInEntrypointScope(this.app.getContainer(), async (scope)=>{
+            const instance = scope.resolve(ep.token);
+            const guards = ComponentManager.resolveGuards(ComponentManager.getScopedComponents('guard', targetClass, methodName), scope);
+            const interceptors = ComponentManager.resolveInterceptors(ComponentManager.getScopedComponents('interceptor', targetClass, methodName), scope);
+            // Closest-first, mirroring the HTTP/WS dispatchers.
+            const filters = ComponentManager.resolveFilters([
+                ...ComponentManager.getScopedComponents('filter', targetClass, methodName)
+            ].reverse(), scope);
+            try {
+                await PipelineRunner.run({
+                    context,
+                    guards,
+                    interceptors,
+                    resolveArgs: async ()=>args,
+                    invoke: async (resolved)=>invoke(instance, methodName, resolved)
+                });
+            } catch (error) {
+                for (const filter of filters){
+                    if (shouldFilterCatch(filter, error)) {
+                        await filter.catch(error, context);
+                        return;
+                    }
+                }
+                throw error;
+            }
+        });
+    }
+    /**
    * Handle Cloudflare Queue consumer events.
-   * Matches the batch queue name to `@QueueConsumer()` handlers.
+   * Matches the batch queue name to `@QueueConsumer()` handlers read from
+   * `app.entrypoints`; each batch is processed inside a fresh request-scoped
+   * child (request-scoped providers rebuild per batch — no boot-time captives).
    */ async queue(batch, env, ctx) {
-        const matching = this.queueConsumers.filter((h)=>h.queueName === batch.queue);
-        await Promise.all(matching.map((h)=>invoke(h.instance, h.methodName, [
+        const handlers = this.app.entrypoints.ofKind('cf:queue').filter((ep)=>ep.meta.queueName === batch.queue);
+        await Promise.all(handlers.map((ep)=>this.dispatchEntrypoint(ep, [
                 batch,
                 env,
                 ctx

package/dist/cloudflare-factory.d.ts

@@ -1,5 +1,5 @@
 import type { MiddlewareHandler } from 'hono';
-import type { Type } from '@velajs/vela';
+import type { RuntimeAdapter, Type } from '@velajs/vela';
 import { CloudflareApplication } from './cloudflare-application';
 /**
  * Options for {@link createCloudflareApp}.
@@ -71,4 +71,18 @@ export interface CreateCloudflareAppOptions {
  * });
  * ```
  */
+/**
+ * The Cloudflare platform binding as a vela {@link RuntimeAdapter}: a one-time
+ * request middleware captures `c.env` on the first request and initializes
+ * every `BindingRef`/`EnvRef` (collected at `onBootstrap`, before any request
+ * can arrive). Adapter `requestMiddleware` is prepended to the global chain by
+ * `VelaFactory.create`, so user middleware can safely read binding refs.
+ *
+ * Exposed so consumers composing `VelaFactory.create` themselves can opt in:
+ *
+ * ```ts
+ * const app = await VelaFactory.create(AppModule, { adapters: [cloudflareAdapter()] });
+ * ```
+ */
+export declare function cloudflareAdapter(): RuntimeAdapter;
 export declare function createCloudflareApp(rootModule: Type, options?: CreateCloudflareAppOptions): Promise<CloudflareApplication>;

package/dist/cloudflare-factory.js

@@ -2,19 +2,18 @@ import { VelaFactory } from "@velajs/vela";
 import { BindingRef } from "./binding-ref.js";
 import { CloudflareApplication } from "./cloudflare-application.js";
 import { EnvRef } from "./env-ref.js";
+import { registerWebSocketRoutes } from "./websocket/websocket-routing.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
 // share state.
 function collectBindingRefs(container) {
+    // Enumerate per-instance useValue providers across ALL module buckets. Two
+    // same-type binding modules (e.g. KVModule.forRoot for CACHE and SESSIONS)
+    // share one token but live in distinct buckets — resolving the token would
+    // return only the first, leaving the others uninitialized.
     const refs = [];
-    for (const token of container.getTokens()){
-        let value;
-        try {
-            value = container.resolve(token);
-        } catch  {
-            continue;
-        }
+    for (const value of container.getUseValues()){
         if (value instanceof BindingRef) refs.push(value);
     }
     return refs;
@@ -49,32 +48,54 @@ function collectBindingRefs(container) {
  *   ],
  * });
  * ```
- */ export async function createCloudflareApp(rootModule, options = {}) {
+ */ /**
+ * The Cloudflare platform binding as a vela {@link RuntimeAdapter}: a one-time
+ * request middleware captures `c.env` on the first request and initializes
+ * every `BindingRef`/`EnvRef` (collected at `onBootstrap`, before any request
+ * can arrive). Adapter `requestMiddleware` is prepended to the global chain by
+ * `VelaFactory.create`, so user middleware can safely read binding refs.
+ *
+ * Exposed so consumers composing `VelaFactory.create` themselves can opt in:
+ *
+ * ```ts
+ * const app = await VelaFactory.create(AppModule, { adapters: [cloudflareAdapter()] });
+ * ```
+ */ export function cloudflareAdapter() {
     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]);
+    let refs = [];
+    return {
+        name: 'cloudflare',
+        requestMiddleware: [
+            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();
             }
+        ],
+        onBootstrap: ({ container })=>{
+            refs = collectBindingRefs(container);
         }
-        await next();
     };
-    // IMPORTANT: keep the binding-init middleware FIRST so user middleware
-    // can safely read binding refs / `c.env` derivatives on the first request.
+}
+export async function createCloudflareApp(rootModule, options = {}) {
     const velaApp = await VelaFactory.create(rootModule, {
         globalPrefix: options.globalPrefix,
-        middleware: [
-            bindingInit,
-            ...options.middleware ?? []
+        middleware: options.middleware,
+        adapters: [
+            cloudflareAdapter()
         ]
     });
-    refs = collectBindingRefs(velaApp.getContainer());
     const cfApp = new CloudflareApplication(velaApp);
     cfApp.scanInstances(velaApp.getInstances());
+    // Register WebSocket upgrade routes for any @WebSocketGateway({ path, binding }).
+    // Each forwards the upgrade to the room's Durable Object (which owns the socket).
+    registerWebSocketRoutes(cfApp.getHonoApp(), cfApp.getWsGatewayRoutes());
     return cfApp;
 }

package/dist/decorators/queue-consumer.js

@@ -1,5 +1,13 @@
-import { defineMetadata, getMetadata } from "@velajs/vela";
+import { defineMetadata, getMetadata, registerEntrypointKind } from "@velajs/vela";
 const QUEUE_CONSUMER_METADATA_KEY = 'cloudflare:queue-consumer';
+// Open entrypoint kind: any adapter can enumerate queue consumers via
+// `app.entrypoints.ofKind('cf:queue')` — declared here, next to the decorator,
+// with zero vela-core involvement.
+registerEntrypointKind({
+    kind: 'cf:queue',
+    metaKey: QUEUE_CONSUMER_METADATA_KEY,
+    level: 'method'
+});
 /**
  * Marks a method as a queue consumer handler.
  *

package/dist/decorators/scheduled.js

@@ -1,5 +1,12 @@
-import { defineMetadata, getMetadata } from "@velajs/vela";
+import { defineMetadata, getMetadata, registerEntrypointKind } from "@velajs/vela";
 const SCHEDULED_METADATA_KEY = 'cloudflare:scheduled';
+// Open entrypoint kind: adapters enumerate cron handlers via
+// `app.entrypoints.ofKind('cf:scheduled')` — declared next to the decorator.
+registerEntrypointKind({
+    kind: 'cf:scheduled',
+    metaKey: SCHEDULED_METADATA_KEY,
+    level: 'method'
+});
 /**
  * Marks a method as a scheduled (cron) handler.
  *

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { createCloudflareApp } from './cloudflare-factory';
+export { cloudflareAdapter, createCloudflareApp } from './cloudflare-factory';
 export type { CreateCloudflareAppOptions } from './cloudflare-factory';
 export { CloudflareApplication } from './cloudflare-application';
 export type { MountOpenApiOptions } from './cloudflare-application';
@@ -11,7 +11,10 @@ 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 { StorageModule, StorageService, StorageManagerService, StorageController, R2StorageDriver, STORAGE_OPTIONS, } from './storage/index';
+export type { StorageModuleOptions, DiskConfig, PresignedUrlConfig } from './storage/index';
 export { KVService } from './services/kv.service';
+export { KVCacheStore } from './services/kv-cache.store';
 export { D1Service } from './services/d1.service';
 export { R2Service } from './services/r2.service';
 export { QueueService } from './services/queue.service';
@@ -23,6 +26,10 @@ export { EnvService } from './services/env.service';
 export { Env } from './decorators/env';
 export { Scheduled } from './decorators/scheduled';
 export { QueueConsumer } from './decorators/queue-consumer';
+export { VelaWebSocketDurableObject, CloudflareWebSocketModule, broadcastToRoom, } from './websocket/index';
+export type { WsGatewayRoute } from './websocket/index';
+export { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, WsException, } from '@velajs/vela/websocket';
+export type { WsClient, WsServer, WsResponse, WsMessage, OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect, } from '@velajs/vela/websocket';
 export type { CloudflareEnv, ScheduledRegistration, QueueRegistration } from './types';
 export type { ScheduledMetadata } from './decorators/scheduled';
 export type { QueueConsumerMetadata } from './decorators/queue-consumer';

package/dist/index.js

@@ -1,5 +1,5 @@
 // Factory & Application
-export { createCloudflareApp } from "./cloudflare-factory.js";
+export { cloudflareAdapter, createCloudflareApp } from "./cloudflare-factory.js";
 export { CloudflareApplication } from "./cloudflare-application.js";
 // Modules
 export { KVModule } from "./modules/kv.module.js";
@@ -11,8 +11,11 @@ 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";
+// Storage (multi-disk over R2 + presign proxy)
+export { StorageModule, StorageService, StorageManagerService, StorageController, R2StorageDriver, STORAGE_OPTIONS } from "./storage/index.js";
 // Services
 export { KVService } from "./services/kv.service.js";
+export { KVCacheStore } from "./services/kv-cache.store.js";
 export { D1Service } from "./services/d1.service.js";
 export { R2Service } from "./services/r2.service.js";
 export { QueueService } from "./services/queue.service.js";
@@ -25,3 +28,7 @@ export { EnvService } from "./services/env.service.js";
 export { Env } from "./decorators/env.js";
 export { Scheduled } from "./decorators/scheduled.js";
 export { QueueConsumer } from "./decorators/queue-consumer.js";
+// WebSocket (Durable Object transport for the Vela WebSocketModule)
+export { VelaWebSocketDurableObject, CloudflareWebSocketModule, broadcastToRoom } from "./websocket/index.js";
+// Re-export the core gateway API so a Cloudflare app can import it from one place.
+export { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, WsException } from "@velajs/vela/websocket";

package/dist/modules/create-binding-module.js

@@ -1,7 +1,8 @@
+import { defineConfigurableModule } from "@velajs/vela";
 import { BindingRef } from "../binding-ref.js";
 // Single factory for every Cloudflare binding module (KV, D1, R2, ...).
-// Each binding module is just a bag of (token, service); this generates
-// the canonical forRoot() shape for them.
+// Each binding module is just a bag of (token, service); this generates the
+// canonical forRoot() shape via vela's `defineConfigurableModule` engine.
 //
 // Identity model (post vela audit #2):
 //   - One real module class is declared per binding TYPE (KV, D1, R2, ...).
@@ -22,24 +23,20 @@ export function createBindingModule(opts) {
         [className]: class {
         }
     }[className];
-    return {
-        forRoot ({ binding }) {
-            const ref = new BindingRef(binding);
-            return {
-                module: moduleClass,
-                key: binding,
-                providers: [
-                    {
-                        provide: opts.bindingRefToken,
-                        useValue: ref
-                    },
-                    opts.serviceClass
-                ],
-                exports: [
-                    opts.serviceClass,
-                    opts.bindingRefToken
-                ]
-            };
-        }
-    };
+    return defineConfigurableModule({
+        module: moduleClass,
+        methodName: 'forRoot',
+        keyFrom: ({ binding })=>binding,
+        providers: ({ binding })=>[
+                {
+                    provide: opts.bindingRefToken,
+                    useValue: new BindingRef(binding)
+                },
+                opts.serviceClass
+            ],
+        exports: [
+            opts.serviceClass,
+            opts.bindingRefToken
+        ]
+    });
 }

package/dist/services/kv-cache.store.d.ts

@@ -0,0 +1,19 @@
+import { type AsyncCacheStore } from '@velajs/vela';
+import { KVService } from './kv.service';
+/**
+ * Cloudflare KV-backed {@link CacheStore}. Values are JSON-encoded. Intended as
+ * the slow tier under a `TieredCacheStore` (memory L1 → KV L2), but usable
+ * standalone as `CacheModule.forRootAsync({ inject: [KVService], useFactory: (kv) => ({ store: new KVCacheStore(kv) }) })`.
+ *
+ * Note: Cloudflare KV requires `expirationTtl >= 60s`, so sub-minute TTLs are
+ * clamped up. Keep short TTLs on the memory tier; use KV for longer-lived entries.
+ */
+export declare class KVCacheStore implements AsyncCacheStore {
+    private readonly kv;
+    constructor(kv: KVService);
+    private get ns();
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
+    del(key: string): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/services/kv-cache.store.js

@@ -0,0 +1,58 @@
+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 { KVService } from "./kv.service.js";
+export class KVCacheStore {
+    kv;
+    constructor(kv){
+        this.kv = kv;
+    }
+    get ns() {
+        return this.kv.namespace;
+    }
+    async get(key) {
+        const value = await this.ns.get(key, 'json');
+        return value === null ? undefined : value;
+    }
+    async set(key, value, ttl) {
+        // KV enforces a 60s minimum expirationTtl; clamp up. Omit for no-TTL.
+        const options = ttl !== undefined ? {
+            expirationTtl: Math.max(60, Math.floor(ttl))
+        } : undefined;
+        await this.ns.put(key, JSON.stringify(value), options);
+    }
+    async del(key) {
+        await this.ns.delete(key);
+    }
+    async clear() {
+        // KV has no native clear — page through and delete. Best-effort.
+        let cursor;
+        do {
+            const list = await this.ns.list(cursor ? {
+                cursor
+            } : undefined);
+            await Promise.all(list.keys.map((entry)=>this.ns.delete(entry.name)));
+            cursor = list.list_complete ? undefined : list.cursor;
+        }while (cursor)
+    }
+}
+KVCacheStore = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(KVService)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof KVService === "undefined" ? Object : KVService
+    ])
+], KVCacheStore);

package/dist/storage/index.d.ts

@@ -0,0 +1,7 @@
+export { StorageModule } from './storage.module';
+export { StorageService } from './storage.service';
+export { StorageManagerService } from './storage-manager.service';
+export { StorageController } from './storage.controller';
+export { R2StorageDriver } from './r2-storage.driver';
+export { STORAGE_OPTIONS } from './storage.tokens';
+export type { StorageModuleOptions, DiskConfig, PresignedUrlConfig } from './storage.types';

package/dist/storage/index.js

@@ -0,0 +1,6 @@
+export { StorageModule } from "./storage.module.js";
+export { StorageService } from "./storage.service.js";
+export { StorageManagerService } from "./storage-manager.service.js";
+export { StorageController } from "./storage.controller.js";
+export { R2StorageDriver } from "./r2-storage.driver.js";
+export { STORAGE_OPTIONS } from "./storage.tokens.js";