it-pushable - npm Package Compare versions

Comparing version 3.1.1 to 3.1.2

dist/src/fifo.d.ts

@@ -1,6 +0,2 @@
-export interface Next<T> {
-    done?: boolean;
-    error?: Error;
-    value?: T;
-}
+import type { Next } from './index.js';
 export interface FIFOOptions {
@@ -7,0 +3,0 @@ /**

dist/src/index.d.ts

@@ -1,4 +0,65 @@
-import { Next } from './fifo.js';
+/**
+ * @packageDocumentation
+ *
+ * An iterable that you can push values into.
+ *
+ * @example
+ *
+ * ```js
+ * import { pushable } from 'it-pushable'
+ *
+ * const source = pushable()
+ *
+ * setTimeout(() => source.push('hello'), 100)
+ * setTimeout(() => source.push('world'), 200)
+ * setTimeout(() => source.end(), 300)
+ *
+ * const start = Date.now()
+ *
+ * for await (const value of source) {
+ *   console.log(`got "${value}" after ${Date.now() - start}ms`)
+ * }
+ * console.log(`done after ${Date.now() - start}ms`)
+ *
+ * // Output:
+ * // got "hello" after 105ms
+ * // got "world" after 207ms
+ * // done after 309ms
+ * ```
+ *
+ * @example
+ *
+ * ```js
+ * import { pushableV } from 'it-pushable'
+ * import all from 'it-all'
+ *
+ * const source = pushableV()
+ *
+ * source.push(1)
+ * source.push(2)
+ * source.push(3)
+ * source.end()
+ *
+ * console.info(await all(source))
+ *
+ * // Output:
+ * // [ [1, 2, 3] ]
+ * ```
+ */
+export interface Next<T> {
+    done?: boolean;
+    error?: Error;
+    value?: T;
+}
 interface BasePushable<T> {
+    /**
+     * End the iterable after all values in the buffer (if any) have been yielded. If an
+     * error is passed the buffer is cleared immediately and the next iteration will
+     * throw the passed error
+     */
     end: (err?: Error) => this;
+    /**
+     * Push a value into the iterable. Values are yielded from the iterable in the order
+     * they are pushed. Values not yet consumed from the iterable are buffered.
+     */
     push: (value: T) => this;
@@ -13,12 +74,29 @@ next: () => Promise<Next<T>>;
     /**
-     * This property contains the number of bytes (or objects) in the queue ready to be read
+     * This property contains the number of bytes (or objects) in the queue ready to be read.
+     *
+     * If `objectMode` is true, this is the number of objects in the queue, if false it's the
+     * total number of bytes in the queue.
      */
     readableLength: number;
 }
+/**
+ * An iterable that you can push values into.
+ */
 export interface Pushable<T> extends AsyncIterable<T>, BasePushable<T> {
 }
+/**
+ * Similar to `pushable`, except it yields multiple buffered chunks at a time. All values yielded from the iterable will be arrays.
+ */
 export interface PushableV<T> extends AsyncIterable<T[]>, BasePushable<T> {
 }
 export interface Options {
+    /**
+     * A boolean value that means non-`Uint8Array`s will be passed to `.push`, default: `false`
+     */
     objectMode?: boolean;
+    /**
+     * A function called after *all* values have been yielded from the iterator (including
+     * buffered values). In the case when the iterator is ended with an error it will be
+     * passed the error as a parameter.
+     */
     onEnd?: (err?: Error) => void;
@@ -32,2 +110,7 @@ }
 }
