@velajs/cloudflare 0.1.0

package/README.md

@@ -0,0 +1,372 @@
+# @velajs/cloudflare
+
+Cloudflare Workers integration for the [Vela](https://github.com/velajs/vela) framework. NestJS-style per-service modules for KV, D1, R2, Queues, Durable Objects, Workers AI, Vectorize, and Hyperdrive.
+
+## Install
+
+```bash
+bun add @velajs/cloudflare @velajs/vela hono
+```
+
+## Quick Start
+
+```ts
+import { Controller, Get, Module, Injectable, Param } from '@velajs/vela';
+import { CloudflareFactory, KVModule, D1Module } from '@velajs/cloudflare';
+import type { KVService, D1Service } from '@velajs/cloudflare';
+
+@Injectable()
+class UserService {
+  constructor(
+    private kv: KVService,
+    private d1: D1Service,
+  ) {}
+
+  async findById(id: string) {
+    const cached = await this.kv.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));
+    return user;
+  }
+}
+
+@Controller('/users')
+class UserController {
+  constructor(private users: UserService) {}
+
+  @Get('/:id')
+  async getUser(@Param('id') id: string) {
+    return this.users.findById(id);
+  }
+}
+
+@Module({
+  imports: [
+    KVModule.forRoot({ binding: 'CACHE' }),
+    D1Module.forRoot({ binding: 'DB' }),
+  ],
+  providers: [UserService],
+  controllers: [UserController],
+})
+class AppModule {}
+
+export default await CloudflareFactory.create(AppModule);
+```
+
+The `binding` string matches the binding name in your `wrangler.toml`:
+
+```toml
+[[kv_namespaces]]
+binding = "CACHE"
+id = "abc123"
+
+[[d1_databases]]
+binding = "DB"
+database_id = "def456"
+```
+
+## Modules
+
+Each module follows the same pattern: `XModule.forRoot({ binding: 'NAME' })` returns a dynamic module that provides a service wrapping the Cloudflare binding.
+
+| Module | Service | Cloudflare Binding |
+|--------|---------|-------------------|
+| `KVModule` | `KVService` | KV Namespace |
+| `D1Module` | `D1Service` | D1 Database |
+| `R2Module` | `R2Service` | R2 Bucket |
+| `QueueModule` | `QueueService` | Queue (producer) |
+| `DurableObjectModule` | `DurableObjectService` | Durable Object Namespace |
+| `AIModule` | `AIService` | Workers AI |
+| `VectorizeModule` | `VectorizeService` | Vectorize Index |
+| `HyperdriveModule` | `HyperdriveService` | Hyperdrive |
+
+### KVModule
+
+```ts
+import { KVModule } from '@velajs/cloudflare';
+import type { KVService } from '@velajs/cloudflare';
+
+@Module({ imports: [KVModule.forRoot({ binding: 'MY_KV' })] })
+class AppModule {}
+
+@Injectable()
+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(); }
+}
+```
+
+### D1Module
+
+```ts
+import { D1Module } from '@velajs/cloudflare';
+import type { D1Service } from '@velajs/cloudflare';
+
+@Module({ imports: [D1Module.forRoot({ binding: 'DB' })] })
+class AppModule {}
+
+@Injectable()
+class PostService {
+  constructor(private d1: D1Service) {}
+
+  async findAll() {
+    return this.d1.prepare('SELECT * FROM posts').all();
+  }
+
+  async create(title: string) {
+    return this.d1.prepare('INSERT INTO posts (title) VALUES (?)').bind(title).run();
+  }
+}
+```
+
+### R2Module
+
+```ts
+import { R2Module } from '@velajs/cloudflare';
+import type { R2Service } from '@velajs/cloudflare';
+
+@Module({ imports: [R2Module.forRoot({ binding: 'ASSETS' })] })
+class AppModule {}
+
+@Injectable()
+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); }
+}
+```
+
+### QueueModule
+
+```ts
+import { QueueModule } from '@velajs/cloudflare';
+import type { QueueService } from '@velajs/cloudflare';
+
+@Module({ imports: [QueueModule.forRoot({ binding: 'EMAIL_QUEUE' })] })
+class AppModule {}
+
+@Injectable()
+class NotificationService {
+  constructor(private queue: QueueService) {}
+
+  async sendEmail(to: string, subject: string) {
+    await this.queue.send({ to, subject });
+  }
+}
+```
+
+### DurableObjectModule
+
+```ts
+import { DurableObjectModule } from '@velajs/cloudflare';
+import type { DurableObjectService } from '@velajs/cloudflare';
+
+@Module({ imports: [DurableObjectModule.forRoot({ binding: 'COUNTER' })] })
+class AppModule {}
+
+@Injectable()
+class CounterService {
+  constructor(private doNs: DurableObjectService) {}
+
+  async increment(name: string) {
+    const id = this.doNs.idFromName(name);
+    const stub = this.doNs.get(id);
+    return (stub as any).fetch('/increment');
+  }
+}
+```
+
+### AIModule
+
+```ts
+import { AIModule } from '@velajs/cloudflare';
+import type { AIService } from '@velajs/cloudflare';
+
+@Module({ imports: [AIModule.forRoot({ binding: 'AI' })] })
+class AppModule {}
+
+@Injectable()
+class ChatService {
+  constructor(private ai: AIService) {}
+
+  async chat(prompt: string) {
+    return this.ai.run('@cf/meta/llama-3.1-8b-instruct', {
+      messages: [{ role: 'user', content: prompt }],
+    });
+  }
+}
+```
+
+### VectorizeModule
+
+```ts
+import { VectorizeModule } from '@velajs/cloudflare';
+import type { VectorizeService } from '@velajs/cloudflare';
+
+@Module({ imports: [VectorizeModule.forRoot({ binding: 'EMBEDDINGS' })] })
+class AppModule {}
+
+@Injectable()
+class SearchService {
+  constructor(private vectorize: VectorizeService) {}
+
+  async search(vector: number[]) {
+    return this.vectorize.query(vector, { topK: 10 });
+  }
+
+  async addVectors(vectors: unknown[]) {
+    return this.vectorize.upsert(vectors);
+  }
+}
+```
+
+### HyperdriveModule
+
+```ts
+import { HyperdriveModule } from '@velajs/cloudflare';
+import type { HyperdriveService } from '@velajs/cloudflare';
+
+@Module({ imports: [HyperdriveModule.forRoot({ binding: 'POSTGRES' })] })
+class AppModule {}
+
+@Injectable()
+class DbService {
+  constructor(private hd: HyperdriveService) {}
+
+  getConnectionString() {
+    return this.hd.connectionString;
+  }
+
+  getConfig() {
+    return { host: this.hd.host, port: this.hd.port, database: this.hd.database };
+  }
+}
+```
+
+## Decorators
+
+### @Env()
+
+Parameter decorator for direct access to Cloudflare bindings in controllers. Useful as an escape hatch when you don't need a full module.
+
+```ts
+import { Env } from '@velajs/cloudflare';
+
+@Controller('/debug')
+class DebugController {
+  @Get('/env')
+  handle(@Env() env: Record<string, unknown>) {
+    return { bindings: Object.keys(env) };
+  }
+
+  @Get('/kv')
+  handleKV(@Env('MY_KV') kv: KVNamespace) {
+    return kv.get('some-key');
+  }
+}
+```
+
+### @Scheduled()
+
+Method decorator for cron trigger handlers.
+
+```ts
+import { Scheduled } from '@velajs/cloudflare';
+
+@Injectable()
+class CleanupService {
+  @Scheduled('0 * * * *')  // every hour
+  async hourlyCleanup() {
+    console.log('Running hourly cleanup');
+  }
+
+  @Scheduled('0 0 * * *')  // every day at midnight
+  async dailyReport() {
+    console.log('Generating daily report');
+  }
+}
+```
+
+### @QueueConsumer()
+
+Method decorator for queue consumer handlers.
+
+```ts
+import { QueueConsumer } from '@velajs/cloudflare';
+
+@Injectable()
+class EmailWorker {
+  @QueueConsumer('email-queue')
+  async process(batch: MessageBatch) {
+    for (const msg of batch.messages) {
+      console.log('Sending email:', msg.body);
+      msg.ack();
+    }
+  }
+}
+```
+
+## CloudflareFactory
+
+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.
+
+```ts
+import { CloudflareFactory } from '@velajs/cloudflare';
+
+const app = await CloudflareFactory.create(AppModule);
+export default app;
+```
+
+## Full Worker Export
+
+To use scheduled triggers and queue consumers, export the handlers explicitly:
+
+```ts
+const app = await CloudflareFactory.create(AppModule);
+
+export default {
+  fetch: app.fetch,
+  scheduled: app.scheduled.bind(app),
+  queue: app.queue.bind(app),
+};
+```
+
+## Raw Binding Access
+
+Each service exposes the underlying Cloudflare binding via a getter:
+
+```ts
+const rawKV = kvService.namespace;     // KVNamespace
+const rawD1 = d1Service.database;      // D1Database
+const rawR2 = r2Service.bucket;        // R2Bucket
+const rawQueue = queueService.queue;   // Queue
+const rawDO = doService.namespace;     // DurableObjectNamespace
+const rawAI = aiService.binding;       // Ai
+const rawVec = vecService.index;       // VectorizeIndex
+const rawHD = hdService.binding;       // Hyperdrive
+```
+
+## How It Works
+
+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:
+
+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
+3. On the first HTTP request, a one-time middleware reads `c.env` and initializes all `BindingRef` instances
+4. From that point on, services access bindings lazily through the ref
+
+This means binding-dependent services work as plain singletons with no per-request overhead.
+
+## License
+
+MIT

package/dist/binding-ref.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Mutable holder for a Cloudflare binding value.
+ *
+ * Created by each module's `forRoot()` and populated by
+ * CloudflareFactory'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 CloudflareFactory middleware */
+    _initialize(value: any): void;
+}

