@atcute/cache 0.1.0

package/dist/walker.d.ts

@@ -0,0 +1,34 @@
+import type { BaseSchema } from '@atcute/lexicons/validations';
+import type { EntityTypeId } from './types.js';
+/**
+ * compiled walk function for a schema
+ * @param data input data to walk
+ * @returns walked data with entities swapped in
+ */
+export type WalkFn = (data: unknown) => unknown;
+/**
+ * context for building and executing schema walkers
+ */
+export interface WalkerContext {
+    /** check if a type ID is a registered entity */
+    isEntityType: (typeId: EntityTypeId) => boolean;
+    /** upsert entity into cache, returns the cached entity */
+    upsertEntity: (typeId: EntityTypeId, incoming: object) => object;
+}
+/**
+ * walker cache that tracks schema -> compiled walker mappings
+ * invalidated when entity definitions change
+ */
+export declare class WalkerCache {
+    #private;
+    constructor(ctx: WalkerContext);
+    /** clear all cached walkers */
+    invalidate(): void;
+    /**
+     * get or build a walker for a schema
+     * @param schema schema to get walker for
+     * @returns walk function
+     */
+    getWalker(schema: BaseSchema): WalkFn;
+}
+//# sourceMappingURL=walker.d.ts.map

package/dist/walker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walker.d.ts","sourceRoot":"","sources":["../lib/walker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAA+B,MAAM,8BAA8B,CAAC;AAS5F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C;;;;GAIG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;AAKhD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,gDAAgD;IAChD,YAAY,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,OAAO,CAAC;IAChD,0DAA0D;IAC1D,YAAY,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CACjE;AAED;;;GAGG;AACH,qBAAa,WAAW;;IAIvB,YAAY,GAAG,EAAE,aAAa,EAE7B;IAED,+BAA+B;IAC/B,UAAU,IAAI,IAAI,CAEjB;IAED;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAEpC;CAwHD"}

package/dist/walker.js

