@pistonite/pure 0.25.0 → 0.26.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pistonite/pure",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "type": "module",
   "description": "Pure TypeScript libraries for my projects",
   "homepage": "https://github.com/Pistonite/pure",

package/src/memory/erc.test.ts

@@ -0,0 +1,267 @@
+import { describe, afterEach, expect, it } from "vitest";
+
+import { type Erc, makeErcType } from "./erc.ts";
+
+type Rc = {
+    value: string;
+    refCount: number;
+};
+const Marker = Symbol("test");
+type Marker = typeof Marker;
+class Allocator {
+    private mockMemory: (Rc | undefined)[] = [];
+    public makeTestErc: (ptr: number) => Erc<Marker>;
+
+    // double indirection means each Erc holds a pointer to the external smart pointer,
+    // which also means external smart pointers all need to be heap allocated
+    // addRef() will return a pointer to a new external smart pointer
+    //
+    // single indirection on the other hand, means each Erc holds a pointer
+    // to the object directly. and addRef() will return the same pointer
+    //
+    // The Erc implementation must work with both
+    constructor(isDoubleIndirection: boolean) {
+        this.makeTestErc = makeErcType({
+            marker: Marker,
+            free: (ptr: number) => {
+                if (ptr < 0 || ptr >= this.mockMemory.length) {
+                    throw new Error(
+                        `Invalid index into mock memory. Length is ${this.mockMemory.length} but index is ${ptr}`,
+                    );
+                }
+
+                const rc = this.mockMemory[ptr];
+                if (!rc) {
+                    throw new Error("Double free detected");
+                }
+
+                rc.refCount--;
+                if (isDoubleIndirection) {
+                    this.mockMemory[ptr] = undefined;
+                    return;
+                }
+
+                if (rc.refCount === 0) {
+                    this.mockMemory[ptr] = undefined;
+                }
+            },
+            addRef: (value: number) => {
+                if (value < 0 || value >= this.mockMemory.length) {
+                    throw new Error(
+                        `Invalid index into mock memory. Length is ${this.mockMemory.length} but index is ${value}`,
+                    );
+                }
+
+                const rc = this.mockMemory[value];
+                if (!rc) {
+                    throw new Error("AddRef on freed memory detected");
+                }
+                rc.refCount++;
+                if (isDoubleIndirection) {
+                    for (let i = 0; i < this.mockMemory.length; i++) {
+                        if (this.mockMemory[i] === undefined) {
+                            this.mockMemory[i] = rc;
+                            return i;
+                        }
+                    }
+                    this.mockMemory.push(rc);
+                    return this.mockMemory.length - 1;
+                }
+
+                return value;
+            },
+        });
+    }
+
+    allocValue(value: string): number {
+        const rc: Rc = {
+            value,
+            refCount: 1,
+        };
+        for (let i = 0; i < this.mockMemory.length; i++) {
+            if (this.mockMemory[i] === undefined) {
+                this.mockMemory[i] = rc;
+                return i;
+            }
+        }
+        this.mockMemory.push(rc);
+        return this.mockMemory.length - 1;
+    }
+
+    getValue(ptr: number | undefined): string {
+        if (ptr === undefined) {
+            throw new Error("Dereference of nullptr");
+        }
+        if (ptr < 0 || ptr >= this.mockMemory.length) {
+            throw new Error(
+                `Invalid index into mock memory. Length is ${this.mockMemory.length} but index is ${ptr}`,
+            );
+        }
+
+        const rc = this.mockMemory[ptr];
+        if (!rc) {
+            throw new Error("Dangling pointer");
+        }
+        return rc.value;
+    }
+
+    expectNoLeak(): void {
+        for (let i = 0; i < this.mockMemory.length; i++) {
+            const rc = this.mockMemory[i];
+            if (rc) {
+                throw new Error(
+                    `Memory leak detected at index ${i}. Value: ${rc.value}, RefCount: ${rc.refCount}`,
+                );
+            }
+        }
+    }
+
+    cleanup(): void {
+        this.mockMemory = [];
+    }
+}
+
+describe.each`
+    indirection | allocator
+    ${"single"} | ${new Allocator(false)}
+    ${"double"} | ${new Allocator(true)}
+`(
+    "Erc - $indirection indirection",
+    ({ allocator }: { allocator: Allocator }) => {
+        afterEach(() => {
+            allocator.cleanup();
+        });
+
+        it("allocate and deallocate correctly", () => {
+            const test = allocator.makeTestErc(allocator.allocValue("Hello"));
+            expect(allocator.getValue(test.value)).toBe("Hello");
+            test.free();
+            allocator.expectNoLeak();
+        });
+
+        it("frees if assigned new value", () => {
+            const test = allocator.makeTestErc(allocator.allocValue("Hello"));
+            test.assign(allocator.allocValue("World"));
+            expect(allocator.getValue(test.value)).toBe("World");
+            test.free();
+            allocator.expectNoLeak();
+        });
+
+        it("does not free when taking value", () => {
+            const test = allocator.makeTestErc(allocator.allocValue("Hello"));
+            const raw = test.take();
+            expect(allocator.getValue(raw)).toBe("Hello");
+            expect(test.value).toBeUndefined();
+            if (raw === undefined) {
+                throw new Error("Raw value is undefined");
+            }
+            allocator.makeTestErc(raw).free();
+            allocator.expectNoLeak();
+        });
+
+        it("invalidates weak references on free", () => {
+            const test = allocator.makeTestErc(allocator.allocValue("Hello"));
+            const testWeak = test.getWeak();
+            expect(allocator.getValue(testWeak.value)).toBe("Hello");
+            test.free();
+            expect(testWeak.value).toBeUndefined();
+            allocator.expectNoLeak();
+        });
+
+        it("invalidates weak references on assign", () => {
+            const test = allocator.makeTestErc(allocator.allocValue("Hello"));
+            const testWeak = test.getWeak();
+            expect(allocator.getValue(testWeak.value)).toBe("Hello");
+            test.assign(allocator.allocValue("World"));
+            expect(testWeak.value).toBeUndefined();
+            test.free();
+            allocator.expectNoLeak();
+        });
+
+        it("handles assign and take of different references correctly", () => {
+            const test1 = allocator.makeTestErc(allocator.allocValue("Hello"));
+            const test2 = allocator.makeTestErc(allocator.allocValue("World"));
+            expect(allocator.getValue(test1.value)).toBe("Hello");
+            expect(allocator.getValue(test2.value)).toBe("World");
+            test1.assign(test2.take());
+            expect(allocator.getValue(test1.value)).toBe("World");
+            test1.free();
+            allocator.expectNoLeak();
+        });
+
+        it("handles assign and take of same references correctly", () => {
+            const test1 = allocator.makeTestErc(allocator.allocValue("Hello"));
+            const test2 = test1.getStrong();
+            test1.assign(test2.take());
+            expect(allocator.getValue(test1.value)).toBe("Hello");
+            test1.free();
+            test2.free(); // should be no-op
+            allocator.expectNoLeak();
+        });
+
+        it("assigning another Erc directly should cause double free", async () => {
+            const test1 = allocator.makeTestErc(allocator.allocValue("Hello"));
+            const test2 = test1.getStrong();
+            test1.assign(test2.value);
+            expect(allocator.getValue(test1.value)).toBe("Hello");
+            test1.free();
+
+            const freeTest2 = async () => {
+                test2.free();
+            };
+            await expect(freeTest2).rejects.toThrow("Double free detected");
+            allocator.expectNoLeak();
+        });
+
+        it("handles assign and take of same references correctly (same Erc)", () => {
+            const test1 = allocator.makeTestErc(allocator.allocValue("Hello"));
+            test1.assign(test1.take());
+            expect(allocator.getValue(test1.value)).toBe("Hello");
+            test1.free();
+            allocator.expectNoLeak();
+        });
+
+        it("assigning another Erc directly should cause double free (same Erc)", async () => {
+            const test1 = allocator.makeTestErc(allocator.allocValue("Hello"));
+            test1.assign(test1.value);
+            const getTest1Value = async () => {
+                allocator.getValue(test1.value);
+            };
+            await expect(getTest1Value).rejects.toThrow("Dangling pointer");
+
+            const freeTest1 = async () => {
+                test1.free();
+            };
+            await expect(freeTest1).rejects.toThrow("Double free detected");
+            allocator.expectNoLeak();
+        });
+
+        it("inc ref count with strong reference", () => {
+            const test = allocator.makeTestErc(allocator.allocValue("Hello"));
+            const test2 = test.getStrong();
+            expect(allocator.getValue(test.value)).toBe("Hello");
+            expect(allocator.getValue(test2.value)).toBe("Hello");
+            test.free();
+            expect(allocator.getValue(test2.value)).toBe("Hello");
+            test2.free();
+            allocator.expectNoLeak();
+        });
+
+        it("inc ref count with strong reference from weak reference", () => {
+            const test = allocator.makeTestErc(allocator.allocValue("Hello"));
+            const testWeak = test.getWeak();
+            expect(allocator.getValue(testWeak.value)).toBe("Hello");
+            const test2 = testWeak.getStrong();
+            expect(allocator.getValue(testWeak.value)).toBe("Hello");
+            expect(allocator.getValue(test2.value)).toBe("Hello");
+            const test2Weak = test2.getWeak();
+            test.free();
+            expect(testWeak.value).toBeUndefined();
+            expect(allocator.getValue(test2.value)).toBe("Hello");
+            expect(allocator.getValue(test2Weak.value)).toBe("Hello");
+            test2.free();
+            expect(test2Weak.value).toBeUndefined();
+            allocator.expectNoLeak();
+        });
+    },
+);

