@sunney/flareutils
Version:
Small Utilities and little goodies that make developing with Cloudflare easier and faster.
119 lines (118 loc) • 6.25 kB
TypeScript
/// <reference types="@cloudflare/workers-types" />
import type { BetterKVConfig, BetterKVWithMetadata, BetterKVPutOptions, BetterKVPutValues, BetterKVListReturns } from "./types";
/**
* A Storage namespace that uses the Cloudflare Workers [KV API](https://developers.cloudflare.com/workers/runtime-apis/kv) to store data, with a [Cache API](https://developers.cloudflare.com/workers/runtime-apis/cache) backing that allows you to reduce your KV billable reads.
*
* For the most part, *BetterKV* should match to the Workers *KVNamespace* standard, other than how it is instantiated, and all methods(except delete) will be cached according to the configured `cacheTtl`. For the *KVNamespace* API, see the [types](https://github.com/cloudflare/workers-types) supplied by Cloudflare.
*
* @note This version of BetterKV supports KV v2. If you require support for KV v1, please import `BetterKVOld`.
*/
export declare class BetterKV {
/**
* Base URL used by BetterKV in Cache Operations.
* @private
*/
private readonly URL;
/**
* Root KV instance utilized by BetterKV.
* @private
*/
private readonly KV;
/**
* Utilized to ensure that any operations performed on the cache do not block the main thread.
* @private
*/
private waitUntil;
/**
* The name utilized to create a dedicated cache for this BetterKV instance. If you have multiple instances of BetterKV running in parallel, make sure each has their own unique cacheSpace.
* @private
*/
private readonly config;
/**
* Cache instance utilized by BetterKV.
* @private
*/
private cache;
/**
* Creates a new BetterKV instance.
* @param {KVNamespace} KV The KV Namespace to use as the primary data store.
* @param {ExecutionContext["waitUntil"]} waitUntil The waitUntil function used to asyncronously update the cache. Must be passed in before executing any other methods on every new request.
* @param {BetterKVConfig} config Configuration for the BetterKV instance.
* @example ```ts
* const NAMESPACE = new BetterKV(env.KV, ctx.waitUntil);
* ```
*/
constructor(KV: KVNamespace, waitUntil: ExecutionContext["waitUntil"], config?: Partial<BetterKVConfig>);
/**
* Retrieves the cache instance utilized by BetterKV. Ensures that the cache is only opened once, and can be shared across multiple runs of BetterKV. If no cacheSpace is provided, the default cache is used.
* @private
*/
private getCache;
/**
* Used to update the waitUntil function to the ExecutionContext of the currently executing request. Should be passed in before executing any other methods on every new request.
* @param {ExecutionContext["waitUntil"]} waitUntil The waitUntil function used to asyncronously update the cache.
*/
setWaitUntil(waitUntil: ExecutionContext["waitUntil"]): void;
/**
* Function to handle all GET-ops hitting origin KV. Should not be called manually.
* @param {string} key The key to retrieve.
* @private
*/
private getFromOrigin;
/**
* Retrieves a value from the BetterKV Namespace.
* @template JSONValue The type of the value. Only used if using the "json" type.
* @param {string} key The key to retrieve.
* @param {BetterKVTypeOptions} type Type of value to retrieve.
* @returns {Promise<BetterKVGetReturns | null>} The value of the key, or null if the key does not exist.
* @example ```ts
* const value = await NAMESPACE.get(key);
* ```
*/
get(key: string, type?: "text"): Promise<string | null>;
get(key: string, type: "arrayBuffer"): Promise<ArrayBuffer | null>;
get(key: string, type: "stream"): Promise<ReadableStream | null>;
get<JSONValue = unknown>(key: string, type: "json"): Promise<JSONValue | null>;
/**
* Retrieves a value from the BetterKV Namespace, and its associated metadata, if provided.
* @template JSONValue The type of the value. Only used if using the "json" type.
* @template Metadata The type of the metadata.
* @param {string} key The key to retrieve.
* @param {BetterKVTypeOptions} type Type of value to retrieve.
* @returns {Promise<BetterKVWithMetadata<BetterKVGetReturns, M> | null>} The value of the key, and its associated metadata(if any), or null if the key does not exist.
*/
getWithMetadata<Metadata = unknown>(key: string, type?: "text"): Promise<BetterKVWithMetadata<string, Metadata> | null>;
getWithMetadata<Metadata = unknown>(key: string, type: "arrayBuffer"): Promise<BetterKVWithMetadata<ArrayBuffer, Metadata> | null>;
getWithMetadata<Metadata = unknown>(key: string, type: "stream"): Promise<BetterKVWithMetadata<ReadableStream, Metadata> | null>;
getWithMetadata<JSONValue = unknown, Metadata = unknown>(key: string, type: "json"): Promise<BetterKVWithMetadata<JSONValue, Metadata> | null>;
/**
* Adds a new value to the BetterKV Namespace. Supports CacheTtl.
* @param {string} key The key to add.
* @param {BetterKVValueOptions} val The value to add. Type is inferred from the value.
* @param {BetterKVAddOptions} options Options for the addition.
* @example ```ts
* await NAMESPACE.put(key, value);
* ```
*/
put<Metadata = unknown>(key: string, val: BetterKVPutValues, options?: BetterKVPutOptions<Metadata>): Promise<void>;
/**
* Removes a value from the BetterKV Namespace.
* @param {string} key The key to remove.
* @example ```ts
* await NAMESPACE.delete(key);
* ```
*/
delete(key: string): Promise<void>;
/**
* Lists keys in the BetterKV Namespace according to the options given. Supports CacheTtl.
* @template M The type of the metadata.
* @param {KVNamespaceListOptions} [opts] Options for the listing.
* @returns {Promise<BetterKVListReturns<M>>} The keys in the namespace, and their associated metadata(if any).
* @example ```ts
* const {keys, list_complete, cursor} = await NAMESPACE.list();
* ```
*/
list<M = unknown>(opts?: KVNamespaceListOptions): Promise<BetterKVListReturns<M>>;
}
export * from "./types";
export { BetterKVOld } from "./old";