@velajs/cloudflare 1.8.0 → 1.9.0

package/dist/index.d.ts

@@ -23,6 +23,10 @@ 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 { FlagshipFlagDriver, flagshipFlagDriver } from './services/flagship-flag.driver';
+export type { FlagshipBinding, FlagshipFlagDriverOptions } from './services/flagship-flag.driver';
+export { KvFlagDriver, kvFlagDriver } from './services/kv-flag.driver';
+export type { KvFlagDriverOptions } from './services/kv-flag.driver';
 export { Env } from './decorators/env';
 export { Scheduled } from './decorators/scheduled';
 export { QueueConsumer } from './decorators/queue-consumer';

package/dist/index.js

@@ -24,6 +24,9 @@ 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";
+// Feature-flag drivers (implement @velajs/feature-flags' FeatureFlagDriver contract)
+export { FlagshipFlagDriver, flagshipFlagDriver } from "./services/flagship-flag.driver.js";
+export { KvFlagDriver, kvFlagDriver } from "./services/kv-flag.driver.js";
 // Decorators
 export { Env } from "./decorators/env.js";
 export { Scheduled } from "./decorators/scheduled.js";

package/dist/services/flagship-flag.driver.d.ts

@@ -0,0 +1,57 @@
+import type { FeatureFlagDriver, FlagContext } from '@velajs/feature-flags';
+/**
+ * The subset of a Cloudflare **Flagship** binding this driver evaluates against
+ * — the four typed value methods. The binding itself returns the supplied
+ * `defaultValue` on evaluation errors; transport-level failures reject and are
+ * left to propagate (never-throw is the service layer's job, not the driver's).
+ *
+ * @see https://developers.cloudflare.com/flagship/binding/
+ */
+export interface FlagshipBinding {
+    getBooleanValue(key: string, defaultValue: boolean, context?: FlagContext): Promise<boolean>;
+    getStringValue(key: string, defaultValue: string, context?: FlagContext): Promise<string>;
+    getNumberValue(key: string, defaultValue: number, context?: FlagContext): Promise<number>;
+    getObjectValue<T extends object>(key: string, defaultValue: T, context?: FlagContext): Promise<T>;
+}
+export interface FlagshipFlagDriverOptions {
+    /** Driver name used for `use(name)` / default-driver selection. Default `"flagship"`. */
+    name?: string;
+}
+/**
+ * {@link FeatureFlagDriver} backed by a Cloudflare Flagship binding.
+ *
+ * A thin, honest wrapper: each contract method maps 1:1 onto the binding's
+ * corresponding value method, forwarding the caller's `fallback` (the binding's
+ * `defaultValue`) and evaluation context. The binding resolves the fallback on
+ * evaluation errors; anything the binding *rejects* with (e.g. a `remote: true`
+ * dev-proxy tunnel dropping) propagates — `@velajs/feature-flags`'s service owns
+ * the never-throw guarantee.
+ *
+ * The binding only exists per request in a Worker, so pass a lazy accessor when
+ * wiring from a bootstrap factory (mirroring how {@link EnvService} reads are
+ * deferred); a resolved binding may be passed directly in tests.
+ *
+ * ```ts
+ * FeatureFlagsModule.forRootAsync({
+ *   inject: [EnvService],
+ *   useFactory: (env: EnvService) => ({
+ *     drivers: [flagshipFlagDriver(() => env.get<FlagshipBinding>('FLAGS')!)],
+ *   }),
+ * });
+ * ```
+ *
+ * Evaluation ergonomics (the 1:1 binding-method mapping) are ported from the
+ * Stratal feature-flags service (MIT, © Temitayo Fadojutimi), reshaped as a
+ * bare driver.
+ */
+export declare class FlagshipFlagDriver implements FeatureFlagDriver {
+    readonly name: string;
+    private readonly resolve;
+    constructor(binding: FlagshipBinding | (() => FlagshipBinding), options?: FlagshipFlagDriverOptions);
+    getBoolean(key: string, fallback: boolean, ctx?: FlagContext): Promise<boolean>;
+    getString(key: string, fallback: string, ctx?: FlagContext): Promise<string>;
+    getNumber(key: string, fallback: number, ctx?: FlagContext): Promise<number>;
+    getObject<T extends object>(key: string, fallback: T, ctx?: FlagContext): Promise<T>;
+}
+/** Convenience factory for {@link FlagshipFlagDriver}. */
+export declare function flagshipFlagDriver(binding: FlagshipBinding | (() => FlagshipBinding), options?: FlagshipFlagDriverOptions): FlagshipFlagDriver;

