grainjs 1.0.1 → 1.1.0

package/dist/cjs/lib/domevent.d.ts

@@ -1,86 +1,106 @@
+import { IDisposable } from './dispose';
+import { DomElementMethod, DomMethod } from './domImpl';
+export type EventName = keyof HTMLElementEventMap;
+export type EventType<E extends EventName | string> = E extends EventName ? HTMLElementEventMap[E] : Event;
+export type EventCB<E extends Event = Event, T extends EventTarget = EventTarget> = (this: void, event: E, elem: T) => void;
 /**
- * domevent provides a way to listen to DOM events, similar to JQuery's `on()` function. Its
- * methods are also exposed via the dom.js module, as `dom.on()`, etc.
- *
- * It is typically used as an argument to the dom() function:
- *
- *    dom('div', dom.on('click', (event, elem) => { ... }));
- *
- * When the div is disposed, the listener is automatically removed.
- *
- * The underlying interface to listen to an event is this:
- *
- *    let listener = dom.onElem(elem, 'click', (event, elem) => { ... });
- *
- * The callback is called with the event and the element to which it was attached. Unlike in
- * JQuery, the callback's return value is ignored. Use event.stopPropagation() and
- * event.preventDefault() explicitly if needed.
+ * Listen to a DOM event, returning the listener object.
+ * ```ts
+ * const listener = dom.onElem(elem, 'click', (event, elem) => { ... });
+ * ```
  *
  * To stop listening:
+ * ```ts
+ * listener.dispose();
+ * ```
+ *
+ * Disposing the listener returned by `onElem()` is the only way to stop listening to an event. You
+ * can use `autoDispose` to stop listening automatically when subscribing in a `Disposable` object:
+ * ```ts
+ * this.autoDispose(domevent.onElem(document, 'mouseup', callback));
+ * ```
+ *
+ * If you need "once" semantics, i.e. to remove the callback on first call, here's a useful pattern:
+ * ```ts
+ * const lis = domevent.onElem(elem, 'mouseup', e => { lis.dispose(); other_work(); });
+ * ```
+ *
+ * @param elem - DOM Element to listen to.
+ * @param eventType - Event type to listen for (e.g. `'click'`).
+ * @param callback - Callback to call as `callback(event, elem)`, where elem is `elem`.
+ * @param options - `useCapture: boolean`: Add the listener in the capture phase. This should very
+ *    rarely be useful (e.g. JQuery doesn't even offer it as an option).
+ * @returns Listener object whose `.dispose()` method will remove the event listener.
+ */
+export declare function onElem<E extends EventName | string, T extends EventTarget>(elem: T, eventType: E, callback: EventCB<EventType<E>, T>, { useCapture }?: {
+    useCapture?: boolean | undefined;
+}): IDisposable;
+/**
+ * Listen to a DOM event. It is typically used as an argument to the `dom()` function:
+ * ```ts
+ * dom('div', dom.on('click', (event, elem) => { ... }));
+ * ```
  *
- *    listener.dispose();
- *
- * Disposing the listener returned by .onElem() is the only way to stop listening to an event. You
- * can use autoDispose to stop listening automatically when subscribing in a Disposable object:
+ * When the div is disposed, the listener is automatically removed.
  *
- *    this.autoDispose(domevent.onElem(document, 'mouseup', callback));
+ * The callback is called with the event and the element to which it was attached. Unlike in, say,
+ * JQuery, the callback's return value is ignored. Use `event.stopPropagation()` and
+ * `event.preventDefault()` explicitly if needed.
  *
  * To listen to descendants of an element matching the given selector (what JQuery calls
- * "delegated events", see http://api.jquery.com/on/):
- *
- *    dom('div', dom.onMatch('.selector', 'click', (event, elem) => { ... }));
- * or
- *    let lis = domevent.onMatchElem(elem, '.selector', 'click', (event, el) => { ... });
+ * "delegated events", see http://api.jquery.com/on/), see [`onMatch`](#onMatch).
  *
- * In this usage, the element passed to the callback will be a DOM element matching the given
- * selector. If there are multiple matches, the callback is only called for the innermost one.
- *
- * If you need to remove the callback on first call, here's a useful pattern:
- *    let lis = domevent.onElem(elem, 'mouseup', e => { lis.dispose(); other_work(); });
- */
-import { IDisposable } from './dispose';
-import { DomElementMethod, DomMethod } from './domImpl';
-export declare type EventName = keyof HTMLElementEventMap;
-export declare type EventType<E extends EventName | string> = E extends EventName ? HTMLElementEventMap[E] : Event;
-export declare type EventCB<E extends Event = Event, T extends EventTarget = EventTarget> = (this: void, event: E, elem: T) => void;
-/**
- * Listen to a DOM event. The `on()` variant takes no `elem` argument, and may be used as an
- * argument to dom() function.
- * @param {DOMElement} elem: DOM Element to listen to.
- * @param {String} eventType: Event type to listen for (e.g. 'click').
- * @param {Function} callback: Callback to call as `callback(event, elem)`, where elem is `elem`.
- * @param [Boolean] options.useCapture: Add the listener in the capture phase. This should very
- *    rarely be useful (e.g. JQuery doesn't even offer it as an option).
- * @returns {Object} Listener object whose .dispose() method will remove the event listener.
+ * @param eventType - Event type to listen for (e.g. `'click'`).
+ * @param callback - Callback to call as `callback(event, elem)`, where `elem` is the element this
+ *    listener is attached to.
+ * @param options - `useCapture?: boolean`: Add the listener in the capture phase.
  */
