@adobe/data 0.1.2 → 0.2.0

package/{cache/functions/get-cached.js → src/cache/functions/get-cached.ts}

@@ -19,31 +19,37 @@ 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.*/
+
 // Create a WeakMap to store cached values for each object
-const cache = new WeakMap();
+const cache = new WeakMap<object, Map<Function, unknown>>();
+
 /**
  * Gets a cached value for an object using a factory function.
  * If the value hasn't been cached yet, the factory function will be called to create it.
  * The cache is stored on the object itself using a WeakMap, allowing for garbage collection
  * when the object is no longer referenced.
- *
+ * 
  * @param context The object to cache the value on
  * @param factory A function that creates the value to be cached
  * @returns The cached value or a newly created value from the factory
  */
-export function getCached(context, factory) {
+export function getCached<A extends object, B>(
+    context: A,
+    factory: (obj: A) => B
+): B {
     // Get or create the factory map for this object
-    let factoryMap = cache.get(context);
+    let factoryMap = cache.get(context) as Map<Function, B> | undefined;
     if (!factoryMap) {
         factoryMap = new Map();
         cache.set(context, factoryMap);
     }
+
     // Get or create the cached value for this factory
     let value = factoryMap.get(factory);
     if (value === undefined) {
         value = factory(context);
         factoryMap.set(factory, value);
     }
+
     return value;
-}
-//# sourceMappingURL=get-cached.js.map
+} 

package/{cache/functions/hashing/blob-to-hash.js → src/cache/functions/hashing/blob-to-hash.ts}

@@ -20,25 +20,27 @@ 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 { bufferToHash } from "./buffer-to-hash.js";
+
 /**
  * Converts a Blob to a hash using the blob content and type using SHA-256.
  */
