feat(kv): add Entity class (#159)

* feat(cfw.kv): add `Entity` class

* feaet: add Entity read/write/delete hooks

Author: lukeed

packages/worktop/src/cfw.kv.d.ts

@@ -1,4 +1,4 @@
-import type { Dict } from 'worktop/utils';
+import type { Dict, Promisable } from 'worktop/utils';
 
 export namespace KV {
 	type Metadata = Dict<any>;
@@ -106,3 +106,47 @@ export function until<X extends string>(
 	toMake: () => X,
 	toSearch: (val: X) => Promise<unknown | false>
 ): Promise<X>;
+
+export declare class Entity {
+	/**
+	 * The KV Namespace for this entity.
+	 */
+	readonly ns: KV.Namespace;
+
+	/**
+	 * Cache.Entity operations
+	 */
+	readonly cache: {
+		get(key: string): Promise<Response|void>;
+		put<T>(key: string, value: T|null, ttl: number): Promise<boolean>;
+		delete(key: string): Promise<boolean>;
+	};
+
+	/**
+	 * cache ttl (seconds)
+	 * @default 0
+	 */
+	ttl?: number;
+
+	/**
+	 * key prefix
+	 * @default ""
+	 */
+	prefix?: string;
+
+	constructor(binding: KV.Namespace);
+
+	onread?(key: string, value: unknown): Promisable<void>;
+	onwrite?(key: string, value: unknown): Promisable<void>;
+	ondelete?(key: string, value: unknown): Promisable<void>;
+
+	list(options?: KV.Options.List): Promise<string[]>;
+
+	get(key: string, type: 'text'): Promise<string|null>;
+	get<T=unknown>(key: string, type?: 'json'): Promise<T|null>;
+	get(key: string, type: 'arrayBuffer'): Promise<ArrayBuffer|null>;
+
+	put<T>(key: string, value: T|null): Promise<boolean>;
+
+	delete(key: string, format?: 'text' | 'json' | 'arrayBuffer'): Promise<boolean>;
+}

packages/worktop/src/cfw.kv.test.ts

@@ -339,3 +339,51 @@ until('should loop until first `nullish` value', async () => {
 });
 
 until.run();
+
+// ---
+
+const Entity = suite('Entity');
+
+Entity('should be a function', () => {
+	assert.type(KV.Entity, 'function');
+});
+
+Entity('should return `Entity` interface', () => {
+	let binding = Namespace();
+	let thing = new KV.Entity(binding);
+
+	assert.type(thing.get, 'function');
+	assert.type(thing.list, 'function');
+	assert.type(thing.delete, 'function');
+	assert.type(thing.put, 'function');
+
+	assert.type(thing.cache, 'object');
+	assert.type(thing.cache.get, 'function');
+	assert.type(thing.cache.delete, 'function');
+	assert.type(thing.cache.put, 'function');
+
+	assert.type(thing.ttl, 'number');
+	assert.is(thing.ns, binding);
+});
+
+Entity('should include property defaults', () => {
+	let binding = Namespace();
+	let thing = new KV.Entity(binding);
+	assert.is(thing.prefix, '');
+	assert.is(thing.ttl, 0);
+});
+
+Entity('should allow class extension', () => {
+	class User extends KV.Entity {
+		ttl = 3600;
+		prefix = 'user';
+	}
+
+	let binding = Namespace();
+	let thing = new User(binding);
+
+	assert.is(thing.prefix, 'user');
+	assert.is(thing.ttl, 3600);
+});
+
+Entity.run();

packages/worktop/src/cfw.kv.ts

@@ -1,4 +1,6 @@
-import type { KV, Options, Database as DB } from 'worktop/cfw.kv';
+import * as Cache from './internal/cfw.cache';
+import type { KV, Options, Database as DB, Entity as E } from 'worktop/cfw.kv';
+import type { Promisable } from 'worktop/utils';
 
 export function Database<Models, I extends Record<keyof Models, string> = { [P in keyof Models]: string }>(binding: KV.Namespace): DB<Models, I> {
 	var $ = <K extends keyof I>(type: K, uid: I[K]) => `${type}__${uid}`;
@@ -77,3 +79,117 @@ export async function until<X extends string>(
 		if (exists == null) return tmp;
 	}
 }
+
+export class Entity implements E {
+	readonly ns: KV.Namespace;
+	readonly cache: Cache.Entity;
+
+	prefix = '';
+	ttl = 0;
+
+	onread?(key: string, value: unknown): Promisable<void>;
+	onwrite?(key: string, value: unknown): Promisable<void>;
+	ondelete?(key: string, value: unknown): Promisable<void>;
+
+	constructor(ns: KV.Namespace) {
+		this.cache = new Cache.Entity;
+		this.ns = ns;
+	}
+
+	async list(options?: KV.Options.List): Promise<string[]> {
+		options = options || {};
+		let { limit, prefix='' } = options;
+
+		if (this.prefix) {
+			options.prefix = prefix.startsWith(this.prefix) ? prefix : (this.prefix + prefix);
+		}
+
+		if (limit) {
+			options.limit = Math.min(1000, limit);
+		}
+
+		let iter = list(this.ns, {
+			...options,
+			metadata: false,
+		});
+
+		let output: string[] = [];
+
+		for await (let chunk of iter) {
+			for (let i=0, len=this.prefix.length; i < chunk.keys.length; i++) {
+				output.push((chunk.keys[i] as string).substring(len));
+				if (limit && output.length === limit) return output;
+			}
+			if (chunk.done) break;
+		}
+
+		return output;
+	}
+
+	async get<T>(key: string, format: Exclude<KV.GetFormat, 'stream'> = 'json'): Promise<T|null> {
+		if (this.prefix) key = this.prefix + key;
+
+		let value: T|null;
+		let res = this.ttl && await this.cache.get(key);
+
+		if (res) {
+			value = await res[format]();
+		} else {
+			// @ts-ignore - TODO fix overload types
+			value = await this.ns.get<T>(key, format);
+			if (this.ttl) await this.cache.put(key, value, this.ttl);
+		}
+
+		if (this.onread) {
+			await this.onread(key, value);
+		}
+
+		return value;
+	}
+
+	async put<T>(key: string, value: T|null): Promise<boolean> {
+		if (this.prefix) key = this.prefix + key;
+
+		let input = Cache.normalize(value);
+		let bool = await this.ns.put(key, input).then(
+			() => true,
+			() => false
+		);
+
+		if (bool && this.ttl) {
+			// allow cache to see `null` value
+			let x = value == null ? null : input;
+			bool = await this.cache.put(key, x, this.ttl);
+		}
+
+		if (bool && this.onwrite) {
+			await this.onwrite(key, value);
+		}
+
+		return bool;
+	}
+
+	async delete(key: string, format: Exclude<KV.GetFormat, 'stream'> = 'json'): Promise<boolean> {
+		if (this.prefix) key = this.prefix + key;
+
+		let hasHook = typeof this.ondelete === 'function';
+
+		// @ts-ignore - TODO fix overload types
+		let value = hasHook && await this.ns.get(key, format);
+
+		let bool = await this.ns.delete(key).then(
+			() => true,
+			() => false
+		);
+
+		if (bool && this.ttl) {
+			bool = await this.cache.delete(key);
+		}
+
+		if (bool && hasHook) {
+			await this.ondelete!(key, value);
+		}
+
+		return bool;
+	}
+}

packages/worktop/src/internal/cfw.cache.ts

@@ -0,0 +1,32 @@
+import type { KV } from 'worktop/cfw.kv';
+
+export function normalize(value: unknown): KV.Value {
+	return (
+		typeof value === 'string'
+		|| value instanceof ArrayBuffer
+		|| value instanceof ReadableStream
+	) ? value : JSON.stringify(value);
+}
+
+export class Entity {
+	get(key: string): Promise<Response|void> {
+		return caches.default.match(key);
+	}
+
+	put<T>(key: string, value: T|null, ttl: number): Promise<boolean> {
+		if (!ttl) return Promise.resolve(true);
+
+		let headers = { 'cache-control': `public,max-age=${ttl}` };
+		let body = value == null ? null : normalize(value);
+		let res = new Response(body, { headers });
+
+		return caches.default.put(key, res).then(
+			() => true,
+			() => false
+		);
+	}
+
+	delete(key: string): Promise<boolean> {
+		return caches.default.delete(key);
+	}
+}

packages/worktop/types/cfw.kv.ts

@@ -1,4 +1,4 @@
-import { Database, list, paginate, until } from 'worktop/cfw.kv';
+import { Database, Entity, list, paginate, until } from 'worktop/cfw.kv';
 import type { KV } from 'worktop/cfw.kv';
 
 /**
@@ -137,3 +137,116 @@ async function storage() {
 	let keys = await paginate(APPS, { page: 2, limit: 12, prefix: 'hello' });
 	assert<string>(keys[0]);
 }
+
+/**
+ * Entity
+ */
+
+let apps = new Entity(APPS);
+
+assert<unknown>(
+	await apps.get('abc123')
+);
+
+assert<IApp|null>(
+	await apps.get<IApp>('abc123')
+);
+
+assert<IApp|null>(
+	await apps.get<IApp>('abc123', 'json')
+);
+
+assert<string|null>(
+	await apps.get('abc123', 'text')
+);
+
+assert<ArrayBuffer|null>(
+	await apps.get('abc123', 'arrayBuffer')
+);
+
+// @ts-expect-error - T w/ "text"
+await apps.get<number>('abc123', 'text');
+
+// @ts-expect-error - T w/ "arrayBuffer"
+await apps.get<number>('abc123', 'arrayBuffer');
+
+assert<boolean>(
+	await apps.put('abc123', null)
+);
+
+assert<boolean>(
+	await apps.put('abc123', 'foobar')
+);
+
+assert<boolean>(
+	await apps.put<IApp>('abc123', {
+		uid: toUID(),
+		name: 'foobar'
+	})
+);
+
+assert<boolean>(
+	await apps.put('abc123', new ArrayBuffer(1))
+);
+
+assert<boolean>(
+	await apps.delete('abc123')
+);
+
+assert<number>(apps.ttl!);
+assert<string>(apps.prefix!);
+
+// ---
+
+class User extends Entity {
+	ttl = 3600; // 1hr
+	prefix = 'user';
+
+	async onread(key: string, value: IApp) {
+		// do something with the value
+	}
+}
+
+declare let ns: KV.Namespace;
+let users = new User(ns);
+
+assert<unknown>(
+	await users.get('abc123')
+);
+
+assert<string|null>(
+	await users.get('abc123', 'text')
+);
+
+assert<ArrayBuffer|null>(
+	await users.get('abc123', 'arrayBuffer')
+);
+
+// @ts-expect-error - T w/ "text"
+await users.get<number>('abc123', 'text');
+
+// @ts-expect-error - T w/ "arrayBuffer"
+await users.get<number>('abc123', 'arrayBuffer');
+
+assert<boolean>(
+	await users.put('abc123', null)
+);
+
+assert<boolean>(
+	await users.put('abc123', 'foobar')
+);
+
+assert<boolean>(
+	await users.put<IApp>('abc123', {
+		uid: toUID(),
+		name: 'foobar'
+	})
+);
+
+assert<boolean>(
+	await users.put('abc123', new ArrayBuffer(1))
+);
+
+assert<boolean>(
+	await users.delete('abc123')
+);