@@ -0,0 +1,179 @@
+import { isArraySchema, isNullableSchema, isObjectSchema, isOptionalSchema, isVariantSchema, } from './predicates.js';
+import { getTypeIdFromSchema } from './types.js';
+/** identity walker - returns data unchanged */
+const identity = (data) => data;
+/**
+ * walker cache that tracks schema -> compiled walker mappings
+ * invalidated when entity definitions change
+ */
+export class WalkerCache {
+    #ctx;
+    #cache = new WeakMap();
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    /** clear all cached walkers */
+    invalidate() {
+        this.#cache = new WeakMap();
+    }
+    /**
+     * get or build a walker for a schema
+     * @param schema schema to get walker for
+     * @returns walk function
+     */
+    getWalker(schema) {
+        return this.#build(schema);
+    }
+    #build(schema) {
+        const cached = this.#cache.get(schema);
+        if (cached !== undefined) {
+            return cached;
+        }
+        // set thunk for cycle detection - will be replaced with actual walker
+        this.#cache.set(schema, (data) => this.#cache.get(schema)(data));
+        const walker = this.#buildForSchema(schema);
+        this.#cache.set(schema, walker);
+        return walker;
+    }
+    #buildForSchema(schema) {
+        if (isObjectSchema(schema)) {
+            return this.#buildObjectWalker(schema);
+        }
+        if (isArraySchema(schema)) {
+            return this.#buildArrayWalker(schema);
+        }
+        if (isVariantSchema(schema)) {
+            return this.#buildVariantWalker(schema);
+        }
+        if (isOptionalSchema(schema)) {
+            const innerWalker = this.#build(schema.wrapped);
+            if (innerWalker === identity) {
+                return identity;
+            }
+            return createOptionalWalker(innerWalker);
+        }
+        if (isNullableSchema(schema)) {
+            const innerWalker = this.#build(schema.wrapped);
+            if (innerWalker === identity) {
+                return identity;
+            }
+            return createNullableWalker(innerWalker);
+        }
+        // primitive types - no walking needed
+        return identity;
+    }
+    #buildObjectWalker(schema) {
+        const ctx = this.#ctx;
+        // check if this is a registered entity type
+        const typeId = getTypeIdFromSchema(schema);
+        const entityTypeId = typeId !== undefined && ctx.isEntityType(typeId) ? typeId : undefined;
+        // build walkers for properties that need walking
+        const shape = schema.shape;
+        let propWalkers = [];
+        for (const propName in shape) {
+            const propSchema = shape[propName];
+            const propWalker = this.#build(propSchema);
+            if (propWalker !== identity) {
+                propWalkers.push([propName, propWalker]);
+            }
+        }
+        if (propWalkers.length === 0) {
+            propWalkers = undefined;
+        }
+        // nothing to do
+        if (entityTypeId === undefined && propWalkers === undefined) {
+            return identity;
+        }
+        return createObjectWalker(ctx, entityTypeId, propWalkers);
+    }
+    #buildArrayWalker(schema) {
+        const itemWalker = this.#build(schema.item);
+        if (itemWalker === identity) {
+            return identity;
+        }
+        return createArrayWalker(itemWalker);
+    }
+    #buildVariantWalker(schema) {
+        // build a map of type ID -> walker for members that need walking
+        const walkerMap = Object.create(null);
+        let hasWalkers = false;
+        for (const member of schema.members) {
+            const memberSchema = member;
+            const memberTypeId = getTypeIdFromSchema(memberSchema);
+            if (memberTypeId !== undefined) {
+                const memberWalker = this.#build(memberSchema);
+                if (memberWalker !== identity) {
+                    walkerMap[memberTypeId] = memberWalker;
+                    hasWalkers = true;
+                }
+            }
+        }
+        if (!hasWalkers) {
+            return identity;
+        }
+        return createVariantWalker(walkerMap);
+    }
+}
+/** creates an object walker with minimal closure scope */
+const createObjectWalker = (ctx, entityTypeId, propWalkers) => {
+    return (data) => {
+        let entity = data;
+        let cloned = entityTypeId !== undefined;
+        if (entityTypeId !== undefined) {
+            entity = ctx.upsertEntity(entityTypeId, entity);
+        }
+        if (propWalkers !== undefined) {
+            for (const [name, walk] of propWalkers) {
+                const propValue = entity[name];
+                const walked = walk(propValue);
+                if (walked !== propValue) {
+                    if (entityTypeId === undefined && !cloned) {
+                        entity = { ...entity };
+                        cloned = true;
+                    }
+                    entity[name] = walked;
+                }
+            }
+        }
+        return entity;
+    };
+};
+/** creates an array walker with minimal closure scope */
+const createArrayWalker = (itemWalker) => {
+    return (data) => {
+        const prev = data;
+        let next;
+        for (let i = 0; i < prev.length; i++) {
+            const item = prev[i];
+            const walked = itemWalker(item);
+            if (walked !== item) {
+                if (next === undefined) {
+                    next = prev.slice();
+                }
+                next[i] = walked;
+            }
+        }
+        return next ?? prev;
+    };
+};
+/** creates a variant walker with minimal closure scope */
+const createVariantWalker = (walkerMap) => {
+    return (data) => {
+        const obj = data;
+        const type = obj.$type;
+        if (type === undefined) {
+            return data;
+        }
+        const memberWalker = walkerMap[type];
+        return memberWalker ? memberWalker(data) : data;
+    };
+};
+/** creates an optional walker with minimal closure scope */
+const createOptionalWalker = (innerWalker) => {
+    return (data) => (data === undefined ? data : innerWalker(data));
+};
+/** creates a nullable walker with minimal closure scope */
+const createNullableWalker = (innerWalker) => {
+    return (data) => (data === null ? data : innerWalker(data));
+};
+//# sourceMappingURL=walker.js.map

