feat: add KV package with dual provider support

package.json

@@ -171,6 +171,10 @@
     "./domains": {
       "require": "./packages/domains/dist/index.js",
       "import": "./packages/domains/dist/index.mjs"
+    },
+    "./kv": {
+      "require": "./packages/kv/dist/index.js",
+      "import": "./packages/kv/dist/index.mjs"
     }
   },
   "typesVersions": {
@@ -237,6 +241,9 @@
       ],
       "utils/node": [
         "./packages/utils/dist/node/index.d.ts"
+      ],
+      "kv": [
+        "./packages/kv/dist/index.d.ts"
       ]
     }
   },

packages/kv/.gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

packages/kv/README.md

@@ -0,0 +1,133 @@
+# Azion KV
+
+A Redis-like KV (Key-Value) client library for Azion Platform.
+
+## Installation
+
+```bash
+npm install azion
+```
+
+## Usage
+
+### Creating a Client
+
+```typescript
+import { createClient, KVClient } from 'azion/kv';
+
+// Create a client with Redis-like chaining pattern
+const client = await createClient()
+  .on('error', (err) => console.log('KV Client Error', err))
+  .connect();
+
+// Or with custom options
+const client = await createClient({
+  namespace: 'my-namespace',
+  apiToken: 'my-token',
+})
+  .on('error', (err) => console.error('KV Error:', err))
+  .connect();
+
+// Get a value
+const value = await client.get('my-key');
+
+// Set a value
+await client.set('my-key', 'my-value');
+
+// Delete a value
+await client.delete('my-key');
+
+// Disconnect when done
+await client.disconnect();
+```
+
+### Basic Operations
+
+#### Get
+
+```typescript
+// Simple get
+const value = await client.get('my-key');
+
+// Get with metadata
+const result = await client.getWithMetadata('my-key');
+console.log(result.value, result.metadata);
+```
+
+#### Set
+
+```typescript
+// Simple set
+await client.set('my-key', 'my-value');
+
+// Set with options
+await client.set('my-key', 'my-value', {
+  expiration: {
+    type: 'EX',
+    value: 10, // 10 seconds
+  },
+  metadata: { userId: '123' },
+});
+```
+
+#### Delete
+
+```typescript
+await client.delete('my-key');
+// or
+await client.del('my-key');
+```
+
+#### hSet and HSET
+
+```typescript
+await client.hSet('my-key', 'field', 'value');
+await client.HSET('my-key', 'field', 'value');
+```
+
+#### hGetAll and HGETALL
+
+```typescript
+const result = await client.hGetAll('my-key');
+const result = await client.HGETALL('my-key');
+```
+
+#### hVals and HVALS
+
+```typescript
+const result = await client.hVals('my-key');
+const result = await client.HVALS('my-key');
+```
+
+### API Reference
+
+#### KVClient
+
+Main client class for interacting with Azion KV.
+
+#### Methods
+
+- `createClient(options?: KVClientOptions): KVClient` - Create a new KV client (does not auto-connect)
+- `on(event: 'error', handler: (error: Error) => void): this` - Register error event handler (chainable)
+- `connect(): Promise<this>` - Connect to KV store (chainable)
+- `get(key: string, options?: KVGetOptions): Promise<KVGetValue | null>`
+- `getWithMetadata(key: string, options?: KVGetOptions): Promise<KVGetResult>`
+- `set(key: string, value: KVValue, options?: KVSetOptions): Promise<void>`
+- `delete(key: string): Promise<void>`
+- `disconnect(): Promise<void>`
+- `quit(): Promise<void>`
+- `hSet(key: string, field: string, value: KVValue): Promise<void>`
+- `HSET(key: string, field: string, value: KVValue): Promise<void>`
+- `hGetAll(key: string): Promise<KVGetValue | null>`
+- `HGETALL(key: string): Promise<KVGetValue | null>`
+- `hVals(key: string): Promise<KVGetValue[] | null>`
+- `HVALS(key: string): Promise<KVGetValue[] | null>`
+- `getProviderType(): 'native' | 'api'`
+
+### Types
+
+See `src/types.ts` for complete type definitions.
+
+## License
+
+MIT

