@adobe/data 0.1.3 → 0.2.1

package/package.json

@@ -1,56 +1,77 @@
 {
   "name": "@adobe/data",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Adobe data oriented programming library",
   "type": "module",
   "sideEffects": true,
   "private": false,
-  "packageManager": "pnpm@8.6.2+sha256.c6da9e00697e334b6193c034a5d1508e4c8605b12f249736b13f31139f4f0d73",
   "exports": {
     ".": {
-      "import": "./core/index.js",
-      "types": "./core/index.d.ts"
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
     },
     "./cache": {
-      "import": "./cache/index.js",
-      "types": "./cache/index.d.ts"
+      "import": "./dist/cache/index.js",
+      "types": "./dist/cache/index.d.ts"
     },
-    "./schemas": {
-      "import": "./schemas/index.js",
-      "types": "./schemas/index.d.ts"
+    "./schema": {
+      "import": "./dist/schema/index.js",
+      "types": "./dist/schema/index.d.ts"
     },
     "./types": {
-      "import": "./types/index.js",
-      "types": "./types/index.d.ts"
+      "import": "./dist/types/index.js",
+      "types": "./dist/types/index.d.ts"
     },
     "./observe": {
-      "import": "./observe/index.js",
-      "types": "./observe/index.d.ts"
+      "import": "./dist/observe/index.js",
+      "types": "./dist/observe/index.d.ts"
     },
     "./ecs": {
-      "import": "./ecs/index.js",
-      "types": "./ecs/index.d.ts"
+      "import": "./dist/ecs/index.js",
+      "types": "./dist/ecs/index.d.ts"
+    },
+    "./old-ecs": {
+      "import": "./dist/old-ecs/index.js",
+      "types": "./dist/old-ecs/index.d.ts"
+    },
+    "./lit": {
+      "import": "./dist/lit/index.js",
+      "types": "./dist/lit/index.d.ts"
+    },
+    "./service": {
+      "import": "./dist/service/index.js",
+      "types": "./dist/service/index.d.ts"
+    },
+    "./table": {
+      "import": "./dist/table/index.js",
+      "types": "./dist/table/index.d.ts"
+    },
+    "./typed-buffer": {
+      "import": "./dist/typed-buffer/index.js",
+      "types": "./dist/typed-buffer/index.d.ts"
     }
   },
   "devDependencies": {
     "@assemblyscript/loader": "^0.27.30",
     "@trivago/prettier-plugin-sort-imports": "^4.3.0",
+    "@types/jsonpath": "^0.2.4",
     "@types/uuid": "^10.0.0",
-    "@typescript-eslint/eslint-plugin": "^5.59.2",
-    "@typescript-eslint/parser": "^5.59.2",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
     "@vitest/browser": "^1.6.0",
+    "@webgpu/types": "^0.1.61",
     "assemblyscript": "^0.27.30",
     "eslint": "^8.56.0",
     "eslint-config-airbnb-typescript": "^17.1.0",
-    "eslint-config-prettier": "^8.6.0",
+    "eslint-config-prettier": "^9.1.0",
     "eslint-formatter-pretty": "^5.0.0",
     "eslint-plugin-header": "^3.1.1",
-    "eslint-plugin-import": "^2.27.5",
+    "eslint-plugin-import": "^2.29.1",
     "eslint-plugin-lit": "^1.11.0",
     "eslint-plugin-lit-a11y": "^4.1.2",
-    "eslint-plugin-notice": "0.9.10",
+    "eslint-plugin-notice": "^0.9.10",
     "eslint-plugin-prettier": "^5.1.3",
-    "glob": "^11.0.0",
+    "glob": "^10.3.10",
     "jsdom": "^24.1.0",
     "lint-staged": "^13.2.2",
     "nodemon": "^3.1.7",
@@ -63,7 +84,7 @@
     "stylelint": "^16.2.1",
     "stylelint-config-standard": "^36.0.0",
     "typedoc": "^0.26.7",
-    "typescript": "^5.3.3",
+    "typescript": "^5.8.3",
     "uuid": "^10.0.0",
     "vite": "^5.1.1",
     "vitest": "^1.6.0",
@@ -76,27 +97,28 @@
   },
   "dependencies": {
     "@cfworker/json-schema": "^4.1.1",
-    "jsonpath": "^1.1.1"
+    "@lit/context": "^1.1.5",
+    "jsonpath": "^1.1.1",
+    "lit": "^3.3.0"
   },
   "scripts": {
     "build": "pnpm build-assembly && run-p build:*",
-    "build:code": "pnpm copy && tsc -b",
+    "build:code": "tsc -b",
     "build:apidocs": "typedoc",
     "build-assembly": "run-p asbuild:release",
     "clean": "rm -rf dist build node_modules",
-    "copy": "mkdir -p dist && cp README.md dist && sed '/publish\":/d' package.json > dist/package.json",
     "deploy-docs": "pnpm build && ./scripts/deploy-docs.sh",
     "dev": "run-p dev:*",
-    "dev:build": "pnpm copy && tsc -b -w --preserveWatchOutput",
+    "dev:build": "tsc -b -w --preserveWatchOutput",
     "dev:test": "pnpm test",
     "dev:apidocs": "nodemon -w README.md -w dist -x typedoc --delay 100",
     "dev:assembly": "nodemon -w assembly -e ts -x pnpm run asbuild:release --delay 100",
     "lint": "pnpm eslint .",
     "lint-fix": "pnpm eslint . --fix",
     "debug": "vitest --inspect-brk --no-file-parallelism --test-timeout 1000000",
-    "link": "pnpm build && cd dist && ln -sf ../node_modules node_modules && pnpm link --global",
-    "bump": "pnpm version patch --no-git-tag-version && git commit -am 'bumped patch version' && pnpm run publish",
+    "link": "pnpm build && pnpm link --global",
     "pre-commit": "lint-staged",
+    "publish-public": "pnpm build && pnpm publish --no-git-checks --access public",
     "perftest": "node dist/perftest/index.js",
     "test": "vitest",
     "asbuild:debug": "asc assembly/index.ts -o dist/assembly/index.wasm --target debug --enable simd && echo built dist/assembly/index.wasm",

package/scripts/deploy-docs.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+
+# Exit if any command fails
+set -e
+
+# Step 1: Ensure we are on the main branch
+current_branch=$(git branch --show-current)
+if [ "$current_branch" != "main" ]; then
+  echo "Error: You are on branch '$current_branch'. Please switch to 'main' before deploying."
+  exit 1
+fi
+
+# Step 2: Check for uncommitted changes
+if [[ -n $(git status --porcelain) ]]; then
+  echo "Error: You have uncommitted changes. Please commit or stash your changes before deploying."
+  exit 1
+fi
+
+# Step 3: Build the project
+echo "Building the project..."
+pnpm install
+pnpm run build
+
+# Step 4: Checkout gh-pages branch
+echo "Checking out the gh-pages branch..."
+git fetch origin
+git checkout gh-pages
+git pull origin gh-pages
+
+# Step 5: Commit and push the changes to gh-pages
+echo "Committing and pushing changes to gh-pages..."
+git checkout -f main -- README.md docs
+git add dist/ docs/ README.md
+git commit -m "Deploy updated docs and dist to GitHub Pages"
+git push origin gh-pages
+
+# Step 6: Switch back to the main branch
+echo "Switching back to the main branch..."
+git checkout main
+
+echo "Deployment to gh-pages complete!"

package/{assembly-test/assembly.test.js → src/assembly-test/assembly.test.ts}

@@ -21,9 +21,9 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.*/
 import { describe, expect, test } from "vitest";
 import { add } from "../../dist/assembly/index.js";
+
 describe("Assembly", () => {
-    test("should be able to call assembly script functions", () => {
-        expect(add(40, 2)).toBe(42);
-    });
+  test("should be able to call assembly script functions", () => {
+    expect(add(40, 2)).toBe(42);
+  });
 });
-//# sourceMappingURL=assembly.test.js.map

package/src/cache/async-cache.ts

@@ -0,0 +1,38 @@
+/*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.*/
+
+/**
+ * This is a generalization of the browser built in Cache API.
+ */
+export interface AsyncCache<K, V> {
+  put(key: K, value: V): Promise<void>;
+  match(key: K): Promise<V | undefined>;
+  delete(key: K): Promise<void>;
+}
+
+/**
+ * Shouldn't be needed normally. Only used by ManagedAsyncCache.
+ * We don't want to expose it externally so leaving out of main AsyncCache type.
+ */
+export interface AsyncCacheWithKeys<K, V> extends AsyncCache<K, V> {
+  keys(): Promise<ReadonlyArray<K>>;
+}

package/{cache/blob-store.test.js → src/cache/blob-store.test.ts}

@@ -20,123 +20,157 @@ 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";
+import { type BlobStore, createBlobStore } from "./blob-store.js";
+
 describe("blobStore", () => {
     // Mock URL.createObjectURL and URL.revokeObjectURL
-    const mockCreateObjectURL = vi.fn((blob) => `blob:${Math.random()}`);
+    const mockCreateObjectURL = vi.fn((blob: Blob) => `blob:${Math.random()}`);
     const mockRevokeObjectURL = vi.fn();
-    let testBlobStore;
-    let createdUrl;
+    let testBlobStore: BlobStore;
+    let createdUrl: string;
+
     beforeEach(async () => {
         // Setup URL mock functions
         const originalCreateObjectURL = URL.createObjectURL;
         const originalRevokeObjectURL = URL.revokeObjectURL;
+
         // Ensure we create a non-http URL
-        mockCreateObjectURL.mockImplementation((blob) => {
+        mockCreateObjectURL.mockImplementation((blob: 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/src/cache/blob-store.ts

@@ -0,0 +1,278 @@
+/*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 { type FromSchema, type Schema } from "../schema/index.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}.*`,
+} as const satisfies Schema;
+type RemoteUrl = `${typeof remoteUrlPrefix}${string}`;
+
+const RemoteBlobRefSchema = {
+  required: ["remoteBlobRef"],
+  properties: {
+    remoteBlobRef: RemoteUrlSchema,
+  },
+  additionalProperties: false,
+} as const satisfies Schema;
+type RemoteBlobRef = FromSchema<typeof RemoteBlobRefSchema>;
+
+const LocalBlobRefSchema = {
+  required: ["localBlobRef"],
+  properties: {
+    localBlobRef: { type: "string" },
+  },
+  additionalProperties: false,
+} as const satisfies Schema;
+type LocalBlobRef = FromSchema<typeof LocalBlobRefSchema>;
+
+export const BlobRefSchema = {
+  oneOf: [RemoteBlobRefSchema, LocalBlobRefSchema],
+} as const satisfies Schema;
+
+/**
+ * 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>;
+
+function isRemoteBlobRef(ref: unknown): ref is RemoteBlobRef {
+  const maybe = ref as Partial<RemoteBlobRef> | undefined;
+  return typeof maybe?.remoteBlobRef === "string";
+}
+
+function isLocalBlobRef(ref: unknown): ref is LocalBlobRef {
+  const maybe = ref as Partial<LocalBlobRef> | undefined;
+  return typeof maybe?.localBlobRef === "string";
+}
+
+export function isBlobRef(value: unknown): value is BlobRef {
+  return isRemoteBlobRef(value) || isLocalBlobRef(value);
+}
+
+function isRemoteUrl(url: string): url is RemoteUrl {
+  return url.startsWith(remoteUrlPrefix);
+}
+
+function toRequest(ref: LocalBlobRef) {
+  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");
+
+/**
+ * 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 function createBlobStore() {
+  const cachePromise = getManagedPersistentCache("blobstore", {
+    maximumMemoryEntries: 10,
+    maximumStorageEntries: 1000,
+  });
+
+  // Track borrowed URLs and their reference counts
+  const borrowedUrls = new Map<string, { url: string; count: number }>();
+  // Reverse mapping for O(1) lookup
+  const urlToKey = new Map<string, string>();
+
+  async function getRef(blob: Blob | string): Promise<BlobRef> {
+    const cache = await cachePromise;
+    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),
+    } as const satisfies LocalBlobRef;
+
+    const request = toRequest(ref);
+    const response = new Response(blob);
+
+    await cache.put(request, response);
+    return ref;
+  }
+
+  async function hasBlob(r: BlobRef): Promise<boolean> {
+    if (isRemoteBlobRef(r)) {
+      return true;
+    }
+    const cache = await cachePromise;
+    const response = await cache.match(toRequest(r));
+    return response !== undefined;
+  }
+
+  async function getBlob(r?: BlobRef | null): Promise<Blob | null> {
+    if (!r) {
+      return null;
+    }
+    const response = await (isRemoteBlobRef(r)
+      ? fetch(r.remoteBlobRef)
+      : (await cachePromise).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: BlobRef): Promise<void> {
+    if (isLocalBlobRef(r)) {
+      const cache = await cachePromise;
+      cache.delete(toRequest(r));
+    }
+  }
+
+  /**
+   * prevent parallel execution to avoid race condition in borrowUrl while awaiting getBlob
+   */
+  const borrowUrlInternalNoIncrement = preventParallelExecution(async (key: string, r: BlobRef): Promise<{ url: string; count: number } | null> => {
+    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: BlobRef): Promise<string | null> {
+    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: string | null) {
+    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: string): BlobRef {
+    if (!isRemoteUrl(url)) {
+      throw new Error(
+        `Invalid url, expected to start with (${remoteUrlPrefix}): ${url}`
+      );
+    }
+    return { remoteBlobRef: url } satisfies RemoteBlobRef;
+  }
+
+  function _testGetBorrowCount(r: BlobRef): number {
+    const key = JSON.stringify(r);
+    return borrowedUrls.get(key)?.count ?? 0;
+  }
+
+  return {
+    getRef,
+    getBlob,
+    hasBlob,
+    borrowUrl,
+    returnUrl,
+    releaseBlob,
+    createRemoteBlobRef,
+    _testGetBorrowCount,
+  } as const satisfies BlobStore;
+}
+
+/**
+ * The global blob store that can be used to store and retrieve blobs.
+ */
+export const blobStore: BlobStore = createBlobStore();