@alienkarma/cloudflare-kv-wrapper

A javascript/typescript wrapper for Cloudflare's KV namespaces using REST API. This helps access Cloudflare's KV data stores directly without requiring CF workers or Wrangler.

👇 Table of contents:-

• 📐 Pre-requisites
• 🚀 Get started
• 🦾 API

📐 Pre-requisites

• Account ID:
  • Go to https://dash.cloudflare.com/
  • Select an account and a website
  • Scroll to the bottom right side of the page
  • Your account ID will be visible (as shown in the image)
• Auth Token:
  • Click on "Get your API token" (as shown in the image)
  • Click on "Create Token" and use the template "Edit Cloudflare Workers"
  • Optionally, customize the settings as needed (zone restrictions, TTL, etc)
  • Once done, note down the API token

❕ NOTE: It is better to store the account ID and auth token credentials as part of your .env file and use it from there securely.

🚀 Get started

Install package via npm

npm install cloudflare-kv-wrapper

Import the appropriate module for use. You can also import their relevant types.

import { init } from "cloudflare-kv-wrapper";

init({
  accountId: "your-account-id",
  authToken: "your-auth-token",
  namespaceId: "your-optional-namespace-id",
});

import { ns } from "cloudflare-kv-wrapper";
import type { NSTypes } from "cloudflare-kv-wrapper";

KV Pair

import { kv } from "cloudflare-kv-wrapper";
import type { KVTypes } from "cloudflare-kv-wrapper";

KV Pair (Multi)

import { kvm } from "cloudflare-kv-wrapper";
import type { KVMTypes } from "cloudflare-kv-wrapper";

And that is it! You can start using KV namespaces and their KV pairs. For usage examples, check out the /example folder.

🦾 API

All functions are async functions and are fully type-supported. Each function's source API link is attached as well for further queries. You can provide the credentials and/or namespace ID beforehand using the init function or provide them as parameters in each function call.

init

Namespaces : create [source]

ns.create();

// Parameters
NSTypes.Create {
  accountId?: string;
  authToken?: string;
  title: string;
}

// Response
NSTypes.CreateResponse {
  errors: Message[];
  messages: Message[];
  success: boolean;
  result: {
    id: string;
    supports_url_encoding: boolean;
    title: string;
  };
}

Namespaces : get [source]

ns.get();

// Parameters
NSTypes.Get {
  accountId?: string;
  authToken?: string;
  namespaceId?: string;
}

// Response
NSTypes.GetResponse {
  errors: Message[];
  messages: Message[];
  success: boolean;
  result: {
    id: string;
    supports_url_encoding: boolean;
    title: string;
  };
}

Namespaces : list [source]

ns.list();

// Parameters
NSTypes.List {
  accountId?: string;
  authToken?: string;
}

// Response
NSTypes.ListResponse {
  errors: Message[];
  messages: Message[];
  success: boolean;
  result: {
    namespaces: {
      id: string;
      title: string;
    }[];
  };
}

Namespaces : remove [source]

ns.remove();

// Parameters
NSTypes.Remove {
  accountId?: string;
  authToken?: string;
  namespaceId?: string;
}

// Response
NSTypes.RemoveResponse {
  errors: Message[];
  messages: Message[];
  success: boolean;
}

Namespaces : rename [source]

ns.rename();

// Parameters
NSTypes.Rename {
  accountId?: string;
  authToken?: string;
  namespaceId?: string;
  title: string;
}

// Response
NSTypes.RenameResponse {
  errors: Message[];
  messages: Message[];
  success: boolean;
  result: {
    id: string;
    supports_url_encoding: boolean;
    title: string;
  };
}

KV Pair : list [source]

kv.list();

// Parameters
KVTypes.List {
  accountId?: string;
  authToken?: string;
  namespaceId?: string;
}

// Response
KVTypes.ListResponse {
  errors: Message[];
  messages: Message[];
  success: boolean;
  result: {
    keys: string[];
  };
}

KV Pair : metadata [source]

kv.metadata();

// Parameters
KVTypes.Metadata {
  accountId?: string;
  authToken?: string;
  namespaceId?: string;
  key: string;
}

// Response
KVTypes.MetadataResponse {
  errors: Message[];
  messages: Message[];
  success: boolean;
  result: {
    expiration: string;
    expiration_ttl: number;
    key: string;
    metadata: {
      [key: string]: string;
    };
  };
}

KV Pair : read [source]

kv.read();

// Parameters
KVTypes.Read {
  accountId?: string;
  authToken?: string;
  namespaceId?: string;
  key: string;
}

// Response
KVTypes.ReadResponse {
  errors: Message[];
  messages: Message[];
  success: boolean;
  result: {
    expiration: string;
    expiration_ttl: number;
    key: string;
    value: string;
  };
}

KV Pair : write [source]

kv.write();

// Parameters
KVTypes.Write {
  accountId?: string;
  authToken?: string;
  namespaceId?: string;
  key: string;
  value: string;
  metadata: {
    [key: string]: string;
  };
  expiration?: string;
  expiration_ttl?: number;
}

// Response
KVTypes.WriteResponse {
  errors: Message[];
  messages: Message[];
  success: boolean;
}

KV Pair : remove [source]

kv.remove();

// Parameters
KVTypes.Remove {
  accountId?: string;
  authToken?: string;
  namespaceId?: string;
  key: string;
}

// Response
KVTypes.RemoveResponse {
  errors: Message[];
  messages: Message[];
  success: boolean;
}

KV Pair (Multi) : write [source]

kvm.write();

// Parameters
KVMTypes.Write {
  accountId?: string;
  authToken?: string;
  namespaceId?: string;
  keys: string[];
}

// Response
KVMTypes.WriteResponse {
  errors: Message[];
  messages: Message[];
  success: boolean;
  result: {
    keys: {
      key: string;
      value: string;
    }[];
  };
}

KV Pair (Multi) : remove [source]

kvm.remove();

// Parameters
KVMTypes.Remove {
  accountId?: string;
  authToken?: string;
  namespaceId?: string;
  keys: string[];
}

// Response
KVMTypes.RemoveResponse {
  errors: Message[];
  messages: Message[];
  success: boolean;
}

If you face any issues, raise a request and I will try my best to solve it. Enjoy! 👍