package/dist/walker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walker.js","sourceRoot":"","sources":["../lib/walker.ts"],"names":[],"mappings":"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"}

package/lib/index.ts

@@ -0,0 +1,3 @@
+export { NormalizedCache } from './store.js';
+export type { NormalizedCacheOptions } from './store.js';
+export type { EntityDefinition, EntitySubscriber, EntityTypeId, TypeSubscriber } from './types.js';

package/lib/predicates.ts

@@ -0,0 +1,39 @@
+import type {
+	ArraySchema,
+	BaseSchema,
+	LiteralSchema,
+	NullableSchema,
+	ObjectSchema,
+	OptionalSchema,
+	VariantSchema,
+} from '@atcute/lexicons/validations';
+
+/** check if schema is an object schema */
+export const isObjectSchema = (schema: BaseSchema): schema is ObjectSchema => {
+	return schema.type === 'object';
+};
+
+/** check if schema is an array schema */
+export const isArraySchema = (schema: BaseSchema): schema is ArraySchema => {
+	return schema.type === 'array';
+};
+
+/** check if schema is a variant schema */
+export const isVariantSchema = (schema: BaseSchema): schema is VariantSchema => {
+	return schema.type === 'variant';
+};
+
+/** check if schema is an optional schema */
+export const isOptionalSchema = (schema: BaseSchema): schema is OptionalSchema => {
+	return schema.type === 'optional';
+};
+
+/** check if schema is a nullable schema */
+export const isNullableSchema = (schema: BaseSchema): schema is NullableSchema => {
+	return schema.type === 'nullable';
+};
+
+/** check if schema is a literal schema */
+export const isLiteralSchema = (schema: BaseSchema): schema is LiteralSchema => {
+	return schema.type === 'literal';
+};

package/lib/store.ts

