@flareone/kv 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flareone Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @flareone/kv
+
+Workers KV integration for Flareone framework.
+
+## Installation
+
+```bash
+npm install @flareone/kv
+```
+
+## Features
+
+- **Type-safe Wrapper**: High-level API for `KVNamespace`
+- **Caching**: Built-in TTL and caching strategies
+- **Repository Pattern**: `KVRepository` base class for entity management
+- **Batch Operations**: Efficient `setMany`, `deleteMany`, `list`
+- **Metadata Support**: Simple API for storing/retrieving metadata
+
+## Usage
+
+```typescript
+import { Module, Injectable, Inject } from '@flareone/core';
+import { KVModule, KVService } from '@flareone/kv';
+
+@Injectable()
+class CacheService {
+  constructor(@Inject(KVService) private kv: KVService) {}
+
+  async saveUser(id: string, data: any) {
+    // Automatic JSON serialization + TTL
+    await this.kv.set(`user:${id}`, data, { expirationTtl: 3600 });
+  }
+}
+
+@Module({
+  imports: [
+    KVModule.forRoot({
+      binding: 'MY_KV', // Binding name in wrangler.toml
+      keyPrefix: 'app:'
+    })
+  ]
+})
+class AppModule {}
+```
+
+See [main repository](https://github.com/flareonejs/flareone) for full documentation.

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+import { Type, DynamicModule, InjectionToken } from '@flareone/core';
+
+/**
+ * @flareone/kv - Workers KV Integration
+ * High-level, type-safe wrapper for Cloudflare Workers KV
+ */
+
+interface KVGetOptions {
+    type?: 'text' | 'json' | 'arrayBuffer' | 'stream';
+    cacheTtl?: number;
+}
+interface KVPutOptions {
+    expiration?: number;
+    expirationTtl?: number;
+    metadata?: Record<string, unknown>;
+}
+interface KVListOptions {
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+}
+interface KVListResult<T = unknown> {
+    keys: Array<{
+        name: string;
+        expiration?: number;
+        metadata?: T;
+    }>;
+    list_complete: boolean;
+    cursor?: string;
+}
+interface KVValueWithMetadata<T, M = unknown> {
+    value: T | null;
+    metadata: M | null;
+}
+interface KVModuleOptions {
+    binding: string;
+    defaultTtl?: number;
+    keyPrefix?: string;
+    enableCache?: boolean;
+    cacheTtl?: number;
+}
+interface KVModuleAsyncOptions {
+    imports?: Array<Type | DynamicModule>;
+    useFactory: (...args: unknown[]) => KVModuleOptions | Promise<KVModuleOptions>;
+    inject?: InjectionToken[];
+}
+declare const KV_OPTIONS: InjectionToken<KVModuleOptions>;
+declare const KV_NAMESPACE: InjectionToken<KVNamespace<string>>;
+/**
+ * High-level KV service with type-safe operations
+ */
+declare class KVService {
+    private namespace;
+    private options;
+    /**
+     * Initialize with KV namespace and options
+     */
+    initialize(namespace: KVNamespace, options: KVModuleOptions): void;
+    /**
+     * Get the underlying KV namespace
+     */
+    getNamespace(): KVNamespace;
+    /**
+     * Build the full key with optional prefix
+     */
+    private buildKey;
+    /**
+     * Get a value by key
+     */
+    get<T = string>(key: string, options?: KVGetOptions): Promise<T | null>;
+    /**
+     * Get a value as text
+     */
+    getText(key: string, cacheTtl?: number): Promise<string | null>;
+    /**
+     * Get a value as JSON
+     */
+    getJson<T>(key: string, cacheTtl?: number): Promise<T | null>;
+    /**
+     * Get a value as ArrayBuffer
+     */
+    getArrayBuffer(key: string, cacheTtl?: number): Promise<ArrayBuffer | null>;
+    /**
+     * Get a value as ReadableStream
+     */
+    getStream(key: string, cacheTtl?: number): Promise<ReadableStream | null>;
+    /**
+     * Get a value with its metadata
+     */
+    getWithMetadata<T = unknown, M = unknown>(key: string, type?: 'text' | 'json' | 'arrayBuffer' | 'stream'): Promise<KVValueWithMetadata<T, M>>;
+    /**
+     * Set a value
+     */
+    set<T = unknown>(key: string, value: T, options?: KVPutOptions): Promise<void>;
+    /**
+     * Set multiple values at once
+     */
+    setMany<T = unknown>(entries: Array<{
+        key: string;
+        value: T;
+        options?: KVPutOptions;
+    }>): Promise<void>;
+    /**
+     * Set a value with automatic JSON serialization
+     */
+    setJson<T>(key: string, value: T, options?: KVPutOptions): Promise<void>;
+    /**
+     * Set a value as raw text
+     */
+    setText(key: string, value: string, options?: KVPutOptions): Promise<void>;
+    /**
+     * Set a value as ArrayBuffer
+     */
+    setArrayBuffer(key: string, value: ArrayBuffer, options?: KVPutOptions): Promise<void>;
+    /**
+     * Delete a key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Delete multiple keys
+     */
+    deleteMany(keys: string[]): Promise<void>;
+    /**
+     * Delete all keys with a prefix
+     */
+    deleteByPrefix(prefix: string): Promise<number>;
+    /**
+     * List keys
+     */
+    list<M = unknown>(options?: KVListOptions): Promise<KVListResult<M>>;
+    /**
+     * Get all keys (handles pagination automatically)
+     */
+    keys<M = unknown>(prefix?: string): Promise<Array<{
+        name: string;
+        metadata?: M;
+    }>>;
+    /**
+     * Check if a key exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Get or set a value (cache pattern)
+     */
+    getOrSet<T>(key: string, factory: () => T | Promise<T>, options?: KVPutOptions): Promise<T>;
+    /**
+     * Increment a numeric value
+     */
+    increment(key: string, delta?: number): Promise<number>;
+    /**
+     * Decrement a numeric value
+     */
+    decrement(key: string, delta?: number): Promise<number>;
+    /**
+     * Append to an array stored in KV
+     */
+    append<T>(key: string, item: T, options?: KVPutOptions): Promise<T[]>;
+    /**
+     * Update a value with a transformer function
+     */
+    update<T>(key: string, updater: (current: T | null) => T, options?: KVPutOptions): Promise<T>;
+}
+/**
+ * Base class for creating typed KV repositories
+ */
+declare abstract class KVRepository<T, M = unknown> {
+    protected readonly kv: KVService;
+    protected readonly prefix: string;
+    constructor(kv: KVService, prefix: string);
+    /**
+     * Build the full key for an entity
+     */
+    protected buildKey(id: string): string;
+    /**
+     * Find an entity by ID
+     */
+    findById(id: string): Promise<T | null>;
+    /**
+     * Find an entity by ID with metadata
+     */
+    findByIdWithMetadata(id: string): Promise<KVValueWithMetadata<T, M>>;
+    /**
+     * Save an entity
+     */
+    save(id: string, entity: T, options?: KVPutOptions): Promise<void>;
+    /**
+     * Delete an entity
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Check if an entity exists
+     */
+    exists(id: string): Promise<boolean>;
+    /**
+     * Get all entity IDs
+     */
+    getAllIds(): Promise<string[]>;
+    /**
+     * Get all entities
+     */
+    findAll(): Promise<T[]>;
+    /**
+     * Count entities
+     */
+    count(): Promise<number>;
+    /**
+     * Delete all entities
+     */
+    deleteAll(): Promise<number>;
+}
+/**
+ * Parameter decorator to inject KV namespace directly
+ */
+declare function InjectKV(binding: string): ParameterDecorator;
+/**
+ * KV Module for Flareone
+ */
+declare class KVModule {
+    /**
+     * Configure KV module with static options
+     */
+    static forRoot(options: KVModuleOptions): DynamicModule;
+    /**
+     * Configure KV module with async options
+     */
+    static forRootAsync(options: KVModuleAsyncOptions): DynamicModule;
+    /**
+     * Configure KV for a specific feature/namespace
+     */
+    static forFeature(options: KVModuleOptions): DynamicModule;
+}
+/**
+ * Create a KV service for a specific namespace
+ */
+declare function createKVService(namespace: KVNamespace, options?: Partial<KVModuleOptions>): KVService;
+/**
+ * Helper to get KV namespace from environment
+ */
+declare function getKVNamespace(env: Record<string, unknown>, binding: string): KVNamespace;
+
+export { InjectKV, type KVGetOptions, type KVListOptions, type KVListResult, KVModule, type KVModuleAsyncOptions, type KVModuleOptions, type KVPutOptions, KVRepository, KVService, type KVValueWithMetadata, KV_NAMESPACE, KV_OPTIONS, createKVService, getKVNamespace };

package/dist/index.js

@@ -0,0 +1,409 @@
+import { createToken, Injectable, Module } from '@flareone/core';
+
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (decorator(result)) || result;
+  return result;
+};
+var KV_OPTIONS = createToken("KV_OPTIONS");
+var KV_NAMESPACE = createToken("KV_NAMESPACE");
+var KVService = class {
+  namespace = null;
+  options = null;
+  /**
+   * Initialize with KV namespace and options
+   */
+  initialize(namespace, options) {
+    this.namespace = namespace;
+    this.options = options;
+  }
+  /**
+   * Get the underlying KV namespace
+   */
+  getNamespace() {
+    if (!this.namespace) {
+      throw new Error("KV namespace not initialized. Make sure KVModule is properly configured.");
+    }
+    return this.namespace;
+  }
+  /**
+   * Build the full key with optional prefix
+   */
+  buildKey(key) {
+    return this.options?.keyPrefix ? `${this.options.keyPrefix}${key}` : key;
+  }
+  /**
+   * Get a value by key
+   */
+  async get(key, options) {
+    const ns = this.getNamespace();
+    const fullKey = this.buildKey(key);
+    const type = options?.type ?? "json";
+    const cacheTtl = options?.cacheTtl ?? this.options?.cacheTtl;
+    const kvOptions = { type };
+    if (cacheTtl) {
+      kvOptions.cacheTtl = cacheTtl;
+    }
+    return ns.get(fullKey, kvOptions);
+  }
+  /**
+   * Get a value as text
+   */
+  async getText(key, cacheTtl) {
+    return this.get(key, { type: "text", cacheTtl });
+  }
+  /**
+   * Get a value as JSON
+   */
+  async getJson(key, cacheTtl) {
+    return this.get(key, { type: "json", cacheTtl });
+  }
+  /**
+   * Get a value as ArrayBuffer
+   */
+  async getArrayBuffer(key, cacheTtl) {
+    return this.get(key, { type: "arrayBuffer", cacheTtl });
+  }
+  /**
+   * Get a value as ReadableStream
+   */
+  async getStream(key, cacheTtl) {
+    return this.get(key, { type: "stream", cacheTtl });
+  }
+  /**
+   * Get a value with its metadata
+   */
+  async getWithMetadata(key, type = "json") {
+    const ns = this.getNamespace();
+    const fullKey = this.buildKey(key);
+    const result = await ns.getWithMetadata(fullKey, { type });
+    return {
+      value: result.value,
+      metadata: result.metadata
+    };
+  }
+  /**
+   * Set a value
+   */
+  async set(key, value, options) {
+    const ns = this.getNamespace();
+    const fullKey = this.buildKey(key);
+    const serialized = typeof value === "string" ? value : JSON.stringify(value);
+    const kvOptions = {};
+    if (options?.expiration) {
+      kvOptions.expiration = options.expiration;
+    }
+    if (options?.expirationTtl ?? this.options?.defaultTtl) {
+      kvOptions.expirationTtl = options?.expirationTtl ?? this.options?.defaultTtl;
+    }
+    if (options?.metadata) {
+      kvOptions.metadata = options.metadata;
+    }
+    await ns.put(fullKey, serialized, kvOptions);
+  }
+  /**
+   * Set multiple values at once
+   */
+  async setMany(entries) {
+    await Promise.all(
+      entries.map(({ key, value, options }) => this.set(key, value, options))
+    );
+  }
+  /**
+   * Set a value with automatic JSON serialization
+   */
+  async setJson(key, value, options) {
+    return this.set(key, value, options);
+  }
+  /**
+   * Set a value as raw text
+   */
+  async setText(key, value, options) {
+    const ns = this.getNamespace();
+    const fullKey = this.buildKey(key);
+    const kvOptions = {};
+    if (options?.expiration) kvOptions.expiration = options.expiration;
+    if (options?.expirationTtl ?? this.options?.defaultTtl) {
+      kvOptions.expirationTtl = options?.expirationTtl ?? this.options?.defaultTtl;
+    }
+    if (options?.metadata) kvOptions.metadata = options.metadata;
+    await ns.put(fullKey, value, kvOptions);
+  }
+  /**
+   * Set a value as ArrayBuffer
+   */
+  async setArrayBuffer(key, value, options) {
+    const ns = this.getNamespace();
+    const fullKey = this.buildKey(key);
+    const kvOptions = {};
+    if (options?.expiration) kvOptions.expiration = options.expiration;
+    if (options?.expirationTtl ?? this.options?.defaultTtl) {
+      kvOptions.expirationTtl = options?.expirationTtl ?? this.options?.defaultTtl;
+    }
+    if (options?.metadata) kvOptions.metadata = options.metadata;
+    await ns.put(fullKey, value, kvOptions);
+  }
+  /**
+   * Delete a key
+   */
+  async delete(key) {
+    const ns = this.getNamespace();
+    const fullKey = this.buildKey(key);
+    await ns.delete(fullKey);
+  }
+  /**
+   * Delete multiple keys
+   */
+  async deleteMany(keys) {
+    await Promise.all(keys.map((key) => this.delete(key)));
+  }
+  /**
+   * Delete all keys with a prefix
+   */
+  async deleteByPrefix(prefix) {
+    const keys = await this.keys(prefix);
+    await this.deleteMany(keys.map((k) => k.name));
+    return keys.length;
+  }
+  /**
+   * List keys
+   */
+  async list(options) {
+    const ns = this.getNamespace();
+    const kvOptions = {};
+    if (options?.prefix) {
+      kvOptions.prefix = this.buildKey(options.prefix);
+    }
+    if (options?.limit) {
+      kvOptions.limit = options.limit;
+    }
+    if (options?.cursor) {
+      kvOptions.cursor = options.cursor;
+    }
+    return ns.list(kvOptions);
+  }
+  /**
+   * Get all keys (handles pagination automatically)
+   */
+  async keys(prefix) {
+    const allKeys = [];
+    let cursor;
+    let complete = false;
+    while (!complete) {
+      const result = await this.list({
+        prefix,
+        cursor,
+        limit: 1e3
+      });
+      allKeys.push(...result.keys);
+      complete = result.list_complete;
+      cursor = result.cursor;
+    }
+    return allKeys;
+  }
+  /**
+   * Check if a key exists
+   */
+  async exists(key) {
+    const value = await this.get(key, { type: "text" });
+    return value !== null;
+  }
+  /**
+   * Get or set a value (cache pattern)
+   */
+  async getOrSet(key, factory, options) {
+    const existing = await this.get(key);
+    if (existing !== null) {
+      return existing;
+    }
+    const value = await factory();
+    await this.set(key, value, options);
+    return value;
+  }
+  /**
+   * Increment a numeric value
+   */
+  async increment(key, delta = 1) {
+    const current = await this.get(key);
+    const newValue = (current ?? 0) + delta;
+    await this.set(key, newValue);
+    return newValue;
+  }
+  /**
+   * Decrement a numeric value
+   */
+  async decrement(key, delta = 1) {
+    return this.increment(key, -delta);
+  }
+  /**
+   * Append to an array stored in KV
+   */
+  async append(key, item, options) {
+    const existing = await this.get(key) ?? [];
+    existing.push(item);
+    await this.set(key, existing, options);
+    return existing;
+  }
+  /**
+   * Update a value with a transformer function
+   */
+  async update(key, updater, options) {
+    const current = await this.get(key);
+    const updated = updater(current);
+    await this.set(key, updated, options);
+    return updated;
+  }
+};
+KVService = __decorateClass([
+  Injectable()
+], KVService);
+var KVRepository = class {
+  constructor(kv, prefix) {
+    this.kv = kv;
+    this.prefix = prefix;
+  }
+  /**
+   * Build the full key for an entity
+   */
+  buildKey(id) {
+    return `${this.prefix}:${id}`;
+  }
+  /**
+   * Find an entity by ID
+   */
+  async findById(id) {
+    return this.kv.get(this.buildKey(id));
+  }
+  /**
+   * Find an entity by ID with metadata
+   */
+  async findByIdWithMetadata(id) {
+    return this.kv.getWithMetadata(this.buildKey(id));
+  }
+  /**
+   * Save an entity
+   */
+  async save(id, entity, options) {
+    await this.kv.set(this.buildKey(id), entity, options);
+  }
+  /**
+   * Delete an entity
+   */
+  async delete(id) {
+    await this.kv.delete(this.buildKey(id));
+  }
+  /**
+   * Check if an entity exists
+   */
+  async exists(id) {
+    return this.kv.exists(this.buildKey(id));
+  }
+  /**
+   * Get all entity IDs
+   */
+  async getAllIds() {
+    const keys = await this.kv.keys(`${this.prefix}:`);
+    return keys.map((k) => k.name.replace(`${this.prefix}:`, ""));
+  }
+  /**
+   * Get all entities
+   */
+  async findAll() {
+    const ids = await this.getAllIds();
+    const entities = await Promise.all(ids.map((id) => this.findById(id)));
+    return entities.filter((e) => e !== null);
+  }
+  /**
+   * Count entities
+   */
+  async count() {
+    const keys = await this.kv.keys(`${this.prefix}:`);
+    return keys.length;
+  }
+  /**
+   * Delete all entities
+   */
+  async deleteAll() {
+    return this.kv.deleteByPrefix(`${this.prefix}:`);
+  }
+};
+function InjectKV(binding) {
+  return (target, propertyKey, parameterIndex) => {
+    const metaKey = `__kv_bindings_${String(propertyKey)}`;
+    const existingParams = target[metaKey] ?? [];
+    existingParams.push({ index: parameterIndex, binding });
+    target[metaKey] = existingParams;
+  };
+}
+var KVModule = class {
+  /**
+   * Configure KV module with static options
+   */
+  static forRoot(options) {
+    return {
+      module: KVModule,
+      providers: [
+        { provide: KV_OPTIONS, useValue: options },
+        KVService
+      ],
+      exports: [KVService, KV_OPTIONS]
+    };
+  }
+  /**
+   * Configure KV module with async options
+   */
+  static forRootAsync(options) {
+    return {
+      module: KVModule,
+      imports: options.imports ?? [],
+      providers: [
+        {
+          provide: KV_OPTIONS,
+          useFactory: options.useFactory,
+          inject: options.inject
+        },
+        KVService
+      ],
+      exports: [KVService, KV_OPTIONS]
+    };
+  }
+  /**
+   * Configure KV for a specific feature/namespace
+   */
+  static forFeature(options) {
+    const featureToken = createToken(`KV_${options.binding}`);
+    return {
+      module: KVModule,
+      providers: [
+        { provide: featureToken, useClass: KVService },
+        { provide: `KV_OPTIONS_${options.binding}`, useValue: options }
+      ],
+      exports: [featureToken]
+    };
+  }
+};
+KVModule = __decorateClass([
+  Module({})
+], KVModule);
+function createKVService(namespace, options = {}) {
+  const service = new KVService();
+  service.initialize(namespace, {
+    binding: "custom",
+    ...options
+  });
+  return service;
+}
+function getKVNamespace(env, binding) {
+  const namespace = env[binding];
+  if (!namespace) {
+    throw new Error(`KV namespace '${binding}' not found in environment`);
+  }
+  return namespace;
+}
+
+export { InjectKV, KVModule, KVRepository, KVService, KV_NAMESPACE, KV_OPTIONS, createKVService, getKVNamespace };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;AA2DO,IAAM,UAAA,GAAa,YAA6B,YAAY;AAC5D,IAAM,YAAA,GAAe,YAAyB,cAAc;AAM5D,IAAM,YAAN,MAAgB;AAAA,EACX,SAAA,GAAgC,IAAA;AAAA,EAChC,OAAA,GAAkC,IAAA;AAAA;AAAA;AAAA;AAAA,EAK1C,UAAA,CAAW,WAAwB,OAAA,EAAgC;AAC/D,IAAA,IAAA,CAAK,SAAA,GAAY,SAAA;AACjB,IAAA,IAAA,CAAK,OAAA,GAAU,OAAA;AAAA,EACnB;AAAA;AAAA;AAAA;AAAA,EAKA,YAAA,GAA4B;AACxB,IAAA,IAAI,CAAC,KAAK,SAAA,EAAW;AACjB,MAAA,MAAM,IAAI,MAAM,0EAA0E,CAAA;AAAA,IAC9F;AACA,IAAA,OAAO,IAAA,CAAK,SAAA;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA,EAKQ,SAAS,GAAA,EAAqB;AAClC,IAAA,OAAO,IAAA,CAAK,SAAS,SAAA,GAAY,CAAA,EAAG,KAAK,OAAA,CAAQ,SAAS,CAAA,EAAG,GAAG,CAAA,CAAA,GAAK,GAAA;AAAA,EACzE;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,GAAA,CAAgB,GAAA,EAAa,OAAA,EAA2C;AAC1E,IAAA,MAAM,EAAA,GAAK,KAAK,YAAA,EAAa;AAC7B,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,QAAA,CAAS,GAAG,CAAA;AACjC,IAAA,MAAM,IAAA,GAAO,SAAS,IAAA,IAAQ,MAAA;AAC9B,IAAA,MAAM,QAAA,GAAW,OAAA,EAAS,QAAA,IAAY,IAAA,CAAK,OAAA,EAAS,QAAA;AAEpD,IAAA,MAAM,SAAA,GAAwC,EAAE,IAAA,EAAK;AACrD,IAAA,IAAI,QAAA,EAAU;AACV,MAAA,SAAA,CAAU,QAAA,GAAW,QAAA;AAAA,IACzB;AAEA,IAAA,OAAO,EAAA,CAAG,GAAA,CAAI,OAAA,EAAS,SAAS,CAAA;AAAA,EACpC;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,OAAA,CAAQ,GAAA,EAAa,QAAA,EAA2C;AAClE,IAAA,OAAO,KAAK,GAAA,CAAY,GAAA,EAAK,EAAE,IAAA,EAAM,MAAA,EAAQ,UAAU,CAAA;AAAA,EAC3D;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,OAAA,CAAW,GAAA,EAAa,QAAA,EAAsC;AAChE,IAAA,OAAO,KAAK,GAAA,CAAO,GAAA,EAAK,EAAE,IAAA,EAAM,MAAA,EAAQ,UAAU,CAAA;AAAA,EACtD;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,cAAA,CAAe,GAAA,EAAa,QAAA,EAAgD;AAC9E,IAAA,OAAO,KAAK,GAAA,CAAiB,GAAA,EAAK,EAAE,IAAA,EAAM,aAAA,EAAe,UAAU,CAAA;AAAA,EACvE;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,SAAA,CAAU,GAAA,EAAa,QAAA,EAAmD;AAC5E,IAAA,OAAO,KAAK,GAAA,CAAoB,GAAA,EAAK,EAAE,IAAA,EAAM,QAAA,EAAU,UAAU,CAAA;AAAA,EACrE;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,eAAA,CACF,GAAA,EACA,IAAA,GAAmD,MAAA,EACjB;AAClC,IAAA,MAAM,EAAA,GAAK,KAAK,YAAA,EAAa;AAC7B,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,QAAA,CAAS,GAAG,CAAA;AACjC,IAAA,MAAM,SAAS,MAAO,EAAA,CAAG,gBAA+G,OAAA,EAAS,EAAE,MAAM,CAAA;AACzJ,IAAA,OAAO;AAAA,MACH,OAAO,MAAA,CAAO,KAAA;AAAA,MACd,UAAU,MAAA,CAAO;AAAA,KACrB;AAAA,EACJ;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,GAAA,CACF,GAAA,EACA,KAAA,EACA,OAAA,EACa;AACb,IAAA,MAAM,EAAA,GAAK,KAAK,YAAA,EAAa;AAC7B,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,QAAA,CAAS,GAAG,CAAA;AAEjC,IAAA,MAAM,aAAa,OAAO,KAAA,KAAU,WAAW,KAAA,GAAQ,IAAA,CAAK,UAAU,KAAK,CAAA;AAE3E,IAAA,MAAM,YAAmC,EAAC;AAC1C,IAAA,IAAI,SAAS,UAAA,EAAY;AACrB,MAAA,SAAA,CAAU,aAAa,OAAA,CAAQ,UAAA;AAAA,IACnC;AACA,IAAA,IAAI,OAAA,EAAS,aAAA,IAAiB,IAAA,CAAK,OAAA,EAAS,UAAA,EAAY;AACpD,MAAA,SAAA,CAAU,aAAA,GAAgB,OAAA,EAAS,aAAA,IAAiB,IAAA,CAAK,OAAA,EAAS,UAAA;AAAA,IACtE;AACA,IAAA,IAAI,SAAS,QAAA,EAAU;AACnB,MAAA,SAAA,CAAU,WAAW,OAAA,CAAQ,QAAA;AAAA,IACjC;AAEA,IAAA,MAAM,EAAA,CAAG,GAAA,CAAI,OAAA,EAAS,UAAA,EAAY,SAAS,CAAA;AAAA,EAC/C;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,QACF,OAAA,EACa;AACb,IAAA,MAAM,OAAA,CAAQ,GAAA;AAAA,MACV,OAAA,CAAQ,GAAA,CAAI,CAAC,EAAE,GAAA,EAAK,KAAA,EAAO,OAAA,EAAQ,KAAM,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,KAAA,EAAO,OAAO,CAAC;AAAA,KAC1E;AAAA,EACJ;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,OAAA,CAAW,GAAA,EAAa,KAAA,EAAU,OAAA,EAAuC;AAC3E,IAAA,OAAO,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,KAAA,EAAO,OAAO,CAAA;AAAA,EACvC;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,OAAA,CAAQ,GAAA,EAAa,KAAA,EAAe,OAAA,EAAuC;AAC7E,IAAA,MAAM,EAAA,GAAK,KAAK,YAAA,EAAa;AAC7B,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,QAAA,CAAS,GAAG,CAAA;AAEjC,IAAA,MAAM,YAAmC,EAAC;AAC1C,IAAA,IAAI,OAAA,EAAS,UAAA,EAAY,SAAA,CAAU,UAAA,GAAa,OAAA,CAAQ,UAAA;AACxD,IAAA,IAAI,OAAA,EAAS,aAAA,IAAiB,IAAA,CAAK,OAAA,EAAS,UAAA,EAAY;AACpD,MAAA,SAAA,CAAU,aAAA,GAAgB,OAAA,EAAS,aAAA,IAAiB,IAAA,CAAK,OAAA,EAAS,UAAA;AAAA,IACtE;AACA,IAAA,IAAI,OAAA,EAAS,QAAA,EAAU,SAAA,CAAU,QAAA,GAAW,OAAA,CAAQ,QAAA;AAEpD,IAAA,MAAM,EAAA,CAAG,GAAA,CAAI,OAAA,EAAS,KAAA,EAAO,SAAS,CAAA;AAAA,EAC1C;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,cAAA,CACF,GAAA,EACA,KAAA,EACA,OAAA,EACa;AACb,IAAA,MAAM,EAAA,GAAK,KAAK,YAAA,EAAa;AAC7B,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,QAAA,CAAS,GAAG,CAAA;AAEjC,IAAA,MAAM,YAAmC,EAAC;AAC1C,IAAA,IAAI,OAAA,EAAS,UAAA,EAAY,SAAA,CAAU,UAAA,GAAa,OAAA,CAAQ,UAAA;AACxD,IAAA,IAAI,OAAA,EAAS,aAAA,IAAiB,IAAA,CAAK,OAAA,EAAS,UAAA,EAAY;AACpD,MAAA,SAAA,CAAU,aAAA,GAAgB,OAAA,EAAS,aAAA,IAAiB,IAAA,CAAK,OAAA,EAAS,UAAA;AAAA,IACtE;AACA,IAAA,IAAI,OAAA,EAAS,QAAA,EAAU,SAAA,CAAU,QAAA,GAAW,OAAA,CAAQ,QAAA;AAEpD,IAAA,MAAM,EAAA,CAAG,GAAA,CAAI,OAAA,EAAS,KAAA,EAAO,SAAS,CAAA;AAAA,EAC1C;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,OAAO,GAAA,EAA4B;AACrC,IAAA,MAAM,EAAA,GAAK,KAAK,YAAA,EAAa;AAC7B,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,QAAA,CAAS,GAAG,CAAA;AACjC,IAAA,MAAM,EAAA,CAAG,OAAO,OAAO,CAAA;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,WAAW,IAAA,EAA+B;AAC5C,IAAA,MAAM,OAAA,CAAQ,GAAA,CAAI,IAAA,CAAK,GAAA,CAAI,CAAC,QAAQ,IAAA,CAAK,MAAA,CAAO,GAAG,CAAC,CAAC,CAAA;AAAA,EACzD;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,eAAe,MAAA,EAAiC;AAClD,IAAA,MAAM,IAAA,GAAO,MAAM,IAAA,CAAK,IAAA,CAAK,MAAM,CAAA;AACnC,IAAA,MAAM,IAAA,CAAK,WAAW,IAAA,CAAK,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAE,IAAI,CAAC,CAAA;AAC7C,IAAA,OAAO,IAAA,CAAK,MAAA;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,KAAkB,OAAA,EAAmD;AACvE,IAAA,MAAM,EAAA,GAAK,KAAK,YAAA,EAAa;AAE7B,IAAA,MAAM,YAAoC,EAAC;AAC3C,IAAA,IAAI,SAAS,MAAA,EAAQ;AACjB,MAAA,SAAA,CAAU,MAAA,GAAS,IAAA,CAAK,QAAA,CAAS,OAAA,CAAQ,MAAM,CAAA;AAAA,IACnD;AACA,IAAA,IAAI,SAAS,KAAA,EAAO;AAChB,MAAA,SAAA,CAAU,QAAQ,OAAA,CAAQ,KAAA;AAAA,IAC9B;AACA,IAAA,IAAI,SAAS,MAAA,EAAQ;AACjB,MAAA,SAAA,CAAU,SAAS,OAAA,CAAQ,MAAA;AAAA,IAC/B;AAEA,IAAA,OAAO,EAAA,CAAG,KAAK,SAAS,CAAA;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,KAAkB,MAAA,EAAiE;AACrF,IAAA,MAAM,UAAiD,EAAC;AACxD,IAAA,IAAI,MAAA;AACJ,IAAA,IAAI,QAAA,GAAW,KAAA;AAEf,IAAA,OAAO,CAAC,QAAA,EAAU;AACd,MAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,IAAA,CAAQ;AAAA,QAC9B,MAAA;AAAA,QACA,MAAA;AAAA,QACA,KAAA,EAAO;AAAA,OACV,CAAA;AAED,MAAA,OAAA,CAAQ,IAAA,CAAK,GAAG,MAAA,CAAO,IAAI,CAAA;AAC3B,MAAA,QAAA,GAAW,MAAA,CAAO,aAAA;AAClB,MAAA,MAAA,GAAS,MAAA,CAAO,MAAA;AAAA,IACpB;AAEA,IAAA,OAAO,OAAA;AAAA,EACX;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,OAAO,GAAA,EAA+B;AACxC,IAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,CAAK,GAAA,CAAI,KAAK,EAAE,IAAA,EAAM,QAAQ,CAAA;AAClD,IAAA,OAAO,KAAA,KAAU,IAAA;AAAA,EACrB;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,QAAA,CACF,GAAA,EACA,OAAA,EACA,OAAA,EACU;AACV,IAAA,MAAM,QAAA,GAAW,MAAM,IAAA,CAAK,GAAA,CAAO,GAAG,CAAA;AACtC,IAAA,IAAI,aAAa,IAAA,EAAM;AACnB,MAAA,OAAO,QAAA;AAAA,IACX;AAEA,IAAA,MAAM,KAAA,GAAQ,MAAM,OAAA,EAAQ;AAC5B,IAAA,MAAM,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,KAAA,EAAO,OAAO,CAAA;AAClC,IAAA,OAAO,KAAA;AAAA,EACX;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,SAAA,CAAU,GAAA,EAAa,KAAA,GAAgB,CAAA,EAAoB;AAC7D,IAAA,MAAM,OAAA,GAAU,MAAM,IAAA,CAAK,GAAA,CAAY,GAAG,CAAA;AAC1C,IAAA,MAAM,QAAA,GAAA,CAAY,WAAW,CAAA,IAAK,KAAA;AAClC,IAAA,MAAM,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,QAAQ,CAAA;AAC5B,IAAA,OAAO,QAAA;AAAA,EACX;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,SAAA,CAAU,GAAA,EAAa,KAAA,GAAgB,CAAA,EAAoB;AAC7D,IAAA,OAAO,IAAA,CAAK,SAAA,CAAU,GAAA,EAAK,CAAC,KAAK,CAAA;AAAA,EACrC;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,MAAA,CAAU,GAAA,EAAa,IAAA,EAAS,OAAA,EAAsC;AACxE,IAAA,MAAM,WAAW,MAAM,IAAA,CAAK,GAAA,CAAS,GAAG,KAAK,EAAC;AAC9C,IAAA,QAAA,CAAS,KAAK,IAAI,CAAA;AAClB,IAAA,MAAM,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,QAAA,EAAU,OAAO,CAAA;AACrC,IAAA,OAAO,QAAA;AAAA,EACX;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,MAAA,CACF,GAAA,EACA,OAAA,EACA,OAAA,EACU;AACV,IAAA,MAAM,OAAA,GAAU,MAAM,IAAA,CAAK,GAAA,CAAO,GAAG,CAAA;AACrC,IAAA,MAAM,OAAA,GAAU,QAAQ,OAAO,CAAA;AAC/B,IAAA,MAAM,IAAA,CAAK,GAAA,CAAI,GAAA,EAAK,OAAA,EAAS,OAAO,CAAA;AACpC,IAAA,OAAO,OAAA;AAAA,EACX;AACJ;AAnTa,SAAA,GAAN,eAAA,CAAA;AAAA,EADN,UAAA;AAAW,CAAA,EACC,SAAA,CAAA;AAwTN,IAAe,eAAf,MAA4C;AAAA,EAC/C,WAAA,CACuB,IACA,MAAA,EACrB;AAFqB,IAAA,IAAA,CAAA,EAAA,GAAA,EAAA;AACA,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAAA,EACnB;AAAA;AAAA;AAAA;AAAA,EAKM,SAAS,EAAA,EAAoB;AACnC,IAAA,OAAO,CAAA,EAAG,IAAA,CAAK,MAAM,CAAA,CAAA,EAAI,EAAE,CAAA,CAAA;AAAA,EAC/B;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,SAAS,EAAA,EAA+B;AAC1C,IAAA,OAAO,KAAK,EAAA,CAAG,GAAA,CAAO,IAAA,CAAK,QAAA,CAAS,EAAE,CAAC,CAAA;AAAA,EAC3C;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,qBAAqB,EAAA,EAAgD;AACvE,IAAA,OAAO,KAAK,EAAA,CAAG,eAAA,CAAsB,IAAA,CAAK,QAAA,CAAS,EAAE,CAAC,CAAA;AAAA,EAC1D;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,IAAA,CAAK,EAAA,EAAY,MAAA,EAAW,OAAA,EAAuC;AACrE,IAAA,MAAM,IAAA,CAAK,GAAG,GAAA,CAAI,IAAA,CAAK,SAAS,EAAE,CAAA,EAAG,QAAQ,OAAO,CAAA;AAAA,EACxD;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,OAAO,EAAA,EAA2B;AACpC,IAAA,MAAM,KAAK,EAAA,CAAG,MAAA,CAAO,IAAA,CAAK,QAAA,CAAS,EAAE,CAAC,CAAA;AAAA,EAC1C;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,OAAO,EAAA,EAA8B;AACvC,IAAA,OAAO,KAAK,EAAA,CAAG,MAAA,CAAO,IAAA,CAAK,QAAA,CAAS,EAAE,CAAC,CAAA;AAAA,EAC3C;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,SAAA,GAA+B;AACjC,IAAA,MAAM,IAAA,GAAO,MAAM,IAAA,CAAK,EAAA,CAAG,KAAK,CAAA,EAAG,IAAA,CAAK,MAAM,CAAA,CAAA,CAAG,CAAA;AACjD,IAAA,OAAO,IAAA,CAAK,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAE,IAAA,CAAK,OAAA,CAAQ,CAAA,EAAG,IAAA,CAAK,MAAM,CAAA,CAAA,CAAA,EAAK,EAAE,CAAC,CAAA;AAAA,EAChE;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,OAAA,GAAwB;AAC1B,IAAA,MAAM,GAAA,GAAM,MAAM,IAAA,CAAK,SAAA,EAAU;AACjC,IAAA,MAAM,QAAA,GAAW,MAAM,OAAA,CAAQ,GAAA,CAAI,GAAA,CAAI,GAAA,CAAI,CAAC,EAAA,KAAO,IAAA,CAAK,QAAA,CAAS,EAAE,CAAC,CAAC,CAAA;AACrE,IAAA,OAAO,QAAA,CAAS,MAAA,CAAO,CAAC,CAAA,KAAkC,MAAM,IAAI,CAAA;AAAA,EACxE;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,KAAA,GAAyB;AAC3B,IAAA,MAAM,IAAA,GAAO,MAAM,IAAA,CAAK,EAAA,CAAG,KAAK,CAAA,EAAG,IAAA,CAAK,MAAM,CAAA,CAAA,CAAG,CAAA;AACjD,IAAA,OAAO,IAAA,CAAK,MAAA;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,SAAA,GAA6B;AAC/B,IAAA,OAAO,KAAK,EAAA,CAAG,cAAA,CAAe,CAAA,EAAG,IAAA,CAAK,MAAM,CAAA,CAAA,CAAG,CAAA;AAAA,EACnD;AACJ;AAKO,SAAS,SAAS,OAAA,EAAqC;AAC1D,EAAA,OAAO,CAAC,MAAA,EAAQ,WAAA,EAAa,cAAA,KAAmB;AAC5C,IAAA,MAAM,OAAA,GAAU,CAAA,cAAA,EAAiB,MAAA,CAAO,WAAW,CAAC,CAAA,CAAA;AACpD,IAAA,MAAM,cAAA,GAAkB,MAAA,CAAmC,OAAO,CAAA,IAAkD,EAAC;AACrH,IAAA,cAAA,CAAe,IAAA,CAAK,EAAE,KAAA,EAAO,cAAA,EAAgB,SAAS,CAAA;AACtD,IAAC,MAAA,CAAmC,OAAO,CAAA,GAAI,cAAA;AAAA,EACnD,CAAA;AACJ;AAMO,IAAM,WAAN,MAAe;AAAA;AAAA;AAAA;AAAA,EAIlB,OAAO,QAAQ,OAAA,EAAyC;AACpD,IAAA,OAAO;AAAA,MACH,MAAA,EAAQ,QAAA;AAAA,MACR,SAAA,EAAW;AAAA,QACP,EAAE,OAAA,EAAS,UAAA,EAAY,QAAA,EAAU,OAAA,EAAQ;AAAA,QACzC;AAAA,OACJ;AAAA,MACA,OAAA,EAAS,CAAC,SAAA,EAAW,UAAU;AAAA,KACnC;AAAA,EACJ;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,aAAa,OAAA,EAA8C;AAC9D,IAAA,OAAO;AAAA,MACH,MAAA,EAAQ,QAAA;AAAA,MACR,OAAA,EAAS,OAAA,CAAQ,OAAA,IAAW,EAAC;AAAA,MAC7B,SAAA,EAAW;AAAA,QACP;AAAA,UACI,OAAA,EAAS,UAAA;AAAA,UACT,YAAY,OAAA,CAAQ,UAAA;AAAA,UACpB,QAAQ,OAAA,CAAQ;AAAA,SACpB;AAAA,QACA;AAAA,OACJ;AAAA,MACA,OAAA,EAAS,CAAC,SAAA,EAAW,UAAU;AAAA,KACnC;AAAA,EACJ;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,WAAW,OAAA,EAAyC;AACvD,IAAA,MAAM,YAAA,GAAe,WAAA,CAAuB,CAAA,GAAA,EAAM,OAAA,CAAQ,OAAO,CAAA,CAAE,CAAA;AAEnE,IAAA,OAAO;AAAA,MACH,MAAA,EAAQ,QAAA;AAAA,MACR,SAAA,EAAW;AAAA,QACP,EAAE,OAAA,EAAS,YAAA,EAAc,QAAA,EAAU,SAAA,EAAU;AAAA,QAC7C,EAAE,OAAA,EAAS,CAAA,WAAA,EAAc,QAAQ,OAAO,CAAA,CAAA,EAAI,UAAU,OAAA;AAAQ,OAClE;AAAA,MACA,OAAA,EAAS,CAAC,YAAY;AAAA,KAC1B;AAAA,EACJ;AACJ;AAjDa,QAAA,GAAN,eAAA,CAAA;AAAA,EADN,MAAA,CAAO,EAAE;AAAA,CAAA,EACG,QAAA,CAAA;AAsDN,SAAS,eAAA,CACZ,SAAA,EACA,OAAA,GAAoC,EAAC,EAC5B;AACT,EAAA,MAAM,OAAA,GAAU,IAAI,SAAA,EAAU;AAC9B,EAAA,OAAA,CAAQ,WAAW,SAAA,EAAW;AAAA,IAC1B,OAAA,EAAS,QAAA;AAAA,IACT,GAAG;AAAA,GACN,CAAA;AACD,EAAA,OAAO,OAAA;AACX;AAKO,SAAS,cAAA,CAAe,KAA8B,OAAA,EAA8B;AACvF,EAAA,MAAM,SAAA,GAAY,IAAI,OAAO,CAAA;AAC7B,EAAA,IAAI,CAAC,SAAA,EAAW;AACZ,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,cAAA,EAAiB,OAAO,CAAA,0BAAA,CAA4B,CAAA;AAAA,EACxE;AACA,EAAA,OAAO,SAAA;AACX","file":"index.js","sourcesContent":["/**\r\n * @flareone/kv - Workers KV Integration\r\n * High-level, type-safe wrapper for Cloudflare Workers KV\r\n */\r\n\r\nimport {\r\n    Injectable,\r\n    Module,\r\n    createToken,\r\n    type Type,\r\n    type DynamicModule,\r\n    type InjectionToken,\r\n} from '@flareone/core';\r\n\r\nexport interface KVGetOptions {\r\n    type?: 'text' | 'json' | 'arrayBuffer' | 'stream';\r\n    cacheTtl?: number;\r\n}\r\n\r\nexport interface KVPutOptions {\r\n    expiration?: number;\r\n    expirationTtl?: number;\r\n    metadata?: Record<string, unknown>;\r\n}\r\n\r\nexport interface KVListOptions {\r\n    prefix?: string;\r\n    limit?: number;\r\n    cursor?: string;\r\n}\r\nexport interface KVListResult<T = unknown> {\r\n    keys: Array<{\r\n        name: string;\r\n        expiration?: number;\r\n        metadata?: T;\r\n    }>;\r\n    list_complete: boolean;\r\n    cursor?: string;\r\n}\r\n\r\nexport interface KVValueWithMetadata<T, M = unknown> {\r\n    value: T | null;\r\n    metadata: M | null;\r\n}\r\n\r\nexport interface KVModuleOptions {\r\n    binding: string;\r\n    defaultTtl?: number;\r\n    keyPrefix?: string;\r\n    enableCache?: boolean;\r\n    cacheTtl?: number;\r\n}\r\n\r\nexport interface KVModuleAsyncOptions {\r\n    imports?: Array<Type | DynamicModule>;\r\n    useFactory: (...args: unknown[]) => KVModuleOptions | Promise<KVModuleOptions>;\r\n    inject?: InjectionToken[];\r\n}\r\n\r\nexport const KV_OPTIONS = createToken<KVModuleOptions>('KV_OPTIONS');\r\nexport const KV_NAMESPACE = createToken<KVNamespace>('KV_NAMESPACE');\r\n\r\n/**\r\n * High-level KV service with type-safe operations\r\n */\r\n@Injectable()\r\nexport class KVService {\r\n    private namespace: KVNamespace | null = null;\r\n    private options: KVModuleOptions | null = null;\r\n\r\n    /**\r\n     * Initialize with KV namespace and options\r\n     */\r\n    initialize(namespace: KVNamespace, options: KVModuleOptions): void {\r\n        this.namespace = namespace;\r\n        this.options = options;\r\n    }\r\n\r\n    /**\r\n     * Get the underlying KV namespace\r\n     */\r\n    getNamespace(): KVNamespace {\r\n        if (!this.namespace) {\r\n            throw new Error('KV namespace not initialized. Make sure KVModule is properly configured.');\r\n        }\r\n        return this.namespace;\r\n    }\r\n\r\n    /**\r\n     * Build the full key with optional prefix\r\n     */\r\n    private buildKey(key: string): string {\r\n        return this.options?.keyPrefix ? `${this.options.keyPrefix}${key}` : key;\r\n    }\r\n\r\n    /**\r\n     * Get a value by key\r\n     */\r\n    async get<T = string>(key: string, options?: KVGetOptions): Promise<T | null> {\r\n        const ns = this.getNamespace();\r\n        const fullKey = this.buildKey(key);\r\n        const type = options?.type ?? 'json';\r\n        const cacheTtl = options?.cacheTtl ?? this.options?.cacheTtl;\r\n\r\n        const kvOptions: KVNamespaceGetOptions<any> = { type };\r\n        if (cacheTtl) {\r\n            kvOptions.cacheTtl = cacheTtl;\r\n        }\r\n\r\n        return ns.get(fullKey, kvOptions) as Promise<T | null>;\r\n    }\r\n\r\n    /**\r\n     * Get a value as text\r\n     */\r\n    async getText(key: string, cacheTtl?: number): Promise<string | null> {\r\n        return this.get<string>(key, { type: 'text', cacheTtl });\r\n    }\r\n\r\n    /**\r\n     * Get a value as JSON\r\n     */\r\n    async getJson<T>(key: string, cacheTtl?: number): Promise<T | null> {\r\n        return this.get<T>(key, { type: 'json', cacheTtl });\r\n    }\r\n\r\n    /**\r\n     * Get a value as ArrayBuffer\r\n     */\r\n    async getArrayBuffer(key: string, cacheTtl?: number): Promise<ArrayBuffer | null> {\r\n        return this.get<ArrayBuffer>(key, { type: 'arrayBuffer', cacheTtl });\r\n    }\r\n\r\n    /**\r\n     * Get a value as ReadableStream\r\n     */\r\n    async getStream(key: string, cacheTtl?: number): Promise<ReadableStream | null> {\r\n        return this.get<ReadableStream>(key, { type: 'stream', cacheTtl });\r\n    }\r\n\r\n    /**\r\n     * Get a value with its metadata\r\n     */\r\n    async getWithMetadata<T = unknown, M = unknown>(\r\n        key: string,\r\n        type: 'text' | 'json' | 'arrayBuffer' | 'stream' = 'json'\r\n    ): Promise<KVValueWithMetadata<T, M>> {\r\n        const ns = this.getNamespace();\r\n        const fullKey = this.buildKey(key);\r\n        const result = await (ns.getWithMetadata as (key: string, options: { type: string }) => Promise<{ value: unknown; metadata: unknown }>)(fullKey, { type });\r\n        return {\r\n            value: result.value as T | null,\r\n            metadata: result.metadata as M | null,\r\n        };\r\n    }\r\n\r\n    /**\r\n     * Set a value\r\n     */\r\n    async set<T = unknown>(\r\n        key: string,\r\n        value: T,\r\n        options?: KVPutOptions\r\n    ): Promise<void> {\r\n        const ns = this.getNamespace();\r\n        const fullKey = this.buildKey(key);\r\n\r\n        const serialized = typeof value === 'string' ? value : JSON.stringify(value);\r\n\r\n        const kvOptions: KVNamespacePutOptions = {};\r\n        if (options?.expiration) {\r\n            kvOptions.expiration = options.expiration;\r\n        }\r\n        if (options?.expirationTtl ?? this.options?.defaultTtl) {\r\n            kvOptions.expirationTtl = options?.expirationTtl ?? this.options?.defaultTtl;\r\n        }\r\n        if (options?.metadata) {\r\n            kvOptions.metadata = options.metadata;\r\n        }\r\n\r\n        await ns.put(fullKey, serialized, kvOptions);\r\n    }\r\n\r\n    /**\r\n     * Set multiple values at once\r\n     */\r\n    async setMany<T = unknown>(\r\n        entries: Array<{ key: string; value: T; options?: KVPutOptions }>\r\n    ): Promise<void> {\r\n        await Promise.all(\r\n            entries.map(({ key, value, options }) => this.set(key, value, options))\r\n        );\r\n    }\r\n\r\n    /**\r\n     * Set a value with automatic JSON serialization\r\n     */\r\n    async setJson<T>(key: string, value: T, options?: KVPutOptions): Promise<void> {\r\n        return this.set(key, value, options);\r\n    }\r\n\r\n    /**\r\n     * Set a value as raw text\r\n     */\r\n    async setText(key: string, value: string, options?: KVPutOptions): Promise<void> {\r\n        const ns = this.getNamespace();\r\n        const fullKey = this.buildKey(key);\r\n\r\n        const kvOptions: KVNamespacePutOptions = {};\r\n        if (options?.expiration) kvOptions.expiration = options.expiration;\r\n        if (options?.expirationTtl ?? this.options?.defaultTtl) {\r\n            kvOptions.expirationTtl = options?.expirationTtl ?? this.options?.defaultTtl;\r\n        }\r\n        if (options?.metadata) kvOptions.metadata = options.metadata;\r\n\r\n        await ns.put(fullKey, value, kvOptions);\r\n    }\r\n\r\n    /**\r\n     * Set a value as ArrayBuffer\r\n     */\r\n    async setArrayBuffer(\r\n        key: string,\r\n        value: ArrayBuffer,\r\n        options?: KVPutOptions\r\n    ): Promise<void> {\r\n        const ns = this.getNamespace();\r\n        const fullKey = this.buildKey(key);\r\n\r\n        const kvOptions: KVNamespacePutOptions = {};\r\n        if (options?.expiration) kvOptions.expiration = options.expiration;\r\n        if (options?.expirationTtl ?? this.options?.defaultTtl) {\r\n            kvOptions.expirationTtl = options?.expirationTtl ?? this.options?.defaultTtl;\r\n        }\r\n        if (options?.metadata) kvOptions.metadata = options.metadata;\r\n\r\n        await ns.put(fullKey, value, kvOptions);\r\n    }\r\n\r\n    /**\r\n     * Delete a key\r\n     */\r\n    async delete(key: string): Promise<void> {\r\n        const ns = this.getNamespace();\r\n        const fullKey = this.buildKey(key);\r\n        await ns.delete(fullKey);\r\n    }\r\n\r\n    /**\r\n     * Delete multiple keys\r\n     */\r\n    async deleteMany(keys: string[]): Promise<void> {\r\n        await Promise.all(keys.map((key) => this.delete(key)));\r\n    }\r\n\r\n    /**\r\n     * Delete all keys with a prefix\r\n     */\r\n    async deleteByPrefix(prefix: string): Promise<number> {\r\n        const keys = await this.keys(prefix);\r\n        await this.deleteMany(keys.map((k) => k.name));\r\n        return keys.length;\r\n    }\r\n\r\n    /**\r\n     * List keys\r\n     */\r\n    async list<M = unknown>(options?: KVListOptions): Promise<KVListResult<M>> {\r\n        const ns = this.getNamespace();\r\n\r\n        const kvOptions: KVNamespaceListOptions = {};\r\n        if (options?.prefix) {\r\n            kvOptions.prefix = this.buildKey(options.prefix);\r\n        }\r\n        if (options?.limit) {\r\n            kvOptions.limit = options.limit;\r\n        }\r\n        if (options?.cursor) {\r\n            kvOptions.cursor = options.cursor;\r\n        }\r\n\r\n        return ns.list(kvOptions) as Promise<KVListResult<M>>;\r\n    }\r\n\r\n    /**\r\n     * Get all keys (handles pagination automatically)\r\n     */\r\n    async keys<M = unknown>(prefix?: string): Promise<Array<{ name: string; metadata?: M }>> {\r\n        const allKeys: Array<{ name: string; metadata?: M }> = [];\r\n        let cursor: string | undefined;\r\n        let complete = false;\r\n\r\n        while (!complete) {\r\n            const result = await this.list<M>({\r\n                prefix,\r\n                cursor,\r\n                limit: 1000,\r\n            });\r\n\r\n            allKeys.push(...result.keys);\r\n            complete = result.list_complete;\r\n            cursor = result.cursor;\r\n        }\r\n\r\n        return allKeys;\r\n    }\r\n\r\n    /**\r\n     * Check if a key exists\r\n     */\r\n    async exists(key: string): Promise<boolean> {\r\n        const value = await this.get(key, { type: 'text' });\r\n        return value !== null;\r\n    }\r\n\r\n    /**\r\n     * Get or set a value (cache pattern)\r\n     */\r\n    async getOrSet<T>(\r\n        key: string,\r\n        factory: () => T | Promise<T>,\r\n        options?: KVPutOptions\r\n    ): Promise<T> {\r\n        const existing = await this.get<T>(key);\r\n        if (existing !== null) {\r\n            return existing;\r\n        }\r\n\r\n        const value = await factory();\r\n        await this.set(key, value, options);\r\n        return value;\r\n    }\r\n\r\n    /**\r\n     * Increment a numeric value\r\n     */\r\n    async increment(key: string, delta: number = 1): Promise<number> {\r\n        const current = await this.get<number>(key);\r\n        const newValue = (current ?? 0) + delta;\r\n        await this.set(key, newValue);\r\n        return newValue;\r\n    }\r\n\r\n    /**\r\n     * Decrement a numeric value\r\n     */\r\n    async decrement(key: string, delta: number = 1): Promise<number> {\r\n        return this.increment(key, -delta);\r\n    }\r\n\r\n    /**\r\n     * Append to an array stored in KV\r\n     */\r\n    async append<T>(key: string, item: T, options?: KVPutOptions): Promise<T[]> {\r\n        const existing = await this.get<T[]>(key) ?? [];\r\n        existing.push(item);\r\n        await this.set(key, existing, options);\r\n        return existing;\r\n    }\r\n\r\n    /**\r\n     * Update a value with a transformer function\r\n     */\r\n    async update<T>(\r\n        key: string,\r\n        updater: (current: T | null) => T,\r\n        options?: KVPutOptions\r\n    ): Promise<T> {\r\n        const current = await this.get<T>(key);\r\n        const updated = updater(current);\r\n        await this.set(key, updated, options);\r\n        return updated;\r\n    }\r\n}\r\n\r\n/**\r\n * Base class for creating typed KV repositories\r\n */\r\nexport abstract class KVRepository<T, M = unknown> {\r\n    constructor(\r\n        protected readonly kv: KVService,\r\n        protected readonly prefix: string\r\n    ) { }\r\n\r\n    /**\r\n     * Build the full key for an entity\r\n     */\r\n    protected buildKey(id: string): string {\r\n        return `${this.prefix}:${id}`;\r\n    }\r\n\r\n    /**\r\n     * Find an entity by ID\r\n     */\r\n    async findById(id: string): Promise<T | null> {\r\n        return this.kv.get<T>(this.buildKey(id));\r\n    }\r\n\r\n    /**\r\n     * Find an entity by ID with metadata\r\n     */\r\n    async findByIdWithMetadata(id: string): Promise<KVValueWithMetadata<T, M>> {\r\n        return this.kv.getWithMetadata<T, M>(this.buildKey(id));\r\n    }\r\n\r\n    /**\r\n     * Save an entity\r\n     */\r\n    async save(id: string, entity: T, options?: KVPutOptions): Promise<void> {\r\n        await this.kv.set(this.buildKey(id), entity, options);\r\n    }\r\n\r\n    /**\r\n     * Delete an entity\r\n     */\r\n    async delete(id: string): Promise<void> {\r\n        await this.kv.delete(this.buildKey(id));\r\n    }\r\n\r\n    /**\r\n     * Check if an entity exists\r\n     */\r\n    async exists(id: string): Promise<boolean> {\r\n        return this.kv.exists(this.buildKey(id));\r\n    }\r\n\r\n    /**\r\n     * Get all entity IDs\r\n     */\r\n    async getAllIds(): Promise<string[]> {\r\n        const keys = await this.kv.keys(`${this.prefix}:`);\r\n        return keys.map((k) => k.name.replace(`${this.prefix}:`, ''));\r\n    }\r\n\r\n    /**\r\n     * Get all entities\r\n     */\r\n    async findAll(): Promise<T[]> {\r\n        const ids = await this.getAllIds();\r\n        const entities = await Promise.all(ids.map((id) => this.findById(id)));\r\n        return entities.filter((e): e is NonNullable<typeof e> => e !== null) as T[];\r\n    }\r\n\r\n    /**\r\n     * Count entities\r\n     */\r\n    async count(): Promise<number> {\r\n        const keys = await this.kv.keys(`${this.prefix}:`);\r\n        return keys.length;\r\n    }\r\n\r\n    /**\r\n     * Delete all entities\r\n     */\r\n    async deleteAll(): Promise<number> {\r\n        return this.kv.deleteByPrefix(`${this.prefix}:`);\r\n    }\r\n}\r\n\r\n/**\r\n * Parameter decorator to inject KV namespace directly\r\n */\r\nexport function InjectKV(binding: string): ParameterDecorator {\r\n    return (target, propertyKey, parameterIndex) => {\r\n        const metaKey = `__kv_bindings_${String(propertyKey)}`;\r\n        const existingParams = (target as Record<string, unknown>)[metaKey] as Array<{ index: number; binding: string }> ?? [];\r\n        existingParams.push({ index: parameterIndex, binding });\r\n        (target as Record<string, unknown>)[metaKey] = existingParams;\r\n    };\r\n}\r\n\r\n/**\r\n * KV Module for Flareone\r\n */\r\n@Module({})\r\nexport class KVModule {\r\n    /**\r\n     * Configure KV module with static options\r\n     */\r\n    static forRoot(options: KVModuleOptions): DynamicModule {\r\n        return {\r\n            module: KVModule,\r\n            providers: [\r\n                { provide: KV_OPTIONS, useValue: options },\r\n                KVService,\r\n            ],\r\n            exports: [KVService, KV_OPTIONS],\r\n        };\r\n    }\r\n\r\n    /**\r\n     * Configure KV module with async options\r\n     */\r\n    static forRootAsync(options: KVModuleAsyncOptions): DynamicModule {\r\n        return {\r\n            module: KVModule,\r\n            imports: options.imports ?? [],\r\n            providers: [\r\n                {\r\n                    provide: KV_OPTIONS,\r\n                    useFactory: options.useFactory,\r\n                    inject: options.inject,\r\n                },\r\n                KVService,\r\n            ],\r\n            exports: [KVService, KV_OPTIONS],\r\n        };\r\n    }\r\n\r\n    /**\r\n     * Configure KV for a specific feature/namespace\r\n     */\r\n    static forFeature(options: KVModuleOptions): DynamicModule {\r\n        const featureToken = createToken<KVService>(`KV_${options.binding}`);\r\n\r\n        return {\r\n            module: KVModule,\r\n            providers: [\r\n                { provide: featureToken, useClass: KVService },\r\n                { provide: `KV_OPTIONS_${options.binding}`, useValue: options },\r\n            ],\r\n            exports: [featureToken],\r\n        };\r\n    }\r\n}\r\n\r\n/**\r\n * Create a KV service for a specific namespace\r\n */\r\nexport function createKVService(\r\n    namespace: KVNamespace,\r\n    options: Partial<KVModuleOptions> = {}\r\n): KVService {\r\n    const service = new KVService();\r\n    service.initialize(namespace, {\r\n        binding: 'custom',\r\n        ...options,\r\n    });\r\n    return service;\r\n}\r\n\r\n/**\r\n * Helper to get KV namespace from environment\r\n */\r\nexport function getKVNamespace(env: Record<string, unknown>, binding: string): KVNamespace {\r\n    const namespace = env[binding] as KVNamespace | undefined;\r\n    if (!namespace) {\r\n        throw new Error(`KV namespace '${binding}' not found in environment`);\r\n    }\r\n    return namespace;\r\n}\r\n"]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@flareone/kv",
+  "version": "0.1.0",
+  "description": "Workers KV integration for Flareone framework",
+  "keywords": [
+    "cloudflare",
+    "workers",
+    "kv",
+    "flareon",
+    "key-value",
+    "storage"
+  ],
+  "homepage": "https://flareone.dev",
+  "license": "MIT",
+  "author": "Flareone Contributors",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@flareone/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250109.0",
+    "rimraf": "^6.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "clean": "rimraf dist",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}