LiveEventScope class

Package:
@microsoft/live-share

Object responsible for sending and receiving live share events.

Extends

TypedEventEmitter<IErrorEvent>

Remarks

Live objects send and receive events using an event scope. Event scopes can be restricted to only receive events from clients with specific roles. Any events that are received from clients without an allowed role type will be ignored.

Event scopes are isolated on a per Fluid object basis. That means that two different Fluid objects using the same event names don't have to worry about collisions. Two event scopes within the same Fluid object, however, don't have any isolation. You can use multiple event scopes within the same FLuid object, you just need to be careful that they send different events.

Constructors

LiveEventScope(IRuntimeSignaler, LiveShareRuntime, UserMeetingRole[])

Creates a new LiveEventScope instance.

Properties

allowedRoles

List of roles allowed to send events through this scope.
clientId

The runtimes current client ID. This will be undefined if the client is disconnected.

Inherited Properties

addListener

Alias for emitter.on(eventName, listener).
off

Alias for emitter.removeListener().
on

Adds the listener function to the end of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.

server.on('connection', (stream) => {
  console.log('someone connected!');
});

Returns a reference to the EventEmitter, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The emitter.prependListener() method can be used as an alternative to add the event listener to the beginning of the listeners array.

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
once

Adds a one-time listener function for the event named eventName. The next time eventName is triggered, this listener is removed and then invoked.

server.once('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

Returns a reference to the EventEmitter, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The emitter.prependOnceListener() method can be used as an alternative to add the event listener to the beginning of the listeners array.

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
prependListener

Adds the listener function to the beginning of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.

server.prependListener('connection', (stream) => {
  console.log('someone connected!');
});

Returns a reference to the EventEmitter, so that calls can be chained.
prependOnceListener

Adds a one-time listener function for the event named eventName to the beginning of the listeners array. The next time eventName is triggered, this listener is removed, and then invoked.

server.prependOnceListener('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

Returns a reference to the EventEmitter, so that calls can be chained.
removeListener

Removes the specified listener from the listener array for the event named eventName.

const callback = (stream) => {
  console.log('someone connected!');
};
server.on('connection', callback);
// ...
server.removeListener('connection', callback);

removeListener() will remove, at most, one instance of a listener from the listener array. If any single listener has been added multiple times to the listener array for the specified eventName, then removeListener() must be called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order. This implies that any removeListener() or removeAllListeners() calls after emitting and before the last listener finishes execution will not remove them from emit() in progress. Subsequent events behave as expected.

import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A

Because listeners are managed using an internal array, calling this will change the position indexes of any listener registered after the listener being removed. This will not impact the order in which listeners are called, but it means that any copies of the listener array as returned by the emitter.listeners() method will need to be recreated.

When a single function has been added as a handler multiple times for a single event (as in the example below), removeListener() will remove the most recently added instance. In the example the once('ping') listener is removed:

import { EventEmitter } from 'node:events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');

Returns a reference to the EventEmitter, so that calls can be chained.

Methods

offEvent<TEvent>(string, LiveEventListener<TEvent>)

Un-registers a listener for a named event.
onEvent<TEvent>(string, LiveEventListener<TEvent>)

Registers a listener for a named event.
sendEvent<TEvent>(string, TEvent)

Sends an event to other event scope instances for the Fluid object.
sendLocalEvent<TEvent>(string, TEvent)

Sends a local only event to local event scope instance for the Fluid object.

Inherited Methods

emit<E>(string | symbol, any[])

Synchronously calls each of the listeners registered for the event named eventName, in the order they were registered, passing the supplied arguments to each.

Returns true if the event had listeners, false otherwise.

import { EventEmitter } from 'node:events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

console.log(myEmitter.listeners('event'));

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// [
//   [Function: firstListener],
//   [Function: secondListener],
//   [Function: thirdListener]
// ]
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
eventNames()

Returns an array listing the events for which the emitter has registered listeners.

import { EventEmitter } from 'node:events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
getMaxListeners()

Returns the current max listener value for the EventEmitter which is either set by emitter.setMaxListeners(n) or defaults to events.defaultMaxListeners.
listenerCount<E>(string | symbol, (args: any[]) => void)

Returns the number of listeners listening for the event named eventName. If listener is provided, it will return how many times the listener is found in the list of the listeners of the event.
listeners<E>(string | symbol)

Returns a copy of the array of listeners for the event named eventName.

server.on('connection', (stream) => {
  console.log('someone connected!');
});
console.log(util.inspect(server.listeners('connection')));
// Prints: [ [Function] ]
rawListeners<E>(string | symbol)

Returns a copy of the array of listeners for the event named eventName, including any wrappers (such as those created by .once()).

import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.once('log', () => console.log('log once'));

// Returns a new Array with a function `onceWrapper` which has a property
// `listener` which contains the original listener bound above
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];

