@siggn/react 0.0.1

package/.prettierrc

@@ -0,0 +1,16 @@
+{
+  "arrowParens": "always",
+  "bracketSpacing": true,
+  "htmlWhitespaceSensitivity": "css",
+  "insertPragma": false,
+  "jsxSingleQuote": true,
+  "printWidth": 100,
+  "proseWrap": "always",
+  "quoteProps": "as-needed",
+  "requirePragma": false,
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "all",
+  "useTabs": false
+}

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @siggn/react
+
+## 0.0.1
+
+### Patch Changes
+
+- [`d2a88af`](https://github.com/Guiguerreiro39/siggn/commit/d2a88af8e484f28e436c594cd3238379295941a2)
+  Thanks [@Guiguerreiro39](https://github.com/Guiguerreiro39)! - Added react hooks support
+
+- Updated dependencies
+  [[`d2a88af`](https://github.com/Guiguerreiro39/siggn/commit/d2a88af8e484f28e436c594cd3238379295941a2)]:
+  - @siggn/core@0.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Guilherme Guerreiro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# @siggn/core
+
+A lightweight and type-safe event-driven pub/sub system for TypeScript projects.
+
+## 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.
+
+## Installation
+
+You can install the package using your favorite package manager:
+
+```bash
+npm install @siggn/core
+```
+
+```bash
+yarn add @siggn/core
+```
+
+```bash
+pnpm add @siggn/core
+```
+
+## Usage
+
+Here's a basic example of how to use Siggn:
+
+```typescript
+import { Siggn } from '@siggn/core';
+
+// 1. Define your message types
+type Message =
+  | { type: 'user_created'; userId: string; name: string }
+  | { type: 'user_deleted'; userId: string };
+
+// 2. Create a new Siggn instance
+const siggn = new Siggn<Message>();
+
+// 3. Subscribe to events
+// Use a unique ID for each subscriber to manage subscriptions
+const subscriberId = 'analytics-service';
+
+siggn.subscribe(subscriberId, 'user_created', (msg) => {
+  console.log(`[Analytics] New user created: ${msg.name} (ID: ${msg.userId})`);
+});
+
+// 4. Publish events
+siggn.publish({ type: 'user_created', userId: '123', name: 'John Doe' });
+// Output: [Analytics] New user created: John Doe (ID: 123)
+
+// 5. Unsubscribe from all events for a given ID
+siggn.unsubscribe(subscriberId);
+
+siggn.publish({ type: 'user_created', userId: '456', name: 'Jane Doe' });
+// No output, because the subscriber was removed.
+```
+
+### Using the `make` helper
+
+The `make` method simplifies managing subscriptions for a specific component or service.
+
+```typescript
+const userComponent = siggn.make('user-component');
+
+userComponent.subscribe('user_deleted', (msg) => {
+  console.log(`[UI] User ${msg.userId} was deleted. Updating view...`);
+});
+
+siggn.publish({ type: 'user_deleted', userId: '123' });
+// Output: [UI] User 123 was deleted. Updating view...
+
+// Unsubscribe from all subscriptions made by 'user-component'
+userComponent.unsubscribe();
+```
+
+### Subscribing to multiple events
+
+You can use `subscribeMany` to group subscriptions for a single subscriber.
+
+```typescript
+const auditService = siggn.make('audit-service');
+
+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}`);
+  });
+});
+
+siggn.publish({ type: 'user_created', userId: '789', name: 'Peter Pan' });
+siggn.publish({ type: 'user_deleted', userId: '123' });
+
+// Unsubscribe from all audit-service events
+auditService.unsubscribe();
+```
+
+### 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.
+
+```typescript
+const logger = siggn.make('logger-service');
+
+logger.subscribeAll((msg) => {
+  console.log(`[Logger] Received event of type: ${msg.type}`);
+});
+
+siggn.publish({ type: 'user_created', userId: '789', name: 'Peter Pan' });
+// Output: [Logger] Received event of type: user_created
+
+siggn.publish({ type: 'user_deleted', userId: '123' });
+// Output: [Logger] Received event of type: user_deleted
+
+// Unsubscribe from all logger-service events
+logger.unsubscribe();
+```
+
+### Extending message types with `createChild`
+
+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.
+
+```typescript
+// Continuing with the previous `Message` type...
+const baseSiggn = new Siggn<Message>();
+
+// 1. Define a new set of messages for a specialized module
+type AdminMessage = { type: 'admin_login'; adminId: string };
+
+// 2. Create a child bus that understands both `Message` and `AdminMessage`
+const adminSiggn = baseSiggn.createChild<AdminMessage>();
+
+// 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
+
+adminSiggn.publish({ type: 'admin_login', adminId: 'xyz' });
+// Output: [Admin Auth] Admin logged in: xyz
+
+// 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`.
+```
+
+## 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)`
+
+Subscribes a callback to all message types with a unique subscriber ID. The callback will receive
+every message published on the bus.
+
+### `unsubscribe(id)`
+
+Removes all subscriptions associated with a specific subscriber ID.
+
+### `make(id)`
+
+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.
+
+### `subscribeMany(id, setup)`
+
+A convenience method to subscribe to multiple message types for a single ID.
+
+### `createChild<C>()`
+
+Creates a new, independent `Siggn` instance whose message types are a union of the parent's types
+and the new child-specific types `C`.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@siggn/react",
+  "version": "0.0.1",
+  "description": "A lightweight type safe message bus system for React",
+  "keywords": [
+    "pub/sub",
+    "message",
+    "event",
+    "bus",
+    "react",
+    "typesafe"
+  ],
+  "publishConfig": {
+    "@siggn:registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "homepage": "https://github.com/Guiguerreiro39/siggn",
+  "bugs": {
+    "url": "https://github.com/Guiguerreiro39/siggn/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Guiguerreiro39/siggn.git/",
+    "directory": "packages/react"
+  },
+  "license": "MIT",
+  "author": "Guilherme Guerreiro (https://guilhermegr.com)",
+  "main": "./dist/index.cjs.js",
+  "module": "./dist/index.es.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.cjs.js"
+    }
+  },
+  "type": "module",
+  "sideEffects": false,
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vite": "^7.1.12",
+    "vite-plugin-dts": "^4.5.4",
+    "@vitejs/plugin-react": "^5.1.0",
+    "vitest": "^3.2.4",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.1.15",
+    "react": "^19.1.1",
+    "jsdom": "^27.0.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5",
+    "react": ">=18 <20"
+  },
+  "dependencies": {
+    "@siggn/core": "0.0.5"
+  },
+  "scripts": {
+    "dev": "vite build --watch",
+    "clean": "rm -rf dist",
+    "test:watch": "vitest",
+    "test": "vitest run",
+    "build": "vite build"
+  }
+}

