tsdoc

src/index.ts

@@ -47,7 +47,28 @@ export const binding = <T>(id: string, opts?: BindingOpts): T => {
 
 type DeriveCacheReturnType<T> = T extends 'default' | undefined ? Cache : Promise<Cache>;
 
-export const cacheApi = <T extends string | undefined>(cacheName?: T): DeriveCacheReturnType<T> => {
+/**
+ * Interfaces with the Cloudflare Cache API.
+ *
+ * By default, the `default` cache is used, however, a custom cache can be provided by passing a
+ * cache name as the first argument.
+ *
+ * @example
+ * ```ts
+ * const value = await cacheApi().put(..., ...);
+ * ```
+ *
+ * @example
+ * ```ts
+ * const value = await cacheApi('custom').put(..., ...);
+ * ```
+ *
+ * @param cacheName Name of the cache to open, or `undefined` to open the default cache.
+ * @returns Cache instance.
+ */
+export const cacheApi = <T extends string | undefined = undefined>(
+	cacheName?: T,
+): DeriveCacheReturnType<T> => {
 	if (isProxyEnabled()) {
 		return new Proxy(
 			{},

tests/proxy.spec.ts

@@ -474,18 +474,16 @@ suite('bindings', () => {
 		const parseRes = async (res: MaybePromise<CfResponse | undefined>) => (await res)?.text();
 
 		test('default cache -> put/match/delete', async () => {
-			const defaultCache = cacheApi('default');
-
 			const firstKey = buildUrl('first-key');
-			await defaultCache.put(firstKey, buildRes('first-value'));
+			await cacheApi('default').put(firstKey, buildRes('first-value'));
 
-			const firstValue = await parseRes(defaultCache.match(firstKey));
+			const firstValue = await parseRes(cacheApi('default').match(firstKey));
 			expect(firstValue).toEqual('first-value');
 
-			const isDeleted = await defaultCache.delete(firstKey);
+			const isDeleted = await cacheApi().delete(firstKey);
 			expect(isDeleted).toEqual(true);
 
-			const firstValueAfterDelete = await parseRes(defaultCache.match(firstKey));
+			const firstValueAfterDelete = await parseRes(cacheApi().match(firstKey));
 			expect(firstValueAfterDelete).toEqual(undefined);
 		});