@adobe/data 0.1.2

package/cache/blob-store.d.ts

@@ -0,0 +1,94 @@
+import { type FromSchema } from "../core/schema.js";
+export declare const BlobRefSchema: {
+    readonly oneOf: readonly [{
+        readonly required: readonly ["remoteBlobRef"];
+        readonly properties: {
+            readonly remoteBlobRef: {
+                readonly type: "string";
+                readonly pattern: "http.*";
+            };
+        };
+        readonly additionalProperties: false;
+    }, {
+        readonly required: readonly ["localBlobRef"];
+        readonly properties: {
+            readonly localBlobRef: {
+                readonly type: "string";
+            };
+        };
+        readonly additionalProperties: false;
+    }];
+};
+/**
+ * Represents a reference to a blob as a plain JSON object.
+ * Do NOT create this type directly.
+ * Use the BlobStore to create and manage blob references.
+ */
+export type BlobRef = FromSchema<typeof BlobRefSchema>;
+export declare function isBlobRef(value: unknown): value is BlobRef;
+/**
+ * Defined as a symbol because we only want it used by internal code like DataCache.
+ */
+export declare const hasBlobInternalDoNotUse: unique symbol;
+/**
+ * A blob store is a service that can efficiently store blobs across sessions and retrieve them using the browsers Cache api.
+ */
+export interface BlobStore {
+    /**
+     * Stores a blob and returns a reference to it.
+     * Blob references are based upon the content and type of the Blob.
+     * If an equivalent blob is stored, an equivalent reference will be returned every time.
+     */
+    getRef(b: Blob | string): Promise<BlobRef>;
+    /**
+     * Gets a blob from the blob store or null if it is not available.
+     */
+    getBlob(r: BlobRef | null): Promise<Blob | null>;
+    /**
+     * Checks if the blob is still available.
+     */
+    hasBlob(r: BlobRef | null): Promise<boolean>;
+    /**
+     * Do NOT use this directly, use useBorrowUrl hook instead as it will automatically return the url when the component unmounts.
+     */
+    borrowUrl(r: BlobRef | null): Promise<string | null>;
+    /**
+     * Return a url that was previously borrowed from borrowUrl.
+     * Failure to do so may result in memory leaking.
+     * @param url The url provided by borrowUrl.
+     */
+    returnUrl(url: string | null): void;
+    /**
+     * Removes a blob from the store.
+     */
+    releaseBlob(r: BlobRef): Promise<void>;
+    /**
+     * Creates a new remote blob ref. The url must start with http.
+     * This should only be called if the remote content is persistent and immutable.
+     */
+    createRemoteBlobRef(url: string): BlobRef;
+    /**
+     * TEST ONLY: Gets the current borrow count for a blob reference.
+     * This should only be used in tests to verify reference counting behavior.
+     * @param r The blob reference to check
+     * @returns The number of times the blob reference has been borrowed, or 0 if not borrowed
+     */
+    _testGetBorrowCount(r: BlobRef): number;
+}
+/**
+ * Creates a new blob store instance.
+ */
+export declare function createBlobStore(): Promise<{
+    readonly getRef: (blob: Blob | string) => Promise<BlobRef>;
+    readonly getBlob: (r?: BlobRef | null) => Promise<Blob | null>;
+    readonly hasBlob: (r: BlobRef) => Promise<boolean>;
+    readonly borrowUrl: (r: BlobRef) => Promise<string | null>;
+    readonly returnUrl: (url: string | null) => void;
+    readonly releaseBlob: (r: BlobRef) => Promise<void>;
+    readonly createRemoteBlobRef: (url: string) => BlobRef;
+    readonly _testGetBorrowCount: (r: BlobRef) => number;
+}>;
+/**
+ * The global blob store that can be used to store and retrieve blobs.
+ */
+export declare const blobStore: BlobStore;

package/cache/blob-store.js

