{"id":22780044,"url":"https://github.com/sitegui/js-binary","last_synced_at":"2025-04-05T08:08:54.729Z","repository":{"id":24904640,"uuid":"28321253","full_name":"sitegui/js-binary","owner":"sitegui","description":"Encode/decode to a custom binary format, much more compact and faster than JSON/BSON","archived":false,"fork":false,"pushed_at":"2024-02-24T09:31:23.000Z","size":77,"stargazers_count":92,"open_issues_count":11,"forks_count":23,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-29T07:08:17.688Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/sitegui.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-12-22T02:13:58.000Z","updated_at":"2024-12-25T06:32:25.000Z","dependencies_parsed_at":"2024-06-18T14:03:40.015Z","dependency_job_id":"35a9aeeb-2ced-4cf9-8466-517c14b98f29","html_url":"https://github.com/sitegui/js-binary","commit_stats":{"total_commits":8,"total_committers":1,"mean_commits":8.0,"dds":0.0,"last_synced_commit":"5a70b33bd27a3284306a13dd1079a8769945b6e4"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sitegui%2Fjs-binary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sitegui%2Fjs-binary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sitegui%2Fjs-binary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sitegui%2Fjs-binary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sitegui","download_url":"https://codeload.github.com/sitegui/js-binary/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247305935,"owners_count":20917208,"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":[],"created_at":"2024-12-11T20:12:07.316Z","updated_at":"2025-04-05T08:08:54.712Z","avatar_url":"https://github.com/sitegui.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JS Binary\n[![Build Status](https://travis-ci.org/sitegui/js-binary.svg?branch=master)](https://travis-ci.org/sitegui/js-binary)\n[![Inline docs](https://inch-ci.org/github/sitegui/js-binary.svg?branch=master)](https://inch-ci.org/github/sitegui/js-binary)\n[![Dependency Status](https://david-dm.org/sitegui/js-binary.svg)](https://david-dm.org/sitegui/js-binary)\n\nEncode/decode to a custom binary format, much more compact and faster than JSON/BSON\n\n## Install\n`npm install js-binary`\n\n## Goal\nThis module is analogous to `JSON.stringify` and `JSON.parse`, but instead of a JSON string, the data is encoded to a custom binary format (using a Buffer instance to store the data).\nThis format was designed to be very *compact* and give support for *more types* (like Date and Buffer).\n\nTo reduce overhead in the format, it carries no information about types. This implies that you must define the data schema to encode/decode properly. Huge plus: this automatically validates the data against the given schema (*input sanitization for free!*). This binary format is well suited for very regular data, like API input/output.\n\nNote that, since it's a binary format, it was not meant to be easily viewed/edited by hand.\n\n## Usage\n```js\nvar user = {\n\tname: {\n\t\tfirst: 'Guilherme',\n\t\tlast: 'Souza'\n\t},\n\tpass: new Buffer('042697a30b2dafbdf91bf66bdacdcba8', 'hex'),\n\tcreationDate: new Date('2014-04-11T21:22:32.504Z'),\n\tactive: true,\n\tachievements: [3, 14, 15, 92, 65, 35]\n}\n\nvar Type = require('js-binary').Type\nvar schema = new Type({\n\tname: {\n\t\tfirst: 'string',\n\t\tlast: 'string'\n\t},\n\tpass: 'Buffer',\n\tcreationDate: 'date',\n\tactive: 'boolean',\n\tachievements: ['uint'],\n\t'optionalField?': 'int'\n})\n\nvar encoded = schema.encode(user)\n\nvar decoded = schema.decode(encoded)\n```\n\n## Benchmark\nA quick example:\n```json\n{\n\t\"name\": \"js-binary\",\n\t\"published\": \"2014-12-21T23:42:46.558Z\",\n\t\"downloads\": 1717\n}\n```\n(76 bytes, without formatting) versus `096a732d62696e617279e000014a6f3b531e86b5` (20 bytes)\n\nOn average, a 2x to 3x space reduction can be observed.\n\nIn the `benchmark` you can find another test with more data. In my machine with node 8.9.0, this is the result:\n```\nEncode\n        JSON\n                Time: 2.47ms\n                Size: 190KiB\n        js-binary\n                Time: 1.453ms (-41%)\n                Size: 51KiB (3.7x less)\nDecode\n        JSON\n                Time: 2.791ms\n        js-binary\n                Time: 0.497ms (-82%)\n```\n\n## Available types\n### Basic types\n* 'uint': unsigned integer (between 0 and 2^53)\n* 'int': signed integer (between -2^53 and 2^53)\n* 'float': a 64-bit floating-point (the JavaScript number type)\n* 'string': a utf-8 string\n* 'Buffer': a Buffer instance\n* 'boolean': a boolean\n* 'regex': a JS RegExp instance\n* 'date': a JS Date instance\n* 'json': any data supported by [JSON format](http://json.org/). Read bellow for more\n* 'oid': mongodb ObjectId (see bellow)\n\n### Compound types\nA compound type is an object with (optional) fields. Those fields may be arrays, but with the restriction that every element has the same data schema.\n\nExamples:\n\n* Nested fields: `{a: {b: 'int', d: {e: 'int'}}}`\n* Optional fields: `{a: 'int', 'b?': 'int', 'c?': {d: 'int'}}`\n* Array fields: `{a: ['int']}`\n* All together now: `{'a?': [{'b?': 'int'}]}`\n\n### Array type\nAn array type in which every element has the same data schema.\n\nExamples:\n\n* Int array: `['int']`\n* Object array: `[{v: 'int', f: 'string'}]`\n\n### JSON type\nAs stated before, the js-binary requires the data to have a rather strict schema. But sometimes, part of the data may not fit this reality. In this case, you can fallback to JSON :)\n\nOf course, a JSON field will miss the point about space efficiency and data validation, but will gain in flexibility.\n\n### ObjectId type\njs-binary gives first-class support for mongodb ObjectId. But since js-binary doesn't (and shouldn't) depend on any peculiar mongodb driver, the rules for this type are:\n\n* Encoding: any object `o` is accepted, as long `new Buffer(String(o), 'hex')` yields a 12-byte Buffer\n* Decoding: returns a 24-char hex-encoded string\n\nThis should be compatible with most ObjectId implementations on the wild\n\n## Spec\nThe binary format spec is documented in the format.md file","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsitegui%2Fjs-binary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsitegui%2Fjs-binary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsitegui%2Fjs-binary/lists"}