-export async function blobToHash(blob) {
-    const { type } = blob;
-    //  create a single buffer to hold both the type and the blob
-    const typeByteLength = type.length * 2;
-    const buffer = new ArrayBuffer(typeByteLength + blob.size);
-    //  write the type into the first part of the buffer
-    const charView = new Uint16Array(buffer, 0, type.length);
-    for (let i = 0, strLen = type.length; i < strLen; i++) {
-        charView[i] = type.charCodeAt(i);
-    }
-    //  write the blob into the second part of the buffer
-    const byteView = new Uint8Array(buffer);
-    const blobArrayBuffer = await blob.arrayBuffer();
-    byteView.set(new Uint8Array(blobArrayBuffer), typeByteLength);
-    //  finally create the hash off the combined buffer
-    const hash = await bufferToHash(buffer);
-    return hash;
+export async function blobToHash(blob: Blob): Promise<string> {
+  const { type } = blob;
+  //  create a single buffer to hold both the type and the blob
+  const typeByteLength = type.length * 2;
+  const buffer = new ArrayBuffer(typeByteLength + blob.size);
+
+  //  write the type into the first part of the buffer
+  const charView = new Uint16Array(buffer, 0, type.length);
+  for (let i = 0, strLen = type.length; i < strLen; i++) {
+    charView[i] = type.charCodeAt(i);
+  }
+  //  write the blob into the second part of the buffer
+  const byteView = new Uint8Array(buffer);
+  const blobArrayBuffer = await blob.arrayBuffer();
+  byteView.set(new Uint8Array(blobArrayBuffer), typeByteLength);
+
+  //  finally create the hash off the combined buffer
+  const hash = await bufferToHash(buffer);
+  return hash;
 }
-//# sourceMappingURL=blob-to-hash.js.map

package/{cache/functions/hashing/buffer-to-hash.js → src/cache/functions/hashing/buffer-to-hash.ts}

@@ -19,15 +19,15 @@ 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.*/
-function arrayBufferToHex(buffer) {
-    return [...new Uint8Array(buffer)]
-        .map((x) => x.toString(16).padStart(2, "0"))
-        .join("");
+function arrayBufferToHex(buffer: ArrayBuffer): string {
+  return [...new Uint8Array(buffer)]
+    .map((x) => x.toString(16).padStart(2, "0"))
+    .join("");
 }
+
 /**
  * Converts an ArrayBuffer to a hash using SHA-256.
  */
-export async function bufferToHash(buffer) {
-    return arrayBufferToHex(await crypto.subtle.digest("SHA-256", buffer));
+export async function bufferToHash(buffer: ArrayBuffer): Promise<string> {
+  return arrayBufferToHex(await crypto.subtle.digest("SHA-256", buffer));
 }
-//# sourceMappingURL=buffer-to-hash.js.map

package/src/cache/functions/hashing/hashing.test.ts

@@ -0,0 +1,95 @@
+/*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 { blobToHash } from "./blob-to-hash.js";
+import { jsonToHash } from "./json-to-hash.js";
+import { describe, expect, it } from "vitest";
+
+describe("test hashing", () => {
+  it("blobToHash should avoid collisions based on content and type", async () => {
+    const blobs = [
+      new Blob([
+        new Uint8Array([
+          45, 255, 128, 0, 1, 33, 33, 85, 129, 250, 245, 12, 33, 89, 7,
+        ]),
+      ]),
+      new Blob([
+        new Uint8Array([
+          45, 255, 128, 0, 1, 33, 33, 85, 129, 250, 245, 12, 33, 89, 8,
+        ]),
+      ]),
+      new Blob(["long text sample here"]),
+      new Blob(["long text sample here."]),
+      new Blob(["a"]),
+      new Blob(["b"]),
+      new Blob(["a"], { type: "octet/binary" }),
+      new Blob(["a"], { type: "text/plain" }),
+      //    empty blobs should work
+      new Blob([""]),
+      new Blob([""], { type: "octet/binary" }),
+      new Blob([""], { type: "text/plain" }),
+    ];
+    const hashPromises = blobs.map((blob) => blobToHash(blob));
+    const hashes = await Promise.all(hashPromises);
+    const unique = new Set(hashes);
+    const collisions = hashes.length - unique.size;
+    expect(collisions).toBe(0);
+  });
+  it("blobToHash should generate consistent hashes", async () => {
+    const blobs = [
+      new Blob(["long text sample here"], { type: "text/plain" }),
+      new Blob(["long text sample here"], { type: "text/plain" }),
+      new Blob(["long text sample here"], { type: "text/plain" }),
+    ];
+    const hashPromises = blobs.map((blob) => blobToHash(blob));
+    const hashes = await Promise.all(hashPromises);
+    const unique = new Set(hashes);
+    expect(unique.size).toBe(1);
+  });
+  it("jsonToHash should avoid collisions", async () => {
+    const values = [
+      "foo",
+      { a: 1 },
+      {},
+      [],
+      { a: 2 },
+      null,
+      "",
+      { alpha: "bravo" },
+    ];
+    const hashPromises = values.map((value) => jsonToHash(value));
+    const hashes = await Promise.all(hashPromises);
+    const unique = new Set(hashes);
+    const collisions = hashes.length - unique.size;
+    expect(collisions).toBe(0);
+  });
+  it("jsonToHash should generate consistent hashes", async () => {
+    const values = [
+      { a: 1, b: 2, foo: "bar" },
+      { a: 1, b: 2, foo: "bar" },
+      { a: 1, b: 2, foo: "bar" },
+    ];
+    const hashPromises = values.map((value) => jsonToHash(value));
+    const hashes = await Promise.all(hashPromises);
+    const unique = new Set(hashes);
+    expect(unique.size).toBe(1);
+  });
+});

package/{cache/functions/hashing/index.js → src/cache/functions/hashing/index.ts}

@@ -19,8 +19,8 @@ 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.*/
+
 export * from "./blob-to-hash.js";
 export * from "./buffer-to-hash.js";
 export * from "./json-to-hash.js";
 export * from "./string-to-hash.js";
-//# sourceMappingURL=index.js.map

package/{cache/functions/hashing/json-to-hash.js → src/cache/functions/hashing/json-to-hash.ts}

@@ -20,10 +20,10 @@ 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 { stringToHash } from "./string-to-hash.js";
+
 /**
  * Converts a JSON object to a hash using SHA-256.
  */
-export async function jsonToHash(value) {
-    return stringToHash(JSON.stringify(value));
+export async function jsonToHash(value: unknown): Promise<string> {
+  return stringToHash(JSON.stringify(value));
 }
-//# sourceMappingURL=json-to-hash.js.map

package/{cache/functions/hashing/string-to-hash.js → src/cache/functions/hashing/string-to-hash.ts}

@@ -20,18 +20,19 @@ 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 { bufferToHash } from "./buffer-to-hash.js";
-function stringToArrayBuffer(value) {
-    const buf = new ArrayBuffer(value.length * 2);
-    const view = new Uint16Array(buf);
-    for (let i = 0, strLen = value.length; i < strLen; i++) {
-        view[i] = value.charCodeAt(i);
-    }
-    return buf;
+
+function stringToArrayBuffer(value: string): ArrayBuffer {
+  const buf = new ArrayBuffer(value.length * 2);
+  const view = new Uint16Array(buf);
+  for (let i = 0, strLen = value.length; i < strLen; i++) {
+    view[i] = value.charCodeAt(i);
+  }
+  return buf;
 }
+
 /**
  * Converts a string to a hash using SHA-256.
  */
-export async function stringToHash(value) {
-    return bufferToHash(stringToArrayBuffer(value));
+export async function stringToHash(value: string): Promise<string> {
+  return bufferToHash(stringToArrayBuffer(value));
 }
-//# sourceMappingURL=string-to-hash.js.map

package/{cache/functions/index.js → src/cache/functions/index.ts}

@@ -19,11 +19,9 @@ 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.*/
+
 export * from "./hashing/index.js";
-// export * from './bind-functions.js';
 export * from "./memoize.js";
-// export * from './omit.js';
 export * from "./prevent-parallel-execution.js";
-export * from "./types.js";
+export * from "./async-data-function.js";
 export * from "./get-cached.js";
-//# sourceMappingURL=index.js.map

package/{cache/functions/memoize.js → src/cache/functions/memoize.ts}

@@ -19,8 +19,13 @@ 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 { preventParallelExecution } from "./prevent-parallel-execution.js";
+import { AsyncDataFunction } from "./async-data-function.js";
+
+import { type Data } from "../../data.js";
 import { getDataCache } from "../index.js";
+
 /**
  * Uses datacache to store results so we can avoid expensive recomputations of the same input.
  * This function also uses preventParallelExecution to prevent multiple executions of the same function at the same time with the same arguments.
@@ -30,19 +35,21 @@ import { getDataCache } from "../index.js";
  * @param name The name of this function which should be application unique to avoid hash collisions.
  * @returns A function with the same signature but memoized results.
  */
-export function memoize(uniqueNameAndVersion, fn) {
-    // synchronize the function to prevent executing same requests simultaneously.
-    fn = preventParallelExecution(fn);
-    const cache = getDataCache(uniqueNameAndVersion);
-    const memoized = async (...args) => {
-        const cachedResult = await cache.match(args);
-        if (cachedResult !== undefined) {
-            return cachedResult;
-        }
-        const result = await fn(...args);
-        await cache.put(args, result);
-        return result;
-    };
-    return memoized;
+export function memoize<In extends Array<Data>, Out extends Data>(
+  uniqueNameAndVersion: string,
+  fn: AsyncDataFunction<In, Out>
+): AsyncDataFunction<In, Out> {
+  // synchronize the function to prevent executing same requests simultaneously.
+  fn = preventParallelExecution(fn);
+  const cache = getDataCache(uniqueNameAndVersion);
+  const memoized = async (...args: Array<Data>): Promise<Data> => {
+    const cachedResult = await cache.match(args);
+    if (cachedResult !== undefined) {
+      return cachedResult;
+    }
+    const result = await fn(...(args as In));
+    await cache.put(args, result);
+    return result;
+  };
+  return memoized as unknown as AsyncDataFunction<In, Out>;
 }
-//# sourceMappingURL=memoize.js.map

package/src/cache/functions/prevent-parallel-execution.ts

@@ -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 { type AsyncDataFunction } from "./async-data-function.js";
+
+import { type Data } from "../../data.js";
+
+/**
+ * Returns an async function which can NOT be executed simultaneously with the same arguments.
+ * Any attempt to call again while a prior call with same args is executing will return the first promise.
+ * Once a promise completes, then a new call with same args could occur.
+ */
+export function preventParallelExecution<In extends Array<unknown>, Out>(
+  fn: AsyncDataFunction<In, Out>
+): AsyncDataFunction<In, Out> {
+  const executing = new Map<string, Promise<Out>>();
+  const synchronized = async (...args: Array<Data>): Promise<Out> => {
+    const key = JSON.stringify(args);
+    let promise = executing.get(key);
+    if (!promise) {
+      promise = fn(...(args as In));
+      executing.set(key, promise);
+    }
+    try {
+      return await promise;
+    } finally {
+      // we delete the key after execution to prevent memory leak.
+      executing.delete(key);
+    }
+  };
+  return synchronized as unknown as AsyncDataFunction<In, Out>;
+}

package/src/cache/get-persistent-cache.ts

@@ -0,0 +1,62 @@
+/*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 type { AsyncCache, AsyncCacheWithKeys } from "./async-cache.js";
+import { createFallbackAsyncCache } from "./fallback-async-cache.js";
+import { createManagedAsyncCache } from "./managed-async-cache.js";
+import { createMemoryAsyncCache } from "./memory-async-cache.js";
+
+/**
+ * Gets a persistent async cache.
+ * @param name the namespace name for the cache.
+ */
+async function getUnmanagedPersistentCache(
+  name: string
+): Promise<AsyncCacheWithKeys<Request, Response>> {
+  return globalThis.caches.open(name) as unknown as Promise<
+    AsyncCacheWithKeys<Request, Response>
+  >;
+}
+
+/**
+ * Gets a managed persistent cache using both fast memory layer and slower storage layer.
+ * @param name The namespace for this persistent cache, used to isolate cache storage.
+ * @param maximumMemoryEntries
+ * @param maximumStorageEntries
+ * @returns
+ */
+export async function getManagedPersistentCache(
+  name: string,
+  options: {
+    maximumMemoryEntries: number;
+    maximumStorageEntries: number;
+  }
+): Promise<AsyncCache<Request, Response>> {
+  const memoryCache = createManagedAsyncCache(
+    createMemoryAsyncCache(),
+    options.maximumMemoryEntries
+  );
+  const storageCache = createManagedAsyncCache(
+    await getUnmanagedPersistentCache(name),
+    options.maximumStorageEntries
+  );
+  return createFallbackAsyncCache(memoryCache, storageCache);
+}

package/{cache/index.js → src/cache/index.ts}

@@ -19,7 +19,13 @@ 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.*/
-export { blobStore, isBlobRef, BlobRefSchema, } from "./blob-store.js";
-export { getDataCache } from "./data-cache.js";
+
+export {
+  type BlobStore,
+  type BlobRef,
+  blobStore,
+  isBlobRef,
+  BlobRefSchema,
+} from "./blob-store.js";
+export { getDataCache, type DataCache } from "./data-cache.js";
 export * from "./functions/index.js";
-//# sourceMappingURL=index.js.map