{"id":22343044,"url":"https://github.com/wiiseguy/node-structor","last_synced_at":"2026-03-05T21:11:57.054Z","repository":{"id":143899418,"uuid":"443369106","full_name":"Wiiseguy/node-structor","owner":"Wiiseguy","description":"Convert binary file data to JavaScript objects","archived":false,"fork":false,"pushed_at":"2025-12-21T19:33:30.000Z","size":103,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-23T07:16:00.237Z","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/Wiiseguy.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-12-31T14:59:36.000Z","updated_at":"2025-12-21T19:33:34.000Z","dependencies_parsed_at":null,"dependency_job_id":"6b38911f-4586-449c-a91a-c9e452226e9f","html_url":"https://github.com/Wiiseguy/node-structor","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Wiiseguy/node-structor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wiiseguy%2Fnode-structor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wiiseguy%2Fnode-structor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wiiseguy%2Fnode-structor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wiiseguy%2Fnode-structor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Wiiseguy","download_url":"https://codeload.github.com/Wiiseguy/node-structor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wiiseguy%2Fnode-structor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30150028,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T16:58:46.102Z","status":"ssl_error","status_checked_at":"2026-03-05T16:58:45.706Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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-04T08:14:37.946Z","updated_at":"2026-03-05T21:11:57.035Z","avatar_url":"https://github.com/Wiiseguy.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# node-structor\n\n\u003e Convert binary file data to JavaScript objects\n\n## Installation\n\n`npm i node-structor`\n\n## Usage\n\nIn the example below we will be reading a list of people from a binary source.\n\n```js\nconst fs = require('fs')\nconst Structor = require('node-structor')\n\nconst structDef = {\n    numPersons: {\n        $format: 'byte',\n        $ignore: true\n    },\n    persons: {\n        $repeat: 'numPersons',\n        $format: {\n            firstName: 'string7',\n            lastName: 'string7',\n            address: {\n                city: 'string7',\n                street: 'string7',\n                number: 'uint16',\n                zipCode: 'string7'\n            },\n            numHobbies: {\n                $ignore: true,\n                $format: 'byte'\n            },\n            hobbies: {\n                $format: 'string7',\n                $repeat: 'numHobbies'\n            }\n        }\n    }\n}\n\nlet result = Structor.readStruct(structDef, fs.readFileSync('./examples/people.dat'))\n\nconsole.log(result)\n```\n\n\u003e Note that `'string7'` is used - this denotes a string that is prepended by the length of that string. [Reference](\u003chttps://msdn.microsoft.com/en-us/library/system.io.binarywriter.write7bitencodedint(v=vs.110).aspx\u003e).\n\nRunning this will log the following:\n\n```js\n{\n    persons: [\n        {\n            firstName: 'John',\n            lastName: 'A',\n            address: {\n                city: 'New York',\n                street: '1st Ave.',\n                number: 1165,\n                zipCode: '10065'\n            },\n            hobbies: ['eating', 'coding', 'walking']\n        },\n        {\n            firstName: 'Betty',\n            lastName: 'B',\n            address: {\n                city: 'York',\n                street: 'Bridge St.',\n                number: 1,\n                zipCode: 'YO1 6DD'\n            },\n            hobbies: []\n        }\n    ]\n}\n```\n\n## API\n\n### `readStruct(structDef, buffer, [options])`\n\nReads the binary data from the buffer according to the structure definition. Returns a JavaScript object.\n\n### `writeStruct(obj, structDef, data, [options])`\n\nWrites the an object to a binary buffer according to the structure definition. Returns the number of bytes written.\n\n### `sizeOf(structDef, [size = 4096])`\n\nCalculates the size of the binary data that would be written according to the structure definition. The size parameter is optional and defaults to 4096; it references the size of the buffer that will be allocated to be able to calculate the size of the data.\n\n## Types\n\n| Type      | Description                                                                                                                                                                                                                             |\n| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `byte`    | Unsigned byte (0 to 255)                                                                                                                                                                                                                |\n| `uint8`   | Unsigned byte (0 to 255)                                                                                                                                                                                                                |\n| `sbyte`   | Signed byte (-128 to 127)                                                                                                                                                                                                               |\n| `int8`    | Signed byte (-128 to 127)                                                                                                                                                                                                               |\n| `uint16`  | 16-bit unsigned integer (0 to 65,535)                                                                                                                                                                                                   |\n| `int16`   | 16-bit signed integer (-32,768 to 32,767)                                                                                                                                                                                               |\n| `uint32`  | 32-bit unsigned integer (0 to 4,294,967,295)                                                                                                                                                                                            |\n| `int32`   | 32-bit signed integer (-2,147,483,648 to 2,147,483,647)                                                                                                                                                                                 |\n| `uint64`  | 64-bit unsigned integer (read as `BigInt`)                                                                                                                                                                                              |\n| `int64`   | 64-bit signed integer (read as `BigInt`)                                                                                                                                                                                                |\n| `char_*`  | A string of characters with its length defined by the `*`. e.g. `char_28`. When reading, the null (0) bytes are removed from the end. When writing, null bytes are added to the end if the string is shorter than the specified length. |\n| `string0` | A string of characters terminated by a null (0) byte. When used with writeStruct, it will write the string with a null byte at the end.                                                                                                 |\n| `string7` | A string of characters prepended by its [7-bit encoded](\u003chttps://msdn.microsoft.com/en-us/library/system.io.binarywriter.write7bitencodedint(v=vs.110).aspx\u003e) length                                                                    |\n| `string`  | Can only be used in conjunction with `$format`. Read `$length` amount of bytes as a new string. Can also be used with `$encoding` to specify the encoding. Default is `utf8`.                                                           |\n| `buffer`  | Can only be used in conjunction with `$format`. Read `$length` amount of bytes as a new `Buffer`.                                                                                                                                       |\n\n\u003e Note: By default the endianness is little-endian (LE) - But you can explicitly define the endianness e.g. `int16be`, `uint64le`, etc.\n\n## Directives\n\n### `$format`\n\nDefine the format. This can be any of the types mentioned above, or another structure definition.\n\nExamples:\n\n```js\n{\n    someNumber: {\n        $format: 'uint16'    // Results in a single number\n    },\n    anotherNumber: 'uint16'  // Short-hand for the above\n}\n```\n\nSome types only work in conjunction with `$format`, as they require extra information to be on the same level. These are: `string` and `buffer`.\n\nExamples:\n\n```js\n{\n    name: {\n        $format: 'string',\n        $length: 32,\n        $encoding: 'ascii' // $encoding is optional, default is 'utf8'\n    }\n}\n```\n\n```js\n{\n    blobData: {\n        $format: 'buffer',\n        $length: 64000\n    }\n}\n```\n\n### `$repeat`\n\nRepeats the specified `$format`. Can be a number or the name of a property containing the value.\n\nExamples:\n\n```js\n{\n    $format: 'byte',\n    $repeat: 2\n}\n```\n\n```js\n{\n    numObjects: 'byte',\n    objects: {\n        $format: {\n            ...\n        },\n        $repeat: 'numObjects'\n    }\n}\n```\n\n### `$foreach`\n\nA special form of `$repeat`. Must be a referenced value pointing to a previously read `array` combined with an alias.\n\nExamples:\n\n```js\n{\n    numFiles: 'uint16',\n    fileTable: {\n        $repeat: 'numFiles',\n        $format: {\n            name: 'char_24',\n            address: 'uint32',\n            length: 'uint32'\n        }\n    },\n    files: {\n        // Iterate over each item in fileTable as 'file'\n        $foreach: 'fileTable file',\n        $format: {\n            fileName: {\n                $value: 'file.name',\n                $format: 'char_24'\n            },\n            fileContent: {\n                $goto: 'file.address',\n                $format: 'buffer',\n                $length: 'file.length'\n            }\n        }\n    }\n}\n```\n\n### `$switch`\n\nRead the next data differently based on a previously read value. A `default` case can optionally be defined.\n\nExamples:\n\n```js\nconst struct = {\n    type: 'byte',\n    shape: {\n        $switch: 'type',\n        $cases: {\n            1: { // when type is 1, assume circle data follows\n                $format: {\n                    radius: 'uint32'\n                }\n            },\n            2: { // when type is 2, assume rectangle data follows\n                $format: {\n                    width: 'uint16',\n                    height: 'uint16'\n                }\n            },\n            3: { // when type is 3, assume polygon data follows\n                $format: {\n                    numPoints: 'byte',\n                    points: {\n                        $repeat: 'numPoints',\n                        $format: {\n                            x: 'byte',\n                            y: 'byte'\n                        }\n                    }\n                }\n            },\n            default: {\n                $format: {\n                    unknown: 'byte'\n                }\n            }\n        }\n    }\n}\n// Which could result in:\n{\n    type: 1,\n    shape: {\n        radius: 38892\n    }\n}\n// or:\n{\n    type: 2,\n    shape: {\n        width: 96,\n        height: 128\n    }\n}\n// or:\n{\n    type: 3,\n    shape: {\n        points: [\n            { x: 0, y: 2 },\n            { x: 128, y: 24 },\n            { x: 255, y: 8 }\n        ]\n    }\n}\n\n```\n\n### `$ignore`\n\nRead the data, but don't put the property in the eventual JS object. Its value can still be used as a referenced value in other directives.\n\nExamples:\n\n```js\nnumObjects: {\n    $format: 'byte',\n    $ignore: true\n}\n```\n\n### `$goto`\n\nJumps to the specified byte location before reading the value.\n\nExamples:\n\n```js\nsignature: {\n    $goto: 0xf0,\n    $format: 'char_2'\n}\n```\n\n### `$skip`\n\nSkips the specified number of bytes before reading the value.\n\nExamples:\n\n```js\nstartOfHeader: {\n    $skip: 255,\n    $format: 'uint16'\n}\n```\n\n### `$length`\n\nCan be used in conjunction with `$format: 'string'` and **must** be used when `$format: 'buffer'`.\n\nExamples:\n\n```js\nfirstName: {\n    $format: 'string',\n    $length: 32\n}\n```\n\n\u003e Note: when `$format` is `'string'`, `$length` is optional. If not present, characters will be read until a null byte (0) is encountered.\n\n```js\nblobData: {\n    $format: 'buffer',\n    $length: 64000\n}\n```\n\n### `$encoding`\n\nCan only be used in conjunction with `$format: 'string'`.\n\nExamples:\n\n```js\nfirstName: {\n    $format: 'string',\n    $encoding: 'ascii'\n}\n```\n\n\u003e Note: the default value for `$encoding` is `'utf8'`\n\n### `$value`\n\nA special directive that doesn't read anything from the buffer and thus doesn't move the internal cursor. Used to copy a value from another source.\n\n```js\n{\n    name: 'string',\n    nameCopy: {\n        $value: 'name',\n        $format: 'uint32'\n    }\n}\n```\n\n### `$tell`\n\nA special directive that reads the current position of the internal cursor. Must be used in conjunction with `$format: '$tell'`.\n\n```js\n{\n    name: 'string',\n    currentAddress: {\n        $format: '$tell',\n        $tell: 'uint16'\n    }\n}\n```\n\n## Referenced values\n\nEvery numeric directive supports passing a reference value string instead of a hard-coded integer. This can be a simple name pointing to a sibling value, or a more complex path.\n\nExamples:\n\n```js\n{\n    nameLength: 'byte',\n    myName: {\n        $format: 'string',\n        $length: 'nameLength'\n    }\n}\n```\n\n```js\n{\n    header: {\n        config: {\n            nameLength: 'byte'\n        }\n    },\n    myName: {\n        $format: 'string',\n        $length: 'header.config.nameLength'\n    }\n}\n```\n\nDirectives that support this:\n\n-   `$repeat`\n-   `$switch`\n-   `$length` (see above examples)\n-   `$goto`\n-   `$skip`\n-   `$value`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiiseguy%2Fnode-structor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwiiseguy%2Fnode-structor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwiiseguy%2Fnode-structor/lists"}