@@ -0,0 +1,364 @@
+import type { BaseSchema, InferOutput, ObjectSchema } from '@atcute/lexicons/validations';
+
+import type { EntityDefinition, EntitySubscriber, EntityTypeId, TypeSubscriber } from './types.js';
+import { getTypeIdFromSchema } from './types.js';
+import { WalkerCache } from './walker.js';
+
+type AnyEntityDefinition = EntityDefinition<ObjectSchema>;
+
+interface EntityStoreEntry {
+	definition: AnyEntityDefinition;
+	entities: Map<string, WeakRef<object>>;
+	subscribers: Map<string, Set<EntitySubscriber<unknown>>>;
+	typeSubscribers: Set<TypeSubscriber<unknown>>;
+}
+
+export interface NormalizedCacheOptions {
+	wrapEntity?: (entity: unknown) => unknown;
+}
+
+/**
+ * normalized cache store for AT Protocol responses
+ */
+export class NormalizedCache {
+	#schemaToTypeId = new Map<ObjectSchema, EntityTypeId>();
+
+	#stores = new Map<EntityTypeId, EntityStoreEntry>();
+	#wrapEntity: ((entity: unknown) => unknown) | undefined;
+
+	#walkerCache = new WalkerCache({
+		isEntityType: (typeId) => this.#stores.has(typeId),
+		upsertEntity: (typeId, incoming) => this.#upsertEntity(typeId, incoming),
+	});
+
+	#registry = new FinalizationRegistry<{ typeId: EntityTypeId; key: string }>((held) => {
+		const store = this.#stores.get(held.typeId);
+		if (store) {
+			const ref = store.entities.get(held.key);
+			// only delete if the ref is actually dead (not replaced with a new one)
+			if (ref !== undefined && ref.deref() === undefined) {
+				store.entities.delete(held.key);
+			}
+		}
+	});
+
+	constructor(options?: NormalizedCacheOptions) {
+		this.#wrapEntity = options?.wrapEntity;
+	}
+
+	#getTypeId(schema: ObjectSchema): EntityTypeId | undefined {
+		let typeId = this.#schemaToTypeId.get(schema);
+		if (typeId === undefined) {
+			typeId = getTypeIdFromSchema(schema);
+			if (typeId !== undefined) {
+				this.#schemaToTypeId.set(schema, typeId);
+			}
+		}
+		return typeId;
+	}
+
+	#getStore(schema: ObjectSchema): EntityStoreEntry | undefined {
+		const typeId = this.#getTypeId(schema);
+		return typeId ? this.#stores.get(typeId) : undefined;
+	}
+
+	#notifySubscribers(store: EntityStoreEntry, key: string, entity: object | undefined): void {
+		// notify entity-specific subscribers
+		const entitySubs = store.subscribers.get(key);
+		if (entitySubs) {
+			for (const cb of entitySubs) {
+				cb(entity);
+			}
+		}
+
+		// notify type subscribers
+		for (const cb of store.typeSubscribers) {
+			cb(key, entity);
+		}
+	}
+
+	#upsertEntity(typeId: EntityTypeId, incoming: object): object {
+		const store = this.#stores.get(typeId)!;
+		const key = store.definition.key(incoming);
+
+		const existingRef = store.entities.get(key);
+		const existing = existingRef?.deref();
+
+		if (existing !== undefined) {
+			// merge incoming into existing
+			const merge = store.definition.merge;
+			const merged = merge ? merge(existing, incoming) : incoming;
+			Object.assign(existing, merged);
+			this.#notifySubscribers(store, key, existing);
+			return existing;
+		}
+
+		// new entity - wrap and store it
+		const entity: any = this.#wrapEntity ? this.#wrapEntity(incoming) : incoming;
+		store.entities.set(key, new WeakRef(entity));
+		this.#registry.register(entity, { typeId, key });
+		this.#notifySubscribers(store, key, entity);
+		return entity;
+	}
+
+	/**
+	 * register an entity type for normalization
+	 * @param definition entity definition with schema, key extractor, and optional merge function
+	 */
+	define<T extends ObjectSchema>(definition: EntityDefinition<T>): void {
+		const typeId = getTypeIdFromSchema(definition.schema);
+		if (typeId === undefined) {
+			throw new Error('schema must have a $type literal field');
+		}
+
+		if (this.#stores.has(typeId)) {
+			throw new Error(`entity type "${typeId}" is already defined`);
+		}
+
+		this.#stores.set(typeId, {
+			definition: definition as unknown as AnyEntityDefinition,
+			entities: new Map(),
+			subscribers: new Map(),
+			typeSubscribers: new Set(),
+		});
+
+		this.#schemaToTypeId.set(definition.schema, typeId);
+
+		// invalidate cached walkers since entity types changed
+		this.#walkerCache.invalidate();
+	}
+
+	/**
+	 * walk response using schema, normalize and cache entities
+	 * @param schema the response schema
+	 * @param data the response data
+	 * @returns response with cached entity refs swapped in
+	 */
+	normalize<T extends BaseSchema>(schema: T, data: InferOutput<T>): InferOutput<T> {
+		return this.#walkerCache.getWalker(schema)(data) as InferOutput<T>;
+	}
+
+	/**
+	 * create a reusable normalizer function for a schema
+	 * @param schema the response schema
+	 * @returns function that normalizes data according to schema
+	 */
+	normalizer<T extends BaseSchema>(schema: T): (data: InferOutput<T>) => InferOutput<T> {
+		return (data) => this.normalize(schema, data);
+	}
+
+	/**
+	 * get entity from cache by schema and key
+	 * @param schema the entity schema
+	 * @param key the entity key
+	 * @returns the cached entity or undefined if not found/collected
+	 */
+	get<T extends ObjectSchema>(schema: T, key: string): InferOutput<T> | undefined {
+		const store = this.#getStore(schema);
+		if (!store) {
+			return undefined;
+		}
+
+		const ref = store.entities.get(key);
+		return ref?.deref() as InferOutput<T> | undefined;
+	}
+
+	/**
+	 * check if entity exists in cache
+	 * @param schema the entity schema
+	 * @param key the entity key
+	 */
+	has(schema: ObjectSchema, key: string): boolean {
+		const store = this.#getStore(schema);
+		if (!store) {
+			return false;
+		}
+
+		const ref = store.entities.get(key);
+		return ref?.deref() !== undefined;
+	}
+
+	/**
+	 * get all cached entities of a type
+	 * @param schema the entity schema
+	 * @returns map of key to entity (only includes live refs)
+	 */
+	getAll<T extends ObjectSchema>(schema: T): Map<string, InferOutput<T>> {
+		const store = this.#getStore(schema);
+		const result = new Map<string, InferOutput<T>>();
+
+		if (!store) {
+			return result;
+		}
+
+		for (const [key, ref] of store.entities) {
+			const entity = ref.deref();
+			if (entity !== undefined) {
+				result.set(key, entity as InferOutput<T>);
+			}
+		}
+
+		return result;
+	}
+
+	/**
+	 * set entity directly in cache
+	 * @param schema the entity schema
+	 * @param key the entity key
+	 * @param entity the entity to cache
+	 */
+	set<T extends ObjectSchema>(schema: T, key: string, entity: InferOutput<T>): void {
+		const typeId = this.#getTypeId(schema);
+		if (typeId === undefined || !this.#stores.has(typeId)) {
+			throw new Error('schema is not registered');
+		}
+
+		const store = this.#stores.get(typeId)!;
+		const existingRef = store.entities.get(key);
+		const existing = existingRef?.deref();
+
+		if (existing !== undefined) {
+			Object.assign(existing, entity);
+			this.#notifySubscribers(store, key, existing);
+		} else {
+			const wrapped: any = this.#wrapEntity ? this.#wrapEntity(entity) : entity;
+			store.entities.set(key, new WeakRef(wrapped));
+			this.#registry.register(wrapped, { typeId, key });
+			this.#notifySubscribers(store, key, wrapped);
+		}
+	}
+
+	/**
+	 * update entity with updater function
+	 * @param schema the entity schema
+	 * @param key the entity key
+	 * @param updater function that returns updated entity
+	 * @returns true if entity was found and updated
+	 */
+	update<T extends ObjectSchema>(
+		schema: T,
+		key: string,
+		updater: (entity: InferOutput<T>) => InferOutput<T>,
+	): boolean {
+		const store = this.#getStore(schema);
+		if (!store) {
+			return false;
+		}
+
+		const ref = store.entities.get(key);
+		const existing = ref?.deref() as InferOutput<T> | undefined;
+
+		if (existing === undefined) {
+			return false;
+		}
+
+		const updated = updater(existing);
+		Object.assign(existing, updated);
+		this.#notifySubscribers(store, key, existing);
+		return true;
+	}
+
+	/**
+	 * delete entity from cache
+	 * @param schema the entity schema
+	 * @param key the entity key
+	 * @returns true if entity was found and deleted
+	 */
+	delete(schema: ObjectSchema, key: string): boolean {
+		const store = this.#getStore(schema);
+		if (!store) {
+			return false;
+		}
+
+		const existed = store.entities.has(key);
+		store.entities.delete(key);
+
+		if (existed) {
+			this.#notifySubscribers(store, key, undefined);
+		}
+
+		return existed;
+	}
+
+	/**
+	 * delete all entities of a type
+	 * @param schema the entity schema
+	 */
+	deleteType(schema: ObjectSchema): void {
+		const store = this.#getStore(schema);
+		if (!store) {
+			return;
+		}
+
+		const keys = [...store.entities.keys()];
+		store.entities.clear();
+
+		for (const key of keys) {
+			this.#notifySubscribers(store, key, undefined);
+		}
+	}
+
+	/** clear entire cache */
+	clear(): void {
+		for (const [_typeId, store] of this.#stores) {
+			const keys = [...store.entities.keys()];
+			store.entities.clear();
+
+			for (const key of keys) {
+				this.#notifySubscribers(store, key, undefined);
+			}
+		}
+	}
+
+	/**
+	 * subscribe to changes for a specific entity
+	 * @param schema the entity schema
+	 * @param key the entity key
+	 * @param callback called when entity changes
+	 * @returns unsubscribe function
+	 */
+	subscribe<T extends ObjectSchema>(
+		schema: T,
+		key: string,
+		callback: EntitySubscriber<InferOutput<T>>,
+	): () => void {
+		const store = this.#getStore(schema);
+		if (!store) {
+			throw new Error('schema is not registered');
+		}
+
+		let subs = store.subscribers.get(key);
+		if (!subs) {
+			subs = new Set();
+			store.subscribers.set(key, subs);
+		}
+
+		subs.add(callback as EntitySubscriber<unknown>);
+
+		return () => {
+			subs!.delete(callback as EntitySubscriber<unknown>);
+			if (subs!.size === 0) {
+				store.subscribers.delete(key);
+			}
+		};
+	}
+
+	/**
+	 * subscribe to all changes for an entity type
+	 * @param schema the entity schema
+	 * @param callback called when any entity of this type changes
+	 * @returns unsubscribe function
+	 */
+	subscribeType<T extends ObjectSchema>(schema: T, callback: TypeSubscriber<InferOutput<T>>): () => void {
+		const store = this.#getStore(schema);
+		if (!store) {
+			throw new Error('schema is not registered');
+		}
+
+		store.typeSubscribers.add(callback as TypeSubscriber<unknown>);
+
+		return () => {
+			store.typeSubscribers.delete(callback as TypeSubscriber<unknown>);
+		};
+	}
+}

