@isograph/react-disposable-state 0.0.0-main-9a9a4679 → 0.0.0-main-c8dd6185

package/dist/CacheItem.d.ts

@@ -21,21 +21,25 @@ export type CacheItemOptions = {
     temporaryRetainTime: number;
 };
 /**
+ * CacheItem:
+ *
+ * Terminology:
  * - 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
+ *   In parent cache? | Item disposed? | TRC | PRC | Name
+ *   -----------------+----------------+-----+-----+-------------------------------
+ *   In parent cache  | Not disposed   | >0  | >=0 | InParentCacheAndNotDisposed
+ *   Removed          | Not disposed   |  0  |  >0 | NotInParentCacheAndNotDisposed
+ *   Removed          | Disposed       |  0  |   0 | NotInParentCacheAndNotDisposed
+ *
+ * A cache item can only move down rows. As in, if its in the parent cache,
+ * it can be removed. It can never be replaced in the parent cache. (If a
+ * parent cache becomes full again, it will contain a new CacheItem.) The
+ * contained item can be disposed, but never un-disposed.
  *
- * Valid transitions are:
+ * So, the valid transitions are:
  * - InParentCacheAndNotDisposed => NotInParentCacheAndNotDisposed
  * - InParentCacheAndNotDisposed => NotInParentCacheAndDisposed
  * - NotInParentCacheAndNotDisposed => NotInParentCacheAndDisposed

package/dist/CacheItem.js

@@ -5,21 +5,25 @@ const DEFAULT_TEMPORARY_RETAIN_TIME = 5000;
 // TODO don't export this class, only export type (interface) instead
 // TODO convert cacheitem impl to a getter and setter and free functions
 /**
+ * CacheItem:
+ *
+ * Terminology:
  * - 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
+ *   In parent cache? | Item disposed? | TRC | PRC | Name
+ *   -----------------+----------------+-----+-----+-------------------------------
+ *   In parent cache  | Not disposed   | >0  | >=0 | InParentCacheAndNotDisposed
+ *   Removed          | Not disposed   |  0  |  >0 | NotInParentCacheAndNotDisposed
+ *   Removed          | Disposed       |  0  |   0 | NotInParentCacheAndNotDisposed
+ *
+ * A cache item can only move down rows. As in, if its in the parent cache,
+ * it can be removed. It can never be replaced in the parent cache. (If a
+ * parent cache becomes full again, it will contain a new CacheItem.) The
+ * contained item can be disposed, but never un-disposed.
  *
- * Valid transitions are:
+ * So, the valid transitions are:
  * - InParentCacheAndNotDisposed => NotInParentCacheAndNotDisposed
  * - InParentCacheAndNotDisposed => NotInParentCacheAndDisposed
  * - NotInParentCacheAndNotDisposed => NotInParentCacheAndDisposed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isograph/react-disposable-state",
-  "version": "0.0.0-main-9a9a4679",
+  "version": "0.0.0-main-c8dd6185",
   "description": "Primitives for managing disposable state in React",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,7 +16,7 @@
     "prepack": "yarn run compile"
   },
   "dependencies": {
-    "@isograph/disposable-types": "0.0.0-main-9a9a4679",
+    "@isograph/disposable-types": "0.0.0-main-c8dd6185",
     "react": "^18.2.0"
   },
   "devDependencies": {

package/src/CacheItem.ts

@@ -43,21 +43,25 @@ export type CacheItemOptions = {
 // TODO convert cacheitem impl to a getter and setter and free functions
 
 /**
+ * CacheItem:
+ *
+ * Terminology:
  * - 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
+ *   In parent cache? | Item disposed? | TRC | PRC | Name
+ *   -----------------+----------------+-----+-----+-------------------------------
+ *   In parent cache  | Not disposed   | >0  | >=0 | InParentCacheAndNotDisposed
+ *   Removed          | Not disposed   |  0  |  >0 | NotInParentCacheAndNotDisposed
+ *   Removed          | Disposed       |  0  |   0 | NotInParentCacheAndNotDisposed
+ *
+ * A cache item can only move down rows. As in, if its in the parent cache,
+ * it can be removed. It can never be replaced in the parent cache. (If a
+ * parent cache becomes full again, it will contain a new CacheItem.) The
+ * contained item can be disposed, but never un-disposed.
  *
- * Valid transitions are:
+ * So, the valid transitions are:
  * - InParentCacheAndNotDisposed => NotInParentCacheAndNotDisposed
  * - InParentCacheAndNotDisposed => NotInParentCacheAndDisposed
  * - NotInParentCacheAndNotDisposed => NotInParentCacheAndDisposed

package/src/ParentCache.test.ts

@@ -4,36 +4,40 @@ 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;
+  return (cache as any).__cacheItem 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);
+  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, 'Parent cache should not be empty');
+
+      parentCache.empty();
+      assert(getValue(parentCache) === null);
 
-    const [_cacheItem, value, clearTemporaryRetain] =
       parentCache.getOrPopulateAndTemporaryRetain();
+      expect(factory.mock.calls.length).toBe(2);
 
-    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);
 
-    assert(getValue(parentCache) != null);
+      clearTemporaryRetain();
 
-    clearTemporaryRetain();
-
-    assert(getValue(parentCache) != null);
-  });
+      assert(getValue(parentCache) != null);
+    },
+  );
 
   test('Clearing the only temporary retain removes the item from the parent cache', () => {
     const factory = vi.fn(() => {

package/src/useCachedPrecommitValue.test.tsx

@@ -7,7 +7,7 @@ import { create } from 'react-test-renderer';
 import { CacheItem, CacheItemState } from './CacheItem';
 
 function getItem<T>(cache: ParentCache<T>): CacheItem<T> | null {
-  return (cache as any).__item;
+  return (cache as any).__cacheItem;
 }
 
 function getState<T>(cacheItem: CacheItem<T>): CacheItemState<T> {
@@ -512,9 +512,8 @@ describe('useCachedPrecommitValue', () => {
   );
 
   test(
-    'If the component unmounts before committing, ' +
-      'the item will remain in the parent cache, ' +
-      'temporarily retained',
+    'After render but before commit, the item will ' +
+      'be in the parent cache, temporarily retained',
     async () => {
       const disposeItem = vi.fn();
       const factory = vi.fn(() => {
@@ -541,35 +540,20 @@ describe('useCachedPrecommitValue', () => {
       // wat is going on?
       //
       // We want to test a scenario where the component unmounts before committing.
+      // However, we cannot distinguish between an unmount before commit and a
+      // render and a commit that hasn't happened yet.
       //
-      // The subcomponents are rendered in order: TestComponent followed by CodeExecutor.
-      // So, during CodeExecutor, we trigger a state update that causes the ParentComponent
-      // to not render the children.
-      function CodeExecutor() {
-        setShowChildren(false);
-        return null;
-      }
-
-      let setShowChildren;
-      function ParentComponent({ children }) {
-        const [showChildren, _setShowChildren] = React.useState(true);
-        setShowChildren = _setShowChildren;
-
-        if (showChildren) {
-          return children;
-        } else {
-          return null;
-        }
-      }
+      // This can be simulated with suspense.
+      //
+      // This test and 'on initial render, it should call getOrPopulateAndTemporaryRetain'
+      // can be merged
 
+      const { promise, isResolvedRef } = promiseAndResolver();
       const element = await awaitableCreate(
-        <ParentComponent>
+        <React.Suspense fallback={null}>
           <TestComponent />
-          <CodeExecutor />
-        </ParentComponent>,
-        // If we're not in concurrent mode, TestComponent will mount before
-        // unmounting. This perhaps is a bug in react-test-renderer. Regardless,
-        // we're not interested in that scenario.
+          <Suspender promise={promise} isResolvedRef={isResolvedRef} />
+        </React.Suspense>,
         true,
       );