packages/kv/USAGE.md

@@ -0,0 +1,143 @@
+# Azion KV Usage Guide
+
+## Dual Implementation Strategy
+
+The KV package automatically detects if `globalThis.Azion.KV` is available and chooses the appropriate implementation:
+
+- **Native Provider**: Uses `globalThis.Azion.KV` when available (Edge Runtime)
+- **API Provider**: Uses Azion's REST API as fallback
+
+## Basic Usage
+
+### 1. Auto-Detection
+
+```typescript
+import { createClient } from 'azion/kv';
+
+// Automatically detects which provider to use (Redis-like pattern)
+const client = await createClient()
+  .on('error', (err) => console.log('KV Client Error', err))
+  .connect();
+
+// On Edge Runtime with Azion.KV available -> uses Native Provider
+// In other environments -> uses API Provider
+```
+
+### 2. Force Native Provider
+
+```typescript
+import { createClient } from 'azion/kv';
+
+const client = await createClient({
+  provider: 'native',
+})
+  .on('error', (err) => console.error(err))
+  .connect();
+
+// Always uses globalThis.Azion.KV
+// Throws error if not available
+```
+
+### 3. Force API Provider
+
+```typescript
+import { createClient } from 'azion/kv';
+
+const client = await createClient({
+  provider: 'api',
+  apiToken: 'your-token-here',
+  environment: 'production', // or 'stage'
+})
+  .on('error', (err) => console.error(err))
+  .connect();
+```
+
+### 4. Check Which Provider is Being Used
+
+```typescript
+const client = await createClient()
+  .on('error', (err) => console.error(err))
+  .connect();
+
+console.log(client.getProviderType()); // 'native' or 'api'
+```
+
+## Operations
+
+### GET
+
+```typescript
+// Simple get
+const value = await client.get('user:123');
+
+// Get with metadata
+const result = await client.getWithMetadata('user:123');
+console.log(result.value);
+console.log(result.metadata);
+
+// Get with specific type
+const json = await client.get('user:123', { type: 'json' });
+const buffer = await client.get('file:data', { type: 'arrayBuffer' });
+```
+
+### SET
+
+```typescript
+// Simple set
+await client.set('user:123', 'John Doe');
+
+// Set with options
+await client.set('user:123', JSON.stringify({ name: 'John' }), {
+  expiration: {
+    type: 'EX',
+    value: 10, // 10 seconds
+  },
+  metadata: { created: Date.now() },
+});
+```
+
+### DELETE
+
+```typescript
+await client.delete('user:123');
+// or
+await client.del('user:123');
+```
+
+## Environment Configuration
+
+### Edge Runtime (Azion)
+
+```typescript
+// Automatically uses globalThis.Azion.KV
+const client = await createClient()
+  .on('error', (err) => console.error(err))
+  .connect();
+```
+
+### Local Development / CI/CD
+
+```typescript
+// Uses API with credentials
+const client = await createClient({
+  provider: 'api',
+  apiToken: process.env.AZION_API_TOKEN,
+  environment: 'stage',
+  namespace: 'dev',
+})
+  .on('error', (err) => console.error(err))
+  .connect();
+```
+
+### Example with Environment Variables
+
+```typescript
+const client = await createClient({
+  provider: process.env.KV_PROVIDER as 'auto' | 'native' | 'api',
+  apiToken: process.env.AZION_API_TOKEN,
+  environment: process.env.AZION_ENV as 'production' | 'stage',
+  namespace: process.env.AZION_KV_NAMESPACE,
+})
+  .on('error', (err) => console.error(err))
+  .connect();
+```