@velajs/cloudflare 1.3.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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}.
@@ -34,22 +35,36 @@ export type MountOpenApiOptions = Parameters<VelaApplication['mountOpenApi']>[0]
  * 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)
+ * // GET /openapi.json -> JSON document
+ * // GET /scalar       -> Scalar UI (loads from CDN)
  * ```
  */
 export declare class CloudflareApplication {
     private app;
     private scheduledHandlers;
     private queueConsumers;
+    private wsGatewayRoutes;
     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 `/docs.json` and the Scalar UI (when
-     * opted in) defaults to `/docs`. Edge-safe — the UI HTML loads Scalar from
+     * 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
@@ -61,13 +76,15 @@ export declare class CloudflareApplication {
      *   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
+     * // 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;
+    /** @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.

package/dist/cloudflare-application.js

@@ -1,6 +1,7 @@
 import { CRON_METADATA, getMetadata } from "@velajs/vela";
 import { getScheduledMetadata } from "./decorators/scheduled.js";
 import { getQueueConsumerMetadata } from "./decorators/queue-consumer.js";
+import { collectWsGatewayRoutes } from "./websocket/websocket-routing.js";
 function invoke(instance, methodName, args) {
     const method = instance[methodName];
     if (typeof method !== 'function') {
@@ -33,13 +34,14 @@ function invoke(instance, methodName, args) {
  * 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)
+ * // GET /openapi.json -> JSON document
+ * // GET /scalar       -> Scalar UI (loads from CDN)
  * ```
  */ export class CloudflareApplication {
     app;
     scheduledHandlers = [];
     queueConsumers = [];
+    wsGatewayRoutes = [];
     constructor(app){
         this.app = app;
     }
@@ -50,10 +52,24 @@ function invoke(instance, methodName, args) {
         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 `/docs.json` and the Scalar UI (when
-   * opted in) defaults to `/docs`. Edge-safe — the UI HTML loads Scalar from
+   * 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
@@ -65,8 +81,8 @@ function invoke(instance, methodName, args) {
    *   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
+   * // GET /openapi.json -> { openapi: '3.1.0', ... }
+   * // GET /scalar       -> Scalar UI HTML
    * ```
    */ mountOpenApi(options) {
         this.app.mountOpenApi(options);
@@ -98,8 +114,12 @@ function invoke(instance, methodName, args) {
                     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.

package/dist/cloudflare-factory.js

@@ -1,19 +1,19 @@
 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;
@@ -56,7 +56,9 @@ function collectBindingRefs(container) {
             initialized = true;
             const env = c.env ?? {};
             for (const ref of refs){
-                ref._initialize(env[ref.bindingName]);
+                // 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();
@@ -73,5 +75,8 @@ function collectBindingRefs(container) {
     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/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

@@ -10,7 +10,11 @@ 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 { 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';
@@ -18,9 +22,14 @@ 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';
+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

@@ -10,8 +10,12 @@ 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";
+// 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";
@@ -19,7 +23,12 @@ 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";
 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/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/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";

package/dist/storage/r2-storage.driver.d.ts

@@ -0,0 +1,19 @@
+import { type DownloadResult, type PresignedUrlResult, type PresignMethod, type StorageBody, type StorageDriver, type UploadOptions, type UploadResult } from '@velajs/vela/storage';
+/** Base path of the StorageController presign-proxy route. */
+export declare const STORAGE_ROUTE_BASE = "/storage";
+export interface R2StorageDriverConfig {
+    disk: string;
+    bucket: R2Bucket;
+    /** HMAC secret for presigned URLs (typically env.APP_SECRET). */
+    secret?: string;
+}
+/** {@link StorageDriver} over a Cloudflare R2 bucket. */
+export declare class R2StorageDriver implements StorageDriver {
+    private readonly config;
+    constructor(config: R2StorageDriverConfig);
+    upload(body: StorageBody, path: string, options: UploadOptions): Promise<UploadResult>;
+    download(path: string): Promise<DownloadResult>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    getPresignedUrl(path: string, method: PresignMethod, expiresIn: number): Promise<PresignedUrlResult>;
+}