package/src/hooks.ts

@@ -0,0 +1,39 @@
+import { type Msg, Siggn } from '@siggn/core';
+import { useEffect, useMemo, useRef, type DependencyList } from 'react';
+
+type SubscriptionOptions<T extends Msg> =
+  | Siggn<T>
+  | {
+      instance: Siggn<T>;
+      id?: string;
+    };
+
+export function useSubscribe<T extends Msg>(
+  options: SubscriptionOptions<T>,
+  setup: (
+    subscribe: <K extends T['type']>(
+      type: K,
+      callback: (msg: Extract<T, { type: K }>) => void,
+    ) => void,
+  ) => 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.subscribeMany(id, setup);
+
+    return () => {
+      instance.unsubscribe(id);
+    };
+  }, [instance, id, ...deps]);
+}
+
+export function useSiggn<T extends Msg>(): Siggn<T> {
+  const siggn = useRef<Siggn<T>>(new Siggn<T>());
+  return siggn.current;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './hooks.js';
+export * from '@siggn/core';

package/tests/hooks.test.tsx

@@ -0,0 +1,55 @@
+import { test, expect, describe, beforeEach } from 'vitest';
+import { useSiggn, useSubscribe } from '../src/hooks.js';
+import { Siggn } from '@siggn/core';
+import { act, render, renderHook, screen } from '@testing-library/react';
+import { useState } from 'react';
+
+type Msg =
+  | {
+      type: 'increment_count';
+      value: number;
+    }
+  | { type: 'decrement_count'; value: number };
+
+describe('@siggn/react', () => {
+  let siggn: Siggn<Msg>;
+
+  beforeEach(() => {
+    const { result } = renderHook(() => useSiggn<Msg>());
+    siggn = result.current;
+  });
+
+  test('user should be able to create a siggn instance and subscribe using hooks', () => {
+    function TestComponent() {
+      const [count, setCount] = useState(0);
+
+      useSubscribe(siggn, (subscribe) => {
+        subscribe('increment_count', (msg) => {
+          setCount((prev) => prev + msg.value);
+        });
+
+        subscribe('decrement_count', (msg) => {
+          setCount((prev) => prev - msg.value);
+        });
+      });
+
+      return <div data-testid='value'>{count}</div>;
+    }
+
+    render(<TestComponent />);
+
+    expect(screen.getByTestId('value')).toHaveTextContent('0');
+
+    act(() => {
+      siggn.publish({ type: 'increment_count', value: 4 });
+    });
+
+    expect(screen.getByTestId('value')).toHaveTextContent('4');
+
+    act(() => {
+      siggn.publish({ type: 'decrement_count', value: 2 });
+    });
+
+    expect(screen.getByTestId('value')).toHaveTextContent('2');
+  });
+});

package/tsconfig.build.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.src.json",
+  "compilerOptions": {
+    "tsBuildInfoFile": ".tsbuildinfo/build.tsbuildinfo",
+    "outDir": "dist",
+    "declarationDir": "dist",
+    "stripInternal": true
+  },
+  "references": [{ "path": "../core" }]
+}

