class-signals
Version:
OOP-Style events
138 lines (94 loc) • 3.26 kB
Markdown
[](https://www.npmjs.com/package/class-signals)
[](https://github.com/your-username/class-signals/blob/main/LICENSE)
# 🎯 signal-system
> Reactive signaling for class-based TypeScript — safe, simple, and expressive.
A small, focused library for creating and managing reactive signals in object-oriented JavaScript and TypeScript.
Use it to **broadcast changes**, **listen to internal events**, and **expose read-only observables** — all with strong typing and no boilerplate.
## ⚡ Quick Example
```ts
import { Signal } from "signal-system"
const onMessage = new Signal<string>()
onMessage.subscribe((text) => {
console.log("📩 Message received:", text)
})
onMessage.activate("Hello, world!")
```
> ✅ For safe, read-only signal exposure, use `ProtectedSignal` + `ProtectedSignalController`
## 🧠 Public API
### 🔔 `Signal<T>`
A reactive signal that allows both **subscribing** and **activating** updates.
Great for local event buses, live data updates, or observable service events.
```ts
const signal = new Signal<number>()
signal.subscribe((v) => console.log("Received:", v))
signal.activate(42)
```
- `subscribe(fn, options?)`
- `unsubscribe(fn, options?)`
- `activate(payload)`
### 🔒 `ProtectedSignal<T>`
A **read-only** signal: lets others subscribe, but only you can activate it.
Designed for safe reactive encapsulation.
```ts
class Store {
#events = new ProtectedSignalController<string>()
public readonly onChange = this.#events.signal
update() {
this.#events.activate("updated")
}
}
```
- `subscribe(fn, options?)`
- `unsubscribe(fn, options?)`
### 🛠️ `ProtectedSignalController<T>`
Holds the power to **trigger** a protected signal.
Perfect for internal logic, paired with a `ProtectedSignal` for external safety.
```ts
const controller = new ProtectedSignalController<number>()
controller.signal.subscribe((v) => console.log(v))
controller.activate(1)
```
- `activate(payload)`
- `signal` — the exposed read-only `ProtectedSignal<T>`
## 💡 Recommended Patterns
### ✅ Expose only what’s needed
```ts
class AuthService {
#changed = new ProtectedSignalController<void>()
public readonly onChange = this.#changed.signal
login() {
this.#changed.activate()
}
}
```
### ✂️ Auto-unsubscribe with AbortSignal
```ts
const controller = new AbortController()
signal.subscribe(fn, { signal: controller.signal })
controller.abort()
```
### 🧱 Object-based subscribers
```ts
signal.subscribe({
handleSignal(value) {
console.log("Handled:", value)
},
})
```
## 🤔 Why not EventTarget / EventEmitter?
- No event names to manage (`"change"`, `"data"` — gone!)
- Fully typed payloads
- Easy read-only APIs
- `AbortSignal` and `once` built-in
- Focused: no bubbling, no DOM quirks, no legacy cruft
🧩 Use `Signal` when you need control.
🔒 Use `ProtectedSignal` to expose safe subscriptions.
⚙️ Use `ProtectedSignalController` to manage internal dispatch.
> That’s it. Clean signals for class-based codebases.