@felixfern/tunnel-fn 2.0.0

package/README.md

@@ -0,0 +1,217 @@
+# @felixfern/tunnel-fn
+
+[![npm](https://img.shields.io/npm/v/@felixfern/tunnel-fn)](https://www.npmjs.com/package/@felixfern/tunnel-fn)
+
+Type-safe function tunneling across React components via context. Call functions registered in distant components without prop drilling.
+
+## Install
+
+```bash
+npm install @felixfern/tunnel-fn
+```
+
+```bash
+pnpm add @felixfern/tunnel-fn
+```
+
+```bash
+yarn add @felixfern/tunnel-fn
+```
+
+Requires React >= 16.8.0 as a peer dependency.
+
+## Quick Start
+
+### 1. Define your tunnel
+
+```tsx
+// tunnel.ts
+import { createTunnel } from "@felixfern/tunnel-fn";
+
+const { TunnelProvider, useTunnel, useTunnelFunction } = createTunnel<{
+  showAlert: (message: string) => void;
+  getCount: () => number;
+}>();
+
+export { TunnelProvider, useTunnel, useTunnelFunction };
+```
+
+### 2. Wrap with Provider
+
+```tsx
+// App.tsx
+import { TunnelProvider } from "./tunnel";
+
+function App() {
+  return (
+    <TunnelProvider>
+      <ComponentA />
+      <ComponentB />
+    </TunnelProvider>
+  );
+}
+```
+
+### 3. Register functions
+
+```tsx
+// ComponentA.tsx
+import { useTunnelFunction } from "./tunnel";
+
+function ComponentA() {
+  useTunnelFunction("showAlert", (message: string) => {
+    alert(message);
+  });
+
+  return <div>Component A</div>;
+}
+```
+
+### 4. Call from anywhere
+
+```tsx
+// ComponentB.tsx
+import { useTunnel } from "./tunnel";
+
+function ComponentB() {
+  const { call } = useTunnel();
+
+  return (
+    <button onClick={() => call("showAlert", "Hello from B!")}>
+      Trigger Alert
+    </button>
+  );
+}
+```
+
+Everything is fully typed — `call("showAlert", 123)` is a type error because `showAlert` expects a `string`.
+
+## API
+
+### `createTunnel<T>()`
+
+Creates a scoped tunnel instance. `T` is a record mapping function names to their signatures.
+
+```tsx
+const { TunnelProvider, useTunnel, useTunnelFunction } = createTunnel<{
+  onSave: (data: FormData) => void;
+  onCancel: () => void;
+  validate: (field: string) => boolean;
+}>();
+```
+
+Returns `{ TunnelProvider, useTunnel, useTunnelFunction }`.
+
+### `TunnelProvider`
+
+React component that scopes the tunnel. All `useTunnel` and `useTunnelFunction` calls must be within a Provider.
+
+```tsx
+<TunnelProvider>{children}</TunnelProvider>
+```
+
+Multiple Providers create independent scopes — functions registered under one Provider are not visible to another.
+
+### `useTunnel()`
+
+Hook that returns `{ call, callAsync, has, onReady }` for invoking tunneled functions.
+
+```tsx
+const { call, callAsync, has, onReady } = useTunnel();
+
+if (has("onSave")) {
+  call("onSave", formData);
+}
+```
+
+- `call(key, ...args)` — Calls the registered function. Returns `undefined` if no function is registered for that key. In development, logs a warning.
+- `callAsync(key, ...args)` — Like `call`, but returns a `Promise`. If the function isn't registered yet, waits until it is, then calls it. Useful when mount order is uncertain.
+- `has(key)` — Returns `true` if a function is registered for that key.
+- `onReady(key, callback)` — Calls `callback` with the registered function immediately if available, or when it becomes available. Returns an unsubscribe function.
+
+All methods are fully typed — keys are autocompleted and arguments are type-checked.
+
+#### `callAsync` — handling async functions and deferred calls
+
+```tsx
+// Call an async tunnel function and await the result
+const data = await callAsync("fetchData", userId);
+
+// Or call a function that hasn't been registered yet — it will wait
+useEffect(() => {
+  callAsync("initialize", config).then(() => {
+    console.log("initialized");
+  });
+}, [callAsync]);
+```
+
+#### `onReady` — react to function availability
+
+```tsx
+useEffect(() => {
+  const unsubscribe = onReady("initialize", (fn) => {
+    fn(config);
+  });
+  return unsubscribe;
+}, [onReady]);
+```
+
+### `useTunnelFunction(key, fn)`
+
+Hook that registers a function in the tunnel. Automatically unregisters on unmount.
+
+```tsx
+useTunnelFunction("onSave", (data: FormData) => {
+  console.log(data);
+});
+```
+
+Returns the same function passed in, preserving its type.
+
+## Multiple Tunnels
+
+Create separate tunnels for different concerns:
+
+```tsx
+const formTunnel = createTunnel<{
+  submit: () => void;
+  reset: () => void;
+}>();
+
+const navTunnel = createTunnel<{
+  navigate: (path: string) => void;
+}>();
+```
+
+Each tunnel has its own Provider and hooks — they don't interfere.
+
+## When to Use tunnel-fn
+
+**Good fit:**
+
+- **Sibling communication** — Two components under the same Provider need to talk without lifting state to a common parent.
+- **Scoped imperative actions** — `showToast()`, `openModal()`, `scrollToTop()` — fire-and-forget commands scoped to a subtree.
+- **Decoupled feature modules** — A toolbar triggers actions defined in a content panel, without either knowing about the other's internals.
+- **Plugin-style architectures** — A host component defines the tunnel type, and dynamically-loaded children register implementations.
+
+**Not a good fit:**
+
+- **Parent → child communication** — Use props. Tunnels are for sideways/upward communication.
+- **Global cross-tree state** — If you need shared state across the entire app, use Zustand, Jotai, or Redux. Tunnels scope to a Provider subtree.
+- **Replacing state management** — Tunnels pass _functions_, not _data_. If you need reactive state, use state management.
+- **High-frequency calls** — Tunnels are ref-based (no re-renders), but rapid polling or animation-frame calls are better served by direct refs or pub/sub.
+
+## Dev Warnings
+
+In development (`NODE_ENV !== "production"`), tunnel-fn logs warnings to help catch common mistakes:
+
+| Warning                    | Cause                                                   | Fix                                                                        |
+| -------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------- |
+| **No function registered** | `call("key")` when no component has registered that key | Ensure the registering component is mounted before calling                 |
+| **Duplicate registration** | Two components register the same key under one Provider | Use separate keys or separate tunnels                                      |
+| **Call during render**     | `call()` invoked directly in the component body         | Move to an event handler, `useEffect`, or callback                         |
+| **Registration churn**     | A function is re-registered rapidly (>3×/sec)           | Wrap the function in `useCallback()` before passing to `useTunnelFunction` |
+
+## License
+
+ISC - [Felix Fernando](https://github.com/FelixFern)

package/dist/index.cjs

@@ -0,0 +1,207 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createTunnel: () => createTunnel
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/tunnel.tsx
+var React = __toESM(require("react"), 1);
+var import_react = require("react");
+function createTunnel() {
+  const TunnelContext = (0, import_react.createContext)(null);
+  function TunnelProvider({ children }) {
+    const storeRef = (0, import_react.useRef)(/* @__PURE__ */ new Map());
+    const listenersRef = (0, import_react.useRef)(/* @__PURE__ */ new Map());
+    const isRenderPhaseRef = (0, import_react.useRef)(false);
+    const registrationCountRef = (0, import_react.useRef)(/* @__PURE__ */ new Map());
+    const churnWarnedRef = (0, import_react.useRef)(/* @__PURE__ */ new Set());
+    if (process.env.NODE_ENV !== "production") {
+      isRenderPhaseRef.current = true;
+    }
+    (0, import_react.useLayoutEffect)(() => {
+      isRenderPhaseRef.current = false;
+    });
+    const store = (0, import_react.useRef)({
+      register(key, fn) {
+        var _a;
+        if (process.env.NODE_ENV !== "production") {
+          if (storeRef.current.has(key)) {
+            console.warn(
+              `[tunnel-fn] Duplicate registration for key "${String(key)}". Another component already registered this key. Only the last registration will be active \u2014 this is likely a bug.`
+            );
+          }
+          const now = Date.now();
+          const timestamps = (_a = registrationCountRef.current.get(key)) != null ? _a : [];
+          timestamps.push(now);
+          const recent = timestamps.filter((t) => now - t < 1e3);
+          registrationCountRef.current.set(key, recent);
+          if (recent.length > 3 && !churnWarnedRef.current.has(key)) {
+            churnWarnedRef.current.add(key);
+            console.warn(
+              `[tunnel-fn] Function for key "${String(key)}" is being re-registered rapidly (${recent.length} times in <1s). This usually means the function passed to useTunnelFunction is recreated every render. Wrap it in useCallback() to fix this:
+
+  const handler = useCallback((...) => { ... }, [deps]);
+  useTunnelFunction("${String(key)}", handler);`
+            );
+          }
+        }
+        storeRef.current.set(key, fn);
+        const listeners = listenersRef.current.get(key);
+        if (listeners) {
+          listeners.forEach((cb) => cb(fn));
+          listenersRef.current.delete(key);
+        }
+      },
+      unregister(key) {
+        storeRef.current.delete(key);
+      },
+      call(key, ...args) {
+        if (process.env.NODE_ENV !== "production") {
+          if (isRenderPhaseRef.current) {
+            console.warn(
+              `[tunnel-fn] call("${String(key)}") was invoked during the render phase. Tunnel functions should only be called from event handlers, useEffect, or callbacks \u2014 never directly during render. This can cause unpredictable behavior.`
+            );
+          }
+        }
+        const fn = storeRef.current.get(key);
+        if (!fn) {
+          if (process.env.NODE_ENV !== "production") {
+            console.warn(
+              `[tunnel-fn] No function registered for key "${String(key)}". Make sure a component with useTunnelFunction("${String(key)}", ...) is mounted.`
+            );
+          }
+          return void 0;
+        }
+        return fn(...args);
+      },
+      has(key) {
+        return storeRef.current.has(key);
+      },
+      callAsync(key, ...args) {
+        const fn = storeRef.current.get(key);
+        if (fn) {
+          return Promise.resolve(fn(...args)).then(
+            (v) => v
+          );
+        }
+        return new Promise((resolve) => {
+          const listener = (registeredFn) => {
+            resolve(
+              Promise.resolve(registeredFn(...args)).then(
+                (v) => v
+              )
+            );
+          };
+          let set = listenersRef.current.get(key);
+          if (!set) {
+            set = /* @__PURE__ */ new Set();
+            listenersRef.current.set(key, set);
+          }
+          set.add(listener);
+        });
+      },
+      onReady(key, callback) {
+        const existing = storeRef.current.get(key);
+        if (existing) {
+          callback(existing);
+          return () => {
+          };
+        }
+        const listener = (fn) => callback(fn);
+        let set = listenersRef.current.get(key);
+        if (!set) {
+          set = /* @__PURE__ */ new Set();
+          listenersRef.current.set(key, set);
+        }
+        set.add(listener);
+        return () => {
+          set.delete(listener);
+        };
+      }
+    }).current;
+    return /* @__PURE__ */ React.createElement(TunnelContext.Provider, { value: store }, children);
+  }
+  function useTunnelStore() {
+    const store = (0, import_react.useContext)(TunnelContext);
+    if (!store) {
+      throw new Error(
+        "[tunnel-fn] useTunnel/useTunnelFunction must be used within a <TunnelProvider>. Wrap your component tree with the TunnelProvider from createTunnel()."
+      );
+    }
+    return store;
+  }
+  function useTunnel() {
+    const store = useTunnelStore();
+    const call = (0, import_react.useCallback)(
+      (key, ...args) => {
+        return store.call(key, ...args);
+      },
+      [store]
+    );
+    const callAsync = (0, import_react.useCallback)(
+      (key, ...args) => {
+        return store.callAsync(key, ...args);
+      },
+      [store]
+    );
+    const has = (0, import_react.useCallback)(
+      (key) => {
+        return store.has(key);
+      },
+      [store]
+    );
+    const onReady = (0, import_react.useCallback)(
+      (key, callback) => {
+        return store.onReady(key, callback);
+      },
+      [store]
+    );
+    return { call, callAsync, has, onReady };
+  }
+  function useTunnelFunction(key, fn) {
+    const store = useTunnelStore();
+    (0, import_react.useEffect)(() => {
+      store.register(key, fn);
+      return () => {
+        store.unregister(key);
+      };
+    }, [store, key, fn]);
+    return fn;
+  }
+  return { TunnelProvider, useTunnel, useTunnelFunction };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createTunnel
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/tunnel.tsx"],"sourcesContent":["export { createTunnel } from \"./tunnel\";\n","import * as React from \"react\";\nimport {\n\tcreateContext,\n\tuseCallback,\n\tuseContext,\n\tuseEffect,\n\tuseLayoutEffect,\n\tuseRef,\n\ttype ReactNode,\n} from \"react\";\n\ntype TunnelFunctionMap = Record<string, (...args: never[]) => unknown>;\n\ntype Awaited<T> = T extends Promise<infer U> ? U : T;\n\ntype TunnelStore<T extends TunnelFunctionMap> = {\n\tregister<K extends keyof T>(key: K, fn: T[K]): void;\n\tunregister<K extends keyof T>(key: K): void;\n\tcall<K extends keyof T>(\n\t\tkey: K,\n\t\t...args: Parameters<T[K]>\n\t): ReturnType<T[K]> | undefined;\n\tcallAsync<K extends keyof T>(\n\t\tkey: K,\n\t\t...args: Parameters<T[K]>\n\t): Promise<Awaited<ReturnType<T[K]>> | undefined>;\n\thas<K extends keyof T>(key: K): boolean;\n\tonReady<K extends keyof T>(key: K, callback: (fn: T[K]) => void): () => void;\n};\n\n/**\n * Creates a type-safe tunnel for passing functions across components via context.\n *\n * @example\n * ```tsx\n * const { TunnelProvider, useTunnel, useTunnelFunction } = createTunnel<{\n *   onSave: (data: string) => void;\n *   getCount: () => number;\n * }>();\n * ```\n */\nexport function createTunnel<T extends TunnelFunctionMap>() {\n\tconst TunnelContext = createContext<TunnelStore<T> | null>(null);\n\n\tfunction TunnelProvider({ children }: { children: ReactNode }) {\n\t\tconst storeRef = useRef<Map<keyof T, T[keyof T]>>(new Map());\n\t\tconst listenersRef = useRef<Map<keyof T, Set<(fn: T[keyof T]) => void>>>(new Map());\n\n\t\tconst isRenderPhaseRef = useRef(false);\n\t\tconst registrationCountRef = useRef<Map<keyof T, number[]>>(new Map());\n\t\tconst churnWarnedRef = useRef<Set<keyof T>>(new Set());\n\n\t\t// Track render phase: set true synchronously during render, false in effect\n\t\tif (process.env.NODE_ENV !== \"production\") {\n\t\t\tisRenderPhaseRef.current = true;\n\t\t}\n\n\t\tuseLayoutEffect(() => {\n\t\t\tisRenderPhaseRef.current = false;\n\t\t});\n\n\t\tconst store = useRef<TunnelStore<T>>({\n\t\t\tregister<K extends keyof T>(key: K, fn: T[K]) {\n\t\t\t\tif (process.env.NODE_ENV !== \"production\") {\n\t\t\t\t\t// Warn: duplicate key registration\n\t\t\t\t\tif (storeRef.current.has(key)) {\n\t\t\t\t\t\tconsole.warn(\n\t\t\t\t\t\t\t`[tunnel-fn] Duplicate registration for key \"${String(key)}\". ` +\n\t\t\t\t\t\t\t\t`Another component already registered this key. ` +\n\t\t\t\t\t\t\t\t`Only the last registration will be active — this is likely a bug.`\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\n\t\t\t\t\t// Track: registration churn (unstable fn reference)\n\t\t\t\t\tconst now = Date.now();\n\t\t\t\t\tconst timestamps = registrationCountRef.current.get(key) ?? [];\n\t\t\t\t\ttimestamps.push(now);\n\t\t\t\t\t// Keep only timestamps from the last second\n\t\t\t\t\tconst recent = timestamps.filter((t) => now - t < 1000);\n\t\t\t\t\tregistrationCountRef.current.set(key, recent);\n\n\t\t\t\t\tif (recent.length > 3 && !churnWarnedRef.current.has(key)) {\n\t\t\t\t\t\tchurnWarnedRef.current.add(key);\n\t\t\t\t\t\tconsole.warn(\n\t\t\t\t\t\t\t`[tunnel-fn] Function for key \"${String(key)}\" is being re-registered rapidly ` +\n\t\t\t\t\t\t\t\t`(${recent.length} times in <1s). This usually means the function passed to ` +\n\t\t\t\t\t\t\t\t`useTunnelFunction is recreated every render. Wrap it in useCallback() to fix this:\\n\\n` +\n\t\t\t\t\t\t\t\t`  const handler = useCallback((...) => { ... }, [deps]);\\n` +\n\t\t\t\t\t\t\t\t`  useTunnelFunction(\"${String(key)}\", handler);`\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\tstoreRef.current.set(key, fn);\n\n\t\t\t\tconst listeners = listenersRef.current.get(key);\n\t\t\t\tif (listeners) {\n\t\t\t\t\tlisteners.forEach((cb) => cb(fn as T[keyof T]));\n\t\t\t\t\tlistenersRef.current.delete(key);\n\t\t\t\t}\n\t\t\t},\n\t\t\tunregister<K extends keyof T>(key: K) {\n\t\t\t\tstoreRef.current.delete(key);\n\t\t\t},\n\t\t\tcall<K extends keyof T>(key: K, ...args: Parameters<T[K]>) {\n\t\t\t\tif (process.env.NODE_ENV !== \"production\") {\n\t\t\t\t\t// Warn: call() during render phase\n\t\t\t\t\tif (isRenderPhaseRef.current) {\n\t\t\t\t\t\tconsole.warn(\n\t\t\t\t\t\t\t`[tunnel-fn] call(\"${String(key)}\") was invoked during the render phase. ` +\n\t\t\t\t\t\t\t\t`Tunnel functions should only be called from event handlers, useEffect, or callbacks — ` +\n\t\t\t\t\t\t\t\t`never directly during render. This can cause unpredictable behavior.`\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\tconst fn = storeRef.current.get(key);\n\t\t\t\tif (!fn) {\n\t\t\t\t\tif (process.env.NODE_ENV !== \"production\") {\n\t\t\t\t\t\tconsole.warn(\n\t\t\t\t\t\t\t`[tunnel-fn] No function registered for key \"${String(key)}\". ` +\n\t\t\t\t\t\t\t\t`Make sure a component with useTunnelFunction(\"${String(key)}\", ...) is mounted.`\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\treturn undefined as ReturnType<T[K]> | undefined;\n\t\t\t\t}\n\t\t\t\treturn (fn as T[K])(...args) as ReturnType<T[K]>;\n\t\t\t},\n\t\t\thas<K extends keyof T>(key: K) {\n\t\t\t\treturn storeRef.current.has(key);\n\t\t\t},\n\t\t\tcallAsync<K extends keyof T>(key: K, ...args: Parameters<T[K]>) {\n\t\t\t\tconst fn = storeRef.current.get(key);\n\t\t\t\tif (fn) {\n\t\t\t\t\treturn Promise.resolve((fn as T[K])(...args)).then(\n\t\t\t\t\t\t(v) => v as Awaited<ReturnType<T[K]>>\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\treturn new Promise<Awaited<ReturnType<T[K]>> | undefined>((resolve) => {\n\t\t\t\t\tconst listener = (registeredFn: T[keyof T]) => {\n\t\t\t\t\t\tresolve(\n\t\t\t\t\t\t\tPromise.resolve((registeredFn as T[K])(...args)).then(\n\t\t\t\t\t\t\t\t(v) => v as Awaited<ReturnType<T[K]>>\n\t\t\t\t\t\t\t) as unknown as Awaited<ReturnType<T[K]>>\n\t\t\t\t\t\t);\n\t\t\t\t\t};\n\t\t\t\t\tlet set = listenersRef.current.get(key);\n\t\t\t\t\tif (!set) {\n\t\t\t\t\t\tset = new Set();\n\t\t\t\t\t\tlistenersRef.current.set(key, set);\n\t\t\t\t\t}\n\t\t\t\t\tset.add(listener);\n\t\t\t\t});\n\t\t\t},\n\t\t\tonReady<K extends keyof T>(key: K, callback: (fn: T[K]) => void) {\n\t\t\t\tconst existing = storeRef.current.get(key);\n\t\t\t\tif (existing) {\n\t\t\t\t\tcallback(existing as T[K]);\n\t\t\t\t\treturn () => {};\n\t\t\t\t}\n\t\t\t\tconst listener = (fn: T[keyof T]) => callback(fn as T[K]);\n\t\t\t\tlet set = listenersRef.current.get(key);\n\t\t\t\tif (!set) {\n\t\t\t\t\tset = new Set();\n\t\t\t\t\tlistenersRef.current.set(key, set);\n\t\t\t\t}\n\t\t\t\tset.add(listener);\n\t\t\t\treturn () => {\n\t\t\t\t\tset!.delete(listener);\n\t\t\t\t};\n\t\t\t},\n\t\t}).current;\n\n\t\treturn (\n\t\t\t<TunnelContext.Provider value={store}>\n\t\t\t\t{children}\n\t\t\t</TunnelContext.Provider>\n\t\t);\n\t}\n\n\tfunction useTunnelStore(): TunnelStore<T> {\n\t\tconst store = useContext(TunnelContext);\n\t\tif (!store) {\n\t\t\tthrow new Error(\n\t\t\t\t\"[tunnel-fn] useTunnel/useTunnelFunction must be used within a <TunnelProvider>. \" +\n\t\t\t\t\t\"Wrap your component tree with the TunnelProvider from createTunnel().\"\n\t\t\t);\n\t\t}\n\t\treturn store;\n\t}\n\n\tfunction useTunnel() {\n\t\tconst store = useTunnelStore();\n\n\t\tconst call = useCallback(\n\t\t\t<K extends keyof T>(key: K, ...args: Parameters<T[K]>): ReturnType<T[K]> | undefined => {\n\t\t\t\treturn store.call(key, ...args);\n\t\t\t},\n\t\t\t[store]\n\t\t);\n\n\t\tconst callAsync = useCallback(\n\t\t\t<K extends keyof T>(key: K, ...args: Parameters<T[K]>): Promise<Awaited<ReturnType<T[K]>> | undefined> => {\n\t\t\t\treturn store.callAsync(key, ...args);\n\t\t\t},\n\t\t\t[store]\n\t\t);\n\n\t\tconst has = useCallback(\n\t\t\t<K extends keyof T>(key: K): boolean => {\n\t\t\t\treturn store.has(key);\n\t\t\t},\n\t\t\t[store]\n\t\t);\n\n\t\tconst onReady = useCallback(\n\t\t\t<K extends keyof T>(key: K, callback: (fn: T[K]) => void): (() => void) => {\n\t\t\t\treturn store.onReady(key, callback);\n\t\t\t},\n\t\t\t[store]\n\t\t);\n\n\t\treturn { call, callAsync, has, onReady } as const;\n\t}\n\n\tfunction useTunnelFunction<K extends keyof T>(key: K, fn: T[K]): T[K] {\n\t\tconst store = useTunnelStore();\n\n\t\tuseEffect(() => {\n\t\t\tstore.register(key, fn);\n\t\t\treturn () => {\n\t\t\t\tstore.unregister(key);\n\t\t\t};\n\t\t}, [store, key, fn]);\n\n\t\treturn fn;\n\t}\n\n\treturn { TunnelProvider, useTunnel, useTunnelFunction } as const;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,30 @@
+import * as React from 'react';
+import { ReactNode } from 'react';
+
+type TunnelFunctionMap = Record<string, (...args: never[]) => unknown>;
+type Awaited<T> = T extends Promise<infer U> ? U : T;
+/**
+ * Creates a type-safe tunnel for passing functions across components via context.
+ *
+ * @example
+ * ```tsx
+ * const { TunnelProvider, useTunnel, useTunnelFunction } = createTunnel<{
+ *   onSave: (data: string) => void;
+ *   getCount: () => number;
+ * }>();
+ * ```
+ */
+declare function createTunnel<T extends TunnelFunctionMap>(): {
+    readonly TunnelProvider: ({ children }: {
+        children: ReactNode;
+    }) => React.JSX.Element;
+    readonly useTunnel: () => {
+        readonly call: <K extends keyof T>(key: K, ...args: Parameters<T[K]>) => ReturnType<T[K]> | undefined;
+        readonly callAsync: <K extends keyof T>(key: K, ...args: Parameters<T[K]>) => Promise<Awaited<ReturnType<T[K]>> | undefined>;
+        readonly has: <K extends keyof T>(key: K) => boolean;
+        readonly onReady: <K extends keyof T>(key: K, callback: (fn: T[K]) => void) => (() => void);
+    };
+    readonly useTunnelFunction: <K extends keyof T>(key: K, fn: T[K]) => T[K];
+};
+
+export { createTunnel };

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import * as React from 'react';
+import { ReactNode } from 'react';
+
+type TunnelFunctionMap = Record<string, (...args: never[]) => unknown>;
+type Awaited<T> = T extends Promise<infer U> ? U : T;
+/**
+ * Creates a type-safe tunnel for passing functions across components via context.
+ *
+ * @example
+ * ```tsx
+ * const { TunnelProvider, useTunnel, useTunnelFunction } = createTunnel<{
+ *   onSave: (data: string) => void;
+ *   getCount: () => number;
+ * }>();
+ * ```
+ */
+declare function createTunnel<T extends TunnelFunctionMap>(): {
+    readonly TunnelProvider: ({ children }: {
+        children: ReactNode;
+    }) => React.JSX.Element;
+    readonly useTunnel: () => {
+        readonly call: <K extends keyof T>(key: K, ...args: Parameters<T[K]>) => ReturnType<T[K]> | undefined;
+        readonly callAsync: <K extends keyof T>(key: K, ...args: Parameters<T[K]>) => Promise<Awaited<ReturnType<T[K]>> | undefined>;
+        readonly has: <K extends keyof T>(key: K) => boolean;
+        readonly onReady: <K extends keyof T>(key: K, callback: (fn: T[K]) => void) => (() => void);
+    };
+    readonly useTunnelFunction: <K extends keyof T>(key: K, fn: T[K]) => T[K];
+};
+
+export { createTunnel };

package/dist/index.js

@@ -0,0 +1,177 @@
+// src/tunnel.tsx
+import * as React from "react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef
+} from "react";
+function createTunnel() {
+  const TunnelContext = createContext(null);
+  function TunnelProvider({ children }) {
+    const storeRef = useRef(/* @__PURE__ */ new Map());
+    const listenersRef = useRef(/* @__PURE__ */ new Map());
+    const isRenderPhaseRef = useRef(false);
+    const registrationCountRef = useRef(/* @__PURE__ */ new Map());
+    const churnWarnedRef = useRef(/* @__PURE__ */ new Set());
+    if (process.env.NODE_ENV !== "production") {
+      isRenderPhaseRef.current = true;
+    }
+    useLayoutEffect(() => {
+      isRenderPhaseRef.current = false;
+    });
+    const store = useRef({
+      register(key, fn) {
+        var _a;
+        if (process.env.NODE_ENV !== "production") {
+          if (storeRef.current.has(key)) {
+            console.warn(
+              `[tunnel-fn] Duplicate registration for key "${String(key)}". Another component already registered this key. Only the last registration will be active \u2014 this is likely a bug.`
+            );
+          }
+          const now = Date.now();
+          const timestamps = (_a = registrationCountRef.current.get(key)) != null ? _a : [];
+          timestamps.push(now);
+          const recent = timestamps.filter((t) => now - t < 1e3);
+          registrationCountRef.current.set(key, recent);
+          if (recent.length > 3 && !churnWarnedRef.current.has(key)) {
+            churnWarnedRef.current.add(key);
+            console.warn(
+              `[tunnel-fn] Function for key "${String(key)}" is being re-registered rapidly (${recent.length} times in <1s). This usually means the function passed to useTunnelFunction is recreated every render. Wrap it in useCallback() to fix this:
+
+  const handler = useCallback((...) => { ... }, [deps]);
+  useTunnelFunction("${String(key)}", handler);`
+            );
+          }
+        }
+        storeRef.current.set(key, fn);
+        const listeners = listenersRef.current.get(key);
+        if (listeners) {
+          listeners.forEach((cb) => cb(fn));
+          listenersRef.current.delete(key);
+        }
+      },
+      unregister(key) {
+        storeRef.current.delete(key);
+      },
+      call(key, ...args) {
+        if (process.env.NODE_ENV !== "production") {
+          if (isRenderPhaseRef.current) {
+            console.warn(
+              `[tunnel-fn] call("${String(key)}") was invoked during the render phase. Tunnel functions should only be called from event handlers, useEffect, or callbacks \u2014 never directly during render. This can cause unpredictable behavior.`
+            );
+          }
+        }
+        const fn = storeRef.current.get(key);
+        if (!fn) {
+          if (process.env.NODE_ENV !== "production") {
+            console.warn(
+              `[tunnel-fn] No function registered for key "${String(key)}". Make sure a component with useTunnelFunction("${String(key)}", ...) is mounted.`
+            );
+          }
+          return void 0;
+        }
+        return fn(...args);
+      },
+      has(key) {
+        return storeRef.current.has(key);
+      },
+      callAsync(key, ...args) {
+        const fn = storeRef.current.get(key);
+        if (fn) {
+          return Promise.resolve(fn(...args)).then(
+            (v) => v
+          );
+        }
+        return new Promise((resolve) => {
+          const listener = (registeredFn) => {
+            resolve(
+              Promise.resolve(registeredFn(...args)).then(
+                (v) => v
+              )
+            );
+          };
+          let set = listenersRef.current.get(key);
+          if (!set) {
+            set = /* @__PURE__ */ new Set();
+            listenersRef.current.set(key, set);
+          }
+          set.add(listener);
+        });
+      },
+      onReady(key, callback) {
+        const existing = storeRef.current.get(key);
+        if (existing) {
+          callback(existing);
+          return () => {
+          };
+        }
+        const listener = (fn) => callback(fn);
+        let set = listenersRef.current.get(key);
+        if (!set) {
+          set = /* @__PURE__ */ new Set();
+          listenersRef.current.set(key, set);
+        }
+        set.add(listener);
+        return () => {
+          set.delete(listener);
+        };
+      }
+    }).current;
+    return /* @__PURE__ */ React.createElement(TunnelContext.Provider, { value: store }, children);
+  }
+  function useTunnelStore() {
+    const store = useContext(TunnelContext);
+    if (!store) {
+      throw new Error(
+        "[tunnel-fn] useTunnel/useTunnelFunction must be used within a <TunnelProvider>. Wrap your component tree with the TunnelProvider from createTunnel()."
+      );
+    }
+    return store;
+  }
+  function useTunnel() {
+    const store = useTunnelStore();
+    const call = useCallback(
+      (key, ...args) => {
+        return store.call(key, ...args);
+      },
+      [store]
+    );
+    const callAsync = useCallback(
+      (key, ...args) => {
+        return store.callAsync(key, ...args);
+      },
+      [store]
+    );
+    const has = useCallback(
+      (key) => {
+        return store.has(key);
+      },
+      [store]
+    );
+    const onReady = useCallback(
+      (key, callback) => {
+        return store.onReady(key, callback);
+      },
+      [store]
+    );
+    return { call, callAsync, has, onReady };
+  }
+  function useTunnelFunction(key, fn) {
+    const store = useTunnelStore();
+    useEffect(() => {
+      store.register(key, fn);
+      return () => {
+        store.unregister(key);
+      };
+    }, [store, key, fn]);
+    return fn;
+  }
+  return { TunnelProvider, useTunnel, useTunnelFunction };
+}
+export {
+  createTunnel
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tunnel.tsx"],"sourcesContent":["import * as React from \"react\";\nimport {\n\tcreateContext,\n\tuseCallback,\n\tuseContext,\n\tuseEffect,\n\tuseLayoutEffect,\n\tuseRef,\n\ttype ReactNode,\n} from \"react\";\n\ntype TunnelFunctionMap = Record<string, (...args: never[]) => unknown>;\n\ntype Awaited<T> = T extends Promise<infer U> ? U : T;\n\ntype TunnelStore<T extends TunnelFunctionMap> = {\n\tregister<K extends keyof T>(key: K, fn: T[K]): void;\n\tunregister<K extends keyof T>(key: K): void;\n\tcall<K extends keyof T>(\n\t\tkey: K,\n\t\t...args: Parameters<T[K]>\n\t): ReturnType<T[K]> | undefined;\n\tcallAsync<K extends keyof T>(\n\t\tkey: K,\n\t\t...args: Parameters<T[K]>\n\t): Promise<Awaited<ReturnType<T[K]>> | undefined>;\n\thas<K extends keyof T>(key: K): boolean;\n\tonReady<K extends keyof T>(key: K, callback: (fn: T[K]) => void): () => void;\n};\n\n/**\n * Creates a type-safe tunnel for passing functions across components via context.\n *\n * @example\n * ```tsx\n * const { TunnelProvider, useTunnel, useTunnelFunction } = createTunnel<{\n *   onSave: (data: string) => void;\n *   getCount: () => number;\n * }>();\n * ```\n */\nexport function createTunnel<T extends TunnelFunctionMap>() {\n\tconst TunnelContext = createContext<TunnelStore<T> | null>(null);\n\n\tfunction TunnelProvider({ children }: { children: ReactNode }) {\n\t\tconst storeRef = useRef<Map<keyof T, T[keyof T]>>(new Map());\n\t\tconst listenersRef = useRef<Map<keyof T, Set<(fn: T[keyof T]) => void>>>(new Map());\n\n\t\tconst isRenderPhaseRef = useRef(false);\n\t\tconst registrationCountRef = useRef<Map<keyof T, number[]>>(new Map());\n\t\tconst churnWarnedRef = useRef<Set<keyof T>>(new Set());\n\n\t\t// Track render phase: set true synchronously during render, false in effect\n\t\tif (process.env.NODE_ENV !== \"production\") {\n\t\t\tisRenderPhaseRef.current = true;\n\t\t}\n\n\t\tuseLayoutEffect(() => {\n\t\t\tisRenderPhaseRef.current = false;\n\t\t});\n\n\t\tconst store = useRef<TunnelStore<T>>({\n\t\t\tregister<K extends keyof T>(key: K, fn: T[K]) {\n\t\t\t\tif (process.env.NODE_ENV !== \"production\") {\n\t\t\t\t\t// Warn: duplicate key registration\n\t\t\t\t\tif (storeRef.current.has(key)) {\n\t\t\t\t\t\tconsole.warn(\n\t\t\t\t\t\t\t`[tunnel-fn] Duplicate registration for key \"${String(key)}\". ` +\n\t\t\t\t\t\t\t\t`Another component already registered this key. ` +\n\t\t\t\t\t\t\t\t`Only the last registration will be active — this is likely a bug.`\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\n\t\t\t\t\t// Track: registration churn (unstable fn reference)\n\t\t\t\t\tconst now = Date.now();\n\t\t\t\t\tconst timestamps = registrationCountRef.current.get(key) ?? [];\n\t\t\t\t\ttimestamps.push(now);\n\t\t\t\t\t// Keep only timestamps from the last second\n\t\t\t\t\tconst recent = timestamps.filter((t) => now - t < 1000);\n\t\t\t\t\tregistrationCountRef.current.set(key, recent);\n\n\t\t\t\t\tif (recent.length > 3 && !churnWarnedRef.current.has(key)) {\n\t\t\t\t\t\tchurnWarnedRef.current.add(key);\n\t\t\t\t\t\tconsole.warn(\n\t\t\t\t\t\t\t`[tunnel-fn] Function for key \"${String(key)}\" is being re-registered rapidly ` +\n\t\t\t\t\t\t\t\t`(${recent.length} times in <1s). This usually means the function passed to ` +\n\t\t\t\t\t\t\t\t`useTunnelFunction is recreated every render. Wrap it in useCallback() to fix this:\\n\\n` +\n\t\t\t\t\t\t\t\t`  const handler = useCallback((...) => { ... }, [deps]);\\n` +\n\t\t\t\t\t\t\t\t`  useTunnelFunction(\"${String(key)}\", handler);`\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\tstoreRef.current.set(key, fn);\n\n\t\t\t\tconst listeners = listenersRef.current.get(key);\n\t\t\t\tif (listeners) {\n\t\t\t\t\tlisteners.forEach((cb) => cb(fn as T[keyof T]));\n\t\t\t\t\tlistenersRef.current.delete(key);\n\t\t\t\t}\n\t\t\t},\n\t\t\tunregister<K extends keyof T>(key: K) {\n\t\t\t\tstoreRef.current.delete(key);\n\t\t\t},\n\t\t\tcall<K extends keyof T>(key: K, ...args: Parameters<T[K]>) {\n\t\t\t\tif (process.env.NODE_ENV !== \"production\") {\n\t\t\t\t\t// Warn: call() during render phase\n\t\t\t\t\tif (isRenderPhaseRef.current) {\n\t\t\t\t\t\tconsole.warn(\n\t\t\t\t\t\t\t`[tunnel-fn] call(\"${String(key)}\") was invoked during the render phase. ` +\n\t\t\t\t\t\t\t\t`Tunnel functions should only be called from event handlers, useEffect, or callbacks — ` +\n\t\t\t\t\t\t\t\t`never directly during render. This can cause unpredictable behavior.`\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\tconst fn = storeRef.current.get(key);\n\t\t\t\tif (!fn) {\n\t\t\t\t\tif (process.env.NODE_ENV !== \"production\") {\n\t\t\t\t\t\tconsole.warn(\n\t\t\t\t\t\t\t`[tunnel-fn] No function registered for key \"${String(key)}\". ` +\n\t\t\t\t\t\t\t\t`Make sure a component with useTunnelFunction(\"${String(key)}\", ...) is mounted.`\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\treturn undefined as ReturnType<T[K]> | undefined;\n\t\t\t\t}\n\t\t\t\treturn (fn as T[K])(...args) as ReturnType<T[K]>;\n\t\t\t},\n\t\t\thas<K extends keyof T>(key: K) {\n\t\t\t\treturn storeRef.current.has(key);\n\t\t\t},\n\t\t\tcallAsync<K extends keyof T>(key: K, ...args: Parameters<T[K]>) {\n\t\t\t\tconst fn = storeRef.current.get(key);\n\t\t\t\tif (fn) {\n\t\t\t\t\treturn Promise.resolve((fn as T[K])(...args)).then(\n\t\t\t\t\t\t(v) => v as Awaited<ReturnType<T[K]>>\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\treturn new Promise<Awaited<ReturnType<T[K]>> | undefined>((resolve) => {\n\t\t\t\t\tconst listener = (registeredFn: T[keyof T]) => {\n\t\t\t\t\t\tresolve(\n\t\t\t\t\t\t\tPromise.resolve((registeredFn as T[K])(...args)).then(\n\t\t\t\t\t\t\t\t(v) => v as Awaited<ReturnType<T[K]>>\n\t\t\t\t\t\t\t) as unknown as Awaited<ReturnType<T[K]>>\n\t\t\t\t\t\t);\n\t\t\t\t\t};\n\t\t\t\t\tlet set = listenersRef.current.get(key);\n\t\t\t\t\tif (!set) {\n\t\t\t\t\t\tset = new Set();\n\t\t\t\t\t\tlistenersRef.current.set(key, set);\n\t\t\t\t\t}\n\t\t\t\t\tset.add(listener);\n\t\t\t\t});\n\t\t\t},\n\t\t\tonReady<K extends keyof T>(key: K, callback: (fn: T[K]) => void) {\n\t\t\t\tconst existing = storeRef.current.get(key);\n\t\t\t\tif (existing) {\n\t\t\t\t\tcallback(existing as T[K]);\n\t\t\t\t\treturn () => {};\n\t\t\t\t}\n\t\t\t\tconst listener = (fn: T[keyof T]) => callback(fn as T[K]);\n\t\t\t\tlet set = listenersRef.current.get(key);\n\t\t\t\tif (!set) {\n\t\t\t\t\tset = new Set();\n\t\t\t\t\tlistenersRef.current.set(key, set);\n\t\t\t\t}\n\t\t\t\tset.add(listener);\n\t\t\t\treturn () => {\n\t\t\t\t\tset!.delete(listener);\n\t\t\t\t};\n\t\t\t},\n\t\t}).current;\n\n\t\treturn (\n\t\t\t<TunnelContext.Provider value={store}>\n\t\t\t\t{children}\n\t\t\t</TunnelContext.Provider>\n\t\t);\n\t}\n\n\tfunction useTunnelStore(): TunnelStore<T> {\n\t\tconst store = useContext(TunnelContext);\n\t\tif (!store) {\n\t\t\tthrow new Error(\n\t\t\t\t\"[tunnel-fn] useTunnel/useTunnelFunction must be used within a <TunnelProvider>. \" +\n\t\t\t\t\t\"Wrap your component tree with the TunnelProvider from createTunnel().\"\n\t\t\t);\n\t\t}\n\t\treturn store;\n\t}\n\n\tfunction useTunnel() {\n\t\tconst store = useTunnelStore();\n\n\t\tconst call = useCallback(\n\t\t\t<K extends keyof T>(key: K, ...args: Parameters<T[K]>): ReturnType<T[K]> | undefined => {\n\t\t\t\treturn store.call(key, ...args);\n\t\t\t},\n\t\t\t[store]\n\t\t);\n\n\t\tconst callAsync = useCallback(\n\t\t\t<K extends keyof T>(key: K, ...args: Parameters<T[K]>): Promise<Awaited<ReturnType<T[K]>> | undefined> => {\n\t\t\t\treturn store.callAsync(key, ...args);\n\t\t\t},\n\t\t\t[store]\n\t\t);\n\n\t\tconst has = useCallback(\n\t\t\t<K extends keyof T>(key: K): boolean => {\n\t\t\t\treturn store.has(key);\n\t\t\t},\n\t\t\t[store]\n\t\t);\n\n\t\tconst onReady = useCallback(\n\t\t\t<K extends keyof T>(key: K, callback: (fn: T[K]) => void): (() => void) => {\n\t\t\t\treturn store.onReady(key, callback);\n\t\t\t},\n\t\t\t[store]\n\t\t);\n\n\t\treturn { call, callAsync, has, onReady } as const;\n\t}\n\n\tfunction useTunnelFunction<K extends keyof T>(key: K, fn: T[K]): T[K] {\n\t\tconst store = useTunnelStore();\n\n\t\tuseEffect(() => {\n\t\t\tstore.register(key, fn);\n\t\t\treturn () => {\n\t\t\t\tstore.unregister(key);\n\t\t\t};\n\t\t}, [store, key, fn]);\n\n\t\treturn fn;\n\t}\n\n\treturn { TunnelProvider, useTunnel, useTunnelFunction } as const;\n}\n"],"mappings":";AAAA,YAAY,WAAW;AACvB;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAEM;AAgCA,SAAS,eAA4C;AAC3D,QAAM,gBAAgB,cAAqC,IAAI;AAE/D,WAAS,eAAe,EAAE,SAAS,GAA4B;AAC9D,UAAM,WAAW,OAAiC,oBAAI,IAAI,CAAC;AAC3D,UAAM,eAAe,OAAoD,oBAAI,IAAI,CAAC;AAElF,UAAM,mBAAmB,OAAO,KAAK;AACrC,UAAM,uBAAuB,OAA+B,oBAAI,IAAI,CAAC;AACrE,UAAM,iBAAiB,OAAqB,oBAAI,IAAI,CAAC;AAGrD,QAAI,QAAQ,IAAI,aAAa,cAAc;AAC1C,uBAAiB,UAAU;AAAA,IAC5B;AAEA,oBAAgB,MAAM;AACrB,uBAAiB,UAAU;AAAA,IAC5B,CAAC;AAED,UAAM,QAAQ,OAAuB;AAAA,MACpC,SAA4B,KAAQ,IAAU;AA9DjD;AA+DI,YAAI,QAAQ,IAAI,aAAa,cAAc;AAE1C,cAAI,SAAS,QAAQ,IAAI,GAAG,GAAG;AAC9B,oBAAQ;AAAA,cACP,+CAA+C,OAAO,GAAG,CAAC;AAAA,YAG3D;AAAA,UACD;AAGA,gBAAM,MAAM,KAAK,IAAI;AACrB,gBAAM,cAAa,0BAAqB,QAAQ,IAAI,GAAG,MAApC,YAAyC,CAAC;AAC7D,qBAAW,KAAK,GAAG;AAEnB,gBAAM,SAAS,WAAW,OAAO,CAAC,MAAM,MAAM,IAAI,GAAI;AACtD,+BAAqB,QAAQ,IAAI,KAAK,MAAM;AAE5C,cAAI,OAAO,SAAS,KAAK,CAAC,eAAe,QAAQ,IAAI,GAAG,GAAG;AAC1D,2BAAe,QAAQ,IAAI,GAAG;AAC9B,oBAAQ;AAAA,cACP,iCAAiC,OAAO,GAAG,CAAC,qCACvC,OAAO,MAAM;AAAA;AAAA;AAAA,uBAGO,OAAO,GAAG,CAAC;AAAA,YACrC;AAAA,UACD;AAAA,QACD;AAEA,iBAAS,QAAQ,IAAI,KAAK,EAAE;AAE5B,cAAM,YAAY,aAAa,QAAQ,IAAI,GAAG;AAC9C,YAAI,WAAW;AACd,oBAAU,QAAQ,CAAC,OAAO,GAAG,EAAgB,CAAC;AAC9C,uBAAa,QAAQ,OAAO,GAAG;AAAA,QAChC;AAAA,MACD;AAAA,MACA,WAA8B,KAAQ;AACrC,iBAAS,QAAQ,OAAO,GAAG;AAAA,MAC5B;AAAA,MACA,KAAwB,QAAW,MAAwB;AAC1D,YAAI,QAAQ,IAAI,aAAa,cAAc;AAE1C,cAAI,iBAAiB,SAAS;AAC7B,oBAAQ;AAAA,cACP,qBAAqB,OAAO,GAAG,CAAC;AAAA,YAGjC;AAAA,UACD;AAAA,QACD;AAEA,cAAM,KAAK,SAAS,QAAQ,IAAI,GAAG;AACnC,YAAI,CAAC,IAAI;AACR,cAAI,QAAQ,IAAI,aAAa,cAAc;AAC1C,oBAAQ;AAAA,cACP,+CAA+C,OAAO,GAAG,CAAC,oDACR,OAAO,GAAG,CAAC;AAAA,YAC9D;AAAA,UACD;AACA,iBAAO;AAAA,QACR;AACA,eAAQ,GAAY,GAAG,IAAI;AAAA,MAC5B;AAAA,MACA,IAAuB,KAAQ;AAC9B,eAAO,SAAS,QAAQ,IAAI,GAAG;AAAA,MAChC;AAAA,MACA,UAA6B,QAAW,MAAwB;AAC/D,cAAM,KAAK,SAAS,QAAQ,IAAI,GAAG;AACnC,YAAI,IAAI;AACP,iBAAO,QAAQ,QAAS,GAAY,GAAG,IAAI,CAAC,EAAE;AAAA,YAC7C,CAAC,MAAM;AAAA,UACR;AAAA,QACD;AACA,eAAO,IAAI,QAA+C,CAAC,YAAY;AACtE,gBAAM,WAAW,CAAC,iBAA6B;AAC9C;AAAA,cACC,QAAQ,QAAS,aAAsB,GAAG,IAAI,CAAC,EAAE;AAAA,gBAChD,CAAC,MAAM;AAAA,cACR;AAAA,YACD;AAAA,UACD;AACA,cAAI,MAAM,aAAa,QAAQ,IAAI,GAAG;AACtC,cAAI,CAAC,KAAK;AACT,kBAAM,oBAAI,IAAI;AACd,yBAAa,QAAQ,IAAI,KAAK,GAAG;AAAA,UAClC;AACA,cAAI,IAAI,QAAQ;AAAA,QACjB,CAAC;AAAA,MACF;AAAA,MACA,QAA2B,KAAQ,UAA8B;AAChE,cAAM,WAAW,SAAS,QAAQ,IAAI,GAAG;AACzC,YAAI,UAAU;AACb,mBAAS,QAAgB;AACzB,iBAAO,MAAM;AAAA,UAAC;AAAA,QACf;AACA,cAAM,WAAW,CAAC,OAAmB,SAAS,EAAU;AACxD,YAAI,MAAM,aAAa,QAAQ,IAAI,GAAG;AACtC,YAAI,CAAC,KAAK;AACT,gBAAM,oBAAI,IAAI;AACd,uBAAa,QAAQ,IAAI,KAAK,GAAG;AAAA,QAClC;AACA,YAAI,IAAI,QAAQ;AAChB,eAAO,MAAM;AACZ,cAAK,OAAO,QAAQ;AAAA,QACrB;AAAA,MACD;AAAA,IACD,CAAC,EAAE;AAEH,WACC,oCAAC,cAAc,UAAd,EAAuB,OAAO,SAC7B,QACF;AAAA,EAEF;AAEA,WAAS,iBAAiC;AACzC,UAAM,QAAQ,WAAW,aAAa;AACtC,QAAI,CAAC,OAAO;AACX,YAAM,IAAI;AAAA,QACT;AAAA,MAED;AAAA,IACD;AACA,WAAO;AAAA,EACR;AAEA,WAAS,YAAY;AACpB,UAAM,QAAQ,eAAe;AAE7B,UAAM,OAAO;AAAA,MACZ,CAAoB,QAAW,SAAyD;AACvF,eAAO,MAAM,KAAK,KAAK,GAAG,IAAI;AAAA,MAC/B;AAAA,MACA,CAAC,KAAK;AAAA,IACP;AAEA,UAAM,YAAY;AAAA,MACjB,CAAoB,QAAW,SAA2E;AACzG,eAAO,MAAM,UAAU,KAAK,GAAG,IAAI;AAAA,MACpC;AAAA,MACA,CAAC,KAAK;AAAA,IACP;AAEA,UAAM,MAAM;AAAA,MACX,CAAoB,QAAoB;AACvC,eAAO,MAAM,IAAI,GAAG;AAAA,MACrB;AAAA,MACA,CAAC,KAAK;AAAA,IACP;AAEA,UAAM,UAAU;AAAA,MACf,CAAoB,KAAQ,aAA+C;AAC1E,eAAO,MAAM,QAAQ,KAAK,QAAQ;AAAA,MACnC;AAAA,MACA,CAAC,KAAK;AAAA,IACP;AAEA,WAAO,EAAE,MAAM,WAAW,KAAK,QAAQ;AAAA,EACxC;AAEA,WAAS,kBAAqC,KAAQ,IAAgB;AACrE,UAAM,QAAQ,eAAe;AAE7B,cAAU,MAAM;AACf,YAAM,SAAS,KAAK,EAAE;AACtB,aAAO,MAAM;AACZ,cAAM,WAAW,GAAG;AAAA,MACrB;AAAA,IACD,GAAG,CAAC,OAAO,KAAK,EAAE,CAAC;AAEnB,WAAO;AAAA,EACR;AAEA,SAAO,EAAE,gBAAgB,WAAW,kBAAkB;AACvD;","names":[]}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@felixfern/tunnel-fn",
+  "version": "2.0.0",
+  "description": "Type-safe function tunneling across React components via context",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "react",
+    "typescript",
+    "type-safe",
+    "context",
+    "function-passing",
+    "callback",
+    "tunnel"
+  ],
+  "author": "Felix Fernando",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^20.12.13",
+    "@types/react": "^19.0.1",
+    "@vitejs/plugin-react": "^5.1.4",
+    "jsdom": "^28.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}