Events

NPM | GitHub

npm install @civet/events

The events module provides advanced event handling functionality.

The DataProvider already has basic support for handling events. However, it is limited to updating all subscribers of a specific resource. If you need more advanced event handling, this is the place to go.

ConfigContext

React context for providing shared configuration to event components.

Context

Name	Type	Description
eventReceiver	EventReceiver

Related

<ConfigProvider>, <ConfigConsumer>, useConfigContext

<ConfigProvider>

Context provider for the ConfigContext.

Usage

<ConfigProvider eventReceiver={receiver}>...</ConfigProvider>

Import

import { ConfigProvider } from "@civet/events";

Props

Name	Type	Description
eventReceiver	EventReceiver

Related

ConfigContext, <ConfigConsumer>, useConfigContext

<ConfigConsumer>

Context consumer for the ConfigContext.

Usage

<ConfigConsumer>
  {(context) => ...}
</ConfigConsumer>

Import

import { ConfigConsumer } from "@civet/events";

Related

ConfigContext, <ConfigProvider>, useConfigContext

useConfigContext

Context consumer for the ConfigContext.

Usage

const context = useConfigContext();

Import

import { useConfigContext } from "@civet/events";

Function arguments

None

Return type

Type	Description
object	ConfigContext

Related

ConfigContext, <ConfigProvider>, <ConfigConsumer>

<EventHandler>

Enables automatic updating for a <Resource> component or useResource hook by subscribing to an EventReceiver.

Necessary configuration that is not directly specified is taken from the ConfigContext and ResourceContext.

onEvent can be used to directly access events allowing you to add custom event logic to your components.

There is also a useEventHandler hook available with similar functionality.

Usage

<EventHandler
  onEvent={(event) => {
    console.log("Received", event);
  }}
/>

Import

import { EventHandler } from "@civet/events";

Props

Name	Type	Description
options	object	Options for the EventReceiver
disabled	boolean	Disables the event handler
onEvent	(event: any) => boolean	Callback to filter events and handle your own event logic - if true is returned, the event does not cause the resource to update
onNotify	({ request: string, revision: string }, events: any[]) => void	Provides information on when the resource has been requested to update - events contains the events that lead to the update
resource	object	ResourceContext to be used
eventReceiver	EventReceiver	EventReceiver to be used

Related

useEventHandler

useEventHandler

Enables automatic updating for a <Resource> component or useResource hook by subscribing to an EventReceiver.

Necessary configuration that is not directly specified is taken from the ConfigContext and ResourceContext.

onEvent can be used to directly access events allowing you to add custom event logic to your components.

There is also an <EventHandler> component available with similar functionality.

Usage

useEventHandler({
  resource,
  onEvent: (event) => {
    console.log("Received", event);
  },
});

Import

import { useEventHandler } from "@civet/events";

Function arguments

Name	Type	Description
config	object	Event handler configuration

Event handler configuration

Name	Type	Description
options	object	Options for the EventReceiver
disabled	boolean	Disables the event handler
onEvent	(event: any) => boolean	Callback to filter events and handle your own event logic - if true is returned, the event does not cause the resource to update
onNotify	({ request: string, revision: string }, events: any[]) => void	Provides information on when the resource has been requested to update - events contains the events that lead to the update
resource	object	ResourceContext to be used
eventReceiver	EventReceiver	EventReceiver to be used

Return type

Type	Description
void

Related

<EventHandler>

EventReceiver

Base class for implementing your own EventReceiver.

Usage

class CustomReceiver extends EventReceiver {
  handleSubscribe(resource, options, handler) {
    ...

    const unsubscribe = () => {
      ...
    };
    return unsubscribe;
  }

  ...
}

const receiver = new CustomReceiver();

Import

import { EventReceiver } from "@civet/events";

Class members

Name	Arguments	Return Type	Description
subscribe	resource: Resource | Notifier<[Resource]> | undefined, options: object, handler: (events: any[]) => void	unsubscribe: () => void	Subscribe to events

Abstract members

Name	Arguments	Return Type	Description
handleSubscribe	resource: Notifier<[Resource]>, options: object, handler: (events: any[]) => void	unsubscribe: () => void

Caveats

Abstract functions

The function subscribe internally invokes its corresponding abstract counterpart handleSubscribe and performs generic validation on its parameters and return value. Therefore, you should not override it, but implement the abstract handleSubscribe method instead.

isEventReceiver

Identifies EventReceiver instances.

Usage

const receiver = new EventReceiver();

if (!isEventReceiver(receiver)) {
  throw new Error("Should be an EventReceiver instance");
}

Import

import { isEventReceiver } from "@civet/events";

Function arguments

Name	Type	Description
eventReceiver	any	The element to be checked

Return type

Type	Description
boolean	Whether eventReceiver is an instance of EventReceiver

eventPlugin

Data provider plugin that integrates an event handler into a resource (using a context plugin).

When using this plugin, you can enable events by passing the events prop to your <Resource> component or useResource hook. The events prop can either be a boolean (whether events should be enabled or not) or a Event handler configuration object. resource does not need to be specified, as it is automatically populated.

composeHandlers

Utility for composing multiple event handlers. Invokes each handler from left to right, but stops immediately when a handler returns true.

Usage

const composedHandler = composeHandlers(
  (event) => {
    console.log("Received", event);
  },
  (event) => true,
  (event) => {
    console.log("Never executed");
  }
);

Import

import { composeHandlers } from "@civet/events";

Function arguments

Name	Type	Description
...handlers	(event: any) => boolean	Event handlers

Return type

Type	Description
(event: any) => boolean	Composed handler