package/src/memory/erc.ts

@@ -0,0 +1,316 @@
+/**
+ * A holder for an externally ref-counted object.
+ *
+ * See {@link makeErcType} for how to use
+ */
+export type Erc<TName, TRepr = number> = {
+    readonly type: TName;
+
+    /**
+     * Underlying object representation.
+     *
+     * The repr should not be undefinable. undefined means nullptr
+     */
+    readonly value: TRepr | undefined;
+
+    /**
+     * Free the underlying object.
+     *
+     * All weak references will be invalidated, and this Erc will become
+     * empty
+     */
+    free: () => void;
+
+    /**
+     * Assign a new value to this Erc.
+     *
+     * The old value will be freed, and all weak references will be invalidated.
+     */
+    assign: (value: TRepr | undefined) => void;
+
+    /**
+     * Take the inner value without freeing it.
+     *
+     * All weak references will be invalidated, and this Erc will become
+     * empty
+     */
+    take: () => TRepr | undefined;
+
+    /**
+     * Create a weak reference to the inner value.
+     *
+     * When this Erc is freed, all weak references will be invalidated.
+     */
+    getWeak: () => ErcRef<TName, TRepr>;
+
+    /**
+     * Create a strong reference to the inner value, essentially
+     * incrementing the ref count.
+     */
+    getStrong: () => Erc<TName, TRepr>;
+};
+
+/**
+ * Weak reference to an externally ref-counted object.
+ *
+ * See {@link makeErcType} for how to use
+ */
+export type ErcRef<TName, TRepr = number> = {
+    readonly type: TName;
+
+    /**
+     * The underlying object representation.
+     *
+     * This may become undefined across async calls if the weak reference
+     * is invalidated
+     */
+    readonly value: TRepr | undefined;
+
+    /**
+     * Create a strong reference to the inner value, essentially
+     * incrementing the ref count.
+     */
+    getStrong: () => Erc<TName, TRepr>;
+};
+
+export type ErcRefType<T> =
+    T extends Erc<infer TName, infer TRepr> ? ErcRef<TName, TRepr> : never;
+
+export type ErcTypeConstructor<TName, TRepr> = {
+    /**
+     * A marker value for the underlying object type.
+     *
+     * This is commonly a string literal or a symbol.
+     */
+    marker: TName;
+
+    /**
+     * The function to free the underlying object.
+     */
+    free: (value: TRepr) => void;
+
+    /**
+     * Given a value, increase the ref count and return the new reference.
+     * The returned representation should be a different value if double indirection
+     * is used (each value is a pointer to the smart pointer), or the same value
+     * if single indirection is used (the value is pointing to the object itself).
+     */
+    addRef: (value: TRepr) => TRepr;
+};
+
+/**
+ * Create a constructor function that serves as the type for an externally ref-counted
+ * object type. Erc instances can then be created for manually managing memory for
+ * external objects, typically through FFI.
+ *
+ * Since JS is garbage collected and has no way to enforce certain memory management,
+ * the programmer must ensure that Erc instances are handled correctly!!!
+ *
+ * ## Defining Erc type
+ * ```typescript
+ * import { makeErcType, type Erc } from "@pistonite/pure/memory";
+ *
+ * // 2 functions are required to create an Erc type:
+ * // free: free the underlying value (essentially decrementing the ref count)
+ * // addRef: increment the ref count and return the new reference
+ *
+ * // here, assume `number` is the JS type used to represent the external object
+ * // for example, this can be a pointer to a C++ object
+ * declare function freeFoo(obj: number) => void;
+ * declare function addRefFoo(obj: number) => number;
+ *
+ * // assume another function to create (allocate) the object
+ * declare function createFoo(): number;
+ *
+ * // The recommended way is to create a unique symbol for tracking
+ * // the external type, you can also use a string literal
+ * const Foo = Symbol("Foo");
+ * type Foo = typeof Foo;
+ *
+ * // now, we can create the Erc type
+ * const makeFooErc = makeErcType({
+ *     marker: Foo,
+ *     free: freeFoo,
+ *     addRef: addRefFoo,
+ * });
+ *
+ * // and create Erc instances
+ * const myFoo: Erc<Foo> = makeFooErc(createFoo());
+ * ```
+ *
+ * ## Using Erc (strong reference)
+ * Each `Erc` instance is a strong reference, corresponding to some ref-counted
+ * object externally. Therefore, owner of the `Erc` instance should
+ * not expose the `Erc` instance to others (for example, returning it from a function),
+ * since it will lead to memory leak or double free.
+ * ```typescript
+ * // create a foo instance externally, and wrap it with Erc
+ * const myFoo = makeFooErc(createFoo());
+ *
+ * // if ownership of myFoo should be returned to external, use `take()`
+ * // this will make myFoo empty, and doSomethingWithFooExternally should free it
+ * doSomethingWithFooExternally(myFoo.take());
+ *
+ * // you can also free it directly
+ * foo.free();
+ * ```
+ *
+ * ## Using ErcRef (weak reference)
+ * Calling `getWeak` on an `Erc` will return a weak reference that has the same
+ * inner value. The weak reference is safe to be passed around and copied.
+ * ```typescript
+ * const myFooWeak = myFoo.getWeak();
+ * ```
+ *
+ * The weak references are tracked by the `Erc` instance.
+ * In the example above, when `myFoo` is freed, all weak references created by
+ * `getWeak` will be invalidated. If some other code kept the inner value of
+ * the weak reference, it will become a dangling pointer.
+ *
+ * To avoid this, `getStrong` can be used to create a strong reference if
+ * the weak reference is still valid, to ensure that the underlying object
+ * is never freed while still in use
+ * ```typescript
+ * const myFooWeak = myFoo.getWeak();
+ *
+ * // assume we have some async code that needs to use myFoo
+ * declare async function doSomethingWithFoo(foo: FooErcRef): Promise<void>;
+ *
+ * // Below is BAD!
+ * await doSomethingWithFoo(myFooWeak);
+ * // Reason: doSomethingWithFoo is async, so it's possible that
+ * // myFooWeak is invalidated when it's still needed. If the implementation
+ * // does not check for that, it could be deferencing a dangling pointer
+ * // (of course, it could actually be fine depending on the implementation of doSomethingWithFoo)
+ *
+ * // Recommendation is to use strong reference for async operations
+ * const myFooStrong = myFooWeak.getStrong();
+ * await doSomethingWithFoo(myFooStrong.getWeak()); // will never be freed while awaiting
+ * // now we free
+ * myFooStrong.free();
+ *
+ * ```
+ *
+ * ## Assigning to Erc
+ * Each `Erc` instance should only ever have one external reference. So you should not
+ * assign to an `Erc` variable directly:
+ * ```typescript
+ * // DO NOT DO THIS
+ * let myFoo = makeFooErc(createFoo());
+ * myFoo = makeFooErc(createFoo()); // previous Erc is overriden without proper clean up
+ * ```
+ *
+ * If you want to attach a new value to an existing `Erc`, use the `assign` method:
+ * ```typescript
+ * const myFoo = makeFooErc(createFoo());
+ * myFoo.assign(createFoo()); // previous Erc is freed, and the new one is assigned
+ * myFoo.free(); // new one is freed
+ * ```
+ * The example above does not cause leaks, since the previous Erc is freed
+ *
+ * However, if you call assign with the value of another `Erc`, it will cause memory
+ * issues:
+ * ```typescript
+ * // DO NOT DO THIS
+ * const myFoo1 = makeFooErc(createFoo());
+ * const myFoo2 = makeFooErc(createFoo());
+ * myFoo1.assign(myFoo2.value); // myFoo1 is freed, and myFoo2 is assigned
+ * // BAD: now both myFoo1 and myFoo2 references the same object, but the ref count is 1
+ * myFoo1.free(); // no issue here, object is freed, but myFoo2 now holds a dangling pointer
+ * myFoo2.free(); // double free!
+ *
+ * // The correct way to do this is to use `take`:
+ * const myFoo1 = makeFooErc(createFoo());
+ * const myFoo2 = makeFooErc(createFoo());
+ * myFoo1.assign(myFoo2.take()); // myFoo1 is freed, and myFoo2 is assigned, myFoo2 is empty
+ * myFoo1.free(); // no issue here, object is freed
+ * // myFoo2 is empty, so calling free() has no effect
+ * ```
+ *
+ * Assign also works if both `Erc` are 2 references of the same object:
+ * ```typescript
+ * const myFoo1 = makeFooErc(createFoo()); // ref count is 1
+ * const myFoo2 = myFoo1.getStrong(); // ref count is 2
+ * myFoo1.assign(myFoo2.take()); // frees old value, ref count is 1
+ *
+ * // This also works:
+ * const myFoo1 = makeFooErc(createFoo()); // ref count is 1
+ * myFoo1.assign(myFoo1.take()); // take() makes myFoo1 empty, so assign() doesn't free it
+ *
+ * // DO NOT DO THIS:
+ * myFoo1.assign(myFoo1.value); // this will free the value since ref count is 0, and result in a dangling pointer
+ * ```
+ *
+ */
+export const makeErcType = <TName, TRepr>({
+    marker,
+    free,
+    addRef,
+}: ErcTypeConstructor<TName, TRepr>): ((
+    value: TRepr | undefined,
+) => Erc<TName, TRepr>) => {
+    const createStrongRef = (value: TRepr | undefined): Erc<TName, TRepr> => {
+        let weakRef:
+            | (ErcRef<TName, TRepr> & { invalidate: () => void })
+            | undefined = undefined;
+        const invalidateWeakRef = () => {
+            if (!weakRef) {
+                return;
+            }
+            const oldWeakRef = weakRef;
+            weakRef = undefined;
+            oldWeakRef.invalidate();
+        };
+        const createWeakRef = (initialValue: TRepr | undefined) => {
+            const weak = {
+                type: marker,
+                value: initialValue,
+                invalidate: () => {
+                    weak.value = undefined;
+                },
+                getStrong: () => {
+                    if (weak.value === undefined) {
+                        return createStrongRef(undefined);
+                    }
+                    return createStrongRef(addRef(weak.value));
+                },
+            };
+            return weak;
+        };
+        const erc = {
+            type: marker,
+            value,
+            free: () => {
+                if (erc.value !== undefined) {
+                    invalidateWeakRef();
+                    free(erc.value);
+                    erc.value = undefined;
+                }
+            },
+            assign: (newValue: TRepr | undefined) => {
+                erc.free();
+                erc.value = newValue;
+            },
+            take: () => {
+                invalidateWeakRef();
+                const oldValue = erc.value;
+                erc.value = undefined;
+                return oldValue;
+            },
+            getWeak: () => {
+                if (!weakRef) {
+                    weakRef = createWeakRef(erc.value);
+                }
+                return weakRef;
+            },
+            getStrong: () => {
+                if (erc.value === undefined) {
+                    return createStrongRef(undefined);
+                }
+                return createStrongRef(addRef(erc.value));
+            },
+        };
+        return erc;
+    };
+    return createStrongRef;
+};