@@ -0,0 +1,191 @@
+/*MIT License
+
+© Copyright 2025 Adobe. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.*/
+import { getManagedPersistentCache } from "./get-persistent-cache.js";
+import { blobToHash } from "./functions/hashing/blob-to-hash.js";
+import { preventParallelExecution } from "./functions/prevent-parallel-execution.js";
+const remoteUrlPrefix = "http";
+const RemoteUrlSchema = {
+    type: "string",
+    pattern: `${remoteUrlPrefix}.*`,
+};
+const RemoteBlobRefSchema = {
+    required: ["remoteBlobRef"],
+    properties: {
+        remoteBlobRef: RemoteUrlSchema,
+    },
+    additionalProperties: false,
+};
+const LocalBlobRefSchema = {
+    required: ["localBlobRef"],
+    properties: {
+        localBlobRef: { type: "string" },
+    },
+    additionalProperties: false,
+};
+export const BlobRefSchema = {
+    oneOf: [RemoteBlobRefSchema, LocalBlobRefSchema],
+};
+function isRemoteBlobRef(ref) {
+    const maybe = ref;
+    return typeof maybe?.remoteBlobRef === "string";
+}
+function isLocalBlobRef(ref) {
+    const maybe = ref;
+    return typeof maybe?.localBlobRef === "string";
+}
+export function isBlobRef(value) {
+    return isRemoteBlobRef(value) || isLocalBlobRef(value);
+}
+function isRemoteUrl(url) {
+    return url.startsWith(remoteUrlPrefix);
+}
+function toRequest(ref) {
+    return new Request(`${window.location.origin}/${ref.localBlobRef}`);
+}
+/**
+ * Defined as a symbol because we only want it used by internal code like DataCache.
+ */
+export const hasBlobInternalDoNotUse = Symbol("hasBlob");
+/**
+ * Creates a new blob store instance.
+ */
+export async function createBlobStore() {
+    const cache = await getManagedPersistentCache("blobstore", {
+        maximumMemoryEntries: 10,
+        maximumStorageEntries: 1000,
+    });
+    // Track borrowed URLs and their reference counts
+    const borrowedUrls = new Map();
+    // Reverse mapping for O(1) lookup
+    const urlToKey = new Map();
+    async function getRef(blob) {
+        if (typeof blob === "string") {
+            //  if this is not a remote url, then we can assume it is a data url and fetch the blob from it.
+            blob = await (await fetch(blob)).blob();
+        }
+        const ref = {
+            localBlobRef: await blobToHash(blob),
+        };
+        const request = toRequest(ref);
+        const response = new Response(blob);
+        await cache.put(request, response);
+        return ref;
+    }
+    async function hasBlob(r) {
+        if (isRemoteBlobRef(r)) {
+            return true;
+        }
+        const response = await cache.match(toRequest(r));
+        return response !== undefined;
+    }
+    async function getBlob(r) {
+        if (!r) {
+            return null;
+        }
+        const response = await (isRemoteBlobRef(r)
+            ? fetch(r.remoteBlobRef)
+            : cache.match(toRequest(r)));
+        if (!response) {
+            return null;
+        }
+        if (!response.ok) {
+            // this should only happen with remote urls. local blob responses are always ok.
+            throw new Error(response.statusText);
+        }
+        return response.blob();
+    }
+    async function releaseBlob(r) {
+        if (isLocalBlobRef(r)) {
+            cache.delete(toRequest(r));
+        }
+    }
+    /**
+     * prevent parallel execution to avoid race condition in borrowUrl while awaiting getBlob
+     */
+    const borrowUrlInternalNoIncrement = preventParallelExecution(async (key, r) => {
+        if (isRemoteBlobRef(r)) {
+            return { url: r.remoteBlobRef, count: 0 };
+        }
+        const blob = await getBlob(r);
+        if (!blob) {
+            return null;
+        }
+        const url = URL.createObjectURL(blob);
+        const existing = { url, count: 0 };
+        borrowedUrls.set(key, existing);
+        urlToKey.set(url, key);
+        return existing;
+    });
+    async function borrowUrl(r) {
+        const key = JSON.stringify(r);
+        const existing = borrowedUrls.get(key) ?? await borrowUrlInternalNoIncrement(key, r);
+        if (!existing) {
+            return null;
+        }
+        existing.count++;
+        return existing.url;
+    }
+    function returnUrl(url) {
+        if (!url) {
+            return;
+        }
+        const key = urlToKey.get(url);
+        if (key) {
+            const entry = borrowedUrls.get(key);
+            if (entry) {
+                entry.count--;
+                if (entry.count <= 0) {
+                    borrowedUrls.delete(key);
+                    urlToKey.delete(url);
+                    if (!isRemoteUrl(url)) {
+                        URL.revokeObjectURL(url);
+                    }
+                }
+            }
+        }
+    }
+    function createRemoteBlobRef(url) {
+        if (!isRemoteUrl(url)) {
+            throw new Error(`Invalid url, expected to start with (${remoteUrlPrefix}): ${url}`);
+        }
+        return { remoteBlobRef: url };
+    }
+    function _testGetBorrowCount(r) {
+        const key = JSON.stringify(r);
+        return borrowedUrls.get(key)?.count ?? 0;
+    }
+    return {
+        getRef,
+        getBlob,
+        hasBlob,
+        borrowUrl,
+        returnUrl,
+        releaseBlob,
+        createRemoteBlobRef,
+        _testGetBorrowCount,
+    };
+}
+/**
+ * The global blob store that can be used to store and retrieve blobs.
+ */
+export const blobStore = await createBlobStore();
+//# sourceMappingURL=blob-store.js.map

