@velajs/cloudflare 1.0.0 → 1.2.0

package/README.md

@@ -10,6 +10,24 @@ Cloudflare Workers integration for the [Vela](https://github.com/velajs/vela) fr
 
 ```bash
 pnpm add @velajs/cloudflare @velajs/vela hono
+pnpm add -D @cloudflare/workers-types
+```
+
+`@cloudflare/workers-types` is a required peer (types-only — zero runtime cost). It's what gives `KVNamespace`, `D1Database`, `R2Bucket`, `Queue`, `DurableObjectNamespace`, `Ai`, `VectorizeIndex`, and `Hyperdrive` their proper types when you reach into the underlying binding.
+
+## Service shape
+
+Every service is a thin typed wrapper around its Cloudflare binding. Use the accessor (`.namespace`, `.database`, `.bucket`, `.queue`, `.binding`, `.index`) to call the binding's methods directly — full `@cloudflare/workers-types` autocomplete, no shim layer in between.
+
+```ts
+class KVService { readonly namespace: KVNamespace; }
+class D1Service { readonly database: D1Database; }
+class R2Service { readonly bucket: R2Bucket; }
+class QueueService<T> { readonly queue: Queue<T>; }
+class DurableObjectService { readonly namespace: DurableObjectNamespace; }
+class AIService { readonly binding: Ai; }
+class VectorizeService { readonly index: VectorizeIndex; }
+class HyperdriveService { readonly binding: Hyperdrive; }
 ```
 
 ## Quick Start
@@ -26,11 +44,11 @@ class UserService {
   ) {}
 
   async findById(id: string) {
-    const cached = await this.kv.get(`user:${id}`);
+    const cached = await this.kv.namespace.get(`user:${id}`);
     if (cached) return JSON.parse(cached as string);
 
-    const user = await this.d1.prepare('SELECT * FROM users WHERE id = ?').bind(id).first();
-    if (user) await this.kv.put(`user:${id}`, JSON.stringify(user));
+    const user = await this.d1.database.prepare('SELECT * FROM users WHERE id = ?').bind(id).first();
+    if (user) await this.kv.namespace.put(`user:${id}`, JSON.stringify(user));
     return user;
   }
 }
@@ -97,10 +115,10 @@ class AppModule {}
 class CacheService {
   constructor(private kv: KVService) {}
 
-  async get(key: string) { return this.kv.get(key); }
-  async set(key: string, value: string) { return this.kv.put(key, value); }
-  async remove(key: string) { return this.kv.delete(key); }
-  async keys() { return this.kv.list(); }
+  async get(key: string) { return this.kv.namespace.get(key); }
+  async set(key: string, value: string) { return this.kv.namespace.put(key, value); }
+  async remove(key: string) { return this.kv.namespace.delete(key); }
+  async keys() { return this.kv.namespace.list(); }
 }
 ```
 
@@ -117,11 +135,11 @@ class PostService {
   constructor(private d1: D1Service) {}
 
   async findAll() {
-    return this.d1.prepare('SELECT * FROM posts').all();
+    return this.d1.database.prepare('SELECT * FROM posts').all();
   }
 
   async create(title: string) {
-    return this.d1.prepare('INSERT INTO posts (title) VALUES (?)').bind(title).run();
+    return this.d1.database.prepare('INSERT INTO posts (title) VALUES (?)').bind(title).run();
   }
 }
 ```
@@ -138,9 +156,9 @@ class AppModule {}
 class StorageService {
   constructor(private r2: R2Service) {}
 
-  async upload(key: string, data: string) { return this.r2.put(key, data); }
-  async download(key: string) { return this.r2.get(key); }
-  async remove(key: string) { return this.r2.delete(key); }
+  async upload(key: string, data: string) { return this.r2.bucket.put(key, data); }
+  async download(key: string) { return this.r2.bucket.get(key); }
+  async remove(key: string) { return this.r2.bucket.delete(key); }
 }
 ```
 
@@ -157,7 +175,7 @@ class NotificationService {
   constructor(private queue: QueueService) {}
 
   async sendEmail(to: string, subject: string) {
-    await this.queue.send({ to, subject });
+    await this.queue.queue.send({ to, subject });
   }
 }
 ```
@@ -175,8 +193,8 @@ class CounterService {
   constructor(private doNs: DurableObjectService) {}
 
   async increment(name: string) {
-    const id = this.doNs.idFromName(name);
-    const stub = this.doNs.get(id);
+    const id = this.doNs.namespace.idFromName(name);
+    const stub = this.doNs.namespace.get(id);
     return (stub as any).fetch('/increment');
   }
 }