// Logs "log once" to the console and does not unbind the `once` event
logFnWrapper.listener();

// Logs "log once" to the console and removes the listener
logFnWrapper();

emitter.on('log', () => console.log('log persistently'));
// Will return a new Array with a single function bound by `.on()` above
const newListeners = emitter.rawListeners('log');

// Logs "log persistently" twice
newListeners[0]();
emitter.emit('log');
removeAllListeners<E>(string | symbol)

Removes all listeners, or those of the specified eventName.

It is bad practice to remove listeners added elsewhere in the code, particularly when the EventEmitter instance was created by some other component or module (e.g. sockets or file streams).

Returns a reference to the EventEmitter, so that calls can be chained.
setMaxListeners(number)

By default EventEmitters will print a warning if more than 10 listeners are added for a particular event. This is a useful default that helps finding memory leaks. The emitter.setMaxListeners() method allows the limit to be modified for this specific EventEmitter instance. The value can be set to Infinity (or 0) to indicate an unlimited number of listeners.

Returns a reference to the EventEmitter, so that calls can be chained.
[captureRejectionSymbol](Error, string | symbol, any[])

The Symbol.for('nodejs.rejection') method is called in case a promise rejection happens when emitting an event and captureRejections is enabled on the emitter. It is possible to use events.captureRejectionSymbol in place of Symbol.for('nodejs.rejection').

import { EventEmitter, captureRejectionSymbol } from 'node:events';

class MyClass extends EventEmitter {
  constructor() {
    super({ captureRejections: true });
  }

  [captureRejectionSymbol](err, event, ...args) {
    console.log('rejection happened for', event, 'with', err, ...args);
    this.destroy(err);
  }

  destroy(err) {
    // Tear the resource down here.
  }
}

Constructor Details

LiveEventScope(IRuntimeSignaler, LiveShareRuntime, UserMeetingRole[])

Creates a new LiveEventScope instance.

new LiveEventScope(runtime: IRuntimeSignaler, _liveRuntime: LiveShareRuntime, allowedRoles?: UserMeetingRole[])

Parameters

runtime
IRuntimeSignaler

A Fluid objects runtime instance, typically this.runtime.

_liveRuntime
LiveShareRuntime
allowedRoles

UserMeetingRole[]

Optional. List of roles allowed to send events using this scope. You should use a second scope if you need mixed permission support.

Property Details

allowedRoles

List of roles allowed to send events through this scope.

UserMeetingRole[] allowedRoles

Property Value

UserMeetingRole[]

clientId

The runtimes current client ID. This will be undefined if the client is disconnected.

string | undefined clientId

Property Value

string | undefined

Inherited Property Details

addListener

Alias for emitter.on(eventName, listener).

addListener: TypedEventTransform<LiveEventScope, IErrorEvent>

Property Value

TypedEventTransform<LiveEventScope, IErrorEvent>

Inherited From TypedEventEmitter.addListener

off

Alias for emitter.removeListener().

off: TypedEventTransform<LiveEventScope, IErrorEvent>

Property Value

TypedEventTransform<LiveEventScope, IErrorEvent>

Inherited From TypedEventEmitter.off

on

Adds the listener function to the end of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.

server.on('connection', (stream) => {
  console.log('someone connected!');
});

Returns a reference to the EventEmitter, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The emitter.prependListener() method can be used as an alternative to add the event listener to the beginning of the listeners array.

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a

on: TypedEventTransform<LiveEventScope, IErrorEvent>

Property Value

TypedEventTransform<LiveEventScope, IErrorEvent>

Inherited From TypedEventEmitter.on

once

Adds a one-time listener function for the event named eventName. The next time eventName is triggered, this listener is removed and then invoked.

