{"_id":"@douganderson444/jco","name":"@douganderson444/jco","dist-tags":{"latest":"0.14.1"},"versions":{"0.14.1":{"name":"@douganderson444/jco","version":"0.14.1","description":"JavaScript tooling for working with WebAssembly Components","author":{"name":"Guy Bedford"},"bin":{"jco":"src/jco.js"},"exports":{"browser":"./src/browser.js","default":"./src/api.js"},"imports":{"#ora":{"browser":"./src/ora-shim.js","default":"ora"}},"type":"module","dependencies":{"@douganderson444/preview2-shim":"0.14.1","binaryen":"^111.0.0","chalk-template":"^0.4.0","commander":"^9.4.1","mkdirp":"^1.0.4","ora":"^6.1.2","terser":"^5.16.1"},"devDependencies":{"@bytecodealliance/componentize-js":"^0.5.0","@types/node":"^18.11.17","@typescript-eslint/eslint-plugin":"^5.41.0","@typescript-eslint/parser":"^5.41.0","eslint":"^8.30.0","mocha":"^10.2.0","terser":"^5.16.1","typescript":"^4.3.2"},"repository":{"type":"git","url":"git+https://github.com/bytecodealliance/jco.git"},"keywords":["Wasm","WebAssembly","Component"],"license":"(Apache-2.0 WITH LLVM-exception)","bugs":{"url":"https://github.com/bytecodealliance/jco/issues"},"homepage":"https://github.com/bytecodealliance/jco#readme","scripts":{"build":"cargo xtask build workspace","build:types:preview2-shim":"cargo xtask generate wasi-types","lint":"eslint -c eslintrc.cjs lib/**/*.js packages/*/lib/**/*.js","test":"mocha -u tdd test/test.js --timeout 120000"},"workspaces":["packages/preview2-shim"],"_id":"@douganderson444/jco@0.14.1","gitHead":"6910154917cc05767d8b8a1e6d9d13fbc91b65bb","_nodeVersion":"18.17.1","_npmVersion":"10.2.4","dist":{"integrity":"sha512-mEo1UM4UoUmObsX1N+5OGZTGtFRPZ3twNTNCVhorXo6zVMuLhM9xs/TboFxqlTr1jmU5O8IxLfp6EFXJkbeiTg==","shasum":"6b5cb153369b4be1e8a62b3afa96810363273fe8","tarball":"https://registry.npmjs.org/@douganderson444/jco/-/jco-0.14.1.tgz","fileCount":64,"unpackedSize":29945775,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIEiWb+P9lKNQBs25fcKxs6jV4c+/m2SD3A3z3IcoYlTeAiBvEvi6MJ+hhM3hFRitrBVyKogezvSlMPyxRTxKyaGMBw=="}]},"_npmUser":{"name":"douganderson444","email":"douganderson444@gmail.com"},"directories":{},"maintainers":[{"name":"douganderson444","email":"douganderson444@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/jco_0.14.1_1701658291579_0.527221715653851"},"_hasShrinkwrap":false}},"time":{"created":"2023-12-04T02:51:31.478Z","0.14.1":"2023-12-04T02:51:31.893Z","modified":"2023-12-04T02:51:32.200Z"},"maintainers":[{"name":"douganderson444","email":"douganderson444@gmail.com"}],"description":"JavaScript tooling for working with WebAssembly Components","homepage":"https://github.com/bytecodealliance/jco#readme","keywords":["Wasm","WebAssembly","Component"],"repository":{"type":"git","url":"git+https://github.com/bytecodealliance/jco.git"},"author":{"name":"Guy Bedford"},"bugs":{"url":"https://github.com/bytecodealliance/jco/issues"},"license":"(Apache-2.0 WITH LLVM-exception)","readme":"<div align=\"center\">\n  <h1><code>jco</code></h1>\n\n  <p>\n    <strong>JavaScript toolchain for working with <a href=\"https://github.com/WebAssembly/component-model\">WebAssembly Components</a></strong>\n  </p>\n\n  <strong>A <a href=\"https://bytecodealliance.org/\">Bytecode Alliance</a> project</strong>\n\n  <p>\n    <a href=\"https://github.com/bytecodealliance/jco/actions?query=workflow%3ACI\"><img src=\"https://github.com/bytecodealliance/jco/workflows/CI/badge.svg\" alt=\"build status\" /></a>\n  </p>\n</div>\n\n## Overview\n\n`jco` is a fully native JS tool for working with [WebAssembly Components](https://github.com/WebAssembly/component-model) in JavaScript.\n\nFeatures include:\n\n* \"Transpiling\" Wasm Component binaries into ES modules that can run in any JS environment.\n* WASI Preview2 support in Node.js ([undergoing stabilization](https://github.com/bytecodealliance/jco/milestone/1)) & browsers (experimental).\n* Component builds of [Wasm Tools](https://github.com/bytecodealliance/wasm-tools) helpers, available for use as a library or CLI commands for use in native JS environments, as well as optimization helper for Components via Binaryen.\n* \"Componentize\" command to easily create components written in JavaScript (wrapper of [ComponentizeJS](https://github.com/bytecodealliance/ComponentizeJS)).\n\nFor creating components in other languages, see the [Cargo Component](https://github.com/bytecodealliance/cargo-Component) project for Rust and [Wit Bindgen](https://github.com/bytecodealliance/wit-bindgen) for various guest bindgen helpers.\n\n> **Note**: This is an experimental project, no guarantees are provided for stability, security or support and breaking changes may be made without notice.\n\n## Installation\n\n```shell\nnpm install @bytecodealliance/jco\n```\n\njco can be used as either a library or a CLI via the `jco` CLI command.\n\n## Example\n\nSee the [example workflow](docs/src/example.md) page for a full usage example.\n\n## CLI\n\n```shell\nUsage: jco <command> [options]\n\njco - WebAssembly JS Component Tools\n      JS Component Transpilation Bindgen & Wasm Tools for JS\n\nOptions:\n  -V, --version                         output the version number\n  -h, --help                            display help for command\n\nCommands:\n  componentize [options] <js-source>    Create a component from a JavaScript module\n  transpile [options] <component-path>  Transpile a WebAssembly Component to JS + core Wasm for JavaScript execution\n  run <command> [args...]               Run a WebAssembly Command component\n  opt [options] <component-file>        optimizes a Wasm component, including running wasm-opt Binaryen optimizations\n  wit [options] <component-path>        extract the WIT from a WebAssembly Component [wasm-tools component wit]\n  print [options] <input>               print the WebAssembly WAT text for a binary file [wasm-tools print]\n  metadata-show [options] [module]      extract the producer metadata for a Wasm binary [wasm-tools metadata show]\n  metadata-add [options] [module]       add producer metadata for a Wasm binary [wasm-tools metadata add]\n  parse [options] <input>               parses the Wasm text format into a binary file [wasm-tools parse]\n  new [options] <core-module>           create a WebAssembly component adapted from a component core Wasm [wasm-tools component new]\n  embed [options] [core-module]         embed the component typing section into a core Wasm module [wasm-tools component embed]\n  help [command]                        display help for command\n```\n\nFor help with individual command options, use `jco <cmd> --help`.\n\n### Transpile\n\nTo transpile a component into JS:\n\n```\njco transpile component.wasm -o out-dir\n```\n\nThe resultant file can be imported providing the bindings of the component as if it were imported directly:\n\napp.js\n```\nimport { fn } from './out-dir/component.js';\n\nfn();\n```\n\nImports can be remapped using the `--map` flag, or to provide imports as an argument use the `--instantiation` option.\n\nComponents relying on WASI bindings will contain external WASI imports, which are automatically updated\nto the `@bytecodealliance/preview-shim` package. This package can be installed from npm separately for\nruntime usage. This shim layer supports both Node.js and browsers.\n\nOptions include:\n* `--name`: Give a custom name for the component JS file in `out-dir/[name].js`\n* `--minify`: Minify the component JS\n* `--optimize`: Runs the internal core Wasm files through Binaryen for optimization. Optimization options can be passed with a `-- <binaryen options>` flag separator.\n* `--tla-compat`: Instead of relying on top-level-await, requires an `$init` promise to be imported and awaited first.\n* `--js`: Converts core Wasm files to JavaScript for environments that don't even support core Wasm.\n* `--base64-cutoff=<number>`: Sets the maximum number of bytes for inlining Wasm files into the JS using base64 encoding. Set to zero to disable base64 inlining entirely.\n* `--no-wasi-shim`: Disable the WASI shim mapping to `@bytecodealliance/preview2-shim`.\n* `--map`: Provide custom mappings for world imports. Supports both wildcard mappings (`*` similarly as in the package.json \"exports\" field) as well as `#` mappings for targetting exported interfaces. For example, the WASI mappings are internally defined with mappings like `--map wasi:filesystem/*=@bytecodealliance/preview2-shim/filesystem#*` to map `import as * filesystem from 'wasi:filesystem/types'` to `import { types } from '@bytecodealliance/preview2-shim/filesystem`.\n* `--no-nodejs-compat`: Disables Node.js compat in the output to load core Wasm with FS methods.\n* `--instantiation [mode]`: Instead of a direct ES module, export an `instantiate` function which can take the imports as an argument instead of implicit imports. The `instantiate` function can be async (with `--instantiation` or `--instantiation async`), or sync (with `--instantiation sync`).\n* `--valid-lifting-optimization`: Internal validations are removed assuming that core Wasm binaries are valid components, providing a minor output size saving.\n* `--tracing`: Emit tracing calls for all function entry and exits.\n* `--no-namespaced-exports`: Removes exports of the type `test as \"test:flavorful/test\"` which are not compatible with typescript\n\n#### Bindgen Crate\n\nTo directly call into the transpilation in Rust, the bindgen used in jco is also available on crates.io as [js-component-bindgen](https://crates.io/crates/js-component-bindgen).\n\n### Run\n\nFor Wasm components that implement the WASI Command world, a `jco run` utility is provided to run these applications in Node.js:\n\n```\njco run cowasy.component.wasm hello\n```\n\nUsing the preview2-shim WASI implementation, full access to the underlying system primitives is provided, including filesystem and environment variable permissions.\n\n> [preview2-shim](packages/preview2-shim) is currently being stabilized in Node.js, tracking in https://github.com/bytecodealliance/jco/milestone/1.\n\n### Componentize\n\nTo componentize a JS file run:\n\n```\njco componentize app.js --wit wit -n world-name -o component.wasm\n```\n\nCreates a component from a JS module implementing a WIT world definition, via a Spidermonkey engine embedding.\n\nCurrently requires an explicit install of the componentize-js engine via `npm install @bytecodealliance/componentize-js`.\n\nSee [ComponentizeJS](https://github.com/bytecodealliance/componentize-js) for more details on this process.\n\n> Additional engines might be supported in future via an `--engine` field or otherwise.\n\n## API\n\n#### `transpile(component: Uint8Array, opts?): Promise<{ files: Record<string, Uint8Array> }>`\n\nTranspile a Component to JS.\n\n#### `opt(component: Uint8Array, opts?): Promise<{ component: Uint8Array }>`\n\nOptimize a Component with the [Binaryen Wasm-opt](https://www.npmjs.com/package/binaryen) project.\n\n#### `componentWit(component: Uint8Array, document?: string): string`\n\nExtract the WIT world from a component binary.\n\n#### `print(component: Uint8Array): string`\n\nPrint the WAT for a Component binary.\n\n#### `metadataShow(wasm: Uint8Array): Metadata`\n\nExtract the producer toolchain metadata for a component and its nested modules.\n\n#### `parse(wat: string): Uint8Array`\n\nParse a compoment WAT to output a Component binary.\n\n#### `componentNew(coreWasm: Uint8Array | null, adapters?: [String, Uint8Array][]): Uint8Array`\n\n\"WIT Component\" Component creation tool, optionally providing a set of named adapter binaries.\n\n#### `componentEmbed(coreWasm: Uint8Array | null, wit: String, opts?: { stringEncoding?, dummy?, world?, metadata? }): Uint8Array`\n\n\"WIT Component\" Component embedding tool, for embedding component types into core binaries, as an advanced use case of component generation.\n\n#### `metadataAdd(wasm: Uint8Array, metadata): Uint8Array`\n\nAdd new producer metadata to a component or core Wasm binary.\n\n## Contributing\n\nSee the [Contributing](docs/src/contributing.md) chapter of the jco book.\n\n# License\n\nThis project is licensed under the Apache 2.0 license with the LLVM exception.\nSee [LICENSE](LICENSE) for more details.\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in this project by you, as defined in the Apache-2.0 license,\nshall be licensed as above, without any additional terms or conditions.\n","readmeFilename":"README.md"}