{"id":18046580,"url":"https://github.com/ltla/wasmarrays.js","last_synced_at":"2025-04-05T04:24:47.284Z","repository":{"id":45404620,"uuid":"463724798","full_name":"LTLA/wasmarrays.js","owner":"LTLA","description":"Memory-management wrapper around arrays on the Wasm heap. ","archived":false,"fork":false,"pushed_at":"2023-03-07T22:27:42.000Z","size":1379,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-16T07:07:11.271Z","etag":null,"topics":["webassembly"],"latest_commit_sha":null,"homepage":"https://ltla.github.io/wasmarrays.js","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/LTLA.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":"2022-02-26T01:38:39.000Z","updated_at":"2023-11-02T03:33:28.000Z","dependencies_parsed_at":"2024-11-03T22:15:36.499Z","dependency_job_id":null,"html_url":"https://github.com/LTLA/wasmarrays.js","commit_stats":{"total_commits":34,"total_committers":1,"mean_commits":34.0,"dds":0.0,"last_synced_commit":"8ebad0dcef1ab93d83a54d5fd538ed88d7700394"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LTLA%2Fwasmarrays.js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LTLA%2Fwasmarrays.js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LTLA%2Fwasmarrays.js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LTLA%2Fwasmarrays.js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LTLA","download_url":"https://codeload.github.com/LTLA/wasmarrays.js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247288047,"owners_count":20914289,"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":["webassembly"],"created_at":"2024-10-30T19:07:58.961Z","updated_at":"2025-04-05T04:24:47.264Z","avatar_url":"https://github.com/LTLA.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Helper classes for WebAssembly arrays\n\n## Overview\n\nWebAssembly uses a resizeable `(Shared)ArrayBuffer` as its heap memory store.\nDevelopers can allocate arrays on this heap to pass data efficiently between Javascript and WebAssembly code.\nThe `WasmArray` class wraps these arrays for more convenient use in complex web applications.\nWe provide functions to quickly create new allocations and convert existing `(Typed)Array`s into their corresponding `WasmArray`s.\nWe provide some helper methods to produce a `TypedArray` view from a `WasmArray` and manipulate its contents.\nWe implement finalizers that automatically free the heap allocation when instances of the class are garbage-collected by the Javascript engine.\nUsers may also directly free the memory for greater control.\n\n## Quick start\n\nInstall the package as usual from NPM:\n\n```sh\nnpm i wasmarrays.js\n```\n\nThis is written as an ES6 module, so we can import its methods and classes:\n\n```js\nimport * as wa from \"wasmarrays.js\";\n```\n\nWe assume that the application already has a Wasm `module` object, typically produced by Emscripten.\nWe register our Wasm module with the **WasmArray** package:\n\n```js\nlet space = wa.register(module);\n```\n\nThen we can create `WasmArray`s on that Wasm heap, e.g., a 1000-element array of unsigned 8-bit integers:\n\n```js\nlet my_array = wa.createUint8WasmArray(space, 1000);\n```\n\nCheck out the [API documentation](https://ltla.github.io/wasmarrays.js) for more details.\n\n## Mimicking `TypedArray`s\n\nWe can create a `TypedArray` view of a `WasmArray` by calling:\n\n```js\nmy_array.array(); // Uint8Array view of the allocation\n```\n\nThis view can be used to write or read values from the Wasm heap.\nHowever, some caution is required as it seems that views can be invalidated when the heap is resized.\nWe generally recommend only creating a view immediately before its use, i.e., there should be no Wasm allocations after the creation of a view but before its use.\n\nFor greater robustness to heap resizing, we provide some methods for the `WasmArray` to mimic its `TypedArray` view.\nThis avoids exposing the creation of a view in the caller's code, avoiding any problems from intervening allocations. \nNote that `slice()` methods return a `TypedArray` with its own `ArrayBuffer` that is not susceptible to issues with resizing.\n\n```js\nmy_array.length; // 1000\n\nmy_array.slice(); // new Uint8Array copy of the entire array\nmy_array.slice(500); // new Uint8Array copy from [500, 1000)\nmy_array.slice(500, 600); // new Uint8Array copy from [500, 600)\n\nmy_array.fill(0); // fills the allocation with zero's.\nmy_array.fill(1, 200); // fills [200, 1000) with 1's.\nmy_array.fill(2, 300, 500); // fills [300m 500) with 2's.\n\nvalues = [1,2,3,4,5];\nmy_array.set(values); // fills first five values with 1-\u003e5.\nmy_array.set(values, 101); // fills 101-\u003e105 with 1-\u003e5.\n\nmy_array.map((x) =\u003e x + 1); // new Uint8Array with +1 values.\nmy_array.filter((x) =\u003e x \u003e 5); // new Uint8Array containing all values \u003e 5.\nmy_array.forEach((x, i) =\u003e { /* do something */ });\n```\n\n## Interacting with the heap\n\nFor an instance of a `WasmArray`, the offset of the allocation on its Wasm heap is available in the `offset` property.\nThis can be passed to Wasm functions for efficient access to the array data.\n\nMultiple Wasm heaps may be registered via `register` if there are multiple Wasm-enabled applications that need to use `WasmArray`s.\nCurrently, each Wasm module can only use the memory from its own heap.\nApplications can check whether a `WasmArray` instance refers to an allocation on the appropriate heap by comparing the `space` property with the value returned by `register()`.\nIf it is, the instance's `offset` can be used directly. \nOtherwise, an application can make a copy on their own heap:\n\n```js\nlet copy = my_array.clone(new_space);\n```\n\nAdvanced users may also create `WasmArray`s that are views on other `WasmArray`s.\nThis avoids the need to carry around start/end parameters when only a subset of the data is of interest.\n\n```js\nlet view = my_array.view(20, 50);\n```\n\nWe can also create a view directly on the Wasm heap.\nThis is helpful for wrapping allocations that are owned by other objects (e.g., instances of `embind`-ed C++ classes).\n\n```js\nlet view2 = wa.createUint8WasmArrayView(my_array.space, my_array.length, my_array.offset);\n```\n\n## Lifetime management\n\nFor each `WasmArray` instance created with the `create*WasmArray()` functions, \nwe register a [finalizer callback](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry) when the instance is garbage-collected.\nThis frees its corresponding allocation on the Wasm heap to reduce memory usage in long-running applications.\nThus, most users can operate on `WasmArray` instances without worrying about manual memory management.\n\nThat said, advanced users may prefer to manually free the memory when it is no longer needed.\nFinalizer callbacks may not be run in a predictable manner, so if memory is scarce, direct control is required to guarantee that the memory is released.\nTo achieve this, we can do:\n\n```js\nmy_array.free();\n```\n\n## Contact\n\nThis package is maintained by Aaron Lun ([@LTLA](https://github.com/LTLA)).\nPost feature requests and bug reports on the [GitHub Issues page](https://github.com/LTLA/wasmarrays.js/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fltla%2Fwasmarrays.js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fltla%2Fwasmarrays.js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fltla%2Fwasmarrays.js/lists"}