{"id":15387044,"url":"https://github.com/gkjohnson/js-struct-data-view","last_synced_at":"2025-11-13T22:52:36.866Z","repository":{"id":66338480,"uuid":"163451381","full_name":"gkjohnson/js-struct-data-view","owner":"gkjohnson","description":"Set of functions used to read and write object data to and from an ArrayBuffer","archived":false,"fork":false,"pushed_at":"2019-03-10T23:49:22.000Z","size":99,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-10-07T02:54:48.090Z","etag":null,"topics":["arraybuffer","javascript","memory","struct"],"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/gkjohnson.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":"2018-12-28T21:35:29.000Z","updated_at":"2025-02-11T03:30:33.000Z","dependencies_parsed_at":"2024-03-14T04:32:41.129Z","dependency_job_id":null,"html_url":"https://github.com/gkjohnson/js-struct-data-view","commit_stats":{"total_commits":24,"total_committers":1,"mean_commits":24.0,"dds":0.0,"last_synced_commit":"6832d4fdf0024963287c3353dacb74103a0aff5f"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gkjohnson/js-struct-data-view","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gkjohnson%2Fjs-struct-data-view","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gkjohnson%2Fjs-struct-data-view/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gkjohnson%2Fjs-struct-data-view/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gkjohnson%2Fjs-struct-data-view/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gkjohnson","download_url":"https://codeload.github.com/gkjohnson/js-struct-data-view/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gkjohnson%2Fjs-struct-data-view/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":284304462,"owners_count":26982161,"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","status":"online","status_checked_at":"2025-11-13T02:00:06.582Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["arraybuffer","javascript","memory","struct"],"created_at":"2024-10-01T14:51:38.507Z","updated_at":"2025-11-13T22:52:36.844Z","avatar_url":"https://github.com/gkjohnson.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# struct-data-view\n\n\u003c!-- [![npm version](https://img.shields.io/npm/v/js-struct-data-view.svg?style=flat-square)](https://www.npmjs.com/package/js-struct-data-view) --\u003e\n[![travis build](https://img.shields.io/travis/gkjohnson/js-struct-data-view.svg?style=flat-square)](https://travis-ci.org/gkjohnson/js-struct-data-view)\n[![lgtm code quality](https://img.shields.io/lgtm/grade/javascript/g/gkjohnson/js-struct-data-view.svg?style=flat-square\u0026label=code-quality)](https://lgtm.com/projects/g/gkjohnson/js-struct-data-view/)\n\nExploration of approaches for reading and writing object data to and from an ArrayBuffer. Useful for keeping object definitions in a compact form or sharing complex structures between web workers (performance benefits untested).\n\n## Approach\n\n### Defining a Struct\n\nStructs are defined ahead of time using the `StructDefinition` and the `StructMember` classes.\n\n```js\nimport { StructDefinition, ScalarMember, FixedLengthArrayMember } from 'struct-data-view';\n\n// struct Vector3 {\n//   float32 x;\n//   float32 y;\n//   float32 z;\n// }\n// 12 bytes\nconst Vector3 = new StructDefinition(\n    new ScalarMember('x', 'float32'),\n    new ScalarMember('y', 'float32'),\n    new ScalarMember('z', 'float32'),\n);\n\n// struct Line {\n//   uint32 color;\n//   Vector3 points[2];\n//   float32 thickness[2];\n// }\n// 36 bytes\nconst Line = new StructDefinition(\n    new ScalarMember('color', 'uint32'),\n    new FixedLengthArrayMember('points', Vector3, 2),\n    new FixedLengthArrayMember('thickness', 'float32', 2)\n);\n\n```\n\nOnly fixed array lengths and the typed array types are implemented.\n\n### Reading a Struct\n\nOnce a struct is created it can be read from or written to an ArrayBuffer with a few different methods.\n\n#### DataView Helpers\n\nThe slowest of the available methods. Based on the provided struct definition these functions read the values from the provided `DataView` and write them into the target object (or writing them from the target object into the buffer if setting the struct). This approach recursively traverses the struct definition and uses the appropriate DataView `set` / `get` function to write / read the data.\n\n```js\nimport { getStruct, setStruct } from 'struct-data-view';\n\n// ... struct definition...\n\nconst buffer = new ArrayBuffer(36);\nconst dataView = new DataView(buffer);\n\nconst data = {\n    color: 0xff0000,\n    points: [\n        { x: -1, y: -1, z: -1 },\n        { x:  1, y:  1, z:  1 }\n    ],\n    thickness: [1, 2]\n};\nsetStruct(dataView, Line, 0, data);\n\nconst target = {};\ngetStruct(dataView, Line, 0, target);\n\n```\n\n#### Generated Read / Write Functions\n\nThe fastest of the available methods. Based on the provided struct definition a function is written with the appropriate read / write functions inlined to save time. If a single array buffer is provided to read / write from then a fast path with Typed Arrays can be taken.\n\nThe fast path can only be taken if the read can by done with a Typed Array which cannot happen if the byte offset is not byte aligned with the byte length for the given array type.\n\n```js\nimport {\n    createReadStructFunction, createReadStructFromArrayBufferFunction,\n    createWriteStructFunction, createWriteStructFromArrayBufferFunction\n} from 'struct-data-view';\n\n// ... struct definition...\n// ... data definition...\n\nconst buffer = new ArrayBuffer(36);\nconst dataView = new DataView(buffer);\n\nconst target = {};\n\n// slower but can be used generally\nconst writeLineFunc = createWriteStructFunction(Line);\nconst readLineFunc = createReadStructFunction(Line);\nwriteLineFunc(dataView, 0, data);\nreadLineFunc(dataView, 0, target);\n\n// faster but can only be used with one array buffer\nconst fastWriteLineFunc = createWriteStructFromArrayBufferFunction(Line, buffer);\nconst fastReadLineFunc = createReadStructFromArrayBufferFunction(Line, buffer);\nfastWriteLineFunc(0, data);\nfastReadLineFunc(0, target);\n\n```\n\n#### Struct Array Wrapper\n\nA convenience method for reading and writing data to and from an array buffer. Behavior is similar to a Typed Array.\n\n```js\nimport { StructArray } from 'struct-data-view';\n\n// ... struct definition...\n// ... data definition...\n\nconst buffer = new ArrayBuffer(36);\nconst structArray = new StructArray(buffer, Line);\n\nstructArray[0] = data;\nconsole.log(structArray[0]);\n\n```\n\n## TODO / Considerations\n\n- Add constructor support to the struct definitions so a class can be instantiated instead of a basic object.\n- Add support for variable length arrays\n- Add support for strings\n- Add support for seeking through an array\n- Add example for reading and writing data of varying types of structs\n- Add read and write functions to `StructArray` to avoid proxy overhead\n- Add method for reading _only_ the needed values so the overhead of reading all values is not incurred if only a single field is being used.\n- Add pointer support so an offset into the current buffer can be declared.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgkjohnson%2Fjs-struct-data-view","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgkjohnson%2Fjs-struct-data-view","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgkjohnson%2Fjs-struct-data-view/lists"}