Expand CultCacheTS toward full CultCache ergonomics

This commit is contained in:
Meta Vens 2026-05-06 04:41:11 +01:00
commit be0a96db7b
23 changed files with 1488 additions and 119 deletions

View file

@ -1,6 +1,12 @@
import { decode, encode } from "@msgpack/msgpack";
import type {
AnyCultCacheDocumentDefinition,
CacheBackingStore,
CultCacheDocumentAccessor,
CultCacheDocumentDefinition,
CultCacheDocumentFormatter,
CultCacheDocumentRegistry,
CultCacheDocumentValue,
CultCacheEnvelope,
CultCacheStoreRegistration,
@ -11,61 +17,193 @@ type StoreRoute = {
mirrors: CacheBackingStore[];
};
type RegisteredDefinition = {
readonly definition: AnyCultCacheDocumentDefinition;
readonly global: boolean;
readonly formatter: CultCacheDocumentFormatter<unknown>;
nameAccessor?: (value: unknown) => string | undefined;
readonly indexAccessors: Map<string, (value: unknown) => string | undefined>;
};
type HydratedEntry = CultCacheEnvelope & {
value: unknown;
};
type BackingStoreTypeReference = string | AnyCultCacheDocumentDefinition;
type AccessorInput = string | ((value: unknown) => unknown);
export class CultCacheBuilder {
readonly #cache = new CultCache();
withDocumentType<TDefinition extends AnyCultCacheDocumentDefinition>(definition: TDefinition): this {
this.#cache.registerDocumentType(definition);
return this;
}
withRegistry(
registry:
| CultCacheDocumentRegistry
| Iterable<AnyCultCacheDocumentDefinition>,
): this {
this.#cache.registerRegistry(registry);
return this;
}
withBackingStore(
store: CacheBackingStore,
...types: BackingStoreTypeReference[]
): this {
this.#cache.addBackingStore(store, ...types);
return this;
}
withGenericStore(store: CacheBackingStore): this {
this.#cache.addGenericBackingStore(store);
return this;
}
build(): CultCache {
return this.#cache;
}
}
export class CultCache {
readonly #definitions = new Map<string, CultCacheDocumentDefinition>();
readonly #entries = new Map<string, CultCacheEnvelope>();
static readonly GLOBAL_KEY = "__global__";
readonly #definitions = new Map<string, RegisteredDefinition>();
readonly #entries = new Map<string, HydratedEntry>();
readonly #typeEntryIds = new Map<string, Set<string>>();
readonly #nameToKeyMaps = new Map<string, Map<string, string>>();
readonly #indexToKeyMaps = new Map<string, Map<string, string>>();
readonly #globalKeys = new Map<string, string>();
readonly #stores: CultCacheStoreRegistration[] = [];
registerDocumentType<TDefinition extends CultCacheDocumentDefinition>(
static builder(): CultCacheBuilder {
return new CultCacheBuilder();
}
registerDocumentType<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
): TDefinition {
const existing = this.#definitions.get(definition.type);
if (existing && existing !== definition) {
if (existing && existing.definition !== definition) {
throw new Error(`CultCache already has a different definition registered for type "${definition.type}".`);
}
this.#definitions.set(definition.type, definition);
const registered = existing ?? {
definition,
global: definition.global === true,
formatter: this.#createFormatter(definition),
nameAccessor: undefined,
indexAccessors: new Map<string, (value: unknown) => string | undefined>(),
};
registered.nameAccessor = definition.name
? this.#compileAccessor(definition.type, "name", definition.name)
: undefined;
registered.indexAccessors.clear();
for (const [indexName, accessor] of this.#enumerateDefinitionIndexes(definition)) {
registered.indexAccessors.set(
indexName,
this.#compileAccessor(definition.type, `index "${indexName}"`, accessor),
);
}
this.#definitions.set(definition.type, registered);
this.#rebuildDefinitionLookups(registered);
return definition;
}
addBackingStore(store: CacheBackingStore, ...types: string[]): void {
registerRegistry(
registry:
| CultCacheDocumentRegistry
| Iterable<AnyCultCacheDocumentDefinition>,
): this {
const definitions = Symbol.iterator in Object(registry) && !("definitions" in Object(registry))
? registry as Iterable<AnyCultCacheDocumentDefinition>
: (registry as CultCacheDocumentRegistry).definitions;
for (const definition of definitions) {
this.registerDocumentType(definition);
}
return this;
}
registerNameLookup<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
accessor: CultCacheDocumentAccessor<CultCacheDocumentValue<TDefinition>>,
): TDefinition {
const registered = this.#requireDefinition(definition);
registered.nameAccessor = this.#compileAccessor(definition.type, "name", accessor);
this.#rebuildNameLookup(registered);
return definition;
}
registerIndex<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
indexName: string,
accessor: CultCacheDocumentAccessor<CultCacheDocumentValue<TDefinition>>,
): TDefinition {
if (!indexName || indexName.trim().length === 0) {
throw new Error(`CultCache index names for type "${definition.type}" must be non-empty.`);
}
const registered = this.#requireDefinition(definition);
registered.indexAccessors.set(
indexName,
this.#compileAccessor(definition.type, `index "${indexName}"`, accessor),
);
this.#rebuildIndexLookup(registered, indexName);
return definition;
}
addBackingStore(
store: CacheBackingStore,
...types: BackingStoreTypeReference[]
): void {
this.#stores.push({
store,
types: [...new Set(types)],
types: [...new Set(types.map((value) => (typeof value === "string" ? value : value.type)))],
});
}
addGenericBackingStore(store: CacheBackingStore): void {
this.addBackingStore(store);
}
async pullAllBackingStores(): Promise<void> {
this.#entries.clear();
this.#resetHydratedState();
for (const registration of this.#stores) {
const entries = await registration.store.pullAll();
for (const entry of entries) {
const definition = this.#definitions.get(entry.type);
if (!definition) {
const registered = this.#definitions.get(entry.type);
if (!registered) {
throw new Error(`No schema is registered for persisted document type "${entry.type}".`);
}
const parsed = definition.schema.parse(entry.payload);
this.#entries.set(this.#entryId(entry.type, entry.key), {
const payload = this.#cloneBytes(entry.payload);
const value = registered.formatter.decode(payload);
this.#applyHydratedEntry(registered, {
...entry,
payload: parsed,
});
payload,
}, value, "pull");
}
}
}
get<TDefinition extends CultCacheDocumentDefinition>(
get<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
key: string,
): CultCacheDocumentValue<TDefinition> | undefined {
this.#requireDefinition(definition);
const entry = this.#entries.get(this.#entryId(definition.type, key));
return entry ? (entry.payload as CultCacheDocumentValue<TDefinition>) : undefined;
return entry ? (entry.value as CultCacheDocumentValue<TDefinition>) : undefined;
}
getRequired<TDefinition extends CultCacheDocumentDefinition>(
getRequired<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
key: string,
): CultCacheDocumentValue<TDefinition> {
@ -77,32 +215,115 @@ export class CultCache {
return value;
}
getAll<TDefinition extends CultCacheDocumentDefinition>(
getGlobal<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
): CultCacheDocumentValue<TDefinition> | undefined {
const registered = this.#requireDefinition(definition);
if (!registered.global) {
throw new Error(`CultCache document type "${definition.type}" is not marked as global.`);
}
const globalKey = this.#globalKeys.get(definition.type);
return globalKey ? this.get(definition, globalKey) : undefined;
}
getRequiredGlobal<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
): CultCacheDocumentValue<TDefinition> {
const value = this.getGlobal(definition);
if (value === undefined) {
throw new Error(`CultCache has no global "${definition.type}" document.`);
}
return value;
}
getAll<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
): CultCacheDocumentValue<TDefinition>[] {
this.#requireDefinition(definition);
const values: CultCacheDocumentValue<TDefinition>[] = [];
const entryIds = this.#typeEntryIds.get(definition.type);
for (const entry of this.#entries.values()) {
if (entry.type === definition.type) {
values.push(entry.payload as CultCacheDocumentValue<TDefinition>);
if (!entryIds) {
return values;
}
for (const entryId of entryIds) {
const entry = this.#entries.get(entryId);
if (entry) {
values.push(entry.value as CultCacheDocumentValue<TDefinition>);
}
}
return values;
}
async put<TDefinition extends CultCacheDocumentDefinition>(
getKeyByName<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
name: string,
): string | undefined {
const registered = this.#requireDefinition(definition);
if (!registered.nameAccessor) {
return undefined;
}
return this.#nameToKeyMaps.get(definition.type)?.get(name);
}
getIdByName<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
name: string,
): string | undefined {
return this.getKeyByName(definition, name);
}
getByName<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
name: string,
): CultCacheDocumentValue<TDefinition> | undefined {
const key = this.getKeyByName(definition, name);
return key ? this.get(definition, key) : undefined;
}
getKeyByIndex<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
indexName: string,
value: string,
): string | undefined {
this.#requireDefinition(definition);
return this.#indexToKeyMaps.get(this.#indexId(definition.type, indexName))?.get(value);
}
getIdByIndex<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
indexName: string,
value: string,
): string | undefined {
return this.getKeyByIndex(definition, indexName, value);
}
getByIndex<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
indexName: string,
value: string,
): CultCacheDocumentValue<TDefinition> | undefined {
const key = this.getKeyByIndex(definition, indexName, value);
return key ? this.get(definition, key) : undefined;
}
async put<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
key: string,
value: CultCacheDocumentValue<TDefinition>,
): Promise<CultCacheDocumentValue<TDefinition>> {
this.#requireDefinition(definition);
const parsed = definition.schema.parse(value) as CultCacheDocumentValue<TDefinition>;
const registered = this.#requireDefinition(definition);
const payload = registered.formatter.encode(value);
const parsed = registered.formatter.decode(payload) as CultCacheDocumentValue<TDefinition>;
const entry: CultCacheEnvelope = {
key,
type: definition.type,
payload: parsed,
payload: this.#cloneBytes(payload),
storedAt: new Date().toISOString(),
};
@ -111,13 +332,32 @@ export class CultCache {
throw new Error(`No backing store is registered for document type "${definition.type}".`);
}
if (registered.global) {
const existingGlobalKey = this.#globalKeys.get(definition.type);
if (existingGlobalKey && existingGlobalKey !== key) {
await this.delete(definition, existingGlobalKey);
}
}
await route.primary.push(entry);
await Promise.all(route.mirrors.map(async (mirror) => mirror.push(entry)));
this.#entries.set(this.#entryId(definition.type, key), entry);
this.#applyHydratedEntry(registered, entry, parsed, "put");
return parsed;
}
async update<TDefinition extends CultCacheDocumentDefinition>(
async putGlobal<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
value: CultCacheDocumentValue<TDefinition>,
): Promise<CultCacheDocumentValue<TDefinition>> {
const registered = this.#requireDefinition(definition);
if (!registered.global) {
throw new Error(`CultCache document type "${definition.type}" is not marked as global.`);
}
return this.put(definition, CultCache.GLOBAL_KEY, value);
}
async update<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
key: string,
updater: (
@ -128,11 +368,21 @@ export class CultCache {
return this.put(definition, key, updater(current));
}
async delete<TDefinition extends CultCacheDocumentDefinition>(
async updateGlobal<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
updater: (
current: CultCacheDocumentValue<TDefinition> | undefined,
) => CultCacheDocumentValue<TDefinition>,
): Promise<CultCacheDocumentValue<TDefinition>> {
const current = this.getGlobal(definition);
return this.putGlobal(definition, updater(current));
}
async delete<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
key: string,
): Promise<boolean> {
this.#requireDefinition(definition);
const registered = this.#requireDefinition(definition);
const entry = this.#entries.get(this.#entryId(definition.type, key));
if (!entry) {
return false;
@ -143,25 +393,110 @@ export class CultCache {
throw new Error(`No backing store is registered for document type "${definition.type}".`);
}
await route.primary.delete(entry);
await Promise.all(route.mirrors.map(async (mirror) => mirror.delete(entry)));
this.#entries.delete(this.#entryId(definition.type, key));
const envelope = this.#toEnvelope(entry);
await route.primary.delete(envelope);
await Promise.all(route.mirrors.map(async (mirror) => mirror.delete(envelope)));
this.#removeHydratedEntry(registered, entry);
return true;
}
snapshot(): CultCacheEnvelope[] {
return [...this.#entries.values()].map((entry) => structuredClone(entry));
async deleteGlobal<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
): Promise<boolean> {
const registered = this.#requireDefinition(definition);
if (!registered.global) {
throw new Error(`CultCache document type "${definition.type}" is not marked as global.`);
}
const globalKey = this.#globalKeys.get(definition.type);
return globalKey ? this.delete(definition, globalKey) : false;
}
#requireDefinition<TDefinition extends CultCacheDocumentDefinition>(
snapshot(): CultCacheEnvelope[] {
return [...this.#entries.values()].map((entry) => this.#toEnvelope(entry));
}
#createFormatter(definition: AnyCultCacheDocumentDefinition): CultCacheDocumentFormatter<unknown> {
const userFormatter = definition.formatter ?? {
encode: (value: unknown) => encode(value),
decode: (payload: Uint8Array) => decode(payload),
};
return {
encode: (value: unknown) => {
const parsed = definition.schema.parse(value);
return this.#cloneBytes(userFormatter.encode(parsed));
},
decode: (payload: Uint8Array) => {
const decoded = userFormatter.decode(this.#cloneBytes(payload));
return definition.schema.parse(decoded);
},
};
}
#enumerateDefinitionIndexes(
definition: AnyCultCacheDocumentDefinition,
): Array<[string, AccessorInput]> {
if (!definition.indexes) {
return [];
}
if (Array.isArray(definition.indexes)) {
return definition.indexes.map((index) => [index.name, index.accessor as AccessorInput]);
}
return Object.entries(definition.indexes) as Array<[string, AccessorInput]>;
}
#compileAccessor(
type: string,
label: string,
accessor: AccessorInput,
): (value: unknown) => string | undefined {
if (typeof accessor === "function") {
return (value: unknown) => this.#normalizeIndexValue(type, label, accessor(value));
}
return (value: unknown) => {
if (value === null || typeof value !== "object") {
return undefined;
}
const fieldValue = (value as Record<string, unknown>)[accessor];
return this.#normalizeIndexValue(type, `${label} field "${accessor}"`, fieldValue);
};
}
#normalizeIndexValue(
type: string,
label: string,
value: unknown,
): string | undefined {
if (value === undefined || value === null) {
return undefined;
}
switch (typeof value) {
case "string":
return value;
case "number":
case "boolean":
case "bigint":
return String(value);
default:
throw new Error(`CultCache ${label} accessor for type "${type}" produced a non-scalar value.`);
}
}
#requireDefinition<TDefinition extends AnyCultCacheDocumentDefinition>(
definition: TDefinition,
): TDefinition {
): RegisteredDefinition {
const registered = this.#definitions.get(definition.type);
if (!registered || registered !== definition) {
if (!registered || registered.definition !== definition) {
throw new Error(`CultCache document type "${definition.type}" is not registered on this cache instance.`);
}
return definition;
return registered;
}
#resolveRoute(type: string): StoreRoute {
@ -180,7 +515,203 @@ export class CultCache {
};
}
#applyHydratedEntry(
registered: RegisteredDefinition,
entry: CultCacheEnvelope,
value: unknown,
source: "pull" | "put",
): void {
const entryId = this.#entryId(entry.type, entry.key);
const existing = this.#entries.get(entryId);
if (existing) {
this.#removeHydratedEntry(registered, existing);
}
if (registered.global) {
const currentGlobalKey = this.#globalKeys.get(entry.type);
if (currentGlobalKey && currentGlobalKey !== entry.key) {
throw new Error(
source === "pull"
? `CultCache global document type "${entry.type}" has multiple persisted entries.`
: `CultCache global document type "${entry.type}" already has a different key "${currentGlobalKey}".`,
);
}
}
const hydrated: HydratedEntry = {
...entry,
payload: this.#cloneBytes(entry.payload),
value,
};
this.#entries.set(entryId, hydrated);
this.#getOrCreateTypeEntrySet(entry.type).add(entryId);
if (registered.global) {
this.#globalKeys.set(entry.type, entry.key);
}
if (registered.nameAccessor) {
const name = registered.nameAccessor(value);
if (name !== undefined) {
this.#getOrCreateNameMap(entry.type).set(name, entry.key);
}
}
for (const [indexName, accessor] of registered.indexAccessors) {
const indexValue = accessor(value);
if (indexValue !== undefined) {
this.#getOrCreateIndexMap(entry.type, indexName).set(indexValue, entry.key);
}
}
}
#removeHydratedEntry(
registered: RegisteredDefinition,
entry: HydratedEntry,
): void {
const entryId = this.#entryId(entry.type, entry.key);
this.#entries.delete(entryId);
const typeEntryIds = this.#typeEntryIds.get(entry.type);
if (typeEntryIds) {
typeEntryIds.delete(entryId);
if (typeEntryIds.size === 0) {
this.#typeEntryIds.delete(entry.type);
}
}
if (registered.global && this.#globalKeys.get(entry.type) === entry.key) {
this.#globalKeys.delete(entry.type);
}
if (registered.nameAccessor) {
const name = registered.nameAccessor(entry.value);
if (name !== undefined) {
this.#nameToKeyMaps.get(entry.type)?.delete(name);
}
}
for (const [indexName, accessor] of registered.indexAccessors) {
const value = accessor(entry.value);
if (value !== undefined) {
this.#indexToKeyMaps.get(this.#indexId(entry.type, indexName))?.delete(value);
}
}
}
#rebuildDefinitionLookups(registered: RegisteredDefinition): void {
this.#rebuildNameLookup(registered);
for (const indexName of registered.indexAccessors.keys()) {
this.#rebuildIndexLookup(registered, indexName);
}
}
#rebuildNameLookup(registered: RegisteredDefinition): void {
this.#nameToKeyMaps.delete(registered.definition.type);
if (!registered.nameAccessor) {
return;
}
const map = this.#getOrCreateNameMap(registered.definition.type);
for (const entry of this.#entriesForType(registered.definition.type)) {
const name = registered.nameAccessor(entry.value);
if (name !== undefined) {
map.set(name, entry.key);
}
}
}
#rebuildIndexLookup(registered: RegisteredDefinition, indexName: string): void {
const lookupId = this.#indexId(registered.definition.type, indexName);
this.#indexToKeyMaps.delete(lookupId);
const accessor = registered.indexAccessors.get(indexName);
if (!accessor) {
return;
}
const map = this.#getOrCreateIndexMap(registered.definition.type, indexName);
for (const entry of this.#entriesForType(registered.definition.type)) {
const value = accessor(entry.value);
if (value !== undefined) {
map.set(value, entry.key);
}
}
}
#entriesForType(type: string): HydratedEntry[] {
const entryIds = this.#typeEntryIds.get(type);
if (!entryIds) {
return [];
}
const entries: HydratedEntry[] = [];
for (const entryId of entryIds) {
const entry = this.#entries.get(entryId);
if (entry) {
entries.push(entry);
}
}
return entries;
}
#getOrCreateTypeEntrySet(type: string): Set<string> {
let set = this.#typeEntryIds.get(type);
if (!set) {
set = new Set<string>();
this.#typeEntryIds.set(type, set);
}
return set;
}
#getOrCreateNameMap(type: string): Map<string, string> {
let map = this.#nameToKeyMaps.get(type);
if (!map) {
map = new Map<string, string>();
this.#nameToKeyMaps.set(type, map);
}
return map;
}
#getOrCreateIndexMap(type: string, indexName: string): Map<string, string> {
const lookupId = this.#indexId(type, indexName);
let map = this.#indexToKeyMaps.get(lookupId);
if (!map) {
map = new Map<string, string>();
this.#indexToKeyMaps.set(lookupId, map);
}
return map;
}
#toEnvelope(entry: HydratedEntry): CultCacheEnvelope {
return {
key: entry.key,
type: entry.type,
payload: this.#cloneBytes(entry.payload),
storedAt: entry.storedAt,
};
}
#resetHydratedState(): void {
this.#entries.clear();
this.#typeEntryIds.clear();
this.#nameToKeyMaps.clear();
this.#indexToKeyMaps.clear();
this.#globalKeys.clear();
}
#entryId(type: string, key: string): string {
return `${type}::${key}`;
}
#indexId(type: string, indexName: string): string {
return `${type}::${indexName}`;
}
#cloneBytes(payload: Uint8Array): Uint8Array {
return new Uint8Array(payload);
}
}

