@effection/events - npm Package Compare versions

Comparing version 2.0.0-preview.3-f6f5f84 to 2.0.0-preview.3-f9e72f1

dist/events.cjs.development.js

@@ -25,6 +25,56 @@ 'use strict';
 /**
- * Takes an event source and event name and returns a yieldable
- * operation which resumes when the event occurs.
+ * Takes an event source and event name and returns an
+ * {@link effection:Operation} that produces the value emitted by that
+ * event. Both {@link EventTarget} and {@link EventEmitter} are
+ * supported.
+ *
+ * ### Example
+ *
+ * ``` javascript
+ * let start = yield once(document, 'dragstart');
+ * console.log(`drag started at (${start.pageX}, ${start.pageY})`);
+ *
+ * let end = yield once(document, 'dragend');
+ * console.log(`drag ended at (${end.pageX}, ${end.pageY})`);
+ * ```
+ *
+ * ### Example
+ *
+ * ``` javascript
+ * let src = yield once(stream, 'pipe');
+ * ```
  */
 
+function once(source, eventName) {
+  return function* () {
+    var _yield$onceEmit = yield onceEmit(source, eventName),
+        event = _yield$onceEmit[0];
+
+    return event;
+  };
+}
+/**
+ * Exactly like {@link once | once()} except the value produced is an
+ * {@link Array} of all the arguments passed when the event was
+ * dispatched.
+ *
+ * In very rare cases, some event emitters pass multiple arguments to
+ * their event handlers. For example the {@link ChildProcess} in
+ * NodeJS emits both a status code _and_ a signal to the 'exit'
+ * event. It would not be possible to read the signal from the `exit`
+ * event using just the `once()` operation, so you would need to use
+ * the `onceEmit()` operation to get all the arguments sent to the
+ * event handler as an array.
+ *
+ * While it is supported, you should never need to use `onceEmit()` on
+ * an {@link EventTarget} since only a single argument is ever passed
+ * to its event handler. In those cases, always use {@link once | once()}
+ *
+ * ### Example
+ *
+ * ```javascript
+ * let [exitCode, signal] = yield onEmit(childProcess, 'exit');
+ * ```
+ */
+
 function onceEmit(source, eventName) {
@@ -48,10 +98,65 @@ return function (task) {
 }
-function once(source, eventName) {
-  return function* () {
-    var _yield$onceEmit = yield onceEmit(source, eventName),
-        event = _yield$onceEmit[0];
 
+/**
+ * Creates a {@link Stream} from an event source and event name that
+ * produces the event as its next value every time that the source
+ * raises it. Streams created in this way are infinite.
+ *
+ * Both {@link EventTarget} and {@link EventEmitter}
+ * are supported.
+ *
+ * ### Example
+ *
+ * log every click in a web page:
+ *
+ * ```javascript
+ * task.spawn(on(document, 'click').forEach(event => {
+ *   console.log(`click at (${event.pageX}, ${event.pageY})`);
+ * }));
+ * ```
+ *
+ * ### Example
+ *
+ * buffer a node process's stdin into a single string:
+ *
+ * ```javascript
+ * let buffer = '';
+ * task.spawn(on(process.stdin, 'data').forEach(data => {
+ *   buffer += data;
+ * }));
+ */
+
+function on(source, name) {
+  return onEmit(source, name).map(function (_ref) {
+    var event = _ref[0];
     return event;
-  };
+  });
 }
+/**
+ * Exactly like {@link on | on()} except each value produced by the
+ * stream is an {@link Array} of all the arguments passed when the event was
+ * dispatched.
+ *
+ * This should rarely be needed, and never with {@link EventTarget}s
+ * which always invoke their event listeners with a single argument.
+ *
+ * ### Example
+ *
+ * stream an odd-ball event emitter that passes multiple arguments to
+ * its handers. Most event emitters do not act this way:
+ *
+ * ```javascript
+ * let emitter = new EventEmitter();
+ *
+ * task.spawn(onEmit(emitter, 'multiplication').forEach(([left, right]) => {
+ *   console.log(`${left} times ${right} = ${left * right}!`);
+ * }));
+ *
+ * yield sleep(10);
+ *
+ * emitter.emit('multiplication', 7, 6);
+ * //=> 7 times 6 = 42!
+ * ```
+ *
+ */
 
@@ -78,14 +183,6 @@ function onEmit(source, name) {
 }
-function on(source, name) {
-  return onEmit(source, name).map(function (_ref) {
-    var event = _ref[0];
-    return event;
-  });
-}
 
 function throwOnErrorEvent(task, source) {
   return task.spawn(function* () {
-    var _yield$once = yield once(source, 'error'),
-        error = _yield$once[0];
-
+    var error = yield once(source, 'error');
     throw error;
@@ -92,0 +189,0 @@ });

dist/events.cjs.production.min.js

@@ -1,2 +0,2 @@
-"use strict";var n=require("@effection/subscription");function r(n){return"function"==typeof n.addEventListener}function t(n,t,e){r(n)?n.addEventListener(t,e):n.on(t,e)}function e(n,t,e){r(n)?n.removeEventListener(t,e):n.off(t,e)}function o(n,r){return function(o){return function(u){var i=function(){for(var n=arguments.length,r=new Array(n),t=0;t<n;t++)r[t]=arguments[t];u(r)};o.ensure((function(){e(n,r,i)})),t(n,r,i)}}}function u(n,r){return function*(){return(yield o(n,r))[0]}}function i(r,o){return n.createStream((function(n){return function*(){var u=function(){for(var r=arguments.length,t=new Array(r),e=0;e<r;e++)t[e]=arguments[e];return n(t)};try{t(r,o,u),yield}finally{e(r,o,u)}}}))}exports.on=function(n,r){return i(n,r).map((function(n){return n[0]}))},exports.onEmit=i,exports.once=u,exports.onceEmit=o,exports.throwOnErrorEvent=function(n,r){return n.spawn((function*(){throw(yield u(r,"error"))[0]}))};
+"use strict";var n=require("@effection/subscription");function r(n){return"function"==typeof n.addEventListener}function t(n,t,e){r(n)?n.addEventListener(t,e):n.on(t,e)}function e(n,t,e){r(n)?n.removeEventListener(t,e):n.off(t,e)}function o(n,r){return function*(){return(yield u(n,r))[0]}}function u(n,r){return function(o){return function(u){var i=function(){for(var n=arguments.length,r=new Array(n),t=0;t<n;t++)r[t]=arguments[t];u(r)};o.ensure((function(){e(n,r,i)})),t(n,r,i)}}}function i(r,o){return n.createStream((function(n){return function*(){var u=function(){for(var r=arguments.length,t=new Array(r),e=0;e<r;e++)t[e]=arguments[e];return n(t)};try{t(r,o,u),yield}finally{e(r,o,u)}}}))}exports.on=function(n,r){return i(n,r).map((function(n){return n[0]}))},exports.onEmit=i,exports.once=o,exports.onceEmit=u,exports.throwOnErrorEvent=function(n,r){return n.spawn((function*(){throw yield o(r,"error")}))};
 //# sourceMappingURL=events.cjs.production.min.js.map

dist/events.esm.js

@@ -23,6 +23,56 @@ import { createStream } from '@effection/subscription';
 /**
- * Takes an event source and event name and returns a yieldable
- * operation which resumes when the event occurs.
+ * Takes an event source and event name and returns an
+ * {@link effection:Operation} that produces the value emitted by that
+ * event. Both {@link EventTarget} and {@link EventEmitter} are
+ * supported.
+ *
+ * ### Example
+ *
+ * ``` javascript
+ * let start = yield once(document, 'dragstart');
+ * console.log(`drag started at (${start.pageX}, ${start.pageY})`);
+ *
+ * let end = yield once(document, 'dragend');
+ * console.log(`drag ended at (${end.pageX}, ${end.pageY})`);
+ * ```
+ *
+ * ### Example
+ *
+ * ``` javascript
+ * let src = yield once(stream, 'pipe');
+ * ```
  */
 
+function once(source, eventName) {
+  return function* () {
+    var _yield$onceEmit = yield onceEmit(source, eventName),
+        event = _yield$onceEmit[0];
+
+    return event;
+  };
+}
+/**
+ * Exactly like {@link once | once()} except the value produced is an
+ * {@link Array} of all the arguments passed when the event was
+ * dispatched.
+ *
+ * In very rare cases, some event emitters pass multiple arguments to
+ * their event handlers. For example the {@link ChildProcess} in
+ * NodeJS emits both a status code _and_ a signal to the 'exit'
+ * event. It would not be possible to read the signal from the `exit`
+ * event using just the `once()` operation, so you would need to use
+ * the `onceEmit()` operation to get all the arguments sent to the
+ * event handler as an array.
+ *
+ * While it is supported, you should never need to use `onceEmit()` on
+ * an {@link EventTarget} since only a single argument is ever passed
+ * to its event handler. In those cases, always use {@link once | once()}
+ *
+ * ### Example
+ *
+ * ```javascript
+ * let [exitCode, signal] = yield onEmit(childProcess, 'exit');
+ * ```
+ */
+
 function onceEmit(source, eventName) {
@@ -46,10 +96,65 @@ return function (task) {
 }
-function once(source, eventName) {
-  return function* () {
-    var _yield$onceEmit = yield onceEmit(source, eventName),
-        event = _yield$onceEmit[0];
 
+/**
+ * Creates a {@link Stream} from an event source and event name that
+ * produces the event as its next value every time that the source
+ * raises it. Streams created in this way are infinite.
+ *
+ * Both {@link EventTarget} and {@link EventEmitter}
+ * are supported.
+ *
+ * ### Example
+ *
+ * log every click in a web page:
+ *
+ * ```javascript
+ * task.spawn(on(document, 'click').forEach(event => {
+ *   console.log(`click at (${event.pageX}, ${event.pageY})`);
+ * }));
+ * ```
+ *
+ * ### Example
+ *
+ * buffer a node process's stdin into a single string:
+ *
+ * ```javascript
+ * let buffer = '';
+ * task.spawn(on(process.stdin, 'data').forEach(data => {
+ *   buffer += data;
+ * }));
+ */
+
+function on(source, name) {
+  return onEmit(source, name).map(function (_ref) {
+    var event = _ref[0];
     return event;
-  };
+  });
 }
+/**
+ * Exactly like {@link on | on()} except each value produced by the
+ * stream is an {@link Array} of all the arguments passed when the event was
+ * dispatched.
+ *
+ * This should rarely be needed, and never with {@link EventTarget}s
+ * which always invoke their event listeners with a single argument.
+ *
+ * ### Example
+ *
+ * stream an odd-ball event emitter that passes multiple arguments to
+ * its handers. Most event emitters do not act this way:
+ *
+ * ```javascript
+ * let emitter = new EventEmitter();
+ *
+ * task.spawn(onEmit(emitter, 'multiplication').forEach(([left, right]) => {
+ *   console.log(`${left} times ${right} = ${left * right}!`);
+ * }));
+ *
+ * yield sleep(10);
+ *
+ * emitter.emit('multiplication', 7, 6);
+ * //=> 7 times 6 = 42!
+ * ```
+ *
+ */
 
@@ -76,14 +181,6 @@ function onEmit(source, name) {
 }
-function on(source, name) {
-  return onEmit(source, name).map(function (_ref) {
-    var event = _ref[0];
-    return event;
-  });
-}
 
 function throwOnErrorEvent(task, source) {
   return task.spawn(function* () {
-    var _yield$once = yield once(source, 'error'),
-        error = _yield$once[0];
-
+    var error = yield once(source, 'error');
     throw error;
@@ -90,0 +187,0 @@ });

dist/on.d.ts

 import { Stream } from '@effection/subscription';
 import { EventSource } from './event-source';
+/**
+ * Creates a {@link Stream} from an event source and event name that
+ * produces the event as its next value every time that the source
+ * raises it. Streams created in this way are infinite.
+ *
+ * Both {@link EventTarget} and {@link EventEmitter}
+ * are supported.
+ *
+ * ### Example
+ *
+ * log every click in a web page:
+ *
+ * ```javascript
+ * task.spawn(on(document, 'click').forEach(event => {
+ *   console.log(`click at (${event.pageX}, ${event.pageY})`);
+ * }));
+ * ```
+ *
+ * ### Example
+ *
+ * buffer a node process's stdin into a single string:
+ *
+ * ```javascript
+ * let buffer = '';
+ * task.spawn(on(process.stdin, 'data').forEach(data => {
+ *   buffer += data;
+ * }));
+ */
+export declare function on<T = unknown>(source: EventSource, name: string): Stream<T, void>;
+/**
+ * Exactly like {@link on | on()} except each value produced by the
+ * stream is an {@link Array} of all the arguments passed when the event was
+ * dispatched.
+ *
+ * This should rarely be needed, and never with {@link EventTarget}s
+ * which always invoke their event listeners with a single argument.
+ *
+ * ### Example
+ *
+ * stream an odd-ball event emitter that passes multiple arguments to
+ * its handers. Most event emitters do not act this way:
+ *
+ * ```javascript
+ * let emitter = new EventEmitter();
+ *
+ * task.spawn(onEmit(emitter, 'multiplication').forEach(([left, right]) => {
+ *   console.log(`${left} times ${right} = ${left * right}!`);
+ * }));
+ *
+ * yield sleep(10);
+ *
+ * emitter.emit('multiplication', 7, 6);
+ * //=> 7 times 6 = 42!
+ * ```
+ *
+ */
 export declare function onEmit<T extends Array<unknown> = unknown[]>(source: EventSource, name: string): Stream<T, void>;
-export declare function on<T = unknown>(source: EventSource, name: string): Stream<T, void>;

dist/once.d.ts

 import { Operation } from '@effection/core';
 import { EventSource } from './event-source';
 /**
- * Takes an event source and event name and returns a yieldable
- * operation which resumes when the event occurs.
+ * Takes an event source and event name and returns an
+ * {@link effection:Operation} that produces the value emitted by that
+ * event. Both {@link EventTarget} and {@link EventEmitter} are
+ * supported.
+ *
+ * ### Example
+ *
+ * ``` javascript
+ * let start = yield once(document, 'dragstart');
+ * console.log(`drag started at (${start.pageX}, ${start.pageY})`);
+ *
+ * let end = yield once(document, 'dragend');
+ * console.log(`drag ended at (${end.pageX}, ${end.pageY})`);
+ * ```
+ *
+ * ### Example
+ *
+ * ``` javascript
+ * let src = yield once(stream, 'pipe');
+ * ```
  */
+export declare function once<T = unknown>(source: EventSource, eventName: string): Operation<T>;
+/**
+ * Exactly like {@link once | once()} except the value produced is an
+ * {@link Array} of all the arguments passed when the event was
+ * dispatched.
+ *
+ * In very rare cases, some event emitters pass multiple arguments to
+ * their event handlers. For example the {@link ChildProcess} in
+ * NodeJS emits both a status code _and_ a signal to the 'exit'
+ * event. It would not be possible to read the signal from the `exit`
+ * event using just the `once()` operation, so you would need to use
+ * the `onceEmit()` operation to get all the arguments sent to the
+ * event handler as an array.
+ *
+ * While it is supported, you should never need to use `onceEmit()` on
+ * an {@link EventTarget} since only a single argument is ever passed
+ * to its event handler. In those cases, always use {@link once | once()}
+ *
+ * ### Example
+ *
+ * ```javascript
+ * let [exitCode, signal] = yield onEmit(childProcess, 'exit');
+ * ```
+ */
 export declare function onceEmit<TArgs extends unknown[] = unknown[]>(source: EventSource, eventName: string): Operation<TArgs>;
-export declare function once<T = unknown>(source: EventSource, eventName: string): Operation<T>;

package.json

 {
   "name": "@effection/events",
-  "version": "2.0.0-preview.3-f6f5f84",
+  "version": "2.0.0-preview.3-f9e72f1",
   "description": "Helpers for listening to events with effection",
@@ -24,11 +24,11 @@ "main": "dist/index.js",
   "dependencies": {
-    "effection": "^2.0.0-preview.4",
-    "@effection/subscription": "^2.0.0-preview.3"
+    "@effection/subscription": "^2.0.0-preview.3",
+    "effection": "^2.0.0-preview.4"
   },
   "devDependencies": {
+    "@effection/mocha": "2.0.0-preview.2",
     "@frontside/tsconfig": "0.0.1",
     "@types/node": "^12.7.11",
-    "@effection/mocha": "2.0.0-preview.2",
     "expect": "^25.4.0",
-    "mocha": "^7.1.1",
+    "mocha": "^8.3.1",
     "ts-node": "^8.9.0",
@@ -35,0 +35,0 @@ "tsdx": "0.13.2",

src/on.ts

@@ -5,2 +5,62 @@ import { createStream, Stream } from '@effection/subscription';
 
+
+/**
+ * Creates a {@link Stream} from an event source and event name that
+ * produces the event as its next value every time that the source
+ * raises it. Streams created in this way are infinite.
+ *
+ * Both {@link EventTarget} and {@link EventEmitter}
+ * are supported.
+ *
+ * ### Example
+ *
+ * log every click in a web page:
+ *
+ * ```javascript
+ * task.spawn(on(document, 'click').forEach(event => {
+ *   console.log(`click at (${event.pageX}, ${event.pageY})`);
+ * }));
+ * ```
+ *
+ * ### Example
+ *
+ * buffer a node process's stdin into a single string:
+ *
+ * ```javascript
+ * let buffer = '';
+ * task.spawn(on(process.stdin, 'data').forEach(data => {
+ *   buffer += data;
+ * }));
+ */
+export function on<T = unknown>(source: EventSource, name: string): Stream<T, void> {
+  return onEmit<[T]>(source, name).map(([event]) => event)
+}
+
+/**
+ * Exactly like {@link on | on()} except each value produced by the
+ * stream is an {@link Array} of all the arguments passed when the event was
+ * dispatched.
+ *
+ * This should rarely be needed, and never with {@link EventTarget}s
+ * which always invoke their event listeners with a single argument.
+ *
+ * ### Example
+ *
+ * stream an odd-ball event emitter that passes multiple arguments to
+ * its handers. Most event emitters do not act this way:
+ *
+ * ```javascript
+ * let emitter = new EventEmitter();
+ *
+ * task.spawn(onEmit(emitter, 'multiplication').forEach(([left, right]) => {
+ *   console.log(`${left} times ${right} = ${left * right}!`);
+ * }));
+ *
+ * yield sleep(10);
+ *
+ * emitter.emit('multiplication', 7, 6);
+ * //=> 7 times 6 = 42!
+ * ```
+ *
+ */
 export function onEmit<T extends Array<unknown> = unknown[]>(source: EventSource, name: string): Stream<T, void> {
@@ -17,6 +77,1 @@ return createStream((publish) => function*() {
 }
-
-
-export function on<T = unknown>(source: EventSource, name: string): Stream<T, void> {
-  return onEmit<[T]>(source, name).map(([event]) => event)
-}

src/once.ts

 import { Operation } from '@effection/core';
 import { EventSource, addListener, removeListener } from './event-source';
 
+
 /**
- * Takes an event source and event name and returns a yieldable
- * operation which resumes when the event occurs.
+ * Takes an event source and event name and returns an
+ * {@link effection:Operation} that produces the value emitted by that
+ * event. Both {@link EventTarget} and {@link EventEmitter} are
+ * supported.
+ *
+ * ### Example
+ *
+ * ``` javascript
+ * let start = yield once(document, 'dragstart');
+ * console.log(`drag started at (${start.pageX}, ${start.pageY})`);
+ *
+ * let end = yield once(document, 'dragend');
+ * console.log(`drag ended at (${end.pageX}, ${end.pageY})`);
+ * ```
+ *
+ * ### Example
+ *
+ * ``` javascript
+ * let src = yield once(stream, 'pipe');
+ * ```
  */
+export function once<T = unknown>(source: EventSource, eventName: string): Operation<T> {
+  return function*() {
+    let [event]: [T] = yield onceEmit<[T]>(source, eventName);
+    return event;
+  }
+}
+
+/**
+ * Exactly like {@link once | once()} except the value produced is an
+ * {@link Array} of all the arguments passed when the event was
+ * dispatched.
+ *
+ * In very rare cases, some event emitters pass multiple arguments to
+ * their event handlers. For example the {@link ChildProcess} in
+ * NodeJS emits both a status code _and_ a signal to the 'exit'
+ * event. It would not be possible to read the signal from the `exit`
+ * event using just the `once()` operation, so you would need to use
+ * the `onceEmit()` operation to get all the arguments sent to the
+ * event handler as an array.
+ *
+ * While it is supported, you should never need to use `onceEmit()` on
+ * an {@link EventTarget} since only a single argument is ever passed
+ * to its event handler. In those cases, always use {@link once | once()}
+ *
+ * ### Example
+ *
+ * ```javascript
+ * let [exitCode, signal] = yield onEmit(childProcess, 'exit');
+ * ```
+ */
 export function onceEmit<TArgs extends unknown[] = unknown[]>(source: EventSource, eventName: string): Operation<TArgs> {
@@ -17,8 +66,1 @@ return (task) => (resolve) => {
 }
-
-export function once<T = unknown>(source: EventSource, eventName: string): Operation<T> {
-  return function*() {
-    let [event]: [T] = yield onceEmit<[T]>(source, eventName);
-    return event;
-  }
-}

src/throw-on-error-event.ts

@@ -7,5 +7,5 @@ import { Task } from '@effection/core';
   return task.spawn(function*() {
-    let [error]: [Error] = yield once(source, 'error');
+    let error: Error = yield once(source, 'error');
     throw error;
   });
 }

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

50818

increased by67.83%

Lines of code

656

increased by139.42%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes