@isograph/react-disposable-state 0.0.4 → 0.1.0

package/dist/CacheItem.d.ts

@@ -1,15 +1,15 @@
-import { CleanupFn, Factory, ItemCleanupPair } from "@isograph/disposable-types";
+import { CleanupFn, Factory, ItemCleanupPair } from '@isograph/disposable-types';
 export type NotInParentCacheAndDisposed = {
-    kind: "NotInParentCacheAndDisposed";
+    kind: 'NotInParentCacheAndDisposed';
 };
 export type NotInParentCacheAndNotDisposed<T> = {
-    kind: "NotInParentCacheAndNotDisposed";
+    kind: 'NotInParentCacheAndNotDisposed';
     value: T;
     disposeValue: () => void;
     permanentRetainCount: number;
 };
 export type InParentCacheAndNotDisposed<T> = {
-    kind: "InParentCacheAndNotDisposed";
+    kind: 'InParentCacheAndNotDisposed';
     value: T;
     disposeValue: () => void;
     removeFromParentCache: () => void;
@@ -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
@@ -34,7 +38,7 @@ class CacheItem {
         this.__options = options !== null && options !== void 0 ? options : null;
         const [value, disposeValue] = factory();
         this.__state = {
-            kind: "InParentCacheAndNotDisposed",
+            kind: 'InParentCacheAndNotDisposed',
             value,
             disposeValue,
             removeFromParentCache,
@@ -46,21 +50,21 @@ class CacheItem {
     }
     getValue() {
         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.");
+                throw new Error('Attempted to access disposed value from CacheItem. ' +
+                    'This indicates a bug in react-disposable-state.');
             }
         }
     }
     permanentRetainIfNotDisposed(disposeOfTemporaryRetain) {
         switch (this.__state.kind) {
-            case "InParentCacheAndNotDisposed": {
+            case 'InParentCacheAndNotDisposed': {
                 let cleared = false;
                 this.__state.permanentRetainCount++;
                 disposeOfTemporaryRetain();
@@ -68,30 +72,30 @@ class CacheItem {
                     this.__state.value,
                     () => {
                         if (cleared) {
-                            throw new Error("A permanent retain should only be cleared once. " +
-                                "This indicates a bug in react-disposable-state.");
+                            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": {
+                            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.");
+                                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": {
+            case 'NotInParentCacheAndNotDisposed': {
                 let cleared = false;
                 this.__state.permanentRetainCount++;
                 disposeOfTemporaryRetain();
@@ -99,19 +103,19 @@ class CacheItem {
                     this.__state.value,
                     () => {
                         if (cleared) {
-                            throw new Error("A permanent retain should only be cleared once. " +
-                                "This indicates a bug in react-disposable-state.");
+                            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": {
+                            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.");
+                                throw new Error('CacheItem was in an unexpected state. ' +
+                                    'This indicates a bug in react-disposable-state.');
                             }
                         }
                     },
@@ -126,40 +130,40 @@ class CacheItem {
     temporaryRetain() {
         var _a, _b;
         switch (this.__state.kind) {
-            case "InParentCacheAndNotDisposed": {
-                let status = "Uncleared";
+            case 'InParentCacheAndNotDisposed': {
+                let status = 'Uncleared';
                 this.__state.temporaryRetainCount++;
                 const clearTemporaryRetainByCallack = () => {
-                    if (status === "ClearedByCallback") {
-                        throw new Error("A temporary retain should only be cleared once. " +
-                            "This indicates a bug in react-disposable-state.");
+                    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") {
+                    else if (status === 'Uncleared') {
                         switch (this.__state.kind) {
-                            case "InParentCacheAndNotDisposed": {
+                            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.");
+                                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";
+                    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.");
+                            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.');
                         }
                     }
                 };
@@ -167,65 +171,65 @@ class CacheItem {
                 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.");
+                throw new Error('temporaryRetain was called, for which the CacheItem is in an invalid state. ' +
+                    'This indicates a bug in react-disposable-state.');
             }
         }
     }
     permanentRetain() {
         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.");
+                        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": {
+                        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.");
+                            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": {
+            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.");
+                        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": {
+                        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.");
+                            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.");
+                throw new Error('permanentRetain was called, but the CacheItem is in an invalid state. ' +
+                    'This indicates a bug in react-disposable-state.');
             }
         }
     }
@@ -234,13 +238,13 @@ class CacheItem {
             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,
@@ -251,7 +255,7 @@ class CacheItem {
         if (state.permanentRetainCount === 0) {
             state.disposeValue();
             this.__state = {
-                kind: "NotInParentCacheAndDisposed",
+                kind: 'NotInParentCacheAndDisposed',
             };
         }
     }

package/dist/ParentCache.d.ts

@@ -1,5 +1,5 @@
-import { CacheItem } from "./CacheItem";
-import { CleanupFn, Factory, ItemCleanupPair } from "@isograph/disposable-types";
+import { CacheItem } from './CacheItem';
+import { CleanupFn, Factory, ItemCleanupPair } from '@isograph/disposable-types';
 /**
  * ParentCache
  * - A ParentCache can be in two states: populated and unpopulated.

package/dist/ParentCache.js

@@ -68,7 +68,7 @@ class ParentCache {
         // 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() {
         this.__cacheItem = null;

package/dist/index.d.ts

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

package/dist/useCachedPrecommitValue.d.ts

@@ -1,5 +1,5 @@
-import { ParentCache } from "./ParentCache";
-import { ItemCleanupPair } from "@isograph/isograph-disposable-types/dist";
+import { ParentCache } from './ParentCache';
+import { ItemCleanupPair } from '@isograph/isograph-disposable-types/dist';
 /**
  * usePrecommitValue<T>
  * - Takes a mutable parent cache, a factory function, and an onCommit callback.

package/dist/useCachedPrecommitValue.js

@@ -1,4 +1,4 @@
-"use strict";
+'use strict';
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useCachedPrecommitValue = void 0;
 const react_1 = require("react");

package/dist/useDisposableState.d.ts

@@ -1,6 +1,6 @@
-import { ParentCache } from "./ParentCache";
-import { ItemCleanupPair } from "@isograph/disposable-types";
-import { UnassignedState } from "./useUpdatableDisposableState";
+import { ParentCache } from './ParentCache';
+import { ItemCleanupPair } from '@isograph/disposable-types';
+import { UnassignedState } from './useUpdatableDisposableState';
 type UseUpdatableDisposableStateReturnValue<T> = {
     state: T;
     setState: (pair: ItemCleanupPair<Exclude<T, UnassignedState>>) => void;

package/dist/useDisposableState.js

@@ -18,8 +18,8 @@ function useDisposableState(parentCache) {
                 itemCleanupPairRef.current = null;
             }
             else {
-                throw new Error("itemCleanupPairRef.current is unexpectedly null. " +
-                    "This indicates a bug in react-disposable-state.");
+                throw new Error('itemCleanupPairRef.current is unexpectedly null. ' +
+                    'This indicates a bug in react-disposable-state.');
             }
         }
     }, [stateFromDisposableStateHook]);
@@ -57,12 +57,14 @@ exports.useDisposableState = useDisposableState;
 function tsTests() {
     let x;
     const a = useDisposableState(x);
+    // This should be a compiler error, because the generic is inferred to be of
+    // type never. TODO determine why this doesn't break the build!
     // @ts-expect-error
-    a.setState(["asdf", () => { }]);
+    a.setState(['asdf', () => { }]);
     // @ts-expect-error
     a.setState([useUpdatableDisposableState_1.UNASSIGNED_STATE, () => { }]);
     const b = useDisposableState(x);
     // @ts-expect-error
     b.setState([useUpdatableDisposableState_1.UNASSIGNED_STATE, () => { }]);
-    b.setState(["asdf", () => { }]);
+    b.setState(['asdf', () => { }]);
 }

package/dist/useHasCommittedRef.d.ts

@@ -1,4 +1,4 @@
-import { MutableRefObject } from "react";
+import { MutableRefObject } from 'react';
 /**
  * Returns true if the component has committed, false otherwise.
  */

package/dist/useLazyDisposableState.d.ts

@@ -1,4 +1,4 @@
-import { ParentCache } from "./ParentCache";
+import { ParentCache } from './ParentCache';
 /**
  * useLazyDisposableState<T>
  * - Takes a mutable parent cache and a factory function

package/dist/useLazyDisposableState.js

@@ -1,4 +1,4 @@
-"use strict";
+'use strict';
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useLazyDisposableState = void 0;
 const react_1 = require("react");
@@ -23,7 +23,7 @@ function useLazyDisposableState(parentCache) {
         const cleanupFn = (_a = itemCleanupPairRef.current) === null || _a === void 0 ? void 0 : _a[1];
         // TODO confirm useEffect is called in order.
         if (cleanupFn == null) {
-            throw new Error("cleanupFn unexpectedly null. This indicates a bug in react-disposable-state.");
+            throw new Error('cleanupFn unexpectedly null. This indicates a bug in react-disposable-state.');
         }
         return cleanupFn;
     }, []);
@@ -34,6 +34,6 @@ function useLazyDisposableState(parentCache) {
     // Safety: This can't happen. For renders before the initial commit, preCommitItem
     // is non-null. During the initial commit, we assign itemCleanupPairRef.current,
     // so during subsequent renders, itemCleanupPairRef.current is non-null.
-    throw new Error("returnedItem was unexpectedly null. This indicates a bug in react-disposable-state.");
+    throw new Error('returnedItem was unexpectedly null. This indicates a bug in react-disposable-state.');
 }
 exports.useLazyDisposableState = useLazyDisposableState;

package/dist/useUpdatableDisposableState.d.ts

@@ -1,4 +1,4 @@
-import { ItemCleanupPair } from "@isograph/disposable-types";
+import { ItemCleanupPair } from '@isograph/disposable-types';
 export declare const UNASSIGNED_STATE: unique symbol;
 export type UnassignedState = typeof UNASSIGNED_STATE;
 type UseUpdatableDisposableStateReturnValue<T> = {

package/dist/useUpdatableDisposableState.js

@@ -41,7 +41,7 @@ function useUpdatableDisposableState() {
     const [stateICI, setStateICI] = (0, react_1.useState)(exports.UNASSIGNED_STATE);
     const setStateAfterCommit = (0, react_1.useCallback)((itemCleanupPair) => {
         if (!hasCommittedRef.current) {
-            throw new Error("Calling setState before the component has committed is unsafe and disallowed.");
+            throw new Error('Calling setState before the component has committed is unsafe and disallowed.');
         }
         const ici = {
             item: itemCleanupPair[0],
@@ -84,9 +84,9 @@ function tsTests() {
     // @ts-expect-error
     a.setState([exports.UNASSIGNED_STATE, () => { }]);
     // @ts-expect-error
-    a.setState(["asdf", () => { }]);
+    a.setState(['asdf', () => { }]);
     const b = useUpdatableDisposableState();
     // @ts-expect-error
     b.setState([exports.UNASSIGNED_STATE, () => { }]);
-    b.setState(["asdf", () => { }]);
+    b.setState(['asdf', () => { }]);
 }

package/docs/managing-complex-state.md

@@ -61,7 +61,7 @@ const addItem2ToState = () => {
 
   // get a new active reference to the existing item1
   const [item1ActiveReference, disposeItem1ActiveReference] = nullthrows(
-    state[0].cloneIfNotDisposed()
+    state[0].cloneIfNotDisposed(),
   );
   setState([item1ActiveReference, item2ActiveReference], () => {
     disposeItem1ActiveReference();
@@ -94,7 +94,7 @@ const removeItem2FromState = () => {
 
   // get a new active reference to the existing item1
   const [item1ActiveReference, disposeItem1ActiveReference] = nullthrows(
-    state[0].cloneIfNotDisposed()
+    state[0].cloneIfNotDisposed(),
   );
   setState([item1ActiveReference], () => {
     disposeItem1ActiveReference();
@@ -133,12 +133,12 @@ For example:
   ```ts
   type MyState =
     | {
-        kind: "ConnectedToDatabase";
+        kind: 'ConnectedToDatabase';
         connectionToDatabase: ConnectionToDatabase;
         currentUserId: number;
       }
     | {
-        kind: "DisconnectedFromDatabase";
+        kind: 'DisconnectedFromDatabase';
       };
   ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isograph/react-disposable-state",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "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.4",
+    "@isograph/disposable-types": "0.1.0",
     "react": "^18.2.0"
   },
   "devDependencies": {
@@ -24,5 +24,10 @@
     "react-test-renderer": "^18.2.0",
     "vitest": "^0.29.8",
     "typescript": "^5.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/isographlabs/isograph.git",
+    "directory": "libs/isograph-react-disposable-state"
   }
 }