keyv-cloudflare-kv 0.1.0-alpha

package/README.md

@@ -0,0 +1,163 @@
+# keyv-cloudflare-kv
+
+Cloudflare KV adapter for Keyv.
+
+This adapter allows Keyv to use Cloudflare Workers KV as a storage backend.
+
+It supports two environments:
+
+- Cloudflare Workers → uses native KV binding
+- Node.js / Bun / servers → uses the Cloudflare API
+
+This allows the same backend code to run anywhere.
+
+---
+
+## Installation
+
+This package is published on GitHub Packages.
+
+First configure your `.npmrc`.
+
+### .npmrc
+
+```bash
+@Sivothajan:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
+```
+
+Replace:
+
+- `YOUR_GITHUB_TOKEN`
+
+---
+
+### Install
+
+```bash
+# npm
+npm install @Sivothajan/keyv-cloudflare-kv
+
+# bun
+bun add @Sivothajan/keyv-cloudflare-kv
+```
+
+---
+
+## Usage
+
+### Node / Bun (Cloudflare API mode)
+
+```javascript
+import Keyv from 'keyv';
+import Cloudflare from 'cloudflare';
+import KeyvCloudflare from '@Sivothajan/keyv-cloudflare-kv';
+
+const client = new Cloudflare({
+  apiToken: process.env.CF_API_TOKEN,
+});
+
+const store = new KeyvCloudflare({
+  mode: 'api',
+  client,
+  accountId: process.env.CF_ACCOUNT_ID,
+  namespaceId: process.env.CF_NAMESPACE_ID,
+});
+
+const keyv = new Keyv({ store });
+
+await keyv.set('hello', 'world');
+
+const value = await keyv.get('hello');
+
+console.log(value);
+```
+
+---
+
+### Cloudflare Workers
+
+```javascript
+import Keyv from 'keyv';
+import KeyvCloudflare from '@Sivothajan/keyv-cloudflare-kv';
+
+export default {
+  async fetch(request, env) {
+    const keyv = new Keyv({
+      store: new KeyvCloudflare({
+        mode: 'workers',
+        kv: env.MY_KV,
+      }),
+    });
+
+    await keyv.set('hello', 'world');
+
+    const value = await keyv.get('hello');
+
+    return new Response(value);
+  },
+};
+```
+
+---
+
+## Options
+
+### API Mode
+
+| Option      | Type       | Required | Description           |
+| ----------- | ---------- | -------- | --------------------- |
+| mode        | "api"      | yes      | Use Cloudflare API    |
+| client      | Cloudflare | yes      | Cloudflare SDK client |
+| accountId   | string     | yes      | Cloudflare account ID |
+| namespaceId | string     | yes      | KV namespace ID       |
+| namespace   | string     | no       | Optional key prefix   |
+
+---
+
+### Workers Mode
+
+| Option    | Type        | Required | Description         |
+| --------- | ----------- | -------- | ------------------- |
+| mode      | "workers"   | yes      | Worker runtime      |
+| kv        | KVNamespace | yes      | Worker KV binding   |
+| namespace | string      | no       | Optional key prefix |
+
+---
+
+## Namespace Prefixing
+
+You can optionally prefix keys:
+
+```text
+namespace: "permissions"
+```
+
+Example stored keys:
+
+```text
+permissions:user:1
+permissions:user:2
+```
+
+---
+
+## Development
+
+Install dependencies
+
+```bash
+bun install
+```
+
+Run lint
+
+```.bash
+bun run lint
+```
+
+Build
+
+```bash
+bun run build
+```

package/dist/adapter.d.ts

@@ -0,0 +1,12 @@
+import type { KeyvCloudflareOptions } from './types';
+export default class KeyvCloudflare {
+    private client;
+    private namespace?;
+    constructor(options: KeyvCloudflareOptions);
+    get(key: string): Promise<any>;
+    set(key: string, value: any, ttl?: number): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    getMany(keys: string[]): Promise<any[]>;
+    setMany(entries: [string, any][], ttl?: number): Promise<boolean[]>;
+    deleteMany(keys: string[]): Promise<boolean[]>;
+}

package/dist/adapter.js

@@ -0,0 +1,42 @@
+import { ApiKVClient } from './api-client';
+import { parse, prefix } from './utils';
+import { WorkersKVClient } from './workers-client';
+export default class KeyvCloudflare {
+    client;
+    namespace;
+    constructor(options) {
+        this.namespace = options.namespace;
+        if (options.mode === 'workers') {
+            this.client = new WorkersKVClient(options.kv);
+            return;
+        }
+        if (options.mode === 'api') {
+            this.client = new ApiKVClient(options.client, options.accountId, options.namespaceId);
+            return;
+        }
+    }
+    async get(key) {
+        const k = prefix(this.namespace, key);
+        const value = await this.client.get(k);
+        return parse(value);
+    }
+    async set(key, value, ttl) {
+        const k = prefix(this.namespace, key);
+        await this.client.set(k, JSON.stringify(value), ttl);
+        return true;
+    }
+    async delete(key) {
+        const k = prefix(this.namespace, key);
+        await this.client.delete(k);
+        return true;
+    }
+    async getMany(keys) {
+        return Promise.all(keys.map((k) => this.get(k)));
+    }
+    async setMany(entries, ttl) {
+        return Promise.all(entries.map(([k, v]) => this.set(k, v, ttl)));
+    }
+    async deleteMany(keys) {
+        return Promise.all(keys.map((k) => this.delete(k)));
+    }
+}

