@nextcloud/event-bus - npm Package Compare versions

Comparing version 3.2.0 to 3.3.0

dist/Event.d.ts

 export type Event = object | number | string | boolean | null | undefined;
+/**
+ * Generic events mapping, fallback if no explicit types events are defined
+ * @see NextcloudEvents
+ */
+export type GenericEvents = Record<string | symbol, Event>;
+/**
+ * Nextcloud EventBus events
+ * This can be extended to allow typing of events like:
+ * @example
+ * ```ts
+ * // event-bus.d.ts
+ * // Extend the Nextcloud events interface for your custom event
+ * declare module '@nextcloud/event-bus' {
+ *     export interface NextcloudEvents {
+ *         // mapping of 'event name' => 'event type'
+ *         'my-event': { foo: number, bar: boolean }
+ *     }
+ * }
+ * export {}
+ *
+ * // your-code.ts
+ * import { subscribe } from '@nextcloud/event-bus'
+ * // Here the type of 'params' is infered automatically
+ * subscribe('my-event', (params) => { console.debug(params.foo, params.bar) })
+ * ```
+ */
+export interface NextcloudEvents {
+    [eventName: string | symbol]: Event;
+}

dist/EventBus.d.ts

@@ -1,8 +0,28 @@
-import { Event } from "./Event";
-import { EventHandler } from "./EventHandler";
-export interface EventBus {
+import { GenericEvents, NextcloudEvents } from './Event';
+import { EventHandler } from './EventHandler';
+
+export interface EventBus<E extends GenericEvents = NextcloudEvents> {
+    /**
+     * Get the version of this event bus instance
+     * This is used for compatibility checking
+     */
     getVersion(): string;
-    subscribe(name: string, handler: EventHandler): void;
-    unsubscribe(name: string, handler: EventHandler): void;
-    emit(name: string, event: Event): void;
+    /**
+     * Subscribe the event bus
+     * @param name Name of the event to subscribe
+     * @param handler Handler ivoken when receiving the event
+     */
+    subscribe<EventName extends keyof E>(name: EventName, handler: EventHandler<E[EventName]>): void;
+    /**
+     * Unsubscribe a handler on one event from the event bus
+     * @param name Name of the event to unsubscribe
+     * @param handler Handler to unsubscribe
+     */
+    unsubscribe<EventName extends keyof E>(name: EventName, handler: EventHandler<E[EventName]>): void;
+    /**
+     * Emit an event on the event bus
+     * @param name Name of the event to emit
+     * @param event Event payload to emit
+     */
+    emit<EventName extends keyof E>(name: EventName, event: E[EventName]): void;
 }

dist/EventHandler.d.ts

@@ -1,4 +0,5 @@
-import { Event } from "./Event";
-export interface EventHandler {
-    (event: Event): void;
+import { Event } from './Event';
+
+export interface EventHandler<T extends Event> {
+    (event: T): void;
 }

dist/index.d.ts

@@ -1,12 +0,16 @@
-import { EventHandler } from "./EventHandler";
-import { Event } from "./Event";
+import { EventBus } from './EventBus';
+import { EventHandler } from './EventHandler';
+import { NextcloudEvents } from './Event';
+
 export type { EventBus } from './EventBus';
-export type { EventHandler } from "./EventHandler";
-export type { Event } from "./Event";
-export { ProxyBus } from "./ProxyBus";
-export { SimpleBus } from "./SimpleBus";
+export type { EventHandler } from './EventHandler';
+export type { Event, NextcloudEvents } from './Event';
+export { ProxyBus } from './ProxyBus';
+export { SimpleBus } from './SimpleBus';
 declare global {
     interface Window {
-        OC: any;
-        _nc_event_bus: any;
+        OC: {
+            _eventBus?: EventBus;
+        };
+        _nc_event_bus?: EventBus;
     }
@@ -20,3 +24,3 @@ }
  */
-export declare function subscribe(name: string, handler: EventHandler): void;
+export declare function subscribe<K extends keyof NextcloudEvents>(name: K, handler: EventHandler<NextcloudEvents[K]>): void;
 /**
@@ -30,3 +34,3 @@ * Unregister a previously registered event listener
  */
-export declare function unsubscribe(name: string, handler: EventHandler): void;
+export declare function unsubscribe<K extends keyof NextcloudEvents>(name: K, handler: EventHandler<NextcloudEvents[K]>): void;
 /**
@@ -38,2 +42,2 @@ * Emit an event
  */
-export declare function emit(name: string, event: Event): void;
+export declare function emit<K extends keyof NextcloudEvents>(name: K, event: NextcloudEvents[K]): void;

dist/ProxyBus.d.ts

@@ -1,11 +0,12 @@
-import { Event } from "./Event.js";
-import { EventBus } from "./EventBus.js";
-import { EventHandler } from "./EventHandler.js";
-export declare class ProxyBus implements EventBus {
+import { GenericEvents, NextcloudEvents } from './Event.js';
+import { EventBus } from './EventBus.js';
+import { EventHandler } from './EventHandler.js';
+
+export declare class ProxyBus<E extends GenericEvents = NextcloudEvents> implements EventBus<E> {
     private bus;
-    constructor(bus: EventBus);
+    constructor(bus: EventBus<E>);
     getVersion(): string;
-    subscribe(name: string, handler: EventHandler): void;
-    unsubscribe(name: string, handler: EventHandler): void;
-    emit(name: string, event: Event): void;
+    subscribe<EventName extends keyof E>(name: EventName, handler: EventHandler<E[EventName]>): void;
+    unsubscribe<EventName extends keyof E>(name: EventName, handler: EventHandler<E[EventName]>): void;
+    emit<EventName extends keyof E>(name: EventName, event: E[EventName]): void;
 }

dist/SimpleBus.d.ts

@@ -1,10 +0,11 @@
-import { Event } from "./Event.js";
-import { EventBus } from "./EventBus.js";
-import { EventHandler } from "./EventHandler.js";
-export declare class SimpleBus implements EventBus {
+import { GenericEvents, NextcloudEvents } from './Event.js';
+import { EventBus } from './EventBus.js';
+import { EventHandler } from './EventHandler.js';
+
+export declare class SimpleBus<E extends GenericEvents = NextcloudEvents> implements EventBus<E> {
     private handlers;
     getVersion(): string;
-    subscribe(name: string, handler: EventHandler): void;
-    unsubscribe(name: string, handler: EventHandler): void;
-    emit(name: string, event: Event): void;
+    subscribe<EventName extends keyof E>(name: EventName, handler: EventHandler<E[EventName]>): void;
+    unsubscribe<EventName extends keyof E>(name: EventName, handler: EventHandler<E[EventName]>): void;
+    emit<EventName extends keyof E>(name: EventName, event: E[EventName]): void;
 }

package.json

 {
   "name": "@nextcloud/event-bus",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "A simple event bus to communicate between Nextcloud components.",
-  "main": "dist/index.cjs",
-  "types": "dist/index.d.ts",
+  "keywords": [
+    "nextcloud"
+  ],
+  "homepage": "https://github.com/nextcloud/nextcloud-event-bus#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nextcloud/nextcloud-event-bus"
+  },
+  "license": "GPL-3.0-or-later",
+  "author": "Christoph Wurst",
+  "type": "module",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.cjs"
     }
   },
+  "main": "dist/index.cjs",
+  "types": "dist/index.d.ts",
   "files": [
@@ -18,36 +29,32 @@ "dist/"
   "scripts": {
-    "build": "rollup --config rollup.config.mjs",
+    "build": "vite --mode production build",
     "build:doc": "typedoc --out dist/doc lib/index.ts && touch dist/doc/.nojekyll",
-    "check-types": "tsc --noEmit",
-    "dev": "rollup --config rollup.config.mjs --watch",
-    "test": "jest",
-    "test:coverage": "jest --coverage",
-    "test:watch": "jest --watchAll"
+    "dev": "vite --mode development build --watch",
+    "format": "prettier --check .",
+    "format:fix": "prettier --write .",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest run --watch"
   },
-  "keywords": [
-    "nextcloud"
-  ],
-  "homepage": "https://github.com/nextcloud/nextcloud-event-bus#readme",
-  "author": "Christoph Wurst",
-  "license": "GPL-3.0-or-later",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/nextcloud/nextcloud-event-bus"
-  },
+  "prettier": "@nextcloud/prettier-config",
   "dependencies": {
-    "@types/node": "^20.12.7",
-    "semver": "^7.6.0"
+    "@types/node": "^20.12.11",
+    "semver": "^7.6.2"
   },
   "devDependencies": {
-    "@rollup/plugin-replace": "^5.0.5",
-    "@rollup/plugin-typescript": "^11.1.6",
+    "@nextcloud/eslint-config": "^8.3.0",
+    "@nextcloud/prettier-config": "^1.1.0",
+    "@nextcloud/vite-config": "^1.2.3",
     "@types/semver": "^7.5.8",
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
-    "rollup": "^4.16.0",
-    "ts-jest": "^29.1.2",
-    "ts-node": "^10.9.2",
-    "tslib": "^2.6.2",
+    "@vitest/coverage-v8": "^1.6.0",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "happy-dom": "^14.10.1",
+    "prettier": "^3.2.5",
     "typedoc": "^0.25.13",
-    "typescript": "^5.4.5"
+    "typescript": "^5.4.5",
+    "vite": "^5.2.11",
+    "vitest": "^1.6.0"
   },
@@ -54,0 +61,0 @@ "engines": {

README.md

 # @nextcloud/event-bus
+
 [![Build Status](https://img.shields.io/github/actions/workflow/status/nextcloud/nextcloud-event-bus/node.yml?branch=master)](https://github.com/nextcloud/nextcloud-event-bus/actions/workflows/node.yml?query=branch%3Amaster) [![Code coverage](https://img.shields.io/codecov/c/gh/nextcloud/nextcloud-event-bus/master)](https://app.codecov.io/gh/nextcloud/nextcloud-event-bus) [![npm](https://img.shields.io/npm/v/@nextcloud/event-bus.svg)](https://www.npmjs.com/package/@nextcloud/event-bus)
@@ -22,3 +23,3 @@ [![Documentation](https://img.shields.io/badge/Documentation-online-brightgreen)](https://nextcloud.github.io/nextcloud-event-bus/)
 
-const h = e => console.info(e)
+const h = (e) => console.info(e)
 
@@ -29,3 +30,3 @@ subscribe('a', h)
 emit('a', {
-    data: 123,
+	data: 123,
 })
@@ -37,2 +38,30 @@
 
+### Typed events
+
+It is also possible to type events, which allows type infering on the event-bus methods like `emit`, `subscribe` and `unsubscribe`.
+To register new events, simply extend the `NextcloudEvents` interface:
+
+1. Create a file like `event-bus.d.ts`:
+
+```ts
+declare module '@nextcloud/event-bus' {
+	interface NextcloudEvents {
+		'example-app:awesomeness:increased': { level: number }
+	}
+}
+
+export {}
+```
+
+2. Now if you use any of the event bus functions, the parameters will automatically be typed correctly:
+
+```ts
+import { subscribe } from '@nextcloud/event-bus'
+
+subscribe('example-app:awesomeness:increased', (event) => {
+	// "event" automatically infers type { level: number}
+	console.log(event.level)
+})
+```
+
 ## Naming convention
@@ -46,9 +75,9 @@
 
-- `nextcloud:unified-search:closed`
-- `files:node:uploading`
-- `files:node:uploaded`
-- `files:node:deleted`
-- `contacts:contact:deleted`
-- `calendar:event:created`
-- `forms:answer:updated`
+-   `nextcloud:unified-search:closed`
+-   `files:node:uploading`
+-   `files:node:uploaded`
+-   `files:node:deleted`
+-   `contacts:contact:deleted`
+-   `calendar:event:created`
+-   `forms:answer:updated`
 
@@ -66,3 +95,3 @@ ## Development
 
-- [Node 16 or higher](https://nodejs.org/en/download/)
-- [NPM 8 or higher](https://www.npmjs.com/package/npm)
+-   [Node 20 or higher](https://nodejs.org/en/download/)
+-   [NPM 10 or higher](https://www.npmjs.com/package/npm)

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Unidentified License

License

(Experimental) Something that seems like a license was found, but its contents could not be matched with a known license.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

63270

increased by1.07%

Number of package files

14

increased by7.69%

Lines of code

322

increased by11.81%

Number of lines in readme file

93

increased by45.31%

Is type module

Yes

Worsened metrics

Dev dependency count

13

increased by18.18%

Number of low license alerts

4

increased by33.33%

Dependency changes

• Updated@types/node@^20.12.11

• Updatedsemver@^7.6.2