{"id":16188267,"url":"https://github.com/konsumer/cmem_helpers","last_synced_at":"2025-03-19T03:30:39.846Z","repository":{"id":187585042,"uuid":"677281624","full_name":"konsumer/cmem_helpers","owner":"konsumer","description":"Simple \u0026 light helpers for working with C-memory (in JS)","archived":false,"fork":false,"pushed_at":"2023-11-28T00:25:12.000Z","size":683,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-14T23:50:44.509Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","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/konsumer.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":"2023-08-11T07:19:10.000Z","updated_at":"2025-02-03T16:43:53.000Z","dependencies_parsed_at":"2023-11-27T21:30:20.223Z","dependency_job_id":"7f44642b-27bc-4d6f-b5a8-f5aee86bc18b","html_url":"https://github.com/konsumer/cmem_helpers","commit_stats":null,"previous_names":["konsumer/cmem_helpers"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konsumer%2Fcmem_helpers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konsumer%2Fcmem_helpers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konsumer%2Fcmem_helpers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/konsumer%2Fcmem_helpers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/konsumer","download_url":"https://codeload.github.com/konsumer/cmem_helpers/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243965752,"owners_count":20375917,"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-10-10T07:25:41.205Z","updated_at":"2025-03-19T03:30:39.396Z","avatar_url":"https://github.com/konsumer.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cmem_helpers\n\nThis provides a few simple \u0026 light helpers for working with C-memory. It should be useful for FFI, native node-modules, and browser/node wasm, and has no dependencies. It should also work for other runtimes like bun, deno, or quickjs.\n\nUse it to pass and work with strings, and structs. It is very light and intended for no-emscripten host-code, or situations where you want to do your own thing, a bit.\n\nI also wrote a couple medium posts about how it works:\n\n- [structs](https://medium.com/@konsumer/c-structs-and-javascript-9012d7e0ca8a)\n- [strings](https://medium.com/@konsumer/c-strings-and-javascript-b79784bc921e)\n\n## usage\n\n### installation\n\nYou can add it to your project like this:\n\n```\nnpm i cmem_helpers\n```\n\nAnd then import or require it:\n\n```js\nimport memhelpers from 'cmem_helpers'\n\n// OR\n\nconst memhelpers = require('cmem_helpers')\n```\n\nYou can also use it on the web:\n\n```html\n\u003cscript type=module\u003e\nimport memhelpers from 'https://cdn.jsdelivr.net/npm/cmem_helpers/+esm'\n\u003c/script\u003e\n```\n\nYou can also use an [importmap](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) to make your code look the same:\n\n```html\n\u003cscript type=\"importmap\"\u003e\n{\n  \"imports\": {\n    \"cmem_helpers\": \"https://cdn.jsdelivr.net/npm/cmem_helpers/+esm\"\n  }\n}\n\u003c/script\u003e\n\u003cscript type=module\u003e\nimport memhelpers from 'cmem_helpers'\n// YOUR CODE HERE\n\u003c/script\u003e\n```\n\n### getting started\n\nHere is an example with WASM, in the browser/nodejs:\n\n```js\nimport memhelpers from 'cmem_helpers'\n\n// define this to pass functions to WASM\nconst env = {\n  demo(namePtr){\n    console.log(`Hello ${getString(namePtr)}!`)\n  }\n}\n\n// load your bytes in wasmBytes however you do that\nconst wasmBytes = '...'\n\nconst mod = (await WebAssembly.instantiate(wasmBytes, { env })).instance.exports\n\n// here is the actual setup\nconst { struct, structClass, setString, getString } = memhelpers(mod.memory.buffer, mod.malloc)\n```\n\nThe first param is a buffer associated with the memory, and the second is optional, and it's a way to allocate bytes, and get a pointer. In this example, I exposed a function called `malloc` in my wasm, so I can allocate bytes, in the host. You can see an example in the [test wasm](src/wasm/).\n\n### strings\n\nThese are for basic C-style null-terminated UTF-8 strings.\n\n```js\n// get a string from a pointer, using /0 termination (standard c-string)\ngetString(strPtr)\n\n// explicitly tell it the length\ngetString(strPtr, 100)\n\n// set a string in memory, with length (remember the last /0 char)\nsetString(\"Hello\", address, 6)\n\n// set a string in memory, without length\nsetString(\"Hello\", address)\n\n// get a pointer to a new string (if you setup malloc earlier)\nconst ptr = setString(\"Hello\")\n```\n\n\n### structs\n\nThis very simple helper uses [DataView](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView) to interact directly with the memory.\n\nValid types are:\n\n- `BigInt64`\n- `BigUint64`\n- `Float32`\n- `Float64`\n- `Int16`\n- `Int32`\n- `Int8`\n- `Uint16`\n- `Uint32`\n- `Uint8`\n\nYou can define a struct like this:\n\n```js\nconst Color = struct({\n  r: 'Uint8',\n  g: 'Uint8',\n  b: 'Uint8',\n  a: 'Uint8'\n})\n```\n\nAnd now you can make `Color` objects, with an address, and/or intiial value:\n\n```js\nconst color = Color({r: 0, g: 0, b: , a: 255}, address)\n```\n\nIf you provided a `malloc` function earlier, when you set it up, you can also do this:\n\n```js\nconst color = Color()\nconst color = Color({r: 0, g: 0, b: , a: 255})\n```\n\nAnd it will allocate it for you. It will have a couple members: `_size` and `_address` that you can use in other things, for example to pass the pointer to a function:\n\n```js\nmod.useMyColor(color._address)\n```\n\nYou can also access the underlying bytes, if you need them:\n\n```js\nconsole.log(color._bytes)\n```\n\n#### structClass\n\nYou can also use `structClass`, if you like to use them more like classes, and they will work the same:\n\n```js\nconst Color = structClass({\n  r: 'Uint8',\n  g: 'Uint8',\n  b: 'Uint8',\n  a: 'Uint8'\n})\nconst color = new Color()\n```\n\n\n### planned\n\nI have a few ideas for the future:\n\n- Nested struct fields as pointers (with param for bit-size to support wasm/ffi) or inline-bytes\n- Tool to parse C header and pull out structs, in this format\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkonsumer%2Fcmem_helpers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkonsumer%2Fcmem_helpers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkonsumer%2Fcmem_helpers/lists"}