package/lib/types.ts

@@ -0,0 +1,55 @@
+import type { BaseSchema, InferOutput, ObjectSchema } from '@atcute/lexicons/validations';
+
+import { isLiteralSchema, isOptionalSchema } from './predicates.js';
+
+/** entity type identifier, extracted from schema's $type literal */
+export type EntityTypeId = string;
+
+/**
+ * definition for an entity type that can be normalized
+ * @template T the object schema type
+ */
+export interface EntityDefinition<T extends ObjectSchema = ObjectSchema> {
+	/** the schema for this entity type */
+	schema: T;
+	/** extract cache key from entity instance */
+	key: (entity: InferOutput<T>) => string;
+	/**
+	 * merge strategy when entity already exists in cache
+	 * @param existing the currently cached entity
+	 * @param incoming the new entity data
+	 * @returns partial entity with fields to update
+	 */
+	merge?: (existing: InferOutput<T>, incoming: InferOutput<T>) => Partial<InferOutput<T>>;
+}
+
+/** subscriber callback type */
+export type EntitySubscriber<T> = (entity: T | undefined) => void;
+
+/** type-level subscriber callback */
+export type TypeSubscriber<T> = (key: string, entity: T | undefined) => void;
+
+/**
+ * extract the $type literal value from an object schema
+ * @param schema object schema with $type field
+ * @returns the $type string value or undefined
+ */
+export const getTypeIdFromSchema = (schema: ObjectSchema): EntityTypeId | undefined => {
+	const shape = schema.shape;
+	let typeField: BaseSchema | undefined = shape.$type;
+
+	if (typeField === undefined) {
+		return undefined;
+	}
+
+	// unwrap optional
+	if (isOptionalSchema(typeField)) {
+		typeField = typeField.wrapped;
+	}
+
+	if (isLiteralSchema(typeField) && typeof typeField.expected === 'string') {
+		return typeField.expected;
+	}
+
+	return undefined;
+};