{"id":23722372,"url":"https://github.com/level/encoding-down","last_synced_at":"2025-04-05T17:07:43.515Z","repository":{"id":16470093,"uuid":"80002969","full_name":"Level/encoding-down","owner":"Level","description":"An abstract-leveldown implementation that wraps another store to encode keys and values.","archived":false,"fork":false,"pushed_at":"2023-11-01T05:33:01.000Z","size":129,"stargazers_count":41,"open_issues_count":1,"forks_count":8,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-10-30T00:00:36.164Z","etag":null,"topics":["abstract-leveldown","browser","buffer","codec","encoding","json","level","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Level.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,"governance":null,"roadmap":null,"authors":null},"funding":{"open_collective":"level"}},"created_at":"2017-01-25T10:08:39.000Z","updated_at":"2023-10-17T02:43:56.000Z","dependencies_parsed_at":"2023-12-24T01:00:44.054Z","dependency_job_id":"2a5f8b07-8ab1-4ea1-8f75-a5d9182ac5a3","html_url":"https://github.com/Level/encoding-down","commit_stats":{"total_commits":162,"total_committers":10,"mean_commits":16.2,"dds":0.6728395061728395,"last_synced_commit":"10e59a3c4164b4b8472c50d1e4ace1b048a55c6c"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Level%2Fencoding-down","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Level%2Fencoding-down/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Level%2Fencoding-down/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Level%2Fencoding-down/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Level","download_url":"https://codeload.github.com/Level/encoding-down/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247369952,"owners_count":20927928,"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":["abstract-leveldown","browser","buffer","codec","encoding","json","level","nodejs"],"created_at":"2024-12-30T23:35:46.762Z","updated_at":"2025-04-05T17:07:43.485Z","avatar_url":"https://github.com/Level.png","language":"JavaScript","funding_links":["https://opencollective.com/level"],"categories":[],"sub_categories":[],"readme":"# encoding-down\n\n**Superseded by [`abstract-level`](https://github.com/Level/abstract-level). Please see [Frequently Asked Questions](https://github.com/Level/community#faq).**\n\n## Introduction\n\nStores like [`leveldown`][leveldown] can only store strings and Buffers. Other types, though accepted, are [_serialized_](https://github.com/Level/abstract-leveldown#db_serializekeykey) before storage, which is an irreversible type conversion. For a richer set of data types you can wrap such a store with `encoding-down`. It allows you to specify an _encoding_ to use for keys and values independently. This not only widens the range of input types, but also limits the range of output types. The encoding is applied to all read and write operations: it encodes writes and decodes reads.\n\n[Many encodings are builtin][builtin-encodings] courtesy of [`level-codec`][level-codec]. The default encoding is `utf8` which ensures you'll always get back a string. You can also provide a custom encoding like `bytewise` - [or your own](#custom-encodings)!\n\n## Usage\n\nWithout any options, `encoding-down` defaults to the `utf8` encoding.\n\n```js\nconst levelup = require('levelup')\nconst leveldown = require('leveldown')\nconst encode = require('encoding-down')\n\nconst db = levelup(encode(leveldown('./db1')))\n\ndb.put('example', Buffer.from('encoding-down'), function (err) {\n  db.get('example', function (err, value) {\n    console.log(typeof value, value) // 'string encoding-down'\n  })\n})\n```\n\nCan we store objects? Yes!\n\n```js\nconst db = levelup(encode(leveldown('./db2'), { valueEncoding: 'json' }))\n\ndb.put('example', { awesome: true }, function (err) {\n  db.get('example', function (err, value) {\n    console.log(value) // { awesome: true }\n    console.log(typeof value) // 'object'\n  })\n})\n```\n\nHow about storing Buffers, but getting back a hex-encoded string?\n\n```js\nconst db = levelup(encode(leveldown('./db3'), { valueEncoding: 'hex' }))\n\ndb.put('example', Buffer.from([0, 255]), function (err) {\n  db.get('example', function (err, value) {\n    console.log(typeof value, value) // 'string 00ff'\n  })\n})\n```\n\nWhat if we previously stored binary data?\n\n```js\nconst db = levelup(encode(leveldown('./db4'), { valueEncoding: 'binary' }))\n\ndb.put('example', Buffer.from([0, 255]), function (err) {\n  db.get('example', function (err, value) {\n    console.log(typeof value, value) // 'object \u003cBuffer 00 ff\u003e'\n  })\n\n  // Override the encoding for this operation\n  db.get('example', { valueEncoding: 'base64' }, function (err, value) {\n    console.log(typeof value, value) // 'string AP8='\n  })\n})\n```\n\nAnd what about keys?\n\n```js\nconst db = levelup(encode(leveldown('./db5'), { keyEncoding: 'json' }))\n\ndb.put({ awesome: true }, 'example', function (err) {\n  db.get({ awesome: true }, function (err, value) {\n    console.log(value) // 'example'\n  })\n})\n```\n\n```js\nconst db = levelup(encode(leveldown('./db6'), { keyEncoding: 'binary' }))\n\ndb.put(Buffer.from([0, 255]), 'example', function (err) {\n  db.get('00ff', { keyEncoding: 'hex' }, function (err, value) {\n    console.log(value) // 'example'\n  })\n})\n```\n\n## Usage with [`level`][level]\n\nThe [`level`][level] module conveniently bundles `encoding-down` and passes its `options` to `encoding-down`. This means you can simply do:\n\n```js\nconst level = require('level')\nconst db = level('./db7', { valueEncoding: 'json' })\n\ndb.put('example', 42, function (err) {\n  db.get('example', function (err, value) {\n    console.log(value) // 42\n    console.log(typeof value) // 'number'\n  })\n})\n```\n\n## API\n\n### `db = require('encoding-down')(db[, options])`\n\n- `db` must be an [`abstract-leveldown`][abstract-leveldown] compliant store\n- `options` are passed to [`level-codec`][level-codec]:\n  - `keyEncoding`: encoding to use for keys\n  - `valueEncoding`: encoding to use for values\n\nBoth encodings default to `'utf8'`. They can be a string (builtin `level-codec` encoding) or an object (custom encoding).\n\n## Custom encodings\n\nPlease refer to [`level-codec` documentation][encoding-format] for a precise description of the format. Here's a quick example with `level` and `async/await` just for fun:\n\n```js\nconst level = require('level')\nconst lexint = require('lexicographic-integer')\n\nasync function main () {\n  const db = level('./db8', {\n    keyEncoding: {\n      type: 'lexicographic-integer',\n      encode: (n) =\u003e lexint.pack(n, 'hex'),\n      decode: lexint.unpack,\n      buffer: false\n    }\n  })\n\n  await db.put(2, 'example')\n  await db.put(10, 'example')\n\n  // Without our encoding, the keys would sort as 10, 2.\n  db.createKeyStream().on('data', console.log) // 2, 10\n}\n\nmain()\n```\n\nWith an npm-installed encoding (modularity ftw!) we can reduce the above to:\n\n```js\nconst level = require('level')\nconst lexint = require('lexicographic-integer-encoding')('hex')\n\nconst db = level('./db8', {\n  keyEncoding: lexint\n})\n```\n\n## Contributing\n\n[`Level/encoding-down`](https://github.com/Level/encoding-down) is an **OPEN Open Source Project**. This means that:\n\n\u003e 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[abstract-leveldown]: https://github.com/Level/abstract-leveldown\n\n[leveldown]: https://github.com/Level/leveldown\n\n[level]: https://github.com/Level/level\n\n[level-codec]: https://github.com/Level/codec\n\n[builtin-encodings]: https://github.com/Level/codec#builtin-encodings\n\n[encoding-format]: https://github.com/Level/codec#encoding-format\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flevel%2Fencoding-down","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flevel%2Fencoding-down","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flevel%2Fencoding-down/lists"}