@asteby/metacore-runtime-react 9.2.0 → 10.0.0

package/src/metadata-cache.ts

@@ -14,6 +14,31 @@ export interface MetadataApiClient {
     get: (url: string, config?: any) => Promise<{ data: any }>
 }
 
+/**
+ * Predicate matching a cache key against an addon. The default
+ * implementation (see {@link defaultAddonKeyMatcher}) treats `addonKey`
+ * itself plus any key beginning with `${addonKey}.`, `${addonKey}:` or
+ * `${addonKey}/` as belonging to the addon. Hosts that namespace their
+ * `model` strings differently can pass a custom matcher to
+ * {@link MetadataCacheState.invalidateAddon}.
+ */
+export type AddonKeyMatcher = (cacheKey: string, addonKey: string) => boolean
+
+/**
+ * Default matcher used by {@link MetadataCacheState.invalidateAddon}.
+ * Mirrors the convention used by the kernel installer when it scopes
+ * model metadata under an addon's key.
+ */
+export function defaultAddonKeyMatcher(cacheKey: string, addonKey: string): boolean {
+    if (!addonKey) return false
+    if (cacheKey === addonKey) return true
+    return (
+        cacheKey.startsWith(`${addonKey}.`) ||
+        cacheKey.startsWith(`${addonKey}:`) ||
+        cacheKey.startsWith(`${addonKey}/`)
+    )
+}
+
 interface MetadataCacheState {
     cache: Record<string, TableMetadata>
     modalCache: Record<string, TableMetadata>
@@ -26,6 +51,26 @@ interface MetadataCacheState {
     hasMetadata: (key: string) => boolean
     hasModalMetadata: (key: string) => boolean
     prefetchAll: (api: MetadataApiClient) => Promise<void>
+    /**
+     * Remove cached entries belonging to a specific addon. Used by the
+     * hot-swap subscriber when the kernel announces a manifest change.
+     *
+     * Returns the number of entries removed across both caches, which is
+     * useful for tests and observability — `0` means the cache had nothing
+     * to flush (the addon either hadn't been hit yet or uses a key
+     * convention the default matcher doesn't recognise; pass a custom
+     * `matcher` if your host namespaces differently).
+     *
+     * Also resets `prefetched` to `false` so the next mount re-runs
+     * `prefetchAll()` and the `metadataVersion` is allowed to advance to
+     * the kernel's freshly-bumped hash.
+     */
+    invalidateAddon: (addonKey: string, matcher?: AddonKeyMatcher) => number
+    /**
+     * Remove every cached entry. Heavier hammer for hosts that prefer a
+     * blanket flush on hot-swap rather than per-addon scoping.
+     */
+    clearAll: () => void
 }
 
 export const useMetadataCache = create<MetadataCacheState>()(
@@ -54,6 +99,47 @@ export const useMetadataCache = create<MetadataCacheState>()(
             hasMetadata: (key: string) => key in get().cache,
             hasModalMetadata: (key: string) => key in get().modalCache,
 
+            invalidateAddon: (addonKey: string, matcher = defaultAddonKeyMatcher) => {
+                if (!addonKey) return 0
+                let removed = 0
+                const state = get()
+                const nextCache: Record<string, TableMetadata> = {}
+                for (const [key, value] of Object.entries(state.cache)) {
+                    if (matcher(key, addonKey)) {
+                        removed += 1
+                        continue
+                    }
+                    nextCache[key] = value
+                }
+                const nextModalCache: Record<string, TableMetadata> = {}
+                for (const [key, value] of Object.entries(state.modalCache)) {
+                    if (matcher(key, addonKey)) {
+                        removed += 1
+                        continue
+                    }
+                    nextModalCache[key] = value
+                }
+                if (removed === 0) return 0
+                set({
+                    cache: nextCache,
+                    modalCache: nextModalCache,
+                    // Allow prefetchAll() to re-run so we pick up the new
+                    // metadataVersion the kernel emits alongside the
+                    // bumped manifest.
+                    prefetched: false,
+                })
+                return removed
+            },
+
+            clearAll: () => {
+                set({
+                    cache: {},
+                    modalCache: {},
+                    metadataVersion: '',
+                    prefetched: false,
+                })
+            },
+
             prefetchAll: async (api: MetadataApiClient) => {
                 if (get().prefetched) return
                 try {