View file

@ -1,6 +1,6 @@
import type { ZodType } from "zod";
import type { CultCacheDocumentDefinition } from "./types";
import type { AnyCultCacheDocumentDefinition, CultCacheDocumentDefinition, CultCacheDocumentRegistry } from "./types";
export function defineDocumentType<TSchema extends ZodType>(
definition: CultCacheDocumentDefinition<TSchema>,
@ -9,5 +9,36 @@ export function defineDocumentType<TSchema extends ZodType>(
throw new Error("CultCache document types must declare a non-empty type.");
}
return definition;
if (definition.name !== undefined && typeof definition.name !== "string" && typeof definition.name !== "function") {
throw new Error(`CultCache document type "${definition.type}" declares an invalid name accessor.`);
}
if (Array.isArray(definition.indexes)) {
const seen = new Set<string>();
for (const index of definition.indexes) {
if (!index.name || index.name.trim().length === 0) {
throw new Error(`CultCache document type "${definition.type}" declares an index with an empty name.`);
}
if (seen.has(index.name)) {
throw new Error(`CultCache document type "${definition.type}" declares duplicate index "${index.name}".`);
}
seen.add(index.name);
}
} else if (definition.indexes) {
for (const name of Object.keys(definition.indexes)) {
if (!name || name.trim().length === 0) {
throw new Error(`CultCache document type "${definition.type}" declares an index with an empty name.`);
}
}
}
return Object.freeze({ ...definition });
}
export function defineDocumentRegistry<
TDefinitions extends readonly AnyCultCacheDocumentDefinition[],
>(...definitions: TDefinitions): CultCacheDocumentRegistry<TDefinitions> {
return Object.freeze({
definitions: Object.freeze([...definitions]) as TDefinitions,
});
}

