@pluot/core 0.1.0

package/src/dom-2d-camera.js

@@ -0,0 +1,441 @@
+// License copied from https://github.com/flekschas/dom-2d-camera/blob/master/LICENSE.md
+//
+// This software is released under the MIT license:
+//
+// 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.
+
+// Reference: https://github.com/flekschas/dom-2d-camera/blob/cd59ea035a0ea72c2c0535fa3721f8127946576c/src/index.js
+// TODO: contribute modifications back upstream once things are working.
+
+import { vec2 } from "gl-matrix";
+import createCamera from "camera-2d-simple";
+
+const MOUSE_DOWN_MOVE_ACTIONS = ["pan", "rotate"];
+const KEY_MAP = {
+  alt: "altKey",
+  cmd: "metaKey",
+  ctrl: "ctrlKey",
+  meta: "metaKey",
+  shift: "shiftKey"
+};
+
+const dom2dCamera = (
+  element,
+  {
+    distance = 1.0,
+    target = [0, 0],
+    rotation = 0,
+    isNdc = true,
+    isFixed = false,
+    isPan = true,
+    isPanInverted = [false, true],
+    panSpeed = 1,
+    isRotate = true,
+    rotateSpeed = 1,
+    defaultMouseDownMoveAction = "pan",
+    mouseDownMoveModKey = "alt",
+    isZoom = true,
+    zoomSpeed = 1,
+    viewCenter,
+    scaleBounds,
+    translationBounds,
+    onKeyDown = () => {},
+    onKeyUp = () => {},
+    onMouseDown = () => {},
+    onMouseUp = () => {},
+    onMouseMove = () => {},
+    onWheel = () => {},
+    aspectRatioMode = "Ignore",
+    aspectRatioAlignmentMode = "Center",
+  } = {}
+) => {
+  let camera = createCamera(
+    target,
+    distance,
+    rotation,
+    viewCenter,
+    scaleBounds,
+    translationBounds
+  );
+  let mouseX = 0;
+  let mouseY = 0;
+  let mouseRelX = 0;
+  let mouseRelY = 0;
+  let prevMouseX = 0;
+  let prevMouseY = 0;
+  let isLeftMousePressed = false;
+  let scrollDist = 0;
+
+  let width = 1;
+  let height = 1;
+  let aspectRatio = 1;
+
+  let isInteractivelyChanged = false;
+  let isProgrammaticallyChanged = false;
+  let isMouseDownMoveModActive = false;
+
+  let panOnMouseDownMove = defaultMouseDownMoveAction === "pan";
+
+  let isPanX = isPan;
+  let isPanY = isPan;
+  let isPanXInverted = isPanInverted;
+  let isPanYInverted = isPanInverted;
+  let isZoomX = isZoom;
+  let isZoomY = isZoom;
+
+  const spreadXYSettings = () => {
+    isPanX = Array.isArray(isPan) ? Boolean(isPan[0]) : isPan;
+    isPanY = Array.isArray(isPan) ? Boolean(isPan[1]) : isPan;
+    isPanXInverted = Array.isArray(isPanInverted)
+      ? Boolean(isPanInverted[0])
+      : isPanInverted;
+    isPanYInverted = Array.isArray(isPanInverted)
+      ? Boolean(isPanInverted[1])
+      : isPanInverted;
+    isZoomX = Array.isArray(isZoom) ? Boolean(isZoom[0]) : isZoom;
+    isZoomY = Array.isArray(isZoom) ? Boolean(isZoom[1]) : isZoom;
+  };
+
+  spreadXYSettings();
+
+  let xAspectRatioModeFactor = 1.0;
+  let yAspectRatioModeFactor = 1.0;
+  let xAlignmentTranslation = 0.0;
+  let yAlignmentTranslation = 0.0;
+
+  /*
+    // Logic for aspect ratio handling in point_layer.wgsl
+    if (aspect_ratio_mode == 1u) {
+        // fit/contain
+        if (layer_aspect_ratio > 1.0) {
+            // Wide rectangle
+            // Show more than (0, 1) in x direction. Show exactly (0, 1) in y direction.
+            x_scale_for_aspect_ratio_mode = 1.0 / layer_aspect_ratio;
+        } else if(layer_aspect_ratio < 1.0) {
+            // Tall layer
+            // Show exactly (0, 1) in x direction. Show more than (0, 1) in y direction.
+            y_scale_for_aspect_ratio_mode = layer_aspect_ratio;
+        } else {
+            // Square layer; no change needed.
+            // Show exactly (0, 1) in both directions.
+        }
+    } else if (aspect_ratio_mode == 2u) {
+        // fill/cover
+        if(layer_aspect_ratio > 1.0) {
+            // Wide rectangle
+            // Show exactly (0, 1) in x direction. Show less than (0, 1) in y direction.
+            y_scale_for_aspect_ratio_mode = layer_aspect_ratio;
+        } else if(layer_aspect_ratio < 1.0) {
+            // Tall layer
+            // Show less than (0, 1) in x direction. Show exactly (0, 1) in y direction.
+            x_scale_for_aspect_ratio_mode = 1.0 / layer_aspect_ratio;
+        } else {
+            // Square layer; no change needed.
+            // Show exactly (0, 1) in both directions.
+        }
+    }
+  */
+  const updateAspectRatioModeFactors = () => {
+    xAspectRatioModeFactor = 1.0;
+    yAspectRatioModeFactor = 1.0;
+    if(aspectRatioMode === "Contain") {
+      if(aspectRatio > 1.0) {
+        xAspectRatioModeFactor = 1.0 / aspectRatio;
+      } else if(aspectRatio < 1.0) {
+        yAspectRatioModeFactor = aspectRatio;
+      }
+    } else if(aspectRatioMode === "Cover") {
+      if(aspectRatio > 1.0) {
+        yAspectRatioModeFactor = aspectRatio;
+      } else if(aspectRatio < 1.0) {
+        xAspectRatioModeFactor = 1.0 / aspectRatio;
+      }
+    }
+
+    xAlignmentTranslation = 0.0;
+    yAlignmentTranslation = 0.0;
+    if(aspectRatioAlignmentMode === "Start") {
+      xAlignmentTranslation = xAspectRatioModeFactor - 1.0;
+      yAlignmentTranslation = yAspectRatioModeFactor - 1.0;
+    } else if(aspectRatioAlignmentMode === "End") {
+      xAlignmentTranslation = 1.0 - xAspectRatioModeFactor;
+      yAlignmentTranslation = 1.0 - yAspectRatioModeFactor;
+    }
+  };
+  updateAspectRatioModeFactors();
+
+  const transformPanX = isNdc
+    ? dX => (dX / width) * 2 * (1.0 / xAspectRatioModeFactor) // to normalized device coords
+    : dX => dX;
+  const transformPanY = isNdc
+    ? dY => (dY / height) * 2 * (1.0 / yAspectRatioModeFactor) // to normalized device coords
+    : dY => -dY;
+
+  const transformScaleX = isNdc
+    ? x => ((-1 + (x / width) * 2) - xAlignmentTranslation) * (1.0 / xAspectRatioModeFactor)
+    : x => x;
+  const transformScaleY = isNdc
+    ? y => ((1 - (y / height) * 2) - yAlignmentTranslation) * (1.0 / yAspectRatioModeFactor)
+    : y => y;
+
+  const tick = () => {
+    if (isFixed) {
+      const isChanged = isProgrammaticallyChanged;
+      isProgrammaticallyChanged = false;
+      return isChanged;
+    }
+
+    isInteractivelyChanged = false;
+    const currentMouseX = mouseX;
+    const currentMouseY = mouseY;
+
+    if (
+      (isPanX || isPanY) &&
+      isLeftMousePressed &&
+      ((panOnMouseDownMove && !isMouseDownMoveModActive) ||
+        (!panOnMouseDownMove && isMouseDownMoveModActive))
+    ) {
+      const dX = isPanXInverted
+        ? prevMouseX - currentMouseX
+        : currentMouseX - prevMouseX;
+
+      const transformedPanX = isPanX ? transformPanX(panSpeed * dX) : 0;
+
+      const dY = isPanYInverted
+        ? prevMouseY - currentMouseY
+        : currentMouseY - prevMouseY;
+
+      const transformedPanY = isPanY ? transformPanY(panSpeed * dY) : 0;
+
+      if (transformedPanX !== 0 || transformedPanY !== 0) {
+        camera.pan([transformedPanX, transformedPanY]);
+        isInteractivelyChanged = true;
+      }
+    }
+
+    if ((isZoomX || isZoomY) && scrollDist) {
+      const dZ = zoomSpeed * Math.exp(scrollDist / height);
+
+      const transformedX = transformScaleX(mouseRelX);
+      const transformedY = transformScaleY(mouseRelY);
+
+      camera.scale(
+        [isZoomX ? 1 / dZ : 1, isZoomY ? 1 / dZ : 1],
+        [transformedX, transformedY]
+      );
+
+      isInteractivelyChanged = true;
+    }
+
+    if (
+      isRotate &&
+      isLeftMousePressed &&
+      ((panOnMouseDownMove && isMouseDownMoveModActive) ||
+        (!panOnMouseDownMove && !isMouseDownMoveModActive)) &&
+      Math.abs(prevMouseX - currentMouseX) +
+        Math.abs(prevMouseY - currentMouseY) >
+        0
+    ) {
+      const wh = width / 2;
+      const hh = height / 2;
+      const x1 = prevMouseX - wh;
+      const y1 = hh - prevMouseY;
+      const x2 = currentMouseX - wh;
+      const y2 = hh - currentMouseY;
+      // Angle between the start and end mouse position with respect to the
+      // viewport center
+      const radians = vec2.angle([x1, y1], [x2, y2]);
+      // Determine the orientation
+      const cross = x1 * y2 - x2 * y1;
+
+      camera.rotate(rotateSpeed * radians * Math.sign(cross));
+
+      isInteractivelyChanged = true;
+    }
+
+    // Reset scroll delta and mouse position
+    scrollDist = 0;
+    prevMouseX = currentMouseX;
+    prevMouseY = currentMouseY;
+
+    const isChanged = isInteractivelyChanged || isProgrammaticallyChanged;
+
+    isProgrammaticallyChanged = false;
+
+    return isChanged;
+  };
+
+  const config = ({
+    defaultMouseDownMoveAction: newDefaultMouseDownMoveAction = null,
+    isFixed: newIsFixed = null,
+    isPan: newIsPan = null,
+    isPanInverted: newIsPanInverted = null,
+    isRotate: newIsRotate = null,
+    isZoom: newIsZoom = null,
+    panSpeed: newPanSpeed = null,
+    rotateSpeed: newRotateSpeed = null,
+    zoomSpeed: newZoomSpeed = null,
+    mouseDownMoveModKey: newMouseDownMoveModKey = null
+  } = {}) => {
+    defaultMouseDownMoveAction =
+      newDefaultMouseDownMoveAction !== null &&
+      MOUSE_DOWN_MOVE_ACTIONS.includes(newDefaultMouseDownMoveAction)
+        ? newDefaultMouseDownMoveAction
+        : defaultMouseDownMoveAction;
+
+    panOnMouseDownMove = defaultMouseDownMoveAction === "pan";
+
+    isFixed = newIsFixed !== null ? newIsFixed : isFixed;
+    isPan = newIsPan !== null ? newIsPan : isPan;
+    isPanInverted =
+      newIsPanInverted !== null ? newIsPanInverted : isPanInverted;
+    isRotate = newIsRotate !== null ? newIsRotate : isRotate;
+    isZoom = newIsZoom !== null ? newIsZoom : isZoom;
+    panSpeed = +newPanSpeed > 0 ? newPanSpeed : panSpeed;
+    rotateSpeed = +newRotateSpeed > 0 ? newRotateSpeed : rotateSpeed;
+    zoomSpeed = +newZoomSpeed > 0 ? newZoomSpeed : zoomSpeed;
+
+    spreadXYSettings();
+
+    mouseDownMoveModKey =
+      newMouseDownMoveModKey !== null &&
+      Object.keys(KEY_MAP).includes(newMouseDownMoveModKey)
+        ? newMouseDownMoveModKey
+        : mouseDownMoveModKey;
+  };
+
+  const refresh = () => {
+    const bBox = element.getBoundingClientRect();
+    width = bBox.width;
+    height = bBox.height;
+    aspectRatio = width / height;
+    updateAspectRatioModeFactors();
+  };
+
+  const keyUpHandler = event => {
+    isMouseDownMoveModActive = false;
+
+    onKeyUp(event);
+  };
+
+  const keyDownHandler = event => {
+    isMouseDownMoveModActive = event[KEY_MAP[mouseDownMoveModKey]];
+
+    onKeyDown(event);
+  };
+
+  const mouseUpHandler = event => {
+    isLeftMousePressed = false;
+
+    onMouseUp(event);
+  };
+
+  const mouseDownHandler = event => {
+    isLeftMousePressed = event.buttons === 1;
+
+    onMouseDown(event);
+  };
+
+  const offsetXSupport =
+    document.createEvent("MouseEvent").offsetX !== undefined;
+
+  const updateMouseRelXY = offsetXSupport
+    ? event => {
+        mouseRelX = event.offsetX;
+        mouseRelY = event.offsetY;
+      }
+    : event => {
+        const bBox = element.getBoundingClientRect();
+        mouseRelX = event.clientX - bBox.left;
+        mouseRelY = event.clientY - bBox.top;
+      };
+
+  const updateMouseXY = event => {
+    mouseX = event.clientX;
+    mouseY = event.clientY;
+  };
+
+  const mouseMoveHandler = event => {
+    updateMouseXY(event);
+    onMouseMove(event);
+  };
+
+  const wheelHandler = event => {
+    if ((isZoomX || isZoomY) && !isFixed) {
+      event.preventDefault();
+
+      updateMouseXY(event);
+      updateMouseRelXY(event);
+
+      const scale = event.deltaMode === 1 ? 12 : 1;
+
+      scrollDist += scale * (event.deltaY || event.deltaX || 0);
+    }
+
+    onWheel(event);
+  };
+
+  const dispose = () => {
+    camera = undefined;
+    element.removeEventListener("keydown", keyDownHandler);
+    element.removeEventListener("keyup", keyUpHandler);
+    element.removeEventListener("mousedown", mouseDownHandler);
+    element.removeEventListener("mouseup", mouseUpHandler);
+    element.removeEventListener("mousemove", mouseMoveHandler);
+    element.removeEventListener("wheel", wheelHandler);
+  };
+
+  element.addEventListener("keydown", keyDownHandler, { passive: true });
+  element.addEventListener("keyup", keyUpHandler, { passive: true });
+  element.addEventListener("mousedown", mouseDownHandler, { passive: true });
+  element.addEventListener("mouseup", mouseUpHandler, { passive: true });
+  element.addEventListener("mousemove", mouseMoveHandler, { passive: true });
+  element.addEventListener("wheel", wheelHandler, { passive: false });
+
+  camera.config = config;
+  camera.dispose = dispose;
+  camera.refresh = refresh;
+  camera.tick = tick;
+
+  const withProgrammaticChange = fn =>
+    function() {
+      fn.apply(null, arguments);
+      isProgrammaticallyChanged = true;
+    };
+
+  camera.lookAt = withProgrammaticChange(camera.lookAt);
+  camera.translate = withProgrammaticChange(camera.translate);
+  camera.pan = withProgrammaticChange(camera.pan);
+  camera.rotate = withProgrammaticChange(camera.rotate);
+  camera.scale = withProgrammaticChange(camera.scale);
+  camera.zoom = withProgrammaticChange(camera.zoom);
+  camera.reset = withProgrammaticChange(camera.reset);
+  camera.set = withProgrammaticChange(camera.set);
+  camera.setScaleBounds = withProgrammaticChange(camera.setScaleBounds);
+  camera.setTranslationBounds = withProgrammaticChange(
+    camera.setTranslationBounds
+  );
+  camera.setView = withProgrammaticChange(camera.setView);
+  camera.setViewCenter = withProgrammaticChange(camera.setViewCenter);
+
+  refresh();
+
+  return camera;
+};
+
+export default dom2dCamera;