-export declare function onElem<E extends EventName | string, T extends EventTarget>(elem: T, eventType: E, callback: EventCB<EventType<E>, T>, { useCapture }?: {
-    useCapture?: boolean | undefined;
-}): IDisposable;
 export declare function on<E extends EventName | string, T extends EventTarget>(eventType: E, callback: EventCB<EventType<E>, T>, { useCapture }?: {
     useCapture?: boolean | undefined;
 }): DomMethod<T>;
 /**
- * Listen to a DOM event on descendants of the given elem matching the given selector. The
- * `onMatch()` variant takes no `elem` argument, and may be used as an argument to dom().
- * @param {DOMElement} elem: DOM Element to whose descendants to listen.
- * @param {String} selector: CSS selector string to filter elements that trigger this event.
+ * Listen to a DOM event on descendants of the given elem matching the given selector.
+ *
+ * ```ts
+ * const let lis = domevent.onMatchElem(elem, '.selector', 'click', (event, el) => { ... });
+ * ```
+ *
+ * @param elem - DOM Element to whose descendants to listen.
+ * @param selector - CSS selector string to filter elements that trigger this event.
  *    JQuery calls it "delegated events" (http://api.jquery.com/on/). The callback will only be
  *    called when the event occurs for an element matching the given selector. If there are
  *    multiple elements matching the selector, the callback is only called for the innermost one.
- * @param {String} eventType: Event type to listen for (e.g. 'click').
- * @param {Function} callback: Callback to call as `callback(event, elem)`, where elem is a
+ * @param eventType - Event type to listen for (e.g. 'click').
+ * @param callback - Callback to call as `callback(event, elem)`, where elem is a
  *    descendent of `elem` which matches `selector`.
- * @param [Boolean] options.useCapture: Add the listener in the capture phase. This should very
- *    rarely be useful (e.g. JQuery doesn't even offer it as an option).
- * @returns {Object} Listener object whose .dispose() method will remove the event listener.
+ * @param options - `useCapture?: boolean`: Add the listener in the capture phase.
+ * @returns Listener object whose `.dispose()` method will remove the event listener.
  */
 export declare function onMatchElem(elem: EventTarget, selector: string, eventType: string, callback: EventCB, { useCapture }?: {
     useCapture?: boolean | undefined;
 }): IDisposable;