View file

@ -1,11 +1,18 @@
export { CultCache } from "./cult-cache";
export { defineDocumentType } from "./document";
export { CultCache, CultCacheBuilder } from "./cult-cache";
export { defineDocumentRegistry, defineDocumentType } from "./document";
export { SingleFileMessagePackBackingStore } from "./single-file-messagepack-backing-store";
export type {
AnyCultCacheDocumentDefinition,
CacheBackingStore,
CultCacheDocumentAccessor,
CultCacheDocumentDefinition,
CultCacheDocumentFieldName,
CultCacheDocumentFormatter,
CultCacheDocumentIndexDefinition,
CultCacheDocumentRegistry,
CultCacheDocumentValue,
CultCacheEnvelope,
CultCacheIndexScalar,
CultCacheStoreRegistration,
PushAllOptions,
} from "./types";

View file

@ -9,7 +9,7 @@ import type { CacheBackingStore, CultCacheEnvelope, PushAllOptions } from "./typ
const envelopeSchema = z.object({
key: z.string().min(1),
type: z.string().min(1),
payload: z.unknown(),
payload: z.instanceof(Uint8Array),
storedAt: z.string().min(1),
});

View file

@ -1,18 +1,51 @@
import { z, type ZodType } from "zod";
export type CultCacheIndexScalar = string | number | boolean | bigint;
export type CultCacheDocumentFieldName<TValue> = TValue extends object ? Extract<keyof TValue, string> : never;
export type CultCacheDocumentAccessor<TValue> =
| CultCacheDocumentFieldName<TValue>
| ((value: TValue) => CultCacheIndexScalar | null | undefined);
export interface CultCacheDocumentFormatter<TValue> {
encode(value: TValue): Uint8Array;
decode(payload: Uint8Array): TValue;
}
export interface CultCacheDocumentIndexDefinition<TValue> {
name: string;
accessor: CultCacheDocumentAccessor<TValue>;
}
export interface CultCacheDocumentDefinition<TSchema extends ZodType = ZodType> {
type: string;
schema: TSchema;
schemaName?: string;
global?: boolean;
name?: CultCacheDocumentAccessor<z.infer<TSchema>>;
indexes?:
| Readonly<Record<string, CultCacheDocumentAccessor<z.infer<TSchema>>>>
| readonly CultCacheDocumentIndexDefinition<z.infer<TSchema>>[];
formatter?: CultCacheDocumentFormatter<z.infer<TSchema>>;
}
export type CultCacheDocumentValue<TDefinition extends CultCacheDocumentDefinition> = z.infer<
TDefinition["schema"]
>;
export type AnyCultCacheDocumentDefinition = CultCacheDocumentDefinition<any>;
export interface CultCacheDocumentRegistry<
TDefinitions extends readonly AnyCultCacheDocumentDefinition[] = readonly AnyCultCacheDocumentDefinition[],
> {
readonly definitions: TDefinitions;
}
export interface CultCacheEnvelope {
key: string;
type: string;
payload: unknown;
payload: Uint8Array;
storedAt: string;
}