npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

fsa-emitter

v2.0.0

Published

Emitter using Flux Standard Action

Downloads

7

Readme

FSA Emitter

NPM version NPM downloads

Circle CI Travis CI Codecov Coveralls Status

Greenkeeper Semantic Release

Visual Studio Code Wallaby.js

EventEmitter in FSA style.

When dealing with event, I find myself need to remember the name of the event, and the parameters each event has.

The person who defines the events and the person who consumes the events can be two different person.

This implicit knowledge coupling relies on communication and documentation that are prone to error, and are not convenient.

This library addresses this issue by emitting and consuming events using a standard format, and provides IDE type support so they can be consumed easily.

Best practice

One of the benefits of using events is decoupling. Here is one way to organize your code:

// app.ts
import { doWork } from './doWork'

const emitter = new Emitter()

doWork({ emitter })

// doWork.ts
import { createEvent, Emitter } from 'fsa-emitter'

export const count = createEvent<number>('count')

export function doWork({ emitter }) {
  emitter.emit(count(1, undefined))
}

// in UI
import { count } from './doWork'

emitter.on(count, payload => {
  console.log('payload is typed and is a number: ', payload)
})

Installation

npm install fsa-emitter

Emitter

Emitter uses FluxStandardAction as the standard event format.

Another key difference between Emitter and NodeJS EventEmitter is that Emitter will capture any error thrown in listener and send it to console.error(). This avoid any listener code throws error and break the event emitting logic.

To create event, use one of the helper methods below:

import {
  createEvent,
  createScopedCreateEvent,
  createEventAction,
  createScopedCreateEventAction,
  Emitter
} from 'fsa-emitter'

const count = createEvent<number>('count')

// create scoped event
const createMyModuleEvent = createScopedCreateEvent('myModule')
// `scopedCount` will emit FSA with `type: 'myModule/count'`
const scopedCount = createMyModuleEvent<number>('count')

const add = createAction<
  /* input */ { a: number, b: number },
  /* payload */ number>('add', ({ a, b }) => emit => emit(a + b))

// create scoped action
const createMyModuleAction = createScopedCreateEventAction('myModule')
// `scopedCountAction` will emit FSA with `type: 'myModule/add'`
const scopedAdd = createMyModuleAction<
  /* input */ { a: number, b: number },
  /* payload */ number>('add', ({ a, b }) => emit => emit(a + b))

const emitter = new Emitter()

emitter.emit(count(1, undefined))
emitter.emit(scopedCount(2, undefined))
add(emitter, { a: 1, b: 2 }, undefined)
scopedAdd(emitter, { a: 1, b: 2 }, undefined)

Note that due to https://github.com/Microsoft/TypeScript/issues/12400, you need to supply undefined at where they expect meta.

To consume the event, use one of the following methods:

import { createEvent, Emitter } from 'fsa-emitter'

const count = createEvent<number>('count')
const emitter = new Emitter()

emitter.addListener(count, value => console.info(value))
emitter.on(count, value => console.info(value))

// Will only listen to the event once
emitter.once(count, value => console.info(value))

// line up in queue to listen for the event once
emitter.queue(count, value => console.info(value))

// listen to all events
emitter.onAny(fsa => console.info(fsa.type, fsa.payload))

// listen to any event that does not have a listener
emitter.onMissed(fsa => console.info(fsa.type, fsa.payload))

Command

Command is a simple command pattern that provides a simple way to manage dependencies.

import { Command, createEvent, Emitter } from 'fsa-emitter'

const count = createEvent<{ n: number }>('count')

class CountCommand extends Command {
  run(n: number) {
    while (n) {
      this.emitter.emit(count({ n }, undefined))
      n--
    }
  }
}

const emitter = new Emitter()
const cmd = new CountCommand({ emitter })
cmd(10)
import { Command, createEvent, Emitter } from 'fsa-emitter'

const changeHeight = createEvent<{ height: number }>('changeHeight')
const landed = createEvent('landed')

class FlyCommand extends Command<{ fuel: number }> {
  fuel: number
  height = 0
  run() {
    while (this.fuel > 0) {
      this.height += 100
      this.fuel--
      this.emitter.emit(changeHeight({ height: this.height }, undefined))
    }
    const gliding = setInterval(() => {
      this.height -= 50
      this.emitter.emit(changeHeight({ height: this.height }, undefined))
      if (this.height <= 0) {
        this.emitter.emit(landed(undefined, undefined))
        clearInterval(gliding)
      }
    }, 100)
  }
}

// `fuel` is in the constructor context
const fly = new FlyCommand({ emitter: new Emitter(), fuel: 10 })
fly.run()

TestEmitter

TestEmitter can be used as a drop in replacement as Emitter during test.

The difference between TestEmitter and Emitter is that TestEmitter will not capture errors thrown in listeners. This make it more suitable to use during testing so that you can detect any error thrown during the test.

Also, it provides some additional methods:

listenerCalled(event: TypedEvent | string): boolean

import { TestEmitter, createEvent } from 'fsa-emitter'

const emitter = new TestEmitter()
const count = createEvent<number>('count')
emitter.on(count, () => ({}))
t.false(emitter.listenerCalled(count))

emitter.emit(count(1, undefined))
t.true(emitter.listenerCalled(count))
t.true(emitter.listenerCalled(count.type))

allListenersCalled(): boolean

import { TestEmitter, createEvent } from 'fsa-emitter'

const emitter = new TestEmitter()
const count = createEvent<number>('count')
const bound = createEvent<number>('bound')

emitter.on(count, () => ({}))
emitter.on(bound, () => ({}))

emitter.emit(count(1, undefined))

t.false(emitter.allListenersCalled())

emitter.emit(bound(1, undefined))

t.true(emitter.allListenersCalled())

listenedTo(events: (TypedEvent | string)[] | { [k]: TypedEvent })

import { TestEmitter, createEvent } from 'fsa-emitter'

const emitter = new TestEmitter()
const count = createEvent<number>('count')
const bound = createEvent<number>('bound')

emitter.on(count, () => ({}))

emitter.listenedTo([count]) // true
emitter.listenedTo({ count }) // true
emitter.listenedTo(['count']) // true

emitter.listenedTo([ bound ]) // false
emitter.listenedTo({ bound }) // false
emitter.listenedTo([ 'bound' ]) // false

setupCommandTest(Command, context?)

setupCommandTest() is a simple helper to create a TestEmitter for the command to run with. The same completion support is available as in the Command constructor.

import { Command, createEvent, setupCommandTest } from 'fsa-emitter'

const count = createEvent<{ n: number }>('count')

class CountCommand extends Command {
  ...
}

const { command, emitter } = setupCommandTest(CountCommand)

class FlyCommand extends Command<{ fuel: number }> {
  ...
}

// completion is available for `fuel`
const { command, emitter } = setupCommandTest(FlyCommand, { fuel: 10 })

Contribute

# after fork and clone
npm install

# begin making changes
git checkout -b <branch>
npm run watch

# after making change(s)
git commit -m "<commit message>"
git push

# create PR