@effection/subscription - npm Package Compare versions

Comparing version 2.0.0-v2-writable-unification.1633595877341 to 2.0.0

CHANGELOG.md

 # @effection/subscription
 
+## \[2.0.0]
+
+- Release Effection 2.0.0
+  - [8bd89ad](https://github.com/thefrontside/effection/commit/8bd89ad40e42805ab6da0fd1b7a49beed9769865) Add 2.0 changeset on %as
+
+## \[2.0.0-beta.19]
+
+- Yielding to something which is not an operation no longer throws an internal error, but properly rejects the task.
+  - Bumped due to a bump in @effection/core.
+  - [a3ad19a](https://github.com/thefrontside/effection/commit/a3ad19a3177a731fee5cd2389ab898dee7b1788e) Fix yielding non operation bug on 2021-10-07
+
 ## \[2.0.0-beta.18]
@@ -4,0 +15,0 @@

dist-cjs/index.d.ts

 export { OperationIterator } from './operation-iterator';
 export { Subscription } from './subscription';
 export { Queue, createQueue } from './queue';
-export { Sink, Close } from './sink';
 //# sourceMappingURL=index.d.ts.map

dist-cjs/operation-iterator.d.ts

 import { Operation } from '@effection/core';
+/**
+ * @hidden
+ */
 export interface OperationIterator<T, TReturn = undefined> {
@@ -3,0 +6,0 @@ next(): Operation<IteratorResult<T, TReturn>>;

dist-cjs/queue.d.ts

@@ -1,6 +0,97 @@
-import { Subscription, Sink } from './index';
-export interface Queue<T, TReturn = undefined> extends Subscription<T, TReturn>, Sink<T, TReturn> {
-    subscription: Subscription<T, TReturn>;
+import { Subscription } from './index';
+declare type Close<T> = (...args: T extends undefined ? [] : [T]) => void;
+/**
+ * A queue which can act as a subscription. It can be sent messages to and
+ * which can be closed.
+ *
+ * @typeParam T the type of the items in the queue
+ * @typeParam TClose the type of the value that the queue is closed with
+ */
+export interface Queue<T, TClose = undefined> extends Subscription<T, TClose> {
+    /**
+     * Send a value to the queue.
+     */
+    send(value: T): void;
+    /**
+     * Close the queue
+     *
+     * ### Example
+     *
+     * Closing queue with no close value:
+     *
+     * ```typescript
+     * import { main, createQueue } from 'effection';
+     *
+     * main(function*() {
+     *   let queue = createQueue<number>();
+     *   queue.close();
+     *   yield queue.join();
+     * });
+     * ```
+     *
+     * Closing queue with close value:
+     *
+     * ```typescript
+     * import { main, createQueue } from 'effection';
+     *
+     * main(function*() {
+     *   let queue = createQueue<number, string>();
+     *   queue.close("I'm done");
+     *   let value = yield queue.join();
+     *   console.log(value) // => "I'm done"
+     * });
+     * ```
+     */
+    close: Close<TClose>;
+    /**
+     * Like {@link close}, but with no special case for closing a queue without a
+     * value, this makes `closeWith` easier to use from generic code.
+     */
+    closeWith(value: TClose): void;
+    /**
+     * Return a subscription for this queue. Useful when using destructuring
+     * assignment.
+     *
+     * ### Example
+     *
+     * ```typescript
+     * import { main, createQueue } from 'effection';
+     *
+     * main(function*() {
+     *   let { send, subscription } = createQueue<number>();
+     *   send(1);
+     *   send(2);
+     *   send(3);
+     *
+     *   yield subscription.forEach((value) => console.log("got number", value));
+     * });
+     * ```
+     */
+    subscription: Subscription<T, TClose>;
 }
-export declare function createQueue<T, TReturn = undefined>(name?: string): Queue<T, TReturn>;
+/**
+ * Creates a new queue. Queues are unlimited in size and sending a message to a
+ * queue is always synchronous.
+ *
+ * ### Example
+ *
+ * ```typescript
+ * import { main, createQueue } from 'effection';
+ *
+ * main(function*() {
+ *   let queue = createQueue<number>();
+ *   queue.send(1);
+ *   queue.send(2);
+ *   queue.send(3);
+ *
+ *   yield queue.forEach((value) => console.log("got number", value));
+ * });
+ * ```
+ *
+ * @param name the name of the returned subscription, useful for debugging
+ * @typeParam T the type of the items in the queue
+ * @typeParam TClose the type of the value that the queue is closed with
+ */
+export declare function createQueue<T, TClose = undefined>(name?: string): Queue<T, TClose>;
+export {};
 //# sourceMappingURL=queue.d.ts.map

dist-cjs/queue.js

@@ -5,2 +5,25 @@ "use strict";
 const core_1 = require("@effection/core");
+/**
+ * Creates a new queue. Queues are unlimited in size and sending a message to a
+ * queue is always synchronous.
+ *
+ * ### Example
+ *
+ * ```typescript
+ * import { main, createQueue } from 'effection';
+ *
+ * main(function*() {
+ *   let queue = createQueue<number>();
+ *   queue.send(1);
+ *   queue.send(2);
+ *   queue.send(3);
+ *
+ *   yield queue.forEach((value) => console.log("got number", value));
+ * });
+ * ```
+ *
+ * @param name the name of the returned subscription, useful for debugging
+ * @typeParam T the type of the items in the queue
+ * @typeParam TClose the type of the value that the queue is closed with
+ */
 function createQueue(name = 'queue') {
@@ -10,3 +33,3 @@ let waiters = [];
     let didClose = false;
-    let send = function* (value) {
+    let send = (value) => {
         if (didClose) {
@@ -23,3 +46,3 @@ new Error(`tried to publish a value: ${value} on an already finished queue`);
     };
-    let close = function* (value) {
+    let close = (value) => {
         if (didClose) {
@@ -59,3 +82,4 @@ new Error('tried to close an already closed queue');
         next,
-        close,
+        close: ((...args) => close(args[0])),
+        closeWith: close,
         first() {
@@ -62,0 +86,0 @@ return withName(`first`, function* () {

dist-cjs/subscription.d.ts

 import { Operation } from '@effection/core';
 import { OperationIterator } from './operation-iterator';
+/**
+ * A Subscription functions as an iterator over a stream of values. Taking the
+ * next value from the subscription returns the next value and crucially also
+ * removes it, so we don't iterate the same value twice. Subscriptions are
+ * stateful objects, and calling methods such as next or expect on them changes
+ * the state of the subscription.
+ *
+ * See [the guide on Streams and Subscriptions](https://frontside.com/effection/docs/guides/collections) for more details.
+ *
+ * @typeParam T the type of the items in the queue
+ * @typeParam TReturn the type of the value that the subscription finishes with
+ */
 export interface Subscription<T, TReturn = undefined> extends OperationIterator<T, TReturn> {
+    /**
+     * Consume and return the next value of the subscription, if the subscription
+     * finishes before it returns another value then `undefined` is returned.
+     */
     first(): Operation<T | undefined>;
+    /**
+     * Consume and return the next value of the subscription, if the subscription
+     * finishes before it returns another value then an error is thrown.
+     */
     expect(): Operation<T>;
+    /**
+     * Iterate the subscription, passing each value to the given callback. Blocks
+     * until the subscription finishes, and returns the value it finished with.
+     *
+     * The callback can be either a regular function which returns `undefined`,
+     * or an operation. If it is an operation, then `forEach` will block until
+     * the operation is complete before invoking the callback again.
+     *
+     * ### Example
+     *
+     * ```typescript
+     * import { main, createQueue } from 'effection';
+     *
+     * main(function*() {
+     *   let queue = createQueue<number, string>();
+     *   queue.send(1);
+     *   queue.send(2);
+     *   queue.close("I'm done");
+     *
+     *   let result = yield queue.forEach((value) => { console.log(value) }); // => '1', '2'
+     *   console.log(result); // => 'I'm done'
+     * });
+     * ```
+     */
     forEach(visit: (value: T) => (Operation<void> | void)): Operation<TReturn>;
+    /**
+     * Block until the subscription finishes, and return the value it finished
+     * with.
+     *
+     * ### Example
+     *
+     * ```typescript
+     * import { main, createQueue } from 'effection';
+     *
+     * main(function*() {
+     *   let queue = createQueue<number, string>();
+     *   queue.send(1);
+     *   queue.close("I'm done");
+     *
+     *   let result = yield queue.join();
+     *   console.log(result); // => "I'm done"
+     * });
+     * ```
+     */
     join(): Operation<TReturn>;
+    /**
+     * Block until the subscription finishes, and return a synchronous iterator
+     * over all of the emitted values.
+     *
+     * ### Example
+     *
+     * ```typescript
+     * import { main, createQueue } from 'effection';
+     *
+     * main(function*() {
+     *   let queue = createQueue<number, string>();
+     *   queue.send(1);
+     *   queue.close("I'm done");
+     *
+     *   let iterator = yield queue.collect();
+     *
+     *   console.log(iterator.next()); // => { done: false, value: 1 }
+     *   console.log(iterator.next()); // => { done: true, value: "I'm done" }
+     * });
+     * ```
+     */
     collect(): Operation<Iterator<T, TReturn>>;
+    /**
+     * Block until the subscription finishes, and return an array of all of the
+     * emitted values.
+     *
+     * ### Example
+     *
+     * ```typescript
+     * import { main, createQueue } from 'effection';
+     *
+     * main(function*() {
+     *   let queue = createQueue<string>();
+     *   queue.send('hello');
+     *   queue.send('world');
+     *   queue.close();
+     *
+     *   let result = yield queue.toArray();
+     *   console.log(result); // => ['hello', 'world']
+     * });
+     * ```
+     */
     toArray(): Operation<T[]>;
 }
 //# sourceMappingURL=subscription.d.ts.map

dist-esm/index.d.ts

 export { OperationIterator } from './operation-iterator';
 export { Subscription } from './subscription';
 export { Queue, createQueue } from './queue';
-export { Sink, Close } from './sink';
 //# sourceMappingURL=index.d.ts.map

dist-esm/operation-iterator.d.ts

 import { Operation } from '@effection/core';
+/**
+ * @hidden
+ */
 export interface OperationIterator<T, TReturn = undefined> {
@@ -3,0 +6,0 @@ next(): Operation<IteratorResult<T, TReturn>>;

dist-esm/queue.d.ts

@@ -1,6 +0,97 @@
-import { Subscription, Sink } from './index';
-export interface Queue<T, TReturn = undefined> extends Subscription<T, TReturn>, Sink<T, TReturn> {
-    subscription: Subscription<T, TReturn>;
+import { Subscription } from './index';
+declare type Close<T> = (...args: T extends undefined ? [] : [T]) => void;
+/**
+ * A queue which can act as a subscription. It can be sent messages to and
+ * which can be closed.
+ *
+ * @typeParam T the type of the items in the queue
+ * @typeParam TClose the type of the value that the queue is closed with
+ */
+export interface Queue<T, TClose = undefined> extends Subscription<T, TClose> {
+    /**
+     * Send a value to the queue.
+     */
+    send(value: T): void;
+    /**
+     * Close the queue
+     *
+     * ### Example
+     *
+     * Closing queue with no close value:
+     *
+     * ```typescript
+     * import { main, createQueue } from 'effection';
+     *
+     * main(function*() {
+     *   let queue = createQueue<number>();
+     *   queue.close();
+     *   yield queue.join();
+     * });
+     * ```
+     *
+     * Closing queue with close value:
+     *
+     * ```typescript
+     * import { main, createQueue } from 'effection';
+     *
+     * main(function*() {
+     *   let queue = createQueue<number, string>();
+     *   queue.close("I'm done");
+     *   let value = yield queue.join();
+     *   console.log(value) // => "I'm done"
+     * });
+     * ```
+     */
+    close: Close<TClose>;
+    /**
+     * Like {@link close}, but with no special case for closing a queue without a
+     * value, this makes `closeWith` easier to use from generic code.
+     */
+    closeWith(value: TClose): void;
+    /**
+     * Return a subscription for this queue. Useful when using destructuring
+     * assignment.
+     *
+     * ### Example
+     *
+     * ```typescript
+     * import { main, createQueue } from 'effection';
+     *
+     * main(function*() {
+     *   let { send, subscription } = createQueue<number>();
+     *   send(1);
+     *   send(2);
+     *   send(3);
+     *
+     *   yield subscription.forEach((value) => console.log("got number", value));
+     * });
+     * ```
+     */
+    subscription: Subscription<T, TClose>;
 }
-export declare function createQueue<T, TReturn = undefined>(name?: string): Queue<T, TReturn>;
+/**
+ * Creates a new queue. Queues are unlimited in size and sending a message to a
+ * queue is always synchronous.
+ *
+ * ### Example
+ *
+ * ```typescript
+ * import { main, createQueue } from 'effection';
+ *
+ * main(function*() {
+ *   let queue = createQueue<number>();
+ *   queue.send(1);
+ *   queue.send(2);
+ *   queue.send(3);
+ *
+ *   yield queue.forEach((value) => console.log("got number", value));
+ * });
+ * ```
+ *
+ * @param name the name of the returned subscription, useful for debugging
+ * @typeParam T the type of the items in the queue
+ * @typeParam TClose the type of the value that the queue is closed with
+ */
+export declare function createQueue<T, TClose = undefined>(name?: string): Queue<T, TClose>;
+export {};
 //# sourceMappingURL=queue.d.ts.map

dist-esm/queue.js

 import { withLabels, createFuture } from '@effection/core';
+/**
+ * Creates a new queue. Queues are unlimited in size and sending a message to a
+ * queue is always synchronous.
+ *
+ * ### Example
+ *
+ * ```typescript
+ * import { main, createQueue } from 'effection';
+ *
+ * main(function*() {
+ *   let queue = createQueue<number>();
+ *   queue.send(1);
+ *   queue.send(2);
+ *   queue.send(3);
+ *
+ *   yield queue.forEach((value) => console.log("got number", value));
+ * });
+ * ```
+ *
+ * @param name the name of the returned subscription, useful for debugging
+ * @typeParam T the type of the items in the queue
+ * @typeParam TClose the type of the value that the queue is closed with
+ */
 export function createQueue(name = 'queue') {
@@ -6,3 +29,3 @@ let waiters = [];
     let didClose = false;
-    let send = function* (value) {
+    let send = (value) => {
         if (didClose) {
@@ -19,3 +42,3 @@ new Error(`tried to publish a value: ${value} on an already finished queue`);
     };
-    let close = function* (value) {
+    let close = (value) => {
         if (didClose) {
@@ -55,3 +78,4 @@ new Error('tried to close an already closed queue');
         next,
-        close,
+        close: ((...args) => close(args[0])),
+        closeWith: close,
         first() {
@@ -58,0 +82,0 @@ return withName(`first`, function* () {

dist-esm/subscription.d.ts

 import { Operation } from '@effection/core';
 import { OperationIterator } from './operation-iterator';
+/**
+ * A Subscription functions as an iterator over a stream of values. Taking the
+ * next value from the subscription returns the next value and crucially also
+ * removes it, so we don't iterate the same value twice. Subscriptions are
+ * stateful objects, and calling methods such as next or expect on them changes
+ * the state of the subscription.
+ *
+ * See [the guide on Streams and Subscriptions](https://frontside.com/effection/docs/guides/collections) for more details.
+ *
+ * @typeParam T the type of the items in the queue
+ * @typeParam TReturn the type of the value that the subscription finishes with
+ */
 export interface Subscription<T, TReturn = undefined> extends OperationIterator<T, TReturn> {
+    /**
+     * Consume and return the next value of the subscription, if the subscription
+     * finishes before it returns another value then `undefined` is returned.
+     */
     first(): Operation<T | undefined>;
+    /**
+     * Consume and return the next value of the subscription, if the subscription
+     * finishes before it returns another value then an error is thrown.
+     */
     expect(): Operation<T>;
+    /**
+     * Iterate the subscription, passing each value to the given callback. Blocks
+     * until the subscription finishes, and returns the value it finished with.
+     *
+     * The callback can be either a regular function which returns `undefined`,
+     * or an operation. If it is an operation, then `forEach` will block until
+     * the operation is complete before invoking the callback again.
+     *
+     * ### Example
+     *
+     * ```typescript
+     * import { main, createQueue } from 'effection';
+     *
+     * main(function*() {
+     *   let queue = createQueue<number, string>();
+     *   queue.send(1);
+     *   queue.send(2);
+     *   queue.close("I'm done");
+     *
+     *   let result = yield queue.forEach((value) => { console.log(value) }); // => '1', '2'
+     *   console.log(result); // => 'I'm done'
+     * });
+     * ```
+     */
     forEach(visit: (value: T) => (Operation<void> | void)): Operation<TReturn>;
+    /**
+     * Block until the subscription finishes, and return the value it finished
+     * with.
+     *
+     * ### Example
+     *
+     * ```typescript
+     * import { main, createQueue } from 'effection';
+     *
+     * main(function*() {
+     *   let queue = createQueue<number, string>();
+     *   queue.send(1);
+     *   queue.close("I'm done");
+     *
+     *   let result = yield queue.join();
+     *   console.log(result); // => "I'm done"
+     * });
+     * ```
+     */
     join(): Operation<TReturn>;
+    /**
+     * Block until the subscription finishes, and return a synchronous iterator
+     * over all of the emitted values.
+     *
+     * ### Example
+     *
+     * ```typescript
+     * import { main, createQueue } from 'effection';
+     *
+     * main(function*() {
+     *   let queue = createQueue<number, string>();
+     *   queue.send(1);
+     *   queue.close("I'm done");
+     *
+     *   let iterator = yield queue.collect();
+     *
+     *   console.log(iterator.next()); // => { done: false, value: 1 }
+     *   console.log(iterator.next()); // => { done: true, value: "I'm done" }
+     * });
+     * ```
+     */
     collect(): Operation<Iterator<T, TReturn>>;
+    /**
+     * Block until the subscription finishes, and return an array of all of the
+     * emitted values.
+     *
+     * ### Example
+     *
+     * ```typescript
+     * import { main, createQueue } from 'effection';
+     *
+     * main(function*() {
+     *   let queue = createQueue<string>();
+     *   queue.send('hello');
+     *   queue.send('world');
+     *   queue.close();
+     *
+     *   let result = yield queue.toArray();
+     *   console.log(result); // => ['hello', 'world']
+     * });
+     * ```
+     */
     toArray(): Operation<T[]>;
 }
 //# sourceMappingURL=subscription.d.ts.map

package.json

 {
   "name": "@effection/subscription",
-  "version": "2.0.0-v2-writable-unification.1633595877341",
+  "version": "2.0.0",
   "description": "Effection Subscriptions",
@@ -31,3 +31,3 @@ "main": "dist-cjs/index.js",
   "dependencies": {
-    "@effection/core": "2.0.0-v2-writable-unification.1633595877341"
+    "@effection/core": "2.0.0"
   },
@@ -34,0 +34,0 @@ "devDependencies": {

src/index.ts

 export { OperationIterator } from './operation-iterator';
 export { Subscription } from './subscription';
 export { Queue, createQueue } from './queue';
-export { Sink, Close } from './sink';

src/operation-iterator.ts

 import { Operation } from '@effection/core';
 
+/**
+ * @hidden
+ */
 export interface OperationIterator<T, TReturn = undefined> {
   next(): Operation<IteratorResult<T, TReturn>>;
 }

src/queue.ts

 import { Operation, withLabels, createFuture } from '@effection/core';
-import { Subscription, Sink, Close } from './index';
+import { Subscription } from './index';
 
-type Waiter<T, TReturn> = (value: IteratorResult<T, TReturn>) => void;
+type Close<T> = (...args: T extends undefined ? [] : [T]) => void;
 
-export interface Queue<T, TReturn = undefined> extends Subscription<T, TReturn>, Sink<T, TReturn> {
-  subscription: Subscription<T, TReturn>;
+type Waiter<T, TClose> = (value: IteratorResult<T, TClose>) => void;
+
+/**
+ * A queue which can act as a subscription. It can be sent messages to and
+ * which can be closed.
+ *
+ * @typeParam T the type of the items in the queue
+ * @typeParam TClose the type of the value that the queue is closed with
+ */
+export interface Queue<T, TClose = undefined> extends Subscription<T, TClose> {
+  /**
+   * Send a value to the queue.
+   */
+  send(value: T): void;
+
+  /**
+   * Close the queue
+   *
+   * ### Example
+   *
+   * Closing queue with no close value:
+   *
+   * ```typescript
+   * import { main, createQueue } from 'effection';
+   *
+   * main(function*() {
+   *   let queue = createQueue<number>();
+   *   queue.close();
+   *   yield queue.join();
+   * });
+   * ```
+   *
+   * Closing queue with close value:
+   *
+   * ```typescript
+   * import { main, createQueue } from 'effection';
+   *
+   * main(function*() {
+   *   let queue = createQueue<number, string>();
+   *   queue.close("I'm done");
+   *   let value = yield queue.join();
+   *   console.log(value) // => "I'm done"
+   * });
+   * ```
+   */
+  close: Close<TClose>;
+
+  /**
+   * Like {@link close}, but with no special case for closing a queue without a
+   * value, this makes `closeWith` easier to use from generic code.
+   */
+  closeWith(value: TClose): void;
+
+  /**
+   * Return a subscription for this queue. Useful when using destructuring
+   * assignment.
+   *
+   * ### Example
+   *
+   * ```typescript
+   * import { main, createQueue } from 'effection';
+   *
+   * main(function*() {
+   *   let { send, subscription } = createQueue<number>();
+   *   send(1);
+   *   send(2);
+   *   send(3);
+   *
+   *   yield subscription.forEach((value) => console.log("got number", value));
+   * });
+   * ```
+   */
+  subscription: Subscription<T, TClose>;
 }
 
-export function createQueue<T, TReturn = undefined>(name = 'queue'): Queue<T, TReturn> {
-  let waiters: Waiter<T, TReturn>[] = [];
-  let values: IteratorResult<T, TReturn>[] = [];
+/**
+ * Creates a new queue. Queues are unlimited in size and sending a message to a
+ * queue is always synchronous.
+ *
+ * ### Example
+ *
+ * ```typescript
+ * import { main, createQueue } from 'effection';
+ *
+ * main(function*() {
+ *   let queue = createQueue<number>();
+ *   queue.send(1);
+ *   queue.send(2);
+ *   queue.send(3);
+ *
+ *   yield queue.forEach((value) => console.log("got number", value));
+ * });
+ * ```
+ *
+ * @param name the name of the returned subscription, useful for debugging
+ * @typeParam T the type of the items in the queue
+ * @typeParam TClose the type of the value that the queue is closed with
+ */
+export function createQueue<T, TClose = undefined>(name = 'queue'): Queue<T, TClose> {
+  let waiters: Waiter<T, TClose>[] = [];
+  let values: IteratorResult<T, TClose>[] = [];
   let didClose = false;
 
-  let send = function*(value: T): Operation<void> {
+  let send = (value: T): void => {
     if(didClose) {
@@ -28,3 +122,3 @@ new Error(`tried to publish a value: ${value} on an already finished queue`);
 
-  let close = function*(value: TReturn): Operation<void> {
+  let close = (value: TClose) => {
     if(didClose) {
@@ -40,9 +134,9 @@ new Error('tried to close an already closed queue');
     }
-  } as Close<TReturn>;
+  };
 
-  let next = (): Operation<IteratorResult<T, TReturn>> => {
+  let next = (): Operation<IteratorResult<T, TClose>> => {
     return withLabels((task) => {
-      let { future, resolve } = createFuture<IteratorResult<T, TReturn>>();
+      let { future, resolve } = createFuture<IteratorResult<T, TClose>>();
       if(values.length) {
-        resolve(values.shift() as IteratorResult<T, TReturn>);
+        resolve(values.shift() as IteratorResult<T, TClose>);
       } else {
@@ -67,6 +161,7 @@ waiters.push(resolve);
     next,
-    close,
+    close: ((...args) => close(args[0] as TClose)) as Close<TClose>,
+    closeWith: close,
     first(): Operation<T | undefined> {
       return withName<T | undefined>(`first`, function*() {
-        let result: IteratorResult<T, TReturn> = yield next();
+        let result: IteratorResult<T, TClose> = yield next();
         if(result.done) {
@@ -82,3 +177,3 @@ return undefined;
       return withName('expect', function*() {
-        let result: IteratorResult<T, TReturn> = yield next();
+        let result: IteratorResult<T, TClose> = yield next();
         if(result.done) {
@@ -92,6 +187,6 @@ throw new Error('expected to contain a value');
 
-    forEach(visit: (value: T) => (Operation<void> | void)): Operation<TReturn> {
+    forEach(visit: (value: T) => (Operation<void> | void)): Operation<TClose> {
       return withName('forEach', function* forEach() {
         while (true) {
-          let result: IteratorResult<T,TReturn> = yield next();
+          let result: IteratorResult<T,TClose> = yield next();
           if(result.done) {
@@ -109,8 +204,8 @@ return result.value;
 
-    join(): Operation<TReturn> {
+    join(): Operation<TClose> {
       return withName('join', subscription.forEach(() => { /* no op */ }));
     },
 
-    collect(): Operation<Iterator<T, TReturn>> {
-      return withName<Iterator<T, TReturn>>('collect', function*() {
+    collect(): Operation<Iterator<T, TClose>> {
+      return withName<Iterator<T, TClose>>('collect', function*() {
         let items: T[] = [];
@@ -117,0 +212,0 @@ let result = yield subscription.forEach((item) => function*() { items.push(item) });

src/subscription.ts

 import { Operation } from '@effection/core';
 import { OperationIterator } from './operation-iterator';
 
+/**
+ * A Subscription functions as an iterator over a stream of values. Taking the
+ * next value from the subscription returns the next value and crucially also
+ * removes it, so we don't iterate the same value twice. Subscriptions are
+ * stateful objects, and calling methods such as next or expect on them changes
+ * the state of the subscription.
+ *
+ * See [the guide on Streams and Subscriptions](https://frontside.com/effection/docs/guides/collections) for more details.
+ *
+ * @typeParam T the type of the items in the queue
+ * @typeParam TReturn the type of the value that the subscription finishes with
+ */
 export interface Subscription<T, TReturn = undefined> extends OperationIterator<T, TReturn> {
+  /**
+   * Consume and return the next value of the subscription, if the subscription
+   * finishes before it returns another value then `undefined` is returned.
+   */
   first(): Operation<T | undefined>;
+
+  /**
+   * Consume and return the next value of the subscription, if the subscription
+   * finishes before it returns another value then an error is thrown.
+   */
   expect(): Operation<T>;
+
+  /**
+   * Iterate the subscription, passing each value to the given callback. Blocks
+   * until the subscription finishes, and returns the value it finished with.
+   *
+   * The callback can be either a regular function which returns `undefined`,
+   * or an operation. If it is an operation, then `forEach` will block until
+   * the operation is complete before invoking the callback again.
+   *
+   * ### Example
+   *
+   * ```typescript
+   * import { main, createQueue } from 'effection';
+   *
+   * main(function*() {
+   *   let queue = createQueue<number, string>();
+   *   queue.send(1);
+   *   queue.send(2);
+   *   queue.close("I'm done");
+   *
+   *   let result = yield queue.forEach((value) => { console.log(value) }); // => '1', '2'
+   *   console.log(result); // => 'I'm done'
+   * });
+   * ```
+   */
   forEach(visit: (value: T) => (Operation<void> | void)): Operation<TReturn>;
+
+  /**
+   * Block until the subscription finishes, and return the value it finished
+   * with.
+   *
+   * ### Example
+   *
+   * ```typescript
+   * import { main, createQueue } from 'effection';
+   *
+   * main(function*() {
+   *   let queue = createQueue<number, string>();
+   *   queue.send(1);
+   *   queue.close("I'm done");
+   *
+   *   let result = yield queue.join();
+   *   console.log(result); // => "I'm done"
+   * });
+   * ```
+   */
   join(): Operation<TReturn>;
+
+  /**
+   * Block until the subscription finishes, and return a synchronous iterator
+   * over all of the emitted values.
+   *
+   * ### Example
+   *
+   * ```typescript
+   * import { main, createQueue } from 'effection';
+   *
+   * main(function*() {
+   *   let queue = createQueue<number, string>();
+   *   queue.send(1);
+   *   queue.close("I'm done");
+   *
+   *   let iterator = yield queue.collect();
+   *
+   *   console.log(iterator.next()); // => { done: false, value: 1 }
+   *   console.log(iterator.next()); // => { done: true, value: "I'm done" }
+   * });
+   * ```
+   */
   collect(): Operation<Iterator<T, TReturn>>;
+
+  /**
+   * Block until the subscription finishes, and return an array of all of the
+   * emitted values.
+   *
+   * ### Example
+   *
+   * ```typescript
+   * import { main, createQueue } from 'effection';
+   *
+   * main(function*() {
+   *   let queue = createQueue<string>();
+   *   queue.send('hello');
+   *   queue.send('world');
+   *   queue.close();
+   *
+   *   let result = yield queue.toArray();
+   *   console.log(result); // => ['hello', 'world']
+   * });
+   * ```
+   */
   toArray(): Operation<T[]>;
 }

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

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

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

60283

increased by42.11%

Lines of code

1066

increased by137.95%

Number of low quality alerts

0

decreased by-100%

Worsened metrics

Number of package files

39

decreased by-18.75%

Dependency changes

• + Added@effection/core@2.0.0(transitive)

• - Removed@effection/core@2.0.0-v2-writable-unification.1633595877341(transitive)

• Updated@effection/core@2.0.0