package/src/memory/index.ts

@@ -6,4 +6,4 @@
  */
 export { cell, type CellConstructor, type Cell } from "./cell.ts";
 export { persist, type PersistConstructor, type Persist } from "./persist.ts";
-export * from "./weak.ts";
+export * from "./erc.ts";

package/src/result/index.ts

@@ -197,19 +197,38 @@ export async function tryAsync<T, E = unknown>(
 }
 
 /** Try best effort converting an error to a string */
-export function errstr(e: unknown): string {
+export function errstr(e: unknown, recursing?: boolean): string {
     if (typeof e === "string") {
         return e;
     }
-    if (e) {
-        if (typeof e === "object" && "message" in e) {
-            if (typeof e.message === "string") {
-                return e.message;
-            }
+    if (!e) {
+        return `${e}`;
+    }
+    if (typeof e === "object" && "message" in e) {
+        if (!recursing) {
+            return errstr(e.message, true);
+        }
+        return `${e.message}`;
+    }
+    if (typeof e === "object" && "toString" in e) {
+        const s = e.toString();
+        if (!recursing) {
+            return errstr(s, true);
         }
-        if (typeof e === "object" && "toString" in e) {
-            return e.toString();
+        return `${s}`;
+    }
+    // try less-likely fields
+    if (typeof e === "object" && "msg" in e) {
+        if (!recursing) {
+            return errstr(e.msg, true);
+        }
+        return `${e.msg}`;
+    }
+    if (typeof e === "object" && "code" in e) {
+        if (!recursing) {
+            return `error code: ${errstr(e.code, true)}`;
         }
+        return `${e.code}`;
     }
     return `${e}`;
 }

package/src/memory/weak.ts

@@ -1,140 +0,0 @@
-export type ExternalWeakRef<TUnderlying, TType> = {
-    /**
-     * A marker value for the underlying object type.
-     *
-     * This is commonly a string literal or a symbol.
-     */
-    type: TType;
-
-    /**
-     * The underlying object reference.
-     */
-    ref: TUnderlying | undefined;
-
-    /**
-     * Free the underlying object.
-     */
-    free: () => void;
-
-    /**
-     * Update the underlying object reference.
-     *
-     * If the new reference is the same as the old one, nothing will happen.
-     * If the old reference is not undefined, it will be freed.
-     */
-    set: (value: TUnderlying | undefined) => void;
-};
-
-export type ExternalWeakRefConstructor<TUnderlying, TType> = {
-    /**
-     * A marker value for the underlying object type.
-     *
-     * This is commonly a string literal or a symbol.
-     */
-    marker: TType;
-
-    /**
-     * The function to free the underlying object.
-     */
-    free: (obj: TUnderlying) => void;
-};
-
-/**
- * Create a weak reference type for managing externally memory-managed object. This means
- * the objects needs to be freed manually by the external code.
- *
- * The `marker` option is used to distinguish between different types of weak references
- * with the same underlying representation for the reference.
- *
- * Note that the underlying representation should not be undefined-able!
- *
- * ## Example
- * ```typescript
- * import { makeExternalWeakRefType } from "@pistonite/pure/memory";
- *
- * // assume `number` is the JS type used to represent the external object
- * // for example, this can be a pointer to a C++ object
- * declare function freeFoo(obj: number) => void;
- *
- * // some function that allocates a foo object externally and returns
- * // a reference
- * declare function getFoo(): number;
- *
- * const makeFooRef = makeExternalWeakRefType({
- *     marker: "foo",
- *     free: (obj) => {
- *         freeFoo(obj);
- *     }
- * });
- * type FooRef = ReturnType<typeof makeFooRef>;
- *
- * // create a reference to a foo object
- * // now this reference can be passed around in JS,
- * // as long as the ownership model is clear and the owner
- * // remembers to free it
- * const fooRef = makeFooRef(getFoo());
- *
- * // free the foo object when it is no longer needed
- * fooRef.free();
- *
- * ## Updating the reference
- * The `set` method will update the reference and free the old one if exists
- * ```
- * const fooRef = makeFooRef(getFoo());
- * fooRef.set(getFoo()); // the old one will be freed, unless it is the same as the new one
- * ```
- *
- * This has a major pitfall: If the ExternalWeakRef is shared, the new object will be accessible
- * by code that has the old reference. In other words, when the reference is updated, code that
- * already has the old reference will not able to know that it has changed.
- *
- * If this is a problem, you should use this pattern instead:
- * ```typescript
- * // track the "current" valid reference
- * let currentRef = makeFooRef(undefined);
- *
- * export const getFooRef = (): FooRef => {
- *     // because of this function, many other places can hold
- *     // a valid reference to foo
- *     return currentRef;
- * }
- *
- * export const updateFooRef = (newFoo: number): void => {
- *     // when updating the reference, we create a new weak ref and free the old one
- *     if (currentRef.ref === newFoo) {
- *         return; // always need to check if old and new are the same, otherwise we will be freeing the new one
- *     }
- *     const newRef = makeFooRef(newFoo);
- *     currentRef.free();
- *     currentRef = newRef;
- *
- *     // now other places that hold the old reference will see it's freed
- * }
- * ```
- */
-export const makeExternalWeakRefType = <TUnderlying, TType>({
-    marker,
-    free,
-}: ExternalWeakRefConstructor<TUnderlying, TType>) => {
-    return (
-        obj: TUnderlying | undefined,
-    ): ExternalWeakRef<TUnderlying, TType> => {
-        const weakRefObj = {
-            type: marker,
-            ref: obj,
-            free: () => {
-                if (weakRefObj.ref !== undefined) {
-                    free(weakRefObj.ref);
-                }
-                weakRefObj.ref = undefined;
-            },
-            set: (value: TUnderlying | undefined) => {
-                if (weakRefObj.ref !== undefined && weakRefObj.ref !== value) {
-                    free(weakRefObj.ref);
-                }
-                weakRefObj.ref = value;
-            },
-        };
-        return weakRefObj;
-    };
-};