package/dist/services/flagship-flag.driver.js

@@ -0,0 +1,49 @@
+/**
+ * {@link FeatureFlagDriver} backed by a Cloudflare Flagship binding.
+ *
+ * A thin, honest wrapper: each contract method maps 1:1 onto the binding's
+ * corresponding value method, forwarding the caller's `fallback` (the binding's
+ * `defaultValue`) and evaluation context. The binding resolves the fallback on
+ * evaluation errors; anything the binding *rejects* with (e.g. a `remote: true`
+ * dev-proxy tunnel dropping) propagates — `@velajs/feature-flags`'s service owns
+ * the never-throw guarantee.
+ *
+ * The binding only exists per request in a Worker, so pass a lazy accessor when
+ * wiring from a bootstrap factory (mirroring how {@link EnvService} reads are
+ * deferred); a resolved binding may be passed directly in tests.
+ *
+ * ```ts
+ * FeatureFlagsModule.forRootAsync({
+ *   inject: [EnvService],
+ *   useFactory: (env: EnvService) => ({
+ *     drivers: [flagshipFlagDriver(() => env.get<FlagshipBinding>('FLAGS')!)],
+ *   }),
+ * });
+ * ```
+ *
+ * Evaluation ergonomics (the 1:1 binding-method mapping) are ported from the
+ * Stratal feature-flags service (MIT, © Temitayo Fadojutimi), reshaped as a
+ * bare driver.
+ */ export class FlagshipFlagDriver {
+    name;
+    resolve;
+    constructor(binding, options = {}){
+        this.resolve = typeof binding === 'function' ? binding : ()=>binding;
+        this.name = options.name ?? 'flagship';
+    }
+    getBoolean(key, fallback, ctx) {
+        return this.resolve().getBooleanValue(key, fallback, ctx);
+    }
+    getString(key, fallback, ctx) {
+        return this.resolve().getStringValue(key, fallback, ctx);
+    }
+    getNumber(key, fallback, ctx) {
+        return this.resolve().getNumberValue(key, fallback, ctx);
+    }
+    getObject(key, fallback, ctx) {
+        return this.resolve().getObjectValue(key, fallback, ctx);
+    }
+}
+/** Convenience factory for {@link FlagshipFlagDriver}. */ export function flagshipFlagDriver(binding, options) {
+    return new FlagshipFlagDriver(binding, options);
+}

package/dist/services/kv-flag.driver.d.ts

