@usefy/use-signal 0.0.31

package/README.md

@@ -0,0 +1,587 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mirunamu00/usefy/master/assets/logo.png" alt="usefy logo" width="120" />
+</p>
+
+<h1 align="center">@usefy/use-signal</h1>
+
+<p align="center">
+  <strong>A lightweight React hook for event-driven communication between components</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@usefy/use-signal">
+    <img src="https://img.shields.io/npm/v/@usefy/use-signal.svg?style=flat-square&color=007acc" alt="npm version" />
+  </a>
+  <a href="https://www.npmjs.com/package/@usefy/use-signal">
+    <img src="https://img.shields.io/npm/dm/@usefy/use-signal.svg?style=flat-square&color=007acc" alt="npm downloads" />
+  </a>
+  <a href="https://bundlephobia.com/package/@usefy/use-signal">
+    <img src="https://img.shields.io/bundlephobia/minzip/@usefy/use-signal?style=flat-square&color=007acc" alt="bundle size" />
+  </a>
+  <a href="https://github.com/mirunamu00/usefy/blob/master/LICENSE">
+    <img src="https://img.shields.io/npm/l/@usefy/use-signal.svg?style=flat-square&color=007acc" alt="license" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#api-reference">API Reference</a> •
+  <a href="#examples">Examples</a> •
+  <a href="#license">License</a>
+</p>
+
+<p align="center">
+  <a href="https://mirunamu00.github.io/usefy/?path=/docs/hooks-usesignal--docs" target="_blank" rel="noopener noreferrer">
+    <strong>📚 View Storybook Demo</strong>
+  </a>
+</p>
+
+---
+
+## Overview
+
+`@usefy/use-signal` enables event-driven communication between React components without prop drilling or complex state management setup. Components subscribe to a shared "signal" by name, and when any component emits that signal, all subscribers receive an update.
+
+**Part of the [@usefy](https://www.npmjs.com/org/usefy) ecosystem** — a collection of production-ready React hooks designed for modern applications.
+
+### Why use-signal?
+
+- **Zero Dependencies** — Pure React implementation with no external dependencies
+- **TypeScript First** — Full type safety with exported interfaces
+- **Stable References** — `emit` and `info` maintain stable references across re-renders
+- **SSR Compatible** — Works seamlessly with Next.js, Remix, and other SSR frameworks
+- **Lightweight** — Minimal bundle footprint (~1KB minified + gzipped)
+- **Well Tested** — Comprehensive test coverage with Vitest
+- **React 18+ Optimized** — Uses `useSyncExternalStore` for concurrent mode compatibility
+
+### Use Cases
+
+- **Dashboard Refresh** — Refresh multiple widgets with a single button click
+- **Form Reset** — Reset multiple form sections simultaneously
+- **Cache Invalidation** — Invalidate and reload data across components
+- **Multi-step Flows** — Coordinate state across wizard steps
+- **Event Broadcasting** — Notify multiple listeners about system events
+
+### ⚠️ What This Hook Is NOT
+
+**`useSignal` is NOT a global state management solution.**
+
+This hook is designed for lightweight event-driven communication—sharing simple "signals" between components without the overhead of complex state management setup.
+
+If you need:
+- Complex shared state with derived values
+- Persistent state across page navigation
+- State that drives business logic
+- Fine-grained state updates with selectors
+
+→ Use dedicated state management tools like **React Context**, **Zustand**, **Jotai**, **Recoil**, or **Redux**.
+
+**About `info.data`:** The data payload feature exists for cases where you need to pass contextual information along with a signal (e.g., which item was clicked, what action was performed). It's meant for event metadata, not as a global state container.
+
+```tsx
+// ✅ Good: Signal with contextual data
+emit({ itemId: "123", action: "refresh" });
+
+// ❌ Bad: Using as global state
+emit({ user: userData, cart: cartItems, settings: appSettings });
+```
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install @usefy/use-signal
+
+# yarn
+yarn add @usefy/use-signal
+
+# pnpm
+pnpm add @usefy/use-signal
+```
+
+### Peer Dependencies
+
+This package requires React 18 or 19:
+
+```json
+{
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  }
+}
+```
+
+---
+
+## Quick Start
+
+```tsx
+import { useSignal } from "@usefy/use-signal";
+import { useEffect } from "react";
+
+// Emitter Component
+function RefreshButton() {
+  const { emit } = useSignal("dashboard-refresh");
+
+  return <button onClick={emit}>Refresh Dashboard</button>;
+}
+
+// Subscriber Component
+function DataWidget() {
+  const { signal } = useSignal("dashboard-refresh");
+
+  useEffect(() => {
+    fetchData(); // Refetch when signal changes
+  }, [signal]);
+
+  return <div>Widget Content</div>;
+}
+```
+
+---
+
+## API Reference
+
+### `useSignal(name, options?)`
+
+A hook that subscribes to a named signal and provides emit functionality.
+
+#### Parameters
+
+| Parameter | Type            | Description                        |
+| --------- | --------------- | ---------------------------------- |
+| `name`    | `string`        | Unique identifier for the signal   |
+| `options` | `SignalOptions` | Optional configuration (see below) |
+
+#### Options
+
+```typescript
+interface SignalOptions {
+  emitOnMount?: boolean; // Emit when component mounts (default: false)
+  onEmit?: () => void; // Callback executed on emit
+  enabled?: boolean; // Enable/disable subscription (default: true)
+  debounce?: number; // Debounce emit calls in milliseconds
+}
+```
+
+#### Returns `UseSignalReturn<T>`
+
+| Property | Type              | Description                                 |
+| -------- | ----------------- | ------------------------------------------- |
+| `signal` | `number`          | Current version number (use in deps arrays) |
+| `emit`   | `(data?: T) => void` | Function to emit the signal with optional data |
+| `info`   | `SignalInfo<T>`   | Metadata object (see below)                 |
+
+#### SignalInfo
+
+```typescript
+interface SignalInfo<T = unknown> {
+  name: string; // Signal name
+  subscriberCount: number; // Active subscribers
+  timestamp: number; // Last emit timestamp
+  emitCount: number; // Total emit count
+  data: T | undefined; // Data passed with last emit
+}
+```
+
+> **Note:** `info` is a stable reference (ref-based) that doesn't trigger re-renders. Use `signal` in dependency arrays to react to changes, and access the latest `info.data` inside `useEffect`.
+
+---
+
+## Examples
+
+### Dashboard Refresh Pattern
+
+```tsx
+import { useSignal } from "@usefy/use-signal";
+import { useEffect, useState } from "react";
+
+function RefreshButton() {
+  const { emit, info } = useSignal("dashboard-refresh");
+
+  return (
+    <button onClick={emit}>
+      Refresh All ({info.subscriberCount} widgets)
+    </button>
+  );
+}
+
+function SalesChart() {
+  const { signal } = useSignal("dashboard-refresh");
+  const [data, setData] = useState([]);
+
+  useEffect(() => {
+    fetchSalesData().then(setData);
+  }, [signal]);
+
+  return <Chart data={data} />;
+}
+
+function UserStats() {
+  const { signal } = useSignal("dashboard-refresh");
+  const [stats, setStats] = useState(null);
+
+  useEffect(() => {
+    fetchUserStats().then(setStats);
+  }, [signal]);
+
+  return <Stats data={stats} />;
+}
+```
+
+### Form Reset
+
+```tsx
+import { useSignal } from "@usefy/use-signal";
+
+function ResetButton() {
+  const { emit } = useSignal("form-reset");
+  return <button onClick={emit}>Reset All Fields</button>;
+}
+
+function PersonalInfoSection() {
+  const { signal } = useSignal("form-reset");
+  const [name, setName] = useState("");
+  const [email, setEmail] = useState("");
+
+  useEffect(() => {
+    if (signal > 0) {
+      setName("");
+      setEmail("");
+    }
+  }, [signal]);
+
+  return (
+    <section>
+      <input value={name} onChange={(e) => setName(e.target.value)} />
+      <input value={email} onChange={(e) => setEmail(e.target.value)} />
+    </section>
+  );
+}
+```
+
+### With Data Payload
+
+```tsx
+import { useSignal } from "@usefy/use-signal";
+import { useEffect } from "react";
+
+interface NotificationData {
+  type: "success" | "error" | "info";
+  message: string;
+}
+
+function NotificationEmitter() {
+  const { emit } = useSignal<NotificationData>("notification");
+
+  return (
+    <button
+      onClick={() =>
+        emit({ type: "success", message: "Operation completed!" })
+      }
+    >
+      Send Notification
+    </button>
+  );
+}
+
+function NotificationReceiver() {
+  const { signal, info } = useSignal<NotificationData>("notification");
+
+  useEffect(() => {
+    if (signal > 0 && info.data) {
+      // info.data is guaranteed to contain the latest data
+      console.log(`[${info.data.type}] ${info.data.message}`);
+    }
+  }, [signal]);
+
+  return <div>Last: {info.data?.message ?? "No notifications"}</div>;
+}
+```
+
+### With Debounce
+
+```tsx
+import { useSignal } from "@usefy/use-signal";
+
+function SearchInput() {
+  const { emit } = useSignal<string>("search-update", { debounce: 300 });
+
+  return (
+    <input
+      type="text"
+      onChange={(e) => {
+        emit(e.target.value); // Debounced - uses latest value after 300ms
+      }}
+    />
+  );
+}
+```
+
+### Conditional Subscription
+
+```tsx
+import { useSignal } from "@usefy/use-signal";
+
+function ConditionalWidget({ visible }: { visible: boolean }) {
+  // Only subscribe when visible
+  const { signal } = useSignal("updates", { enabled: visible });
+
+  useEffect(() => {
+    if (signal > 0) {
+      refreshData();
+    }
+  }, [signal]);
+
+  if (!visible) return null;
+  return <div>Widget Content</div>;
+}
+```
+
+### With onEmit Callback
+
+```tsx
+import { useSignal } from "@usefy/use-signal";
+
+function LoggingEmitter() {
+  const { emit } = useSignal("analytics-event", {
+    onEmit: () => {
+      console.log("Event emitted at", new Date().toISOString());
+      trackAnalytics("signal_emitted");
+    },
+  });
+
+  return <button onClick={emit}>Track Event</button>;
+}
+```
+
+### Emit on Mount
+
+```tsx
+import { useSignal } from "@usefy/use-signal";
+
+function AutoRefreshComponent() {
+  const { signal } = useSignal("data-refresh", { emitOnMount: true });
+
+  useEffect(() => {
+    // This runs immediately on mount due to emitOnMount
+    fetchLatestData();
+  }, [signal]);
+
+  return <div>Auto-refreshed content</div>;
+}
+```
+
+### Using Info for Conditional Logic
+
+```tsx
+import { useSignal } from "@usefy/use-signal";
+
+function SmartEmitter() {
+  const { emit, info } = useSignal("notification");
+
+  const handleClick = () => {
+    // Only emit if there are subscribers
+    if (info.subscriberCount > 0) {
+      emit();
+    } else {
+      console.log("No subscribers, skipping emit");
+    }
+  };
+
+  return (
+    <button onClick={handleClick}>
+      Notify ({info.subscriberCount} listeners)
+    </button>
+  );
+}
+```
+
+---
+
+## TypeScript
+
+This hook is written in TypeScript and exports all interfaces. Use generics to type the data payload.
+
+```tsx
+import {
+  useSignal,
+  type UseSignalReturn,
+  type SignalOptions,
+  type SignalInfo,
+} from "@usefy/use-signal";
+
+// With typed data payload
+interface MyEventData {
+  action: string;
+  payload: Record<string, unknown>;
+}
+
+const { signal, emit, info }: UseSignalReturn<MyEventData> = useSignal<MyEventData>(
+  "my-signal",
+  {
+    emitOnMount: true,
+    onEmit: () => console.log("emitted"),
+    enabled: true,
+    debounce: 100,
+  }
+);
+
+// signal: number
+// emit: (data?: MyEventData) => void
+// info: SignalInfo<MyEventData>
+// info.data: MyEventData | undefined
+```
+
+---
+
+## Performance
+
+### Stable References
+
+The `emit` function and `info` object maintain stable references across re-renders:
+
+```tsx
+const { emit, info } = useSignal<MyData>("my-signal");
+
+// emit reference remains stable
+useEffect(() => {
+  // Safe to use as dependencies
+}, [emit]);
+
+// info is a ref-based object - stable reference, live values via getters
+console.log(info.subscriberCount); // Always current
+console.log(info.data); // Latest data from last emit
+```
+
+### Data Ordering Guarantee
+
+When `emit(data)` is called, the data is stored **before** the signal version increments:
+
+```tsx
+const { signal, info } = useSignal<string>("my-signal");
+
+useEffect(() => {
+  // This is guaranteed: info.data contains the data passed to emit()
+  // that triggered this signal change
+  console.log(info.data); // Always the latest data
+}, [signal]);
+```
+
+### Minimal Re-renders
+
+- Only subscribed components re-render when signal is emitted
+- The signal value is a primitive number, optimized for dependency arrays
+- Uses React 18's `useSyncExternalStore` for optimal concurrent mode support
+
+---
+
+## How It Works
+
+1. **Global Store**: A singleton Map stores signal data (version, subscribers, metadata, payload data)
+2. **Subscription**: Components subscribe via `useSyncExternalStore`
+3. **Emit**: Sets data → Increments version → Updates timestamp → Notifies all subscribers
+4. **Cleanup**: Automatic unsubscription on unmount
+
+> **Key Design**: Data is set **before** version increment to ensure `useEffect` callbacks always see the latest `info.data`.
+
+```
+┌─────────────┐     emit()      ┌─────────────┐
+│  Component  │ ───────────────▶│   Signal    │
+│   Emitter   │                 │   Store     │
+└─────────────┘                 └──────┬──────┘
+                                       │
+                        notify all subscribers
+                                       │
+              ┌────────────────────────┼────────────────────────┐
+              ▼                        ▼                        ▼
+      ┌─────────────┐          ┌─────────────┐          ┌─────────────┐
+      │ Subscriber  │          │ Subscriber  │          │ Subscriber  │
+      │     A       │          │     B       │          │     C       │
+      └─────────────┘          └─────────────┘          └─────────────┘
+```
+
+---
+
+## Testing
+
+This package maintains comprehensive test coverage to ensure reliability and stability.
+
+### Test Categories
+
+<details>
+<summary><strong>Initialization Tests</strong></summary>
+
+- Initial signal value is 0
+- Returns all required properties (signal, emit, info)
+- Info object contains correct properties
+- Subscriber count tracking
+
+</details>
+
+<details>
+<summary><strong>Emit Tests</strong></summary>
+
+- Signal increments on emit
+- Multiple emits increment correctly
+- Emit count and timestamp update
+- Rapid successive emits
+
+</details>
+
+<details>
+<summary><strong>Data Payload Tests</strong></summary>
+
+- Data stored in info.data on emit
+- Data updates on each emit
+- Data shared across subscribers
+- Data ordering guarantee (available before signal changes)
+- Complex object data support
+- Debounced emit uses latest data
+
+</details>
+
+<details>
+<summary><strong>Multi-Subscriber Tests</strong></summary>
+
+- All subscribers receive signal updates
+- Subscriber count accuracy
+- Cleanup on unmount
+
+</details>
+
+<details>
+<summary><strong>Options Tests</strong></summary>
+
+- emitOnMount behavior
+- onEmit callback execution
+- enabled option subscription control
+- debounce timing
+
+</details>
+
+<details>
+<summary><strong>Stable Reference Tests</strong></summary>
+
+- Emit function stability
+- Info object stability
+- Values update with stable reference
+
+</details>
+
+---
+
+## License
+
+MIT © [mirunamu](https://github.com/mirunamu00)
+
+This package is part of the [usefy](https://github.com/mirunamu00/usefy) monorepo.
+
+---
+
+<p align="center">
+  <sub>Built with care by the usefy team</sub>
+</p>

package/dist/index.d.mts

@@ -0,0 +1,115 @@
+/**
+ * Signal metadata object for debugging and monitoring
+ */
+interface SignalInfo<T = unknown> {
+    /** Signal subscription name */
+    name: string;
+    /** Current number of active subscribers */
+    subscriberCount: number;
+    /** Timestamp of last emit (Date.now()) */
+    timestamp: number;
+    /** Total number of times this signal has been emitted */
+    emitCount: number;
+    /** Data passed with the last emit */
+    data: T | undefined;
+}
+/**
+ * Options for useSignal hook
+ */
+interface SignalOptions {
+    /** Automatically emit when component mounts */
+    emitOnMount?: boolean;
+    /** Callback executed when emit is called */
+    onEmit?: () => void;
+    /** Conditionally enable/disable subscription (default: true) */
+    enabled?: boolean;
+    /** Debounce emit calls in milliseconds */
+    debounce?: number;
+}
+/**
+ * Return type for useSignal hook
+ */
+interface UseSignalReturn<T = unknown> {
+    /** Current signal version number - use in dependency arrays */
+    signal: number;
+    /** Function to emit the signal and notify all subscribers, optionally with data */
+    emit: (data?: T) => void;
+    /** Stable metadata object for debugging and monitoring */
+    info: SignalInfo<T>;
+}
+/**
+ * A hook for event-driven communication between components without prop drilling.
+ * Components subscribe to a shared signal by name. When any component emits,
+ * all subscribers receive a new version number.
+ *
+ * @param name - Unique identifier string for the signal channel
+ * @param options - Configuration options
+ * @returns Object containing signal value, emit function, and info metadata
+ *
+ * @example
+ * ```tsx
+ * // Parent Component - emits signal
+ * function ParentComponent() {
+ *   const { emit } = useSignal("Dashboard Refresh");
+ *
+ *   return <button onClick={emit}>Refresh All</button>;
+ * }
+ *
+ * // Child Component - subscribes to signal
+ * function DataTable() {
+ *   const { signal } = useSignal("Dashboard Refresh");
+ *
+ *   useEffect(() => {
+ *     fetchTableData();
+ *   }, [signal]);
+ *
+ *   return <table>...</table>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With debugging info
+ * function MonitoredComponent() {
+ *   const { signal, emit, info } = useSignal("API Sync", {
+ *     onEmit: () => console.log("Syncing...")
+ *   });
+ *
+ *   useEffect(() => {
+ *     syncData();
+ *     console.log(`Sync #${info.emitCount} with ${info.subscriberCount} listeners`);
+ *   }, [signal]);
+ *
+ *   return <button onClick={emit}>Sync</button>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With data payload
+ * function DataEmitter() {
+ *   const { emit } = useSignal<{ userId: string }>("user-action");
+ *
+ *   const handleClick = (userId: string) => {
+ *     emit({ userId });
+ *   };
+ *
+ *   return <button onClick={() => handleClick("123")}>Action</button>;
+ * }
+ *
+ * function DataReceiver() {
+ *   const { signal, info } = useSignal<{ userId: string }>("user-action");
+ *
+ *   useEffect(() => {
+ *     if (info.data) {
+ *       console.log("User action for:", info.data.userId);
+ *     }
+ *   }, [signal]);
+ *
+ *   return <div>Listening...</div>;
+ * }
+ * ```
+ */
+declare function useSignal<T = unknown>(name: string, options?: SignalOptions): UseSignalReturn<T>;
+
+export { type SignalInfo, type SignalOptions, type UseSignalReturn, useSignal };

package/dist/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Signal metadata object for debugging and monitoring
+ */
+interface SignalInfo<T = unknown> {
+    /** Signal subscription name */
+    name: string;
+    /** Current number of active subscribers */
+    subscriberCount: number;
+    /** Timestamp of last emit (Date.now()) */
+    timestamp: number;
+    /** Total number of times this signal has been emitted */
+    emitCount: number;
+    /** Data passed with the last emit */
+    data: T | undefined;
+}
+/**
+ * Options for useSignal hook
+ */
+interface SignalOptions {
+    /** Automatically emit when component mounts */
+    emitOnMount?: boolean;
+    /** Callback executed when emit is called */
+    onEmit?: () => void;
+    /** Conditionally enable/disable subscription (default: true) */
+    enabled?: boolean;
+    /** Debounce emit calls in milliseconds */
+    debounce?: number;
+}
+/**
+ * Return type for useSignal hook
+ */
+interface UseSignalReturn<T = unknown> {
+    /** Current signal version number - use in dependency arrays */
+    signal: number;
+    /** Function to emit the signal and notify all subscribers, optionally with data */
+    emit: (data?: T) => void;
+    /** Stable metadata object for debugging and monitoring */
+    info: SignalInfo<T>;
+}
+/**
+ * A hook for event-driven communication between components without prop drilling.
+ * Components subscribe to a shared signal by name. When any component emits,
+ * all subscribers receive a new version number.
+ *
+ * @param name - Unique identifier string for the signal channel
+ * @param options - Configuration options
+ * @returns Object containing signal value, emit function, and info metadata
+ *
+ * @example
+ * ```tsx
+ * // Parent Component - emits signal
+ * function ParentComponent() {
+ *   const { emit } = useSignal("Dashboard Refresh");
+ *
+ *   return <button onClick={emit}>Refresh All</button>;
+ * }
+ *
+ * // Child Component - subscribes to signal
+ * function DataTable() {
+ *   const { signal } = useSignal("Dashboard Refresh");
+ *
+ *   useEffect(() => {
+ *     fetchTableData();
+ *   }, [signal]);
+ *
+ *   return <table>...</table>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With debugging info
+ * function MonitoredComponent() {
+ *   const { signal, emit, info } = useSignal("API Sync", {
+ *     onEmit: () => console.log("Syncing...")
+ *   });
+ *
+ *   useEffect(() => {
+ *     syncData();
+ *     console.log(`Sync #${info.emitCount} with ${info.subscriberCount} listeners`);
+ *   }, [signal]);
+ *
+ *   return <button onClick={emit}>Sync</button>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With data payload
+ * function DataEmitter() {
+ *   const { emit } = useSignal<{ userId: string }>("user-action");
+ *
+ *   const handleClick = (userId: string) => {
+ *     emit({ userId });
+ *   };
+ *
+ *   return <button onClick={() => handleClick("123")}>Action</button>;
+ * }
+ *
+ * function DataReceiver() {
+ *   const { signal, info } = useSignal<{ userId: string }>("user-action");
+ *
+ *   useEffect(() => {
+ *     if (info.data) {
+ *       console.log("User action for:", info.data.userId);
+ *     }
+ *   }, [signal]);
+ *
+ *   return <div>Listening...</div>;
+ * }
+ * ```
+ */
+declare function useSignal<T = unknown>(name: string, options?: SignalOptions): UseSignalReturn<T>;
+
+export { type SignalInfo, type SignalOptions, type UseSignalReturn, useSignal };

package/dist/index.js

@@ -0,0 +1,182 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  useSignal: () => useSignal
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useSignal.ts
+var import_react = require("react");
+
+// src/store.ts
+var signalStore = /* @__PURE__ */ new Map();
+function getOrCreateSignal(name) {
+  if (!signalStore.has(name)) {
+    signalStore.set(name, {
+      version: 0,
+      subscribers: /* @__PURE__ */ new Set(),
+      emitCount: 0,
+      timestamp: 0,
+      data: void 0
+    });
+  }
+  return signalStore.get(name);
+}
+function subscribe(name, listener) {
+  const signal = getOrCreateSignal(name);
+  signal.subscribers.add(listener);
+  return () => {
+    signal.subscribers.delete(listener);
+    if (signal.subscribers.size === 0 && signal.emitCount === 0) {
+      signalStore.delete(name);
+    }
+  };
+}
+function getSnapshot(name) {
+  const signal = signalStore.get(name);
+  return signal?.version ?? 0;
+}
+function emit(name, data) {
+  const signal = getOrCreateSignal(name);
+  signal.data = data;
+  signal.version += 1;
+  signal.emitCount += 1;
+  signal.timestamp = Date.now();
+  signal.subscribers.forEach((listener) => listener());
+}
+function getSubscriberCount(name) {
+  return signalStore.get(name)?.subscribers.size ?? 0;
+}
+function getEmitCount(name) {
+  return signalStore.get(name)?.emitCount ?? 0;
+}
+function getTimestamp(name) {
+  return signalStore.get(name)?.timestamp ?? 0;
+}
+function getData(name) {
+  return signalStore.get(name)?.data;
+}
+
+// src/useSignal.ts
+function useSignal(name, options = {}) {
+  const {
+    emitOnMount = false,
+    onEmit,
+    enabled = true,
+    debounce
+  } = options;
+  const onEmitRef = (0, import_react.useRef)(onEmit);
+  onEmitRef.current = onEmit;
+  const nameRef = (0, import_react.useRef)(name);
+  nameRef.current = name;
+  const infoRef = (0, import_react.useRef)(null);
+  if (!infoRef.current) {
+    infoRef.current = {
+      get name() {
+        return nameRef.current;
+      },
+      get subscriberCount() {
+        return getSubscriberCount(nameRef.current);
+      },
+      get timestamp() {
+        return getTimestamp(nameRef.current);
+      },
+      get emitCount() {
+        return getEmitCount(nameRef.current);
+      },
+      get data() {
+        return getData(nameRef.current);
+      }
+    };
+  }
+  const subscribeToStore = (0, import_react.useCallback)(
+    (onStoreChange) => {
+      if (!enabled) {
+        return () => {
+        };
+      }
+      return subscribe(name, onStoreChange);
+    },
+    [name, enabled]
+  );
+  const getSnapshot2 = (0, import_react.useCallback)(() => {
+    if (!enabled) {
+      return 0;
+    }
+    return getSnapshot(name);
+  }, [name, enabled]);
+  const getServerSnapshot = (0, import_react.useCallback)(() => {
+    return 0;
+  }, []);
+  const signal = (0, import_react.useSyncExternalStore)(
+    subscribeToStore,
+    getSnapshot2,
+    getServerSnapshot
+  );
+  const baseEmit = (0, import_react.useCallback)(
+    (data) => {
+      emit(name, data);
+      onEmitRef.current?.();
+    },
+    [name]
+  );
+  const debounceTimerRef = (0, import_react.useRef)(null);
+  const pendingDataRef = (0, import_react.useRef)(void 0);
+  const emit2 = (0, import_react.useMemo)(() => {
+    if (!debounce || debounce <= 0) {
+      return baseEmit;
+    }
+    return (data) => {
+      pendingDataRef.current = data;
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current);
+      }
+      debounceTimerRef.current = setTimeout(() => {
+        baseEmit(pendingDataRef.current);
+        pendingDataRef.current = void 0;
+        debounceTimerRef.current = null;
+      }, debounce);
+    };
+  }, [baseEmit, debounce]);
+  (0, import_react.useEffect)(() => {
+    return () => {
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current);
+      }
+    };
+  }, []);
+  (0, import_react.useEffect)(() => {
+    if (emitOnMount) {
+      baseEmit();
+    }
+  }, [emitOnMount, baseEmit]);
+  return {
+    signal,
+    emit: emit2,
+    info: infoRef.current
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useSignal
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/useSignal.ts","../src/store.ts"],"sourcesContent":["export {\n  useSignal,\n  type UseSignalReturn,\n  type SignalOptions,\n  type SignalInfo,\n} from \"./useSignal\";\n","import {\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n} from \"react\";\nimport {\n  subscribe,\n  getSnapshot as getStoreSnapshot,\n  emit as storeEmit,\n  getSubscriberCount,\n  getEmitCount,\n  getTimestamp,\n  getData,\n} from \"./store\";\n\n/**\n * Signal metadata object for debugging and monitoring\n */\nexport interface SignalInfo<T = unknown> {\n  /** Signal subscription name */\n  name: string;\n  /** Current number of active subscribers */\n  subscriberCount: number;\n  /** Timestamp of last emit (Date.now()) */\n  timestamp: number;\n  /** Total number of times this signal has been emitted */\n  emitCount: number;\n  /** Data passed with the last emit */\n  data: T | undefined;\n}\n\n/**\n * Options for useSignal hook\n */\nexport interface SignalOptions {\n  /** Automatically emit when component mounts */\n  emitOnMount?: boolean;\n  /** Callback executed when emit is called */\n  onEmit?: () => void;\n  /** Conditionally enable/disable subscription (default: true) */\n  enabled?: boolean;\n  /** Debounce emit calls in milliseconds */\n  debounce?: number;\n}\n\n/**\n * Return type for useSignal hook\n */\nexport interface UseSignalReturn<T = unknown> {\n  /** Current signal version number - use in dependency arrays */\n  signal: number;\n  /** Function to emit the signal and notify all subscribers, optionally with data */\n  emit: (data?: T) => void;\n  /** Stable metadata object for debugging and monitoring */\n  info: SignalInfo<T>;\n}\n\n/**\n * A hook for event-driven communication between components without prop drilling.\n * Components subscribe to a shared signal by name. When any component emits,\n * all subscribers receive a new version number.\n *\n * @param name - Unique identifier string for the signal channel\n * @param options - Configuration options\n * @returns Object containing signal value, emit function, and info metadata\n *\n * @example\n * ```tsx\n * // Parent Component - emits signal\n * function ParentComponent() {\n *   const { emit } = useSignal(\"Dashboard Refresh\");\n *\n *   return <button onClick={emit}>Refresh All</button>;\n * }\n *\n * // Child Component - subscribes to signal\n * function DataTable() {\n *   const { signal } = useSignal(\"Dashboard Refresh\");\n *\n *   useEffect(() => {\n *     fetchTableData();\n *   }, [signal]);\n *\n *   return <table>...</table>;\n * }\n * ```\n *\n * @example\n * ```tsx\n * // With debugging info\n * function MonitoredComponent() {\n *   const { signal, emit, info } = useSignal(\"API Sync\", {\n *     onEmit: () => console.log(\"Syncing...\")\n *   });\n *\n *   useEffect(() => {\n *     syncData();\n *     console.log(`Sync #${info.emitCount} with ${info.subscriberCount} listeners`);\n *   }, [signal]);\n *\n *   return <button onClick={emit}>Sync</button>;\n * }\n * ```\n *\n * @example\n * ```tsx\n * // With data payload\n * function DataEmitter() {\n *   const { emit } = useSignal<{ userId: string }>(\"user-action\");\n *\n *   const handleClick = (userId: string) => {\n *     emit({ userId });\n *   };\n *\n *   return <button onClick={() => handleClick(\"123\")}>Action</button>;\n * }\n *\n * function DataReceiver() {\n *   const { signal, info } = useSignal<{ userId: string }>(\"user-action\");\n *\n *   useEffect(() => {\n *     if (info.data) {\n *       console.log(\"User action for:\", info.data.userId);\n *     }\n *   }, [signal]);\n *\n *   return <div>Listening...</div>;\n * }\n * ```\n */\nexport function useSignal<T = unknown>(\n  name: string,\n  options: SignalOptions = {}\n): UseSignalReturn<T> {\n  const {\n    emitOnMount = false,\n    onEmit,\n    enabled = true,\n    debounce,\n  } = options;\n\n  // Store options in refs for stable references\n  const onEmitRef = useRef(onEmit);\n  onEmitRef.current = onEmit;\n\n  // Stable name ref for info object\n  const nameRef = useRef(name);\n  nameRef.current = name;\n\n  // Info object with stable reference using getters for live data\n  const infoRef = useRef<SignalInfo<T> | null>(null);\n  if (!infoRef.current) {\n    infoRef.current = {\n      get name() {\n        return nameRef.current;\n      },\n      get subscriberCount() {\n        return getSubscriberCount(nameRef.current);\n      },\n      get timestamp() {\n        return getTimestamp(nameRef.current);\n      },\n      get emitCount() {\n        return getEmitCount(nameRef.current);\n      },\n      get data() {\n        return getData(nameRef.current) as T | undefined;\n      },\n    } as SignalInfo<T>;\n  }\n\n  // Subscribe function for useSyncExternalStore\n  const subscribeToStore = useCallback(\n    (onStoreChange: () => void) => {\n      if (!enabled) {\n        return () => {};\n      }\n      return subscribe(name, onStoreChange);\n    },\n    [name, enabled]\n  );\n\n  // Get snapshot function\n  const getSnapshot = useCallback((): number => {\n    if (!enabled) {\n      return 0;\n    }\n    return getStoreSnapshot(name);\n  }, [name, enabled]);\n\n  // Server snapshot (always 0 for SSR)\n  const getServerSnapshot = useCallback((): number => {\n    return 0;\n  }, []);\n\n  // Use useSyncExternalStore for synchronized state\n  const signal = useSyncExternalStore(\n    subscribeToStore,\n    getSnapshot,\n    getServerSnapshot\n  );\n\n  // Base emit function\n  const baseEmit = useCallback(\n    (data?: T) => {\n      storeEmit(name, data);\n      onEmitRef.current?.();\n    },\n    [name]\n  );\n\n  // Debounce timer ref\n  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n  // Store the latest data for debounced emit\n  const pendingDataRef = useRef<T | undefined>(undefined);\n\n  // Debounced or regular emit\n  const emit = useMemo(() => {\n    if (!debounce || debounce <= 0) {\n      return baseEmit;\n    }\n\n    return (data?: T) => {\n      // Store the latest data\n      pendingDataRef.current = data;\n\n      if (debounceTimerRef.current) {\n        clearTimeout(debounceTimerRef.current);\n      }\n      debounceTimerRef.current = setTimeout(() => {\n        baseEmit(pendingDataRef.current);\n        pendingDataRef.current = undefined;\n        debounceTimerRef.current = null;\n      }, debounce);\n    };\n  }, [baseEmit, debounce]);\n\n  // Cleanup debounce timer on unmount\n  useEffect(() => {\n    return () => {\n      if (debounceTimerRef.current) {\n        clearTimeout(debounceTimerRef.current);\n      }\n    };\n  }, []);\n\n  // Emit on mount if option is set\n  useEffect(() => {\n    if (emitOnMount) {\n      baseEmit();\n    }\n  }, [emitOnMount, baseEmit]);\n\n  return {\n    signal,\n    emit,\n    info: infoRef.current!,\n  };\n}\n","/**\n * Internal Signal Store for cross-component communication\n * This module manages signal versions and subscribers for the useSignal hook.\n *\n * @internal This module is not exported publicly\n */\n\n/** Signal data structure for each named signal */\ninterface SignalData {\n  version: number;\n  subscribers: Set<() => void>;\n  emitCount: number;\n  timestamp: number;\n  data: unknown;\n}\n\n/** Map of signal name -> SignalData */\nconst signalStore = new Map<string, SignalData>();\n\n/**\n * Get or create signal data for a given name\n * @param name - The signal name\n * @returns SignalData object\n */\nfunction getOrCreateSignal(name: string): SignalData {\n  if (!signalStore.has(name)) {\n    signalStore.set(name, {\n      version: 0,\n      subscribers: new Set(),\n      emitCount: 0,\n      timestamp: 0,\n      data: undefined,\n    });\n  }\n  return signalStore.get(name)!;\n}\n\n/**\n * Subscribe a listener to changes for a specific signal name\n * @param name - The signal name to subscribe to\n * @param listener - Callback to invoke when the signal is emitted\n * @returns Unsubscribe function\n */\nexport function subscribe(name: string, listener: () => void): () => void {\n  const signal = getOrCreateSignal(name);\n  signal.subscribers.add(listener);\n\n  return () => {\n    signal.subscribers.delete(listener);\n\n    // Cleanup: remove the signal entry if no more subscribers and never emitted\n    if (signal.subscribers.size === 0 && signal.emitCount === 0) {\n      signalStore.delete(name);\n    }\n  };\n}\n\n/**\n * Get the current version number for a signal\n * @param name - The signal name\n * @returns Current version number (0 if signal doesn't exist)\n */\nexport function getSnapshot(name: string): number {\n  const signal = signalStore.get(name);\n  return signal?.version ?? 0;\n}\n\n/**\n * Emit a signal - update data, increment version, update metadata, and notify all subscribers\n * Data is set BEFORE version increment to ensure useEffect callbacks see the latest data.\n * @param name - The signal name to emit\n * @param data - Optional data to pass with the signal\n */\nexport function emit(name: string, data?: unknown): void {\n  const signal = getOrCreateSignal(name);\n\n  // Set data FIRST before incrementing version\n  // This ensures that when useEffect runs due to signal change,\n  // info.data already contains the latest value\n  signal.data = data;\n\n  signal.version += 1;\n  signal.emitCount += 1;\n  signal.timestamp = Date.now();\n\n  // Notify all subscribers\n  signal.subscribers.forEach((listener) => listener());\n}\n\n/**\n * Get the current subscriber count for a signal\n * @param name - The signal name\n * @returns Number of active subscribers\n */\nexport function getSubscriberCount(name: string): number {\n  return signalStore.get(name)?.subscribers.size ?? 0;\n}\n\n/**\n * Get the total emit count for a signal\n * @param name - The signal name\n * @returns Total number of times the signal has been emitted\n */\nexport function getEmitCount(name: string): number {\n  return signalStore.get(name)?.emitCount ?? 0;\n}\n\n/**\n * Get the last emit timestamp for a signal\n * @param name - The signal name\n * @returns Timestamp of last emit (0 if never emitted)\n */\nexport function getTimestamp(name: string): number {\n  return signalStore.get(name)?.timestamp ?? 0;\n}\n\n/**\n * Get the data passed with the last emit for a signal\n * @param name - The signal name\n * @returns Data from last emit (undefined if never emitted or no data)\n */\nexport function getData(name: string): unknown {\n  return signalStore.get(name)?.data;\n}\n\n/**\n * Clear all signals (for testing purposes)\n * @internal\n */\nexport function clearAllSignals(): void {\n  signalStore.clear();\n}\n"],"mappings":"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","names":["getSnapshot","emit"]}

package/dist/index.mjs

@@ -0,0 +1,161 @@
+// src/useSignal.ts
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore
+} from "react";
+
+// src/store.ts
+var signalStore = /* @__PURE__ */ new Map();
+function getOrCreateSignal(name) {
+  if (!signalStore.has(name)) {
+    signalStore.set(name, {
+      version: 0,
+      subscribers: /* @__PURE__ */ new Set(),
+      emitCount: 0,
+      timestamp: 0,
+      data: void 0
+    });
+  }
+  return signalStore.get(name);
+}
+function subscribe(name, listener) {
+  const signal = getOrCreateSignal(name);
+  signal.subscribers.add(listener);
+  return () => {
+    signal.subscribers.delete(listener);
+    if (signal.subscribers.size === 0 && signal.emitCount === 0) {
+      signalStore.delete(name);
+    }
+  };
+}
+function getSnapshot(name) {
+  const signal = signalStore.get(name);
+  return signal?.version ?? 0;
+}
+function emit(name, data) {
+  const signal = getOrCreateSignal(name);
+  signal.data = data;
+  signal.version += 1;
+  signal.emitCount += 1;
+  signal.timestamp = Date.now();
+  signal.subscribers.forEach((listener) => listener());
+}
+function getSubscriberCount(name) {
+  return signalStore.get(name)?.subscribers.size ?? 0;
+}
+function getEmitCount(name) {
+  return signalStore.get(name)?.emitCount ?? 0;
+}
+function getTimestamp(name) {
+  return signalStore.get(name)?.timestamp ?? 0;
+}
+function getData(name) {
+  return signalStore.get(name)?.data;
+}
+
+// src/useSignal.ts
+function useSignal(name, options = {}) {
+  const {
+    emitOnMount = false,
+    onEmit,
+    enabled = true,
+    debounce
+  } = options;
+  const onEmitRef = useRef(onEmit);
+  onEmitRef.current = onEmit;
+  const nameRef = useRef(name);
+  nameRef.current = name;
+  const infoRef = useRef(null);
+  if (!infoRef.current) {
+    infoRef.current = {
+      get name() {
+        return nameRef.current;
+      },
+      get subscriberCount() {
+        return getSubscriberCount(nameRef.current);
+      },
+      get timestamp() {
+        return getTimestamp(nameRef.current);
+      },
+      get emitCount() {
+        return getEmitCount(nameRef.current);
+      },
+      get data() {
+        return getData(nameRef.current);
+      }
+    };
+  }
+  const subscribeToStore = useCallback(
+    (onStoreChange) => {
+      if (!enabled) {
+        return () => {
+        };
+      }
+      return subscribe(name, onStoreChange);
+    },
+    [name, enabled]
+  );
+  const getSnapshot2 = useCallback(() => {
+    if (!enabled) {
+      return 0;
+    }
+    return getSnapshot(name);
+  }, [name, enabled]);
+  const getServerSnapshot = useCallback(() => {
+    return 0;
+  }, []);
+  const signal = useSyncExternalStore(
+    subscribeToStore,
+    getSnapshot2,
+    getServerSnapshot
+  );
+  const baseEmit = useCallback(
+    (data) => {
+      emit(name, data);
+      onEmitRef.current?.();
+    },
+    [name]
+  );
+  const debounceTimerRef = useRef(null);
+  const pendingDataRef = useRef(void 0);
+  const emit2 = useMemo(() => {
+    if (!debounce || debounce <= 0) {
+      return baseEmit;
+    }
+    return (data) => {
+      pendingDataRef.current = data;
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current);
+      }
+      debounceTimerRef.current = setTimeout(() => {
+        baseEmit(pendingDataRef.current);
+        pendingDataRef.current = void 0;
+        debounceTimerRef.current = null;
+      }, debounce);
+    };
+  }, [baseEmit, debounce]);
+  useEffect(() => {
+    return () => {
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current);
+      }
+    };
+  }, []);
+  useEffect(() => {
+    if (emitOnMount) {
+      baseEmit();
+    }
+  }, [emitOnMount, baseEmit]);
+  return {
+    signal,
+    emit: emit2,
+    info: infoRef.current
+  };
+}
+export {
+  useSignal
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useSignal.ts","../src/store.ts"],"sourcesContent":["import {\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n} from \"react\";\nimport {\n  subscribe,\n  getSnapshot as getStoreSnapshot,\n  emit as storeEmit,\n  getSubscriberCount,\n  getEmitCount,\n  getTimestamp,\n  getData,\n} from \"./store\";\n\n/**\n * Signal metadata object for debugging and monitoring\n */\nexport interface SignalInfo<T = unknown> {\n  /** Signal subscription name */\n  name: string;\n  /** Current number of active subscribers */\n  subscriberCount: number;\n  /** Timestamp of last emit (Date.now()) */\n  timestamp: number;\n  /** Total number of times this signal has been emitted */\n  emitCount: number;\n  /** Data passed with the last emit */\n  data: T | undefined;\n}\n\n/**\n * Options for useSignal hook\n */\nexport interface SignalOptions {\n  /** Automatically emit when component mounts */\n  emitOnMount?: boolean;\n  /** Callback executed when emit is called */\n  onEmit?: () => void;\n  /** Conditionally enable/disable subscription (default: true) */\n  enabled?: boolean;\n  /** Debounce emit calls in milliseconds */\n  debounce?: number;\n}\n\n/**\n * Return type for useSignal hook\n */\nexport interface UseSignalReturn<T = unknown> {\n  /** Current signal version number - use in dependency arrays */\n  signal: number;\n  /** Function to emit the signal and notify all subscribers, optionally with data */\n  emit: (data?: T) => void;\n  /** Stable metadata object for debugging and monitoring */\n  info: SignalInfo<T>;\n}\n\n/**\n * A hook for event-driven communication between components without prop drilling.\n * Components subscribe to a shared signal by name. When any component emits,\n * all subscribers receive a new version number.\n *\n * @param name - Unique identifier string for the signal channel\n * @param options - Configuration options\n * @returns Object containing signal value, emit function, and info metadata\n *\n * @example\n * ```tsx\n * // Parent Component - emits signal\n * function ParentComponent() {\n *   const { emit } = useSignal(\"Dashboard Refresh\");\n *\n *   return <button onClick={emit}>Refresh All</button>;\n * }\n *\n * // Child Component - subscribes to signal\n * function DataTable() {\n *   const { signal } = useSignal(\"Dashboard Refresh\");\n *\n *   useEffect(() => {\n *     fetchTableData();\n *   }, [signal]);\n *\n *   return <table>...</table>;\n * }\n * ```\n *\n * @example\n * ```tsx\n * // With debugging info\n * function MonitoredComponent() {\n *   const { signal, emit, info } = useSignal(\"API Sync\", {\n *     onEmit: () => console.log(\"Syncing...\")\n *   });\n *\n *   useEffect(() => {\n *     syncData();\n *     console.log(`Sync #${info.emitCount} with ${info.subscriberCount} listeners`);\n *   }, [signal]);\n *\n *   return <button onClick={emit}>Sync</button>;\n * }\n * ```\n *\n * @example\n * ```tsx\n * // With data payload\n * function DataEmitter() {\n *   const { emit } = useSignal<{ userId: string }>(\"user-action\");\n *\n *   const handleClick = (userId: string) => {\n *     emit({ userId });\n *   };\n *\n *   return <button onClick={() => handleClick(\"123\")}>Action</button>;\n * }\n *\n * function DataReceiver() {\n *   const { signal, info } = useSignal<{ userId: string }>(\"user-action\");\n *\n *   useEffect(() => {\n *     if (info.data) {\n *       console.log(\"User action for:\", info.data.userId);\n *     }\n *   }, [signal]);\n *\n *   return <div>Listening...</div>;\n * }\n * ```\n */\nexport function useSignal<T = unknown>(\n  name: string,\n  options: SignalOptions = {}\n): UseSignalReturn<T> {\n  const {\n    emitOnMount = false,\n    onEmit,\n    enabled = true,\n    debounce,\n  } = options;\n\n  // Store options in refs for stable references\n  const onEmitRef = useRef(onEmit);\n  onEmitRef.current = onEmit;\n\n  // Stable name ref for info object\n  const nameRef = useRef(name);\n  nameRef.current = name;\n\n  // Info object with stable reference using getters for live data\n  const infoRef = useRef<SignalInfo<T> | null>(null);\n  if (!infoRef.current) {\n    infoRef.current = {\n      get name() {\n        return nameRef.current;\n      },\n      get subscriberCount() {\n        return getSubscriberCount(nameRef.current);\n      },\n      get timestamp() {\n        return getTimestamp(nameRef.current);\n      },\n      get emitCount() {\n        return getEmitCount(nameRef.current);\n      },\n      get data() {\n        return getData(nameRef.current) as T | undefined;\n      },\n    } as SignalInfo<T>;\n  }\n\n  // Subscribe function for useSyncExternalStore\n  const subscribeToStore = useCallback(\n    (onStoreChange: () => void) => {\n      if (!enabled) {\n        return () => {};\n      }\n      return subscribe(name, onStoreChange);\n    },\n    [name, enabled]\n  );\n\n  // Get snapshot function\n  const getSnapshot = useCallback((): number => {\n    if (!enabled) {\n      return 0;\n    }\n    return getStoreSnapshot(name);\n  }, [name, enabled]);\n\n  // Server snapshot (always 0 for SSR)\n  const getServerSnapshot = useCallback((): number => {\n    return 0;\n  }, []);\n\n  // Use useSyncExternalStore for synchronized state\n  const signal = useSyncExternalStore(\n    subscribeToStore,\n    getSnapshot,\n    getServerSnapshot\n  );\n\n  // Base emit function\n  const baseEmit = useCallback(\n    (data?: T) => {\n      storeEmit(name, data);\n      onEmitRef.current?.();\n    },\n    [name]\n  );\n\n  // Debounce timer ref\n  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n  // Store the latest data for debounced emit\n  const pendingDataRef = useRef<T | undefined>(undefined);\n\n  // Debounced or regular emit\n  const emit = useMemo(() => {\n    if (!debounce || debounce <= 0) {\n      return baseEmit;\n    }\n\n    return (data?: T) => {\n      // Store the latest data\n      pendingDataRef.current = data;\n\n      if (debounceTimerRef.current) {\n        clearTimeout(debounceTimerRef.current);\n      }\n      debounceTimerRef.current = setTimeout(() => {\n        baseEmit(pendingDataRef.current);\n        pendingDataRef.current = undefined;\n        debounceTimerRef.current = null;\n      }, debounce);\n    };\n  }, [baseEmit, debounce]);\n\n  // Cleanup debounce timer on unmount\n  useEffect(() => {\n    return () => {\n      if (debounceTimerRef.current) {\n        clearTimeout(debounceTimerRef.current);\n      }\n    };\n  }, []);\n\n  // Emit on mount if option is set\n  useEffect(() => {\n    if (emitOnMount) {\n      baseEmit();\n    }\n  }, [emitOnMount, baseEmit]);\n\n  return {\n    signal,\n    emit,\n    info: infoRef.current!,\n  };\n}\n","/**\n * Internal Signal Store for cross-component communication\n * This module manages signal versions and subscribers for the useSignal hook.\n *\n * @internal This module is not exported publicly\n */\n\n/** Signal data structure for each named signal */\ninterface SignalData {\n  version: number;\n  subscribers: Set<() => void>;\n  emitCount: number;\n  timestamp: number;\n  data: unknown;\n}\n\n/** Map of signal name -> SignalData */\nconst signalStore = new Map<string, SignalData>();\n\n/**\n * Get or create signal data for a given name\n * @param name - The signal name\n * @returns SignalData object\n */\nfunction getOrCreateSignal(name: string): SignalData {\n  if (!signalStore.has(name)) {\n    signalStore.set(name, {\n      version: 0,\n      subscribers: new Set(),\n      emitCount: 0,\n      timestamp: 0,\n      data: undefined,\n    });\n  }\n  return signalStore.get(name)!;\n}\n\n/**\n * Subscribe a listener to changes for a specific signal name\n * @param name - The signal name to subscribe to\n * @param listener - Callback to invoke when the signal is emitted\n * @returns Unsubscribe function\n */\nexport function subscribe(name: string, listener: () => void): () => void {\n  const signal = getOrCreateSignal(name);\n  signal.subscribers.add(listener);\n\n  return () => {\n    signal.subscribers.delete(listener);\n\n    // Cleanup: remove the signal entry if no more subscribers and never emitted\n    if (signal.subscribers.size === 0 && signal.emitCount === 0) {\n      signalStore.delete(name);\n    }\n  };\n}\n\n/**\n * Get the current version number for a signal\n * @param name - The signal name\n * @returns Current version number (0 if signal doesn't exist)\n */\nexport function getSnapshot(name: string): number {\n  const signal = signalStore.get(name);\n  return signal?.version ?? 0;\n}\n\n/**\n * Emit a signal - update data, increment version, update metadata, and notify all subscribers\n * Data is set BEFORE version increment to ensure useEffect callbacks see the latest data.\n * @param name - The signal name to emit\n * @param data - Optional data to pass with the signal\n */\nexport function emit(name: string, data?: unknown): void {\n  const signal = getOrCreateSignal(name);\n\n  // Set data FIRST before incrementing version\n  // This ensures that when useEffect runs due to signal change,\n  // info.data already contains the latest value\n  signal.data = data;\n\n  signal.version += 1;\n  signal.emitCount += 1;\n  signal.timestamp = Date.now();\n\n  // Notify all subscribers\n  signal.subscribers.forEach((listener) => listener());\n}\n\n/**\n * Get the current subscriber count for a signal\n * @param name - The signal name\n * @returns Number of active subscribers\n */\nexport function getSubscriberCount(name: string): number {\n  return signalStore.get(name)?.subscribers.size ?? 0;\n}\n\n/**\n * Get the total emit count for a signal\n * @param name - The signal name\n * @returns Total number of times the signal has been emitted\n */\nexport function getEmitCount(name: string): number {\n  return signalStore.get(name)?.emitCount ?? 0;\n}\n\n/**\n * Get the last emit timestamp for a signal\n * @param name - The signal name\n * @returns Timestamp of last emit (0 if never emitted)\n */\nexport function getTimestamp(name: string): number {\n  return signalStore.get(name)?.timestamp ?? 0;\n}\n\n/**\n * Get the data passed with the last emit for a signal\n * @param name - The signal name\n * @returns Data from last emit (undefined if never emitted or no data)\n */\nexport function getData(name: string): unknown {\n  return signalStore.get(name)?.data;\n}\n\n/**\n * Clear all signals (for testing purposes)\n * @internal\n */\nexport function clearAllSignals(): void {\n  signalStore.clear();\n}\n"],"mappings":"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","names":["getSnapshot","emit"]}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@usefy/use-signal",
+  "version": "0.0.31",
+  "description": "A React hook for event-driven communication between components",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.0.0",
+    "jsdom": "^27.3.0",
+    "react": "^19.0.0",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mirunamu00/usefy.git",
+    "directory": "packages/use-signal"
+  },
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "hooks",
+    "signal",
+    "event",
+    "broadcast",
+    "pubsub"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}