@siggn/react 0.0.1 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @siggn/react
 
+## 0.1.0
+
+### Minor Changes
+
+- [`54e3afd`](https://github.com/Guiguerreiro39/siggn/commit/54e3afd430bdb73ef0549ebdfbf9fc6f76bc62b1)
+  Thanks [@Guiguerreiro39](https://github.com/Guiguerreiro39)! - - Introduced automatic garbage
+  collection to prevent memory leaks.
+  - Added code documentation
+  - Added `subscriptionsCount` property to `Siggn`
+
+### Patch Changes
+
+- Updated dependencies
+  [[`54e3afd`](https://github.com/Guiguerreiro39/siggn/commit/54e3afd430bdb73ef0549ebdfbf9fc6f76bc62b1)]:
+  - @siggn/core@0.1.0
+
 ## 0.0.1
 
 ### Patch Changes

package/README.md

@@ -1,202 +1,173 @@
-# @siggn/core
+[![npm version](https://badge.fury.io/js/%40siggn%2Freact.svg)](https://www.npmjs.com/package/%40siggn%2Freact)
 
-A lightweight and type-safe event-driven pub/sub system for TypeScript projects.
+# @siggn/react
+
+React package for `@siggn/core`, providing a simple and idiomatic way to integrate the message bus with your React components.
 
 ## Features
 
-- **Type-Safe**: Leverages TypeScript to ensure that message payloads are correct at compile and
-  runtime.
-- **Lightweight**: Zero dependencies and a minimal API surface.
-- **Simple API**: Easy to learn and use, with a clear and concise API.
+- **Seamless Integration**: Hooks-based API that feels natural in React.
+- **Automatic Cleanup**: Subscriptions are automatically managed throughout the component lifecycle.
+- **Type-Safe**: Full TypeScript support, inheriting the type safety of `@siggn/core`.
 
 ## Installation
 
-You can install the package using your favorite package manager:
-
 ```bash
-npm install @siggn/core
+npm install @siggn/react
 ```
 
 ```bash
-yarn add @siggn/core
+yarn add @siggn/react
 ```
 
 ```bash
-pnpm add @siggn/core
+pnpm add @siggn/react
 ```
 
 ## Usage
 
-Here's a basic example of how to use Siggn:
+The primary way to use `@siggn/react` is by creating a `Siggn` instance and sharing it across your application. You can do this using React Context or by exporting a singleton instance.
 
-```typescript
-import { Siggn } from '@siggn/core';
+### 1. Create a Siggn Instance
 
-// 1. Define your message types
-type Message =
-  | { type: 'user_created'; userId: string; name: string }
-  | { type: 'user_deleted'; userId: string };
+It's recommended to create a single `Siggn` instance and share it throughout your app.
 
-// 2. Create a new Siggn instance
-const siggn = new Siggn<Message>();
+```typescript
+// src/siggn.ts
+import { Siggn } from '@siggn/react';
 
-// 3. Subscribe to events
-// Use a unique ID for each subscriber to manage subscriptions
-const subscriberId = 'analytics-service';
+// Define your message types
+export type Message =
+  | { type: 'user_login'; name: string }
+  | { type: 'user_logout' };
 
-siggn.subscribe(subscriberId, 'user_created', (msg) => {
-  console.log(`[Analytics] New user created: ${msg.name} (ID: ${msg.userId})`);
-});
+// Create and export the instance
+export const siggn = new Siggn<Message>();
+```
 
-// 4. Publish events
-siggn.publish({ type: 'user_created', userId: '123', name: 'John Doe' });
-// Output: [Analytics] New user created: John Doe (ID: 123)
+Alternatively, you can use the `useSiggn` hook to create a `Siggn` instance that is scoped to a component and its children.
 
-// 5. Unsubscribe from all events for a given ID
-siggn.unsubscribe(subscriberId);
+### 2. Subscribe to Events in a Component
 
-siggn.publish({ type: 'user_created', userId: '456', name: 'Jane Doe' });
-// No output, because the subscriber was removed.
-```
+Use the `useSubscribe` hook to listen for messages. It automatically handles subscribing and unsubscribing.
 
-### Using the `make` helper
+```tsx
+// src/components/Notification.tsx
+import { useState } from 'react';
+import { useSubscribe } from '@siggn/react';
+import { siggn, type Message } from '../siggn';
 
-The `make` method simplifies managing subscriptions for a specific component or service.
+function Notification() {
+  const [notification, setNotification] = useState<string | null>(null);
 
-```typescript
-const userComponent = siggn.make('user-component');
+  useSubscribe(siggn, (subscribe) => {
+    subscribe('user_login', (msg) => {
+      setNotification(`Welcome, ${msg.name}!`);
+    });
 
-userComponent.subscribe('user_deleted', (msg) => {
-  console.log(`[UI] User ${msg.userId} was deleted. Updating view...`);
-});
+    subscribe('user_logout', () => {
+      setNotification('You have been logged out.');
+    });
+  });
 
-siggn.publish({ type: 'user_deleted', userId: '123' });
-// Output: [UI] User 123 was deleted. Updating view...
+  if (!notification) {
+    return null;
+  }
 
-// Unsubscribe from all subscriptions made by 'user-component'
-userComponent.unsubscribe();
+  return <div className='notification'>{notification}</div>;
+}
 ```
 
-### Subscribing to multiple events
-
-You can use `subscribeMany` to group subscriptions for a single subscriber.
+### 3. Publish Events
 
-```typescript
-const auditService = siggn.make('audit-service');
+You can publish events from anywhere in your application.
 
-auditService.subscribeMany((subscribe) => {
-  subscribe('user_created', (msg) => {
-    console.log(`[Audit] User created: ${msg.name}`);
-  });
-  subscribe('user_deleted', (msg) => {
-    console.log(`[Audit] User deleted: ${msg.userId}`);
-  });
-});
+```tsx
+// src/components/AuthButton.tsx
+import { siggn } from '../siggn';
 
-siggn.publish({ type: 'user_created', userId: '789', name: 'Peter Pan' });
-siggn.publish({ type: 'user_deleted', userId: '123' });
+function AuthButton({ isLoggedIn }: { isLoggedIn: boolean }) {
+  const handleClick = () => {
+    if (isLoggedIn) {
+      siggn.publish({ type: 'user_logout' });
+    } else {
+      siggn.publish({ type: 'user_login', name: 'Jane Doe' });
+    }
+  };
 
-// Unsubscribe from all audit-service events
-auditService.unsubscribe();
+  return <button onClick={handleClick}>{isLoggedIn ? 'Log Out' : 'Log In'}</button>;
+}
 ```
 
-### Subscribing to all events
-
-If you need to listen to every message that passes through the bus, regardless of its type, you can
-use `subscribeAll`. This is useful for cross-cutting concerns like logging or debugging.
+### Subscribing to All Events
 
-```typescript
-const logger = siggn.make('logger-service');
-
-logger.subscribeAll((msg) => {
-  console.log(`[Logger] Received event of type: ${msg.type}`);
-});
+If you need to listen to all messages, you can use `useSubscribeAll`. This is useful for cross-cutting concerns like logging or analytics.
 
-siggn.publish({ type: 'user_created', userId: '789', name: 'Peter Pan' });
-// Output: [Logger] Received event of type: user_created
+```tsx
+// src/components/Logger.tsx
+import { useSubscribeAll } from '@siggn/react';
+import { siggn } from '../siggn';
 
-siggn.publish({ type: 'user_deleted', userId: '123' });
-// Output: [Logger] Received event of type: user_deleted
+function Logger() {
+  useSubscribeAll(siggn, (msg) => {
+    console.log(`[Logger] Event of type ${msg.type} was triggered`);
+  });
 
-// Unsubscribe from all logger-service events
-logger.unsubscribe();
+  return null; // This component does not render anything
+}
 ```
 
-### Extending message types with `createChild`
+### Using `useSiggn`
 
-The `createChild` method allows you to create a new, independent `Siggn` instance that inherits the
-message types of its parent. This is useful for creating specialized message buses that extend a
-base set of events without affecting the parent bus.
+The `useSiggn` hook creates a `Siggn` instance that is tied to the component's lifecycle. This can be useful for local, component-specific event buses.
 
-```typescript
-// Continuing with the previous `Message` type...
-const baseSiggn = new Siggn<Message>();
+```tsx
+import { useSiggn, useSubscribe } from '@siggn/react';
 
-// 1. Define a new set of messages for a specialized module
-type AdminMessage = { type: 'admin_login'; adminId: string };
+type LocalMessage = { type: 'local_event' };
 
-// 2. Create a child bus that understands both `Message` and `AdminMessage`
-const adminSiggn = baseSiggn.createChild<AdminMessage>();
+function LocalComponent() {
+  const localSiggn = useSiggn<LocalMessage>();
 
-// 3. Subscribe to events on the child bus
-adminSiggn.subscribe('audit-log', 'user_created', (msg) => {
-  console.log(`[Admin Audit] User created: ${msg.name}`);
-});
-
-adminSiggn.subscribe('auth-service', 'admin_login', (msg) => {
-  console.log(`[Admin Auth] Admin logged in: ${msg.adminId}`);
-});
-
-// 4. Publish events on the child bus
-adminSiggn.publish({ type: 'user_created', userId: 'abc', name: 'Alice' });
-// Output: [Admin Audit] User created: Alice
+  useSubscribe(localSiggn, (subscribe) => {
+    subscribe('local_event', () => {
+      console.log('Local event received!');
+    });
+  });
 
-adminSiggn.publish({ type: 'admin_login', adminId: 'xyz' });
-// Output: [Admin Auth] Admin logged in: xyz
+  const triggerEvent = () => {
+    localSiggn.publish({ type: 'local_event' });
+  };
 
-// Note: The parent and child buses are independent.
-// Publishing on the parent does not affect the child's subscribers.
-baseSiggn.publish({ type: 'user_created', userId: 'def', name: 'Bob' });
-// No output, because the subscription is on `adminSiggn`.
+  return <button onClick={triggerEvent}>Trigger Local Event</button>;
+}
 ```
 
 ## API
 
-### `new Siggn<T>()`
-
-Creates a new message bus instance. `T` is a union type of all possible messages.
-
-### `publish(msg)`
-
-Publishes a message to all relevant subscribers.
-
-### `subscribe(id, type, callback)`
-
-Subscribes a callback to a specific message type with a unique subscriber ID.
-
-### `subscribeAll(id, callback)`
+### `useSiggn<T>()`
 
-Subscribes a callback to all message types with a unique subscriber ID. The callback will receive
-every message published on the bus.
+Creates and returns a `Siggn` instance that persists for the lifetime of the component.
 
-### `unsubscribe(id)`
+- `T`: A union type of all possible messages.
 
-Removes all subscriptions associated with a specific subscriber ID.
+Returns a `Siggn<T>` instance.
 
-### `make(id)`
+### `useSubscribe(options, setup, deps)`
 
-Returns a helper object with `subscribe`, `subscribeMany`, `subscribeAll`, and `unsubscribe` methods
-pre-bound to the provided ID. This is useful for encapsulating subscription logic within a component
-or service.
+Subscribes to messages and automatically unsubscribes when the component unmounts.
 
-### `subscribeMany(id, setup)`
+- `options`: A `Siggn` instance or an object `{ instance: Siggn<T>; id?: string; }`.
+- `setup`: A function that receives a `subscribe` helper to define subscriptions, similar to `subscribeMany` in `@siggn/core`.
+- `deps` (optional): A dependency array to control when the subscriptions are re-created.
 
-A convenience method to subscribe to multiple message types for a single ID.
+### `useSubscribeAll(options, callback, deps)`
 
-### `createChild<C>()`
+Subscribes to all messages and automatically unsubscribes when the component unmounts.
 
-Creates a new, independent `Siggn` instance whose message types are a union of the parent's types
-and the new child-specific types `C`.
+- `options`: A `Siggn` instance or an object `{ instance: Siggn<T>; id?: string; }`.
+- `callback`: A function that will be called with every message.
+- `deps` (optional): A dependency array to control when the subscriptions are re-created.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siggn/react",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "A lightweight type safe message bus system for React",
   "keywords": [
     "pub/sub",
@@ -55,13 +55,14 @@
     "react": ">=18 <20"
   },
   "dependencies": {
-    "@siggn/core": "0.0.5"
+    "@siggn/core": "0.1.0"
   },
   "scripts": {
     "dev": "vite build --watch",
     "clean": "rm -rf dist",
     "test:watch": "vitest",
     "test": "vitest run",
+    "coverage": "vitest run --coverage",
     "build": "vite build"
   }
 }

package/src/hooks.ts

@@ -1,13 +1,51 @@
 import { type Msg, Siggn } from '@siggn/core';
+import type { SubscriptionOptions } from 'packages/react/src/types';
 import { useEffect, useMemo, useRef, type DependencyList } from 'react';
 
-type SubscriptionOptions<T extends Msg> =
-  | Siggn<T>
-  | {
-      instance: Siggn<T>;
-      id?: string;
-    };
+/**
+ * Creates and returns a `Siggn` instance that persists for the lifetime of the component.
+ * This is useful for creating a message bus scoped to a component and its children.
+ *
+ * @template T A union of all possible message types for the new instance.
+ * @returns A `Siggn<T>` instance.
+ * @category Lifecycle
+ * @since 0.0.1
+ * @example
+ * 
+```tsx
+ * function MyComponent() {
+ *   const localSiggn = useSiggn<{ type: 'local-event' }>();
+ *   // ...
+ * }
+ * ```
+ */
+export function useSiggn<T extends Msg>(): Siggn<T> {
+  const siggn = useRef(new Siggn<T>());
+  return siggn.current;
+}
 
+/**
+ * Subscribes to messages and automatically unsubscribes when the component unmounts.
+ *
+ * @template T A union of all possible message types.
+ * @param options A `Siggn` instance or an object with the instance and an optional subscriber ID.
+ * @param setup A function that receives a `subscribe` helper to define subscriptions.
+ * @param deps An optional dependency array to control when the subscriptions are re-created.
+ * @category Subscription
+ * @since 0.0.1
+ * @example
+ * 
+```tsx
+ * import { siggn } from './siggn'; // Your shared instance
+ *
+ * function MyComponent() {
+ *   useSubscribe(siggn, (subscribe) => {
+ *     subscribe('user-created', (msg) => console.log(msg.name));
+ *   });
+ *   // ...
+ * }
+ * ```
+ */
 export function useSubscribe<T extends Msg>(
   options: SubscriptionOptions<T>,
   setup: (
@@ -33,7 +71,45 @@ export function useSubscribe<T extends Msg>(
   }, [instance, id, ...deps]);
 }
 
-export function useSiggn<T extends Msg>(): Siggn<T> {
-  const siggn = useRef<Siggn<T>>(new Siggn<T>());
-  return siggn.current;
+/**
+ * Subscribes to all messages on a `Siggn` instance and automatically unsubscribes
+ * when the component unmounts.
+ *
+ * @template T A union of all possible message types.
+ * @param options A `Siggn` instance or an object with the instance and an optional subscriber ID.
+ * @param callback The function to call for any message.
+ * @param deps An optional dependency array to control when the subscription is re-created.
+ * @category Subscription
+ * @since 0.0.1
+ * @example
+ * 
+```tsx
+ * import { siggn } from './siggn';
+ *
+ * function LoggerComponent() {
+ *   useSubscribeAll(siggn, (msg) => {
+ *     console.log(`[LOG]: ${msg.type}`);
+ *   }, []);
+ *   // ...
+ * }
+ * ```
+ */
+export function useSubscribeAll<T extends Msg>(
+  options: SubscriptionOptions<T>,
+  callback: (msg: T) => void,
+  deps: DependencyList = [],
+) {
+  const instance = useMemo(
+    () => (options instanceof Siggn ? options : options.instance),
+    [options],
+  );
+  const id = useMemo(() => instance.makeId('id' in options ? options.id : undefined), [instance]);
+
+  useEffect(() => {
+    instance.subscribeAll(id, callback);
+
+    return () => {
+      instance.unsubscribeGlobal(id);
+    };
+  }, [instance, id, ...deps]);
 }

package/src/types.ts

@@ -0,0 +1,8 @@
+import type { Msg, Siggn } from '@siggn/core';
+
+export type SubscriptionOptions<T extends Msg> =
+  | Siggn<T>
+  | {
+      instance: Siggn<T>;
+      id?: string;
+    };

package/tests/hooks.test.tsx

@@ -1,7 +1,7 @@
-import { test, expect, describe, beforeEach } from 'vitest';
-import { useSiggn, useSubscribe } from '../src/hooks.js';
+import { test, expect, describe, beforeEach, afterEach, vi } from 'vitest';
+import { useSiggn, useSubscribe, useSubscribeAll } from '../src/hooks.js';
 import { Siggn } from '@siggn/core';
-import { act, render, renderHook, screen } from '@testing-library/react';
+import { act, render, renderHook, screen, cleanup } from '@testing-library/react';
 import { useState } from 'react';
 
 type Msg =
@@ -9,7 +9,9 @@ type Msg =
       type: 'increment_count';
       value: number;
     }
-  | { type: 'decrement_count'; value: number };
+  | { type: 'decrement_count'; value: number }
+  | { type: 'custom_event'; data: string }
+  | { type: 'dependency_changed'; newValue: number };
 
 describe('@siggn/react', () => {
   let siggn: Siggn<Msg>;
@@ -19,6 +21,10 @@ describe('@siggn/react', () => {
     siggn = result.current;
   });
 
+  afterEach(() => {
+    cleanup();
+  });
+
   test('user should be able to create a siggn instance and subscribe using hooks', () => {
     function TestComponent() {
       const [count, setCount] = useState(0);
@@ -52,4 +58,213 @@ describe('@siggn/react', () => {
 
     expect(screen.getByTestId('value')).toHaveTextContent('2');
   });
+
+  test('useSiggn should return a stable instance across re-renders', () => {
+    const { result, rerender } = renderHook(() => useSiggn<Msg>());
+    const firstInstance = result.current;
+
+    rerender(); // Re-render the hook
+
+    const secondInstance = result.current;
+    expect(firstInstance).toBe(secondInstance); // Should be the same instance
+  });
+
+  test('useSubscribe should work with explicit id in options', () => {
+    let receivedData: string | null = null;
+    const customId = 'my-custom-subscriber';
+
+    function TestComponent() {
+      useSubscribe({ instance: siggn, id: customId }, (subscribe) => {
+        subscribe('custom_event', (msg) => {
+          receivedData = msg.data;
+        });
+      });
+      return null;
+    }
+
+    render(<TestComponent />);
+
+    act(() => {
+      siggn.publish({ type: 'custom_event', data: 'hello' });
+    });
+
+    expect(receivedData).toBe('hello');
+
+    // Manually unsubscribe using the custom ID
+    act(() => {
+      siggn.unsubscribe(customId);
+    });
+
+    act(() => {
+      siggn.publish({ type: 'custom_event', data: 'world' });
+    });
+
+    // Should not receive 'world' as it's unsubscribed
+    expect(receivedData).toBe('hello');
+  });
+
+  test('useSubscribe should re-subscribe when dependencies change', () => {
+    let callCount = 0;
+    let lastReceivedValue = 0;
+
+    function TestComponent({ depValue }: { depValue: number }) {
+      useSubscribe(
+        siggn,
+        (subscribe) => {
+          callCount++; // This should increment when subscription is re-established
+          subscribe('dependency_changed', (msg) => {
+            lastReceivedValue = msg.newValue + depValue; // Use depValue in callback
+          });
+        },
+        [depValue], // Dependency array includes depValue
+      );
+      return <div data-testid='last-value'>{lastReceivedValue}</div>;
+    }
+
+    const { rerender } = render(<TestComponent depValue={10} />);
+
+    act(() => {
+      siggn.publish({ type: 'dependency_changed', newValue: 5 });
+    });
+    expect(lastReceivedValue).toBe(15); // 5 + 10
+    expect(callCount).toBe(1);
+
+    rerender(<TestComponent depValue={20} />); // Change dependency
+
+    act(() => {
+      siggn.publish({ type: 'dependency_changed', newValue: 5 });
+    });
+
+    expect(lastReceivedValue).toBe(25); // 5 + 20
+    expect(callCount).toBe(2); // Subscription should have been re-established
+  });
+
+  test('useSubscribe should automatically unsubscribe on component unmount', () => {
+    let receivedMessage: string | null = null;
+
+    function TestComponent() {
+      useSubscribe(siggn, (subscribe) => {
+        subscribe('custom_event', (msg) => {
+          receivedMessage = msg.data;
+        });
+      });
+      return null;
+    }
+
+    const { unmount } = render(<TestComponent />);
+
+    act(() => {
+      siggn.publish({ type: 'custom_event', data: 'first message' });
+    });
+    expect(receivedMessage).toBe('first message');
+
+    receivedMessage = null; // Reset for next check
+
+    unmount(); // Unmount the component
+
+    act(() => {
+      siggn.publish({ type: 'custom_event', data: 'second message' });
+    });
+
+    // After unmount, the subscription should be gone
+    expect(receivedMessage).toBeNull();
+  });
+
+  test('useSubscribeAll should receive all messages', () => {
+    const receivedMessages: Msg[] = [];
+    const callback = vi.fn((msg: Msg) => {
+      receivedMessages.push(msg);
+    });
+
+    function TestComponent() {
+      useSubscribeAll(siggn, callback);
+      return null;
+    }
+
+    render(<TestComponent />);
+
+    act(() => {
+      siggn.publish({ type: 'increment_count', value: 1 });
+      siggn.publish({ type: 'custom_event', data: 'test' });
+    });
+
+    expect(callback).toHaveBeenCalledTimes(2);
+    expect(receivedMessages).toEqual([
+      { type: 'increment_count', value: 1 },
+      { type: 'custom_event', data: 'test' },
+    ]);
+  });
+
+  test('useSubscribeAll should automatically unsubscribe on component unmount', () => {
+    const callback = vi.fn();
+
+    function TestComponent() {
+      useSubscribeAll(siggn, callback);
+      return null;
+    }
+
+    const { unmount } = render(<TestComponent />);
+
+    act(() => {
+      siggn.publish({ type: 'increment_count', value: 1 });
+    });
+    expect(callback).toHaveBeenCalledTimes(1);
+
+    unmount();
+
+    act(() => {
+      siggn.publish({ type: 'custom_event', data: 'after unmount' });
+    });
+
+    expect(callback).toHaveBeenCalledTimes(1); // Should not be called again
+  });
+
+  test('useSubscribeAll should re-subscribe when dependencies change', () => {
+    const callback = vi.fn();
+
+    function TestComponent({ dep }: { dep: number }) {
+      useSubscribeAll(siggn, callback, [dep]);
+      return null;
+    }
+
+    const { rerender } = render(<TestComponent dep={1} />);
+
+    act(() => {
+      siggn.publish({ type: 'increment_count', value: 1 });
+    });
+    expect(callback).toHaveBeenCalledTimes(1);
+
+    rerender(<TestComponent dep={2} />);
+
+    act(() => {
+      siggn.publish({ type: 'increment_count', value: 2 });
+    });
+    expect(callback).toHaveBeenCalledTimes(2);
+  });
+
+  test('useSubscribeAll should work with explicit id in options', () => {
+    const callback = vi.fn();
+    const customId = 'my-global-subscriber';
+
+    function TestComponent() {
+      useSubscribeAll({ instance: siggn, id: customId }, callback);
+      return null;
+    }
+
+    render(<TestComponent />);
+
+    act(() => {
+      siggn.publish({ type: 'increment_count', value: 1 });
+    });
+    expect(callback).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      siggn.unsubscribeGlobal(customId);
+    });
+
+    act(() => {
+      siggn.publish({ type: 'increment_count', value: 2 });
+    });
+    expect(callback).toHaveBeenCalledTimes(1); // Should not be called again
+  });
 });

package/tsconfig.test.json

@@ -1,6 +1,6 @@
 {
   "extends": "../../tsconfig.base.json",
-  "include": ["test"],
+  "include": ["tests"],
   "references": [
     {
       "path": "tsconfig.src.json"
@@ -8,7 +8,7 @@
   ],
   "compilerOptions": {
     "tsBuildInfoFile": ".tsbuildinfo/test.tsbuildinfo",
-    "rootDir": "test",
+    "rootDir": "tests",
     "noEmit": true,
     "jsx": "react-jsx",
     "types": ["@testing-library/jest-dom", "vitest/globals"]