{"id":19123100,"url":"https://github.com/digitalbazaar/bnid","last_synced_at":"2025-08-21T11:22:42.556Z","repository":{"id":40338617,"uuid":"254159318","full_name":"digitalbazaar/bnid","owner":"digitalbazaar","description":"JavaScript Base-N Id Generator","archived":false,"fork":false,"pushed_at":"2022-08-25T18:55:01.000Z","size":47,"stargazers_count":3,"open_issues_count":0,"forks_count":3,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-16T06:20:01.252Z","etag":null,"topics":["generator","id","random"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/digitalbazaar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-08T17:44:23.000Z","updated_at":"2023-10-02T01:32:02.000Z","dependencies_parsed_at":"2022-08-09T17:40:29.498Z","dependency_job_id":null,"html_url":"https://github.com/digitalbazaar/bnid","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalbazaar%2Fbnid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalbazaar%2Fbnid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalbazaar%2Fbnid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalbazaar%2Fbnid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/digitalbazaar","download_url":"https://codeload.github.com/digitalbazaar/bnid/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252552893,"owners_count":21766794,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["generator","id","random"],"created_at":"2024-11-09T05:24:19.933Z","updated_at":"2025-05-05T18:33:28.675Z","avatar_url":"https://github.com/digitalbazaar.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JavaScript Base-N Id Generator _(bnid)_\n\n[![Node.js CI](https://github.com/digitalbazaar/bnid/workflows/Node.js%20CI/badge.svg)](https://github.com/digitalbazaar/bnid/actions?query=workflow%3A%22Node.js+CI%22)\n\n\u003e A JavaScript library for Web browsers and Node.js apps to generate random\n\u003e ids and encode and decode them using various base-N encodings.\n\n## Table of Contents\n\n- [Background](#background)\n- [Install](#install)\n- [Usage](#usage)\n- [API](#api)\n- [CLI](#cli)\n- [Contribute](#contribute)\n- [Commercial Support](#commercial-support)\n- [License](#license)\n\n## Background\n\nThis library provides tools for Web and Node.js to generate random ids and\nencode and decode them in various base-N encodings.\n\n## Install\n\n### NPM\n\n```\nnpm install bnid\n```\n\n### Git\n\nTo install locally (for development):\n\n```\ngit clone https://github.com/digitalbazaar/bnid.git\ncd bnid\nnpm install\n```\n\n## Usage\n\nThe interface follows the [TextEncoder][]/[TextDecoder][] interfaces and\nprovides [IdEncoder](#idencoder) and [IdDecoder](#iddecoder) classes. Instances\ncan be configured with reusable encodings and other parameters. The encoder\noperates on a `Uint8Array` of input bytes. A [IdGenerator](#idgenerator) class\nis provided that can be used to generate random ids with selectable bit\nlengths, but any id data can be used.\n\nThe encoder and decoder support various encodings and options:\n\n- `base16`/`hex`, `base16upper`: The simple [Base16][].\n- `base58`/`base58btc`: The [Base58][] Bitcoin alphabet as supported by\n  [base58-universal][].\n- Optional [multibase][] type prefix.\n- Fixed bit length. This is useful to ensure the output id length is constant\n  even when the id starts with an arbitrary number of zeros.\n\nThe fixed length options can be important when using encodings that have\nvariable length outputs depending on the input length. `base58btc` is and\nexample. When encoding, the `fixedLength` or `fixedBitLength` options can be\nused to force the output to be a constant length. When decoding, the\n`fixedBitLength` options can be used to ensure a constant length array of\nbytes.\n\n### Generate an ID\n\nTo generate a default [Base58][], 128 bit, non-fixed-length, multibase encoded\nid:\n\n```js\nimport {generateId} from 'bnid';\n\nconst id = await generateId();\n```\n\nTo generate a [Base58][], 128 bit, fixed-length id:\n\n```js\nimport {generateId} from 'bnid';\n\nconst id = await generateId({\n  fixedLength: true\n});\n```\n\n### Reusable Components\n\nSome setup overhead can be avoided by using the component `IdGenerator` and\n`IdEncoder` classes.\n\n```js\nimport {IdGenerator, IdEncoder} from 'bnid';\n\n// 64 bit random id generator\nconst generator = new IdGenerator({\n  bitLength: 64\n});\n// base58, multibase, fixed-length encoder\nconst encoder = new IdEncoder({\n  encoding: 'base58',\n  fixedLength: true,\n  multibase: true\n});\nconst id1 = encoder.encode(await generator.generate());\nconst id2 = encoder.encode(await generator.generate());\n```\n\n### Reusable Components\n\nSome setup overhead can be avoided by using the component `IdGenerator` and\n`IdEncoder` classes.\n\n```js\nimport {IdGenerator, IdEncoder, IdDecoder} from 'bnid';\n\n// 64 bit random id generator\nconst generator = new IdGenerator({\n  bitLength: 64\n});\n// base58, multibase, fixed-length encoder\nconst encoder = new IdEncoder({\n  encoding: 'base58',\n  fixedLength: true,\n  multibase: true\n});\nconst id1 = encoder.encode(await generator.generate());\n// =\u003e \"z...\"\nconst id2 = encoder.encode(await generator.generate());\n// =\u003e \"z...\"\n\nconst decoder = new IdDecoder({\n  fixedBitLength: 64,\n  multibase: true\n});\nconst id1bytes = decoder.decode(id1);\n// =\u003e Uint8Array([...])\nconst id2bytes = decoder.decode(id2);\n// =\u003e Uint8Array([...])\n```\n\n## API\n\n### `generateId(options)`\n\nGenerate a string id. See `IdGenerator` and `IdEncoder` for options.\n\n### `decodeId(options)`\n\nDecode the options.id string. See `IdDecoder` for other options.\n\n### `IdGenerator`\n\nAn `IdGenerator` generates an array of id bytes.\n\n#### `constuctor(options)` / `constructor(bitLength)`\n\nOptions:\n- `bitLength`: Number of id bits. Must be multiple of 8. (default: 128)\n\n#### `generate()`\n\nGenerate random id bytes.\n\n### `IdEncoder`\n\nAn `IdEncoder` encodes an array of id bytes into a specific encoding.\n\n#### `constuctor(options)`\n\nOptions:\n- `encoding`: Output encoding. (default: `base58`)\n  - `base16`/`base16upper`/`hex`: base16 encoded string.\n  - `base58`/`base58btc`: base58btc encoded string.\n- `fixedLength`: `true` to ensure fixed output length. (default: false)\n- `fixedBitLength`: fixed output bit length or 0 to base on input byte size.\n  (default: 0)\n- `multibase`: `true` to use multibase encoding. (default: `true`)\n- `multihash`: `true` to use multihash encoding. (default: `false`)\n\n#### `encode(bytes)`\n\nEncode id bytes into a string.\n\n### `IdDecoder`\n\nAn `IdDecoder` decodes a specific encoding into an array of bytes representing\nan ID.\n\n#### `constuctor(options)`\n\nOptions:\n- `encoding`: Input encoding. Ignored if `multibase` is `true`. (default:\n  `base58`)\n  - Same options as for `IdEncoder`.\n- `fixedBitLength`: fixed output bit length.  (default: none)\n- `multibase`: `true` to use multibase encoding to detect id format. (default:\n  `true`)\n- `multihash`: `true` to use multihash encoding. (default: `false`)\n- `expectedSize`: Expected size for multihash-encoded ID bytes. Use `0` to\n  disable size check. (default: 32)\n\n#### `decode(id)`\n\nDecode id string into bytes.\n\n### `minEncodedIdBytes(options)`\n\nMinimum number of bytes needed to encode an id of a given bit length.\n\nOptions:\n- `encoding`: Encoding. (default: `base58`)\n- `bitLength`: Number of id bits. (default: 128)\n- `multibase`: Account for multibase encoding. (default: true)\n\n### `maxEncodedIdBytes(options)`\n\nMaximum number of bytes needed to encode an id of a given bit length.\n\nOptions:\n- `encoding`: Encoding. (default: `base58`)\n- `bitLength`: Number of id bits. (default: 128)\n- `multibase`: Account for multibase encoding. (default: true)\n\n### `generateSecretKeySeed(options)`\n\n`generateSecretKeySeed()` and `decodeSecretKeySeed()` methods are for creating\nand decoding secret key pair seeds which can be used to generate public key\nbased identifiers.\n\n`generateSecretKeySeed()` generates a secret key seed encoded as a string that\ncan be stored and later used to generate a key pair. The public key from\nthe key pair can be used as an identifier. The encoded key seed MUST be kept\nsecret.\n\n```js\nimport {generateSecretKeySeed} from 'bnid';\nconst secretKeySeed = await generateSecretKeySeed();\n// Example secretKeySeed: z1Aaj5A4UCsdMpXwdYAReXa4bxWYiKJtdAvB1zMzCHtCbtD\n```\nOptions:\n- `encoding`: Encoding. (default: `base58`)\n- `bitLength`: Number of id bits. (default: 32 * 8)\n- `multibase`: Account for multibase encoding. (default: true)\n- `multihash`: Account for multihash encoding. (default: true)\n\n### `decodeSecretKeySeed(options)`\n\nDecodes an encoded secret key seed into an array of secret key seed bytes\n(default size: 32 bytes). Both the encoded key seed and the decoded bytes MUST\nbe kept secret.\n\n```js\nimport {decodeSecretKeySeed} from 'bnid';\nconst secretKeySeed = 'z1Aaj5A4UCsdMpXwdYAReXa4bxWYiKJtdAvB1zMzCHtCbtD';\ndecoded = decodeSecretKeySeed({secretKeySeed});\n// Example decoded:\n// Uint8Array(32) [\n//    80, 174,  15, 131, 124,  59,   9,  51,\n//   145, 129,  92, 157, 157, 172, 161,  79,\n//    74,  61, 152, 152,  48, 151,  20,  89,\n//   225, 169,  71,  34,  49,  61,  21, 215\n// ]\n```\nOptions:\n- `secretKeySeed`: The secret key seed to be decoded.\n- `multibase`: Account for multibase encoding. (default: true)\n- `multihash`: Account for multihash encoding. (default: true)\n- `expectedSize`: Expected size for multihash-encoded ID bytes. Use `0` to\n  disable size check. (default: 32)\n\n## CLI\n\nA command line interface tool to generate and encode ids is provided in\n[`bnid-cli`](https://github.com/digitalbazaar/bnid-cli).\n\n## Contribute\n\nPlease follow the existing code style.\n\nPRs accepted.\n\nIf editing the README, please conform to the\n[standard-readme](https://github.com/RichardLitt/standard-readme) specification.\n\n## Commercial Support\n\nCommercial support for this library is available upon request from\nDigital Bazaar: support@digitalbazaar.com\n\n## License\n\n[BSD-3-Clause](LICENSE.md) © Digital Bazaar\n\n[Base16]: https://en.wikipedia.org/wiki/Base16\n[Base58]: https://en.wikipedia.org/wiki/Base58\n[TextDecoder]: https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder\n[TextEncoder]: https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder\n[base58-universal]: https://github.com/digitalbazaar/base58-universal\n[multibase]: https://github.com/multiformats/multibase\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalbazaar%2Fbnid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigitalbazaar%2Fbnid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalbazaar%2Fbnid/lists"}