package/src/feature-detection.ts

@@ -0,0 +1,57 @@
+import UserAgent from "lightua";
+
+// Returns the tuple [supportsWebGpu, supportsWebGpuMessage]
+export function checkWebGpuFeatureDetection(): [boolean, string|null] {
+  const isSupported = typeof navigator !== 'undefined' && navigator.gpu;
+  if (isSupported) {
+    return [true, null];
+  }
+  const ua = UserAgent.parse(navigator.userAgent);
+  // WebGPU is supported in the following cases:
+  // - Browser Engine: Chromium. Major: 113+. OS: mac, windows, chromeOS
+  // - Browser Engine: Chromium. Major: 121+. OS: android
+  // - Browser Engine: Chromium. Major: 144+. OS: linux
+  // - Browser: Firefox. Major: 141+. OS: windows
+  // - Browser: Firefox. Major: 145+. OS: macos
+  // - Browser: Safari. Major: 26+. OS: macOS. OS version: tahoe 26+.
+  // - Browser: Safari. Major: 26+. OS: iOS/iPadOS. OS version: tahoe 26+.
+  // Else: suggest upgrading browser version or OS version (if different version of same browser has support)
+  // Else: suggest using different browser version.
+  const browserName = ua.browser.name;
+  const browserMajor = ua.browser.major;
+  const osName = ua.os.name;
+  const osVersion = ua.os.version;
+
+  // Should be supported according to UA but support wasn't detected.
+  const shouldSupportResult: [boolean, string|null] = [false, `WebGPU support was not detected. Please ensure the WebGPU feature is enabled or try a different browser.`];
+
+  if(["Chrome", "Chromium"].includes(browserName)) {
+    if(["Windows", "macOS", "ChromeOS"].includes(osName)) {
+      if(browserMajor < 113) {
+        return [false, `WebGPU is not supported in your web browser. If using Chrome or a Chromium-based browser on Windows/macOS/ChromeOS, WebGPU is supported in browser versions 113 and above.`];
+      }
+    } else if(osName === "Android") {
+      if(browserMajor < 121) {
+        return [false, `WebGPU is not supported in your web browser. If using Chrome or a Chromium-based browser on Android, WebGPU is supported in browser versions 121 and above.`];
+      }
+    } else if(osName === "Linux") {
+      if(browserMajor < 144) {
+        return [false, `WebGPU is not supported in your web browser. If using Chrome or a Chromium-based browser on Linux, WebGPU is supported in browser versions 144 and above.`];
+      }
+    }
+  } else if(browserName === "Firefox") {
+    if(osName === "Windows") {
+      if(browserMajor < 141) {
+        return [false, `WebGPU is not supported in your web browser. If using Firefox on Windows, WebGPU is supported in browser versions 141 and above.`];
+      }
+    }
+  } else if(browserName === "Safari") {
+    if(["macOS", "iOS"].includes(osName)) {
+      const osVersionFloat = parseFloat(osVersion);
+      if(browserMajor < 26 || osVersionFloat < 26) {
+        return [false, `WebGPU is not supported in your web browser. If using Safari, WebGPU is supported in Safari version 26 and above on macOS 26 (Tahoe) and above.`];
+      }
+    }
+  }
+  return shouldSupportResult;
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export {
+  initialize,
+  getIsWasmReady,
+  render_wasm,
+  pick_wasm,
+  setStore,
+  setStoreByName,
+  getStore,
+} from './core.js';
+export { default as create2dCamera } from "./dom-2d-camera.js";
+export { default as create3dCamera } from "./3d-view-controls.js";
+export { checkWebGpuFeatureDetection } from './feature-detection.js';
+export { getBounds, getCameraMatrixFromBounds } from './viewport.js';

package/src/lru-store.ts

@@ -0,0 +1,155 @@
+import QuickLRU from "quick-lru";
+
+import type { RangeQuery, AsyncReadable, AbsolutePath } from 'zarrita';
+
+
+function normalizeKey(key: string, range?: RangeQuery) {
+  if (!range) return key;
+  if ("suffixLength" in range) return `${key}:-${range.suffixLength}`;
+  return `${key}:${range.offset}:${range.offset + range.length - 1}`;
+}
+
+// Provides a blanket implementation of getRange that can be used with any AsyncReadable store,
+// even if it doesn't define a getRange method.
+// If the store does have a native getRange method, we use that instead.
+// Reference: https://github.com/vitessce/vitessce/blob/main/packages/utils/zarr-utils/src/base-getrange.ts
+export function createGetRange<S extends AsyncReadable>(store: S) {
+  // TODO: support options param for getRange?
+  return async (...args: Parameters<NonNullable<S["getRange"]>>): Promise<Uint8Array | undefined> => {
+    const [key, range, opts] = args;
+    if (typeof store.getRange === 'function') {
+      return store.getRange(key, range, opts);
+    }
+    // Store does not have a native getRange method; falling back to get. This may be inefficient for large data.
+    const arr = await store.get(key, opts);
+    if (!arr) return undefined;
+    const { buffer } = arr;
+    if ('suffixLength' in range) {
+      const { suffixLength } = range;
+      return new Uint8Array(buffer, buffer.byteLength - suffixLength, suffixLength);
+    }
+    if ('offset' in range && 'length' in range) {
+      const { offset, length } = range;
+      return new Uint8Array(buffer, offset, length);
+    }
+    throw new Error('Invalid rangeQuery value.');
+  };
+}
+
+// A class-based version of the proxy-based lru() function from vizarr.
+// Reference: https://github.com/hms-dbmi/vizarr/blob/862745c1c7c095748bbe97475da61807d5b49189/src/lru-store.ts
+export class LruStore<S extends AsyncReadable> implements AsyncReadable {
+  #inner_store: S;
+
+  #cache: QuickLRU<string, [Promise<Uint8Array | undefined>, AbortController]>;
+
+  // We need a way to synchronously peek at the promise state (a-la Bun's peek or Effect's Deferred.poll).
+  // We can probably do something more sophisticated but will try this first.
+  #promise_states: Map<string, 'pending' | 'fulfilled' | 'rejected'>;
+
+  constructor(store: S, maxSize = 100) {
+    this.#inner_store = store;
+    this.#promise_states = new Map();
+    this.#cache = new QuickLRU({
+      maxSize,
+      onEviction: (key, _value) => {
+        this.#promise_states.delete(key);
+      },
+    });
+  }
+
+  async get(...args: Parameters<S["get"]>): Promise<Uint8Array | undefined> {
+    const [key, opts] = args;
+    // console.log(`LRU get: ${key}`);
+    const cacheKey = normalizeKey(key);
+    const cached = this.#cache.get(cacheKey);
+    if (cached) {
+      return cached[0];
+    }
+    const controller = new AbortController();
+    let getResult = this.#inner_store.get(key, {
+      signal: controller.signal,
+      ...(opts ?? {})
+    });
+
+    const getResultPromise = Promise.resolve(getResult);
+    this.#promise_states.set(cacheKey, 'pending');
+
+    const result = getResultPromise.then((val) => {
+      this.#promise_states.set(cacheKey, 'fulfilled');
+      return val;
+    }).catch((err) => {
+      this.#promise_states.set(cacheKey, 'rejected');
+      this.#cache.delete(cacheKey);
+      throw err;
+    });
+    this.#cache.set(cacheKey, [result, controller]);
+    return result;
+  }
+
+  // Synchronously peek at the promise state.
+  getPeek(...args: Parameters<S["get"]>): 'pending' | 'fulfilled' | 'rejected' | undefined {
+    this.get(...args); // Kick off the promise but do not await. TODO: do we want to do this here?
+    const [key, opts] = args;
+    // console.log(`LRU getPeek: ${key}`);
+    const cacheKey = normalizeKey(key);
+    return this.#promise_states.get(cacheKey);
+  }
+
+  async getRange(...args: Parameters<NonNullable<S["getRange"]>>): Promise<Uint8Array | undefined> {
+    const [key, range, opts] = args;
+    const cacheKey = normalizeKey(key, range);
+    const cached = this.#cache.get(cacheKey);
+    if (cached) {
+      return cached[0];
+    }
+
+    const _getRange = typeof this.#inner_store.getRange === 'function'
+      ? this.#inner_store.getRange.bind(this.#inner_store)
+      : createGetRange(this.#inner_store);
+
+    const controller = new AbortController();
+    // @ts-expect-error
+    let getRangeResult = _getRange(key, range, {
+      signal: controller.signal,
+      ...(opts ?? {})
+    });
+
+    const getRangeResultPromise = Promise.resolve(getRangeResult);
+    this.#promise_states.set(cacheKey, 'pending');
+
+    const result = getRangeResultPromise.then((val) => {
+      this.#promise_states.set(cacheKey, 'fulfilled');
+      return val;
+    }).catch((err) => {
+      this.#promise_states.set(cacheKey, 'rejected');
+      this.#cache.delete(cacheKey);
+      throw err;
+    });
+    this.#cache.set(cacheKey, [result, controller]);
+    return result;
+  }
+
+  // Synchronously peek at the promise state.
+  getRangePeek(...args: Parameters<NonNullable<S["getRange"]>>): 'pending' | 'fulfilled' | 'rejected' | undefined {
+    this.getRange(...args); // Kick off the promise but do not await. TODO: do we want to do this here?
+    const [key, range, opts] = args;
+    const cacheKey = normalizeKey(key, range);
+    return this.#promise_states.get(cacheKey);
+  }
+
+  clearCache() {
+    // Use AbortSignal in clearCache for promises that have not yet been resolved.
+    this.#cache.forEach(([promise, controller]) => {
+      // TODO: check if promise is still pending before aborting? Or just always abort?
+      // TODO: verify that this aborting is actually working
+      controller.abort()
+    });
+    this.#cache.clear();
+    this.#promise_states = new Map();
+  }
+}
+
+export function lru(inner_store: AsyncReadable, maxSize = 100): LruStore<AsyncReadable> {
+  return new LruStore(inner_store, maxSize);
+}