@isograph/react-disposable-state 0.0.0-main-4ef7c123

package/src/CacheItem.ts

@@ -0,0 +1,364 @@
+import {
+  CleanupFn,
+  Factory,
+  ItemCleanupPair,
+} from "@isograph/disposable-types";
+
+const DEFAULT_TEMPORARY_RETAIN_TIME = 5000;
+
+export type NotInParentCacheAndDisposed = {
+  kind: "NotInParentCacheAndDisposed";
+};
+export type NotInParentCacheAndNotDisposed<T> = {
+  kind: "NotInParentCacheAndNotDisposed";
+  value: T;
+  disposeValue: () => void;
+
+  // Invariant: >0
+  permanentRetainCount: number;
+};
+export type InParentCacheAndNotDisposed<T> = {
+  kind: "InParentCacheAndNotDisposed";
+  value: T;
+  disposeValue: () => void;
+  removeFromParentCache: () => void;
+
+  // Invariant: >0
+  temporaryRetainCount: number;
+
+  // Invariant: >= 0
+  permanentRetainCount: number;
+};
+
+export type CacheItemState<T> =
+  | InParentCacheAndNotDisposed<T>
+  | NotInParentCacheAndNotDisposed<T>
+  | NotInParentCacheAndDisposed;
+
+export type CacheItemOptions = {
+  temporaryRetainTime: number;
+};
+
+// TODO don't export this class, only export type (interface) instead
+// TODO convert cacheitem impl to a getter and setter and free functions
+
+/**
+ * - TRC = Temporary Retain Count
+ * - PRC = Permanent Retain Count
+ *
+ * Rules:
+ * - In parent cache <=> TRC > 0
+ * - Removed from parent cache <=> TRC === 0
+ * - In parent cache => not disposed
+ * - Disposed => removed from parent cache + PRC === 0
+ *
+ * A CacheItem<T> can be in three states:
+ * - Removed from the parent cache, item disposed, TRC === 0, PRC === 0
+ * - Removed from the parent cache, item not disposed, PRC > 0, TRC === 0
+ * - In parent cache, item not disposed, TRC > 0, PRC >= 0
+ *
+ * Valid transitions are:
+ * - InParentCacheAndNotDisposed => NotInParentCacheAndNotDisposed
+ * - InParentCacheAndNotDisposed => NotInParentCacheAndDisposed
+ * - NotInParentCacheAndNotDisposed => NotInParentCacheAndDisposed
+ */
+export class CacheItem<T> {
+  private __state: CacheItemState<T>;
+  private __options: CacheItemOptions | null;
+
+  // Private. Do not call this constructor directly. Use
+  // createTemporarilyRetainedCacheItem instead. This is because this
+  // constructor creates a CacheItem in an invalid state. It must be
+  // temporarily retained to enter a valid state, and JavaScript doesn't
+  // let you return a tuple from a constructor.
+  constructor(
+    factory: Factory<T>,
+    removeFromParentCache: CleanupFn,
+    options: CacheItemOptions | void
+  ) {
+    this.__options = options ?? null;
+    const [value, disposeValue] = factory();
+    this.__state = {
+      kind: "InParentCacheAndNotDisposed",
+      value,
+      disposeValue,
+      removeFromParentCache,
+      // NOTE: we are creating the CacheItem in an invalid state. This is okay, because
+      // we are immediately calling .temporaryRetain.
+      temporaryRetainCount: 0,
+      permanentRetainCount: 0,
+    };
+  }
+
+  getValue(): T {
+    switch (this.__state.kind) {
+      case "InParentCacheAndNotDisposed": {
+        return this.__state.value;
+      }
+      case "NotInParentCacheAndNotDisposed": {
+        return this.__state.value;
+      }
+      default: {
+        throw new Error(
+          "Attempted to access disposed value from CacheItem. " +
+            "This indicates a bug in react-disposable-state."
+        );
+      }
+    }
+  }
+
+  permanentRetainIfNotDisposed(
+    disposeOfTemporaryRetain: CleanupFn
+  ): ItemCleanupPair<T> | null {
+    switch (this.__state.kind) {
+      case "InParentCacheAndNotDisposed": {
+        let cleared = false;
+        this.__state.permanentRetainCount++;
+        disposeOfTemporaryRetain();
+        return [
+          this.__state.value,
+          () => {
+            if (cleared) {
+              throw new Error(
+                "A permanent retain should only be cleared once. " +
+                  "This indicates a bug in react-disposable-state."
+              );
+            }
+            cleared = true;
+            switch (this.__state.kind) {
+              case "InParentCacheAndNotDisposed": {
+                this.__state.permanentRetainCount--;
+                this.__maybeExitInParentCacheAndNotDisposedState(this.__state);
+                return;
+              }
+              case "NotInParentCacheAndNotDisposed": {
+                this.__state.permanentRetainCount--;
+                this.__maybeExitNotInParentCacheAndNotDisposedState(
+                  this.__state
+                );
+                return;
+              }
+              default: {
+                throw new Error(
+                  "CacheItem was in a disposed state, but there existed a permanent retain. " +
+                    "This indicates a bug in react-disposable-state."
+                );
+              }
+            }
+          },
+        ];
+      }
+      case "NotInParentCacheAndNotDisposed": {
+        let cleared = false;
+        this.__state.permanentRetainCount++;
+        disposeOfTemporaryRetain();
+        return [
+          this.__state.value,
+          () => {
+            if (cleared) {
+              throw new Error(
+                "A permanent retain should only be cleared once. " +
+                  "This indicates a bug in react-disposable-state."
+              );
+            }
+            cleared = true;
+            switch (this.__state.kind) {
+              case "NotInParentCacheAndNotDisposed": {
+                this.__state.permanentRetainCount--;
+                this.__maybeExitNotInParentCacheAndNotDisposedState(
+                  this.__state
+                );
+                return;
+              }
+              default: {
+                throw new Error(
+                  "CacheItem was in an unexpected state. " +
+                    "This indicates a bug in react-disposable-state."
+                );
+              }
+            }
+          },
+        ];
+      }
+      default: {
+        // The CacheItem is disposed, so disposeOfTemporaryRetain is a no-op
+        return null;
+      }
+    }
+  }
+
+  temporaryRetain(): CleanupFn {
+    type TemporaryRetainStatus =
+      | "Uncleared"
+      | "ClearedByCallback"
+      | "ClearedByTimeout";
+
+    switch (this.__state.kind) {
+      case "InParentCacheAndNotDisposed": {
+        let status: TemporaryRetainStatus = "Uncleared";
+        this.__state.temporaryRetainCount++;
+        const clearTemporaryRetainByCallack: CleanupFn = () => {
+          if (status === "ClearedByCallback") {
+            throw new Error(
+              "A temporary retain should only be cleared once. " +
+                "This indicates a bug in react-disposable-state."
+            );
+          } else if (status === "Uncleared") {
+            switch (this.__state.kind) {
+              case "InParentCacheAndNotDisposed": {
+                this.__state.temporaryRetainCount--;
+                this.__maybeExitInParentCacheAndNotDisposedState(this.__state);
+                clearTimeout(timeoutId);
+                return;
+              }
+              default: {
+                throw new Error(
+                  "A temporary retain was cleared, for which the CacheItem is in an invalid state. " +
+                    "This indicates a bug in react-disposable-state."
+                );
+              }
+            }
+          }
+        };
+
+        const clearTemporaryRetainByTimeout = () => {
+          status = "ClearedByTimeout";
+          switch (this.__state.kind) {
+            case "InParentCacheAndNotDisposed": {
+              this.__state.temporaryRetainCount--;
+              this.__maybeExitInParentCacheAndNotDisposedState(this.__state);
+              return;
+            }
+            default: {
+              throw new Error(
+                "A temporary retain was cleared, for which the CacheItem is in an invalid state. " +
+                  "This indicates a bug in react-disposable-state."
+              );
+            }
+          }
+        };
+
+        const timeoutId = setTimeout(
+          clearTemporaryRetainByTimeout,
+          this.__options?.temporaryRetainTime ?? DEFAULT_TEMPORARY_RETAIN_TIME
+        );
+        return clearTemporaryRetainByCallack;
+      }
+      default: {
+        throw new Error(
+          "temporaryRetain was called, for which the CacheItem is in an invalid state. " +
+            "This indicates a bug in react-disposable-state."
+        );
+      }
+    }
+  }
+
+  permanentRetain(): CleanupFn {
+    switch (this.__state.kind) {
+      case "InParentCacheAndNotDisposed": {
+        let cleared = false;
+        this.__state.permanentRetainCount++;
+        return () => {
+          if (cleared) {
+            throw new Error(
+              "A permanent retain should only be cleared once. " +
+                "This indicates a bug in react-disposable-state."
+            );
+          }
+          cleared = true;
+          switch (this.__state.kind) {
+            case "InParentCacheAndNotDisposed": {
+              this.__state.permanentRetainCount--;
+              this.__maybeExitInParentCacheAndNotDisposedState(this.__state);
+              return;
+            }
+            case "NotInParentCacheAndNotDisposed": {
+              this.__state.permanentRetainCount--;
+              this.__maybeExitNotInParentCacheAndNotDisposedState(this.__state);
+              return;
+            }
+            default: {
+              throw new Error(
+                "CacheItem was in a disposed state, but there existed a permanent retain. " +
+                  "This indicates a bug in react-disposable-state."
+              );
+            }
+          }
+        };
+      }
+      case "NotInParentCacheAndNotDisposed": {
+        let cleared = false;
+        this.__state.permanentRetainCount++;
+        return () => {
+          if (cleared) {
+            throw new Error(
+              "A permanent retain should only be cleared once. " +
+                "This indicates a bug in react-disposable-state."
+            );
+          }
+          cleared = true;
+          switch (this.__state.kind) {
+            case "NotInParentCacheAndNotDisposed": {
+              this.__state.permanentRetainCount--;
+              this.__maybeExitNotInParentCacheAndNotDisposedState(this.__state);
+              return;
+            }
+            default: {
+              throw new Error(
+                "CacheItem was in an unexpected state. " +
+                  "This indicates a bug in react-disposable-state."
+              );
+            }
+          }
+        };
+      }
+      default: {
+        throw new Error(
+          "permanentRetain was called, but the CacheItem is in an invalid state. " +
+            "This indicates a bug in react-disposable-state."
+        );
+      }
+    }
+  }
+
+  private __maybeExitInParentCacheAndNotDisposedState(
+    state: InParentCacheAndNotDisposed<T>
+  ) {
+    if (state.temporaryRetainCount === 0 && state.permanentRetainCount === 0) {
+      state.removeFromParentCache();
+      state.disposeValue();
+      this.__state = {
+        kind: "NotInParentCacheAndDisposed",
+      };
+    } else if (state.temporaryRetainCount === 0) {
+      state.removeFromParentCache();
+      this.__state = {
+        kind: "NotInParentCacheAndNotDisposed",
+        value: state.value,
+        disposeValue: state.disposeValue,
+        permanentRetainCount: state.permanentRetainCount,
+      };
+    }
+  }
+
+  private __maybeExitNotInParentCacheAndNotDisposedState(
+    state: NotInParentCacheAndNotDisposed<T>
+  ) {
+    if (state.permanentRetainCount === 0) {
+      state.disposeValue();
+      this.__state = {
+        kind: "NotInParentCacheAndDisposed",
+      };
+    }
+  }
+}
+
+export function createTemporarilyRetainedCacheItem<T>(
+  factory: Factory<T>,
+  removeFromParentCache: CleanupFn,
+  options: CacheItemOptions | void
+): [CacheItem<T>, CleanupFn] {
+  const cacheItem = new CacheItem(factory, removeFromParentCache, options);
+  const disposeTemporaryRetain = cacheItem.temporaryRetain();
+  return [cacheItem, disposeTemporaryRetain];
+}

