From b5d17af750dfa2191423dcf06f37b06e5a866ec8 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 15 Nov 2023 12:18:00 +0000 Subject: [PATCH] deps(dev): bump aegir from 40.0.13 to 41.1.9 (#98) Bumps [aegir](https://github.com/ipfs/aegir) from 40.0.13 to 41.1.9. - [Release notes](https://github.com/ipfs/aegir/releases) - [Changelog](https://github.com/ipfs/aegir/blob/master/CHANGELOG.md) - [Commits](https://github.com/ipfs/aegir/compare/v40.0.13...v41.1.9) --- updated-dependencies: - dependency-name: aegir dependency-type: direct:development update-type: version-update:semver-major ... --------- Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: achingbrain --- .github/workflows/js-test-and-release.yml | 189 ++---------------- .github/workflows/semantic-pull-request.yml | 12 ++ .github/workflows/stale.yml | 13 ++ .github/workflows/test.yml | 98 --------- README.md | 16 +- package.json | 5 +- packages/blob-to-it/README.md | 44 ++-- packages/blob-to-it/package.json | 3 +- packages/blob-to-it/src/index.ts | 19 +- packages/blob-to-it/typedoc.json | 5 + .../browser-readablestream-to-it/README.md | 47 ++--- .../browser-readablestream-to-it/package.json | 3 +- .../browser-readablestream-to-it/src/index.ts | 42 ++++ .../browser-readablestream-to-it/typedoc.json | 5 + packages/it-all/README.md | 44 ++-- packages/it-all/package.json | 3 +- packages/it-all/src/index.ts | 33 +++ packages/it-all/typedoc.json | 5 + packages/it-batch/README.md | 46 ++--- packages/it-batch/package.json | 3 +- packages/it-batch/src/index.ts | 37 ++++ packages/it-batch/typedoc.json | 5 + packages/it-batched-bytes/README.md | 44 ++-- packages/it-batched-bytes/package.json | 3 +- packages/it-batched-bytes/src/index.ts | 49 ++++- packages/it-batched-bytes/typedoc.json | 5 + packages/it-buffer-stream/README.md | 44 ++-- packages/it-buffer-stream/package.json | 3 +- packages/it-buffer-stream/src/index.ts | 40 +++- packages/it-buffer-stream/typedoc.json | 5 + packages/it-byte-stream/README.md | 62 ++---- packages/it-byte-stream/package.json | 3 +- packages/it-byte-stream/src/index.ts | 6 +- packages/it-byte-stream/test/index.spec.ts | 10 +- packages/it-byte-stream/typedoc.json | 5 + packages/it-drain/README.md | 44 ++-- packages/it-drain/package.json | 3 +- packages/it-drain/src/index.ts | 29 +++ packages/it-drain/typedoc.json | 5 + packages/it-filter/README.md | 44 ++-- packages/it-filter/package.json | 3 +- packages/it-filter/src/index.ts | 39 ++++ packages/it-filter/typedoc.json | 5 + packages/it-first/README.md | 46 ++--- packages/it-first/package.json | 3 +- packages/it-first/src/index.ts | 33 +++ packages/it-first/typedoc.json | 5 + packages/it-flat-batch/README.md | 44 ++-- packages/it-flat-batch/package.json | 3 +- packages/it-flat-batch/src/index.ts | 37 ++++ packages/it-flat-batch/typedoc.json | 5 + packages/it-foreach/README.md | 46 ++--- packages/it-foreach/package.json | 3 +- packages/it-foreach/src/index.ts | 41 ++++ packages/it-foreach/typedoc.json | 5 + packages/it-glob/README.md | 29 +-- packages/it-glob/package.json | 3 +- packages/it-glob/src/index.ts | 26 +++ packages/it-glob/typedoc.json | 5 + packages/it-last/README.md | 46 ++--- packages/it-last/package.json | 3 +- packages/it-last/src/index.ts | 33 +++ packages/it-last/typedoc.json | 5 + packages/it-length-prefixed-stream/README.md | 62 +++--- .../it-length-prefixed-stream/package.json | 3 +- .../it-length-prefixed-stream/src/index.ts | 18 +- .../test/index.spec.ts | 10 +- .../it-length-prefixed-stream/typedoc.json | 5 + packages/it-length/README.md | 44 ++-- packages/it-length/package.json | 3 +- packages/it-length/src/index.ts | 35 ++++ packages/it-length/typedoc.json | 5 + packages/it-map/README.md | 44 ++-- packages/it-map/package.json | 3 +- packages/it-map/src/index.ts | 33 +++ packages/it-map/typedoc.json | 5 + packages/it-merge/README.md | 44 ++-- packages/it-merge/package.json | 3 +- packages/it-merge/src/index.ts | 42 ++++ packages/it-merge/typedoc.json | 5 + packages/it-multipart/README.md | 25 +-- packages/it-multipart/package.json | 3 +- packages/it-multipart/src/index.ts | 35 ++++ packages/it-multipart/typedoc.json | 5 + packages/it-ndjson/README.md | 44 ++-- packages/it-ndjson/package.json | 3 +- packages/it-ndjson/src/index.ts | 24 +++ packages/it-ndjson/typedoc.json | 5 + packages/it-parallel-batch/README.md | 46 ++--- packages/it-parallel-batch/package.json | 5 +- packages/it-parallel-batch/src/index.ts | 41 ++++ packages/it-parallel-batch/typedoc.json | 5 + packages/it-parallel/README.md | 46 ++--- packages/it-parallel/package.json | 5 +- packages/it-parallel/src/index.ts | 72 ++++++- packages/it-parallel/typedoc.json | 5 + packages/it-peekable/README.md | 44 ++-- packages/it-peekable/package.json | 3 +- packages/it-peekable/src/index.ts | 63 +++++- packages/it-peekable/typedoc.json | 5 + packages/it-protobuf-stream/README.md | 63 +++--- packages/it-protobuf-stream/package.json | 3 +- packages/it-protobuf-stream/src/index.ts | 18 +- packages/it-protobuf-stream/typedoc.json | 5 + packages/it-reduce/README.md | 46 ++--- packages/it-reduce/package.json | 3 +- packages/it-reduce/src/index.ts | 33 +++ packages/it-reduce/typedoc.json | 5 + packages/it-skip/README.md | 46 ++--- packages/it-skip/package.json | 3 +- packages/it-skip/src/index.ts | 35 ++++ packages/it-skip/typedoc.json | 5 + packages/it-sort/README.md | 44 ++-- packages/it-sort/package.json | 3 +- packages/it-sort/src/index.ts | 43 ++++ packages/it-sort/typedoc.json | 5 + packages/it-split/README.md | 44 ++-- packages/it-split/package.json | 3 +- packages/it-split/src/index.ts | 60 ++++++ packages/it-split/typedoc.json | 5 + packages/it-take/README.md | 46 ++--- packages/it-take/package.json | 3 +- packages/it-take/src/index.ts | 35 ++++ packages/it-take/typedoc.json | 5 + .../it-to-browser-readablestream/README.md | 44 ++-- .../it-to-browser-readablestream/package.json | 3 +- .../it-to-browser-readablestream/src/index.ts | 21 ++ .../it-to-browser-readablestream/typedoc.json | 5 + packages/it-to-buffer/README.md | 44 ++-- packages/it-to-buffer/package.json | 3 +- packages/it-to-buffer/src/index.ts | 34 ++++ packages/it-to-buffer/typedoc.json | 5 + 132 files changed, 1940 insertions(+), 1177 deletions(-) create mode 100644 .github/workflows/semantic-pull-request.yml create mode 100644 .github/workflows/stale.yml delete mode 100644 .github/workflows/test.yml create mode 100644 packages/blob-to-it/typedoc.json create mode 100644 packages/browser-readablestream-to-it/typedoc.json create mode 100644 packages/it-all/typedoc.json create mode 100644 packages/it-batch/typedoc.json create mode 100644 packages/it-batched-bytes/typedoc.json create mode 100644 packages/it-buffer-stream/typedoc.json create mode 100644 packages/it-byte-stream/typedoc.json create mode 100644 packages/it-drain/typedoc.json create mode 100644 packages/it-filter/typedoc.json create mode 100644 packages/it-first/typedoc.json create mode 100644 packages/it-flat-batch/typedoc.json create mode 100644 packages/it-foreach/typedoc.json create mode 100644 packages/it-glob/typedoc.json create mode 100644 packages/it-last/typedoc.json create mode 100644 packages/it-length-prefixed-stream/typedoc.json create mode 100644 packages/it-length/typedoc.json create mode 100644 packages/it-map/typedoc.json create mode 100644 packages/it-merge/typedoc.json create mode 100644 packages/it-multipart/typedoc.json create mode 100644 packages/it-ndjson/typedoc.json create mode 100644 packages/it-parallel-batch/typedoc.json create mode 100644 packages/it-parallel/typedoc.json create mode 100644 packages/it-peekable/typedoc.json create mode 100644 packages/it-protobuf-stream/typedoc.json create mode 100644 packages/it-reduce/typedoc.json create mode 100644 packages/it-skip/typedoc.json create mode 100644 packages/it-sort/typedoc.json create mode 100644 packages/it-split/typedoc.json create mode 100644 packages/it-take/typedoc.json create mode 100644 packages/it-to-browser-readablestream/typedoc.json create mode 100644 packages/it-to-buffer/typedoc.json diff --git a/.github/workflows/js-test-and-release.yml b/.github/workflows/js-test-and-release.yml index 13232aab..2c7a14bb 100644 --- a/.github/workflows/js-test-and-release.yml +++ b/.github/workflows/js-test-and-release.yml @@ -1,182 +1,25 @@ name: test & maybe release + on: push: branches: - master pull_request: + workflow_dispatch: -jobs: - - check: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - with: - node-version: lts/* - - uses: ipfs/aegir/actions/cache-node-modules@master - - run: npm run --if-present lint - - run: npm run --if-present dep-check - - run: npm run --if-present doc-check - - test-node: - needs: check - runs-on: ${{ matrix.os }} - strategy: - matrix: - os: [windows-latest, ubuntu-latest, macos-latest] - node: [lts/*] - fail-fast: true - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - with: - node-version: ${{ matrix.node }} - - uses: ipfs/aegir/actions/cache-node-modules@master - - run: npm run --if-present test:node - - uses: codecov/codecov-action@d9f34f8cd5cb3b3eb79b3e4b5dae3a16df499a70 # v3.1.1 - with: - flags: node - - test-chrome: - needs: check - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - with: - node-version: lts/* - - uses: ipfs/aegir/actions/cache-node-modules@master - - run: npm run --if-present test:chrome - - uses: codecov/codecov-action@d9f34f8cd5cb3b3eb79b3e4b5dae3a16df499a70 # v3.1.1 - with: - flags: chrome - - test-chrome-webworker: - needs: check - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - with: - node-version: lts/* - - uses: ipfs/aegir/actions/cache-node-modules@master - - run: npm run --if-present test:chrome-webworker - - uses: codecov/codecov-action@d9f34f8cd5cb3b3eb79b3e4b5dae3a16df499a70 # v3.1.1 - with: - flags: chrome-webworker +permissions: + contents: write + packages: write - test-firefox: - needs: check - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - with: - node-version: lts/* - - uses: ipfs/aegir/actions/cache-node-modules@master - - run: npm run --if-present test:firefox - - uses: codecov/codecov-action@d9f34f8cd5cb3b3eb79b3e4b5dae3a16df499a70 # v3.1.1 - with: - flags: firefox +concurrency: + group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event_name == 'push' && github.sha || github.ref }} + cancel-in-progress: true - test-firefox-webworker: - needs: check - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - with: - node-version: lts/* - - uses: ipfs/aegir/actions/cache-node-modules@master - - run: npm run --if-present test:firefox-webworker - - uses: codecov/codecov-action@d9f34f8cd5cb3b3eb79b3e4b5dae3a16df499a70 # v3.1.1 - with: - flags: firefox-webworker - - test-webkit: - needs: check - runs-on: ${{ matrix.os }} - strategy: - matrix: - os: [ubuntu-latest, macos-latest] - node: [lts/*] - fail-fast: true - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - with: - node-version: lts/* - - uses: ipfs/aegir/actions/cache-node-modules@master - - run: npm run --if-present test:webkit - - uses: codecov/codecov-action@d9f34f8cd5cb3b3eb79b3e4b5dae3a16df499a70 # v3.1.1 - with: - flags: webkit - - test-webkit-webworker: - needs: check - runs-on: ${{ matrix.os }} - strategy: - matrix: - os: [ubuntu-latest, macos-latest] - node: [lts/*] - fail-fast: true - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - with: - node-version: lts/* - - uses: ipfs/aegir/actions/cache-node-modules@master - - run: npm run --if-present test:webkit-webworker - - uses: codecov/codecov-action@d9f34f8cd5cb3b3eb79b3e4b5dae3a16df499a70 # v3.1.1 - with: - flags: webkit-webworker - - test-electron-main: - needs: check - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - with: - node-version: lts/* - - uses: ipfs/aegir/actions/cache-node-modules@master - - run: npx xvfb-maybe npm run --if-present test:electron-main - - uses: codecov/codecov-action@d9f34f8cd5cb3b3eb79b3e4b5dae3a16df499a70 # v3.1.1 - with: - flags: electron-main - - test-electron-renderer: - needs: check - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 - with: - node-version: lts/* - - uses: ipfs/aegir/actions/cache-node-modules@master - - run: npx xvfb-maybe npm run --if-present test:electron-renderer - - uses: codecov/codecov-action@d9f34f8cd5cb3b3eb79b3e4b5dae3a16df499a70 # v3.1.1 - with: - flags: electron-renderer - - release: - needs: [test-node, test-chrome, test-chrome-webworker, test-firefox, test-firefox-webworker, test-webkit, test-webkit-webworker, test-electron-main, test-electron-renderer] - runs-on: ubuntu-latest - if: github.event_name == 'push' && github.ref == 'refs/heads/master' - steps: - - uses: actions/checkout@v3 - with: - fetch-depth: 0 - - uses: actions/setup-node@v3 - with: - node-version: lts/* - - uses: ipfs/aegir/actions/cache-node-modules@master - - uses: ipfs/aegir/actions/docker-login@master - with: - docker-token: ${{ secrets.DOCKER_TOKEN }} - docker-username: ${{ secrets.DOCKER_USERNAME }} - - run: npm run --if-present release - env: - GITHUB_TOKEN: ${{ secrets.UCI_GITHUB_TOKEN || github.token }} - NPM_TOKEN: ${{ secrets.NPM_TOKEN }} +jobs: + js-test-and-release: + uses: pl-strflt/uci/.github/workflows/js-test-and-release.yml@v0.0 + secrets: + DOCKER_TOKEN: ${{ secrets.DOCKER_TOKEN }} + DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }} + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} + UCI_GITHUB_TOKEN: ${{ secrets.UCI_GITHUB_TOKEN }} diff --git a/.github/workflows/semantic-pull-request.yml b/.github/workflows/semantic-pull-request.yml new file mode 100644 index 00000000..bd00f090 --- /dev/null +++ b/.github/workflows/semantic-pull-request.yml @@ -0,0 +1,12 @@ +name: Semantic PR + +on: + pull_request_target: + types: + - opened + - edited + - synchronize + +jobs: + main: + uses: pl-strflt/.github/.github/workflows/reusable-semantic-pull-request.yml@v0.3 diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml new file mode 100644 index 00000000..16d65d72 --- /dev/null +++ b/.github/workflows/stale.yml @@ -0,0 +1,13 @@ +name: Close and mark stale issue + +on: + schedule: + - cron: '0 0 * * *' + +permissions: + issues: write + pull-requests: write + +jobs: + stale: + uses: pl-strflt/.github/.github/workflows/reusable-stale-issue.yml@v0.3 diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml deleted file mode 100644 index 398bbe88..00000000 --- a/.github/workflows/test.yml +++ /dev/null @@ -1,98 +0,0 @@ -name: Test -on: - pull_request: - branches: - - master - -jobs: - - build: - name: Build - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v2 - with: - node-version: 16 - - uses: actions/cache@v2 - id: cache - env: - CACHE_NAME: cache-node-modules - with: - path: | - ~/.npm - ./node_modules - ./packages/*/node_modules - ./packages/*/dist - key: ${{ runner.os }}-build-${{ env.CACHE_NAME }}-${{ github.event.pull_request.head.sha }} - - name: Install Dependencies - if: steps.cache.outputs.cache-hit != 'true' - run: | - npm install - npm run build --if-present - npm run link --if-present - - check: - name: Check - needs: build - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v2 - with: - node-version: 16 - - uses: actions/cache@v2 - id: cache - env: - CACHE_NAME: cache-node-modules - with: - path: | - ~/.npm - ./node_modules - ./packages/*/node_modules - ./packages/*/dist - key: ${{ runner.os }}-build-${{ env.CACHE_NAME }}-${{ github.event.pull_request.head.sha }} - - name: Install Dependencies - if: steps.cache.outputs.cache-hit != 'true' - run: | - npm install - npm run build --if-present - npm run link --if-present - - run: | - npm run lint --if-present - npm run dep-check --if-present -- -- -- -p - npm run dep-check --if-present -- -- -- -- --unused - - test-node: - name: Unit tests ${{ matrix.project }} node ${{ matrix.node }} ${{ matrix.os }} - needs: build - runs-on: ${{ matrix.os }} - strategy: - matrix: - os: [windows-latest, ubuntu-latest, macos-latest] - node: [16] - steps: - - uses: actions/checkout@v2 - with: - fetch-depth: 0 - - uses: actions/setup-node@v2 - with: - node-version: ${{ matrix.node }} - - uses: actions/cache@v2 - id: cache - env: - CACHE_NAME: cache-node-modules - with: - path: | - ~/.npm - ./node_modules - ./packages/*/node_modules - ./packages/*/dist - key: ${{ runner.os }}-build-${{ env.CACHE_NAME }}-${{ github.event.pull_request.head.sha }} - - name: Install Dependencies - if: steps.cache.outputs.cache-hit != 'true' - run: | - npm install - npm run build --if-present - npm run link --if-present - - run: npm run test -- --since ${{ github.event.pull_request.base.sha }} --concurrency 1 diff --git a/README.md b/README.md index bcf0d6c2..d114bde9 100644 --- a/README.md +++ b/README.md @@ -5,13 +5,7 @@ > A collection of utilities for making working with iterables more bearable -## Table of contents - -- [Structure](#structure) -- [License](#license) -- [Contribution](#contribution) - -## Structure +# Packages - [`/packages/blob-to-it`](./packages/blob-to-it) Turns a blob into an async iterator - [`/packages/browser-readablestream-to-it`](./packages/browser-readablestream-to-it) Turns a browser readble stream into an async iterator @@ -33,8 +27,8 @@ - [`/packages/it-merge`](./packages/it-merge) Treat one or more iterables as a single iterable - [`/packages/it-multipart`](./packages/it-multipart) Async iterable http multipart message parser - [`/packages/it-ndjson`](./packages/it-ndjson) Parse iterators as ndjson and transform iterators to ndjson -- [`/packages/it-parallel`](./packages/it-parallel) Takes an (async) iterable that emits promise-returning functions, invokes them in parallel up to the concurrency limit and emits the results as they become available, optionally in the same order as the input -- [`/packages/it-parallel-batch`](./packages/it-parallel-batch) Takes an async iterator that emits promise-returning functions, invokes them in parallel and emits the results in the same order as the input +- [`/packages/it-parallel`](./packages/it-parallel) Process incoming async(iterable) functions in parallel +- [`/packages/it-parallel-batch`](./packages/it-parallel-batch) Process (async)iterable values as functions with concurrency control - [`/packages/it-peekable`](./packages/it-peekable) Allows peeking/pushing an iterable - [`/packages/it-protobuf-stream`](./packages/it-protobuf-stream) Read and write protobuf messages over a duplex stream - [`/packages/it-reduce`](./packages/it-reduce) Reduces the values yielded from an async iterator @@ -45,13 +39,13 @@ - [`/packages/it-to-browser-readablestream`](./packages/it-to-browser-readablestream) Takes an async iterator and turns it into a browser readable stream - [`/packages/it-to-buffer`](./packages/it-to-buffer) Takes an async iterator that yields buffers and concatenates them all together -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/package.json b/package.json index 74b511d3..efc4168c 100644 --- a/package.json +++ b/package.json @@ -20,10 +20,11 @@ "clean": "aegir run clean", "lint": "aegir run lint", "dep-check": "aegir run dep-check", - "release": "aegir run release" + "release": "aegir run release", + "docs": "aegir docs" }, "devDependencies": { - "aegir": "^40.0.11" + "aegir": "^41.1.9" }, "workspaces": [ "packages/*" diff --git a/packages/blob-to-it/README.md b/packages/blob-to-it/README.md index 948bd618..78a84c01 100644 --- a/packages/blob-to-it/README.md +++ b/packages/blob-to-it/README.md @@ -1,33 +1,13 @@ -# blob-to-it - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Turns a blob into an async iterator -## Table of contents - -- [Install](#install) - - [Browser ` -``` +Allows reading Blob contents as an async iterator. -## Usage +## Example ```javascript import toIt from 'blob-to-it' @@ -40,13 +20,27 @@ const arr = await all(toIt(blob)) console.info(arr) // [ [ 0, 1, 2, 3, 4 ] ] ``` -## License +# Install + +```console +$ npm i blob-to-it +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/blob-to-it/package.json b/packages/blob-to-it/package.json index 5776ebf4..1222570d 100644 --- a/packages/blob-to-it/package.json +++ b/packages/blob-to-it/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -133,7 +134,7 @@ "browser-readablestream-to-it": "^2.0.0" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "it-all": "^3.0.0" } } diff --git a/packages/blob-to-it/src/index.ts b/packages/blob-to-it/src/index.ts index 2035e548..ae8f6fc5 100644 --- a/packages/blob-to-it/src/index.ts +++ b/packages/blob-to-it/src/index.ts @@ -1,4 +1,21 @@ -/* eslint-env browser */ +/** + * @packageDocumentation + * + * Allows reading Blob contents as an async iterator. + * + * @example + * + * ```javascript + * import toIt from 'blob-to-it' + * import all from 'it-all' + * + * const content = [ Uint8Array.from([0, 1, 2, 3, 4]) ] + * const blob = new Blob(content) + * const arr = await all(toIt(blob)) + * + * console.info(arr) // [ [ 0, 1, 2, 3, 4 ] ] + * ``` + */ import browserReadableStreamToIt from 'browser-readablestream-to-it' diff --git a/packages/blob-to-it/typedoc.json b/packages/blob-to-it/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/blob-to-it/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/browser-readablestream-to-it/README.md b/packages/browser-readablestream-to-it/README.md index 17516727..fc723e05 100644 --- a/packages/browser-readablestream-to-it/README.md +++ b/packages/browser-readablestream-to-it/README.md @@ -1,34 +1,13 @@ -# browser-readablestream-to-it - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Turns a browser readble stream into an async iterator -## Table of contents - -- [Install](#install) - - [Browser ` -``` +Allows treating a browser readable stream as an async iterator. -## Usage +## Example ```javascript import toIt from 'browser-readablestream-to-it' @@ -51,7 +30,7 @@ const arr = await all(toIt(stream)) console.info(arr) // 0, 1, 2, 3, 4 ``` -### preventCancel +## preventCancel By default a readable stream will have [.cancel](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream/cancel) called on it once it has ended or reading has stopped prematurely. @@ -64,13 +43,27 @@ const arr = await all(toIt(stream, { preventCancel: true })) console.info(arr) // 0, 1, 2, 3, 4 ``` -## License +# Install + +```console +$ npm i browser-readablestream-to-it +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/browser-readablestream-to-it/package.json b/packages/browser-readablestream-to-it/package.json index c1dfb894..0fd40aa7 100644 --- a/packages/browser-readablestream-to-it/package.json +++ b/packages/browser-readablestream-to-it/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -130,7 +131,7 @@ "release": "aegir release" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "it-all": "^3.0.0" } } diff --git a/packages/browser-readablestream-to-it/src/index.ts b/packages/browser-readablestream-to-it/src/index.ts index 2cc54d3a..83fad801 100644 --- a/packages/browser-readablestream-to-it/src/index.ts +++ b/packages/browser-readablestream-to-it/src/index.ts @@ -1,3 +1,45 @@ +/** + * @packageDocumentation + * + * Allows treating a browser readable stream as an async iterator. + * + * @example + * + * ```javascript + * import toIt from 'browser-readablestream-to-it' + * import all from 'it-all' + * + * const content = [0, 1, 2, 3, 4] + * + * const stream = new ReadableStream({ + * start(controller) { + * for (let i = 0; i < content.length; i++) { + * controller.enqueue(content[i]) + * } + * + * controller.close() + * } + * }) + * + * const arr = await all(toIt(stream)) + * + * console.info(arr) // 0, 1, 2, 3, 4 + * ``` + * + * ## preventCancel + * + * By default a readable stream will have [.cancel](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream/cancel) called on it once it has ended or + * reading has stopped prematurely. + * + * To prevent this behaviour, pass `preventCancel: true` as an option: + * + * ```javascript + * const arr = await all(toIt(stream, { preventCancel: true })) + * + * console.info(arr) // 0, 1, 2, 3, 4 + * ``` + */ + export interface BrowserReadableStreamToItOptions { preventCancel?: boolean } diff --git a/packages/browser-readablestream-to-it/typedoc.json b/packages/browser-readablestream-to-it/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/browser-readablestream-to-it/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-all/README.md b/packages/it-all/README.md index 58470011..21a472c8 100644 --- a/packages/it-all/README.md +++ b/packages/it-all/README.md @@ -1,35 +1,13 @@ -# it-all - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Collects all values from an (async) iterable and returns them as an array -## Table of contents - -- [Install](#install) - - [Browser ` -``` +# About For when you need a one-liner to collect iterable values. -## Usage +## Example ```javascript import all from 'it-all' @@ -56,13 +34,27 @@ const arr = await all(values()) console.info(arr) // 0, 1, 2, 3, 4 ``` -## License +# Install + +```console +$ npm i it-all +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-all/package.json b/packages/it-all/package.json index de1eb628..87f3def3 100644 --- a/packages/it-all/package.json +++ b/packages/it-all/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -131,6 +132,6 @@ "release": "aegir release" }, "devDependencies": { - "aegir": "^40.0.11" + "aegir": "^41.1.9" } } diff --git a/packages/it-all/src/index.ts b/packages/it-all/src/index.ts index a8293746..36d508e8 100644 --- a/packages/it-all/src/index.ts +++ b/packages/it-all/src/index.ts @@ -1,3 +1,36 @@ +/** + * @packageDocumentation + * + * For when you need a one-liner to collect iterable values. + * + * @example + * + * ```javascript + * import all from 'it-all' + * + * // This can also be an iterator, etc + * const values = function * () { + * yield * [0, 1, 2, 3, 4] + * } + * + * const arr = all(values) + * + * console.info(arr) // 0, 1, 2, 3, 4 + * ``` + * + * Async sources must be awaited: + * + * ```javascript + * const values = async function * () { + * yield * [0, 1, 2, 3, 4] + * } + * + * const arr = await all(values()) + * + * console.info(arr) // 0, 1, 2, 3, 4 + * ``` + */ + function isAsyncIterable (thing: any): thing is AsyncIterable { return thing[Symbol.asyncIterator] != null } diff --git a/packages/it-all/typedoc.json b/packages/it-all/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-all/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-batch/README.md b/packages/it-batch/README.md index 5dc42b6f..2009d1f2 100644 --- a/packages/it-batch/README.md +++ b/packages/it-batch/README.md @@ -1,35 +1,13 @@ -# it-batch - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Takes an async iterator that emits things and emits them as fixed size batches -## Table of contents - -- [Install](#install) - - [Browser ` -``` +# About The final batch may be smaller than the max. -## Usage +## Example ```javascript import batch from 'it-batch' @@ -53,20 +31,34 @@ import all from 'it-all' const values = async function * () { yield * [0, 1, 2, 3, 4] } -const batchSize = 2 +const batchSize = 2 const result = await all(batch(values(), batchSize)) console.info(result) // [0, 1], [2, 3], [4] ``` -## License +# Install + +```console +$ npm i it-batch +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-batch/package.json b/packages/it-batch/package.json index e3537e94..72fdbec5 100644 --- a/packages/it-batch/package.json +++ b/packages/it-batch/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -131,7 +132,7 @@ "release": "aegir release" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "it-all": "^3.0.0" } } diff --git a/packages/it-batch/src/index.ts b/packages/it-batch/src/index.ts index 7915414b..0be57f9f 100644 --- a/packages/it-batch/src/index.ts +++ b/packages/it-batch/src/index.ts @@ -1,3 +1,40 @@ +/** + * @packageDocumentation + * + * The final batch may be smaller than the max. + * + * @example + * + * ```javascript + * import batch from 'it-batch' + * import all from 'it-all' + * + * // This can also be an iterator, generator, etc + * const values = [0, 1, 2, 3, 4] + * const batchSize = 2 + * + * const result = all(batch(values, batchSize)) + * + * console.info(result) // [0, 1], [2, 3], [4] + * ``` + * + * Async sources must be awaited: + * + * ```javascript + * import batch from 'it-batch' + * import all from 'it-all' + * + * const values = async function * () { + * yield * [0, 1, 2, 3, 4] + * } + * + * const batchSize = 2 + * const result = await all(batch(values(), batchSize)) + * + * console.info(result) // [0, 1], [2, 3], [4] + * ``` + */ + function isAsyncIterable (thing: any): thing is AsyncIterable { return thing[Symbol.asyncIterator] != null } diff --git a/packages/it-batch/typedoc.json b/packages/it-batch/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-batch/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-batched-bytes/README.md b/packages/it-batched-bytes/README.md index 4f02a8cb..8919b6b0 100644 --- a/packages/it-batched-bytes/README.md +++ b/packages/it-batched-bytes/README.md @@ -1,35 +1,13 @@ -# it-batched-bytes - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Takes an async iterator that emits byte arrays and emits them as fixed size batches -## Table of contents - -- [Install](#install) - - [Browser ` -``` +# About The final batch may be smaller than the max. -## Usage +## Example ```javascript import batch from 'it-batched-bytes' @@ -70,13 +48,27 @@ const result = await all(batch(values, { size: batchSize })) console.info(result) // [0, 1], [2, 3], [4] ``` -## License +# Install + +```console +$ npm i it-batched-bytes +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-batched-bytes/package.json b/packages/it-batched-bytes/package.json index 77a8b6a8..c38d5b92 100644 --- a/packages/it-batched-bytes/package.json +++ b/packages/it-batched-bytes/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -135,7 +136,7 @@ "uint8arraylist": "^2.4.1" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "it-all": "^3.0.0" } } diff --git a/packages/it-batched-bytes/src/index.ts b/packages/it-batched-bytes/src/index.ts index 6946581e..fc1024c5 100644 --- a/packages/it-batched-bytes/src/index.ts +++ b/packages/it-batched-bytes/src/index.ts @@ -1,3 +1,50 @@ +/** + * @packageDocumentation + * + * The final batch may be smaller than the max. + * + * @example + * + * ```javascript + * import batch from 'it-batched-bytes' + * import all from 'it-all' + * + * // This can also be an iterator, generator, etc + * const values = [ + * Uint8Array.from([0]), + * Uint8Array.from([1]), + * Uint8Array.from([2]), + * Uint8Array.from([3]), + * Uint8Array.from([4]) + * ] + * const batchSize = 2 + * + * const result = all(batch(values, { size: batchSize })) + * + * console.info(result) // [0, 1], [2, 3], [4] + * ``` + * + * Async sources must be awaited: + * + * ```javascript + * import batch from 'it-batched-bytes' + * import all from 'it-all' + * + * const values = async function * () { + * yield Uint8Array.from([0]) + * yield Uint8Array.from([1]) + * yield Uint8Array.from([2]) + * yield Uint8Array.from([3]) + * yield Uint8Array.from([4]) + * } + * const batchSize = 2 + * + * const result = await all(batch(values, { size: batchSize })) + * + * console.info(result) // [0, 1], [2, 3], [4] + * ``` + */ + import defer from 'p-defer' import { Uint8ArrayList } from 'uint8arraylist' @@ -28,7 +75,7 @@ export interface BatchedObjectsOptions extends BatchedBytesOptions { * This function should serialize the object and append the * result to the passed list */ - serialize: (object: T, list: Uint8ArrayList) => void + serialize(object: T, list: Uint8ArrayList): void } export interface AsyncBatchedObjectsOptions extends AsyncBatchedBytesOptions, BatchedObjectsOptions { diff --git a/packages/it-batched-bytes/typedoc.json b/packages/it-batched-bytes/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-batched-bytes/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-buffer-stream/README.md b/packages/it-buffer-stream/README.md index 9153e9e1..9ca1ca3f 100644 --- a/packages/it-buffer-stream/README.md +++ b/packages/it-buffer-stream/README.md @@ -1,33 +1,13 @@ -# it-buffer-stream - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > An async iterator that emits buffers containing bytes up to a certain length -## Table of contents - -- [Install](#install) - - [Browser ` -``` +Generate a stream of buffers, useful for testing purposes. -## Usage +## Example ```javascript import bufferStream from 'it-buffer-stream' @@ -57,13 +37,27 @@ for await (buf of bufferStream(totalLength, options)) { // `buffers` is an array of Buffers the combined length of which === totalLength ``` -## License +# Install + +```console +$ npm i it-buffer-stream +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-buffer-stream/package.json b/packages/it-buffer-stream/package.json index 9bf3491e..3b84f2b3 100644 --- a/packages/it-buffer-stream/package.json +++ b/packages/it-buffer-stream/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -134,7 +135,7 @@ "iso-random-stream": "^2.0.2" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "uint8arrays": "^4.0.2" } } diff --git a/packages/it-buffer-stream/src/index.ts b/packages/it-buffer-stream/src/index.ts index 50ce7e79..f63f510d 100644 --- a/packages/it-buffer-stream/src/index.ts +++ b/packages/it-buffer-stream/src/index.ts @@ -1,9 +1,45 @@ +/** + * @packageDocumentation + * + * Generate a stream of buffers, useful for testing purposes. + * + * @example + * + * ```javascript + * import bufferStream from 'it-buffer-stream' + * + * const totalLength = //... a big number + * + * // all options are optional, defaults are shown + * const options = { + * chunkSize: 4096, // how many bytes will be in each buffer + * collector: (buffer) => { + * // will be called as each buffer is generated. the final buffer + * // may be smaller than `chunkSize` + * }, + * generator: async (size) => { + * // return a promise that resolves to a buffer of length `size` + * // + * // if omitted, `Promise.resolve(crypto.randomBytes(size))` will be used + * } + * } + * + * let buffers = [] + * + * for await (buf of bufferStream(totalLength, options)) { + * buffers.push(buf) + * } + * + * // `buffers` is an array of Buffers the combined length of which === totalLength + * ``` + */ + import randomBytes from 'iso-random-stream/src/random.js' export interface BufferStreamOptions { chunkSize?: number - collector?: (arr: Uint8Array) => void - generator?: (length: number) => Uint8Array | Promise + collector?(arr: Uint8Array): void + generator?(length: number): Uint8Array | Promise } const defaultOptions: Required = { diff --git a/packages/it-buffer-stream/typedoc.json b/packages/it-buffer-stream/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-buffer-stream/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-byte-stream/README.md b/packages/it-byte-stream/README.md index dcc5a5bd..79daf035 100644 --- a/packages/it-byte-stream/README.md +++ b/packages/it-byte-stream/README.md @@ -1,68 +1,50 @@ -# it-byte-stream - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Read and write arbitrary bytes over a duplex stream -## Table of contents - -- [Install](#install) - - [Browser ` -``` +// read the next chunk +const bytes = await stream.read() -- [Install](#install) - - [Browser ` ``` -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-byte-stream/package.json b/packages/it-byte-stream/package.json index b828a65a..77961a2e 100644 --- a/packages/it-byte-stream/package.json +++ b/packages/it-byte-stream/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -136,7 +137,7 @@ "uint8arraylist": "^2.4.1" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "it-pair": "^2.0.2", "uint8arrays": "^4.0.2" } diff --git a/packages/it-byte-stream/src/index.ts b/packages/it-byte-stream/src/index.ts index 36cb1191..37ef8857 100644 --- a/packages/it-byte-stream/src/index.ts +++ b/packages/it-byte-stream/src/index.ts @@ -51,17 +51,17 @@ export interface ByteStream { /** * Read a set number of bytes from the stream */ - read: (bytes?: number, options?: AbortOptions) => Promise + read(bytes?: number, options?: AbortOptions): Promise /** * Write the passed bytes to the stream */ - write: (input: Uint8Array | Uint8ArrayList, options?: AbortOptions) => Promise + write(input: Uint8Array | Uint8ArrayList, options?: AbortOptions): Promise /** * Returns the underlying stream */ - unwrap: () => Stream + unwrap(): Stream } export function byteStream > (duplex: Stream): ByteStream { diff --git a/packages/it-byte-stream/test/index.spec.ts b/packages/it-byte-stream/test/index.spec.ts index fec59062..7ef389e2 100644 --- a/packages/it-byte-stream/test/index.spec.ts +++ b/packages/it-byte-stream/test/index.spec.ts @@ -10,11 +10,11 @@ import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string' import { byteStream, type ByteStream } from '../src/index.js' interface Test { - from: (str: string) => T - alloc: (length: number, fill?: number) => T - allocUnsafe: (length: number) => T - concat: (arrs: T[], length?: number) => T - writeInt32BE: (buf: T, value: number, offset: number) => void + from(str: string): T + alloc(length: number, fill?: number): T + allocUnsafe(length: number): T + concat(arrs: T[], length?: number): T + writeInt32BE(buf: T, value: number, offset: number): void } const tests: Record> = { diff --git a/packages/it-byte-stream/typedoc.json b/packages/it-byte-stream/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-byte-stream/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-drain/README.md b/packages/it-drain/README.md index 675fe337..4a36f9ac 100644 --- a/packages/it-drain/README.md +++ b/packages/it-drain/README.md @@ -1,35 +1,13 @@ -# it-drain - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Empties an async iterator -## Table of contents - -- [Install](#install) - - [Browser ` -``` +# About Mostly useful for tests or when you want to be explicit about consuming an iterable without doing anything with any yielded values. -## Usage +## Example ```javascript import drain from 'it-drain' @@ -52,13 +30,27 @@ const values = async function * { await drain(values()) ``` -## License +# Install + +```console +$ npm i it-drain +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-drain/package.json b/packages/it-drain/package.json index 6b8e8111..c74d59d2 100644 --- a/packages/it-drain/package.json +++ b/packages/it-drain/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -131,7 +132,7 @@ "release": "aegir release" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "delay": "^6.0.0" } } diff --git a/packages/it-drain/src/index.ts b/packages/it-drain/src/index.ts index b27527a9..8315095a 100644 --- a/packages/it-drain/src/index.ts +++ b/packages/it-drain/src/index.ts @@ -1,3 +1,32 @@ +/** + * @packageDocumentation + * + * Mostly useful for tests or when you want to be explicit about consuming an iterable without doing anything with any yielded values. + * + * @example + * + * ```javascript + * import drain from 'it-drain' + * + * // This can also be an iterator, generator, etc + * const values = [0, 1, 2, 3, 4] + * + * drain(values) + * ``` + * + * Async sources must be awaited: + * + * ```javascript + * import drain from 'it-drain' + * + * const values = async function * { + * yield * [0, 1, 2, 3, 4] + * } + * + * await drain(values()) + * ``` + */ + function isAsyncIterable (thing: any): thing is AsyncIterable { return thing[Symbol.asyncIterator] != null } diff --git a/packages/it-drain/typedoc.json b/packages/it-drain/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-drain/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-filter/README.md b/packages/it-filter/README.md index 5a57f7fd..f81f5902 100644 --- a/packages/it-filter/README.md +++ b/packages/it-filter/README.md @@ -1,33 +1,13 @@ -# it-filter - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Filters the passed iterable by using the filter function -## Table of contents - -- [Install](#install) - - [Browser ` -``` +Filter values out of an (async)iterable -## Usage +## Example ```javascript import all from 'it-all' @@ -60,13 +40,27 @@ const arr = await all(filter(values, fn)) console.info(arr) // 3, 4 ``` -## License +# Install + +```console +$ npm i it-filter +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-filter/package.json b/packages/it-filter/package.json index 3aba61a5..884df436 100644 --- a/packages/it-filter/package.json +++ b/packages/it-filter/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -134,7 +135,7 @@ "it-peekable": "^3.0.0" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "it-all": "^3.0.0" } } diff --git a/packages/it-filter/src/index.ts b/packages/it-filter/src/index.ts index 03d7de4f..a4b84ec4 100644 --- a/packages/it-filter/src/index.ts +++ b/packages/it-filter/src/index.ts @@ -1,3 +1,42 @@ +/** + * @packageDocumentation + * + * Filter values out of an (async)iterable + * + * @example + * + * ```javascript + * import all from 'it-all' + * import filter from 'it-filter' + * + * // This can also be an iterator, generator, etc + * const values = [0, 1, 2, 3, 4] + * + * const fn = val => val > 2 // Return boolean to keep item + * + * const arr = all(filter(values, fn)) + * + * console.info(arr) // 3, 4 + * ``` + * + * Async sources and filter functions must be awaited: + * + * ```javascript + * import all from 'it-all' + * import filter from 'it-filter' + * + * const values = async function * () { + * yield * [0, 1, 2, 3, 4] + * } + * + * const fn = async val => val > 2 // Return boolean or promise of boolean to keep item + * + * const arr = await all(filter(values, fn)) + * + * console.info(arr) // 3, 4 + * ``` + */ + import peek from 'it-peekable' function isAsyncIterable (thing: any): thing is AsyncIterable { diff --git a/packages/it-filter/typedoc.json b/packages/it-filter/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-filter/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-first/README.md b/packages/it-first/README.md index e226cc52..2943a27e 100644 --- a/packages/it-first/README.md +++ b/packages/it-first/README.md @@ -1,35 +1,13 @@ -# it-first - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Returns the first result from an async iterator -## Table of contents - -- [Install](#install) - - [Browser ` -``` +# About -Mostly useful for tests. +Return the first value in an (async)iterable -## Usage +## Example ```javascript import first from 'it-first' @@ -56,13 +34,27 @@ const res = await first(values()) console.info(res) // 0 ``` -## License +# Install + +```console +$ npm i it-first +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-first/package.json b/packages/it-first/package.json index a18dd12c..2c821886 100644 --- a/packages/it-first/package.json +++ b/packages/it-first/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -131,6 +132,6 @@ "release": "aegir release" }, "devDependencies": { - "aegir": "^40.0.11" + "aegir": "^41.1.9" } } diff --git a/packages/it-first/src/index.ts b/packages/it-first/src/index.ts index aba9bc8d..07f1212e 100644 --- a/packages/it-first/src/index.ts +++ b/packages/it-first/src/index.ts @@ -1,3 +1,36 @@ +/** + * @packageDocumentation + * + * Return the first value in an (async)iterable + * + * @example + * + * ```javascript + * import first from 'it-first' + * + * // This can also be an iterator, generator, etc + * const values = [0, 1, 2, 3, 4] + * + * const res = first(values) + * + * console.info(res) // 0 + * ``` + * + * Async sources must be awaited: + * + * ```javascript + * import first from 'it-first' + * + * const values = async function * () { + * yield * [0, 1, 2, 3, 4] + * } + * + * const res = await first(values()) + * + * console.info(res) // 0 + * ``` + */ + function isAsyncIterable (thing: any): thing is AsyncIterable { return thing[Symbol.asyncIterator] != null } diff --git a/packages/it-first/typedoc.json b/packages/it-first/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-first/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-flat-batch/README.md b/packages/it-flat-batch/README.md index 9fc9a519..d9b87d11 100644 --- a/packages/it-flat-batch/README.md +++ b/packages/it-flat-batch/README.md @@ -1,35 +1,13 @@ -# it-flat-batch - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Takes an async iterator that emits variable length arrays and emits them as fixed size batches -## Table of contents - -- [Install](#install) - - [Browser ` -``` +# About The final batch may be smaller than requested batch size. -## Usage +## Example ```javascript import batch from 'it-flat-batch' @@ -60,13 +38,27 @@ const result = await all(batch(values(), batchSize)) console.info(result) // [0, 1], [2, 3], [4] ``` -## License +# Install + +```console +$ npm i it-flat-batch +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-flat-batch/package.json b/packages/it-flat-batch/package.json index 18c3edad..cb86dc4e 100644 --- a/packages/it-flat-batch/package.json +++ b/packages/it-flat-batch/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -131,7 +132,7 @@ "release": "aegir release" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "it-all": "^3.0.0" } } diff --git a/packages/it-flat-batch/src/index.ts b/packages/it-flat-batch/src/index.ts index 9ed67552..faa5565b 100644 --- a/packages/it-flat-batch/src/index.ts +++ b/packages/it-flat-batch/src/index.ts @@ -1,3 +1,40 @@ +/** + * @packageDocumentation + * + * The final batch may be smaller than requested batch size. + * + * @example + * + * ```javascript + * import batch from 'it-flat-batch' + * import all from 'it-all' + * + * // This can also be an iterator, async iterator, generator, etc + * const values = [[0, 1, 2], [3], [4]] + * const batchSize = 2 + * + * const result = all(batch(values, batchSize)) + * + * console.info(result) // [0, 1], [2, 3], [4] + * ``` + * + * Async sources must be awaited: + * + * ```javascript + * import batch from 'it-flat-batch' + * import all from 'it-all' + * + * const values = async function * () { + * yield * [[0, 1, 2], [3], [4]] + * } + * const batchSize = 2 + * + * const result = await all(batch(values(), batchSize)) + * + * console.info(result) // [0, 1], [2, 3], [4] + * ``` + */ + function isAsyncIterable (thing: any): thing is AsyncIterable { return thing[Symbol.asyncIterator] != null } diff --git a/packages/it-flat-batch/typedoc.json b/packages/it-flat-batch/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-flat-batch/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-foreach/README.md b/packages/it-foreach/README.md index dd936d61..c8ce3582 100644 --- a/packages/it-foreach/README.md +++ b/packages/it-foreach/README.md @@ -1,35 +1,17 @@ -# it-foreach - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Invokes the passed function for each item in an iterable -## Table of contents - -- [Install](#install) - - [Browser ` -``` +The function can be sync or async. -For when you need a one-liner to collect iterable values. +Async functions can be awaited on so may slow down processing of the (async)iterable. -## Usage +## Example ```javascript import each from 'it-foreach' @@ -60,13 +42,27 @@ const arr = await drain( ) ``` -## License +# Install + +```console +$ npm i it-foreach +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-foreach/package.json b/packages/it-foreach/package.json index 7f81b48b..39eab7db 100644 --- a/packages/it-foreach/package.json +++ b/packages/it-foreach/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -134,7 +135,7 @@ "it-peekable": "^3.0.0" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "it-all": "^3.0.0" } } diff --git a/packages/it-foreach/src/index.ts b/packages/it-foreach/src/index.ts index c319e7e7..35b96547 100644 --- a/packages/it-foreach/src/index.ts +++ b/packages/it-foreach/src/index.ts @@ -1,3 +1,44 @@ +/** + * @packageDocumentation + * + * Calls a function for each value in an (async)iterable. + * + * The function can be sync or async. + * + * Async functions can be awaited on so may slow down processing of the (async)iterable. + * + * @example + * + * ```javascript + * import each from 'it-foreach' + * import drain from 'it-drain' + * + * // This can also be an iterator, generator, etc + * const values = [0, 1, 2, 3, 4] + * + * // prints 0, 1, 2, 3, 4 + * const arr = drain( + * each(values, console.info) + * ) + * ``` + * + * Async sources and callbacks must be awaited: + * + * ```javascript + * import each from 'it-foreach' + * import drain from 'it-drain' + * + * const values = async function * () { + * yield * [0, 1, 2, 3, 4] + * } + * + * // prints 0, 1, 2, 3, 4 + * const arr = await drain( + * each(values(), console.info) + * ) + * ``` + */ + import peek from 'it-peekable' function isAsyncIterable (thing: any): thing is AsyncIterable { diff --git a/packages/it-foreach/typedoc.json b/packages/it-foreach/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-foreach/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-glob/README.md b/packages/it-glob/README.md index 23d2635e..ecf82076 100644 --- a/packages/it-glob/README.md +++ b/packages/it-glob/README.md @@ -1,26 +1,13 @@ -# it-glob - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Async iterable filename pattern matcher -## Table of contents - -- [Install](#install) -- [Usage](#usage) -- [License](#license) -- [Contribution](#contribution) - -## Install - -```console -$ npm i it-glob -``` +# About Like [`glob`](https://npmjs.com/package/glob) but async iterable. -## Usage +## Example ```javascript import glob from 'it-glob' @@ -34,19 +21,25 @@ const options = { } for await (const path of glob('/path/to/file', '**/*', options)) { - console.info(path) + console.info(path) } ``` See the [minimatch docs](https://www.npmjs.com/package/minimatch#options) for the full list of options. -## License +# Install + +```console +$ npm i it-glob +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-glob/package.json b/packages/it-glob/package.json index cc32014f..9e08f4ea 100644 --- a/packages/it-glob/package.json +++ b/packages/it-glob/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -129,7 +130,7 @@ "minimatch": "^9.0.0" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "it-all": "^3.0.0" }, "browser": { diff --git a/packages/it-glob/src/index.ts b/packages/it-glob/src/index.ts index 12661003..9a06011a 100644 --- a/packages/it-glob/src/index.ts +++ b/packages/it-glob/src/index.ts @@ -1,3 +1,29 @@ +/** + * @packageDocumentation + * + * Like [`glob`](https://npmjs.com/package/glob) but async iterable. + * + * @example + * + * ```javascript + * import glob from 'it-glob' + * + * const options = { + * cwd // defaults to process.cwd + * absolute // return absolute paths, defaults to false + * nodir // only yield file paths, skip directories + * + * // all other options are passed to minimatch + * } + * + * for await (const path of glob('/path/to/file', '**\/*', options)) { + * console.info(path) + * } + * ``` + * + * See the [minimatch docs](https://www.npmjs.com/package/minimatch#options) for the full list of options. + */ + import fs from 'fs/promises' import path from 'path' import { minimatch } from 'minimatch' diff --git a/packages/it-glob/typedoc.json b/packages/it-glob/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-glob/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-last/README.md b/packages/it-last/README.md index 72480424..4265930d 100644 --- a/packages/it-last/README.md +++ b/packages/it-last/README.md @@ -1,35 +1,13 @@ -# it-last - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Returns the last result from an async iterator -## Table of contents - -- [Install](#install) - - [Browser ` -``` +# About -Mostly useful for tests. +Return the last value from an (async)iterable. -## Usage +## Example ```javascript import last from 'it-last' @@ -56,13 +34,27 @@ const res = await last(values()) console.info(res) // 4 ``` -## License +# Install + +```console +$ npm i it-last +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-last/package.json b/packages/it-last/package.json index 4c757925..52cec260 100644 --- a/packages/it-last/package.json +++ b/packages/it-last/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -131,6 +132,6 @@ "release": "aegir release" }, "devDependencies": { - "aegir": "^40.0.11" + "aegir": "^41.1.9" } } diff --git a/packages/it-last/src/index.ts b/packages/it-last/src/index.ts index 82550c98..8573030b 100644 --- a/packages/it-last/src/index.ts +++ b/packages/it-last/src/index.ts @@ -1,3 +1,36 @@ +/** + * @packageDocumentation + * + * Return the last value from an (async)iterable. + * + * @example + * + * ```javascript + * import last from 'it-last' + * + * // This can also be an iterator, generator, etc + * const values = [0, 1, 2, 3, 4] + * + * const res = last(values) + * + * console.info(res) // 4 + * ``` + * + * Async sources must be awaited: + * + * ```javascript + * import last from 'it-last' + * + * const values = async function * () { + * yield * [0, 1, 2, 3, 4] + * } + * + * const res = await last(values()) + * + * console.info(res) // 4 + * ``` + */ + function isAsyncIterable (thing: any): thing is AsyncIterable { return thing[Symbol.asyncIterator] != null } diff --git a/packages/it-last/typedoc.json b/packages/it-last/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-last/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-length-prefixed-stream/README.md b/packages/it-length-prefixed-stream/README.md index f21157d5..f91ba6b9 100644 --- a/packages/it-length-prefixed-stream/README.md +++ b/packages/it-length-prefixed-stream/README.md @@ -1,65 +1,53 @@ -# it-length-prefixed-stream - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Read and write length-prefixed byte arrays over a duplex stream -## Table of contents - -- [Install](#install) - - [Browser ` -``` +// read the next length-prefixed chunk +const bytes = await stream.read() -- [Install](#install) - - [Browser ` ``` -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-length-prefixed-stream/package.json b/packages/it-length-prefixed-stream/package.json index e8c0ece5..993d96bf 100644 --- a/packages/it-length-prefixed-stream/package.json +++ b/packages/it-length-prefixed-stream/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -138,7 +139,7 @@ "uint8arraylist": "^2.4.1" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "it-pair": "^2.0.2", "uint8arrays": "^4.0.2" } diff --git a/packages/it-length-prefixed-stream/src/index.ts b/packages/it-length-prefixed-stream/src/index.ts index 5b53f4dd..d18fbf6c 100644 --- a/packages/it-length-prefixed-stream/src/index.ts +++ b/packages/it-length-prefixed-stream/src/index.ts @@ -1,8 +1,7 @@ /** * @packageDocumentation * - * This module makes it easy to send and receive length-prefixed byte arrays over - * streams. + * This module makes it easy to send and receive length-prefixed byte arrays over streams. * * @example * @@ -16,9 +15,14 @@ * * // write a length-prefixed chunk * await stream.write(Uint8Array.from([0, 1, 2, 3, 4])) + * + * // write several chunks, all individually length-prefixed + * await stream.writeV([ + * Uint8Array.from([0, 1, 2, 3, 4]), + * Uint8Array.from([5, 6, 7, 8, 9]) + * ]) * ``` */ - import { byteStream } from 'it-byte-stream' import * as lp from 'it-length-prefixed' import * as varint from 'uint8-varint' @@ -42,22 +46,22 @@ export interface LengthPrefixedStream { /** * Read the next length-prefixed number of bytes from the stream */ - read: (options?: AbortOptions) => Promise + read(options?: AbortOptions): Promise /** * Write the passed bytes to the stream prefixed by their length */ - write: (input: Uint8Array | Uint8ArrayList, options?: AbortOptions) => Promise + write(input: Uint8Array | Uint8ArrayList, options?: AbortOptions): Promise /** * Write passed list of bytes, prefix by their individual lengths to the stream as a single write */ - writeV: (input: Array, options?: AbortOptions) => Promise + writeV(input: Array, options?: AbortOptions): Promise /** * Returns the underlying stream */ - unwrap: () => Stream + unwrap(): Stream } export interface LengthPrefixedStreamOpts { diff --git a/packages/it-length-prefixed-stream/test/index.spec.ts b/packages/it-length-prefixed-stream/test/index.spec.ts index b964a58a..c571e70b 100644 --- a/packages/it-length-prefixed-stream/test/index.spec.ts +++ b/packages/it-length-prefixed-stream/test/index.spec.ts @@ -14,11 +14,11 @@ import type { LengthPrefixedStream } from '../src/index.js' /* eslint-disable max-nested-callbacks */ interface Test { - from: (str: string) => T - alloc: (length: number, fill?: number) => T - allocUnsafe: (length: number) => T - concat: (arrs: T[], length?: number) => T - writeInt32BE: (buf: T, value: number, offset: number) => void + from(str: string): T + alloc(length: number, fill?: number): T + allocUnsafe(length: number): T + concat(arrs: T[], length?: number): T + writeInt32BE(buf: T, value: number, offset: number): void } const tests: Record> = { diff --git a/packages/it-length-prefixed-stream/typedoc.json b/packages/it-length-prefixed-stream/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-length-prefixed-stream/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-length/README.md b/packages/it-length/README.md index b81bcc9c..44ac2431 100644 --- a/packages/it-length/README.md +++ b/packages/it-length/README.md @@ -1,35 +1,15 @@ -# it-length - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Counts the number of items in an async iterable -## Table of contents - -- [Install](#install) - - [Browser ` -``` +Counts the number of items in an (async)iterable. N.b. will consume the iterable -## Usage +## Example ```javascript import length from 'it-length' @@ -56,13 +36,27 @@ const res = await length(values()) console.info(res) // 5 ``` -## License +# Install + +```console +$ npm i it-length +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-length/package.json b/packages/it-length/package.json index 9454799c..b2e1b497 100644 --- a/packages/it-length/package.json +++ b/packages/it-length/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -131,6 +132,6 @@ "release": "aegir release" }, "devDependencies": { - "aegir": "^40.0.11" + "aegir": "^41.1.9" } } diff --git a/packages/it-length/src/index.ts b/packages/it-length/src/index.ts index 215840f2..119e8a7e 100644 --- a/packages/it-length/src/index.ts +++ b/packages/it-length/src/index.ts @@ -1,3 +1,38 @@ +/** + * @packageDocumentation + * + * Counts the number of items in an (async)iterable. + * + * N.b. will consume the iterable + * + * @example + * + * ```javascript + * import length from 'it-length' + * + * // This can also be an iterator, generator, etc + * const values = [0, 1, 2, 3, 4] + * + * const res = length(values) + * + * console.info(res) // 5 + * ``` + * + * Async sources must be awaited: + * + * ```javascript + * import length from 'it-length' + * + * const values = async function * () { + * yield * [0, 1, 2, 3, 4] + * } + * + * const res = await length(values()) + * + * console.info(res) // 5 + * ``` + */ + function isAsyncIterable (thing: any): thing is AsyncIterable { return thing[Symbol.asyncIterator] != null } diff --git a/packages/it-length/typedoc.json b/packages/it-length/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-length/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-map/README.md b/packages/it-map/README.md index a8373ab2..3c536126 100644 --- a/packages/it-map/README.md +++ b/packages/it-map/README.md @@ -1,33 +1,13 @@ -# it-map - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Maps the values yielded by an async iterator -## Table of contents - -- [Install](#install) - - [Browser ` -``` +Convert one value from an (async)iterator into another. -## Usage +## Example ```javascript import map from 'it-map' @@ -54,13 +34,27 @@ const result = await map(values(), async (val) => val++) console.info(result) // [1, 2, 3, 4, 5] ``` -## License +# Install + +```console +$ npm i it-map +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-map/package.json b/packages/it-map/package.json index e499a752..d55db78b 100644 --- a/packages/it-map/package.json +++ b/packages/it-map/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -134,7 +135,7 @@ "it-peekable": "^3.0.0" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "it-all": "^3.0.0" } } diff --git a/packages/it-map/src/index.ts b/packages/it-map/src/index.ts index 6d469110..d8f35038 100644 --- a/packages/it-map/src/index.ts +++ b/packages/it-map/src/index.ts @@ -1,3 +1,36 @@ +/** + * @packageDocumentation + * + * Convert one value from an (async)iterator into another. + * + * @example + * + * ```javascript + * import map from 'it-map' + * + * // This can also be an iterator, generator, etc + * const values = [0, 1, 2, 3, 4] + * + * const result = map(values, (val) => val++) + * + * console.info(result) // [1, 2, 3, 4, 5] + * ``` + * + * Async sources and transforms must be awaited: + * + * ```javascript + * import map from 'it-map' + * + * const values = async function * () { + * yield * [0, 1, 2, 3, 4] + * } + * + * const result = await map(values(), async (val) => val++) + * + * console.info(result) // [1, 2, 3, 4, 5] + * ``` + */ + import peek from 'it-peekable' function isAsyncIterable (thing: any): thing is AsyncIterable { diff --git a/packages/it-map/typedoc.json b/packages/it-map/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-map/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-merge/README.md b/packages/it-merge/README.md index 9230f68e..f2a8e307 100644 --- a/packages/it-merge/README.md +++ b/packages/it-merge/README.md @@ -1,35 +1,15 @@ -# it-merge - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Treat one or more iterables as a single iterable -## Table of contents - -- [Install](#install) - - [Browser ` -``` +Merge several (async)iterables into one, yield values as they arrive. Nb. sources are iterated over in parallel so the order of emitted items is not guaranteed. -## Usage +## Example ```javascript import merge from 'it-merge' @@ -63,13 +43,27 @@ const arr = await all(merge(values1(), values2())) console.info(arr) // 0, 1, 5, 6, 2, 3, 4, 7, 8, 9 <- nb. order is not guaranteed ``` -## License +# Install + +```console +$ npm i it-merge +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-merge/package.json b/packages/it-merge/package.json index ddc25333..c764140a 100644 --- a/packages/it-merge/package.json +++ b/packages/it-merge/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -134,7 +135,7 @@ "it-pushable": "^3.2.0" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "it-all": "^3.0.0" } } diff --git a/packages/it-merge/src/index.ts b/packages/it-merge/src/index.ts index 961403b5..842a9db4 100644 --- a/packages/it-merge/src/index.ts +++ b/packages/it-merge/src/index.ts @@ -1,3 +1,45 @@ +/** + * @packageDocumentation + * + * Merge several (async)iterables into one, yield values as they arrive. + * + * Nb. sources are iterated over in parallel so the order of emitted items is not guaranteed. + * + * @example + * + * ```javascript + * import merge from 'it-merge' + * import all from 'it-all' + * + * // This can also be an iterator, generator, etc + * const values1 = [0, 1, 2, 3, 4] + * const values2 = [5, 6, 7, 8, 9] + * + * const arr = all(merge(values1, values2)) + * + * console.info(arr) // 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 + * ``` + * + * Async sources must be awaited: + * + * ```javascript + * import merge from 'it-merge' + * import all from 'it-all' + * + * // This can also be an iterator, async iterator, generator, etc + * const values1 = async function * () { + * yield * [0, 1, 2, 3, 4] + * } + * const values2 = async function * () { + * yield * [5, 6, 7, 8, 9] + * } + * + * const arr = await all(merge(values1(), values2())) + * + * console.info(arr) // 0, 1, 5, 6, 2, 3, 4, 7, 8, 9 <- nb. order is not guaranteed + * ``` + */ + import { pushable } from 'it-pushable' function isAsyncIterable (thing: any): thing is AsyncIterable { diff --git a/packages/it-merge/typedoc.json b/packages/it-merge/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-merge/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-multipart/README.md b/packages/it-multipart/README.md index 0e37fcdb..6185d4d9 100644 --- a/packages/it-multipart/README.md +++ b/packages/it-multipart/README.md @@ -1,22 +1,11 @@ -# it-multipart - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Async iterable http multipart message parser -## Table of contents - -- [Install](#install) -- [Example](#example) -- [License](#license) -- [Contribution](#contribution) - -## Install +# About -```console -$ npm i it-multipart -``` +Allows iterating over multipart messages found in a HTTP request/ ## Example @@ -47,13 +36,19 @@ http.createServer(async (req, res) => { }) ``` -## License +# Install + +```console +$ npm i it-multipart +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-multipart/package.json b/packages/it-multipart/package.json index cf5e6d68..5fab1316 100644 --- a/packages/it-multipart/package.json +++ b/packages/it-multipart/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -132,7 +133,7 @@ }, "devDependencies": { "@types/formidable": "^2.0.5", - "aegir": "^40.0.11", + "aegir": "^41.1.9", "form-data": "^4.0.0", "it-drain": "^3.0.0", "node-fetch": "^3.2.10", diff --git a/packages/it-multipart/src/index.ts b/packages/it-multipart/src/index.ts index a5480f68..c61401bc 100644 --- a/packages/it-multipart/src/index.ts +++ b/packages/it-multipart/src/index.ts @@ -1,3 +1,38 @@ +/** + * @packageDocumentation + * + * Allows iterating over multipart messages found in a HTTP request/ + * + * @example + * + * ```javascript + * import http from 'http' + * import multipart from 'it-multipart' + * + * http.createServer(async (req, res) => { + * if (req.method === 'POST' && req.headers['content-type']) { + * for await (const part of multipart(req)) { + * console.log(`part with HTTP headers ${part.headers}`) + * + * // nb. part.body must be consumed before the next part is emitted + * for await (const chunk of part.body) { + * console.log(`part with content ${part.name} contents:`, chunk.toString()) + * } + * } + * + * console.log('finished parsing') + * res.writeHead(200) + * res.end() + * } + * + * res.writeHead(404) + * res.end() + * }).listen(5001, () => { + * console.log('server listening on port 5001') + * }) + * ``` + */ + import formidable from 'formidable' import { pushable } from 'it-pushable' import type { IncomingMessage, IncomingHttpHeaders } from 'http' diff --git a/packages/it-multipart/typedoc.json b/packages/it-multipart/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-multipart/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-ndjson/README.md b/packages/it-ndjson/README.md index a7b6019a..bf7c4255 100644 --- a/packages/it-ndjson/README.md +++ b/packages/it-ndjson/README.md @@ -1,33 +1,13 @@ -# it-ndjson - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Parse iterators as ndjson and transform iterators to ndjson -## Table of contents - -- [Install](#install) - - [Browser ` -``` +Turn (async)iterable values into JSON and back again. -## Usage +## Example ```javascript import ndjson from 'it-ndjson' @@ -45,13 +25,27 @@ const res = await all(ndjson.parse(arr)) console.info(res) // [0, 1, 2, 3, 4] ``` -## License +# Install + +```console +$ npm i it-ndjson +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-ndjson/package.json b/packages/it-ndjson/package.json index 3f314c66..3942d71b 100644 --- a/packages/it-ndjson/package.json +++ b/packages/it-ndjson/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -131,7 +132,7 @@ "release": "aegir release" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "buffer": "^6.0.3", "it-all": "^3.0.0" } diff --git a/packages/it-ndjson/src/index.ts b/packages/it-ndjson/src/index.ts index 218058e2..2422a5f8 100644 --- a/packages/it-ndjson/src/index.ts +++ b/packages/it-ndjson/src/index.ts @@ -1,2 +1,26 @@ +/** + * @packageDocumentation + * + * Turn (async)iterable values into JSON and back again. + * + * @example + * + * ```javascript + * import ndjson from 'it-ndjson' + * import all from 'it-all' + * + * // This can also be an iterator, async iterator, generator, etc + * const values = [0, 1, 2, 3, 4] + * + * const arr = await all(ndjson.stringify(values)) + * + * console.info(arr) // '0\n', '1\n', '2\n', '3\n', '4\n' + * + * const res = await all(ndjson.parse(arr)) + * + * console.info(res) // [0, 1, 2, 3, 4] + * ``` + */ + export { default as parse } from './parse.js' export { default as stringify } from './stringify.js' diff --git a/packages/it-ndjson/typedoc.json b/packages/it-ndjson/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-ndjson/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-parallel-batch/README.md b/packages/it-parallel-batch/README.md index 12fba7b6..aab443c4 100644 --- a/packages/it-parallel-batch/README.md +++ b/packages/it-parallel-batch/README.md @@ -1,35 +1,15 @@ -# it-parallel-batch - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) -> Takes an async iterator that emits promise-returning functions, invokes them in parallel and emits the results in the same order as the input - -## Table of contents - -- [Install](#install) - - [Browser ` -``` +Takes an async iterator that emits promise-returning functions, invokes them in parallel and emits the results in the same order as the input. The final batch may be smaller than the batch size. -## Usage +## Example ```javascript import parallelBatch from 'it-parallel-batch' @@ -62,13 +42,27 @@ const result = await all(parallelBatch(input, batchSize)) console.info(result) // [1, 2, 3] ``` -## License +# Install + +```console +$ npm i it-parallel-batch +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-parallel-batch/package.json b/packages/it-parallel-batch/package.json index 57d2e156..dc687625 100644 --- a/packages/it-parallel-batch/package.json +++ b/packages/it-parallel-batch/package.json @@ -1,7 +1,7 @@ { "name": "it-parallel-batch", "version": "3.0.3", - "description": "Takes an async iterator that emits promise-returning functions, invokes them in parallel and emits the results in the same order as the input", + "description": "Process (async)iterable values as functions with concurrency control", "author": "Alex Potsides ", "license": "Apache-2.0 OR MIT", "homepage": "https://github.com/achingbrain/it/tree/master/packages/it-parallel-batch#readme", @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -134,7 +135,7 @@ "it-batch": "^3.0.0" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "delay": "^6.0.0", "it-all": "^3.0.0" } diff --git a/packages/it-parallel-batch/src/index.ts b/packages/it-parallel-batch/src/index.ts index 330d882d..786260b6 100644 --- a/packages/it-parallel-batch/src/index.ts +++ b/packages/it-parallel-batch/src/index.ts @@ -1,3 +1,44 @@ +/** + * @packageDocumentation + * + * Takes an async iterator that emits promise-returning functions, invokes them in parallel and emits the results in the same order as the input. + * + * The final batch may be smaller than the batch size. + * + * @example + * + * ```javascript + * import parallelBatch from 'it-parallel-batch' + * import all from 'it-all' + * import delay from 'delay' + * + * // This can also be an iterator, async iterator, generator, etc + * const input = [ + * async () => { + * await delay(500) + * + * return 1 + * }, + * async () => { + * await delay(200) + * + * return 2 + * }, + * async () => { + * await delay(100) + * + * return 3 + * } + * ] + * + * const batchSize = 2 + * + * const result = await all(parallelBatch(input, batchSize)) + * + * console.info(result) // [1, 2, 3] + * ``` + */ + import batch from 'it-batch' interface Success { diff --git a/packages/it-parallel-batch/typedoc.json b/packages/it-parallel-batch/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-parallel-batch/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-parallel/README.md b/packages/it-parallel/README.md index e8ecb110..100ddfb3 100644 --- a/packages/it-parallel/README.md +++ b/packages/it-parallel/README.md @@ -1,33 +1,13 @@ -# it-parallel - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) -> Takes an (async) iterable that emits promise-returning functions, invokes them in parallel up to the concurrency limit and emits the results as they become available, optionally in the same order as the input - -## Table of contents - -- [Install](#install) - - [Browser ` -``` +Takes an (async) iterable that emits promise-returning functions, invokes them in parallel up to the concurrency limit and emits the results as they become available, optionally in the same order as the input -## Usage +## Example ```javascript import parallel from 'it-parallel' @@ -93,13 +73,27 @@ const result = await all(parallel(input, { console.info(result) // [1, 2, 3] ``` -## License +# Install + +```console +$ npm i it-parallel +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-parallel/package.json b/packages/it-parallel/package.json index bac8e119..2ae10cec 100644 --- a/packages/it-parallel/package.json +++ b/packages/it-parallel/package.json @@ -1,7 +1,7 @@ { "name": "it-parallel", "version": "3.0.5", - "description": "Takes an (async) iterable that emits promise-returning functions, invokes them in parallel up to the concurrency limit and emits the results as they become available, optionally in the same order as the input", + "description": "Process incoming async(iterable) functions in parallel", "author": "Alex Potsides ", "license": "Apache-2.0 OR MIT", "homepage": "https://github.com/achingbrain/it/tree/master/packages/it-parallel#readme", @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -134,7 +135,7 @@ "p-defer": "^4.0.0" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "delay": "^6.0.0", "it-all": "^3.0.0" } diff --git a/packages/it-parallel/src/index.ts b/packages/it-parallel/src/index.ts index 219ca1a9..48b874cd 100644 --- a/packages/it-parallel/src/index.ts +++ b/packages/it-parallel/src/index.ts @@ -1,4 +1,74 @@ -/* global EventTarget Event */ +/** + * @packageDocumentation + * + * Takes an (async) iterable that emits promise-returning functions, invokes them in parallel up to the concurrency limit and emits the results as they become available, optionally in the same order as the input + * + * @example + * + * ```javascript + * import parallel from 'it-parallel' + * import all from 'it-all' + * import delay from 'delay' + * + * // This can also be an iterator, async iterator, generator, etc + * const input = [ + * async () => { + * console.info('start 1') + * await delay(500) + * + * console.info('end 1') + * return 1 + * }, + * async () => { + * console.info('start 2') + * await delay(200) + * + * console.info('end 2') + * return 2 + * }, + * async () => { + * console.info('start 3') + * await delay(100) + * + * console.info('end 3') + * return 3 + * } + * ] + * + * const result = await all(parallel(input, { + * concurrency: 2 + * })) + * + * // output: + * // start 1 + * // start 2 + * // end 2 + * // start 3 + * // end 3 + * // end 1 + * + * console.info(result) // [2, 3, 1] + * ``` + * + * If order is important, pass `ordered: true` as an option: + * + * ```javascript + * const result = await all(parallel(input, { + * concurrency: 2, + * ordered: true + * })) + * + * // output: + * // start 1 + * // start 2 + * // end 2 + * // start 3 + * // end 3 + * // end 1 + * + * console.info(result) // [1, 2, 3] + * ``` + */ import defer from 'p-defer' diff --git a/packages/it-parallel/typedoc.json b/packages/it-parallel/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-parallel/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-peekable/README.md b/packages/it-peekable/README.md index 3440ae8a..68f860e2 100644 --- a/packages/it-peekable/README.md +++ b/packages/it-peekable/README.md @@ -1,35 +1,13 @@ -# it-peekable - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Allows peeking/pushing an iterable -## Table of contents - -- [Install](#install) - - [Browser ` -``` +# About Lets you look at the contents of an async iterator and decide what to do -## Usage +## Example ```javascript import peekable from 'it-peekable' @@ -70,13 +48,27 @@ console.info(await all(it)) // [ 0, 1, 2, 3, 4 ] ``` -## License +# Install + +```console +$ npm i it-peekable +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-peekable/package.json b/packages/it-peekable/package.json index 7bee3ec3..9359e70d 100644 --- a/packages/it-peekable/package.json +++ b/packages/it-peekable/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -131,7 +132,7 @@ "release": "aegir release" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "it-all": "^3.0.0" } } diff --git a/packages/it-peekable/src/index.ts b/packages/it-peekable/src/index.ts index 0ba1d4dd..dc83da40 100644 --- a/packages/it-peekable/src/index.ts +++ b/packages/it-peekable/src/index.ts @@ -1,18 +1,65 @@ -interface Peek { - peek: () => IteratorResult +/** + * @packageDocumentation + * + * Lets you look at the contents of an async iterator and decide what to do + * + * @example + * + * ```javascript + * import peekable from 'it-peekable' + * + * // This can also be an iterator, generator, etc + * const values = [0, 1, 2, 3, 4] + * + * const it = peekable(value) + * + * const first = it.peek() + * + * console.info(first) // 0 + * + * it.push(first) + * + * console.info([...it]) + * // [ 0, 1, 2, 3, 4 ] + * ``` + * + * Async sources must be awaited: + * + * ```javascript + * import peekable from 'it-peekable' + * + * const values = async function * () { + * yield * [0, 1, 2, 3, 4] + * } + * + * const it = peekable(values()) + * + * const first = await it.peek() + * + * console.info(first) // 0 + * + * it.push(first) + * + * console.info(await all(it)) + * // [ 0, 1, 2, 3, 4 ] + * ``` + */ + +export interface Peek { + peek(): IteratorResult } -interface AsyncPeek { - peek: () => Promise> +export interface AsyncPeek { + peek(): Promise> } -interface Push { - push: (value: T) => void +export interface Push { + push(value: T): void } -type Peekable = Iterable & Peek & Push & Iterator +export type Peekable = Iterable & Peek & Push & Iterator -type AsyncPeekable = AsyncIterable & AsyncPeek & Push & AsyncIterator +export type AsyncPeekable = AsyncIterable & AsyncPeek & Push & AsyncIterator function peekable (iterable: Iterable): Peekable function peekable (iterable: AsyncIterable): AsyncPeekable diff --git a/packages/it-peekable/typedoc.json b/packages/it-peekable/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-peekable/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-protobuf-stream/README.md b/packages/it-protobuf-stream/README.md index ebdc52da..7540fc73 100644 --- a/packages/it-protobuf-stream/README.md +++ b/packages/it-protobuf-stream/README.md @@ -1,65 +1,54 @@ -# it-protobuf-stream - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Read and write protobuf messages over a duplex stream -## Table of contents +# About -- [Install](#install) - - [Browser ` -``` +const stream = pbStream(duplex) -- [Install](#install) - - [Browser ` ``` -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-protobuf-stream/package.json b/packages/it-protobuf-stream/package.json index 6e63e069..cd67e9f4 100644 --- a/packages/it-protobuf-stream/package.json +++ b/packages/it-protobuf-stream/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -140,7 +141,7 @@ "uint8arraylist": "^2.4.1" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "it-map": "^3.0.0", "it-pair": "^2.0.2", "it-to-buffer": "^4.0.0", diff --git a/packages/it-protobuf-stream/src/index.ts b/packages/it-protobuf-stream/src/index.ts index 47c0fe94..f62d4f9c 100644 --- a/packages/it-protobuf-stream/src/index.ts +++ b/packages/it-protobuf-stream/src/index.ts @@ -55,27 +55,27 @@ export interface ProtobufStream { /** * Read the next length-prefixed byte array from the stream and decode it as the passed protobuf format */ - read: (proto: { decode: Decoder }, options?: AbortOptions) => Promise + read(proto: { decode: Decoder }, options?: AbortOptions): Promise /** * Encode the passed object as a protobuf message and write it's length-prefixed bytes to the stream */ - write: (data: T, proto: { encode: Encoder }, options?: AbortOptions) => Promise + write(data: T, proto: { encode: Encoder }, options?: AbortOptions): Promise /** * Encode the passed objects as protobuf messages and write their length-prefixed bytes to the stream as a single write */ - writeV: (input: T[], proto: { encode: Encoder }, options?: AbortOptions) => Promise + writeV(input: T[], proto: { encode: Encoder }, options?: AbortOptions): Promise /** * Returns an object with read/write methods for operating on one specific type of protobuf message */ - pb: (proto: { encode: Encoder, decode: Decoder }) => MessageStream + pb(proto: { encode: Encoder, decode: Decoder }): MessageStream /** * Returns the underlying stream */ - unwrap: () => Stream + unwrap(): Stream } /** @@ -85,22 +85,22 @@ export interface MessageStream { /** * Read a message from the stream */ - read: (options?: AbortOptions) => Promise + read(options?: AbortOptions): Promise /** * Write a message to the stream */ - write: (d: T, options?: AbortOptions) => Promise + write(d: T, options?: AbortOptions): Promise /** * Write several messages to the stream */ - writeV: (d: T[], options?: AbortOptions) => Promise + writeV(d: T[], options?: AbortOptions): Promise /** * Unwrap the underlying protobuf stream */ - unwrap: () => ProtobufStream + unwrap(): ProtobufStream } export interface ProtobufStreamOpts extends LengthPrefixedStreamOpts { diff --git a/packages/it-protobuf-stream/typedoc.json b/packages/it-protobuf-stream/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-protobuf-stream/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-reduce/README.md b/packages/it-reduce/README.md index d92ad968..064dfd34 100644 --- a/packages/it-reduce/README.md +++ b/packages/it-reduce/README.md @@ -1,35 +1,13 @@ -# it-reduce - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Reduces the values yielded from an async iterator -## Table of contents - -- [Install](#install) - - [Browser ` -``` +# About -Mostly useful for tests or when you want to be explicit about consuming an iterable without doing anything with any yielded values. +Reduce the values of an (async)iterable to a single value. -## Usage +## Example ```javascript import reduce from 'it-reduce' @@ -56,13 +34,27 @@ const result = await reduce(values(), (acc, curr) => acc + curr, 0) console.info(result) // 10 ``` -## License +# Install + +```console +$ npm i it-reduce +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-reduce/package.json b/packages/it-reduce/package.json index e92eafe9..9c5d76e8 100644 --- a/packages/it-reduce/package.json +++ b/packages/it-reduce/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -131,6 +132,6 @@ "release": "aegir release" }, "devDependencies": { - "aegir": "^40.0.11" + "aegir": "^41.1.9" } } diff --git a/packages/it-reduce/src/index.ts b/packages/it-reduce/src/index.ts index f63c689e..e2b7d6a4 100644 --- a/packages/it-reduce/src/index.ts +++ b/packages/it-reduce/src/index.ts @@ -1,3 +1,36 @@ +/** + * @packageDocumentation + * + * Reduce the values of an (async)iterable to a single value. + * + * @example + * + * ```javascript + * import reduce from 'it-reduce' + * + * // This can also be an iterator, generator, etc + * const values = [0, 1, 2, 3, 4] + * + * const result = reduce(values, (acc, curr) => acc + curr, 0) + * + * console.info(result) // 10 + * ``` + * + * Async sources must be awaited: + * + * ```javascript + * import reduce from 'it-reduce' + * + * const values = async function * () { + * yield * [0, 1, 2, 3, 4] + * } + * + * const result = await reduce(values(), (acc, curr) => acc + curr, 0) + * + * console.info(result) // 10 + * ``` + */ + function isAsyncIterable (thing: any): thing is AsyncIterable { return thing[Symbol.asyncIterator] != null } diff --git a/packages/it-reduce/typedoc.json b/packages/it-reduce/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-reduce/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-skip/README.md b/packages/it-skip/README.md index 54898609..d2b03a5c 100644 --- a/packages/it-skip/README.md +++ b/packages/it-skip/README.md @@ -1,35 +1,13 @@ -# it-skip - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Skip items from an iterable -## Table of contents - -- [Install](#install) - - [Browser ` -``` +# About -For when you are only interested in later values from an iterable. +For when you are only interested in later values from an (async)iterable. -## Usage +## Example ```javascript import take from 'it-skip' @@ -58,13 +36,27 @@ const arr = await all(skip(values(), 2)) console.info(arr) // 2, 3, 4 ``` -## License +# Install + +```console +$ npm i it-skip +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-skip/package.json b/packages/it-skip/package.json index 4ef67554..b3b7ccaa 100644 --- a/packages/it-skip/package.json +++ b/packages/it-skip/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -131,7 +132,7 @@ "release": "aegir release" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "it-all": "^3.0.0" } } diff --git a/packages/it-skip/src/index.ts b/packages/it-skip/src/index.ts index a6ea0419..64086349 100644 --- a/packages/it-skip/src/index.ts +++ b/packages/it-skip/src/index.ts @@ -1,3 +1,38 @@ +/** + * @packageDocumentation + * + * For when you are only interested in later values from an (async)iterable. + * + * @example + * + * ```javascript + * import take from 'it-skip' + * import all from 'it-all' + * + * // This can also be an iterator, generator, etc + * const values = [0, 1, 2, 3, 4] + * + * const arr = all(skip(values, 2)) + * + * console.info(arr) // 2, 3, 4 + * ``` + * + * Async sources must be awaited: + * + * ```javascript + * import take from 'it-skip' + * import all from 'it-all' + * + * const values = async function * () { + * yield * [0, 1, 2, 3, 4] + * } + * + * const arr = await all(skip(values(), 2)) + * + * console.info(arr) // 2, 3, 4 + * ``` + */ + function isAsyncIterable (thing: any): thing is AsyncIterable { return thing[Symbol.asyncIterator] != null } diff --git a/packages/it-skip/typedoc.json b/packages/it-skip/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-skip/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-sort/README.md b/packages/it-sort/README.md index c15a6dfc..b4162e10 100644 --- a/packages/it-sort/README.md +++ b/packages/it-sort/README.md @@ -1,33 +1,13 @@ -# it-sort - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Collects all values from an async iterator, sorts them using the passed function and yields them -## Table of contents - -- [Install](#install) - - [Browser ` -``` +Consumes all values from an (async)iterable and returns them sorted by the passed sort function. -## Usage +## Example ```javascript import sort from 'it-sort' @@ -64,13 +44,27 @@ const arr = await all(sort(values, sorter)) console.info(arr) // 'bar', 'foo' ``` -## License +# Install + +```console +$ npm i it-sort +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-sort/package.json b/packages/it-sort/package.json index 55c670a6..d0e3d0f0 100644 --- a/packages/it-sort/package.json +++ b/packages/it-sort/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -134,6 +135,6 @@ "it-all": "^3.0.0" }, "devDependencies": { - "aegir": "^40.0.11" + "aegir": "^41.1.9" } } diff --git a/packages/it-sort/src/index.ts b/packages/it-sort/src/index.ts index b93e81dc..bb4ec341 100644 --- a/packages/it-sort/src/index.ts +++ b/packages/it-sort/src/index.ts @@ -1,3 +1,46 @@ +/** + * @packageDocumentation + * + * Consumes all values from an (async)iterable and returns them sorted by the passed sort function. + * + * @example + * + * ```javascript + * import sort from 'it-sort' + * import all from 'it-all' + * + * const sorter = (a, b) => { + * return a.localeCompare(b) + * } + * + * // This can also be an iterator, generator, etc + * const values = ['foo', 'bar'] + * + * const arr = all(sort(values, sorter)) + * + * console.info(arr) // 'bar', 'foo' + * ``` + * + * Async sources must be awaited: + * + * ```javascript + * import sort from 'it-sort' + * import all from 'it-all' + * + * const sorter = (a, b) => { + * return a.localeCompare(b) + * } + * + * const values = async function * () { + * yield * ['foo', 'bar'] + * } + * + * const arr = await all(sort(values, sorter)) + * + * console.info(arr) // 'bar', 'foo' + * ``` + */ + import all from 'it-all' function isAsyncIterable (thing: any): thing is AsyncIterable { diff --git a/packages/it-sort/typedoc.json b/packages/it-sort/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-sort/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-split/README.md b/packages/it-split/README.md index b7f23d53..12eeaffa 100644 --- a/packages/it-split/README.md +++ b/packages/it-split/README.md @@ -1,33 +1,13 @@ -# it-split - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Splits Uint8Arrays emitted by an (async) iterable by a delimiter -## Table of contents - -- [Install](#install) - - [Browser ` -``` +Searches `Uint8Array`s emitted by an (async)iterable for a delimiter and yields chunks split by that delimiter. -## Usage +## Example ```javascript import split from 'it-split' @@ -81,13 +61,27 @@ const arr = await all(split(values())) console.info(arr) // [encoder.encode('hello'), encoder.encode('world')] ``` -## License +# Install + +```console +$ npm i it-split +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-split/package.json b/packages/it-split/package.json index e73f544e..1b9010a6 100644 --- a/packages/it-split/package.json +++ b/packages/it-split/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -134,7 +135,7 @@ "uint8arraylist": "^2.4.1" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "buffer": "^6.0.3", "it-all": "^3.0.0", "uint8arrays": "^4.0.2" diff --git a/packages/it-split/src/index.ts b/packages/it-split/src/index.ts index b0d9d122..8201404a 100644 --- a/packages/it-split/src/index.ts +++ b/packages/it-split/src/index.ts @@ -1,3 +1,63 @@ +/** + * @packageDocumentation + * + * Searches `Uint8Array`s emitted by an (async)iterable for a delimiter and yields chunks split by that delimiter. + * + * @example + * + * ```javascript + * import split from 'it-split' + * + * const encoder = new TextEncoder() + * + * // This can also be an iterator, generator, etc + * const values = [ + * encoder.encode('hello\nwor'), + * encoder.encode('ld') + * ] + * + * const arr = all(split(values)) + * + * console.info(arr) // [encoder.encode('hello'), encoder.encode('world')] + * ``` + * + * You can also split by arbitrary delimiters: + * + * ```javascript + * const values = [ + * Uint8Array.from([0, 1, 2, 3]), + * Uint8Array.from([0, 1, 2, 3]), + * Uint8Array.from([1, 1, 2]) + * ] + * const delimiter = Uint8Array.from([1, 2]) + * + * const arr = all(split(values, { + * delimiter + * })) + * + * console.info(arr) // [ Buffer.from([0]), Buffer.from([3, 0]), Buffer.from([3, 1]) ] + * ``` + * + * Async sources must be awaited: + * + * ```javascript + * import split from 'it-split' + * + * const encoder = new TextEncoder() + * + * const values = async function * () { + * yield * [ + * encoder.encode('hello\nwor'), + * encoder.encode('ld') + * ] + * } + * + * const arr = await all(split(values())) + * + * console.info(arr) // [encoder.encode('hello'), encoder.encode('world')] + * ``` + */ + import { Uint8ArrayList } from 'uint8arraylist' export interface SplitOptions { diff --git a/packages/it-split/typedoc.json b/packages/it-split/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-split/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-take/README.md b/packages/it-take/README.md index 6d810e43..68a16978 100644 --- a/packages/it-take/README.md +++ b/packages/it-take/README.md @@ -1,35 +1,13 @@ -# it-take - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Stop iteration after n items have been received -## Table of contents - -- [Install](#install) - - [Browser ` -``` +# About -For when you only want a few values out of an iterable. +For when you only want a few values out of an (async)iterable. -## Usage +## Example ```javascript import take from 'it-take' @@ -58,13 +36,27 @@ const arr = await all(take(values(), 2)) console.info(arr) // 0, 1 ``` -## License +# Install + +```console +$ npm i it-take +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-take/package.json b/packages/it-take/package.json index 4bca51c2..5326ac46 100644 --- a/packages/it-take/package.json +++ b/packages/it-take/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -131,7 +132,7 @@ "release": "aegir release" }, "devDependencies": { - "aegir": "^40.0.11", + "aegir": "^41.1.9", "it-all": "^3.0.0" } } diff --git a/packages/it-take/src/index.ts b/packages/it-take/src/index.ts index 4892f1a0..e7a6eb1c 100644 --- a/packages/it-take/src/index.ts +++ b/packages/it-take/src/index.ts @@ -1,3 +1,38 @@ +/** + * @packageDocumentation + * + * For when you only want a few values out of an (async)iterable. + * + * @example + * + * ```javascript + * import take from 'it-take' + * import all from 'it-all' + * + * // This can also be an iterator, generator, etc + * const values = [0, 1, 2, 3, 4] + * + * const arr = all(take(values, 2)) + * + * console.info(arr) // 0, 1 + * ``` + * + * Async sources must be awaited: + * + * ```javascript + * import take from 'it-take' + * import all from 'it-all' + * + * const values = async function * () { + * yield * [0, 1, 2, 3, 4] + * } + * + * const arr = await all(take(values(), 2)) + * + * console.info(arr) // 0, 1 + * ``` + */ + function isAsyncIterable (thing: any): thing is AsyncIterable { return thing[Symbol.asyncIterator] != null } diff --git a/packages/it-take/typedoc.json b/packages/it-take/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-take/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-to-browser-readablestream/README.md b/packages/it-to-browser-readablestream/README.md index a1fd4fc7..0eef95ab 100644 --- a/packages/it-to-browser-readablestream/README.md +++ b/packages/it-to-browser-readablestream/README.md @@ -1,33 +1,13 @@ -# it-to-browser-readablestream - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Takes an async iterator and turns it into a browser readable stream -## Table of contents - -- [Install](#install) - - [Browser ` -``` +Turns an (async)iterable into a W3C ReadbleStream. -## Usage +## Example ```javascript import toBrowserReadableStream from 'it-to-browser-readablestream' @@ -42,13 +22,27 @@ for await (const buf of stream) { } ``` -## License +# Install + +```console +$ npm i it-to-browser-readablestream +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-to-browser-readablestream/package.json b/packages/it-to-browser-readablestream/package.json index 04d4b9c3..dd759c3a 100644 --- a/packages/it-to-browser-readablestream/package.json +++ b/packages/it-to-browser-readablestream/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -130,6 +131,6 @@ "release": "aegir release" }, "devDependencies": { - "aegir": "^40.0.11" + "aegir": "^41.1.9" } } diff --git a/packages/it-to-browser-readablestream/src/index.ts b/packages/it-to-browser-readablestream/src/index.ts index 95501199..63434287 100644 --- a/packages/it-to-browser-readablestream/src/index.ts +++ b/packages/it-to-browser-readablestream/src/index.ts @@ -1,3 +1,24 @@ +/** + * @packageDocumentation + * + * Turns an (async)iterable into a W3C ReadbleStream. + * + * @example + * + * ```javascript + * import toBrowserReadableStream from 'it-to-browser-readablestream' + * + * // This can also be an iterator, async iterator, generator, etc + * const values = [Buffer.from([0, 1]), Buffer.from([2, 3])] + * + * const stream = await toBrowserReadableStream(values) + * + * for await (const buf of stream) { + * console.info(buf) // Buffer[0, 1] + * } + * ``` + */ + interface SourceExt { _cancelled: boolean } diff --git a/packages/it-to-browser-readablestream/typedoc.json b/packages/it-to-browser-readablestream/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-to-browser-readablestream/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +} diff --git a/packages/it-to-buffer/README.md b/packages/it-to-buffer/README.md index 286ecc43..c2b80629 100644 --- a/packages/it-to-buffer/README.md +++ b/packages/it-to-buffer/README.md @@ -1,33 +1,13 @@ -# it-to-buffer - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/it.svg?style=flat-square)](https://codecov.io/gh/achingbrain/it) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/it/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/it/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Takes an async iterator that yields buffers and concatenates them all together -## Table of contents - -- [Install](#install) - - [Browser ` -``` +Collects all `Uint8Array` values from an (async)iterable and returns them as a single `Uint8Array`. -## Usage +## Example ```javascript import toBuffer from 'it-to-buffer' @@ -55,13 +35,27 @@ const result = await toBuffer(values()) console.info(result) // Buffer[0, 1, 2, 3] ``` -## License +# Install + +```console +$ npm i it-to-buffer +``` + +## Browser ` +``` + +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribution +# Contribution 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. diff --git a/packages/it-to-buffer/package.json b/packages/it-to-buffer/package.json index 04ff02b6..00809c09 100644 --- a/packages/it-to-buffer/package.json +++ b/packages/it-to-buffer/package.json @@ -29,6 +29,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -134,6 +135,6 @@ "uint8arrays": "^4.0.2" }, "devDependencies": { - "aegir": "^40.0.11" + "aegir": "^41.1.9" } } diff --git a/packages/it-to-buffer/src/index.ts b/packages/it-to-buffer/src/index.ts index 424d9831..d9eef43c 100644 --- a/packages/it-to-buffer/src/index.ts +++ b/packages/it-to-buffer/src/index.ts @@ -1,3 +1,37 @@ +/** + * @packageDocumentation + * + * Collects all `Uint8Array` values from an (async)iterable and returns them as a single `Uint8Array`. + * + * @example + * + * ```javascript + * import toBuffer from 'it-to-buffer' + * + * // This can also be an iterator, generator, etc + * const values = [Buffer.from([0, 1]), Buffer.from([2, 3])] + * + * const result = toBuffer(values) + * + * console.info(result) // Buffer[0, 1, 2, 3] + * ``` + * + * Async sources must be awaited: + * + * ```javascript + * import toBuffer from 'it-to-buffer' + * + * const values = async function * () { + * yield Buffer.from([0, 1]) + * yield Buffer.from([2, 3]) + * } + * + * const result = await toBuffer(values()) + * + * console.info(result) // Buffer[0, 1, 2, 3] + * ``` + */ + import { concat as uint8ArrayConcat } from 'uint8arrays/concat' function isAsyncIterable (thing: any): thing is AsyncIterable { diff --git a/packages/it-to-buffer/typedoc.json b/packages/it-to-buffer/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/it-to-buffer/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +}