@isograph/reference-counted-pointer 0.0.0-main-4ef7c123

package/README.md

@@ -0,0 +1,7 @@
+# Reference counted pointers
+
+## API
+
+```js
+
+```

package/dist/createReferenceCountedPointer.d.ts

@@ -0,0 +1,33 @@
+import type { ItemCleanupPair } from "@isograph/disposable-types";
+/**
+ * Create an undisposed reference-counted pointer guarding a given item.
+ *
+ * Once all reference-counted pointers guarding a given item have been
+ * disposed, the underlying item will be disposed.
+ *
+ * Additional reference-counted pointers guarding the same item can be
+ * created by calling retainIfNotDisposed().
+ *
+ * ## Structural sharing
+ *
+ * Reference counted pointers enable reusing disposable items between
+ * application states, so-called structural sharing.
+ *
+ * If state 1 contains a reference counted pointer to an item, in order
+ * to transition to state 2, one would first create an additional
+ * reference-counted pointer by calling cloneIfNotDisposed, transition
+ * to state 2, then clean up state 1 by disposing of its reference-
+ * counted pointers. In this transition, at no time were there zero
+ * undisposed reference countend pointers to the disposable item, so it
+ * was never disposed, and we could reuse it between states.
+ */
+export declare function createReferenceCountedPointer<T>(pair: ItemCleanupPair<T>): ItemCleanupPair<ReferenceCountedPointer<T>>;
+export interface ReferenceCountedPointer<T> {
+    isDisposed(): boolean;
+    /**
+     * Safety: the item returned here is valid for use only as long as the reference
+     * counted pointer is not disposed.
+     */
+    getItemIfNotDisposed(): T | null;
+    cloneIfNotDisposed(): ItemCleanupPair<ReferenceCountedPointer<T>> | null;
+}

