https://github.com/sagi/workers-kv
Cloudflare Workers KV API for Node.js
https://github.com/sagi/workers-kv
api cloudflare-workers kv node
Last synced: 7 months ago
JSON representation
Cloudflare Workers KV API for Node.js
- Host: GitHub
- URL: https://github.com/sagi/workers-kv
- Owner: sagi
- License: mit
- Created: 2019-07-08T16:18:42.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-09-03T19:49:30.000Z (about 1 year ago)
- Last Synced: 2025-02-27T04:12:41.751Z (7 months ago)
- Topics: api, cloudflare-workers, kv, node
- Language: JavaScript
- Homepage: https://sagi.io
- Size: 299 KB
- Stars: 53
- Watchers: 2
- Forks: 5
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# workers-kv
[`@sagi.io/workers-kv`](https://www.npmjs.com/package/@sagi.io/workers-kv) is a Cloudflare Workers KV API for Node.js.
⭐ We use it at **[OpenSay](https://opensay.co/?s=workers-kv)** to efficiently cache data on Cloudflare Workers KV.
[](https://circleci.com/gh/sagi/workers-kv)
[](http://opensource.org/licenses/MIT)
[](http://npm.im/@sagi.io/workers-kv)
## Installation
~~~
$ npm i @sagi.io/workers-kv
~~~
## Quickstart
First, instantiate a `WorkersKVREST` instance:
~~~js
const WorkersKVREST = require('@sagi.io/workers-kv')
const cfAccountId = process.env.CLOUDFLARE_ACCOUNT_ID;
const cfAuthKey = process.env.CLOUDFLARE_AUTH_KEY;
const cfEmail = process.env.CLOUDFLARE_EMAIL;
const WorkersKV = new WorkersKVREST({ cfAccountId, cfAuthKey, cfEmail })
~~~
Then, access it's instance methods. For instance:
~~~js
const namespaceId = '...'
const allKeys = await KV.listAllKeys({ namespaceId })
~~~
## API
We adhere to [Cloudflare's Workers KV REST API](https://api.cloudflare.com/#workers-kv-namespace-properties).
### **`WorkersKVREST({ ... })`**
Instantiates a `WorkersKV` object with the defined below methods.
Function definition:
```js
const WorkersKVREST = function({
cfAccountId,
cfEmail,
cfAuthKey,
namespaceId = '',
}){ ... }
```
Where:
- **`cfAccountId`** *required* Your Cloudflare account id.
- **`cfEmail`** *optional|required* The email you registered with Cloudflare.
- **`cfAuthKey`** *optional|required* Your Cloudflare Auth Key.
- **`cfAuthToken`** *optional|required* Your Cloudflare Auth Token.
- **`namespaceId`** *optional* The `Workers KV` namespace id. This argument is *optional* - either provide it here, or via the methods below.
Use `cfAuthToken` with a [Cloudflare auth token](https://support.cloudflare.com/hc/en-us/articles/200167836-Managing-API-Tokens-and-Keys). You can also set `cfEmail` and `cfAuthKey` directly without using an auth token.
### **`WorkersKV.listKeys({ ... })`**
Function definition:
```js
const listKeys = async ({
namespaceId = '',
limit = MAX_KEYS_LIMIT,
cursor = undefined,
prefix = undefined,
} = {}) => { ... }
```
Where:
- **`namespaceId`** *optional* The namespace id (can also be provided while instantiating `WorkersKV`).
- **`limit`** *optional* The number of keys to return. The cursor attribute may be used to iterate over the next batch of keys if there are more than the limit.
- **`cursor`** *optional* Opaque token indicating the position from which to continue when requesting the next set of records if the amount of list results was limited by the limit parameter. A valid value for the cursor can be obtained from the cursors object in the result_info structure.
- **`prefix`** *optional* A string prefix used to filter down which keys will be returned. Exact matches and any key names that begin with the prefix will be returned.
### **`WorkersKV.listAllKeys({ ... })`**
Cursors through `listKeys` requests for you.
Function definition:
```js
const listAllKeys = async ({
namespaceId = '',
prefix = undefined,
limit = MAX_KEYS_LIMIT,
} = {}) => { ... }
```
Where:
- **`namespaceId`** *optional* The namespace id (can also be provided while instantiating `WorkersKV`).
- **`cursor`** *optional* Opaque token indicating the position from which to continue when requesting the next set of records if the amount of list results was limited by the limit parameter. A valid value for the cursor can be obtained from the cursors object in the result_info structure.
- **`prefix`** *optional* A string prefix used to filter down which keys will be returned. Exact matches and any key names that begin with the prefix will be returned.
### **`listNamespaces({ ... })`**
Function definition:
```js
const listNamespaces = async ({
page = 1,
per_page = 50,
} = {}) => { ... }
```
Where:
- **`page`** *optional* Page number of paginated results.
- **`per_page`** *optional* Maximum number of results per page.
### **`readKey({ ... })`**
Function definition:
```js
const readKey = async ({
key,
namespaceId = '',
}) => { ... }
```
Where:
- **`key`** *required* the key name.
- **`namespaceId`** *optional* The namespace id (can also be provided while instantiating `WorkersKV`).
### **`WorkersKV.deleteKey({ ... })`**
Function definition:
```js
const deleteKey= async ({
key,
namespaceId = '',
}) => { ... }
```
Where:
- **`key`** *required* the key name.
- **`namespaceId`** *optional* The namespace id (can also be provided while instantiating `WorkersKV`).
### **`WorkersKV.writeKey({ ... })`**
Function definition:
```js
const writeKey=> async ({
key,
value,
namespaceId = '',
expiration = undefined,
expiration_ttl = undefined,
}) => { ... }
```
Where:
- **`key`** *required* A key's name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid.
- **`value`** *required* A UTF-8 encoded string to be stored, up to 10 MB in length.
- **`namespaceId`** *optional* Is the namespace id (can also be provided while instantiating `WorkersKV`).
- **`expiration`** *optional* The time, measured in number of seconds since the UNIX epoch, at which the key should expire.
- **`expiration_ttl`** *optional* The number of seconds for which the key should be visible before it expires. At least 60.
### **`WorkersKV.writeMultipleKeys({ ... })`**
Function definition:
```js
const writeMultipleKeys => async ({
keyValueMap,
namespaceId = '',
expiration = undefined,
expiration_ttl = undefined,
base64 = false,
}) => { ... }
```
Where:
- **`keyValueMap`** *required* Is an object with string keys and values. e.g `{ keyName1: 'keyValue1', keyName2: 'keyValue2' }`
- **`namespaceId`** *optional* Is the namespace id (can also be provided while instantiating `WorkersKV`).
- **`expiration`** *optional* The time, measured in number of seconds since the UNIX epoch, at which the key should expire.
- **`expiration_ttl`** *optional* The number of seconds for which the key should be visible before it expires. At least 60.
- **`base64`** *optional* Whether or not the server should base64 decode the value before storing it. Useful for writing values that wouldn't otherwise be valid JSON strings, such as images. Default: false.
### **`WorkersKV.deleteMultipleKeys({ ... })`**
Function definition:
```js
const deleteMultipleKeys = async ({
keys,
namespaceId = '',
}) => { ... }
```
Where:
- **`keys`** *required* An array of keys to be deleted.
- **`namespaceId`** *optional* The namespace id (can also be provided while instantiating `WorkersKV`).