@@ -0,0 +1,48 @@
+import type { FeatureFlagDriver, FlagContext } from '@velajs/feature-flags';
+import { KVService } from './kv.service';
+export interface KvFlagDriverOptions {
+    /** Driver name used for `use(name)` / default-driver selection. Default `"kv"`. */
+    name?: string;
+    /** Prefix prepended to every flag key before the KV read. Default `""` (none). */
+    prefix?: string;
+}
+/**
+ * Cloudflare KV-backed {@link FeatureFlagDriver}. Flags are stored as JSON
+ * values under an optional key prefix and read with `get(key, 'json')`. Reads
+ * are type-checked against the requested type: a missing key or a value of the
+ * wrong JSON type returns the caller's `fallback`. KV has no targeting, so the
+ * evaluation context is ignored.
+ *
+ * The driver stays honest — it does **not** swallow errors. A KV failure (or a
+ * `SyntaxError` from a malformed stored value) propagates; the never-throw
+ * guarantee lives in `@velajs/feature-flags`'s service layer.
+ *
+ * Placed like {@link KVCacheStore}: construct it in a wiring factory over a
+ * resolved {@link KVService}.
+ *
+ * ```ts
+ * FeatureFlagsModule.forRootAsync({
+ *   inject: [KVService],
+ *   useFactory: (kv: KVService) => ({ drivers: [new KvFlagDriver(kv, { prefix: 'flag:' })] }),
+ * });
+ * ```
+ */
+export declare class KvFlagDriver implements FeatureFlagDriver {
+    private readonly kv;
+    readonly name: string;
+    private readonly prefix;
+    constructor(kv: KVService, options?: KvFlagDriverOptions);
+    private get ns();
+    getBoolean(key: string, fallback: boolean, _ctx?: FlagContext): Promise<boolean>;
+    getString(key: string, fallback: string, _ctx?: FlagContext): Promise<string>;
+    getNumber(key: string, fallback: number, _ctx?: FlagContext): Promise<number>;
+    getObject<T extends object>(key: string, fallback: T, _ctx?: FlagContext): Promise<T>;
+    /**
+     * Reads and JSON-parses the (prefixed) key, returning the parsed value only
+     * when `matches` accepts its type; otherwise the caller's fallback. A missing
+     * key reads as `null` → fallback. Read/parse errors are left to propagate.
+     */
+    private read;
+}
+/** Convenience factory for {@link KvFlagDriver}. */
+export declare function kvFlagDriver(kv: KVService, options?: KvFlagDriverOptions): KvFlagDriver;

package/dist/services/kv-flag.driver.js

@@ -0,0 +1,62 @@
+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 KvFlagDriver {
+    kv;
+    name;
+    prefix;
+    constructor(kv, options = {}){
+        this.kv = kv;
+        this.name = options.name ?? 'kv';
+        this.prefix = options.prefix ?? '';
+    }
+    get ns() {
+        return this.kv.namespace;
+    }
+    getBoolean(key, fallback, _ctx) {
+        return this.read(key, fallback, (v)=>typeof v === 'boolean');
+    }
+    getString(key, fallback, _ctx) {
+        return this.read(key, fallback, (v)=>typeof v === 'string');
+    }
+    getNumber(key, fallback, _ctx) {
+        return this.read(key, fallback, (v)=>typeof v === 'number');
+    }
+    getObject(key, fallback, _ctx) {
+        return this.read(key, fallback, (v)=>typeof v === 'object' && v !== null);
+    }
+    /**
+   * Reads and JSON-parses the (prefixed) key, returning the parsed value only
+   * when `matches` accepts its type; otherwise the caller's fallback. A missing
+   * key reads as `null` → fallback. Read/parse errors are left to propagate.
+   */ async read(key, fallback, matches) {
+        const value = await this.ns.get(this.prefix + key, 'json');
+        if (value === null || value === undefined) return fallback;
+        return matches(value) ? value : fallback;
+    }
+}
+KvFlagDriver = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(KVService)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof KVService === "undefined" ? Object : KVService,
+        typeof KvFlagDriverOptions === "undefined" ? Object : KvFlagDriverOptions
+    ])
+], KvFlagDriver);
+/** Convenience factory for {@link KvFlagDriver}. */ export function kvFlagDriver(kv, options) {
+    return new KvFlagDriver(kv, options);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/cloudflare",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Cloudflare Workers integration for Vela framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,13 +45,20 @@
   },
   "peerDependencies": {
     "@cloudflare/workers-types": ">=4",
+    "@velajs/feature-flags": "^0.1.0",
     "@velajs/vela": ">=1.11.0",
     "hono": ">=4"
   },
+  "peerDependenciesMeta": {
+    "@velajs/feature-flags": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260624.1",
     "@swc/cli": "^0.8.1",
     "@swc/core": "^1.15.43",
+    "@velajs/feature-flags": "^0.1.0",
     "@velajs/vela": "^1.12.0",
     "hono": "^4.12.27",
     "typescript": "^6.0.3",