bunja 0.0.0 → 0.0.2

package/README.md

@@ -1,8 +1,59 @@
 # Bunja
 
-Minimal Dependency Injection Library for React. (Minified & gzipped size < 1kB)\
+Bunja is State Lifetime Manager for React. (Minified & gzipped size < 1kB)\
 Heavily inspired by [Bunshi](https://github.com/saasquatch/bunshi).
 
 > Definition: Bunja (分子 / 분자) - Korean for molecule, member or element.
 
-## TODO: How to use
+## Why is managing the lifetime of state necessary?
+
+Global state managers like jotai or signals offer the advantage of declaratively describing state and effectively reducing render counts,
+but they lack suitable methods for managing resources with a defined start and end.\
+For example, consider establishing and closing a WebSocket connection or a modal form UI that appears temporarily and then disappears.
+
+Bunja is a library designed to address these weaknesses.\
+Each state defined with Bunja has a lifetime that begins when it is first depended on somewhere in the render tree and ends when all dependencies disappear.
+
+Therefore, when writing a state to manage a WebSocket,
+you only need to create a function that establishes the WebSocket connection and an dispose handler that terminates the connection.\
+The library automatically tracks the actual usage period and calls the init and dispose as needed.
+
+## So, do I no longer need jotai or other state management libraries?
+
+No. Bunja focuses solely on managing the lifetime of state, so jotai and other state management libraries are still valuable.\
+You can typically use jotai or something, and when lifetime management becomes necessary, you can wrap those states with bunja.
+
+## How to use
+
+Bunja provides two functions: `bunja` and `useBunja`.\
+You can use `bunja` to define a state with a finite lifetime and use the `useBunja` hook to access that state.
+
+### Defining a Bunja
+
+You can define a bunja using the `bunja` function. When you access the defined bunja with the `useBunja` hook, a bunja instance is created.\
+If all components in the render tree that refer to the bunja disappear, the bunja instance is automatically destroyed.
+
+If you want to clean up resources when the bunja's lifetime ends, you can use the `Symbol.dispose` field.
+
+```ts
+const countBunja = bunja([], () => {
+  const countAtom = atom(0);
+  return {
+    countAtom,
+    [Symbol.dispose]() {
+      console.log("disposed");
+    },
+  };
+});
+
+function MyComponent() {
+  const { countAtom } = useBunja(countBunja);
+  const [count, setCount] = useAtom(countAtom);
+  // Your component logic here
+}
+```
+
+This code snippet defines a bunja that creates a `countAtom`.\
+The `Symbol.dispose` method is used when the bunja instance is no longer referenced by any component in the render tree, allowing you to clean up resources appropriately.
+
+TODO: context

package/bunja.ts

@@ -1,5 +1,11 @@
 import * as React from "react";
 
+disposePolyfill: {
+  const S = Symbol as any;
+  S.dispose ??= Symbol.for("dispose");
+  S.asyncDispose ??= Symbol.for("asyncDispose");
+}
+
 type Dep<T> = React.Context<T> | Bunja<T>;
 
 class Bunja<T> {
@@ -7,32 +13,24 @@ class Bunja<T> {
     public id: number,
     public deps: Dep<any>[],
     public contexts: React.Context<any>[],
-    public init: (args: any[], dispose: () => void) => BunjaInstance<T>
+    public init: (...args: any[]) => T
   ) {}
 }
 
-interface BunjaInitResult<T> {
-  value: T;
-  mount?: () => void;
-  unmount?: () => void;
-}
-
-export function bunja<T>(deps: [], init: () => BunjaInitResult<T>): Bunja<T>;
-export function bunja<T, U>(
-  deps: [Dep<U>],
-  init: (u: U) => BunjaInitResult<T>
-): Bunja<T>;
+const bunjas: Record<string, BunjaInstance<any>> = {};
+export function bunja<T>(deps: [], init: () => T): Bunja<T>;
+export function bunja<T, U>(deps: [Dep<U>], init: (u: U) => T): Bunja<T>;
 export function bunja<T, U, V>(
   deps: [Dep<U>, Dep<V>],
-  init: (u: U, v: V) => BunjaInitResult<T>
+  init: (u: U, v: V) => T
 ): Bunja<T>;
 export function bunja<T, U, V, W>(
   deps: [Dep<U>, Dep<V>, Dep<W>],
-  init: (u: U, v: V, w: W) => BunjaInitResult<T>
+  init: (u: U, v: V, w: W) => T
 ): Bunja<T>;
 export function bunja<T, const U extends any[]>(
   deps: { [K in keyof U]: Dep<U[K]> },
-  init: (...args: U) => BunjaInitResult<T>
+  init: (...args: U) => T
 ): Bunja<T> {
   const contexts = deps.filter(
     (dep) => !(dep instanceof Bunja)
@@ -41,17 +39,12 @@ export function bunja<T, const U extends any[]>(
   const dedupedContexts = Array.from(
     new Set([...contexts, ...bunjas.flatMap((def) => def.contexts)])
   );
-  return new Bunja(bunja.counter++, deps, dedupedContexts, (args, dispose) => {
-    const noop = () => {};
-    const { value, mount = noop, unmount = noop } = init(...(args as U));
-    mount();
-    return new BunjaInstance(() => (dispose(), unmount()), value);
-  });
+  return new Bunja(bunja.counter++, deps, dedupedContexts, init);
 }
 bunja.counter = 0;
 
 export function useBunja<T>(bunja: Bunja<T>): T {
-  const { id, deps, contexts } = bunja;
+  const { id, deps, contexts, init } = bunja;
   const rid = useRid();
   const tuples = contexts.map((c) => [c, React.useContext(c)] as const);
   const scopes = tuples.map(([context, value]) => getScope(context, value));
@@ -64,28 +57,21 @@ export function useBunja<T>(bunja: Bunja<T>): T {
     .map(({ id }) => id)
     .sort()
     .join(",")}`;
-  const bunjaInstance = getBunjaInstance(bunja, biid, args);
+  const instance = (bunjas[biid] ??= new BunjaInstance(biid, init(...args)));
   React.useEffect(() => {
-    bunjaInstance.reg(rid);
-    return () => bunjaInstance.dereg(rid);
-  }, [bunjaInstance]);
+    instance.reg(rid);
+    return () => instance.dereg(rid);
+  }, [instance]);
   React.useEffect(() => {
     scopes.forEach((scope) => scope.reg(rid));
     return () => scopes.forEach((scope) => scope.dereg(rid));
-  }, [rid]);
-  return bunjaInstance.value;
+  }, [rid, ...scopes]);
+  return instance.value;
 }
 
 const useRid = () => React.useState(() => useRid.counter++)[0];
 useRid.counter = 0;
 
-const bunjas: Record<string, BunjaInstance<any>> = {};
-function getBunjaInstance<T>(bunja: Bunja<T>, biid: string, args: any[]) {
-  return (bunjas[biid] ??= bunja.init(args, () => {
-    delete bunjas[biid];
-  }));
-}
-
 const scopes = new WeakMap<React.Context<any>, Map<any, Scope>>();
 function getScope(context: React.Context<any>, value: any) {
   const m = scopes.get(context) ?? scopes.set(context, new Map()).get(context)!;
@@ -98,7 +84,6 @@ getScope.counter = 0;
 class RefCounter<T = number> {
   #disposed = false;
   refs = new Set<T>();
-  constructor(public dispose: () => void) {}
   reg(reference: T) {
     this.refs.add(reference);
   }
@@ -108,15 +93,19 @@ class RefCounter<T = number> {
       if (this.#disposed) return;
       if (this.refs.size < 1) {
         this.#disposed = true;
-        this.dispose();
+        this[Symbol.dispose]();
       }
     });
   }
 }
 
 class BunjaInstance<T> extends RefCounter {
-  constructor(dispose: () => void, public value: T) {
-    super(dispose);
+  constructor(public biid: string, public value: T) {
+    super();
+  }
+  [Symbol.dispose]() {
+    delete bunjas[this.biid];
+    (this.value[Symbol.asyncDispose] ?? this.value[Symbol.dispose])?.();
   }
 }
 
@@ -127,6 +116,7 @@ class Scope extends RefCounter {
     public value: any,
     public id: number
   ) {
-    super(dispose);
+    super();
+    this[Symbol.dispose] = dispose;
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bunja",
-  "version": "0.0.0",
-  "description": "Minimal Dependency Injection Library for React",
+  "version": "0.0.2",
+  "description": "State Lifetime Manager for React",
   "main": "bunja.ts",
   "scripts": {},
   "keywords": [

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "compilerOptions": {
+    "target": "ESNext"
+  }
+}