+/**
+ * Listen to a DOM event on descendants of the given element matching the given selector.
+ *
+ * This is similar to JQuery's [delegated events](https://api.jquery.com/on/#direct-and-delegated-events)
+ *
+ * ```ts
+ * dom('div', dom.onMatch('.selector', 'click', (event, elem) => { ... }));
+ * ```
+ *
+ * In this usage, the element passed to the callback will be a DOM element matching the given
+ * selector. If there are multiple matches, the callback is only called for the innermost one.
+ *
+ * @param selector - CSS selector string to filter elements that trigger this event.
+ * @param eventType - Event type to listen for (e.g. `'click'`).
+ * @param callback - Callback to call as `callback(event, elem)`, where `elem` is an element
+ *    matching `selector`.
+ * @param options - `useCapture?: boolean`: Add the listener in the capture phase.
+ */
 export declare function onMatch(selector: string, eventType: string, callback: EventCB, { useCapture }?: {
     useCapture?: boolean | undefined;
 }): DomElementMethod;
-export declare type KeyEventType = 'keypress' | 'keyup' | 'keydown';
+export type KeyEventType = 'keypress' | 'keyup' | 'keydown';
 export interface IKeyHandlers<T extends HTMLElement = HTMLElement> {
     [key: string]: (this: void, ev: KeyboardEvent, elem: T) => void;
 }