package/cache/blob-store.js.map

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

package/cache/blob-store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/cache/blob-store.test.js

@@ -0,0 +1,142 @@
+/*MIT License
+
+© Copyright 2025 Adobe. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.*/
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createBlobStore } from "./blob-store.js";
+describe("blobStore", () => {
+    // Mock URL.createObjectURL and URL.revokeObjectURL
+    const mockCreateObjectURL = vi.fn((blob) => `blob:${Math.random()}`);
+    const mockRevokeObjectURL = vi.fn();
+    let testBlobStore;
+    let createdUrl;
+    beforeEach(async () => {
+        // Setup URL mock functions
+        const originalCreateObjectURL = URL.createObjectURL;
+        const originalRevokeObjectURL = URL.revokeObjectURL;
+        // Ensure we create a non-http URL
+        mockCreateObjectURL.mockImplementation((blob) => {
+            createdUrl = `blob:${Math.random()}`;
+            return createdUrl;
+        });
+        URL.createObjectURL = mockCreateObjectURL;
+        URL.revokeObjectURL = mockRevokeObjectURL;
+        // Clear mock call history
+        mockCreateObjectURL.mockClear();
+        mockRevokeObjectURL.mockClear();
+        testBlobStore = await createBlobStore();
+        return () => {
+            URL.createObjectURL = originalCreateObjectURL;
+            URL.revokeObjectURL = originalRevokeObjectURL;
+        };
+    });
+    afterEach(() => {
+        // Clean up any remaining borrowed URLs
+        mockCreateObjectURL.mockReset();
+        mockRevokeObjectURL.mockReset();
+    });
+    describe("URL reference counting", () => {
+        it("should reuse the same URL for multiple borrows of the same blob", async () => {
+            // Create a test blob
+            const testBlob = new Blob(["test"], { type: "text/plain" });
+            const blobRef = await testBlobStore.getRef(testBlob);
+            // Borrow the URL multiple times
+            const url1 = await testBlobStore.borrowUrl(blobRef);
+            const url2 = await testBlobStore.borrowUrl(blobRef);
+            const url3 = await testBlobStore.borrowUrl(blobRef);
+            expect(url1).toBeTruthy();
+            expect(url1).toBe(url2);
+            expect(url2).toBe(url3);
+            expect(url1).toMatch(/^blob:/); // Verify it's a blob URL
+            // createObjectURL should only be called once
+            expect(mockCreateObjectURL).toHaveBeenCalledTimes(1);
+            // Clean up
+            testBlobStore.returnUrl(url1);
+            testBlobStore.returnUrl(url2);
+            testBlobStore.returnUrl(url3);
+        });
+        it("should only revoke URL when all references are returned", async () => {
+            const testBlob = new Blob(["test"], { type: "text/plain" });
+            const blobRef = await testBlobStore.getRef(testBlob);
+            // Borrow the URL three times
+            const url1 = await testBlobStore.borrowUrl(blobRef);
+            const url2 = await testBlobStore.borrowUrl(blobRef);
+            const url3 = await testBlobStore.borrowUrl(blobRef);
+            expect(url1).toMatch(/^blob:/); // Verify it's a blob URL
+            // Return URLs one by one
+            testBlobStore.returnUrl(url1);
+            expect(mockRevokeObjectURL).not.toHaveBeenCalled();
+            testBlobStore.returnUrl(url2);
+            expect(mockRevokeObjectURL).not.toHaveBeenCalled();
+            testBlobStore.returnUrl(url3);
+            expect(mockRevokeObjectURL).toHaveBeenCalledTimes(1);
+            expect(mockRevokeObjectURL).toHaveBeenCalledWith(createdUrl);
+        });
+        it("should handle remote URLs correctly", async () => {
+            const remoteRef = testBlobStore.createRemoteBlobRef("http://example.com/image.jpg");
+            // Borrow remote URL multiple times
+            const url1 = await testBlobStore.borrowUrl(remoteRef);
+            const url2 = await testBlobStore.borrowUrl(remoteRef);
+            expect(url1).toBe("http://example.com/image.jpg");
+            expect(url2).toBe("http://example.com/image.jpg");
+            expect(mockCreateObjectURL).not.toHaveBeenCalled();
+            // Return URLs
+            testBlobStore.returnUrl(url1);
+            testBlobStore.returnUrl(url2);
+            // Should not revoke remote URLs
+            expect(mockRevokeObjectURL).not.toHaveBeenCalled();
+        });
+        it("should handle null inputs gracefully", async () => {
+            const nullUrl = await testBlobStore.borrowUrl(null);
+            expect(nullUrl).toBeNull();
+            // Should not throw when returning null
+            expect(() => testBlobStore.returnUrl(null)).not.toThrow();
+        });
+        it('demonstrates race condition in borrowUrl', async () => {
+            const store = testBlobStore;
+            const testBlob = new Blob(['test data'], { type: 'text/plain' });
+            const blobRef = await store.getRef(testBlob);
+            // Create an artificially delayed getBlob to simulate network latency
+            const originalGetBlob = store.getBlob;
+            store.getBlob = async (ref) => {
+                await new Promise(resolve => setTimeout(resolve, 50)); // Add delay
+                return originalGetBlob(ref);
+            };
+            // Make two parallel borrowUrl calls
+            const [url1, url2] = await Promise.all([
+                store.borrowUrl(blobRef),
+                store.borrowUrl(blobRef)
+            ]);
+            expect(url1).toBe(url2); // Same URL should be returned
+            // Return one of the URLs
+            store.returnUrl(url1);
+            // Verify that the borrow count is still 1 since we borrowed twice and returned once
+            expect(store._testGetBorrowCount(blobRef)).toBe(1);
+            // Return the second URL
+            store.returnUrl(url2);
+            // Verify the borrow count is now 0
+            expect(store._testGetBorrowCount(blobRef)).toBe(0);
+            // Verify the URL was revoked
+            expect(mockRevokeObjectURL).toHaveBeenCalledTimes(1);
+            expect(mockRevokeObjectURL).toHaveBeenCalledWith(url1);
+        });
+    });
+});
+//# sourceMappingURL=blob-store.test.js.map

