diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 2fae542..188fa57 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -4,22 +4,40 @@ import { defineConfig } from "vitepress"; export default defineConfig({ title: "ESMitter", description: - "ESMitter is a rewrite of the popular EventEmitter3 with a focus on modern tooling, TypeScript, and EcmaScript module syntax.", + "ESMitter is a fork of the popular EventEmitter3 with a focus on EcmaScript module syntax, TypeScript and modern tooling.", base: "/esm-itter/", themeConfig: { // https://vitepress.dev/reference/default-theme-config nav: [ { text: "Home", link: "/" }, - { text: "Guide", link: "/guide" }, + { text: "Guide", link: "/installation" }, { text: "API Reference", link: "/api" }, ], sidebar: [ { - text: "Examples", + text: "Guide", items: [ - { text: "Markdown Examples", link: "/markdown-examples" }, - { text: "Runtime API Examples", link: "/api-examples" }, + { text: "Installation", link: "/installation" }, + { text: "Setup", link: "/setup" }, + { text: "Usage", link: "/usage" }, + { text: "Context", link: "/context" }, + ], + }, + { + text: "API Reference", + items: [ + { text: "Types", link: "/api/types" }, + { text: "addListener()", link: "/api/addListener" }, + { text: "emit()", link: "/api/emit" }, + { text: "eventNames()", link: "/api/eventNames" }, + { text: "listenerCount()", link: "/api/listenerCount" }, + { text: "listeners()", link: "/api/listeners" }, + { text: "off()", link: "/api/off" }, + { text: "on()", link: "/api/on" }, + { text: "once()", link: "/api/once" }, + { text: "removeAllListeners()", link: "/api/removeAllListeners" }, + { text: "removeListener()", link: "/api/removeListener" }, ], }, ], diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..f54e4d4 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,3 @@ +# API Reference + +TBD \ No newline at end of file diff --git a/docs/api/addListener.md b/docs/api/addListener.md new file mode 100644 index 0000000..57552cb --- /dev/null +++ b/docs/api/addListener.md @@ -0,0 +1,19 @@ +# addListener() + +```typescript +instance.addListener('foo', () => { /* [...] */ }) +``` + +## Parameters + +| Parameter | Type | Default | Description | +| --------- | ---- | ------- | ----------- | +| event | string \| symbol | | The event name. Expects an [ESMitterEventName](/api/types#esmittereventname). | +| fn | unknown | | The function that will be called then the event is emitted. | +| context | unknown | undefined | The [context](/context) to invoke the listener with. | +| once | boolean | false | Specify if the listener is a one-time listener. | + +## on() + +The [`on()`](/api/on) method is almost an alias of `addListener()`, the only exception being the +missing `once` parameter. For this, use [`once()`](/api/once) instead. \ No newline at end of file diff --git a/docs/api/emit.md b/docs/api/emit.md new file mode 100644 index 0000000..449ea23 --- /dev/null +++ b/docs/api/emit.md @@ -0,0 +1,3 @@ +# emit() + +TBD \ No newline at end of file diff --git a/docs/api/eventNames.md b/docs/api/eventNames.md new file mode 100644 index 0000000..bb5310c --- /dev/null +++ b/docs/api/eventNames.md @@ -0,0 +1,3 @@ +# eventNames() + +TBD \ No newline at end of file diff --git a/docs/api/listenerCount.md b/docs/api/listenerCount.md new file mode 100644 index 0000000..8cd7249 --- /dev/null +++ b/docs/api/listenerCount.md @@ -0,0 +1,3 @@ +# listenerCount() + +TBD \ No newline at end of file diff --git a/docs/api/listeners.md b/docs/api/listeners.md new file mode 100644 index 0000000..293d2a1 --- /dev/null +++ b/docs/api/listeners.md @@ -0,0 +1,3 @@ +# listeners() + +TBD \ No newline at end of file diff --git a/docs/api/off.md b/docs/api/off.md new file mode 100644 index 0000000..52a0a7d --- /dev/null +++ b/docs/api/off.md @@ -0,0 +1,3 @@ +# off() + +TBD \ No newline at end of file diff --git a/docs/api/on.md b/docs/api/on.md new file mode 100644 index 0000000..16f453a --- /dev/null +++ b/docs/api/on.md @@ -0,0 +1,3 @@ +# on() + +TBD \ No newline at end of file diff --git a/docs/api/once.md b/docs/api/once.md new file mode 100644 index 0000000..25bdb0f --- /dev/null +++ b/docs/api/once.md @@ -0,0 +1,3 @@ +# once() + +TBD \ No newline at end of file diff --git a/docs/api/removeAllListeners.md b/docs/api/removeAllListeners.md new file mode 100644 index 0000000..b9e8850 --- /dev/null +++ b/docs/api/removeAllListeners.md @@ -0,0 +1,3 @@ +# removeAllListeners() + +TBD \ No newline at end of file diff --git a/docs/api/removeListener.md b/docs/api/removeListener.md new file mode 100644 index 0000000..b27220b --- /dev/null +++ b/docs/api/removeListener.md @@ -0,0 +1,3 @@ +# removeListener() + +TBD \ No newline at end of file diff --git a/docs/api/types.md b/docs/api/types.md new file mode 100644 index 0000000..9fb090c --- /dev/null +++ b/docs/api/types.md @@ -0,0 +1,13 @@ +# Types + +## ESMitterEventName + +TBD + +## ESMitterEvent + +TBD + +## ESMitterEvents + +TBD \ No newline at end of file diff --git a/docs/context.md b/docs/context.md new file mode 100644 index 0000000..23768e7 --- /dev/null +++ b/docs/context.md @@ -0,0 +1,3 @@ +# Context + +TBD \ No newline at end of file diff --git a/docs/guide.md b/docs/guide.md deleted file mode 100644 index 8c0d02f..0000000 --- a/docs/guide.md +++ /dev/null @@ -1 +0,0 @@ -# Guide diff --git a/docs/index.md b/docs/index.md index d519573..aad9c05 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,24 +5,31 @@ layout: home hero: name: "ESMitter" text: "Modern, ESM-only, natively TypeScript event emitter for the browser and Node.js" - tagline: ESMitter is a rewrite of the popular EventEmitter3 with a focus on modern tooling, TypeScript, and EcmaScript module syntax. + tagline: ESMitter is a fork of the popular EventEmitter3 with a focus on EcmaScript module syntax, TypeScript and modern tooling. actions: - theme: brand text: Get Started - link: /get-started + link: /installation - theme: alt text: API Reference link: /api features: - - title: Natively TypeScript - details: Rewritten in TypeScript, ESMitter offers strongly typed event context and listeners. - title: ESM-only details: No CommonJS/UMD/AMD, just a pure EcmaScript module with modern ES6+ syntax. + - title: Natively TypeScript + details: Rewritten in TypeScript, ESMitter offers strongly typed event context and listeners. - title: Great Developer Experience details: The latest tooling, Unit Tests, Code Coverage, Benchmarks and decent documentation. --- -::: warning -This project is currently in alpha stage. +::: warning ALPHA STAGE +This project is currently under development. Initial tests suggests, that it is working properly and +because I want to maintain compatibility with EventEmitter3 and the Node EventEmitter API, **no** +breaking changes are to be expected. However, the unit tests and documentation are unfinished. + +Furthermore, +[initial performance tests](https://github.com/tillsanders/esm-itter/tree/main/benchmarks) show that +this implementation does not match the speed delivered by EventEmitter3. While I don't expect to +surpass EventEmitter3 in performance, I'm hopeful that this can be improved. ::: diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..8024880 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,31 @@ +# Installation + +ESMitter can be installed using your package manager of choice: + +::: code-group + +```sh [npm] +npm install esm-itter +``` + +```sh [yarn] +yarn add esm-itter +``` + +```sh [pnpm] +pnpm add esm-itter +``` + +::: + +## Compatibility + +ESMitter requires Node > v16 or a browser with EcmaScript modules (ESM) support. + +## Import + +ESMitter uses named exports. You can import the base class like this: + +```typescript +import { ESMitter } from 'esm-itter'; +``` diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..b023a50 --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,28 @@ +# Setup + +ESMitter is designed to be used as a parent class, so all the relevant methods will be available as +part of your own class. If you're looking for an event system that is standalone and works without +classes, you might want to look at [Mitt](https://github.com/developit/mitt). + +```typescript +import { ESMitter } from 'esm-itter'; + +class MyClass extends ESMitter {} +``` + +Since ESMitter is embracing TypeScript, we need to provide a list of known events as a generic type +to the ESMitter class: + +```typescript +import { ESMitter, type ESMitterEvent } from "esm-itter"; + +class MyClass extends ESMitter<{ + 'success': ESMitterEvent<[{ foo: string, bar: string }]>; + 'error': ESMitterEvent<[number, string]>; +}> {} +``` + +In the example above, we have now added the ESMitter event system with all it's logic and methods to +our own class (`MyClass`). We have also provided a list of events that we can emit: one is named +`'success'` and it's payload will return an object. The other event is named `'error'` and it's +payload will contain a number as the first parameter and a string as the second. \ No newline at end of file diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..169979b --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,59 @@ +# Usage + +In the [Setup](/esm-itter/setup), we've added two events to our class (`MyClass`). We're now ready +to attach event listeners and emit events. + +## Adding Listeners + +Listeners can be attached using the `on()`, `once()` and `addListener()` methods: + +```typescript{10-17} +import { ESMitter, type ESMitterEvent } from "esm-itter"; + +class MyClass extends ESMitter<{ + 'success': ESMitterEvent<[{ foo: string, bar: string }]>; + 'error': ESMitterEvent<[number, string]>; +}> {} + +const instance = MyClass(); + +// Attach event listener using on() +instance.on('success', ({ foo, bar }) => { /* [...] */ }) + +// Attach event listener using addListener() +instance.addListener('success', ({ foo, bar }) => { /* [...] */ }) + +// Attach event listener using once() +instance.once('success', ({ foo, bar }) => { /* [...] */ }) +``` + +Note that `on()` is merely an alias for `addListener()` and `once()` will make sure a listener is +only called once and the discarded. + +The parameters passed to the listener are typed according to the list of events we provided to the +ESMitter class. + +## Removing Listeners + +Listeners can be removed using the `off()`, `removeListener()` and `removeAllListeners()` methods: + +```typescript +// Remove all listeners for the 'success' event using off() +instance.off('success') + +// Remove all listeners for the 'success' event using removeListener() +instance.removeListener('success') + +// Remove all listeners for the 'success' event using removeAllListeners() +instance.removeAllListeners('success') + +// Remove all listeners for all events (like a reset) using removeAllListeners() +instance.removeAllListeners() + +// Remove a specific listener using off() and referencing the listener itself +const listener = ({ foo, bar }) => { /* [...] */ }; +instance.on('success', listener); +instance.off('success', listener); +``` + +Note that `off()` (like `on()`, respectively) is merely an alias for `removeListener()`. \ No newline at end of file diff --git a/package.json b/package.json index a2ae76c..3baf114 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "esm-itter", "version": "0.2.0", - "description": "ESMitter is an event emitter compatible with Node.js and modern browsers. It is a fork of EventEmitter3, but natively TypeScript, ESM-only and with more modern tooling.", + "description": "ESMitter is a fork of the popular EventEmitter3 with a focus on EcmaScript module syntax, TypeScript and modern tooling.", "type": "module", "exports": { ".": {