{"_id":"level-transcoder","_rev":"4212132","name":"level-transcoder","description":"Encode data with built-in or custom encodings","dist-tags":{"latest":"1.0.1"},"maintainers":[{"name":"vweevers","email":""}],"time":{"modified":"2026-03-04T17:06:51.000Z","created":"2021-11-07T22:22:44.730Z","1.0.1":"2021-11-26T20:20:49.266Z","1.0.0":"2021-11-07T22:22:44.730Z"},"users":{},"repository":{"type":"git","url":"git+https://github.com/Level/transcoder.git"},"versions":{"1.0.1":{"name":"level-transcoder","version":"1.0.1","description":"Encode data with built-in or custom encodings","license":"MIT","main":"index.js","types":"./index.d.ts","scripts":{"test":"ts-standard && tsc && standard && hallmark && nyc tape test/*.js","test-browsers-local":"airtap --coverage --verbose test/*.js","coverage":"nyc report -r lcovonly","hallmark":"hallmark --fix"},"dependencies":{"buffer":"^6.0.3","module-error":"^1.0.1"},"devDependencies":{"@types/node":"^16.11.10","@voxpelli/tsconfig":"^3.1.0","airtap":"^4.0.3","airtap-playwright":"^1.0.1","hallmark":"^4.0.0","nyc":"^15.1.0","standard":"^16.0.3","tape":"^5.3.2","ts-standard":"^11.0.0","typescript":"^4.5.2"},"repository":{"type":"git","url":"git+https://github.com/Level/transcoder.git"},"homepage":"https://github.com/Level/transcoder","keywords":["level"],"engines":{"node":">=12"},"gitHead":"30ef334d492e470709795954a271ad9e64bcb6ea","bugs":{"url":"https://github.com/Level/transcoder/issues"},"_id":"level-transcoder@1.0.1","_nodeVersion":"16.9.1","_npmVersion":"7.21.1","dist":{"shasum":"f8cef5990c4f1283d4c86d949e73631b0bc8ba9c","size":9922,"noattachment":false,"key":"/level-transcoder/-/level-transcoder-1.0.1.tgz","tarball":"http://registry.cnpm.dingdandao.com/level-transcoder/download/level-transcoder-1.0.1.tgz"},"_npmUser":{"name":"vweevers","email":"dev@vincentweevers.nl"},"directories":{},"maintainers":[{"name":"vweevers","email":""}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/level-transcoder_1.0.1_1637958048884_0.03632570890321407"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2021-12-28T00:28:09.430Z","publish_time":1637958049266,"_cnpm_publish_time":1637958049266},"1.0.0":{"name":"level-transcoder","version":"1.0.0","description":"Encode data with built-in or custom encodings","license":"MIT","main":"index.js","types":"./index.d.ts","scripts":{"test":"ts-standard && tsc && standard && hallmark && nyc tape test/*.js","test-browsers-local":"airtap --coverage --verbose test/*.js","coverage":"nyc report -r lcovonly","hallmark":"hallmark --fix","dependency-check":"dependency-check . test/*.js","prepublishOnly":"npm run dependency-check"},"dependencies":{"buffer":"^6.0.3","module-error":"^1.0.1"},"devDependencies":{"@types/node":"^16.11.4","@voxpelli/tsconfig":"^3.0.0","airtap":"^4.0.3","airtap-playwright":"^1.0.1","dependency-check":"^3.3.0","hallmark":"^3.1.0","nyc":"^15.1.0","standard":"^16.0.3","tape":"^5.0.1","ts-standard":"^10.0.0","typescript":"^4.4.4"},"repository":{"type":"git","url":"git+https://github.com/Level/transcoder.git"},"homepage":"https://github.com/Level/transcoder","keywords":["level"],"engines":{"node":">=12"},"gitHead":"21f22cae5c330dafe0d6bf4a3560cf292579b3f6","bugs":{"url":"https://github.com/Level/transcoder/issues"},"_id":"level-transcoder@1.0.0","_nodeVersion":"16.9.1","_npmVersion":"7.21.1","dist":{"shasum":"b239ecc45c7cbef467f0698300a2d8ccfd74667b","size":9976,"noattachment":false,"key":"/level-transcoder/-/level-transcoder-1.0.0.tgz","tarball":"http://registry.cnpm.dingdandao.com/level-transcoder/download/level-transcoder-1.0.0.tgz"},"_npmUser":{"name":"vweevers","email":"dev@vincentweevers.nl"},"directories":{},"maintainers":[{"name":"vweevers","email":""}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/level-transcoder_1.0.0_1636323764595_0.6757064755442204"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2021-12-28T00:28:08.492Z","publish_time":1636323764730,"_cnpm_publish_time":1636323764730}},"readme":"# level-transcoder\n\n**Encode data with built-in or custom encodings.** The successor to [`level-codec`][level-codec] that transcodes encodings from and to internal data formats supported by a database. This allows a database to store data in a format of its choice (Buffer, Uint8Array or String) with zero-effort support of known encodings. That includes other encoding interfaces in the ecosystem like [`abstract-encoding`][abstract-enc] and [`multiformats`][blockcodec].\n\n[![level badge][level-badge]](https://github.com/Level/awesome)\n[![npm](https://img.shields.io/npm/v/level-transcoder.svg)](https://www.npmjs.com/package/level-transcoder)\n[![Node version](https://img.shields.io/node/v/level-transcoder.svg)](https://www.npmjs.com/package/level-transcoder)\n[![Test](https://img.shields.io/github/workflow/status/Level/transcoder/Test?label=test)](https://github.com/Level/transcoder/actions/workflows/test.yml)\n[![Coverage](https://img.shields.io/codecov/c/github/Level/transcoder?label=\\&logo=codecov\\&logoColor=fff)](https://codecov.io/gh/Level/transcoder)\n[![Standard](https://img.shields.io/badge/standard-informational?logo=javascript\\&logoColor=fff)](https://standardjs.com)\n[![Common Changelog](https://common-changelog.org/badge.svg)](https://common-changelog.org)\n[![Donate](https://img.shields.io/badge/donate-orange?logo=open-collective\\&logoColor=fff)](https://opencollective.com/level)\n\n## Usage\n\nCreate a transcoder, passing a desired format:\n\n```js\nconst { Transcoder } = require('level-transcoder')\n\nconst transcoder1 = new Transcoder(['view'])\nconst transcoder2 = new Transcoder(['buffer'])\nconst transcoder3 = new Transcoder(['utf8'])\n```\n\nThen select an encoding and encode some data:\n\n```js\n// Uint8Array(3) [ 49, 50, 51 ]\nconsole.log(transcoder1.encoding('json').encode(123))\n\n// <Buffer 31 32 33>\nconsole.log(transcoder2.encoding('json').encode(123))\n\n// '123'\nconsole.log(transcoder3.encoding('json').encode(123))\n```\n\nIf the `Transcoder` constructor is given multiple formats then `Transcoder#encoding()` selects an encoding with the best fitting format. Consider a database like [`leveldown`][leveldown] which has the ability to return data as a Buffer or string. If an `encoding.decode(data)` function needs a string, we'll want to fetch that `data` from the database as a string. This avoids the cost of having to convert a Buffer to a string. So we'd use the following transcoder:\n\n```js\nconst transcoder = new Transcoder(['buffer', 'utf8'])\n```\n\nThen, knowing for example that the return value of `JSON.stringify(data)` is a UTF-8 string which matches one of the given formats, the `'json'` encoding will return a string here:\n\n```js\n// '123'\nconsole.log(transcoder.encoding('json').encode(123))\n```\n\nIn contrast, data encoded as a `'view'` (for now that just means Uint8Array) would get transcoded into the `'buffer'` encoding. Copying of data is avoided where possible, like how the underlying ArrayBuffer of a view can be passed to `Buffer.from(..)` without a copy.\n\nLastly, encodings returned by `Transcoder#encoding()` have a `format` property to be used to forward information to an underlying store. For example: an input value of `{ x: 3 }` using the `'json'` encoding which has a `format` of `'utf8'`, can be forwarded as value `'{\"x\":3}'` with encoding `'utf8'`. Vice versa for output.\n\n## Encodings\n\n### Built-in Encodings\n\nThese encodings can be used out of the box and are to be selected by name.\n\nIn this table, the _input_ is what `encode()` accepts. The _format_ is what `encode()` returns as well as what `decode()` accepts. The _output_ is what `decode()` returns. The TypeScript typings of `level-transcoder` have generic type parameters with matching names: `TIn`, `TFormat` and `TOut`.\n\n| Name                    | Input                      | Format     | Output          |\n| :---------------------- | :------------------------- | :--------- | :-------------- |\n| `'buffer'` <sup>1</sup> | Buffer, Uint8Array, String | `'buffer'` | Buffer          |\n| `'view'`                | Uint8Array, Buffer, String | `'view'`   | Uint8Array      |\n| `'utf8'`                | String, Buffer, Uint8Array | `'utf8'`   | String          |\n| `'json'`                | Any JSON type              | `'utf8'`   | As input        |\n| `'hex'`                 | String (hex), Buffer       | `'buffer'` | String (hex)    |\n| `'base64'`              | String (base64), Buffer    | `'buffer'` | String (base64) |\n\n<sup>1</sup> Aliased as `'binary'`. Use of this alias does not affect the ability to transcode.\n\n### Transcoder Encodings\n\nIt's not necessary to use or reference the below encodings directly. They're listed here for implementation notes and to show how input and output is the same; it's the format that differs.\n\nCustom encodings are transcoded in the same way and require no additional setup. For example: if a custom encoding has `{ name: 'example', format: 'utf8' }` then `level-transcoder` will create transcoder encodings on demand with names `'example+buffer'` and `'example+view'`.\n\n| Name                         | Input                      | Format     | Output          |\n| :--------------------------- | :------------------------- | :--------- | :-------------- |\n| `'buffer+view'`              | Buffer, Uint8Array, String | `'view'`   | Buffer          |\n| `'view+buffer'`              | Uint8Array, Buffer, String | `'buffer'` | Uint8Array      |\n| `'utf8+view'`                | String, Buffer, Uint8Array | `'view'`   | String          |\n| `'utf8+buffer'`              | String, Buffer, Uint8Array | `'buffer'` | String          |\n| `'json+view'`                | Any JSON type              | `'view'`   | As input        |\n| `'json+buffer'`              | Any JSON type              | `'buffer'` | As input        |\n| `'hex+view'` <sup>1</sup>    | String (hex), Buffer       | `'view'`   | String (hex)    |\n| `'base64+view'` <sup>1</sup> | String (base64), Buffer    | `'view'`   | String (base64) |\n\n<sup>1</sup> Unlike other encodings that transcode to `'view'`, these depend on Buffer at the moment and thus don't work in browsers if a [shim](https://github.com/feross/buffer) is not included by JavaScript bundlers like Webpack and Browserify.\n\n### Ecosystem Encodings\n\nVarious modules in the ecosystem, in and outside of Level, can be used with `level-transcoder` although they follow different interfaces. Common between the interfaces is that they have `encode()` and `decode()` methods. The terms \"codec\" and \"encoding\" are used interchangeably in the ecosystem. Passing these encodings through `Transcoder#encoding()` (which is done implicitly when used in an `abstract-level` database) results in normalized encoding objects as described further below.\n\n| Module                                     | Format           | Interface                           | Named |\n| :----------------------------------------- | :--------------- | :---------------------------------- | :---- |\n| [`protocol-buffers`][protocol-buffers]     | `buffer`         | [`level-codec`][level-codec]        | ❌     |\n| [`charwise`][charwise]                     | `utf8`           | [`level-codec`][level-codec]        | ✅     |\n| [`bytewise`][bytewise]                     | `buffer`         | [`level-codec`][level-codec]        | ✅     |\n| [`lexicographic-integer-encoding`][lexint] | `buffer`, `utf8` | [`level-codec`][level-codec]        | ✅     |\n| [`abstract-encoding`][abstract-enc]        | `buffer`         | [`abstract-encoding`][abstract-enc] | ❌     |\n| [`multiformats`][js-multiformats]          | `view`           | [`multiformats`][blockcodec]        | ✅     |\n\nThose marked as not named are modules that export or generate encodings that don't have a `name` property (or `type` as an alias). We call these _anonymous encodings_. They can only be used as objects and not by name. Passing an anonymous encoding through `Transcoder#encoding()` does give it a `name` property for compatibility, but the value of `name` is not deterministic.\n\n## API\n\n### `Transcoder`\n\n#### `transcoder = new Transcoder(formats)`\n\nCreate a new transcoder, providing the formats that are supported by a database (or other). The `formats` argument must be an array containing one or more of `'buffer'`, `'view'`, `'utf8'`. The returned `transcoder` instance is stateful, in that it contains a set of cached encoding objects.\n\n#### `encoding = transcoder.encoding(encoding)`\n\nReturns the given `encoding` argument as a normalized encoding object that follows the `level-transcoder` encoding interface. The `encoding` argument may be:\n\n- A string to select a known encoding by its name\n- An object that follows one of the following interfaces: [`level-transcoder`](#encoding-interface), [`level-codec`](https://github.com/Level/codec#encoding-format), [`abstract-encoding`][abstract-enc], [`multiformats`][blockcodec]\n- A previously normalized encoding, such that `encoding(x)` equals `encoding(encoding(x))`.\n\nResults are cached. If the `encoding` argument is an object and it has a name then subsequent calls can refer to that encoding by name.\n\nDepending on the `formats` provided to the `Transcoder` constructor, this method may return a _transcoder encoding_ that translates the desired encoding from / to a supported format. Its `encode()` and `decode()` methods will have respectively the same input and output types as a non-transcoded encoding, but its `name` property will differ.\n\n#### `encodings = transcoder.encodings()`\n\nGet an array of encoding objects. This includes:\n\n- Encodings for the `formats` that were passed to the `Transcoder` constructor\n- Custom encodings that were passed to `transcoder.encoding()`\n- Transcoder encodings for either.\n\n### `Encoding`\n\n#### `data = encoding.encode(data)`\n\nEncode data.\n\n#### `data = encoding.decode(data)`\n\nDecode data.\n\n#### `encoding.name`\n\nUnique name. A string.\n\n#### `encoding.commonName`\n\nCommon name, computed from `name`. If this encoding is a transcoder encoding, `name` will be for example `'json+view'` and `commonName` will be just `'json'`. Else `name` will equal `commonName`.\n\n#### `encoding.format`\n\nName of the (lower-level) encoding used by the return value of `encode()`. One of `'buffer'`, `'view'`, `'utf8'`. If `name` equals `format` then the encoding can be assumed to be idempotent, such that `encode(x)` equals `encode(encode(x))`.\n\n## Encoding Interface\n\nCustom encodings must follow the following interface:\n\n```ts\ninterface IEncoding<TIn, TFormat, TOut> {\n  name: string\n  format: 'buffer' | 'view' | 'utf8'\n  encode: (data: TIn) => TFormat\n  decode: (data: TFormat) => TOut\n}\n```\n\n## Install\n\nWith [npm](https://npmjs.org) do:\n\n```\nnpm install level-transcoder\n```\n\n## Contributing\n\n[`Level/transcoder`](https://github.com/Level/transcoder) is an **OPEN Open Source Project**. This means that:\n\n> Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.\n\nSee the [Contribution Guide](https://github.com/Level/community/blob/master/CONTRIBUTING.md) for more details.\n\n## Donate\n\nSupport us with a monthly donation on [Open Collective](https://opencollective.com/level) and help us continue our work.\n\n## License\n\n[MIT](LICENSE)\n\n[level-badge]: https://leveljs.org/img/badge.svg\n\n[level-codec]: https://github.com/Level/codec\n\n[leveldown]: https://github.com/Level/leveldown\n\n[protocol-buffers]: https://github.com/mafintosh/protocol-buffers\n\n[charwise]: https://github.com/dominictarr/charwise\n\n[bytewise]: https://github.com/deanlandolt/bytewise\n\n[lexint]: https://github.com/vweevers/lexicographic-integer-encoding\n\n[abstract-enc]: https://github.com/mafintosh/abstract-encoding\n\n[js-multiformats]: https://github.com/multiformats/js-multiformats\n\n[blockcodec]: https://github.com/multiformats/js-multiformats/blob/master/src/codecs/interface.ts\n","_attachments":{},"homepage":"https://github.com/Level/transcoder","bugs":{"url":"https://github.com/Level/transcoder/issues"},"license":"MIT"}