+/**
+ * Create a new async iterable. The values yielded from calls to `.next()`
+ * or when used in a `for await of`loop are "pushed" into the iterable.
+ * Returns an async iterable object with additional methods.
+ */
 export declare function pushable<T extends {
@@ -34,0 +117,0 @@ byteLength: number;

dist/src/index.js

@@ -0,1 +1,49 @@
+/**
+ * @packageDocumentation
+ *
+ * An iterable that you can push values into.
+ *
+ * @example
+ *
+ * ```js
+ * import { pushable } from 'it-pushable'
+ *
+ * const source = pushable()
+ *
+ * setTimeout(() => source.push('hello'), 100)
+ * setTimeout(() => source.push('world'), 200)
+ * setTimeout(() => source.end(), 300)
+ *
+ * const start = Date.now()
+ *
+ * for await (const value of source) {
+ *   console.log(`got "${value}" after ${Date.now() - start}ms`)
+ * }
+ * console.log(`done after ${Date.now() - start}ms`)
+ *
+ * // Output:
+ * // got "hello" after 105ms
+ * // got "world" after 207ms
+ * // done after 309ms
+ * ```
+ *
+ * @example
+ *
+ * ```js
+ * import { pushableV } from 'it-pushable'
+ * import all from 'it-all'
+ *
+ * const source = pushableV()
+ *
+ * source.push(1)
+ * source.push(2)
+ * source.push(3)
+ * source.end()
+ *
+ * console.info(await all(source))
+ *
+ * // Output:
+ * // [ [1, 2, 3] ]
+ * ```
+ */
 import { FIFO } from './fifo.js';
@@ -2,0 +50,0 @@ export function pushable(options = {}) {

package.json

 {
   "name": "it-pushable",
-  "version": "3.1.1",
-  "description": "Pushable iterable",
+  "version": "3.1.2",
+  "description": "An iterable that you can push values into",
+  "author": "Alan Shaw",
+  "license": "Apache-2.0 OR MIT",
+  "homepage": "https://github.com/alanshaw/it-pushable#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alanshaw/it-pushable.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alanshaw/it-pushable/issues"
+  },
+  "keywords": [
+    "iterable",
+    "iterator",
+    "push",
+    "pushable"
+  ],
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=7.0.0"
+  },
   "type": "module",
@@ -9,3 +29,3 @@ "types": "./dist/src/index.d.ts",
     "src",
-    "dist/src",
+    "dist",
     "!dist/test",
@@ -16,2 +36,3 @@ "!**/*.tsbuildinfo"
     ".": {
+      "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
@@ -53,11 +74,11 @@ }
             {
-              "type": "chore",
+              "type": "docs",
               "release": "patch"
             },
             {
-              "type": "docs",
+              "type": "test",
               "release": "patch"
             },
             {
-              "type": "test",
+              "type": "deps",
               "release": "patch"
@@ -92,5 +113,9 @@ },
                 "type": "docs",
-                "section": "Trivial Changes"
+                "section": "Documentation"
               },
               {
+                "type": "deps",
+                "section": "Dependencies"
+              },
+              {
                 "type": "test",
@@ -121,27 +146,12 @@ "section": "Tests"
     "test:electron-main": "aegir test -t electron-main",
-    "release": "aegir release"
+    "release": "aegir release",
+    "docs": "aegir docs"
   },
-  "keywords": [
-    "push",
-    "iterable",
-    "iterator",
-    "pushable"
-  ],
-  "author": "Alan Shaw",
-  "license": "MIT",
   "devDependencies": {
     "@types/fast-fifo": "^1.0.0",
-    "aegir": "^37.0.17",
+    "aegir": "^37.7.8",
     "it-all": "^2.0.0",
     "it-pipe": "^2.0.0",
     "uint8arraylist": "^2.0.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/alanshaw/it-pushable.git"
-  },
-  "bugs": {
-    "url": "https://github.com/alanshaw/it-pushable/issues"
-  },
-  "homepage": "https://github.com/alanshaw/it-pushable#readme"
+  }
 }

README.md

@@ -1,15 +0,32 @@
-# it-pushable
+# it-pushable <!-- omit in toc -->
 
