@sunney/flareutils
Version:
Small Utilities and little goodies that make developing with Cloudflare easier and faster.
115 lines (114 loc) • 6.22 kB
TypeScript
/// <reference types="@cloudflare/workers-types" />
import type { BetterKVCacheStatus, BetterKVListReturns } from "./types";
export declare type BetterKVGetReturns<V = unknown> = string | V | ArrayBuffer | ReadableStream;
export declare interface BetterKVTypedGetOptions<L extends string> {
type: L;
cacheTtl?: number;
}
export declare interface BetterKVGetOptions {
type?: BetterKVTypeOptions;
cacheTtl?: number;
}
export declare interface BetterKVWithMetadata<V, M> {
value: V | null;
metadata: M | null;
cacheStatus: BetterKVCacheStatus;
}
export declare interface BetterKVPutOptions<K = unknown> {
expiration?: number;
expirationTtl?: number;
metadata?: K | null;
cacheTtl?: number;
}
export declare interface BetterKVListOptions extends KVNamespaceListOptions {
cacheTtl?: number;
}
export declare type BetterKVTypeOptions = "text" | "json" | "arrayBuffer" | "stream";
export declare type BetterKVValueOptions = string | ArrayBuffer | ArrayBufferView | ReadableStream;
/**
* 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) support cacheTtl. For the *KVNamespace* API, see the [types](https://github.com/cloudflare/workers-types) supplied by Cloudflare.
*
* @note This version of BetterKV is provided for backwards compatibility with KV v1. For projects using KV v2, use the regular `BetterKV` import.
*/
export declare class BetterKVOld {
/**
* Base URL used by BetterKV in Cache Operations.
*/
private readonly url;
/**
* Root KV instance utilized by BetterKV.
*/
private readonly kv;
/**
* Utilized to ensure that any operations performed on the cache do not block the main thread.
*/
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 readonly cacheSpace;
/**
* Cache instance utilized by BetterKV.
*/
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 {string} cacheSpace 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.
* @example ```ts
* const NAMESPACE = new BetterKV(env.KV, "BetterKVNamespace");
* ```
*/
constructor(kv: KVNamespace, waitUntil: ExecutionContext["waitUntil"], cacheSpace?: string);
/**
* 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
*/
getCache(): Promise<Cache>;
/**
* 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;
get(key: string, options: BetterKVGetOptions): Promise<string | null>;
get(key: string, options: BetterKVTypedGetOptions<"text">): Promise<string | null>;
get(key: string, options: BetterKVTypedGetOptions<"arrayBuffer">): Promise<ArrayBuffer | null>;
get(key: string, options: BetterKVTypedGetOptions<"stream">): Promise<ReadableStream | null>;
get<V = unknown>(key: string, options: BetterKVTypedGetOptions<"json">): Promise<V | null>;
getWithMetadata<M = unknown>(key: string, options: BetterKVGetOptions): Promise<BetterKVWithMetadata<string, M> | null>;
getWithMetadata<M = unknown>(key: string, options: BetterKVTypedGetOptions<"text">): Promise<BetterKVWithMetadata<string, M> | null>;
getWithMetadata<M = unknown>(key: string, options: BetterKVTypedGetOptions<"arrayBuffer">): Promise<BetterKVWithMetadata<ArrayBuffer, M> | null>;
getWithMetadata<M = unknown>(key: string, options: BetterKVTypedGetOptions<"stream">): Promise<BetterKVWithMetadata<ReadableStream, M> | null>;
getWithMetadata<V = unknown, M = unknown>(key: string, options: BetterKVTypedGetOptions<"json">): Promise<BetterKVWithMetadata<V, M> | 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<M = unknown>(key: string, val: BetterKVValueOptions, options?: BetterKVPutOptions<M>): 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 {BetterKVListOptions} [options] 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?: BetterKVListOptions): Promise<BetterKVListReturns<M>>;
}