package/cache/blob-store.test.js.map

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

package/cache/data-cache.d.ts

@@ -0,0 +1,38 @@
+import { type AsyncCache } from "./async-cache.js";
+import { type BlobRef, BlobStore } from "./blob-store.js";
+import { type Data } from "../core/data.js";
+export type DataCacheInternal<K extends Data, V extends Data> = AsyncCache<K, V>;
+/**
+ * A persistent cache that stores data with an optional expiration time.
+ */
+export interface DataCache<K extends Data, V extends Data> {
+    /**
+     * Stores a new value within the cache.
+     * @param key key to use to store the value
+     * @param value the value to store
+     * @param maxDuration the time to live relative to the current time
+     */
+    put(key: K, value: V, options?: {
+        maximumDuration: number;
+    }): Promise<void>;
+    /**
+     * Attempts to retrieve a value from the cache.
+     * @param key The key previously used to store the value.
+     */
+    match(key: K): Promise<V | undefined>;
+    /**
+     * Deletes an item from the cache.
+     * @param key The key previously used to store the value.
+     */
+    delete(key: K): Promise<void>;
+}
+export declare function getBlobRefs(d: Data): Array<BlobRef>;
+export declare function createDataCache<K extends Data, V extends Data>(cache: AsyncCache<Request, Response>): DataCacheInternal<K, V>;
+export declare function createBlobRefAwareDataCache<K extends Data = Data, V extends Data = Data>(baseCache?: DataCacheInternal<K, V>, blobstore?: BlobStore): DataCacheInternal<Data, Data>;
+export declare const dataCache: DataCache<Data, Data>;
+/**
+ * Retrieves a namespaced data cache. Calling it multiple times will return an equivalent cache.
+ * Values stored within a data cache generally persist across sessions.
+ * @param nameSpace A unique string used to isolate values within this cache from other caches.
+ */
+export declare function getDataCache<K extends Data, V extends Data>(nameSpace: string): DataCache<K, V>;