package/tsconfig.examples.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["examples"],
+  "references": [
+    {
+      "path": "tsconfig.build.json"
+    }
+  ],
+  "compilerOptions": {
+    "tsBuildInfoFile": ".tsbuildinfo/examples.tsbuildinfo",
+    "rootDir": "examples",
+    "noEmit": true
+  }
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "references": [
+    {
+      "path": "tsconfig.src.json"
+    },
+    {
+      "path": "tsconfig.test.json"
+    },
+    {
+      "path": "tsconfig.examples.json"
+    }
+  ]
+}

package/tsconfig.src.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src"],
+  "compilerOptions": {
+    "tsBuildInfoFile": ".tsbuildinfo/src.tsbuildinfo",
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "references": [{ "path": "../core" }]
+}

package/tsconfig.test.json

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

package/vite.config.ts

@@ -0,0 +1,49 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import dts from 'vite-plugin-dts';
+import path from 'path';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@siggn/core': path.resolve(__dirname, '../core/src/index.ts'),
+    },
+  },
+  build: {
+    lib: {
+      entry: 'src/index.ts',
+      name: 'SiggnReact',
+      formats: ['es', 'cjs'],
+      fileName: (format) => `index.${format}.js`,
+    },
+    sourcemap: true,
+    outDir: 'dist',
+    emptyOutDir: true,
+    rollupOptions: {
+      // Prevent bundling peer dependencies like React, etc.
+      external: ['react', 'react-dom', '@siggn/core'],
+      output: {
+        globals: {
+          react: 'React',
+          'react-dom': 'ReactDOM',
+          '@siggn/core': 'SiggnCore',
+        },
+      },
+    },
+  },
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: './vitest.setup.ts',
+  },
+  plugins: [
+    react(),
+    dts({
+      insertTypesEntry: true,
+      tsconfigPath: 'tsconfig.build.json',
+      outDir: 'dist',
+      include: ['src'],
+      exclude: ['src/**/*.test.ts', 'tests/**'],
+    }),
+  ],
+});

package/vitest.setup.ts

@@ -0,0 +1,7 @@
+import '@testing-library/jest-dom/vitest';
+import { cleanup } from '@testing-library/react';
+import { afterEach } from 'vitest';
+
+afterEach(() => {
+  cleanup();
+});