-[![Build Status](https://github.com/alanshaw/it-pushable/actions/workflows/js-test-and-release.yml/badge.svg?branch=master)](https://github.com/alanshaw/it-pushable/actions/workflows/js-test-and-release.yml)
-[![Dependencies Status](https://david-dm.org/alanshaw/it-pushable/status.svg)](https://david-dm.org/alanshaw/it-pushable)
-[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
+[![codecov](https://img.shields.io/codecov/c/github/alanshaw/it-pushable.svg?style=flat-square)](https://codecov.io/gh/alanshaw/it-pushable)
+[![CI](https://img.shields.io/github/actions/workflow/status/alanshaw/it-pushable/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/alanshaw/it-pushable/actions/workflows/js-test-and-release.yml?query=branch%3Amaster)
 
 > An iterable that you can push values into
 
+## Table of contents <!-- omit in toc -->
+
+- [Install](#install)
+  - [Browser `<script>` tag](#browser-script-tag)
+- [Usage](#usage)
+- [Related](#related)
+- [API Docs](#api-docs)
+- [License](#license)
+- [Contribution](#contribution)
+
 ## Install
 
-```sh
-npm install it-pushable
+```console
+$ npm i it-pushable
 ```
 
+### Browser `<script>` tag
+
+Loading this module through a script tag will make it's exports available as `ItPushable` in the global namespace.
+
+```html
+<script src="https://unpkg.com/it-pushable/dist/index.min.js"></script>
+```
+
 ## Usage
@@ -59,31 +76,19 @@
 
-## API
+## Related
 
-### `pushable([options])`
+- [`it-pipe`](https://www.npmjs.com/package/it-pipe) Utility to "pipe" async iterables together
 
-Create a new async iterable. The values yielded from calls to `.next()` or when used in a `for await of` loop are "pushed" into the iterable. Returns an async iterable object with the following additional methods:
+## API Docs
 
-* `.push(value)` - push a value into the iterable. Values are yielded from the iterable in the order they are pushed. Values not yet consumed from the iterable are buffered
-* `.end([err])` - end the iterable after all values in the buffer (if any) have been yielded. If an error is passed the buffer is cleared immediately and the next iteration will throw the passed error
-* `.readableLength` - a number that represents the size of the queue. if `objectMode` is true, this is the number of objects in the queue, if false it's the total number of bytes in the queue
+- <https://alanshaw.github.io/it-pushable>
 
-`options` is an _optional_ parameter, an object with the following properties:
+## License
 
-* `onEnd` - a function called after _all_ values have been yielded from the iterator (including buffered values). In the case when the iterator is ended with an error it will be passed the error as a parameter.
-* `objectMode` - a boolean value that means non-`Uint8Array`s will be passed to `.push`, default: `false`
+Licensed under either of
 
-### `pushableV([options])`
+- Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT ([LICENSE-MIT](LICENSE-MIT) / <http://opensource.org/licenses/MIT>)
 
-Similar to `pushable`, except it yields multiple buffered chunks at a time. All values yielded from the iterable will be arrays.
+## Contribution
 
-## Related
-
-* [`it-pipe`](https://www.npmjs.com/package/it-pipe) Utility to "pipe" async iterables together
-
-## Contribute
-
-Feel free to dive in! [Open an issue](https://github.com/alanshaw/it-pushable/issues/new) or submit PRs.
-
-## License
-
-[MIT](LICENSE) © Alan Shaw
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

src/fifo.ts

 // ported from https://www.npmjs.com/package/fast-fifo
 
-export interface Next<T> {
-  done?: boolean
-  error?: Error
-  value?: T
-}
+import type { Next } from './index.js'
+
 class FixedFIFO<T> {
@@ -9,0 +6,0 @@ public buffer: Array<Next<T> | undefined>

src/index.ts

@@ -1,5 +0,70 @@
-import { FIFO, Next } from './fifo.js'
+/**
+ * @packageDocumentation
+ *
+ * An iterable that you can push values into.
+ *
+ * @example
+ *
+ * ```js
+ * import { pushable } from 'it-pushable'
+ *
+ * const source = pushable()
+ *
+ * setTimeout(() => source.push('hello'), 100)
+ * setTimeout(() => source.push('world'), 200)
+ * setTimeout(() => source.end(), 300)
+ *
+ * const start = Date.now()
+ *
+ * for await (const value of source) {
+ *   console.log(`got "${value}" after ${Date.now() - start}ms`)
+ * }
+ * console.log(`done after ${Date.now() - start}ms`)
+ *
+ * // Output:
+ * // got "hello" after 105ms
+ * // got "world" after 207ms
+ * // done after 309ms
+ * ```
+ *
+ * @example
+ *
+ * ```js
+ * import { pushableV } from 'it-pushable'
+ * import all from 'it-all'
+ *
+ * const source = pushableV()
+ *
+ * source.push(1)
+ * source.push(2)
+ * source.push(3)
+ * source.end()
+ *
+ * console.info(await all(source))
+ *
+ * // Output:
+ * // [ [1, 2, 3] ]
+ * ```
+ */
 
+import { FIFO } from './fifo.js'
+
+export interface Next<T> {
+  done?: boolean
+  error?: Error
+  value?: T
+}
+
 interface BasePushable<T> {
+  /**
+   * End the iterable after all values in the buffer (if any) have been yielded. If an
+   * error is passed the buffer is cleared immediately and the next iteration will
+   * throw the passed error
+   */
   end: (err?: Error) => this
+
+  /**
+   * Push a value into the iterable. Values are yielded from the iterable in the order
+   * they are pushed. Values not yet consumed from the iterable are buffered.
+   */
   push: (value: T) => this
@@ -11,3 +76,6 @@ next: () => Promise<Next<T>>
   /**
-   * This property contains the number of bytes (or objects) in the queue ready to be read
+   * This property contains the number of bytes (or objects) in the queue ready to be read.
+   *
+   * If `objectMode` is true, this is the number of objects in the queue, if false it's the
+   * total number of bytes in the queue.
    */
@@ -17,7 +85,23 @@ readableLength: number
 
+/**
+ * An iterable that you can push values into.
+ */
 export interface Pushable<T> extends AsyncIterable<T>, BasePushable<T> {}
+
+/**
+ * Similar to `pushable`, except it yields multiple buffered chunks at a time. All values yielded from the iterable will be arrays.
+ */
 export interface PushableV<T> extends AsyncIterable<T[]>, BasePushable<T> {}
 
 export interface Options {
+  /**
+   * A boolean value that means non-`Uint8Array`s will be passed to `.push`, default: `false`
+   */
   objectMode?: boolean
+
+  /**
+   * A function called after *all* values have been yielded from the iterator (including
+   * buffered values). In the case when the iterator is ended with an error it will be
+   * passed the error as a parameter.
+   */
   onEnd?: (err?: Error) => void
@@ -38,2 +122,7 @@ }
 
+/**
+ * Create a new async iterable. The values yielded from calls to `.next()`
+ * or when used in a `for await of`loop are "pushed" into the iterable.
+ * Returns an async iterable object with additional methods.
+ */
 export function pushable<T extends { byteLength: number } = Uint8Array> (options?: BytePushableOptions): Pushable<T>
@@ -40,0 +129,0 @@ export function pushable<T> (options: ObjectPushableOptions): Pushable<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

Unidentified License

License

(Experimental) Something that seems like a license was found, but its contents could not be matched with a known license.

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

Improved metrics

Total package byte prevSize

40153

increased by25.33%

Number of package files

15

increased by15.38%

Lines of code

811

increased by39.35%

Number of lines in readme file

94

increased by5.62%

Worsened metrics

Number of low license alerts

1

increased byInfinity%

License quality

80

decreased by-20%

No dependency changes