server.once('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

Returns a reference to the EventEmitter, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The emitter.prependOnceListener() method can be used as an alternative to add the event listener to the beginning of the listeners array.

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a

once: TypedEventTransform<LiveEventScope, IErrorEvent>

Property Value

TypedEventTransform<LiveEventScope, IErrorEvent>

Inherited From TypedEventEmitter.once

prependListener

Adds the listener function to the beginning of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.

server.prependListener('connection', (stream) => {
  console.log('someone connected!');
});

Returns a reference to the EventEmitter, so that calls can be chained.

prependListener: TypedEventTransform<LiveEventScope, IErrorEvent>

Property Value

TypedEventTransform<LiveEventScope, IErrorEvent>

Inherited From TypedEventEmitter.prependListener

prependOnceListener

Adds a one-time listener function for the event named eventName to the beginning of the listeners array. The next time eventName is triggered, this listener is removed, and then invoked.

server.prependOnceListener('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

Returns a reference to the EventEmitter, so that calls can be chained.

prependOnceListener: TypedEventTransform<LiveEventScope, IErrorEvent>

Property Value

TypedEventTransform<LiveEventScope, IErrorEvent>

Inherited From TypedEventEmitter.prependOnceListener

removeListener

Removes the specified listener from the listener array for the event named eventName.

const callback = (stream) => {
  console.log('someone connected!');
};
server.on('connection', callback);
// ...
server.removeListener('connection', callback);

removeListener() will remove, at most, one instance of a listener from the listener array. If any single listener has been added multiple times to the listener array for the specified eventName, then removeListener() must be called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order. This implies that any removeListener() or removeAllListeners() calls after emitting and before the last listener finishes execution will not remove them from emit() in progress. Subsequent events behave as expected.

import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A

Because listeners are managed using an internal array, calling this will change the position indexes of any listener registered after the listener being removed. This will not impact the order in which listeners are called, but it means that any copies of the listener array as returned by the emitter.listeners() method will need to be recreated.

When a single function has been added as a handler multiple times for a single event (as in the example below), removeListener() will remove the most recently added instance. In the example the once('ping') listener is removed:

import { EventEmitter } from 'node:events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');

Returns a reference to the EventEmitter, so that calls can be chained.

removeListener: TypedEventTransform<LiveEventScope, IErrorEvent>

Property Value

TypedEventTransform<LiveEventScope, IErrorEvent>

Inherited From TypedEventEmitter.removeListener

Method Details

offEvent<TEvent>(string, LiveEventListener<TEvent>)

Un-registers a listener for a named event.

function offEvent<TEvent>(eventName: string, listener: LiveEventListener<TEvent>): this

Parameters

eventName

string

Name of event to un-register.

listener

LiveEventListener<TEvent>

Function that was originally passed to onEvent().

Returns

this

onEvent<TEvent>(string, LiveEventListener<TEvent>)

Registers a listener for a named event.

function onEvent<TEvent>(eventName: string, listener: LiveEventListener<TEvent>): this

Parameters

eventName

string

Name of event to listen for.

listener

LiveEventListener<TEvent>

Function to call when the named event is sent or received.

Returns

this

sendEvent<TEvent>(string, TEvent)

Sends an event to other event scope instances for the Fluid object.

function sendEvent<TEvent>(eventName: string, evt: TEvent): Promise<ILiveEvent<TEvent>>

Parameters

eventName

string

Name of the event to send.

evt

TEvent

Optional. Partial event object to send. The ILiveEvent.name, ILiveEvent.timestamp, and ILiveEvent.clientId fields will be automatically populated prior to sending.

Returns

Promise<ILiveEvent<TEvent>>

The full event, including ILiveEvent.name, ILiveEvent.timestamp, and ILiveEvent.clientId fields if known.

sendLocalEvent<TEvent>(string, TEvent)

Sends a local only event to local event scope instance for the Fluid object.

function sendLocalEvent<TEvent>(eventName: string, evt: TEvent): Promise<ILiveEvent<TEvent>>

Parameters

eventName

string

Name of the event to send.

evt

TEvent

Optional. Partial event object to send. The ILiveEvent.name, ILiveEvent.timestamp, and ILiveEvent.clientId fields will be automatically populated prior to sending.

Returns

Promise<ILiveEvent<TEvent>>

The full event, including ILiveEvent.name, ILiveEvent.timestamp, and ILiveEvent.clientId fields if known.

Inherited Method Details

emit<E>(string | symbol, any[])

Synchronously calls each of the listeners registered for the event named eventName, in the order they were registered, passing the supplied arguments to each.

Returns true if the event had listeners, false otherwise.

import { EventEmitter } from 'node:events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

console.log(myEmitter.listeners('event'));

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// [
//   [Function: firstListener],
//   [Function: secondListener],
//   [Function: thirdListener]
// ]
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener

function emit<E>(eventName: string | symbol, args: any[]): boolean

Parameters

eventName

string | symbol

args

any[]

Returns

boolean

Inherited From TypedEventEmitter.emit

eventNames()

Returns an array listing the events for which the emitter has registered listeners.

import { EventEmitter } from 'node:events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]

function eventNames(): (string | symbol)[]

Returns

(string | symbol)[]

Inherited From TypedEventEmitter.eventNames

getMaxListeners()

Returns the current max listener value for the EventEmitter which is either set by emitter.setMaxListeners(n) or defaults to events.defaultMaxListeners.

function getMaxListeners(): number

Returns

number

Inherited From TypedEventEmitter.getMaxListeners

listenerCount<E>(string | symbol, (args: any[]) => void)

Returns the number of listeners listening for the event named eventName. If listener is provided, it will return how many times the listener is found in the list of the listeners of the event.

function listenerCount<E>(eventName: string | symbol, listener?: (args: any[]) => void): number

Parameters

eventName

string | symbol

The name of the event being listened for

listener

(args: any[]) => void

The event handler function

Returns

number

Inherited From TypedEventEmitter.listenerCount

listeners<E>(string | symbol)

Returns a copy of the array of listeners for the event named eventName.

server.on('connection', (stream) => {
  console.log('someone connected!');
});
console.log(util.inspect(server.listeners('connection')));
// Prints: [ [Function] ]

function listeners<E>(eventName: string | symbol): (args: any[]) => void[]

Parameters

eventName

string | symbol

Returns

(args: any[]) => void[]

Inherited From TypedEventEmitter.listeners

rawListeners<E>(string | symbol)

Returns a copy of the array of listeners for the event named eventName, including any wrappers (such as those created by .once()).

import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.once('log', () => console.log('log once'));

// Returns a new Array with a function `onceWrapper` which has a property
// `listener` which contains the original listener bound above
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];

