docs: initial guide and structure for api reference

Signed-off-by: Till Sanders <[email protected]>

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" },
         ],
       },
     ],

docs/api.md

@@ -0,0 +1,3 @@
+# API Reference
+
+TBD

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.

docs/api/emit.md

@@ -0,0 +1,3 @@
+# emit()
+
+TBD

docs/api/eventNames.md

@@ -0,0 +1,3 @@
+# eventNames()
+
+TBD

docs/api/listenerCount.md

@@ -0,0 +1,3 @@
+# listenerCount()
+
+TBD

docs/api/listeners.md

@@ -0,0 +1,3 @@
+# listeners()
+
+TBD

docs/api/off.md

@@ -0,0 +1,3 @@
+# off()
+
+TBD

docs/api/on.md

@@ -0,0 +1,3 @@
+# on()
+
+TBD

docs/api/once.md

@@ -0,0 +1,3 @@
+# once()
+
+TBD

docs/api/removeAllListeners.md

@@ -0,0 +1,3 @@
+# removeAllListeners()
+
+TBD

docs/api/removeListener.md

@@ -0,0 +1,3 @@
+# removeListener()
+
+TBD

docs/api/types.md

@@ -0,0 +1,13 @@
+# Types
+
+## ESMitterEventName
+
+TBD
+
+## ESMitterEvent
+
+TBD
+
+## ESMitterEvents
+
+TBD

docs/context.md

@@ -0,0 +1,3 @@
+# Context
+
+TBD

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.
 :::

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';
+```

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.

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()`.

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": {
     ".": {