package/cache/data-cache.js

@@ -0,0 +1,96 @@
+import { isBlobRef, blobStore } from "./blob-store.js";
+import { getManagedPersistentCache } from "./get-persistent-cache.js";
+import { createExpiringDataCache } from "./expiring-data-cache.js";
+/**
+ * Recursively searches arbitrary JSON data and locates any BlobRefs within it.
+ */
+function getBlobRefsInternal(d, refs = []) {
+    if (d && typeof d === "object") {
+        if (isBlobRef(d)) {
+            refs.push(d);
+        }
+        for (const value of Array.isArray(d) ? d : Object.values(d)) {
+            getBlobRefsInternal(value, refs);
+        }
+    }
+    return refs;
+}
+export function getBlobRefs(d) {
+    return getBlobRefsInternal(d);
+}
+function toRequest(data) {
+    return new Request("http://cache.key?" + encodeURI(JSON.stringify(data)));
+}
+async function areAllBlobRefsPresentInBlobStore(blobstore, data) {
+    for (const ref of getBlobRefs(data)) {
+        //  TODO: consider using a batched request to the blobstore or await Promise.all
+        if (!(await blobstore.hasBlob(ref))) {
+            // a contained blob ref is expired, so the entire data structure is expired
+            return false;
+        }
+    }
+    return true;
+}
+export function createDataCache(cache) {
+    return {
+        async match(k) {
+            const response = await cache.match(toRequest(k));
+            return response?.json();
+        },
+        async put(k, v) {
+            const blob = new Blob([JSON.stringify(v)], { type: "application/json" });
+            await cache.put(toRequest(k), new Response(blob));
+        },
+        async delete(k) {
+            await cache.delete(toRequest(k));
+        },
+    };
+}
+export function createBlobRefAwareDataCache(baseCache = dataCache, blobstore = blobStore) {
+    return {
+        ...baseCache,
+        async match(k) {
+            const result = await baseCache.match(k);
+            if (result !== undefined &&
+                !(await areAllBlobRefsPresentInBlobStore(blobstore, result))) {
+                await baseCache.delete(k);
+                return undefined;
+            }
+            return result;
+        },
+    };
+}
+const managedPersistentCache = await getManagedPersistentCache("datacache", {
+    maximumMemoryEntries: 100,
+    maximumStorageEntries: 1000,
+});
+const blobRefAwareDataCache = await createBlobRefAwareDataCache(createDataCache(managedPersistentCache));
+export const dataCache = createExpiringDataCache(blobRefAwareDataCache);
+/**
+ * Retrieves a namespaced data cache. Calling it multiple times will return an equivalent cache.
+ * Values stored within a data cache generally persist across sessions.
+ * @param nameSpace A unique string used to isolate values within this cache from other caches.
+ */
+export function getDataCache(nameSpace) {
+    return getNamespacedDataCacheInternal(nameSpace, dataCache);
+}
+function getNamespacedDataCacheInternal(name, mainCache = dataCache) {
+    if (!name || name.length === 0) {
+        throw new Error(`name is required`);
+    }
+    const getNSKey = (key) => {
+        return { name, key };
+    };
+    return {
+        async match(key) {
+            return (await mainCache.match(getNSKey(key)));
+        },
+        async put(key, value, options) {
+            await mainCache.put(getNSKey(key), value, options);
+        },
+        async delete(key) {
+            await mainCache.delete(getNSKey(key));
+        },
+    };
+}
+//# sourceMappingURL=data-cache.js.map

