diff --git a/.github/workflows/js-test-and-release.yml b/.github/workflows/js-test-and-release.yml index 5e2410d..2c7a14b 100644 --- a/.github/workflows/js-test-and-release.yml +++ b/.github/workflows/js-test-and-release.yml @@ -1,181 +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 - - 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 0000000..bd00f09 --- /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 0000000..16d65d7 --- /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/README.md b/README.md index f0fa12c..bdebe8a 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,15 @@ -# uint8arrays - [![codecov](https://img.shields.io/codecov/c/github/achingbrain/uint8arrays.svg?style=flat-square)](https://codecov.io/gh/achingbrain/uint8arrays) [![CI](https://img.shields.io/github/actions/workflow/status/achingbrain/uint8arrays/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/achingbrain/uint8arrays/actions/workflows/js-test-and-release.yml?query=branch%3Amaster) > Utility functions to make dealing with Uint8Arrays easier -## Table of contents - -- [Install](#install) - - [Browser ` ``` -## API - -### alloc(size) - -Create a new `Uint8Array`. If `globalThis.Buffer` is defined, it will be used in preference to `globalThis.Uint8Array`. - -#### Example - -```js -import { alloc } from 'uint8arrays/alloc' - -const buf = alloc(100) -``` - -### allocUnsafe(size) - -Create a new `Uint8Array`. If `globalThis.Buffer` is defined, it will be used in preference to `globalThis.Uint8Array`. - -On platforms that support it, memory referenced by the returned `Uint8Array` will not be initialized. - -#### Example - -```js -import { allocUnsafe } from 'uint8arrays/alloc' - -const buf = allocUnsafe(100) -``` - -### compare(a, b) - -Compare two `Uint8Arrays` - -#### Example - -```js -import { compare } from 'uint8arrays/compare' - -const arrays = [ - Uint8Array.from([3, 4, 5]), - Uint8Array.from([0, 1, 2]) -] - -const sorted = arrays.sort(compare) - -console.info(sorted) -// [ -// Uint8Array[0, 1, 2] -// Uint8Array[3, 4, 5] -// ] -``` - -### concat(arrays, \[length]) - -Concatenate one or more array-likes and return a `Uint8Array` with their contents. - -If you know the length of the arrays, pass it as a second parameter, otherwise it will be calculated by traversing the list of arrays. - -#### Example - -```js -import { concat } from 'uint8arrays/concat' - -const arrays = [ - Uint8Array.from([0, 1, 2]), - Uint8Array.from([3, 4, 5]) -] +# API Docs -const all = concat(arrays, 6) - -console.info(all) -// Uint8Array[0, 1, 2, 3, 4, 5] -``` - -### equals(a, b) - -Returns true if the two arrays are the same array or if they have the same length and contents. - -#### Example - -```js -import { equals } from 'uint8arrays/equals' - -const a = Uint8Array.from([0, 1, 2]) -const b = Uint8Array.from([3, 4, 5]) -const c = Uint8Array.from([0, 1, 2]) - -console.info(equals(a, b)) // false -console.info(equals(a, c)) // true -console.info(equals(a, a)) // true -``` - -### fromString(string, encoding = 'utf8') - -Returns a new `Uint8Array` created from the passed string and interpreted as the passed encoding. - -Supports `utf8` and any of the [multibase encodings](https://github.com/multiformats/multibase/blob/master/multibase.csv) as implemented by the [multiformats module](https://www.npmjs.com/package/multiformats). - -#### Example - -```js -import { fromString } from 'uint8arrays/from-string' - -console.info(fromString('hello world')) // Uint8Array[104, 101 ... -console.info(fromString('00010203aabbcc', 'base16')) // Uint8Array[0, 1 ... -console.info(fromString('AAECA6q7zA', 'base64')) // Uint8Array[0, 1 ... -console.info(fromString('01234', 'ascii')) // Uint8Array[48, 49 ... -``` - -### toString(array, encoding = 'utf8') - -Returns a string created from the passed `Uint8Array` in the passed encoding. - -Supports `utf8` and any of the [multibase encodings](https://github.com/multiformats/multibase/blob/master/multibase.csv) as implemented by the [multiformats module](https://www.npmjs.com/package/multiformats). - -#### Example - -```js -import { toString } from 'uint8arrays/to-string' - -console.info(toString(Uint8Array.from([104, 101...]))) // 'hello world' -console.info(toString(Uint8Array.from([0, 1, 2...]), 'base16')) // '00010203aabbcc' -console.info(toString(Uint8Array.from([0, 1, 2...]), 'base64')) // 'AAECA6q7zA' -console.info(toString(Uint8Array.from([48, 49, 50...]), 'ascii')) // '01234' -``` - -### xor(a, b) - -Returns a `Uint8Array` containing `a` and `b` xored together. - -#### Example - -```js -import { xor } from 'uint8arrays/xor' - -console.info(xor(Uint8Array.from([1, 0]), Uint8Array.from([0, 1]))) // Uint8Array[1, 1] -``` +- -## 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 48dd377..f4f0227 100644 --- a/package.json +++ b/package.json @@ -73,6 +73,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -172,14 +173,15 @@ "lint": "aegir lint", "release": "aegir release", "build": "aegir build", - "dep-check": "aegir dep-check" + "dep-check": "aegir dep-check", + "docs": "aegir docs" }, "dependencies": { "multiformats": "^12.0.1" }, "devDependencies": { "@types/benchmark": "^2.1.1", - "aegir": "^40.0.8", + "aegir": "^41.1.9", "benchmark": "^2.1.4" } } diff --git a/src/index.ts b/src/index.ts index 3b92bc8..3a78b1e 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,3 +1,148 @@ +/** + * @packageDocumentation + * + * `Uint8Array`s bring memory-efficient(ish) byte handling to browsers - they are similar to Node.js `Buffer`s but lack a lot of the utility methods present on that class. + * + * This module exports a number of function that let you do common operations - joining Uint8Arrays together, seeing if they have the same contents etc. + * + * Since Node.js `Buffer`s are also `Uint8Array`s, it falls back to `Buffer` internally where it makes sense for performance reasons. + * + * ## alloc(size) + * + * Create a new `Uint8Array`. If `globalThis.Buffer` is defined, it will be used in preference to `globalThis.Uint8Array`. + * + * ### Example + * + * ```js + * import { alloc } from 'uint8arrays/alloc' + * + * const buf = alloc(100) + * ``` + * + * ## allocUnsafe(size) + * + * Create a new `Uint8Array`. If `globalThis.Buffer` is defined, it will be used in preference to `globalThis.Uint8Array`. + * + * On platforms that support it, memory referenced by the returned `Uint8Array` will not be initialized. + * + * ### Example + * + * ```js + * import { allocUnsafe } from 'uint8arrays/alloc' + * + * const buf = allocUnsafe(100) + * ``` + * + * ## compare(a, b) + * + * Compare two `Uint8Arrays` + * + * ### Example + * + * ```js + * import { compare } from 'uint8arrays/compare' + * + * const arrays = [ + * Uint8Array.from([3, 4, 5]), + * Uint8Array.from([0, 1, 2]) + * ] + * + * const sorted = arrays.sort(compare) + * + * console.info(sorted) + * // [ + * // Uint8Array[0, 1, 2] + * // Uint8Array[3, 4, 5] + * // ] + * ``` + * + * ## concat(arrays, \[length]) + * + * Concatenate one or more array-likes and return a `Uint8Array` with their contents. + * + * If you know the length of the arrays, pass it as a second parameter, otherwise it will be calculated by traversing the list of arrays. + * + * ### Example + * + * ```js + * import { concat } from 'uint8arrays/concat' + * + * const arrays = [ + * Uint8Array.from([0, 1, 2]), + * Uint8Array.from([3, 4, 5]) + * ] + * + * const all = concat(arrays, 6) + * + * console.info(all) + * // Uint8Array[0, 1, 2, 3, 4, 5] + * ``` + * + * ## equals(a, b) + * + * Returns true if the two arrays are the same array or if they have the same length and contents. + * + * ### Example + * + * ```js + * import { equals } from 'uint8arrays/equals' + * + * const a = Uint8Array.from([0, 1, 2]) + * const b = Uint8Array.from([3, 4, 5]) + * const c = Uint8Array.from([0, 1, 2]) + * + * console.info(equals(a, b)) // false + * console.info(equals(a, c)) // true + * console.info(equals(a, a)) // true + * ``` + * + * ## fromString(string, encoding = 'utf8') + * + * Returns a new `Uint8Array` created from the passed string and interpreted as the passed encoding. + * + * Supports `utf8` and any of the [multibase encodings](https://github.com/multiformats/multibase/blob/master/multibase.csv) as implemented by the [multiformats module](https://www.npmjs.com/package/multiformats). + * + * ### Example + * + * ```js + * import { fromString } from 'uint8arrays/from-string' + * + * console.info(fromString('hello world')) // Uint8Array[104, 101 ... + * console.info(fromString('00010203aabbcc', 'base16')) // Uint8Array[0, 1 ... + * console.info(fromString('AAECA6q7zA', 'base64')) // Uint8Array[0, 1 ... + * console.info(fromString('01234', 'ascii')) // Uint8Array[48, 49 ... + * ``` + * + * ## toString(array, encoding = 'utf8') + * + * Returns a string created from the passed `Uint8Array` in the passed encoding. + * + * Supports `utf8` and any of the [multibase encodings](https://github.com/multiformats/multibase/blob/master/multibase.csv) as implemented by the [multiformats module](https://www.npmjs.com/package/multiformats). + * + * ### Example + * + * ```js + * import { toString } from 'uint8arrays/to-string' + * + * console.info(toString(Uint8Array.from([104, 101...]))) // 'hello world' + * console.info(toString(Uint8Array.from([0, 1, 2...]), 'base16')) // '00010203aabbcc' + * console.info(toString(Uint8Array.from([0, 1, 2...]), 'base64')) // 'AAECA6q7zA' + * console.info(toString(Uint8Array.from([48, 49, 50...]), 'ascii')) // '01234' + * ``` + * + * ## xor(a, b) + * + * Returns a `Uint8Array` containing `a` and `b` xored together. + * + * ### Example + * + * ```js + * import { xor } from 'uint8arrays/xor' + * + * console.info(xor(Uint8Array.from([1, 0]), Uint8Array.from([0, 1]))) // Uint8Array[1, 1] + * ``` + */ + import { compare } from './compare.js' import { concat } from './concat.js' import { equals } from './equals.js' diff --git a/typedoc.json b/typedoc.json new file mode 100644 index 0000000..0b86048 --- /dev/null +++ b/typedoc.json @@ -0,0 +1,12 @@ +{ + "entryPoints": [ + "./src/index.ts", + "./src/alloc.ts", + "./src/compare.ts", + "./src/concat.ts", + "./src/equals.ts", + "./src/from-string.ts", + "./src/to-string.ts", + "./src/xor.ts" + ] +}