Class KVBinding<E>

Accessor for the Workers KV namespace binding (kv_namespaces in wrangler.json).

Example

const cache = new KVBinding() // binding name and default TTL from the configuration layer
await cache.putJson(ctx.env, 'session:42', { userId: 42 })
const session = await cache.getJson<Session>(ctx.env, 'session:42')

Author

Bayu Dwiyan Satria

Version

1.0.0

Since

1.0.0

Type Parameters

E extends CloudflareEnv = CloudflareEnv

Hierarchy (View Summary)

Binding<KVNamespace, E>
- KVBinding

Index

Constructors

constructor

new KVBinding<E extends CloudflareEnv = CloudflareEnv>(
settings?: KVSettings,
): KVBinding<E>
Constructs a KVBinding instance.
Type Parameters
- E extends CloudflareEnv = CloudflareEnv
Parameters
- Optionalsettings: KVSettings
  Resolved settings. Defaults to resolve('kv'), so callers normally construct this with no arguments at all.
Returns KVBinding<E>
Overrides Binding.constructor
- Defined in src/core/bindings/KVBinding.ts:40

Properties

`Private` `Optional` `Readonly`expirationTtl

expirationTtl?: number

Default expiration applied to writes, in seconds.

`Private` `Readonly`settings

settings: () => KVSettings

This accessor’s settings, resolved on first read.

Accessors

name

get name(): string
The binding name this instance resolves.

Returns string
The binding name as declared in wrangler.json.
Inherited from Binding.name
- Defined in src/core/bindings/Binding.ts:58

Methods

delete

delete(env: E, key: string): Promise<void>
Deletes a key.

Deleting a key that does not exist is not an error.
Parameters
- env: E
  The Worker environment.
- key: string
  The key to delete.
Returns Promise<void>
- Defined in src/core/bindings/KVBinding.ts:128

get

get(env: E, key: string, cacheTtl?: number): Promise<string>
Reads a value as text.
Parameters
- env: E
  The Worker environment.
- key: string
  The key to read.
- OptionalcacheTtl: number
  How long, in seconds, the edge may serve this read from cache.
Returns Promise<string>
The stored value, or null when the key is absent or expired.

Throws
MissingBindingError When the KV binding is absent.
- Defined in src/core/bindings/KVBinding.ts:57

getJson

getJson<T = unknown>(env: E, key: string, cacheTtl?: number): Promise<T>
Reads a value and parses it as JSON.
Type Parameters
- T = unknown
Parameters
- env: E
  The Worker environment.
- key: string
  The key to read.
- OptionalcacheTtl: number
  How long, in seconds, the edge may serve this read from cache.
Returns Promise<T>
The parsed value, or null when the key is absent or expired.
- Defined in src/core/bindings/KVBinding.ts:71

getWithMetadata

getWithMetadata<Metadata = unknown>(
env: E,
key: string,
): Promise<KVNamespaceGetWithMetadataResult<string, Metadata>>
Reads a value together with its metadata.
Type Parameters
- Metadata = unknown
Parameters
- env: E
  The Worker environment.
- key: string
  The key to read.
Returns Promise<KVNamespaceGetWithMetadataResult<string, Metadata>>
The value and metadata pair — both null when the key is absent.
- Defined in src/core/bindings/KVBinding.ts:84

isBound

isBound(env: E): boolean
Checks whether the binding is available on the given environment.

Use this to degrade gracefully when a binding is optional.
Parameters
- env: E
  The Worker environment.
Returns boolean
true when the binding is present.
Inherited from Binding.isBound
- Defined in src/core/bindings/Binding.ts:74

list

list<Metadata = unknown>(
env: E,
options?: KVNamespaceListOptions,
): Promise<KVNamespaceListResult<Metadata, string>>
Lists keys in the namespace.
Type Parameters
- Metadata = unknown
Parameters
- env: E
  The Worker environment.
- options: KVNamespaceListOptions = {}
  List options — prefix, limit, and cursor.
Returns Promise<KVNamespaceListResult<Metadata, string>>
The matched keys and pagination state.

Remarks
Results are paginated — check list_complete and pass the returned cursor back in to read the next page.
- Defined in src/core/bindings/KVBinding.ts:143

put

put(
    env: E,
    key: string,
    value: string | ReadableStream<any> | ArrayBuffer | ArrayBufferView,
    options?: KVNamespacePutOptions,
): Promise<void>
Writes a value, applying the configured default TTL when none is supplied.
Parameters
- env: E
  The Worker environment.
- key: string
  The key to write.
- value: string | ReadableStream<any> | ArrayBuffer | ArrayBufferView
  The value to store.
- options: KVNamespacePutOptions = {}
  Put options — expiration, TTL, and metadata.
Returns Promise<void>
- Defined in src/core/bindings/KVBinding.ts:99

putJson

putJson(
    env: E,
    key: string,
    value: unknown,
    options?: KVNamespacePutOptions,
): Promise<void>
Serialises a value to JSON and writes it.
Parameters
- env: E
  The Worker environment.
- key: string
  The key to write.
- value: unknown
  The value to serialise and store.
- options: KVNamespacePutOptions = {}
  Put options — expiration, TTL, and metadata.
Returns Promise<void>
- Defined in src/core/bindings/KVBinding.ts:116

resolve

resolve(env: E): KVNamespace
Resolves the binding, failing fast when it is not configured.
Parameters
- env: E
  The Worker environment.
Returns KVNamespace
The resolved binding.

Throws
MissingBindingError When the binding is absent from the environment.
Inherited from Binding.resolve
- Defined in src/core/bindings/Binding.ts:85

tryResolve

tryResolve(env: E): KVNamespace<string>
Resolves the binding without throwing.
Parameters
- env: E
  The Worker environment.
Returns KVNamespace<string>
The resolved binding, or null when it is not configured.
Inherited from Binding.tryResolve
- Defined in src/core/bindings/Binding.ts:101

`Private`withDefaultTtl

withDefaultTtl(options: KVNamespacePutOptions): KVNamespacePutOptions
Applies the configured default TTL to put options that do not set one.
Parameters
- options: KVNamespacePutOptions
  The caller-supplied put options.
Returns KVNamespacePutOptions
Put options with an expiration applied where appropriate.
- Defined in src/core/bindings/KVBinding.ts:156

Class KVBinding<E>

Example

Author

Version

Since

Type Parameters

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns KVBinding<E>

Properties

Private Optional ReadonlyexpirationTtl

Private Readonlysettings

Accessors

name

Returns string

Methods

delete

Parameters

Returns Promise<void>

get

Parameters

Returns Promise<string>

Throws

getJson

Type Parameters

Parameters

Returns Promise<T>

getWithMetadata

Type Parameters

Parameters

Returns Promise<KVNamespaceGetWithMetadataResult<string, Metadata>>

isBound

Parameters

Returns boolean

list

Type Parameters

Parameters

Returns Promise<KVNamespaceListResult<Metadata, string>>

Remarks

put

Parameters

Returns Promise<void>

putJson

Parameters

Returns Promise<void>

resolve

Parameters

Returns KVNamespace

Throws

tryResolve

Parameters

Returns KVNamespace<string>

PrivatewithDefaultTtl

Parameters

Returns KVNamespacePutOptions

Settings

On This Page

`Private` `Optional` `Readonly`expirationTtl

`Private` `Readonly`settings

`Private`withDefaultTtl