package/cache/data-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-cache.js","sourceRoot":"","sources":["../../src/cache/data-cache.ts"],"names":[],"mappings":"AAsBA,OAAO,EAA2B,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAGtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AA8BnE;;GAEG;AACH,SAAS,mBAAmB,CAC1B,CAAO,EACP,OAAuB,EAAE;IAEzB,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC/B,IAAI,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;YACjB,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACf,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5D,mBAAmB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAO;IACjC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,SAAS,CAAC,IAAU;IAC3B,OAAO,IAAI,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED,KAAK,UAAU,gCAAgC,CAC7C,SAAoB,EACpB,IAAU;IAEV,KAAK,MAAM,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,gFAAgF;QAChF,IAAI,CAAC,CAAC,MAAM,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACpC,2EAA2E;YAC3E,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,KAAoC;IAEpC,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,CAAI;YACd,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;YACjD,OAAO,QAAQ,EAAE,IAAI,EAAE,CAAC;QAC1B,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,CAAI,EAAE,CAAI;YAClB,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,CAAC,CAAC;YACzE,MAAM,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QACpD,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,CAAI;YACf,MAAM,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QACnC,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,2BAA2B,CAIzC,YAAqC,SAAoC,EACzE,SAAS,GAAG,SAAS;IAErB,OAAO;QACL,GAAG,SAAS;QACZ,KAAK,CAAC,KAAK,CAAC,CAAI;YACd,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACxC,IACE,MAAM,KAAK,SAAS;gBACpB,CAAC,CAAC,MAAM,gCAAgC,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,EAC5D,CAAC;gBACD,MAAM,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;gBAC1B,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,sBAAsB,GAAG,MAAM,yBAAyB,CAAC,WAAW,EAAE;IAC1E,oBAAoB,EAAE,GAAG;IACzB,qBAAqB,EAAE,IAAI;CAC5B,CAAC,CAAC;AACH,MAAM,qBAAqB,GAAG,MAAM,2BAA2B,CAC7D,eAAe,CAAC,sBAAsB,CAAC,CACxC,CAAC;AACF,MAAM,CAAC,MAAM,SAAS,GAA0B,uBAAuB,CACrE,qBAAqB,CACtB,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAC1B,SAAiB;IAEjB,OAAO,8BAA8B,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,8BAA8B,CACrC,IAAY,EACZ,SAAS,GAAG,SAAS;IAErB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,GAAM,EAAE,EAAE;QAC1B,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;IACvB,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,GAAM;YAChB,OAAO,CAAC,MAAM,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAkB,CAAC;QACjE,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAM,EAAE,KAAQ,EAAE,OAAO;YACjC,MAAM,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QACrD,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,GAAM;YACjB,MAAM,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;QACxC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/cache/data-cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/cache/data-cache.test.js