@@ -195,7 +213,7 @@ class ChatService {
   constructor(private ai: AIService) {}
 
   async chat(prompt: string) {
-    return this.ai.run('@cf/meta/llama-3.1-8b-instruct', {
+    return this.ai.binding.run('@cf/meta/llama-3.1-8b-instruct', {
       messages: [{ role: 'user', content: prompt }],
     });
   }
@@ -215,11 +233,11 @@ class SearchService {
   constructor(private vectorize: VectorizeService) {}
 
   async search(vector: number[]) {
-    return this.vectorize.query(vector, { topK: 10 });
+    return this.vectorize.index.query(vector, { topK: 10 });
   }
 
   async addVectors(vectors: unknown[]) {
-    return this.vectorize.upsert(vectors);
+    return this.vectorize.index.upsert(vectors);
   }
 }
 ```
@@ -237,11 +255,11 @@ class DbService {
   constructor(private hd: HyperdriveService) {}
 
   getConnectionString() {
-    return this.hd.connectionString;
+    return this.hd.binding.connectionString;
   }
 
   getConfig() {
-    return { host: this.hd.host, port: this.hd.port, database: this.hd.database };
+    return { host: this.hd.binding.host, port: this.hd.binding.port, database: this.hd.binding.database };
   }
 }
 ```

package/dist/binding-ref.d.ts

@@ -1,15 +1,8 @@
-/**
- * Mutable holder for a Cloudflare binding value.
- *
- * Created by each module's `forRoot()` and populated by
- * `createCloudflareApp`'s one-time middleware on the first request.
- * Services access the binding lazily via `.value`.
- */
 export declare class BindingRef<T = unknown> {
     readonly bindingName: string;
     private _value;
     constructor(bindingName: string);
     get value(): T;
     /** @internal — called by createCloudflareApp middleware */
-    _initialize(value: any): void;
+    _initialize(value: T): void;
 }

package/dist/binding-ref.js

@@ -1,10 +1,7 @@
-/**
- * Mutable holder for a Cloudflare binding value.
- *
- * Created by each module's `forRoot()` and populated by
- * `createCloudflareApp`'s one-time middleware on the first request.
- * Services access the binding lazily via `.value`.
- */ export class BindingRef {
+// Mutable holder for a Cloudflare binding value. Created by each module's
+// forRoot() and populated by createCloudflareApp's one-time middleware on
+// the first request. Services access the binding lazily via .value.
+export class BindingRef {
     bindingName;
     _value;
     constructor(bindingName){
@@ -16,8 +13,7 @@
         }
         return this._value;
     }
-    /** @internal — called by createCloudflareApp middleware */ // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    _initialize(value) {
+    /** @internal — called by createCloudflareApp middleware */ _initialize(value) {
         this._value = value;
     }
 }

package/dist/cloudflare-application.d.ts

@@ -4,7 +4,8 @@ import type { CloudflareEnv } from './types';
 /**
  * Wraps VelaApplication with Cloudflare-specific handlers:
  * - `fetch` — HTTP request handler (from Hono)
- * - `scheduled` — Cron trigger handler (matches `@Scheduled()` decorators)
+ * - `scheduled` — Cron trigger handler (matches `@Scheduled()` decorators
+ *                 AND vela's own `@Cron()` jobs)
  * - `queue` — Queue consumer handler (matches `@QueueConsumer()` decorators)
  *
  * @example
@@ -28,7 +29,7 @@ export declare class CloudflareApplication {
     scanInstances(instances: unknown[]): void;
     /**
      * Handle Cloudflare scheduled (cron) events.
-     * Matches the event's cron expression to `@Scheduled()` handlers.
+     * Matches the event's cron expression to `@Scheduled()` and vela `@Cron()` handlers.
      */
     scheduled(event: {
         cron: string;
@@ -46,6 +47,5 @@ export declare class CloudflareApplication {
     }, env: CloudflareEnv, ctx: {
         waitUntil: (promise: Promise<unknown>) => void;
     }): Promise<void>;
-    /** Gracefully shut down the application. */
     close(signal?: string): Promise<void>;
 }

package/dist/cloudflare-application.js

@@ -1,10 +1,18 @@
 import { CRON_METADATA, getMetadata } from "@velajs/vela";
 import { getScheduledMetadata } from "./decorators/scheduled.js";
 import { getQueueConsumerMetadata } from "./decorators/queue-consumer.js";
+function invoke(instance, methodName, args) {
+    const method = instance[methodName];
+    if (typeof method !== 'function') {
+        throw new Error(`Method '${methodName}' is not a function on ${instance.constructor.name}`);
+    }
+    return method.apply(instance, args);
+}
 /**
  * Wraps VelaApplication with Cloudflare-specific handlers:
  * - `fetch` — HTTP request handler (from Hono)
- * - `scheduled` — Cron trigger handler (matches `@Scheduled()` decorators)
+ * - `scheduled` — Cron trigger handler (matches `@Scheduled()` decorators
+ *                 AND vela's own `@Cron()` jobs)
  * - `queue` — Queue consumer handler (matches `@QueueConsumer()` decorators)
  *
  * @example
@@ -32,14 +40,14 @@ import { getQueueConsumerMetadata } from "./decorators/queue-consumer.js";
     /** @internal — scans instances for @Scheduled, @Cron, and @QueueConsumer metadata */ scanInstances(instances) {
         for (const instance of instances){
             if (!instance || typeof instance !== 'object') continue;
-            const scheduledMeta = getScheduledMetadata(instance);
-            for (const meta of scheduledMeta){
+            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({
@@ -48,8 +56,7 @@ import { getQueueConsumerMetadata } from "./decorators/queue-consumer.js";
                     cron: meta.expression
                 });
             }
-            const queueMeta = getQueueConsumerMetadata(instance);
-            for (const meta of queueMeta){
+            for (const meta of getQueueConsumerMetadata(instance)){
                 this.queueConsumers.push({
                     instance,
                     methodName: meta.methodName,
@@ -60,27 +67,27 @@ import { getQueueConsumerMetadata } from "./decorators/queue-consumer.js";
     }
     /**
    * Handle Cloudflare scheduled (cron) events.
-   * Matches the event's cron expression to `@Scheduled()` handlers.
+   * Matches the event's cron expression to `@Scheduled()` and vela `@Cron()` handlers.
    */ async scheduled(event, env, ctx) {
         const matching = this.scheduledHandlers.filter((h)=>h.cron === event.cron);
-        const promises = matching.map((handler)=>{
-            const method = handler.instance[handler.methodName];
-            return method.call(handler.instance, event, env, ctx);
-        });
-        await Promise.all(promises);
+        await Promise.all(matching.map((h)=>invoke(h.instance, h.methodName, [
+                event,
+                env,
+                ctx
+            ])));
     }
     /**
    * Handle Cloudflare Queue consumer events.
    * Matches the batch queue name to `@QueueConsumer()` handlers.
    */ async queue(batch, env, ctx) {
         const matching = this.queueConsumers.filter((h)=>h.queueName === batch.queue);
-        const promises = matching.map((handler)=>{
-            const method = handler.instance[handler.methodName];
-            return method.call(handler.instance, batch, env, ctx);
-        });
-        await Promise.all(promises);
+        await Promise.all(matching.map((h)=>invoke(h.instance, h.methodName, [
+                batch,
+                env,
+                ctx
+            ])));
     }
-    /** Gracefully shut down the application. */ async close(signal) {
+    async close(signal) {
         return this.app.close(signal);
     }
 }

package/dist/cloudflare-factory.d.ts

@@ -3,8 +3,8 @@ import { CloudflareApplication } from './cloudflare-application';
 /**
  * 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.
+ * Sets up a one-time Hono middleware that captures `c.env` on the first
+ * request and initializes all configured binding refs.
  *
  * @example
  * ```ts

package/dist/cloudflare-factory.js

@@ -1,11 +1,28 @@
 import { VelaFactory } from "@velajs/vela";
+import { BindingRef } from "./binding-ref.js";
 import { CloudflareApplication } from "./cloudflare-application.js";
-import { bindingsRegistry } from "./tokens.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) {
+    const refs = [];
+    for (const token of container.getTokens()){
+        let value;
+        try {
+            value = container.resolve(token);
+        } catch  {
+            continue;
+        }
+        if (value instanceof BindingRef) refs.push(value);
+    }
+    return refs;
+}
 /**
  * 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.
+ * Sets up a one-time Hono middleware that captures `c.env` on the first
+ * request and initializes all configured binding refs.
  *
  * @example
  * ```ts
@@ -14,13 +31,14 @@ import { bindingsRegistry } from "./tokens.js";
  * ```
  */ export async function createCloudflareApp(rootModule) {
     let initialized = false;
+    let refs;
     const velaApp = await VelaFactory.create(rootModule, {
         middleware: [
             async (c, next)=>{
                 if (!initialized) {
                     initialized = true;
                     const env = c.env ?? {};
-                    for (const ref of bindingsRegistry){
+                    for (const ref of refs){
                         ref._initialize(env[ref.bindingName]);
                     }
                 }
@@ -28,6 +46,7 @@ import { bindingsRegistry } from "./tokens.js";
             }
         ]
     });
+    refs = collectBindingRefs(velaApp.getContainer());
     const cfApp = new CloudflareApplication(velaApp);
     cfApp.scanInstances(velaApp.getInstances());
     return cfApp;

package/dist/index.d.ts

@@ -19,9 +19,6 @@ export { HyperdriveService } from './services/hyperdrive.service';
 export { Env } from './decorators/env';
 export { Scheduled } from './decorators/scheduled';
 export { QueueConsumer } from './decorators/queue-consumer';
-export { BindingRef } from './binding-ref';
-export { bindingsRegistry, clearBindingsRegistry } from './tokens';
-export { KV_BINDING_REF, D1_BINDING_REF, R2_BINDING_REF, QUEUE_BINDING_REF, DO_BINDING_REF, AI_BINDING_REF, VECTORIZE_BINDING_REF, HYPERDRIVE_BINDING_REF, } from './tokens';
 export type { CloudflareEnv, ScheduledRegistration, QueueRegistration } from './types';
 export type { ScheduledMetadata } from './decorators/scheduled';
 export type { QueueConsumerMetadata } from './decorators/queue-consumer';

package/dist/index.js

@@ -23,7 +23,3 @@ export { HyperdriveService } from "./services/hyperdrive.service.js";
 export { Env } from "./decorators/env.js";
 export { Scheduled } from "./decorators/scheduled.js";
 export { QueueConsumer } from "./decorators/queue-consumer.js";
-// Internals (for advanced usage / testing)
-export { BindingRef } from "./binding-ref.js";
-export { bindingsRegistry, clearBindingsRegistry } from "./tokens.js";
-export { KV_BINDING_REF, D1_BINDING_REF, R2_BINDING_REF, QUEUE_BINDING_REF, DO_BINDING_REF, AI_BINDING_REF, VECTORIZE_BINDING_REF, HYPERDRIVE_BINDING_REF } from "./tokens.js";

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

@@ -1,6 +1 @@
-import { type DynamicModule } from '@velajs/vela';
-export declare class AIModule {
-    static forRoot(options: {
-        binding: string;
-    }): DynamicModule;
-}
+export declare const AIModule: import("./create-binding-module").BindingModuleStatic;

package/dist/modules/ai.module.js

@@ -1,24 +1,8 @@
-import { createModuleRef } from "@velajs/vela";
-import { BindingRef } from "../binding-ref.js";
-import { AI_BINDING_REF, bindingsRegistry } from "../tokens.js";
 import { AIService } from "../services/ai.service.js";
-export class AIModule {
-    static forRoot(options) {
-        const ref = new BindingRef(options.binding);
-        bindingsRegistry.push(ref);
-        return {
-            module: createModuleRef(`AIModule_${options.binding}`),
-            providers: [
-                {
-                    provide: AI_BINDING_REF,
-                    useValue: ref
-                },
-                AIService
-            ],
-            exports: [
-                AIService,
-                AI_BINDING_REF
-            ]
-        };
-    }
-}
+import { AI_BINDING_REF } from "../tokens.js";
+import { createBindingModule } from "./create-binding-module.js";
+export const AIModule = createBindingModule({
+    name: 'AI',
+    serviceClass: AIService,
+    bindingRefToken: AI_BINDING_REF
+});

package/dist/modules/create-binding-module.d.ts

@@ -0,0 +1,14 @@
+import { type DynamicModule, type InjectionToken, type Type } from '@velajs/vela';
+import { BindingRef } from '../binding-ref';
+interface CreateBindingModuleOptions<TService> {
+    name: string;
+    serviceClass: Type<TService>;
+    bindingRefToken: InjectionToken<BindingRef>;
+}
+export interface BindingModuleStatic {
+    forRoot(options: {
+        binding: string;
+    }): DynamicModule;
+}
+export declare function createBindingModule<TService>(opts: CreateBindingModuleOptions<TService>): BindingModuleStatic;
+export {};

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

@@ -0,0 +1,45 @@
+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.
+//
+// Identity model (post vela audit #2):
+//   - One real module class is declared per binding TYPE (KV, D1, R2, ...).
+//     Its `name` property is set so error messages and diagnostics carry
+//     the friendly name (e.g. `KVModule`).
+//   - Each `forRoot({ binding })` returns `{ module, key: binding, ... }`.
+//     Vela dedups by (module, key), so two `KVModule.forRoot({...})` calls
+//     with different bindings coexist as distinct module instances; two
+//     calls with the same binding dedup.
+export function createBindingModule(opts) {
+    // Fresh module class per binding TYPE (one KVModule, one D1Module, ...).
+    // The computed-property-name idiom is the canonical JS way to give a
+    // class expression a dynamic `name`: NamedEvaluation reads the property
+    // key and stamps it on the class at creation, instead of patching the
+    // (configurable, non-writable) `name` slot via Object.defineProperty.
+    const className = `${opts.name}Module`;
+    const moduleClass = {
+        [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
+                ]
+            };
+        }
+    };
+}

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

@@ -1,6 +1 @@
-import { type DynamicModule } from '@velajs/vela';
-export declare class D1Module {
-    static forRoot(options: {
-        binding: string;
-    }): DynamicModule;
-}
+export declare const D1Module: import("./create-binding-module").BindingModuleStatic;

package/dist/modules/d1.module.js

@@ -1,24 +1,8 @@
-import { createModuleRef } from "@velajs/vela";
-import { BindingRef } from "../binding-ref.js";
-import { D1_BINDING_REF, bindingsRegistry } from "../tokens.js";
 import { D1Service } from "../services/d1.service.js";
-export class D1Module {
-    static forRoot(options) {
-        const ref = new BindingRef(options.binding);
-        bindingsRegistry.push(ref);
-        return {
-            module: createModuleRef(`D1Module_${options.binding}`),
-            providers: [
-                {
-                    provide: D1_BINDING_REF,
-                    useValue: ref
-                },
-                D1Service
-            ],
-            exports: [
-                D1Service,
-                D1_BINDING_REF
-            ]
-        };
-    }
-}
+import { D1_BINDING_REF } from "../tokens.js";
+import { createBindingModule } from "./create-binding-module.js";
+export const D1Module = createBindingModule({
+    name: 'D1',
+    serviceClass: D1Service,
+    bindingRefToken: D1_BINDING_REF
+});

package/dist/modules/durable-object.module.d.ts

@@ -1,6 +1 @@
-import { type DynamicModule } from '@velajs/vela';
-export declare class DurableObjectModule {
-    static forRoot(options: {
-        binding: string;
-    }): DynamicModule;
-}
+export declare const DurableObjectModule: import("./create-binding-module").BindingModuleStatic;

package/dist/modules/durable-object.module.js

@@ -1,24 +1,8 @@
-import { createModuleRef } from "@velajs/vela";
-import { BindingRef } from "../binding-ref.js";
-import { DO_BINDING_REF, bindingsRegistry } from "../tokens.js";
 import { DurableObjectService } from "../services/durable-object.service.js";
-export class DurableObjectModule {
-    static forRoot(options) {
-        const ref = new BindingRef(options.binding);
-        bindingsRegistry.push(ref);
-        return {
-            module: createModuleRef(`DurableObjectModule_${options.binding}`),
-            providers: [
-                {
-                    provide: DO_BINDING_REF,
-                    useValue: ref
-                },
-                DurableObjectService
-            ],
-            exports: [
-                DurableObjectService,
-                DO_BINDING_REF
-            ]
-        };
-    }
-}
+import { DO_BINDING_REF } from "../tokens.js";
+import { createBindingModule } from "./create-binding-module.js";
+export const DurableObjectModule = createBindingModule({
+    name: 'DurableObject',
+    serviceClass: DurableObjectService,
+    bindingRefToken: DO_BINDING_REF
+});

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

@@ -1,6 +1 @@
-import { type DynamicModule } from '@velajs/vela';
-export declare class HyperdriveModule {
-    static forRoot(options: {
-        binding: string;
-    }): DynamicModule;
-}
+export declare const HyperdriveModule: import("./create-binding-module").BindingModuleStatic;

package/dist/modules/hyperdrive.module.js

@@ -1,24 +1,8 @@
-import { createModuleRef } from "@velajs/vela";
-import { BindingRef } from "../binding-ref.js";
-import { HYPERDRIVE_BINDING_REF, bindingsRegistry } from "../tokens.js";
 import { HyperdriveService } from "../services/hyperdrive.service.js";
-export class HyperdriveModule {
-    static forRoot(options) {
-        const ref = new BindingRef(options.binding);
-        bindingsRegistry.push(ref);
-        return {
-            module: createModuleRef(`HyperdriveModule_${options.binding}`),
-            providers: [
-                {
-                    provide: HYPERDRIVE_BINDING_REF,
-                    useValue: ref
-                },
-                HyperdriveService
-            ],
-            exports: [
-                HyperdriveService,
-                HYPERDRIVE_BINDING_REF
-            ]
-        };
-    }
-}
+import { HYPERDRIVE_BINDING_REF } from "../tokens.js";
+import { createBindingModule } from "./create-binding-module.js";
+export const HyperdriveModule = createBindingModule({
+    name: 'Hyperdrive',
+    serviceClass: HyperdriveService,
+    bindingRefToken: HYPERDRIVE_BINDING_REF
+});

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

@@ -1,6 +1 @@
-import { type DynamicModule } from '@velajs/vela';
-export declare class KVModule {
-    static forRoot(options: {
-        binding: string;
-    }): DynamicModule;
-}
+export declare const KVModule: import("./create-binding-module").BindingModuleStatic;

package/dist/modules/kv.module.js

@@ -1,24 +1,8 @@
-import { createModuleRef } from "@velajs/vela";
-import { BindingRef } from "../binding-ref.js";
-import { KV_BINDING_REF, bindingsRegistry } from "../tokens.js";
 import { KVService } from "../services/kv.service.js";
-export class KVModule {
-    static forRoot(options) {
-        const ref = new BindingRef(options.binding);
-        bindingsRegistry.push(ref);
-        return {
-            module: createModuleRef(`KVModule_${options.binding}`),
-            providers: [
-                {
-                    provide: KV_BINDING_REF,
-                    useValue: ref
-                },
-                KVService
-            ],
-            exports: [
-                KVService,
-                KV_BINDING_REF
-            ]
-        };
-    }
-}
+import { KV_BINDING_REF } from "../tokens.js";
+import { createBindingModule } from "./create-binding-module.js";
+export const KVModule = createBindingModule({
+    name: 'KV',
+    serviceClass: KVService,
+    bindingRefToken: KV_BINDING_REF
+});

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

@@ -1,6 +1 @@
-import { type DynamicModule } from '@velajs/vela';
-export declare class QueueModule {
-    static forRoot(options: {
-        binding: string;
-    }): DynamicModule;
-}
+export declare const QueueModule: import("./create-binding-module").BindingModuleStatic;

package/dist/modules/queue.module.js

@@ -1,24 +1,8 @@
-import { createModuleRef } from "@velajs/vela";
-import { BindingRef } from "../binding-ref.js";
-import { QUEUE_BINDING_REF, bindingsRegistry } from "../tokens.js";
 import { QueueService } from "../services/queue.service.js";
-export class QueueModule {
-    static forRoot(options) {
-        const ref = new BindingRef(options.binding);
-        bindingsRegistry.push(ref);
-        return {
-            module: createModuleRef(`QueueModule_${options.binding}`),
-            providers: [
-                {
-                    provide: QUEUE_BINDING_REF,
-                    useValue: ref
-                },
-                QueueService
-            ],
-            exports: [
-                QueueService,
-                QUEUE_BINDING_REF
-            ]
-        };
-    }
-}
+import { QUEUE_BINDING_REF } from "../tokens.js";
+import { createBindingModule } from "./create-binding-module.js";
+export const QueueModule = createBindingModule({
+    name: 'Queue',
+    serviceClass: QueueService,
+    bindingRefToken: QUEUE_BINDING_REF
+});

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

@@ -1,6 +1 @@
-import { type DynamicModule } from '@velajs/vela';
-export declare class R2Module {
-    static forRoot(options: {
-        binding: string;
-    }): DynamicModule;
-}
+export declare const R2Module: import("./create-binding-module").BindingModuleStatic;

package/dist/modules/r2.module.js

@@ -1,24 +1,8 @@
-import { createModuleRef } from "@velajs/vela";
-import { BindingRef } from "../binding-ref.js";
-import { R2_BINDING_REF, bindingsRegistry } from "../tokens.js";
 import { R2Service } from "../services/r2.service.js";
-export class R2Module {
-    static forRoot(options) {
-        const ref = new BindingRef(options.binding);
-        bindingsRegistry.push(ref);
-        return {
-            module: createModuleRef(`R2Module_${options.binding}`),
-            providers: [
-                {
-                    provide: R2_BINDING_REF,
-                    useValue: ref
-                },
-                R2Service
-            ],
-            exports: [
-                R2Service,
-                R2_BINDING_REF
-            ]
-        };
-    }
-}
+import { R2_BINDING_REF } from "../tokens.js";
+import { createBindingModule } from "./create-binding-module.js";
+export const R2Module = createBindingModule({
+    name: 'R2',
+    serviceClass: R2Service,
+    bindingRefToken: R2_BINDING_REF
+});

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

@@ -1,6 +1 @@
-import { type DynamicModule } from '@velajs/vela';
-export declare class VectorizeModule {
-    static forRoot(options: {
-        binding: string;
-    }): DynamicModule;
-}
+export declare const VectorizeModule: import("./create-binding-module").BindingModuleStatic;

package/dist/modules/vectorize.module.js

@@ -1,24 +1,8 @@
-import { createModuleRef } from "@velajs/vela";
-import { BindingRef } from "../binding-ref.js";
-import { VECTORIZE_BINDING_REF, bindingsRegistry } from "../tokens.js";
 import { VectorizeService } from "../services/vectorize.service.js";
-export class VectorizeModule {
-    static forRoot(options) {
-        const ref = new BindingRef(options.binding);
-        bindingsRegistry.push(ref);
-        return {
-            module: createModuleRef(`VectorizeModule_${options.binding}`),
-            providers: [
-                {
-                    provide: VECTORIZE_BINDING_REF,
-                    useValue: ref
-                },
-                VectorizeService
-            ],
-            exports: [
-                VectorizeService,
-                VECTORIZE_BINDING_REF
-            ]
-        };
-    }
-}
+import { VECTORIZE_BINDING_REF } from "../tokens.js";
+import { createBindingModule } from "./create-binding-module.js";
+export const VectorizeModule = createBindingModule({
+    name: 'Vectorize',
+    serviceClass: VectorizeService,
+    bindingRefToken: VECTORIZE_BINDING_REF
+});

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

@@ -1,16 +1,6 @@
 import type { BindingRef } from '../binding-ref';
-type AIBinding = {
-    run: Function;
-} & Record<string, any>;
-/**
- * Wrapper around Cloudflare Workers AI binding.
- * Injected via `AIModule.forRoot({ binding: 'AI' })`.
- */
 export declare class AIService {
     private ref;
-    constructor(ref: BindingRef);
-    /** Access the raw Ai binding directly. */
-    get binding(): AIBinding;
-    run(model: string, inputs: Record<string, unknown>, options?: Record<string, unknown>): Promise<unknown>;
+    constructor(ref: BindingRef<Ai>);
+    get binding(): Ai;
 }
-export {};

package/dist/services/ai.service.js

@@ -19,12 +19,9 @@ export class AIService {
     constructor(ref){
         this.ref = ref;
     }
-    /** Access the raw Ai binding directly. */ get binding() {
+    get binding() {
         return this.ref.value;
     }
-    run(model, inputs, options) {
-        return this.binding.run(model, inputs, options);
-    }
 }
 AIService = _ts_decorate([
     Injectable(),

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

@@ -1,22 +1,6 @@
 import type { BindingRef } from '../binding-ref';
-type D1Binding = {
-    prepare: Function;
-    batch: Function;
-    exec: Function;
-    dump: Function;
-} & Record<string, any>;
-/**
- * Wrapper around Cloudflare D1 Database.
- * Injected via `D1Module.forRoot({ binding: 'DB' })`.
- */
 export declare class D1Service {
     private ref;
-    constructor(ref: BindingRef);
-    /** Access the raw D1Database binding directly. */
-    get database(): D1Binding;
-    prepare(query: string): any;
-    batch(statements: unknown[]): Promise<any[]>;
-    exec(query: string): Promise<unknown>;
-    dump(): Promise<ArrayBuffer>;
+    constructor(ref: BindingRef<D1Database>);
+    get database(): D1Database;
 }
-export {};

package/dist/services/d1.service.js

@@ -19,23 +19,9 @@ export class D1Service {
     constructor(ref){
         this.ref = ref;
     }
-    /** Access the raw D1Database binding directly. */ get database() {
+    get database() {
         return this.ref.value;
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    prepare(query) {
-        return this.database.prepare(query);
-    }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    batch(statements) {
-        return this.database.batch(statements);
-    }
-    exec(query) {
-        return this.database.exec(query);
-    }
-    dump() {
-        return this.database.dump();
-    }
 }
 D1Service = _ts_decorate([
     Injectable(),

package/dist/services/durable-object.service.d.ts

@@ -1,24 +1,6 @@
 import type { BindingRef } from '../binding-ref';
-type DOBinding = {
-    newUniqueId: Function;
-    idFromName: Function;
-    idFromString: Function;
-    get: Function;
-    jurisdiction: Function;
-} & Record<string, any>;
-/**
- * Wrapper around Cloudflare DurableObjectNamespace.
- * Injected via `DurableObjectModule.forRoot({ binding: 'COUNTER' })`.
- */
 export declare class DurableObjectService {
     private ref;
-    constructor(ref: BindingRef);
-    /** Access the raw DurableObjectNamespace binding directly. */
-    get namespace(): DOBinding;
-    newUniqueId(options?: Record<string, unknown>): unknown;
-    idFromName(name: string): unknown;
-    idFromString(hexStr: string): unknown;
-    get(id: unknown): unknown;
-    jurisdiction(name: string): unknown;
+    constructor(ref: BindingRef<DurableObjectNamespace>);
+    get namespace(): DurableObjectNamespace;
 }
-export {};

package/dist/services/durable-object.service.js

@@ -19,24 +19,9 @@ export class DurableObjectService {
     constructor(ref){
         this.ref = ref;
     }
-    /** Access the raw DurableObjectNamespace binding directly. */ get namespace() {
+    get namespace() {
         return this.ref.value;
     }
-    newUniqueId(options) {
-        return this.namespace.newUniqueId(options);
-    }
-    idFromName(name) {
-        return this.namespace.idFromName(name);
-    }
-    idFromString(hexStr) {
-        return this.namespace.idFromString(hexStr);
-    }
-    get(id) {
-        return this.namespace.get(id);
-    }
-    jurisdiction(name) {
-        return this.namespace.jurisdiction(name);
-    }
 }
 DurableObjectService = _ts_decorate([
     Injectable(),

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

@@ -1,21 +1,8 @@
 import type { BindingRef } from '../binding-ref';
-type HyperdriveBinding = {
-    connectionString: string;
-    host: string;
-    port: number;
-    user: string;
-    password: string;
-    database: string;
-} & Record<string, any>;
-/**
- * Wrapper around Cloudflare Hyperdrive binding.
- * Injected via `HyperdriveModule.forRoot({ binding: 'POSTGRES' })`.
- */
 export declare class HyperdriveService {
     private ref;
-    constructor(ref: BindingRef);
-    /** Access the raw Hyperdrive binding directly. */
-    get binding(): HyperdriveBinding;
+    constructor(ref: BindingRef<Hyperdrive>);
+    get binding(): Hyperdrive;
     get connectionString(): string;
     get host(): string;
     get port(): number;
@@ -23,4 +10,3 @@ export declare class HyperdriveService {
     get password(): string;
     get database(): string;
 }
-export {};

package/dist/services/hyperdrive.service.js

@@ -19,7 +19,7 @@ export class HyperdriveService {
     constructor(ref){
         this.ref = ref;
     }
-    /** Access the raw Hyperdrive binding directly. */ get binding() {
+    get binding() {
         return this.ref.value;
     }
     get connectionString() {

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

@@ -1,24 +1,11 @@
 import type { BindingRef } from '../binding-ref';
-type KVBinding = {
-    get: Function;
-    getWithMetadata: Function;
-    put: Function;
-    delete: Function;
-    list: Function;
-} & Record<string, any>;
 /**
- * Wrapper around Cloudflare KV Namespace.
- * Injected via `KVModule.forRoot({ binding: 'MY_KV' })`.
+ * Wrapper around a Cloudflare KV namespace binding.
+ * Use `kv.namespace.get(...)`, `kv.namespace.put(...)`, etc. — the namespace
+ * is the standard @cloudflare/workers-types `KVNamespace`.
  */
 export declare class KVService {
     private ref;
-    constructor(ref: BindingRef);
-    /** Access the raw KVNamespace binding directly. */
-    get namespace(): KVBinding;
-    get(key: string, typeOrOptions?: string | Record<string, unknown>): Promise<unknown>;
-    getWithMetadata(key: string, typeOrOptions?: string | Record<string, unknown>): Promise<unknown>;
-    put(key: string, value: string | ArrayBuffer | ReadableStream, options?: Record<string, unknown>): Promise<void>;
-    delete(key: string): Promise<void>;
-    list(options?: Record<string, unknown>): Promise<unknown>;
+    constructor(ref: BindingRef<KVNamespace>);
+    get namespace(): KVNamespace;
 }
-export {};

package/dist/services/kv.service.js

@@ -19,24 +19,9 @@ export class KVService {
     constructor(ref){
         this.ref = ref;
     }
-    /** Access the raw KVNamespace binding directly. */ get namespace() {
+    get namespace() {
         return this.ref.value;
     }
-    get(key, typeOrOptions) {
-        return this.namespace.get(key, typeOrOptions);
-    }
-    getWithMetadata(key, typeOrOptions) {
-        return this.namespace.getWithMetadata(key, typeOrOptions);
-    }
-    put(key, value, options) {
-        return this.namespace.put(key, value, options);
-    }
-    delete(key) {
-        return this.namespace.delete(key);
-    }
-    list(options) {
-        return this.namespace.list(options);
-    }
 }
 KVService = _ts_decorate([
     Injectable(),

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

@@ -1,20 +1,6 @@
 import type { BindingRef } from '../binding-ref';
-type QueueBinding = Record<string, any>;
-/**
- * Wrapper around Cloudflare Queue (producer side).
- * Injected via `QueueModule.forRoot({ binding: 'MY_QUEUE' })`.
- *
- * For consuming messages, use the `@QueueConsumer()` decorator.
- */
-export declare class QueueService {
+export declare class QueueService<Body = unknown> {
     private ref;
-    constructor(ref: BindingRef);
-    /** Access the raw Queue binding directly. */
-    get queue(): QueueBinding;
-    send(message: unknown, options?: Record<string, unknown>): Promise<void>;
-    sendBatch(messages: Iterable<{
-        body: unknown;
-        [key: string]: unknown;
-    }>, options?: Record<string, unknown>): Promise<void>;
+    constructor(ref: BindingRef<Queue<Body>>);
+    get queue(): Queue<Body>;
 }
-export {};

package/dist/services/queue.service.js

@@ -19,15 +19,9 @@ export class QueueService {
     constructor(ref){
         this.ref = ref;
     }
-    /** Access the raw Queue binding directly. */ get queue() {
+    get queue() {
         return this.ref.value;
     }
-    send(message, options) {
-        return this.queue.send(message, options);
-    }
-    sendBatch(messages, options) {
-        return this.queue.sendBatch(messages, options);
-    }
 }
 QueueService = _ts_decorate([
     Injectable(),

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

@@ -1,18 +1,6 @@
 import type { BindingRef } from '../binding-ref';
-type R2Binding = Record<string, any>;
-/**
- * Wrapper around Cloudflare R2 Bucket.
- * Injected via `R2Module.forRoot({ binding: 'ASSETS' })`.
- */
 export declare class R2Service {
     private ref;
-    constructor(ref: BindingRef);
-    /** Access the raw R2Bucket binding directly. */
-    get bucket(): R2Binding;
-    get(key: string, options?: Record<string, unknown>): Promise<unknown>;
-    head(key: string): Promise<unknown>;
-    put(key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | null | Blob, options?: Record<string, unknown>): Promise<unknown>;
-    delete(keys: string | string[]): Promise<void>;
-    list(options?: Record<string, unknown>): Promise<unknown>;
+    constructor(ref: BindingRef<R2Bucket>);
+    get bucket(): R2Bucket;
 }
-export {};

package/dist/services/r2.service.js

@@ -19,24 +19,9 @@ export class R2Service {
     constructor(ref){
         this.ref = ref;
     }
-    /** Access the raw R2Bucket binding directly. */ get bucket() {
+    get bucket() {
         return this.ref.value;
     }
-    get(key, options) {
-        return this.bucket.get(key, options);
-    }
-    head(key) {
-        return this.bucket.head(key);
-    }
-    put(key, value, options) {
-        return this.bucket.put(key, value, options);
-    }
-    delete(keys) {
-        return this.bucket.delete(keys);
-    }
-    list(options) {
-        return this.bucket.list(options);
-    }
 }
 R2Service = _ts_decorate([
     Injectable(),

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

@@ -1,26 +1,6 @@
 import type { BindingRef } from '../binding-ref';
-type VectorizeBinding = {
-    query: Function;
-    insert: Function;
-    upsert: Function;
-    getByIds: Function;
-    deleteByIds: Function;
-    describe: Function;
-} & Record<string, any>;
-/**
- * Wrapper around Cloudflare Vectorize Index.
- * Injected via `VectorizeModule.forRoot({ binding: 'EMBEDDINGS' })`.
- */
 export declare class VectorizeService {
     private ref;
-    constructor(ref: BindingRef);
-    /** Access the raw VectorizeIndex binding directly. */
-    get index(): VectorizeBinding;
-    query(vector: number[], options?: Record<string, unknown>): Promise<unknown>;
-    insert(vectors: unknown[]): Promise<unknown>;
-    upsert(vectors: unknown[]): Promise<unknown>;
-    getByIds(ids: string[]): Promise<unknown>;
-    deleteByIds(ids: string[]): Promise<unknown>;
-    describe(): Promise<unknown>;
+    constructor(ref: BindingRef<VectorizeIndex>);
+    get index(): VectorizeIndex;
 }
-export {};

package/dist/services/vectorize.service.js

@@ -19,27 +19,9 @@ export class VectorizeService {
     constructor(ref){
         this.ref = ref;
     }
-    /** Access the raw VectorizeIndex binding directly. */ get index() {
+    get index() {
         return this.ref.value;
     }
-    query(vector, options) {
-        return this.index.query(vector, options);
-    }
-    insert(vectors) {
-        return this.index.insert(vectors);
-    }
-    upsert(vectors) {
-        return this.index.upsert(vectors);
-    }
-    getByIds(ids) {
-        return this.index.getByIds(ids);
-    }
-    deleteByIds(ids) {
-        return this.index.deleteByIds(ids);
-    }
-    describe() {
-        return this.index.describe();
-    }
 }
 VectorizeService = _ts_decorate([
     Injectable(),

package/dist/tokens.d.ts

@@ -8,10 +8,3 @@ 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>>;
-/**
- * Global registry of binding refs to initialize on first request.
- * Each module's `forRoot()` pushes its BindingRef here.
- * createCloudflareApp reads from this to populate bindings.
- */
-export declare const bindingsRegistry: BindingRef[];
-export declare function clearBindingsRegistry(): void;

package/dist/tokens.js

@@ -1,5 +1,5 @@
 import { InjectionToken } from "@velajs/vela";
-// Internal tokens for binding refs — used by services
+// Tokens for binding refs — used by services to receive the binding value.
 export const KV_BINDING_REF = new InjectionToken('CF_KV_BINDING_REF');
 export const D1_BINDING_REF = new InjectionToken('CF_D1_BINDING_REF');
 export const R2_BINDING_REF = new InjectionToken('CF_R2_BINDING_REF');
@@ -8,11 +8,3 @@ 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');
-/**
- * Global registry of binding refs to initialize on first request.
- * Each module's `forRoot()` pushes its BindingRef here.
- * createCloudflareApp reads from this to populate bindings.
- */ export const bindingsRegistry = [];
-export function clearBindingsRegistry() {
-    bindingsRegistry.length = 0;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/cloudflare",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Cloudflare Workers integration for Vela framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,18 +44,15 @@
     "node": ">=20"
   },
   "peerDependencies": {
-    "@velajs/vela": ">=1.0.0",
+    "@cloudflare/workers-types": ">=4",
+    "@velajs/vela": ">=1.5.0",
     "hono": ">=4"
   },
-  "peerDependenciesMeta": {
-    "@velajs/vela": {
-      "optional": true
-    }
-  },
   "devDependencies": {
+    "@cloudflare/workers-types": "^4",
     "@swc/cli": "^0.8.0",
     "@swc/core": "^1.15.11",
-    "@velajs/vela": "^1.0.0",
+    "@velajs/vela": "^1.5.0",
     "hono": "^4",
     "typescript": "^5",
     "unplugin-swc": "^1.5.9",