@misaka17535/create-typed-event v1.0.12

createTypedEvent

English | 中文

A modern eventManager, bridging vanilla-js and reactive frameworks, with types to prevent errors.
Proven and well-tested in private projects.

Compared to others

• rxjs
  • Its Objective: requires you to create an Observable/Subject object.
  • Way much larger package size: rxjs@7.8.2 itself takes 4.29MB, while this library only takes 12.5KB (can be smaller in the future).
• mitt
  • Requires you to write event name: emitter.on('xxx'...
  • Does not return an unsub method.
  • Does not support getting current value.
• so many others
  • Almost every library I know requires you to write event name on subscription, and cannot auto-complete.

Examples

Traditional unsubscribe:

import { createTypedEvent } from '@misaka17535/create-typed-event'

type Payload = { ready: boolean }
const networkStateChange = createTypedEvent<Payload>()

const handler = (payload: Payload) => console.log(payload)
networkStateChange.sub(handler)
networkStateChange.dispatch({ready: true})
networkStateChange.unsub(handler)

>>> { ready: true }

Simplified unsubscribe:

import { createTypedEvent } from '@misaka17535/create-typed-event'

const misakaStateChange = createTypedEvent<{ selfDestructionInProgress: boolean }>()
const unsub = misakaStateChange.sub((payload) => console.log(payload)) // returns unsub function without defining handler outside
misakaStateChange.dispatch({selfDestructionInProgress: true})
unsub()

>>> { selfDestructionInProgress: true }

Create an "event bus":

import { createTypedEvent } from '@misaka17535/create-typed-event'

export const eventBus = {
    alice: createTypedEvent(),
    bob: createTypedEvent<{ isE2eEncryption: boolean }>()
}
eventBus.bob.dispatch({isE2eEncryption: true})

Supports react hook:

import { createTypedEventMemorized } from '@misaka17535/create-typed-event/react'
const marketPriceUpdateEvent = createTypedEventMemorized<number>();

import { useTypedEventValue } from '@misaka17535/create-typed-event/react'
const [marketPrice, setMarketPrice, marketPriceRef] = useTypedEventValue(marketPriceUpdateEvent);

API

import { createTypedEvent, type TypedEvent } from '@misaka17535/create-typed-event'

• type TypedEvent<Payload>

  • The type that "createTypedEvent" returns.

• createTypedEvent<Payload>(dispatchLastValueOnSubscribe?: boolean): TypedEvent<Payload> Create a new event unit.

  • Parameter
    • dispatchLastValueOnSubscribe optional, default to false.
      If dispatchLastValueOnSubscribe is true, it will dispatch the last value to new subscribers.
  • Returns an object with the following:
    • sub(callback: (payload: Payload) => void): () => void
      Subscribe to event. Returns an unsub method that does not require original callback.
    • unsub(callback: (payload: Payload) => void): void Unsubscribe from event with the original callback.
    • dispatch(payload: Payload): void
      Dispatch an event with the given payload.
    • once(callback: (payload: Payload) => void): () => void
      Subscribe to event, but only once. Returns an unsub method that does not require original callback.
    • get value(): Payload | undefined
      A getter to get the current value of the event.

import { useTypedEvent, createTypedEventMemorized } from '@misaka17535/create-typed-event/react'

• useTypedEvent(event: TypedEvent): HybridState Use typed event as a React state.
  • Returns a tuple of:
    • value: Payload | undefined
      The current value of the event.
    • setValue: (payload: Payload) => void
      A function to set the value of the event.
    • ref: React.MutableRefObject<Payload | undefined>
      A ref that holds the current value of the event, useful for accessing the latest value in effects or callbacks.
• createTypedEventMemorized<Payload>(dispatchLastValueOnSubscribe?: boolean) Create TypedEvent within react component. Parameters and returns are the same as createTypedEvent.