// Logs "log once" to the console and does not unbind the `once` event
logFnWrapper.listener();

// Logs "log once" to the console and removes the listener
logFnWrapper();

emitter.on('log', () => console.log('log persistently'));
// Will return a new Array with a single function bound by `.on()` above
const newListeners = emitter.rawListeners('log');

// Logs "log persistently" twice
newListeners[0]();
emitter.emit('log');

function rawListeners<E>(eventName: string | symbol): (args: any[]) => void[]

Parameters

eventName

string | symbol

Returns

(args: any[]) => void[]

Inherited From TypedEventEmitter.rawListeners

removeAllListeners<E>(string | symbol)

Removes all listeners, or those of the specified eventName.

It is bad practice to remove listeners added elsewhere in the code, particularly when the EventEmitter instance was created by some other component or module (e.g. sockets or file streams).

Returns a reference to the EventEmitter, so that calls can be chained.

function removeAllListeners<E>(eventName?: string | symbol): this

Parameters

eventName

string | symbol

Returns

this

Inherited From TypedEventEmitter.removeAllListeners

setMaxListeners(number)

By default EventEmitters will print a warning if more than 10 listeners are added for a particular event. This is a useful default that helps finding memory leaks. The emitter.setMaxListeners() method allows the limit to be modified for this specific EventEmitter instance. The value can be set to Infinity (or 0) to indicate an unlimited number of listeners.

Returns a reference to the EventEmitter, so that calls can be chained.

function setMaxListeners(n: number): this

Parameters

n

number

Returns

this

Inherited From TypedEventEmitter.setMaxListeners

[captureRejectionSymbol](Error, string | symbol, any[])

The Symbol.for('nodejs.rejection') method is called in case a promise rejection happens when emitting an event and captureRejections is enabled on the emitter. It is possible to use events.captureRejectionSymbol in place of Symbol.for('nodejs.rejection').

import { EventEmitter, captureRejectionSymbol } from 'node:events';

class MyClass extends EventEmitter {
  constructor() {
    super({ captureRejections: true });
  }

  [captureRejectionSymbol](err, event, ...args) {
    console.log('rejection happened for', event, 'with', err, ...args);
    this.destroy(err);
  }

  destroy(err) {
    // Tear the resource down here.
  }
}

function [captureRejectionSymbol](error: Error, event: string | symbol, args: any[])

Parameters

error

Error

event

string | symbol

args

any[]

Inherited From TypedEventEmitter.[captureRejectionSymbol]