package/src/ParentCache.test.ts

@@ -0,0 +1,70 @@
+import { describe, assert, test, vi, expect } from "vitest";
+import { ParentCache } from "./ParentCache";
+import { ItemCleanupPair } from "@isograph/disposable-types";
+import { CacheItem } from "./CacheItem";
+
+function getValue<T>(cache: ParentCache<T>): CacheItem<T> | null {
+  return (cache as any).__item as CacheItem<T> | null;
+}
+
+describe("ParentCache", () => {
+  test("Populated, emptied, repopulated cache is not re-emptied by original temporary retain being disposed", () => {
+    const factory = vi.fn(() => {
+      const pair: ItemCleanupPair<number> = [1, vi.fn()];
+      return pair;
+    });
+    const parentCache = new ParentCache<number>(factory);
+
+    const [_cacheItem, value, clearTemporaryRetain] =
+      parentCache.getOrPopulateAndTemporaryRetain();
+
+    expect(factory.mock.calls.length).toBe(1);
+    assert(value === 1);
+    assert(getValue(parentCache) != null);
+
+    parentCache.empty();
+    assert(getValue(parentCache) === null);
+
+    parentCache.getOrPopulateAndTemporaryRetain();
+    expect(factory.mock.calls.length).toBe(2);
+
+    assert(getValue(parentCache) != null);
+
+    clearTemporaryRetain();
+
+    assert(getValue(parentCache) != null);
+  });
+
+  test("Clearing the only temporary retain removes the item from the parent cache", () => {
+    const factory = vi.fn(() => {
+      const pair: ItemCleanupPair<number> = [1, vi.fn()];
+      return pair;
+    });
+    const parentCache = new ParentCache<number>(factory);
+
+    const [_cacheItem, _value, clearTemporaryRetain] =
+      parentCache.getOrPopulateAndTemporaryRetain();
+    clearTemporaryRetain();
+
+    assert(getValue(parentCache) === null);
+  });
+
+  test("Clearing one of two temporary retains does not remove the item from the parent cache", () => {
+    const factory = vi.fn(() => {
+      const pair: ItemCleanupPair<number> = [1, vi.fn()];
+      return pair;
+    });
+    const parentCache = new ParentCache<number>(factory);
+
+    const [_cacheItem, _value, clearTemporaryRetain] =
+      parentCache.getOrPopulateAndTemporaryRetain();
+    const [_cacheItem2, _value2, clearTemporaryRetain2] =
+      parentCache.getOrPopulateAndTemporaryRetain();
+
+    clearTemporaryRetain();
+    assert(getValue(parentCache) != null);
+
+    clearTemporaryRetain2();
+    assert(getValue(parentCache) === null);
+  });
+});