package/dist/binding-ref.js

@@ -0,0 +1,23 @@
+/**
+ * Mutable holder for a Cloudflare binding value.
+ *
+ * Created by each module's `forRoot()` and populated by
+ * CloudflareFactory's one-time middleware on the first request.
+ * Services access the binding lazily via `.value`.
+ */ export class BindingRef {
+    bindingName;
+    _value;
+    constructor(bindingName){
+        this.bindingName = bindingName;
+    }
+    get value() {
+        if (this._value === undefined) {
+            throw new Error(`Cloudflare binding '${this.bindingName}' not initialized. ` + `Ensure CloudflareFactory.create() is used and a request has been made.`);
+        }
+        return this._value;
+    }
+    /** @internal — called by CloudflareFactory middleware */ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _initialize(value) {
+        this._value = value;
+    }
+}

package/dist/cloudflare-application.d.ts

@@ -0,0 +1,51 @@
+import type { Hono } from 'hono';
+import type { VelaApplication } from '@velajs/vela';
+import type { CloudflareEnv } from './types';
+/**
+ * Wraps VelaApplication with Cloudflare-specific handlers:
+ * - `fetch` — HTTP request handler (from Hono)
+ * - `scheduled` — Cron trigger handler (matches `@Scheduled()` decorators)
+ * - `queue` — Queue consumer handler (matches `@QueueConsumer()` decorators)
+ *
+ * @example
+ * ```ts
+ * const app = await CloudflareFactory.create(AppModule);
+ * export default {
+ *   fetch: app.fetch,
+ *   scheduled: app.scheduled.bind(app),
+ *   queue: app.queue.bind(app),
+ * };
+ * ```
+ */
+export declare class CloudflareApplication {
+    private app;
+    private scheduledHandlers;
+    private queueConsumers;
+    constructor(app: VelaApplication);
+    get fetch(): Hono['fetch'];
+    getHonoApp(): Hono;
+    /** @internal — scans instances for @Scheduled and @QueueConsumer metadata */
+    scanInstances(instances: unknown[]): void;
+    /**
+     * Handle Cloudflare scheduled (cron) events.
+     * Matches the event's cron expression to `@Scheduled()` handlers.
+     */
+    scheduled(event: {
+        cron: string;
+        scheduledTime?: number;
+    }, env: CloudflareEnv, ctx: {
+        waitUntil: (promise: Promise<unknown>) => void;
+    }): Promise<void>;
+    /**
+     * Handle Cloudflare Queue consumer events.
+     * Matches the batch queue name to `@QueueConsumer()` handlers.
+     */
+    queue(batch: {
+        queue: string;
+        messages: unknown[];
+    }, 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

@@ -0,0 +1,77 @@
+import { getScheduledMetadata } from "./decorators/scheduled.js";
+import { getQueueConsumerMetadata } from "./decorators/queue-consumer.js";
+/**
+ * Wraps VelaApplication with Cloudflare-specific handlers:
+ * - `fetch` — HTTP request handler (from Hono)
+ * - `scheduled` — Cron trigger handler (matches `@Scheduled()` decorators)
+ * - `queue` — Queue consumer handler (matches `@QueueConsumer()` decorators)
+ *
+ * @example
+ * ```ts
+ * const app = await CloudflareFactory.create(AppModule);
+ * export default {
+ *   fetch: app.fetch,
+ *   scheduled: app.scheduled.bind(app),
+ *   queue: app.queue.bind(app),
+ * };
+ * ```
+ */ export class CloudflareApplication {
+    app;
+    scheduledHandlers = [];
+    queueConsumers = [];
+    constructor(app){
+        this.app = app;
+    }
+    get fetch() {
+        return this.app.fetch;
+    }
+    getHonoApp() {
+        return this.app.getHonoApp();
+    }
+    /** @internal — scans instances for @Scheduled 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){
+                this.scheduledHandlers.push({
+                    instance,
+                    methodName: meta.methodName,
+                    cron: meta.cron
+                });
+            }
+            const queueMeta = getQueueConsumerMetadata(instance);
+            for (const meta of queueMeta){
+                this.queueConsumers.push({
+                    instance,
+                    methodName: meta.methodName,
+                    queueName: meta.queueName
+                });
+            }
+        }
+    }
+    /**
+   * Handle Cloudflare scheduled (cron) events.
+   * Matches the event's cron expression to `@Scheduled()` 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);
+    }
+    /**
+   * 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);
+    }
+    /** Gracefully shut down the application. */ async close(signal) {
+        return this.app.close(signal);
+    }
+}

package/dist/cloudflare-factory.d.ts

@@ -0,0 +1,18 @@
+import type { Type } from '@velajs/vela';
+import { CloudflareApplication } from './cloudflare-application';
+/**
+ * Factory for creating Cloudflare Worker applications.
+ * Replaces `VelaFactory.create()` for Cloudflare apps.
+ *
+ * Sets up a one-time Hono middleware that captures `c.env` on the
+ * first request and initializes all configured binding refs.
+ *
+ * @example
+ * ```ts
+ * const app = await CloudflareFactory.create(AppModule);
+ * export default app; // has .fetch, .scheduled, .queue
+ * ```
+ */
+export declare const CloudflareFactory: {
+    create(rootModule: Type): Promise<CloudflareApplication>;
+};

package/dist/cloudflare-factory.js

@@ -0,0 +1,42 @@
+import { VelaFactory } from "@velajs/vela";
+import { CloudflareApplication } from "./cloudflare-application.js";
+import { bindingsRegistry } from "./tokens.js";
+/**
+ * Factory for creating Cloudflare Worker applications.
+ * Replaces `VelaFactory.create()` for Cloudflare apps.
+ *
+ * Sets up a one-time Hono middleware that captures `c.env` on the
+ * first request and initializes all configured binding refs.
+ *
+ * @example
+ * ```ts
+ * const app = await CloudflareFactory.create(AppModule);
+ * export default app; // has .fetch, .scheduled, .queue
+ * ```
+ */ export const CloudflareFactory = {
+    async create (rootModule) {
+        const velaApp = await VelaFactory.create(rootModule);
+        // One-time middleware: captures c.env on first request
+        // and initializes all BindingRef instances from bindingsRegistry.
+        // Registered via useGlobalMiddleware so it persists across rebuilds.
+        let initialized = false;
+        velaApp.useGlobalMiddleware({
+            use: async (c, next)=>{
+                if (!initialized) {
+                    initialized = true;
+                    const ctx = c;
+                    const env = ctx.env ?? {};
+                    for (const ref of bindingsRegistry){
+                        ref._initialize(env[ref.bindingName]);
+                    }
+                }
+                await next();
+            }
+        });
+        // Rebuild so the init middleware is placed before route handlers
+        await velaApp.rebuild();
+        const cfApp = new CloudflareApplication(velaApp);
+        cfApp.scanInstances(velaApp.getInstances());
+        return cfApp;
+    }
+};

package/dist/decorators/env.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Parameter decorator to inject Cloudflare environment bindings.
+ *
+ * Without arguments, returns the entire `env` object.
+ * With a binding name, returns that specific binding.
+ *
+ * @example
+ * ```ts
+ * @Get()
+ * handle(@Env() env: CloudflareEnv) { ... }
+ *
+ * @Get()
+ * handle(@Env('MY_KV') kv: KVNamespace) { ... }
+ * ```
+ */
+export declare const Env: (data?: string | undefined, ...pipes: import("@velajs/vela").PipeType[]) => ParameterDecorator;

package/dist/decorators/env.js

@@ -0,0 +1,22 @@
+import { createParamDecorator } from "@velajs/vela";
+/**
+ * Parameter decorator to inject Cloudflare environment bindings.
+ *
+ * Without arguments, returns the entire `env` object.
+ * With a binding name, returns that specific binding.
+ *
+ * @example
+ * ```ts
+ * @Get()
+ * handle(@Env() env: CloudflareEnv) { ... }
+ *
+ * @Get()
+ * handle(@Env('MY_KV') kv: KVNamespace) { ... }
+ * ```
+ */ export const Env = createParamDecorator((bindingName, ctx)=>{
+    // Hono Context has .env on Cloudflare Workers
+    const c = ctx.getContext();
+    const env = c.env;
+    if (!env) return undefined;
+    return bindingName ? env[bindingName] : env;
+});

package/dist/decorators/queue-consumer.d.ts

@@ -0,0 +1,23 @@
+export interface QueueConsumerMetadata {
+    queueName: string;
+    methodName: string;
+}
+/**
+ * Marks a method as a queue consumer handler.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class WorkerService {
+ *   @QueueConsumer('email-queue')
+ *   async processEmails(batch: MessageBatch) {
+ *     for (const msg of batch.messages) {
+ *       console.log('Processing:', msg.body);
+ *       msg.ack();
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare function QueueConsumer(queueName: string): MethodDecorator;
+export declare function getQueueConsumerMetadata(target: object): QueueConsumerMetadata[];

package/dist/decorators/queue-consumer.js

@@ -0,0 +1,32 @@
+import { defineMetadata, getMetadata } from "@velajs/vela";
+const QUEUE_CONSUMER_METADATA_KEY = 'cloudflare:queue-consumer';
+/**
+ * Marks a method as a queue consumer handler.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class WorkerService {
+ *   @QueueConsumer('email-queue')
+ *   async processEmails(batch: MessageBatch) {
+ *     for (const msg of batch.messages) {
+ *       console.log('Processing:', msg.body);
+ *       msg.ack();
+ *     }
+ *   }
+ * }
+ * ```
+ */ export function QueueConsumer(queueName) {
+    return (target, propertyKey, _descriptor)=>{
+        const existing = getMetadata(QUEUE_CONSUMER_METADATA_KEY, target.constructor) ?? [];
+        existing.push({
+            queueName,
+            methodName: String(propertyKey)
+        });
+        defineMetadata(QUEUE_CONSUMER_METADATA_KEY, existing, target.constructor);
+    };
+}
+export function getQueueConsumerMetadata(target) {
+    const ctor = target.constructor ?? target;
+    return getMetadata(QUEUE_CONSUMER_METADATA_KEY, ctor) ?? [];
+}