package/dist/createReferenceCountedPointer.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createReferenceCountedPointer = void 0;
+// TODO cloneIfNotDisposed should also return the underlying item
+/**
+ * Create an undisposed reference-counted pointer guarding a given item.
+ *
+ * Once all reference-counted pointers guarding a given item have been
+ * disposed, the underlying item will be disposed.
+ *
+ * Additional reference-counted pointers guarding the same item can be
+ * created by calling retainIfNotDisposed().
+ *
+ * ## Structural sharing
+ *
+ * Reference counted pointers enable reusing disposable items between
+ * application states, so-called structural sharing.
+ *
+ * If state 1 contains a reference counted pointer to an item, in order
+ * to transition to state 2, one would first create an additional
+ * reference-counted pointer by calling cloneIfNotDisposed, transition
+ * to state 2, then clean up state 1 by disposing of its reference-
+ * counted pointers. In this transition, at no time were there zero
+ * undisposed reference countend pointers to the disposable item, so it
+ * was never disposed, and we could reuse it between states.
+ */
+function createReferenceCountedPointer(pair) {
+    const originalReferenceCountedPointer = new RefCounter(pair);
+    return originalReferenceCountedPointer.retainIfNotDisposed();
+}
+exports.createReferenceCountedPointer = createReferenceCountedPointer;
+// N.B. this could implement ReferenceCountedPointer<T>, but it would not be correct to use it
+// as such, since it does not have an associated dispose function that can be called.
+//
+// Note that there is no way, and should be no way, to determine whether the underlying item
+// has been disposed, let alone force it to be disposed! If you need that, you need to keep track
+// of all calls to retainIfNotDisposed.
+class RefCounter {
+    /**
+     * Private. Do not expose this class directly, as this contructor creates a ReferenceCountedPointer
+     * in an invalid state. We must immediately, after creation, call retainIfNotDisposed().
+     */
+    constructor([item, dispose]) {
+        this.__state = {
+            item,
+            dispose,
+            activeReferenceCount: 0,
+        };
+    }
+    getIfNotDisposed() {
+        return this.__state === null ? null : this.__state.item;
+    }
+    retainIfNotDisposed() {
+        if (this.__state !== null) {
+            this.__state.activeReferenceCount++;
+            const activeReference = new ActiveReference(this);
+            let disposed = false;
+            const dispose = () => {
+                if (disposed) {
+                    throw new Error("Do not dispose an already-disposed ActiveReference.");
+                }
+                disposed = true;
+                if (activeReference.__original === null) {
+                    throw new Error("Attempted to dispose an active reference, but it was already disposed. " +
+                        "This indicates a bug in reference-counted-pointer.");
+                }
+                activeReference.__original = null;
+                if (this.__state === null) {
+                    throw new Error("Attempted to dispose, but the underlying reference counted pointer was disposed. " +
+                        "This indicates a bug in reference-counted-pointer.");
+                }
+                this.__state.activeReferenceCount--;
+                this.__maybeDispose();
+            };
+            return [activeReference, dispose];
+        }
+        else {
+            return null;
+        }
+    }
+    __maybeDispose() {
+        if (this.__state === null) {
+            throw new Error("__maybeDispose was called, but the reference counted pointer was disposed. " +
+                "This indicates a bug in reference-counted-pointer.");
+        }
+        if (this.__state.activeReferenceCount === 0) {
+            this.__state.dispose();
+            this.__state = null;
+        }
+    }
+}
+class ActiveReference {
+    constructor(original) {
+        this.__original = original;
+    }
+    isDisposed() {
+        return this.__original === null;
+    }
+    cloneIfNotDisposed() {
+        var _a, _b;
+        return (_b = (_a = this.__original) === null || _a === void 0 ? void 0 : _a.retainIfNotDisposed()) !== null && _b !== void 0 ? _b : null;
+    }
+    getItemIfNotDisposed() {
+        var _a, _b;
+        return (_b = (_a = this.__original) === null || _a === void 0 ? void 0 : _a.getIfNotDisposed()) !== null && _b !== void 0 ? _b : null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./createReferenceCountedPointer";

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./createReferenceCountedPointer"), exports);

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@isograph/reference-counted-pointer",
+  "version": "0.0.0-main-4ef7c123",
+  "description": "Reference counted pointers enable sharing of disposable items.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "author": "Isograph Labs",
+  "license": "MIT",
+  "scripts": {
+    "compile": "rm -rf dist/* && tsc -p tsconfig.pkg.json",
+    "compile-watch": "tsc -p tsconfig.pkg.json --watch",
+    "test": "vitest run",
+    "test-watch": "vitest watch",
+    "coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@isograph/disposable-types": "0.0.0-main-4ef7c123",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.31",
+    "react-test-renderer": "^18.2.0",
+    "typescript": "^5.0.3",
+    "vitest": "^0.29.8"
+  }
+}

package/src/createReferenceCountedPointer.test.ts

@@ -0,0 +1,202 @@
+import { describe, test, vi, expect, assert } from "vitest";
+import { createReferenceCountedPointer } from "./createReferenceCountedPointer";
+
+describe("createReferenceCountedPointer", () => {
+  describe("it should not dispose the underlying item until all outstanding pointers are disposed", () => {
+    test("one pointer", () => {
+      const disposeItem = vi.fn();
+      const [pointer, disposePointer] = createReferenceCountedPointer([
+        1,
+        disposeItem,
+      ]);
+      expect(disposeItem).not.toHaveBeenCalled();
+      disposePointer();
+      expect(disposeItem).toHaveBeenCalled();
+    });
+
+    test("linked list, FIFO", () => {
+      const disposeItem = vi.fn();
+      const [pointer, disposePointer] = createReferenceCountedPointer([
+        1,
+        disposeItem,
+      ]);
+      const [pointer2, disposePointer2] = pointer.cloneIfNotDisposed()!;
+      const [pointer3, disposePointer3] = pointer2.cloneIfNotDisposed()!;
+      const [pointer4, disposePointer4] = pointer3.cloneIfNotDisposed()!;
+
+      disposePointer4();
+      disposePointer3();
+      disposePointer2();
+      expect(disposeItem).not.toHaveBeenCalled();
+      disposePointer();
+      expect(disposeItem).toHaveBeenCalled();
+    });
+
+    test("linked list, LIFO", () => {
+      const disposeItem = vi.fn();
+      const [pointer, disposePointer] = createReferenceCountedPointer([
+        1,
+        disposeItem,
+      ]);
+      const [pointer2, disposePointer2] = pointer.cloneIfNotDisposed()!;
+      const [pointer3, disposePointer3] = pointer2.cloneIfNotDisposed()!;
+      const [pointer4, disposePointer4] = pointer3.cloneIfNotDisposed()!;
+
+      disposePointer();
+      disposePointer2();
+      disposePointer3();
+      expect(disposeItem).not.toHaveBeenCalled();
+      disposePointer4();
+      expect(disposeItem).toHaveBeenCalled();
+    });
+
+    test("linked list, mixed order", () => {
+      const disposeItem = vi.fn();
+      const [pointer, disposePointer] = createReferenceCountedPointer([
+        1,
+        disposeItem,
+      ]);
+      const [pointer2, disposePointer2] = pointer.cloneIfNotDisposed()!;
+      const [pointer3, disposePointer3] = pointer2.cloneIfNotDisposed()!;
+      const [pointer4, disposePointer4] = pointer3.cloneIfNotDisposed()!;
+
+      disposePointer2();
+      disposePointer();
+      disposePointer4();
+      expect(disposeItem).not.toHaveBeenCalled();
+      disposePointer3();
+      expect(disposeItem).toHaveBeenCalled();
+    });
+
+    test("DAG, from root", () => {
+      const disposeItem = vi.fn();
+      const [pointer, disposePointer] = createReferenceCountedPointer([
+        1,
+        disposeItem,
+      ]);
+      const [pointerA, disposePointerA] = pointer.cloneIfNotDisposed()!;
+      const [pointerA_1, disposePointerA_1] = pointerA.cloneIfNotDisposed()!;
+      const [pointerA_2, disposePointerA_2] = pointerA.cloneIfNotDisposed()!;
+      const [pointerB, disposePointerB] = pointer.cloneIfNotDisposed()!;
+      const [pointerB_1, disposePointerB_1] = pointerB.cloneIfNotDisposed()!;
+      const [pointerB_2, disposePointerB_2] = pointerB.cloneIfNotDisposed()!;
+
+      disposePointer();
+      disposePointerA();
+      disposePointerA_1();
+      disposePointerA_2();
+      disposePointerB();
+      disposePointerB_1();
+      expect(disposeItem).not.toHaveBeenCalled();
+      disposePointerB_2();
+      expect(disposeItem).toHaveBeenCalled();
+    });
+
+    test("DAG, from leaves", () => {
+      const disposeItem = vi.fn();
+      const [pointer, disposePointer] = createReferenceCountedPointer([
+        1,
+        disposeItem,
+      ]);
+      const [pointerA, disposePointerA] = pointer.cloneIfNotDisposed()!;
+      const [pointerA_1, disposePointerA_1] = pointerA.cloneIfNotDisposed()!;
+      const [pointerA_2, disposePointerA_2] = pointerA.cloneIfNotDisposed()!;
+      const [pointerB, disposePointerB] = pointer.cloneIfNotDisposed()!;
+      const [pointerB_1, disposePointerB_1] = pointerB.cloneIfNotDisposed()!;
+      const [pointerB_2, disposePointerB_2] = pointerB.cloneIfNotDisposed()!;
+
+      disposePointerB_1();
+      disposePointerB_2();
+      disposePointerB();
+      disposePointerA_1();
+      disposePointerA_2();
+      disposePointerA();
+      expect(disposeItem).not.toHaveBeenCalled();
+      disposePointer();
+      expect(disposeItem).toHaveBeenCalled();
+    });
+
+    test("DAG, random", () => {
+      const disposeItem = vi.fn();
+      const [pointer, disposePointer] = createReferenceCountedPointer([
+        1,
+        disposeItem,
+      ]);
+      const [pointerA, disposePointerA] = pointer.cloneIfNotDisposed()!;
+      const [pointerA_1, disposePointerA_1] = pointerA.cloneIfNotDisposed()!;
+      const [pointerA_2, disposePointerA_2] = pointerA.cloneIfNotDisposed()!;
+      const [pointerB, disposePointerB] = pointer.cloneIfNotDisposed()!;
+      const [pointerB_1, disposePointerB_1] = pointerB.cloneIfNotDisposed()!;
+      const [pointerB_2, disposePointerB_2] = pointerB.cloneIfNotDisposed()!;
+
+      disposePointerB_1();
+      disposePointerA();
+      disposePointer();
+      disposePointerB_2();
+      disposePointerB();
+      disposePointerA_2();
+      expect(disposeItem).not.toHaveBeenCalled();
+      disposePointerA_1();
+      expect(disposeItem).toHaveBeenCalled();
+    });
+  });
+
+  test("it should throw when disposed twice", () => {
+    const disposeItem = vi.fn();
+    const [pointer, disposePointer] = createReferenceCountedPointer([
+      1,
+      disposeItem,
+    ]);
+    disposePointer();
+    expect(() => {
+      disposePointer();
+    }).toThrow();
+  });
+
+  test("it should return null when you attempt to retain a disposed pointer", () => {
+    const disposeItem = vi.fn();
+    const [pointer, disposePointer] = createReferenceCountedPointer([
+      1,
+      disposeItem,
+    ]);
+    disposePointer();
+    expect(pointer.cloneIfNotDisposed()).toBe(null);
+  });
+
+  test("it should expose the underlying object only when undisposed", () => {
+    const disposeItem = vi.fn();
+    const [pointer, disposePointer] = createReferenceCountedPointer([
+      1,
+      disposeItem,
+    ]);
+    expect(pointer.getItemIfNotDisposed()).toBe(1);
+    disposePointer();
+    expect(pointer.getItemIfNotDisposed()).toBe(null);
+  });
+
+  test("it should accurately report its disposed status", () => {
+    const disposeItem = vi.fn();
+    const [pointer, disposePointer] = createReferenceCountedPointer([
+      1,
+      disposeItem,
+    ]);
+    expect(pointer.isDisposed()).toBe(false);
+    disposePointer();
+    expect(pointer.isDisposed()).toBe(true);
+  });
+
+  test("disposable status is unaffected by the presence of other undisposed pointers", () => {
+    const disposeItem = vi.fn();
+    const [pointer, disposePointer] = createReferenceCountedPointer([
+      1,
+      disposeItem,
+    ]);
+    const pointer2 = pointer.cloneIfNotDisposed();
+    assert(pointer2 != null);
+    expect(pointer2[0].isDisposed()).toBe(false);
+    expect(pointer.isDisposed()).toBe(false);
+    disposePointer();
+    expect(pointer.isDisposed()).toBe(true);
+    expect(pointer2[0].isDisposed()).toBe(false);
+  });
+});

package/src/createReferenceCountedPointer.ts

@@ -0,0 +1,147 @@
+import type { CleanupFn, ItemCleanupPair } from "@isograph/disposable-types";
+
+// TODO cloneIfNotDisposed should also return the underlying item
+
+/**
+ * Create an undisposed reference-counted pointer guarding a given item.
+ *
+ * Once all reference-counted pointers guarding a given item have been
+ * disposed, the underlying item will be disposed.
+ *
+ * Additional reference-counted pointers guarding the same item can be
+ * created by calling retainIfNotDisposed().
+ *
+ * ## Structural sharing
+ *
+ * Reference counted pointers enable reusing disposable items between
+ * application states, so-called structural sharing.
+ *
+ * If state 1 contains a reference counted pointer to an item, in order
+ * to transition to state 2, one would first create an additional
+ * reference-counted pointer by calling cloneIfNotDisposed, transition
+ * to state 2, then clean up state 1 by disposing of its reference-
+ * counted pointers. In this transition, at no time were there zero
+ * undisposed reference countend pointers to the disposable item, so it
+ * was never disposed, and we could reuse it between states.
+ */
+export function createReferenceCountedPointer<T>(
+  pair: ItemCleanupPair<T>
+): ItemCleanupPair<ReferenceCountedPointer<T>> {
+  const originalReferenceCountedPointer = new RefCounter(pair);
+
+  return originalReferenceCountedPointer.retainIfNotDisposed()!;
+}
+
+export interface ReferenceCountedPointer<T> {
+  isDisposed(): boolean;
+  /**
+   * Safety: the item returned here is valid for use only as long as the reference
+   * counted pointer is not disposed.
+   */
+  getItemIfNotDisposed(): T | null;
+  cloneIfNotDisposed(): ItemCleanupPair<ReferenceCountedPointer<T>> | null;
+}
+
+type RefCountState<T> = {
+  item: T;
+  dispose: CleanupFn;
+  // Invariant: >0
+  activeReferenceCount: number;
+};
+
+// N.B. this could implement ReferenceCountedPointer<T>, but it would not be correct to use it
+// as such, since it does not have an associated dispose function that can be called.
+//
+// Note that there is no way, and should be no way, to determine whether the underlying item
+// has been disposed, let alone force it to be disposed! If you need that, you need to keep track
+// of all calls to retainIfNotDisposed.
+class RefCounter<T> {
+  private __state: RefCountState<T> | null;
+
+  /**
+   * Private. Do not expose this class directly, as this contructor creates a ReferenceCountedPointer
+   * in an invalid state. We must immediately, after creation, call retainIfNotDisposed().
+   */
+  constructor([item, dispose]: ItemCleanupPair<T>) {
+    this.__state = {
+      item,
+      dispose,
+      activeReferenceCount: 0,
+    };
+  }
+
+  getIfNotDisposed(): T | null {
+    return this.__state === null ? null : this.__state.item;
+  }
+
+  retainIfNotDisposed(): ItemCleanupPair<ReferenceCountedPointer<T>> | null {
+    if (this.__state !== null) {
+      this.__state.activeReferenceCount++;
+
+      const activeReference = new ActiveReference(this);
+
+      let disposed = false;
+      const dispose = () => {
+        if (disposed) {
+          throw new Error(
+            "Do not dispose an already-disposed ActiveReference."
+          );
+        }
+        disposed = true;
+        if (activeReference.__original === null) {
+          throw new Error(
+            "Attempted to dispose an active reference, but it was already disposed. " +
+              "This indicates a bug in reference-counted-pointer."
+          );
+        }
+        activeReference.__original = null;
+        if (this.__state === null) {
+          throw new Error(
+            "Attempted to dispose, but the underlying reference counted pointer was disposed. " +
+              "This indicates a bug in reference-counted-pointer."
+          );
+        }
+        this.__state.activeReferenceCount--;
+        this.__maybeDispose();
+      };
+
+      return [activeReference, dispose];
+    } else {
+      return null;
+    }
+  }
+
+  private __maybeDispose() {
+    if (this.__state === null) {
+      throw new Error(
+        "__maybeDispose was called, but the reference counted pointer was disposed. " +
+          "This indicates a bug in reference-counted-pointer."
+      );
+    }
+    if (this.__state.activeReferenceCount === 0) {
+      this.__state.dispose();
+      this.__state = null;
+    }
+  }
+}
+
+class ActiveReference<T> implements ReferenceCountedPointer<T> {
+  // Invariant: __original !== null => the original is not disposed.
+  __original: RefCounter<T> | null;
+
+  constructor(original: RefCounter<T>) {
+    this.__original = original;
+  }
+
+  isDisposed(): boolean {
+    return this.__original === null;
+  }
+
+  cloneIfNotDisposed(): ItemCleanupPair<ReferenceCountedPointer<T>> | null {
+    return this.__original?.retainIfNotDisposed() ?? null;
+  }
+
+  getItemIfNotDisposed(): T | null {
+    return this.__original?.getIfNotDisposed() ?? null;
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./createReferenceCountedPointer";

package/tsconfig.pkg.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.build.json",
+  "compilerOptions": {
+    "outDir": "./dist/",
+    "rootDir": "./src/",
+    "declaration": true
+  },
+  "include": ["./src/**/*.ts"]
+}