package/dist/api-client.d.ts

@@ -0,0 +1,10 @@
+import type Cloudflare from 'cloudflare';
+export declare class ApiKVClient {
+    private client;
+    private accountId;
+    private namespaceId;
+    constructor(client: Cloudflare, accountId: string, namespaceId: string);
+    get(key: string): Promise<Response>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}

package/dist/api-client.js

@@ -0,0 +1,27 @@
+export class ApiKVClient {
+    client;
+    accountId;
+    namespaceId;
+    constructor(client, accountId, namespaceId) {
+        this.client = client;
+        this.accountId = accountId;
+        this.namespaceId = namespaceId;
+    }
+    async get(key) {
+        return this.client.kv.namespaces.values.get(this.namespaceId, key, {
+            account_id: this.accountId,
+        });
+    }
+    async set(key, value, ttl) {
+        await this.client.kv.namespaces.values.update(this.namespaceId, key, {
+            account_id: this.accountId,
+            value,
+            expiration_ttl: ttl ? Math.floor(ttl / 1000) : undefined,
+        });
+    }
+    async delete(key) {
+        await this.client.kv.namespaces.values.delete(this.namespaceId, key, {
+            account_id: this.accountId,
+        });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import KeyvCloudflare from './adapter';
+export default KeyvCloudflare;
+export { KeyvCloudflare };

package/dist/index.js

@@ -0,0 +1,3 @@
+import KeyvCloudflare from './adapter';
+export default KeyvCloudflare;
+export { KeyvCloudflare };

package/dist/types.d.ts

@@ -0,0 +1,25 @@
+import type { KVNamespace } from '@cloudflare/workers-types';
+import type Cloudflare from 'cloudflare';
+export interface CloudflareApiOptions {
+    client: Cloudflare;
+    accountId: string;
+    namespaceId: string;
+}
+export interface WorkersKVOptions {
+    kv: KVNamespace;
+}
+interface BaseOptions {
+    namespace?: string;
+}
+export type KeyvCloudflareOptions = (BaseOptions & {
+    mode: 'api';
+} & CloudflareApiOptions) | (BaseOptions & {
+    mode: 'workers';
+} & WorkersKVOptions) | (BaseOptions & {
+    mode?: 'auto';
+    kv?: KVNamespace;
+    client?: Cloudflare;
+    accountId?: string;
+    namespaceId?: string;
+});
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function prefix(namespace: string | undefined, key: string): string;
+export declare function parse(value: string | null): any;

package/dist/utils.js

@@ -0,0 +1,13 @@
+export function prefix(namespace, key) {
+    return namespace ? `${namespace}:${key}` : key;
+}
+export function parse(value) {
+    if (!value)
+        return undefined;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}

package/dist/workers-client.d.ts

@@ -0,0 +1,8 @@
+import type { KVNamespace } from '@cloudflare/workers-types';
+export declare class WorkersKVClient {
+    private kv;
+    constructor(kv: KVNamespace);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}

package/dist/workers-client.js

@@ -0,0 +1,17 @@
+export class WorkersKVClient {
+    kv;
+    constructor(kv) {
+        this.kv = kv;
+    }
+    async get(key) {
+        return this.kv.get(key);
+    }
+    async set(key, value, ttl) {
+        await this.kv.put(key, value, {
+            expirationTtl: ttl ? Math.floor(ttl / 1000) : undefined,
+        });
+    }
+    async delete(key) {
+        await this.kv.delete(key);
+    }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "keyv-cloudflare-kv",
+  "version": "0.1.0-alpha",
+  "description": "Cloudflare KV storage adapter for Keyv",
+  "author": {
+    "name": "Sivothayan",
+    "email": "hi@sivothayan.com",
+    "url": "https://sivothayan.com"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -w",
+    "format": "prettier --write .",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "dependencies": {
+    "cloudflare": "^4.0.0"
+  },
+  "peerDependencies": {
+    "keyv": "^4 || ^5 || ^6"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260312.1",
+    "@types/node": "^25.5.0",
+    "@typescript-eslint/eslint-plugin": "^8.57.0",
+    "@typescript-eslint/parser": "^8.57.0",
+    "eslint": "^9.39.2",
+    "eslint-plugin-import": "^2.32.0",
+    "jiti": "^2.6.1",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3"
+  },
+  "prettier": {
+    "printWidth": 80,
+    "tabWidth": 2,
+    "useTabs": false,
+    "semi": true,
+    "singleQuote": true,
+    "trailingComma": "es5",
+    "bracketSpacing": true,
+    "arrowParens": "always",
+    "endOfLine": "auto"
+  }
+}