@chidchanun/bcp 0.1.0

package/packages/cache/src/index.ts

@@ -0,0 +1,761 @@
+import {
+    AsyncLocalStorage,
+} from "node:async_hooks";
+import {
+    createHash,
+} from "node:crypto";
+
+export type RevalidateValue =
+    | number
+    | false;
+
+export interface CacheOptions {
+    key?: string;
+    revalidate?: RevalidateValue;
+    tags?: string[];
+    paths?: string[];
+}
+
+export interface CacheEntryOptions {
+    revalidate?: RevalidateValue;
+    tags?: string[];
+    paths?: string[];
+}
+
+export interface CacheStats {
+    entries: number;
+    inFlight: number;
+}
+
+interface CacheEntry {
+    value: unknown;
+    expiresAt: number | null;
+    tags: Set<string>;
+    paths: Set<string>;
+}
+
+interface RequestCacheContext {
+    pathname: string | null;
+    memo: Map<string, Promise<unknown>>;
+}
+
+interface CacheRuntimeState {
+    persistentCache: Map<string, CacheEntry>;
+    inFlight: Map<string, Promise<unknown>>;
+    requestStorage: AsyncLocalStorage<RequestCacheContext>;
+}
+
+const CACHE_RUNTIME_SYMBOL =
+    Symbol.for(
+        "bcp.framework.cache.runtime"
+    );
+
+const globalRecord =
+    globalThis as typeof globalThis &
+        Record<PropertyKey, unknown>;
+
+let runtimeState =
+    globalRecord[
+        CACHE_RUNTIME_SYMBOL
+    ] as CacheRuntimeState |
+        undefined;
+
+if (!runtimeState) {
+    runtimeState = {
+        persistentCache:
+            new Map(),
+        inFlight:
+            new Map(),
+        requestStorage:
+            new AsyncLocalStorage<RequestCacheContext>(),
+    };
+
+    globalRecord[
+        CACHE_RUNTIME_SYMBOL
+    ] =
+        runtimeState;
+}
+
+const persistentCache =
+    runtimeState.persistentCache;
+
+const inFlight =
+    runtimeState.inFlight;
+
+const requestStorage =
+    runtimeState.requestStorage;
+
+export function enterRequestCacheContext(
+    pathname: string
+): void {
+    requestStorage.enterWith({
+        pathname:
+            normalizePath(pathname),
+        memo:
+            new Map(),
+    });
+}
+
+export function runWithRequestCacheContext<T>(
+    pathname: string,
+    callback: () => T
+): T {
+    return requestStorage.run(
+        {
+            pathname:
+                normalizePath(pathname),
+            memo:
+                new Map(),
+        },
+        callback
+    );
+}
+
+export function dedupe<
+    Args extends unknown[],
+    Result
+>(
+    fn: (...args: Args) =>
+        Result | Promise<Result>,
+    key?: string
+): (...args: Args) => Promise<Result> {
+    const namespace =
+        key ??
+        fn.name ??
+        "anonymous";
+
+    return async (
+        ...args: Args
+    ): Promise<Result> => {
+        const context =
+            ensureRequestContext();
+
+        const cacheKey =
+            `request:${namespace}:${hashArguments(args)}`;
+
+        const existing =
+            context.memo.get(
+                cacheKey
+            );
+
+        if (existing) {
+            return await existing as Result;
+        }
+
+        const promise =
+            Promise.resolve(
+                fn(...args)
+            );
+
+        context.memo.set(
+            cacheKey,
+            promise
+        );
+
+        try {
+            return await promise;
+        } catch (error) {
+            context.memo.delete(
+                cacheKey
+            );
+            throw error;
+        }
+    };
+}
+
+export function cache<
+    Args extends unknown[],
+    Result
+>(
+    fn: (...args: Args) =>
+        Result | Promise<Result>,
+    options: CacheOptions = {}
+): (...args: Args) => Promise<Result> {
+    const namespace =
+        options.key ??
+        fn.name;
+
+    if (!namespace) {
+        throw new Error(
+            "BCP Framework: cache() requires options.key when the wrapped function has no name."
+        );
+    }
+
+    validateRevalidate(
+        options.revalidate
+    );
+    validateTags(
+        options.tags
+    );
+
+    return async (
+        ...args: Args
+    ): Promise<Result> => {
+        if (
+            options.revalidate === 0
+        ) {
+            return await fn(
+                ...args
+            );
+        }
+
+        const cacheKey =
+            `data:${namespace}:${hashArguments(args)}`;
+
+        const existingEntry =
+            readCacheEntry<Result>(
+                cacheKey
+            );
+
+        if (existingEntry.hit) {
+            return existingEntry.value as Result;
+        }
+
+        const pending =
+            inFlight.get(
+                cacheKey
+            );
+
+        if (pending) {
+            return await pending as Result;
+        }
+
+        const promise =
+            Promise.resolve(
+                fn(...args)
+            );
+
+        inFlight.set(
+            cacheKey,
+            promise
+        );
+
+        try {
+            const value =
+                await promise;
+
+            const currentPath =
+                requestStorage
+                    .getStore()
+                    ?.pathname ??
+                null;
+
+            const paths =
+                new Set(
+                    (
+                        options.paths ?? []
+                    ).map(
+                        normalizePath
+                    )
+                );
+
+            if (currentPath) {
+                paths.add(
+                    currentPath
+                );
+            }
+
+            setCacheEntry(
+                cacheKey,
+                value,
+                {
+                    revalidate:
+                        options.revalidate,
+                    tags:
+                        options.tags,
+                    paths:
+                        Array.from(
+                            paths
+                        ),
+                }
+            );
+
+            return value;
+        } finally {
+            inFlight.delete(
+                cacheKey
+            );
+        }
+    };
+}
+
+export function getCacheEntry<T>(
+    key: string
+): T | undefined {
+    const result =
+        readCacheEntry<T>(
+            key
+        );
+
+    return result.hit
+        ? result.value
+        : undefined;
+}
+
+export function setCacheEntry<T>(
+    key: string,
+    value: T,
+    options: CacheEntryOptions = {}
+): void {
+    validateRevalidate(
+        options.revalidate
+    );
+    validateTags(
+        options.tags
+    );
+
+    if (
+        options.revalidate === 0
+    ) {
+        persistentCache.delete(
+            key
+        );
+        return;
+    }
+
+    const expiresAt =
+        options.revalidate === undefined ||
+        options.revalidate === false
+            ? null
+            : Date.now() +
+                options.revalidate * 1000;
+
+    persistentCache.set(
+        key,
+        {
+            value,
+            expiresAt,
+            tags:
+                new Set(
+                    options.tags ?? []
+                ),
+            paths:
+                new Set(
+                    (
+                        options.paths ?? []
+                    ).map(
+                        normalizePath
+                    )
+                ),
+        }
+    );
+}
+
+export function deleteCacheEntry(
+    key: string
+): boolean {
+    return persistentCache.delete(
+        key
+    );
+}
+
+export function revalidateTag(
+    tag: string
+): number {
+    const normalized =
+        normalizeTag(tag);
+
+    let removed = 0;
+
+    for (
+        const [
+            key,
+            entry,
+        ]
+        of persistentCache
+    ) {
+        if (
+            entry.tags.has(
+                normalized
+            )
+        ) {
+            persistentCache.delete(
+                key
+            );
+            removed++;
+        }
+    }
+
+    return removed;
+}
+
+export function revalidatePath(
+    pathname: string
+): number {
+    const normalized =
+        normalizePath(pathname);
+
+    let removed = 0;
+
+    for (
+        const [
+            key,
+            entry,
+        ]
+        of persistentCache
+    ) {
+        const matches =
+            Array.from(
+                entry.paths
+            ).some(
+                (cachedPath) =>
+                    pathMatches(
+                        cachedPath,
+                        normalized
+                    )
+            );
+
+        if (matches) {
+            persistentCache.delete(
+                key
+            );
+            removed++;
+        }
+    }
+
+    return removed;
+}
+
+export function clearCache(): void {
+    persistentCache.clear();
+    inFlight.clear();
+}
+
+export function getCacheStats(): CacheStats {
+    pruneExpiredEntries();
+
+    return {
+        entries:
+            persistentCache.size,
+        inFlight:
+            inFlight.size,
+    };
+}
+
+export function createRouteCacheKey(
+    kind: "page" | "api" | "navigation",
+    url: string
+): string {
+    return `route:${kind}:${url}`;
+}
+
+export function normalizeRevalidate(
+    value: unknown
+): RevalidateValue | undefined {
+    if (
+        value === undefined
+    ) {
+        return undefined;
+    }
+
+    if (
+        value === false
+    ) {
+        return false;
+    }
+
+    if (
+        typeof value === "number" &&
+        Number.isFinite(value) &&
+        value >= 0
+    ) {
+        return value;
+    }
+
+    throw new Error(
+        "BCP Framework: revalidate must be false or a non-negative number of seconds."
+    );
+}
+
+function readCacheEntry<T>(
+    key: string
+): {
+    hit: boolean;
+    value?: T;
+} {
+    const entry =
+        persistentCache.get(
+            key
+        );
+
+    if (!entry) {
+        return {
+            hit: false,
+        };
+    }
+
+    if (
+        entry.expiresAt !== null &&
+        entry.expiresAt <= Date.now()
+    ) {
+        persistentCache.delete(
+            key
+        );
+        return {
+            hit: false,
+        };
+    }
+
+    return {
+        hit: true,
+        value:
+            entry.value as T,
+    };
+}
+
+function ensureRequestContext(): RequestCacheContext {
+    const existing =
+        requestStorage.getStore();
+
+    if (existing) {
+        return existing;
+    }
+
+    const context:
+        RequestCacheContext = {
+        pathname: null,
+        memo:
+            new Map(),
+    };
+
+    requestStorage.enterWith(
+        context
+    );
+
+    return context;
+}
+
+function pruneExpiredEntries(): void {
+    const now =
+        Date.now();
+
+    for (
+        const [
+            key,
+            entry,
+        ]
+        of persistentCache
+    ) {
+        if (
+            entry.expiresAt !== null &&
+            entry.expiresAt <= now
+        ) {
+            persistentCache.delete(
+                key
+            );
+        }
+    }
+}
+
+function validateRevalidate(
+    value: RevalidateValue | undefined
+): void {
+    normalizeRevalidate(
+        value
+    );
+}
+
+function validateTags(
+    tags: string[] | undefined
+): void {
+    for (
+        const tag
+        of tags ?? []
+    ) {
+        normalizeTag(
+            tag
+        );
+    }
+}
+
+function normalizeTag(
+    value: string
+): string {
+    const normalized =
+        value.trim();
+
+    if (!normalized) {
+        throw new Error(
+            "BCP Framework: cache tags cannot be empty."
+        );
+    }
+
+    return normalized;
+}
+
+function normalizePath(
+    value: string
+): string {
+    let pathname =
+        value.trim();
+
+    if (!pathname) {
+        return "/";
+    }
+
+    try {
+        if (
+            pathname.startsWith(
+                "http://"
+            ) ||
+            pathname.startsWith(
+                "https://"
+            )
+        ) {
+            pathname =
+                new URL(
+                    pathname
+                ).pathname;
+        }
+    } catch {
+        // Fall back to treating the input as a pathname.
+    }
+
+    pathname =
+        pathname.split("?")[0]
+            .split("#")[0];
+
+    if (
+        !pathname.startsWith("/")
+    ) {
+        pathname =
+            `/${pathname}`;
+    }
+
+    if (
+        pathname.length > 1 &&
+        pathname.endsWith("/")
+    ) {
+        pathname =
+            pathname.slice(
+                0,
+                -1
+            );
+    }
+
+    return pathname;
+}
+
+function pathMatches(
+    cachedPath: string,
+    invalidatedPath: string
+): boolean {
+    if (
+        invalidatedPath === "/"
+    ) {
+        return true;
+    }
+
+    return (
+        cachedPath ===
+            invalidatedPath ||
+        cachedPath.startsWith(
+            `${invalidatedPath}/`
+        )
+    );
+}
+
+function hashArguments(
+    args: unknown[]
+): string {
+    return createHash(
+        "sha256"
+    )
+        .update(
+            stableSerialize(
+                args
+            )
+        )
+        .digest(
+            "hex"
+        )
+        .slice(
+            0,
+            24
+        );
+}
+
+function stableSerialize(
+    value: unknown,
+    seen = new WeakSet<object>()
+): string {
+    if (
+        value === null
+    ) {
+        return "null";
+    }
+
+    switch (
+        typeof value
+    ) {
+        case "undefined":
+            return "undefined";
+        case "string":
+            return JSON.stringify(
+                value
+            );
+        case "number":
+        case "boolean":
+            return String(value);
+        case "bigint":
+            return `${value.toString()}n`;
+        case "symbol":
+        case "function":
+            throw new Error(
+                `BCP Framework: cache keys cannot include ${typeof value} values.`
+            );
+        case "object":
+            break;
+        default:
+            return String(value);
+    }
+
+    const object =
+        value as object;
+
+    if (
+        seen.has(object)
+    ) {
+        throw new Error(
+            "BCP Framework: cache keys cannot include circular values."
+        );
+    }
+
+    seen.add(object);
+
+    try {
+        if (
+            value instanceof Date
+        ) {
+            return `Date(${value.toISOString()})`;
+        }
+
+        if (
+            Array.isArray(value)
+        ) {
+            return `[${value.map(
+                (item) =>
+                    stableSerialize(
+                        item,
+                        seen
+                    )
+            ).join(",")}]`;
+        }
+
+        const record =
+            value as Record<string, unknown>;
+
+        return `{${Object.keys(record)
+            .sort()
+            .map(
+                (key) =>
+                    `${JSON.stringify(key)}:${stableSerialize(
+                        record[key],
+                        seen
+                    )}`
+            )
+            .join(",")}}`;
+    } finally {
+        seen.delete(object);
+    }
+}