@@ -88,8 +108,6 @@ export interface IKeyHandlers<T extends HTMLElement = HTMLElement> {
  * Listen to key events (typically 'keydown' or 'keypress'), with specified per-key callbacks.
  * Key names are listed at https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values
  *
- * Methods onKeyPress() and onKeyDown() are intended to be used as arguments to dom().
- *
  * By default, handled events are stopped from bubbling with stopPropagation() and
  * preventDefault(). If, however, you register a key with a "$" suffix (i.e. "Enter$" instead of
  * "Enter"), then the event is allowed to bubble normally.
@@ -98,7 +116,7 @@ export interface IKeyHandlers<T extends HTMLElement = HTMLElement> {
  * to allow this element to receive keyboard events.
  *
  * For example:
- *
+ * ```
  *    dom('input', ...
  *      dom.onKeyDown({
  *        Enter: (e, elem) => console.log("Enter pressed"),
@@ -106,7 +124,14 @@ export interface IKeyHandlers<T extends HTMLElement = HTMLElement> {
  *        Delete$: (e, elem) => console.log("Delete pressed, will bubble"),
  *      })
  *    )
+ * ```
  */
 export declare function onKeyElem<T extends HTMLElement>(elem: T, evType: KeyEventType, keyHandlers: IKeyHandlers<T>): IDisposable;
+/**
+ * Add listeners to `"keypress"` events. See [`onKeyElem`](#onKeyElem) for details.
+ */
 export declare function onKeyPress<T extends HTMLElement>(keyHandlers: IKeyHandlers<T>): DomMethod<T>;
+/**
+ * Add listeners to `"keydown"` events. See [`onKeyElem`](#onKeyElem) for details.
+ */
 export declare function onKeyDown<T extends HTMLElement>(keyHandlers: IKeyHandlers<T>): DomMethod<T>;

package/dist/cjs/lib/domevent.js

@@ -1,45 +1,6 @@
 "use strict";
-/**
- * domevent provides a way to listen to DOM events, similar to JQuery's `on()` function. Its
- * methods are also exposed via the dom.js module, as `dom.on()`, etc.
- *
- * It is typically used as an argument to the dom() function:
- *
- *    dom('div', dom.on('click', (event, elem) => { ... }));
- *
- * When the div is disposed, the listener is automatically removed.
- *
- * The underlying interface to listen to an event is this:
- *
- *    let listener = dom.onElem(elem, 'click', (event, elem) => { ... });
- *
- * The callback is called with the event and the element to which it was attached. Unlike in
- * JQuery, the callback's return value is ignored. Use event.stopPropagation() and
- * event.preventDefault() explicitly if needed.
- *
- * To stop listening:
- *
- *    listener.dispose();
- *
- * Disposing the listener returned by .onElem() is the only way to stop listening to an event. You
- * can use autoDispose to stop listening automatically when subscribing in a Disposable object:
- *
- *    this.autoDispose(domevent.onElem(document, 'mouseup', callback));
- *
- * To listen to descendants of an element matching the given selector (what JQuery calls
- * "delegated events", see http://api.jquery.com/on/):
- *
- *    dom('div', dom.onMatch('.selector', 'click', (event, elem) => { ... }));
- * or
- *    let lis = domevent.onMatchElem(elem, '.selector', 'click', (event, el) => { ... });
- *
- * In this usage, the element passed to the callback will be a DOM element matching the given
- * selector. If there are multiple matches, the callback is only called for the innermost one.
- *
- * If you need to remove the callback on first call, here's a useful pattern:
- *    let lis = domevent.onElem(elem, 'mouseup', e => { lis.dispose(); other_work(); });
- */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.onKeyDown = exports.onKeyPress = exports.onKeyElem = exports.onMatch = exports.onMatchElem = exports.on = exports.onElem = void 0;
 function _findMatch(inner, outer, selector) {
     for (let el = inner; el && el !== outer; el = el.parentElement) {
         if (el.matches(selector)) {
@@ -75,43 +36,103 @@ class DomEventMatchListener extends DomEventListener {
     }
 }
 /**
- * Listen to a DOM event. The `on()` variant takes no `elem` argument, and may be used as an
- * argument to dom() function.
- * @param {DOMElement} elem: DOM Element to listen to.
- * @param {String} eventType: Event type to listen for (e.g. 'click').
- * @param {Function} callback: Callback to call as `callback(event, elem)`, where elem is `elem`.
- * @param [Boolean] options.useCapture: Add the listener in the capture phase. This should very
+ * Listen to a DOM event, returning the listener object.
+ * ```ts
+ * const listener = dom.onElem(elem, 'click', (event, elem) => { ... });
+ * ```
+ *
+ * To stop listening:
+ * ```ts
+ * listener.dispose();
+ * ```
+ *
+ * Disposing the listener returned by `onElem()` is the only way to stop listening to an event. You
+ * can use `autoDispose` to stop listening automatically when subscribing in a `Disposable` object:
+ * ```ts
+ * this.autoDispose(domevent.onElem(document, 'mouseup', callback));
+ * ```
+ *
+ * If you need "once" semantics, i.e. to remove the callback on first call, here's a useful pattern:
+ * ```ts
+ * const lis = domevent.onElem(elem, 'mouseup', e => { lis.dispose(); other_work(); });
+ * ```
+ *
+ * @param elem - DOM Element to listen to.
+ * @param eventType - Event type to listen for (e.g. `'click'`).
+ * @param callback - Callback to call as `callback(event, elem)`, where elem is `elem`.
+ * @param options - `useCapture: boolean`: Add the listener in the capture phase. This should very
  *    rarely be useful (e.g. JQuery doesn't even offer it as an option).
- * @returns {Object} Listener object whose .dispose() method will remove the event listener.
+ * @returns Listener object whose `.dispose()` method will remove the event listener.
  */
 function onElem(elem, eventType, callback, { useCapture = false } = {}) {
     return new DomEventListener(elem, eventType, callback, useCapture);
 }
 exports.onElem = onElem;
+/**
+ * Listen to a DOM event. It is typically used as an argument to the `dom()` function:
+ * ```ts
+ * dom('div', dom.on('click', (event, elem) => { ... }));
+ * ```
+ *
+ * When the div is disposed, the listener is automatically removed.
+ *
+ * The callback is called with the event and the element to which it was attached. Unlike in, say,
+ * JQuery, the callback's return value is ignored. Use `event.stopPropagation()` and
+ * `event.preventDefault()` explicitly if needed.
+ *
+ * To listen to descendants of an element matching the given selector (what JQuery calls
+ * "delegated events", see http://api.jquery.com/on/), see [`onMatch`](#onMatch).
+ *
+ * @param eventType - Event type to listen for (e.g. `'click'`).
+ * @param callback - Callback to call as `callback(event, elem)`, where `elem` is the element this
+ *    listener is attached to.
+ * @param options - `useCapture?: boolean`: Add the listener in the capture phase.
+ */
 function on(eventType, callback, { useCapture = false } = {}) {
     // tslint:disable-next-line:no-unused-expression
     return (elem) => { new DomEventListener(elem, eventType, callback, useCapture); };
 }
 exports.on = on;
 /**
- * Listen to a DOM event on descendants of the given elem matching the given selector. The
- * `onMatch()` variant takes no `elem` argument, and may be used as an argument to dom().
- * @param {DOMElement} elem: DOM Element to whose descendants to listen.
- * @param {String} selector: CSS selector string to filter elements that trigger this event.
+ * Listen to a DOM event on descendants of the given elem matching the given selector.
+ *
+ * ```ts
+ * const let lis = domevent.onMatchElem(elem, '.selector', 'click', (event, el) => { ... });
+ * ```
+ *
+ * @param elem - DOM Element to whose descendants to listen.
+ * @param selector - CSS selector string to filter elements that trigger this event.
  *    JQuery calls it "delegated events" (http://api.jquery.com/on/). The callback will only be
  *    called when the event occurs for an element matching the given selector. If there are
  *    multiple elements matching the selector, the callback is only called for the innermost one.
- * @param {String} eventType: Event type to listen for (e.g. 'click').
- * @param {Function} callback: Callback to call as `callback(event, elem)`, where elem is a
+ * @param eventType - Event type to listen for (e.g. 'click').
+ * @param callback - Callback to call as `callback(event, elem)`, where elem is a
  *    descendent of `elem` which matches `selector`.
- * @param [Boolean] options.useCapture: Add the listener in the capture phase. This should very
- *    rarely be useful (e.g. JQuery doesn't even offer it as an option).
- * @returns {Object} Listener object whose .dispose() method will remove the event listener.
+ * @param options - `useCapture?: boolean`: Add the listener in the capture phase.
+ * @returns Listener object whose `.dispose()` method will remove the event listener.
  */
 function onMatchElem(elem, selector, eventType, callback, { useCapture = false } = {}) {
     return new DomEventMatchListener(elem, eventType, callback, useCapture, selector);
 }
 exports.onMatchElem = onMatchElem;
+/**
+ * Listen to a DOM event on descendants of the given element matching the given selector.
+ *
+ * This is similar to JQuery's [delegated events](https://api.jquery.com/on/#direct-and-delegated-events)
+ *
+ * ```ts
+ * dom('div', dom.onMatch('.selector', 'click', (event, elem) => { ... }));
+ * ```
+ *
+ * In this usage, the element passed to the callback will be a DOM element matching the given
+ * selector. If there are multiple matches, the callback is only called for the innermost one.
+ *
+ * @param selector - CSS selector string to filter elements that trigger this event.
+ * @param eventType - Event type to listen for (e.g. `'click'`).
+ * @param callback - Callback to call as `callback(event, elem)`, where `elem` is an element
+ *    matching `selector`.
+ * @param options - `useCapture?: boolean`: Add the listener in the capture phase.
+ */
 function onMatch(selector, eventType, callback, { useCapture = false } = {}) {
     // tslint:disable-next-line:no-unused-expression
     return (elem) => { new DomEventMatchListener(elem, eventType, callback, useCapture, selector); };
@@ -121,8 +142,6 @@ exports.onMatch = onMatch;
  * Listen to key events (typically 'keydown' or 'keypress'), with specified per-key callbacks.
  * Key names are listed at https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values
  *
- * Methods onKeyPress() and onKeyDown() are intended to be used as arguments to dom().
- *
  * By default, handled events are stopped from bubbling with stopPropagation() and
  * preventDefault(). If, however, you register a key with a "$" suffix (i.e. "Enter$" instead of
  * "Enter"), then the event is allowed to bubble normally.
@@ -131,7 +150,7 @@ exports.onMatch = onMatch;
  * to allow this element to receive keyboard events.
  *
  * For example:
- *
+ * ```
  *    dom('input', ...
  *      dom.onKeyDown({
  *        Enter: (e, elem) => console.log("Enter pressed"),
@@ -139,6 +158,7 @@ exports.onMatch = onMatch;
  *        Delete$: (e, elem) => console.log("Delete pressed, will bubble"),
  *      })
  *    )
+ * ```
  */
 function onKeyElem(elem, evType, keyHandlers) {
     if (!(elem.tabIndex >= 0)) { // If tabIndex property is undefined or -1,
@@ -157,10 +177,16 @@ function onKeyElem(elem, evType, keyHandlers) {
     });
 }
 exports.onKeyElem = onKeyElem;
+/**
+ * Add listeners to `"keypress"` events. See [`onKeyElem`](#onKeyElem) for details.
+ */
 function onKeyPress(keyHandlers) {
     return (elem) => { onKeyElem(elem, 'keypress', keyHandlers); };
 }
 exports.onKeyPress = onKeyPress;
+/**
+ * Add listeners to `"keydown"` events. See [`onKeyElem`](#onKeyElem) for details.
+ */
 function onKeyDown(keyHandlers) {
     return (elem) => { onKeyElem(elem, 'keydown', keyHandlers); };
 }

package/dist/cjs/lib/domevent.js.map

@@ -1 +1 @@
-{"version":3,"file":"domevent.js","sourceRoot":"","sources":["../../../lib/domevent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"domevent.js","sourceRoot":"","sources":["../../../lib/domevent.ts"],"names":[],"mappings":";;;AASA,SAAS,UAAU,CAAC,KAAc,EAAE,KAAc,EAAE,QAAgB;IAClE,KAAK,IAAI,EAAE,GAAiB,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,KAAK,EAAE,EAAE,GAAG,EAAE,CAAC,aAAa,EAAE;QAC5E,IAAI,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE;YACxB,OAAO,EAAE,CAAC;SACX;KACF;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,gBAAgB;IACpB,YAAsB,IAAO,EACP,SAAiB,EACjB,QAAuB,EACvB,UAAmB,EACnB,QAAiB;QAJjB,SAAI,GAAJ,IAAI,CAAG;QACP,cAAS,GAAT,SAAS,CAAQ;QACjB,aAAQ,GAAR,QAAQ,CAAe;QACvB,eAAU,GAAV,UAAU,CAAS;QACnB,aAAQ,GAAR,QAAQ,CAAS;QACrC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACpE,CAAC;IAEM,WAAW,CAAC,KAAQ;QACzB,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC;QACzB,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;IAEM,OAAO;QACZ,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACvE,CAAC;CACF;AAED,MAAM,qBAAuC,SAAQ,gBAAgC;IAC5E,WAAW,CAAC,KAAQ;QACzB,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,MAAiB,EAAE,IAAI,CAAC,IAAe,EAAE,IAAI,CAAC,QAAS,CAAC,CAAC;QACvF,IAAI,IAAI,EAAE;YACR,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC;YACzB,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;SACjB;IACH,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,SAAgB,MAAM,CACpB,IAAO,EAAE,SAAY,EAAE,QAAkC,EAAE,EAAC,UAAU,GAAG,KAAK,EAAC,GAAG,EAAE;IACpF,OAAO,IAAI,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;AACrE,CAAC;AAHD,wBAGC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,EAAE,CAChB,SAAY,EAAE,QAAkC,EAAE,EAAC,UAAU,GAAG,KAAK,EAAC,GAAG,EAAE;IAC3E,gDAAgD;IAChD,OAAO,CAAC,IAAI,EAAE,EAAE,GAAG,IAAI,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AACpF,CAAC;AAJD,gBAIC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,WAAW,CAAC,IAAiB,EAAE,QAAgB,EAAE,SAAiB,EACtD,QAAiB,EAAE,EAAC,UAAU,GAAG,KAAK,EAAC,GAAG,EAAE;IACtE,OAAO,IAAI,qBAAqB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;AACpF,CAAC;AAHD,kCAGC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,OAAO,CAAC,QAAgB,EAAE,SAAiB,EAAE,QAAiB,EACtD,EAAC,UAAU,GAAG,KAAK,EAAC,GAAG,EAAE;IAC/C,gDAAgD;IAChD,OAAO,CAAC,IAAI,EAAE,EAAE,GAAG,IAAI,qBAAqB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACnG,CAAC;AAJD,0BAIC;AAQD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,SAAS,CACvB,IAAO,EAAE,MAAoB,EAAE,WAA4B;IAE3D,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,EAAE,EAAqB,2CAA2C;QACzF,IAAI,CAAC,YAAY,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAU,wDAAwD;KACvG;IACD,OAAO,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE;QACxC,MAAM,YAAY,GAAG,WAAW,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,YAAY,IAAI,WAAW,CAAC,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC;QAC1D,IAAI,OAAO,EAAE;YACX,IAAI,YAAa,EAAE;gBACjB,EAAE,CAAC,eAAe,EAAE,CAAC;gBACrB,EAAE,CAAC,cAAc,EAAE,CAAC;aACrB;YACD,OAAO,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;SACpB;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAjBD,8BAiBC;AAED;;GAEG;AACH,SAAgB,UAAU,CAAwB,WAA4B;IAC5E,OAAO,CAAC,IAAI,EAAE,EAAE,GAAG,SAAS,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC;AAFD,gCAEC;AAED;;GAEG;AACH,SAAgB,SAAS,CAAwB,WAA4B;IAC3E,OAAO,CAAC,IAAI,EAAE,EAAE,GAAG,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC;AAFD,8BAEC"}

package/dist/cjs/lib/emit.d.ts

@@ -1,29 +1,12 @@
+export type ListenerCB<T> = (this: T, ...args: any[]) => void;
 /**
- * emit.js implements an Emitter class which emits events to a list of listeners. Listeners are
- * simply functions to call, and "emitting an event" just calls those functions.
- *
- * This is similar to Backbone events, with more focus on efficiency. Both inserting and removing
- * listeners is constant time.
- *
- * To create an emitter:
- *    let emitter = new Emitter();
- *
- * To add a listener:
- *    let listener = fooEmitter.addListener(callback);
- * To remove a listener:
- *    listener.dispose();
- *
- * The only way to remove a listener is to dispose the Listener object returned by addListener().
- * You can often use autoDispose to do this automatically when subscribing in a constructor:
- *    this.autoDispose(fooEmitter.addListener(this.onFoo, this));
- *
- * To emit an event, call emit() with any number of arguments:
- *    emitter.emit("hello", "world");
+ * A callback that listens to _changes_ in the Emitter listeners. This is mainly used for
+ * internal purposes.
  */
-export declare type ListenerCB<T> = (this: T, ...args: any[]) => void;
-export declare type ChangeCB = (hasListeners: boolean) => void;
+export type ChangeCB = (hasListeners: boolean) => void;
 /**
  * This is an implementation of a doubly-linked list, with just the minimal functionality we need.
+ * @internal
  */
 export declare class LLink {
     protected _next: LLink | null;
@@ -34,18 +17,62 @@ export declare class LLink {
     protected _removeNode(node: LLink): void;
     protected _disposeList(): void;
 }
+/**
+ * An `Emitter` emits events to a list of listeners. Listeners are
+ * simply functions to call, and "emitting an event" just calls those functions.
+ *
+ * This is similar to Backbone events, with more focus on efficiency. Both inserting and removing
+ * listeners is constant time.
+ *
+ * To create an emitter:
+ * ```ts
+ * const emitter = new Emitter();
+ * ```
+ *
+ * To add a listener:
+ * ```ts
+ * const listener = fooEmitter.addListener(callback);
+ * ```
+ *
+ * To remove a listener:
+ * ```ts
+ * listener.dispose();
+ * ```
+ *
+ * The only way to remove a listener is to dispose the `Listener` object returned by `addListener()`.
+ * You can often use autoDispose to do this automatically when subscribing in a constructor:
+ * ```ts
+ * this.autoDispose(fooEmitter.addListener(this.onFoo, this));
+ * ```
+ *
+ * To emit an event, call `emit()` with any number of arguments:
+ * ```ts
+ * emitter.emit("hello", "world");
+ * ```
+ *
+ * @privateRemarks
+ *
+ * Note about a possible alternative implementation.
+ *
+ * We could implement the same interface using an array of listeners. Certain issues apply, in
+ * particular with removing listeners from inside emit(), and in ensuring that removals are
+ * constant time on average. Such an implementation was attempted and timed. The result is that
+ * compared to the linked-list implementation here, add/remove combination could be made nearly
+ * twice faster (on average), while emit and add/remove/emit are consistently slightly slower.
+ *
+ * The implementation here was chosen based on those timings, and as the simpler one. For example,
+ * on one setup (macbook, node4, 5-listener queue), add+remove take 0.1us, while add+remove+emit
+ * take 3.82us. (In array-based implementation with same set up, add+remove is 0.06us, while
+ * add+remove+emit is 4.80us.)
+ */
 export declare class Emitter extends LLink {
     private _changeCB;
     private _changeCBContext;
-    /**
-     * Constructs an Emitter object.
-     */
-    constructor();
     /**
      * Adds a listening callback to the list of functions to call on emit().
-     * @param {Function} callback: Function to call.
-     * @param {Object} optContext: Context for the function.
-     * @returns {Listener} Listener object. Its dispose() method removes the callback from the list.
+     * @param callback - Function to call.
+     * @param optContext - Context for the function.
+     * @returns Listener object. Its dispose() method removes the callback from the list.
      */
     addListener<T>(callback: ListenerCB<T>, optContext?: T): Listener;
     /**
@@ -54,7 +81,7 @@ export declare class Emitter extends LLink {
     emit(...args: any[]): void;
     /**
      * Sets the single callback that would get called when a listener is added or removed.
-     * @param {Function} changeCB(hasListeners): Function to call after a listener is added or
+     * @param changeCB - Function to call after a listener is added or
      *    removed. It's called with a boolean indicating whether this Emitter has any listeners.
      *    Pass in `null` to unset the callback. Note that it can be called multiple times in a row
      *    with hasListeners `true`.
@@ -62,6 +89,7 @@ export declare class Emitter extends LLink {
     setChangeCB(changeCB: ChangeCB, optContext?: any): void;
     /**
      * Helper used by Listener class, but not intended for public usage.
+     * @internal
      */
     _triggerChangeCB(): void;
     /**
@@ -75,14 +103,16 @@ export declare class Emitter extends LLink {
     dispose(): void;
 }
 /**
- * Listener object wraps a callback added to an Emitter, allowing for O(1) removal when the
- * listener is disposed.
+ * The `Listener` object wraps a callback added to an Emitter, allowing for O(1) removal when the
+ * listener is disposed. It implements `IDisposable`.
  */
 export declare class Listener extends LLink {
     private emitter;
     private callback;
     private context?;
+    /** @internal */
     static callAll(begin: LLink, end: LLink, args: any[]): void;
     constructor(emitter: Emitter, callback: ListenerCB<any>, context?: any);
+    /** @internal */
     dispose(): void;
 }