bunja 0.0.12 → 1.0.0

package/.vscode/settings.json

@@ -1,4 +1,5 @@
 {
+  "deno.enable": true,
   "editor.formatOnSave": true,
-  "editor.defaultFormatter": "esbenp.prettier-vscode"
+  "editor.defaultFormatter": "denoland.vscode-deno"
 }

package/README.md

@@ -57,4 +57,170 @@ function MyComponent() {
 }
 ```
 
-TODO: context
+### Defining a Bunja that relies on other Bunja
+
+If you want to manage a state with a broad lifetime and another state with a narrower lifetime, you can create a (narrower) bunja that depends on a (broader) bunja.
+For example, you can think of a bunja that manages the WebSocket connection and disconnection, and another bunja that subscribes to a specific resource over the connected WebSocket.
+
+In an application composed of multiple pages, you might want to subscribe to the Foo resource on page A and the Bar resource on page B, while using the same WebSocket connection regardless of which page you're on.
+In such a case, you can write the following code.
+
+```ts
+// To simplify the example, code for buffering and reconnection has been omitted.
+const websocketBunja = bunja([], () => {
+  let socket;
+  const send = (message) => socket.send(JSON.stringify(message));
+
+  const emitter = new EventEmitter();
+  const on = (handler) => {
+    emitter.on("message", handler);
+    return () => emitter.off("message", handler);
+  };
+
+  return {
+    send,
+    on,
+    [bunja.effect]() {
+      socket = new WebSocket("...");
+      socket.onmessage = (e) => emitter.emit("message", JSON.parse(e.data));
+      return () => socket.close();
+    },
+  };
+});
+
+const resourceFooBunja = bunja([websocketBunja], ({ send, on }) => {
+  const resourceFooAtom = atom();
+  return {
+    resourceFooAtom,
+    [bunja.effect]() {
+      const off = on((message) => {
+        if (message.type === "foo") store.set(resourceAtom, message.value);
+      });
+      send("subscribe-foo");
+      return () => {
+        send("unsubscribe-foo");
+        off();
+      };
+    },
+  };
+});
+
+const resourceBarBunja = bunja([websocketBunja], ({ send, on }) => {
+  const resourceBarAtom = atom();
+  // ...
+});
+
+function PageA() {
+  const { resourceFooAtom } = useBunja(resourceFooBunja);
+  const resourceFoo = useAtomValue(resourceFooAtom);
+  // ...
+}
+
+function PageB() {
+  const { resourceBarAtom } = useBunja(resourceBarBunja);
+  const resourceBar = useAtomValue(resourceBarAtom);
+  // ...
+}
+```
+
+Notice that `websocketBunja` is not directly `useBunja`-ed.
+When you `useBunja` either `resourceFooBunja` or `resourceBarBunja`, since they depend on `websocketBunja`,
+it has the same effect as if `websocketBunja` were also `useBunja`-ed.
+
+> [!NOTE]
+> When a bunja starts, the initialization effect of the bunja with a broader lifetime is called first.\
+> Similarly, when a bunja ends, the cleanup effect of the bunja with the broader lifetime is called first.\
+> This behavior is aligned with how React's `useEffect` cleanup function is invoked, where the parent’s cleanup is executed before the child’s in the render tree.
+>
+> See: <https://github.com/facebook/react/issues/16728>
+
+### Dependency injection using Scope
+
+You can use a bunja for local state management.\
+When you specify a scope as a dependency of the bunja, separate bunja instances are created based on the values injected into the scope.
+
+```ts
+import { bunja, createScope } from "bunja";
+
+const UrlScope = createScope();
+
+const fetchBunja = bunja([UrlScope], (url) => {
+  const queryAtom = atomWithQuery((get) => ({
+    queryKey: [url],
+    queryFn: async () => (await fetch(url)).json(),
+  }));
+  return { queryAtom };
+});
+```
+
+#### Injecting dependencies via React context
+
+If you bind a scope to a React context, bunjas that depend on the scope can retrieve values from the corresponding React context.
+
+In the example below, there are two React instances (`<ChildComponent />`) that reference the same `fetchBunja`, but since each looks at a different context value, two separate bunja instances are also created.
+
+```tsx
+import { createContext } from "react";
+import { bunja, createScope } from "bunja";
+import { bindScope } from "bunja/react";
+
+const UrlContext = createContext("https://example.com/");
+const UrlScope = createScope();
+bindScope(UrlScope, UrlContext);
+
+const fetchBunja = bunja([UrlScope], (url) => {
+  const queryAtom = atomWithQuery((get) => ({
+    queryKey: [url],
+    queryFn: async () => (await fetch(url)).json(),
+  }));
+  return { queryAtom };
+});
+
+function ParentComponent() {
+  return (
+    <>
+      <UrlContext.Provider value="https://example.com/foo">
+        <ChildComponent />
+      </UrlContext.Provider>
+      <UrlContext.Provider value="https://example.com/bar">
+        <ChildComponent />
+      </UrlContext.Provider>
+    </>
+  );
+}
+
+function ChildComponent() {
+  const { queryAtom } = useBunja(fetchBunja);
+  const { data, isPending, isError } = useAtomValue(queryAtom);
+  // Your component logic here
+}
+```
+
+You can use the `createScopeFromContext` function to handle both the creation of the scope and the binding to the context in one step.
+
+```ts
+import { createContext } from "react";
+import { createScopeFromContext } from "bunja/react";
+
+const UrlContext = createContext("https://example.com/");
+const UrlScope = createScopeFromContext(UrlContext);
+```
+
+#### Injecting dependencies directly into the scope
+
+You might want to use a bunja directly within a React component where the values to be injected into the scope are created.
+
+In such cases, you can use the inject function to inject values into the scope without wrapping the context separately.
+
+```tsx
+import { inject } from "bunja/react";
+
+function MyComponent() {
+  const { queryAtom } = useBunja(
+    fetchBunja,
+    inject([[UrlScope, "https://example.com/"]])
+  );
+  const { data, isPending, isError } = useAtomValue(queryAtom);
+  // Your component logic here
+}
+```

package/bunja.ts

@@ -1,5 +1,8 @@
 export type Dep<T> = Bunja<T> | Scope<T>;
 
+const bunjaEffectSymbol: unique symbol = Symbol("Bunja.effect");
+type BunjaEffectSymbol = typeof bunjaEffectSymbol;
+
 export class Bunja<T> {
   public static readonly bunjas: Bunja<any>[] = [];
   public readonly id: number;
@@ -9,27 +12,29 @@ export class Bunja<T> {
     public parents: Bunja<any>[], // one depth parents
     public relatedBunjas: Bunja<any>[], // toposorted parents without self
     public relatedScopes: Scope<any>[], // deduped
-    public init: (...args: any[]) => T & BunjaValue
+    public init: (...args: any[]) => T & BunjaValue,
   ) {
     this.id = Bunja.bunjas.length;
     Bunja.bunjas.push(this);
   }
-  static readonly effect = Symbol("Bunja.effect");
-  toString() {
+  static readonly effect: BunjaEffectSymbol = bunjaEffectSymbol;
+  toString(): string {
     const { id, debugLabel } = this;
     return `[Bunja:${id}${debugLabel && ` - ${debugLabel}`}]`;
   }
 }
 
+export type HashFn<T = any, U = any> = (value: T) => U;
+
 export class Scope<T> {
   public static readonly scopes: Scope<any>[] = [];
   public readonly id: number;
   public debugLabel: string = "";
-  constructor() {
+  constructor(public readonly hash: HashFn = id) {
     this.id = Scope.scopes.length;
     Scope.scopes.push(this);
   }
-  toString() {
+  toString(): string {
     const { id, debugLabel } = this;
     return `[Scope:${id}${debugLabel && ` - ${debugLabel}`}]`;
   }
@@ -40,12 +45,19 @@ export type ReadScope = <T>(scope: Scope<T>) => T;
 export class BunjaStore {
   #bunjas: Record<string, BunjaInstance> = {};
   #scopes: Map<Scope<any>, Map<any, ScopeInstance>> = new Map();
-  get<T>(bunja: Bunja<T>, readScope: ReadScope) {
+  get<T>(
+    bunja: Bunja<T>,
+    readScope: ReadScope,
+  ): {
+    value: T;
+    mount: () => () => void;
+    deps: any[];
+  } {
     const scopeInstanceMap = new Map(
       bunja.relatedScopes.map((scope) => [
         scope,
         this.#getScopeInstance(scope, readScope(scope)),
-      ])
+      ]),
     );
     const bunjaInstance = this.#getBunjaInstance(bunja, scopeInstanceMap);
     const { relatedBunjaInstanceMap } = bunjaInstance; // toposorted
@@ -55,7 +67,7 @@ export class BunjaStore {
         relatedBunjaInstanceMap.forEach((related) => related.add());
         bunjaInstance.add();
         scopeInstanceMap.forEach((scope) => scope.add());
-        return function unmount() {
+        return function unmount(): void {
           // concern: reverse order?
           relatedBunjaInstanceMap.forEach((related) => related.sub());
           bunjaInstance.sub();
@@ -67,10 +79,10 @@ export class BunjaStore {
   }
   #getBunjaInstance(
     bunja: Bunja<any>,
-    scopeInstanceMap: Map<Scope<any>, ScopeInstance>
+    scopeInstanceMap: Map<Scope<any>, ScopeInstance>,
   ): BunjaInstance {
     const localScopeInstanceMap = new Map(
-      bunja.relatedScopes.map((scope) => [scope, scopeInstanceMap.get(scope)!])
+      bunja.relatedScopes.map((scope) => [scope, scopeInstanceMap.get(scope)!]),
     );
     const scopeInstanceIds = Array.from(localScopeInstanceMap.values())
       .map(({ instanceId }) => instanceId)
@@ -81,7 +93,7 @@ export class BunjaStore {
       bunja.relatedBunjas.map((relatedBunja) => [
         relatedBunja,
         this.#getBunjaInstance(relatedBunja, scopeInstanceMap),
-      ])
+      ]),
     );
     const args = bunja.deps.map((dep) => {
       if (dep instanceof Bunja) return relatedBunjaInstanceMap.get(dep)!.value;
@@ -92,76 +104,78 @@ export class BunjaStore {
       () => delete this.#bunjas[bunjaInstanceId],
       bunjaInstanceId,
       relatedBunjaInstanceMap,
-      bunja.init.apply(bunja, args)
+      bunja.init.apply(bunja, args),
     );
     this.#bunjas[bunjaInstanceId] = bunjaInstance;
     return bunjaInstance;
   }
   #getScopeInstance(scope: Scope<any>, value: any): ScopeInstance {
-    const scopeInstanceMap =
-      this.#scopes.get(scope) ?? this.#scopes.set(scope, new Map()).get(scope)!;
+    const key = scope.hash(value);
+    const scopeInstanceMap = this.#scopes.get(scope) ??
+      this.#scopes.set(scope, new Map()).get(scope)!;
     const init = () =>
       new ScopeInstance(
-        () => scopeInstanceMap.delete(value),
+        () => scopeInstanceMap.delete(key),
         ScopeInstance.counter++,
         scope,
-        value
+        value,
       );
     return (
-      scopeInstanceMap.get(value) ??
-      scopeInstanceMap.set(value, init()).get(value)!
+      scopeInstanceMap.get(key) ??
+        scopeInstanceMap.set(key, init()).get(key)!
     );
   }
 }
 
-export const createBunjaStore = () => new BunjaStore();
+export const createBunjaStore = (): BunjaStore => new BunjaStore();
 
 export type BunjaEffectFn = () => () => void;
 export interface BunjaValue {
   [Bunja.effect]?: BunjaEffectFn;
 }
 
-export function bunja<T>(deps: [], init: () => T & BunjaValue): Bunja<T>;
-export function bunja<T, U>(
-  deps: [Dep<U>],
-  init: (u: U) => T & BunjaValue
-): Bunja<T>;
-export function bunja<T, U, V>(
-  deps: [Dep<U>, Dep<V>],
-  init: (u: U, v: V) => T & BunjaValue
-): Bunja<T>;
-export function bunja<T, U, V, W>(
-  deps: [Dep<U>, Dep<V>, Dep<W>],
-  init: (u: U, v: V, w: W) => T & BunjaValue
-): Bunja<T>;
-export function bunja<T, U, V, W, X>(
-  deps: [Dep<U>, Dep<V>, Dep<W>, Dep<X>],
-  init: (u: U, v: V, w: W, x: X) => T & BunjaValue
-): Bunja<T>;
-export function bunja<T, U, V, W, X, Y>(
-  deps: [Dep<U>, Dep<V>, Dep<W>, Dep<X>, Dep<Y>],
-  init: (u: U, v: V, w: W, x: X, y: Y) => T & BunjaValue
-): Bunja<T>;
-export function bunja<T, U, V, W, X, Y, Z>(
-  deps: [Dep<U>, Dep<V>, Dep<W>, Dep<X>, Dep<Y>, Dep<Z>],
-  init: (u: U, v: V, w: W, x: X, y: Y, z: Z) => T & BunjaValue
-): Bunja<T>;
-export function bunja<T, const U extends any[]>(
+function bunjaImpl<T, const U extends any[]>(
   deps: { [K in keyof U]: Dep<U[K]> },
-  init: (...args: U) => T & BunjaValue
+  init: (...args: U) => T & BunjaValue,
 ): Bunja<T> {
   const parents = deps.filter((dep) => dep instanceof Bunja) as Bunja<any>[];
   const scopes = deps.filter((dep) => dep instanceof Scope) as Scope<any>[];
   const relatedBunjas = toposort(parents);
   const relatedScopes = Array.from(
-    new Set([...scopes, ...parents.flatMap((parent) => parent.relatedScopes)])
+    new Set([...scopes, ...parents.flatMap((parent) => parent.relatedScopes)]),
   );
   return new Bunja(deps, parents, relatedBunjas, relatedScopes, init as any);
 }
-bunja.effect = Bunja.effect;
+bunjaImpl.effect = Bunja.effect;
 
-export function createScope<T>(): Scope<T> {
-  return new Scope();
+export const bunja: {
+  <T>(deps: [], init: () => T & BunjaValue): Bunja<T>;
+  <T, U>(deps: [Dep<U>], init: (u: U) => T & BunjaValue): Bunja<T>;
+  <T, U, V>(
+    deps: [Dep<U>, Dep<V>],
+    init: (u: U, v: V) => T & BunjaValue,
+  ): Bunja<T>;
+  <T, U, V, W>(
+    deps: [Dep<U>, Dep<V>, Dep<W>],
+    init: (u: U, v: V, w: W) => T & BunjaValue,
+  ): Bunja<T>;
+  <T, U, V, W, X>(
+    deps: [Dep<U>, Dep<V>, Dep<W>, Dep<X>],
+    init: (u: U, v: V, w: W, x: X) => T & BunjaValue,
+  ): Bunja<T>;
+  <T, U, V, W, X, Y>(
+    deps: [Dep<U>, Dep<V>, Dep<W>, Dep<X>, Dep<Y>],
+    init: (u: U, v: V, w: W, x: X, y: Y) => T & BunjaValue,
+  ): Bunja<T>;
+  <T, U, V, W, X, Y, Z>(
+    deps: [Dep<U>, Dep<V>, Dep<W>, Dep<X>, Dep<Y>, Dep<Z>],
+    init: (u: U, v: V, w: W, x: X, y: Y, z: Z) => T & BunjaValue,
+  ): Bunja<T>;
+  readonly effect: BunjaEffectSymbol;
+} = bunjaImpl;
+
+export function createScope<T>(hash?: HashFn): Scope<T> {
+  return new Scope(hash);
 }
 
 abstract class RefCounter {
@@ -183,6 +197,7 @@ abstract class RefCounter {
   abstract dispose(): void;
 }
 
+const id = <T>(x: T): T => x;
 const noop = () => {};
 class BunjaInstance extends RefCounter {
   #cleanup: (() => void) | undefined;
@@ -191,7 +206,7 @@ class BunjaInstance extends RefCounter {
     dispose: () => void,
     public instanceId: string,
     public relatedBunjaInstanceMap: Map<Bunja<any>, BunjaInstance>,
-    public value: BunjaValue
+    public value: BunjaValue,
   ) {
     super();
     this.#dispose = () => {
@@ -199,7 +214,7 @@ class BunjaInstance extends RefCounter {
       dispose();
     };
   }
-  add() {
+  override add() {
     this.#cleanup ??= this.value[Bunja.effect]?.() ?? noop;
     super.add();
   }
@@ -214,7 +229,7 @@ class ScopeInstance extends RefCounter {
     public dispose: () => void,
     public instanceId: number,
     public scope: Scope<any>,
-    public value: any
+    public value: any,
   ) {
     super();
   }

package/deno.json

@@ -0,0 +1,9 @@
+{
+  "name": "@disjukr/bunja",
+  "version": "1.0.0",
+  "license": "Zlib",
+  "exports": {
+    ".": "./bunja.ts",
+    "./react": "./react.ts"
+  }
+}