@isograph/react-disposable-state 0.0.4 → 0.1.1

package/src/CacheItem.ts

@@ -2,15 +2,15 @@ import {
   CleanupFn,
   Factory,
   ItemCleanupPair,
-} from "@isograph/disposable-types";
+} from '@isograph/disposable-types';
 
 const DEFAULT_TEMPORARY_RETAIN_TIME = 5000;
 
 export type NotInParentCacheAndDisposed = {
-  kind: "NotInParentCacheAndDisposed";
+  kind: 'NotInParentCacheAndDisposed';
 };
 export type NotInParentCacheAndNotDisposed<T> = {
-  kind: "NotInParentCacheAndNotDisposed";
+  kind: 'NotInParentCacheAndNotDisposed';
   value: T;
   disposeValue: () => void;
 
@@ -18,7 +18,7 @@ export type NotInParentCacheAndNotDisposed<T> = {
   permanentRetainCount: number;
 };
 export type InParentCacheAndNotDisposed<T> = {
-  kind: "InParentCacheAndNotDisposed";
+  kind: 'InParentCacheAndNotDisposed';
   value: T;
   disposeValue: () => void;
   removeFromParentCache: () => void;
@@ -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
@@ -74,12 +78,12 @@ export class CacheItem<T> {
   constructor(
     factory: Factory<T>,
     removeFromParentCache: CleanupFn,
-    options: CacheItemOptions | void
+    options: CacheItemOptions | void,
   ) {
     this.__options = options ?? null;
     const [value, disposeValue] = factory();
     this.__state = {
-      kind: "InParentCacheAndNotDisposed",
+      kind: 'InParentCacheAndNotDisposed',
       value,
       disposeValue,
       removeFromParentCache,
@@ -92,26 +96,26 @@ export class CacheItem<T> {
 
   getValue(): T {
     switch (this.__state.kind) {
-      case "InParentCacheAndNotDisposed": {
+      case 'InParentCacheAndNotDisposed': {
         return this.__state.value;
       }
-      case "NotInParentCacheAndNotDisposed": {
+      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."
+          'Attempted to access disposed value from CacheItem. ' +
+            'This indicates a bug in react-disposable-state.',
         );
       }
     }
   }
 
   permanentRetainIfNotDisposed(
-    disposeOfTemporaryRetain: CleanupFn
+    disposeOfTemporaryRetain: CleanupFn,
   ): ItemCleanupPair<T> | null {
     switch (this.__state.kind) {
-      case "InParentCacheAndNotDisposed": {
+      case 'InParentCacheAndNotDisposed': {
         let cleared = false;
         this.__state.permanentRetainCount++;
         disposeOfTemporaryRetain();
@@ -120,35 +124,35 @@ export class CacheItem<T> {
           () => {
             if (cleared) {
               throw new Error(
-                "A permanent retain should only be cleared once. " +
-                  "This indicates a bug in react-disposable-state."
+                'A permanent retain should only be cleared once. ' +
+                  'This indicates a bug in react-disposable-state.',
               );
             }
             cleared = true;
             switch (this.__state.kind) {
-              case "InParentCacheAndNotDisposed": {
+              case 'InParentCacheAndNotDisposed': {
                 this.__state.permanentRetainCount--;
                 this.__maybeExitInParentCacheAndNotDisposedState(this.__state);
                 return;
               }
-              case "NotInParentCacheAndNotDisposed": {
+              case 'NotInParentCacheAndNotDisposed': {
                 this.__state.permanentRetainCount--;
                 this.__maybeExitNotInParentCacheAndNotDisposedState(
-                  this.__state
+                  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."
+                  'CacheItem was in a disposed state, but there existed a permanent retain. ' +
+                    'This indicates a bug in react-disposable-state.',
                 );
               }
             }
           },
         ];
       }
-      case "NotInParentCacheAndNotDisposed": {
+      case 'NotInParentCacheAndNotDisposed': {
         let cleared = false;
         this.__state.permanentRetainCount++;
         disposeOfTemporaryRetain();
@@ -157,23 +161,23 @@ export class CacheItem<T> {
           () => {
             if (cleared) {
               throw new Error(
-                "A permanent retain should only be cleared once. " +
-                  "This indicates a bug in react-disposable-state."
+                'A permanent retain should only be cleared once. ' +
+                  'This indicates a bug in react-disposable-state.',
               );
             }
             cleared = true;
             switch (this.__state.kind) {
-              case "NotInParentCacheAndNotDisposed": {
+              case 'NotInParentCacheAndNotDisposed': {
                 this.__state.permanentRetainCount--;
                 this.__maybeExitNotInParentCacheAndNotDisposedState(
-                  this.__state
+                  this.__state,
                 );
                 return;
               }
               default: {
                 throw new Error(
-                  "CacheItem was in an unexpected state. " +
-                    "This indicates a bug in react-disposable-state."
+                  'CacheItem was in an unexpected state. ' +
+                    'This indicates a bug in react-disposable-state.',
                 );
               }
             }
@@ -189,23 +193,23 @@ export class CacheItem<T> {
 
   temporaryRetain(): CleanupFn {
     type TemporaryRetainStatus =
-      | "Uncleared"
-      | "ClearedByCallback"
-      | "ClearedByTimeout";
+      | 'Uncleared'
+      | 'ClearedByCallback'
+      | 'ClearedByTimeout';
 
     switch (this.__state.kind) {
-      case "InParentCacheAndNotDisposed": {
-        let status: TemporaryRetainStatus = "Uncleared";
+      case 'InParentCacheAndNotDisposed': {
+        let status: TemporaryRetainStatus = 'Uncleared';
         this.__state.temporaryRetainCount++;
         const clearTemporaryRetainByCallack: CleanupFn = () => {
-          if (status === "ClearedByCallback") {
+          if (status === 'ClearedByCallback') {
             throw new Error(
-              "A temporary retain should only be cleared once. " +
-                "This indicates a bug in react-disposable-state."
+              'A temporary retain should only be cleared once. ' +
+                'This indicates a bug in react-disposable-state.',
             );
-          } else if (status === "Uncleared") {
+          } else if (status === 'Uncleared') {
             switch (this.__state.kind) {
-              case "InParentCacheAndNotDisposed": {
+              case 'InParentCacheAndNotDisposed': {
                 this.__state.temporaryRetainCount--;
                 this.__maybeExitInParentCacheAndNotDisposedState(this.__state);
                 clearTimeout(timeoutId);
@@ -213,8 +217,8 @@ export class CacheItem<T> {
               }
               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."
+                  'A temporary retain was cleared, for which the CacheItem is in an invalid state. ' +
+                    'This indicates a bug in react-disposable-state.',
                 );
               }
             }
@@ -222,17 +226,17 @@ export class CacheItem<T> {
         };
 
         const clearTemporaryRetainByTimeout = () => {
-          status = "ClearedByTimeout";
+          status = 'ClearedByTimeout';
           switch (this.__state.kind) {
-            case "InParentCacheAndNotDisposed": {
+            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."
+                'A temporary retain was cleared, for which the CacheItem is in an invalid state. ' +
+                  'This indicates a bug in react-disposable-state.',
               );
             }
           }
@@ -240,14 +244,14 @@ export class CacheItem<T> {
 
         const timeoutId = setTimeout(
           clearTemporaryRetainByTimeout,
-          this.__options?.temporaryRetainTime ?? DEFAULT_TEMPORARY_RETAIN_TIME
+          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."
+          'temporaryRetain was called, for which the CacheItem is in an invalid state. ' +
+            'This indicates a bug in react-disposable-state.',
         );
       }
     }
@@ -255,58 +259,58 @@ export class CacheItem<T> {
 
   permanentRetain(): CleanupFn {
     switch (this.__state.kind) {
-      case "InParentCacheAndNotDisposed": {
+      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."
+              'A permanent retain should only be cleared once. ' +
+                'This indicates a bug in react-disposable-state.',
             );
           }
           cleared = true;
           switch (this.__state.kind) {
-            case "InParentCacheAndNotDisposed": {
+            case 'InParentCacheAndNotDisposed': {
               this.__state.permanentRetainCount--;
               this.__maybeExitInParentCacheAndNotDisposedState(this.__state);
               return;
             }
-            case "NotInParentCacheAndNotDisposed": {
+            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."
+                'CacheItem was in a disposed state, but there existed a permanent retain. ' +
+                  'This indicates a bug in react-disposable-state.',
               );
             }
           }
         };
       }
-      case "NotInParentCacheAndNotDisposed": {
+      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."
+              'A permanent retain should only be cleared once. ' +
+                'This indicates a bug in react-disposable-state.',
             );
           }
           cleared = true;
           switch (this.__state.kind) {
-            case "NotInParentCacheAndNotDisposed": {
+            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."
+                'CacheItem was in an unexpected state. ' +
+                  'This indicates a bug in react-disposable-state.',
               );
             }
           }
@@ -314,26 +318,26 @@ export class CacheItem<T> {
       }
       default: {
         throw new Error(
-          "permanentRetain was called, but the CacheItem is in an invalid state. " +
-            "This indicates a bug in react-disposable-state."
+          'permanentRetain was called, but the CacheItem is in an invalid state. ' +
+            'This indicates a bug in react-disposable-state.',
         );
       }
     }
   }
 
   private __maybeExitInParentCacheAndNotDisposedState(
-    state: InParentCacheAndNotDisposed<T>
+    state: InParentCacheAndNotDisposed<T>,
   ) {
     if (state.temporaryRetainCount === 0 && state.permanentRetainCount === 0) {
       state.removeFromParentCache();
       state.disposeValue();
       this.__state = {
-        kind: "NotInParentCacheAndDisposed",
+        kind: 'NotInParentCacheAndDisposed',
       };
     } else if (state.temporaryRetainCount === 0) {
       state.removeFromParentCache();
       this.__state = {
-        kind: "NotInParentCacheAndNotDisposed",
+        kind: 'NotInParentCacheAndNotDisposed',
         value: state.value,
         disposeValue: state.disposeValue,
         permanentRetainCount: state.permanentRetainCount,
@@ -342,12 +346,12 @@ export class CacheItem<T> {
   }
 
   private __maybeExitNotInParentCacheAndNotDisposedState(
-    state: NotInParentCacheAndNotDisposed<T>
+    state: NotInParentCacheAndNotDisposed<T>,
   ) {
     if (state.permanentRetainCount === 0) {
       state.disposeValue();
       this.__state = {
-        kind: "NotInParentCacheAndDisposed",
+        kind: 'NotInParentCacheAndDisposed',
       };
     }
   }
@@ -356,7 +360,7 @@ export class CacheItem<T> {
 export function createTemporarilyRetainedCacheItem<T>(
   factory: Factory<T>,
   removeFromParentCache: CleanupFn,
-  options: CacheItemOptions | void
+  options: CacheItemOptions | void,
 ): [CacheItem<T>, CleanupFn] {
   const cacheItem = new CacheItem(factory, removeFromParentCache, options);
   const disposeTemporaryRetain = cacheItem.temporaryRetain();

package/src/ParentCache.test.ts

@@ -1,41 +1,45 @@
-import { describe, assert, test, vi, expect } from "vitest";
-import { ParentCache } from "./ParentCache";
-import { ItemCleanupPair } from "@isograph/disposable-types";
-import { CacheItem } from "./CacheItem";
+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;
+  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);
+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();
+      const [_cacheItem, value, clearTemporaryRetain] =
+        parentCache.getOrPopulateAndTemporaryRetain();
 
-    expect(factory.mock.calls.length).toBe(1);
-    assert(value === 1);
-    assert(getValue(parentCache) != null);
+      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);
+      parentCache.empty();
+      assert(getValue(parentCache) === null);
 
-    parentCache.getOrPopulateAndTemporaryRetain();
-    expect(factory.mock.calls.length).toBe(2);
+      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", () => {
+  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;
@@ -49,7 +53,7 @@ describe("ParentCache", () => {
     assert(getValue(parentCache) === null);
   });
 
-  test("Clearing one of two temporary retains does not remove the item from the parent cache", () => {
+  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;

package/src/ParentCache.ts

@@ -1,9 +1,9 @@
-import { CacheItem, createTemporarilyRetainedCacheItem } from "./CacheItem";
+import { CacheItem, createTemporarilyRetainedCacheItem } from './CacheItem';
 import {
   CleanupFn,
   Factory,
   ItemCleanupPair,
-} from "@isograph/disposable-types";
+} from '@isograph/disposable-types';
 
 // TODO convert cache impl to a getter and setter and free functions
 // TODO accept options that get passed to CacheItem
@@ -79,7 +79,7 @@ export class ParentCache<T> {
     // 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];
+    return [cacheItem, cacheItem.getValue(), disposeTemporaryRetain];
   }
 
   empty() {

package/src/index.ts

@@ -1,9 +1,9 @@
-export * from "@isograph/disposable-types";
+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";
+export * from './CacheItem';
+export * from './ParentCache';
+export * from './useCachedPrecommitValue';
+export * from './useDisposableState';
+export * from './useHasCommittedRef';
+export * from './useLazyDisposableState';
+export * from './useUpdatableDisposableState';