@@ -0,0 +1,50 @@
+/*MIT License
+
+© Copyright 2025 Adobe. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.*/
+import { getDataCache } from "./data-cache.js";
+import { beforeAll, describe, expect, it } from "vitest";
+describe("DataCache", () => {
+    beforeAll(() => { });
+    it("should allow storing and retrieving values in namespaced/versioned caches", async () => {
+        //  get a namespaced cache
+        const cache = await getDataCache("test:v1");
+        //  create some keys and values to store
+        const key = { foo: 1, bar: [{ baz: 12 }] };
+        const valueIn = { alpha: "bet", bar: ["a", "b"] };
+        //  store a key/value pair
+        await cache.put(key, valueIn);
+        //  retrieve the value
+        const valueOut = await cache.match(key);
+        //  output is NOT identical
+        expect(valueOut !== valueIn).toBe(true);
+        //  output IS structurally equal
+        expect(valueOut).toEqual(valueIn);
+        //  output from structurally equivalent key is the same
+        expect(await cache.match(JSON.parse(JSON.stringify(key)))).toEqual(valueIn);
+        //  output from equivalent cache (constructed with same name/version) is the same.
+        expect(await (await getDataCache("test:v1")).match(key)).toEqual(valueIn);
+        //  output from different named cache is undefined
+        expect(await (await getDataCache("test2:v1")).match(key)).toEqual(undefined);
+        //  output from different cache version is undefined
+        expect(await (await getDataCache("test:v2")).match(key)).toEqual(undefined);
+    });
+});
+//# sourceMappingURL=data-cache.test.js.map

package/cache/data-cache.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-cache.test.js","sourceRoot":"","sources":["../../src/cache/data-cache.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;WAoBW;AACX,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAEzD,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;IACzB,SAAS,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACpB,EAAE,CAAC,2EAA2E,EAAE,KAAK,IAAI,EAAE;QACzF,0BAA0B;QAC1B,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,SAAS,CAAC,CAAC;QAE5C,wCAAwC;QACxC,MAAM,GAAG,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;QAC3C,MAAM,OAAO,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;QAElD,0BAA0B;QAC1B,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAE9B,sBAAsB;QACtB,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAExC,2BAA2B;QAC3B,MAAM,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAExC,gCAAgC;QAChC,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAElC,uDAAuD;QACvD,MAAM,CAAC,MAAM,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAE5E,kFAAkF;QAClF,MAAM,CAAC,MAAM,CAAC,MAAM,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAE1E,kDAAkD;QAClD,MAAM,CAAC,MAAM,CAAC,MAAM,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAC/D,SAAS,CACV,CAAC;QAEF,oDAAoD;QACpD,MAAM,CAAC,MAAM,CAAC,MAAM,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC9E,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/cache/expiring-data-cache.d.ts

@@ -0,0 +1,6 @@
+import { type Data } from "../core/data.js";
+import { type DataCache, DataCacheInternal } from "./data-cache.js";
+/**
+ * Creates a new expiring data cache with the specified underlying cache.
+ */
+export declare function createExpiringDataCache<K extends Data, V extends Data>(baseCache: DataCacheInternal<K, V>, getTime?: () => number): DataCache<K, V>;