package/src/ParentCache.ts

@@ -0,0 +1,100 @@
+import { CacheItem, createTemporarilyRetainedCacheItem } from "./CacheItem";
+import {
+  CleanupFn,
+  Factory,
+  ItemCleanupPair,
+} from "@isograph/disposable-types";
+
+// TODO convert cache impl to a getter and setter and free functions
+// TODO accept options that get passed to CacheItem
+
+/**
+ * ParentCache
+ * - A ParentCache can be in two states: populated and unpopulated.
+ * - A ParentCache holds a CacheItem, which can choose to remove itself from
+ *   the parent ParentCache.
+ * - If the ParentCache is populated, the CacheItem (i.e. this.__value) must be
+ *   in the InParentCacheAndNotDisposed state, i.e. not disposed, so after we
+ *   null-check this.__value, this.__value.getValue(), this.__value.temporaryRetain()
+ *   and this.__value.permanentRetain() are safe to be called.
+ *
+ * - Though we do not do so, it is always safe to call parentCache.delete().
+ *
+ * Invariant:
+ * - A parent cache at a given "location" (conceptually, an ID) should always
+ *   be called
+ */
+export class ParentCache<T> {
+  private __cacheItem: CacheItem<T> | null = null;
+  private readonly __factory: Factory<T>;
+
+  constructor(factory: Factory<T>) {
+    this.__factory = factory;
+  }
+
+  /**
+   * This is called from useCachedPrecommitValue, when the parent cache is populated
+   * and a previous temporary retain has been disposed. This can occur in scenarios like:
+   * - temporary retain A is created by component B rendering
+   * - temporary retain A expires, emptying the parent cache
+   * - another component renders, sharing the same parent cache, filling
+   *   by calling getOrPopulateAndTemporaryRetain
+   * - component B commits. We see that temporary retain A has been disposed,
+   *   and re-check the parent cache by calling this method.
+   */
+  getAndPermanentRetainIfPresent(): ItemCleanupPair<T> | null {
+    return this.__cacheItem != null
+      ? [this.__cacheItem.getValue(), this.__cacheItem.permanentRetain()]
+      : null;
+  }
+
+  getOrPopulateAndTemporaryRetain(): [CacheItem<T>, T, CleanupFn] {
+    return this.__cacheItem === null
+      ? this.__populateAndTemporaryRetain()
+      : temporaryRetain(this.__cacheItem);
+  }
+
+  private __populateAndTemporaryRetain(): [CacheItem<T>, T, CleanupFn] {
+    const pair: ItemCleanupPair<CacheItem<T>> =
+      createTemporarilyRetainedCacheItem(this.__factory, () => {
+        // We are doing this check because we don't want to remove the cache item
+        // if it is not the one that was created when the temporary retain was created.
+        //
+        // Consider the following scenario:
+        // - we populate the cache with CacheItem A,
+        // - then manually delete CacheItem A (e.g. to force a refetch)
+        // - then, we re-populate the parent cache with CacheItem B
+        // - then, the temporary retain of CacheItem A is disposed or expires.
+        //
+        // At this point, we don't want to delete CacheItem B from the cache.
+        //
+        // TODO consider what happens if items are === comparable to each other,
+        // e.g. the item is a number!
+        if (this.__cacheItem === pair[0]) {
+          this.empty();
+        }
+      });
+
+    // We deconstruct this here instead of at the definition site because otherwise,
+    // typescript thinks that cacheItem is any, because it's referenced in the closure.
+    const [cacheItem, disposeTemporaryRetain] = pair;
+    this.__cacheItem = cacheItem;
+    return [cacheItem, this.__cacheItem.getValue(), disposeTemporaryRetain];
+  }
+
+  empty() {
+    this.__cacheItem = null;
+  }
+
+  get factory(): Factory<T> {
+    return this.__factory;
+  }
+
+  isEmpty(): boolean {
+    return this.__cacheItem === null;
+  }
+}
+
+function temporaryRetain<T>(value: CacheItem<T>): [CacheItem<T>, T, CleanupFn] {
+  return [value, value.getValue(), value.temporaryRetain()];
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from "@isograph/disposable-types";
+
+export * from "./CacheItem";
+export * from "./ParentCache";
+export * from "./useCachedPrecommitValue";
+export * from "./useDisposableState";
+export * from "./useHasCommittedRef";
+export * from "./useLazyDisposableState";
+export * from "./useUpdatableDisposableState";