encounter/jco
0
0
Fork 0
mirror of https://github.com/encounter/jco.git synced 2026-07-10 12:18:38 -07:00
Code Issues Packages Projects Releases Wiki Activity

add readme and coc

Browse Source
This commit is contained in:
Guy Bedford
2022-12-21 15:54:14 -08:00
committed by Guy Bedford
parent a4f8883bdf
commit 9bfebceefe
5 changed files with 426 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CODE_OF_CONDUCT.md
+49
View File
@@ -0,0 +1,49 @@
# Contributor Covenant Code of Conduct
*Note*: this Code of Conduct pertains to individuals' behavior. Please also see the [Organizational Code of Conduct][OCoC].
## Our Pledge
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
## Our Standards
Examples of behavior that contributes to creating a positive environment include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the Bytecode Alliance CoC team at [report@bytecodealliance.org](mailto:report@bytecodealliance.org). The CoC team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The CoC team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the Bytecode Alliance's leadership.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
[OCoC]: https://github.com/bytecodealliance/wasmtime/blob/main/ORG_CODE_OF_CONDUCT.md
[homepage]: https://www.contributor-covenant.org
[version]: https://www.contributor-covenant.org/version/1/4/
ORG_CODE_OF_CONDUCT.md
+139
View File
@@ -0,0 +1,139 @@
# Bytecode Alliance Organizational Code of Conduct (OCoC)
*Note*: this Code of Conduct pertains to organizations' behavior. Please also see the [Individual Code of Conduct](CODE_OF_CONDUCT.md).
## Preamble
The Bytecode Alliance (BA) welcomes involvement from organizations,
including commercial organizations. This document is an
*organizational* code of conduct, intended particularly to provide
guidance to commercial organizations. It is distinct from the
[Individual Code of Conduct (ICoC)](CODE_OF_CONDUCT.md), and does not
replace the ICoC. This OCoC applies to any group of people acting in
concert as a BA member or as a participant in BA activities, whether
or not that group is formally incorporated in some jurisdiction.
The code of conduct described below is not a set of rigid rules, and
we did not write it to encompass every conceivable scenario that might
arise. For example, it is theoretically possible there would be times
when asserting patents is in the best interest of the BA community as
a whole. In such instances, consult with the BA, strive for
consensus, and interpret these rules with an intent that is generous
to the community the BA serves.
While we may revise these guidelines from time to time based on
real-world experience, overall they are based on a simple principle:
*Bytecode Alliance members should observe the distinction between
public community functions and private functions — especially
commercial ones — and should ensure that the latter support, or at
least do not harm, the former.*
## Guidelines
* **Do not cause confusion about Wasm standards or interoperability.**
Having an interoperable WebAssembly core is a high priority for
the BA, and members should strive to preserve that core. It is fine
to develop additional non-standard features or APIs, but they
should always be clearly distinguished from the core interoperable
Wasm.
Treat the WebAssembly name and any BA-associated names with
respect, and follow BA trademark and branding guidelines. If you
distribute a customized version of software originally produced by
the BA, or if you build a product or service using BA-derived
software, use names that clearly distinguish your work from the
original. (You should still provide proper attribution to the
original, of course, wherever such attribution would normally be
given.)
Further, do not use the WebAssembly name or BA-associated names in
other public namespaces in ways that could cause confusion, e.g.,
in company names, names of commercial service offerings, domain
names, publicly-visible social media accounts or online service
accounts, etc. It may sometimes be reasonable, however, to
register such a name in a new namespace and then immediately donate
control of that account to the BA, because that would help the project
maintain its identity.
* **Do not restrict contributors.** If your company requires
employees or contractors to sign non-compete agreements, those
agreements must not prevent people from participating in the BA or
contributing to related projects.
This does not mean that all non-compete agreements are incompatible
with this code of conduct. For example, a company may restrict an
employee's ability to solicit the company's customers. However, an
agreement must not block any form of technical or social
participation in BA activities, including but not limited to the
implementation of particular features.
The accumulation of experience and expertise in individual persons,
who are ultimately free to direct their energy and attention as
they decide, is one of the most important drivers of progress in
open source projects. A company that limits this freedom may hinder
the success of the BA's efforts.
* **Do not use patents as offensive weapons.** If any BA participant
prevents the adoption or development of BA technologies by
asserting its patents, that undermines the purpose of the
coalition. The collaboration fostered by the BA cannot include
members who act to undermine its work.
* **Practice responsible disclosure** for security vulnerabilities.
Use designated, non-public reporting channels to disclose technical
vulnerabilities, and give the project a reasonable period to
respond, remediate, and patch.
Vulnerability reporters may patch their company's own offerings, as
long as that patching does not significantly delay the reporting of
the vulnerability. Vulnerability information should never be used
for unilateral commercial advantage. Vendors may legitimately
compete on the speed and reliability with which they deploy
security fixes, but withholding vulnerability information damages
everyone in the long run by risking harm to the BA project's
reputation and to the security of all users.
* **Respect the letter and spirit of open source practice.** While
there is not space to list here all possible aspects of standard
open source practice, some examples will help show what we mean:
* Abide by all applicable open source license terms. Do not engage
in copyright violation or misattribution of any kind.
* Do not claim others' ideas or designs as your own.
* When others engage in publicly visible work (e.g., an upcoming
demo that is coordinated in a public issue tracker), do not
unilaterally announce early releases or early demonstrations of
that work ahead of their schedule in order to secure private
advantage (such as marketplace advantage) for yourself.
The BA reserves the right to determine what constitutes good open
source practices and to take action as it deems appropriate to
encourage, and if necessary enforce, such practices.
## Enforcement
Instances of organizational behavior in violation of the OCoC may
be reported by contacting the Bytecode Alliance CoC team at
[report@bytecodealliance.org](mailto:report@bytecodealliance.org). The
CoC team will review and investigate all complaints, and will respond
in a way that it deems appropriate to the circumstances. The CoC team
is obligated to maintain confidentiality with regard to the reporter of
an incident. Further details of specific enforcement policies may be
posted separately.
When the BA deems an organization in violation of this OCoC, the BA
will, at its sole discretion, determine what action to take. The BA
will decide what type, degree, and duration of corrective action is
needed, if any, before a violating organization can be considered for
membership (if it was not already a member) or can have its membership
reinstated (if it was a member and the BA canceled its membership due
to the violation).
In practice, the BA's first approach will be to start a conversation,
with punitive enforcement used only as a last resort. Violations
often turn out to be unintentional and swiftly correctable with all
parties acting in good faith.
README.md
+188 -3
View File
@@ -8,9 +8,194 @@
<strong>A <a href="https://bytecodealliance.org/">Bytecode Alliance</a> project</strong>
<p>
<!-- <a href="https://github.com/bytecodealliance/js-component-tools/actions?query=workflow%3ACI"><img src="https://github.com/bytecodealliance/js-component-tools/workflows/CI/badge.svg" alt="build status" /></a>
-->
<a href="https://github.com/bytecodealliance/js-component-tools/actions?query=workflow%3ACI"><img src="https://github.com/bytecodealliance/js-component-tools/workflows/CI/badge.svg" alt="build status" /></a>
</p>
</div>
> See the initial draft PR at https://github.com/bytecodealliance/js-component-tools/pull/1
## Overview
JS Component Tools provides a JS ecosystem tool for working with the emerging [WebAssembly Components](https://github.com/WebAssembly/component-model) specification in JavaScript.
Features include:
* "Transpiling" Wasm Component binaries into ES modules that can run in any JS environment.
* Optimization helpers for Components, including Binaryen and asm.js support.
* Component operations from a JS-native build of [Wasm Tools](https://github.com/bytecodealliance/wasm-tools).
The Rust transpiler and Wasm Tools crates are both compiled from Rust into JS using Wasm Component tools itself.
> This tool is designed primarily for working with already-created Components, and not for creating Components. For creating Components, see the [Cargo Component](https://github.com/bytecodealliance/cargo-Component) and [Wit Bindgen](https://github.com/bytecodealliance/wit-bindgen) projects.
_Note: This is an experimental project, no guarantees are provided for stability or support and breaking changes may be made in future._
## Installation
This is a fully-native JS & Wasm library which can be installed from npm directly.
```sh
npm install js-component-tools
```
JS Component Tools can be used as either a library (e.g. `import { transpile } from 'js-component-tools'`) or as a CLI via the `jsct` CLI command.
## Example
Given an existing Wasm Component, `jsct` provides the tooling necessary to work with this Component fully natively in JS.
For an example, consider a Component `cowsay.wasm`:
```sh
- cowsay.wasm
```
Where we would like to use and run this Component in a JS environment.
### Inspecting Component WIT
As a first step, we might like to look instead this binary black box of a Component and see what it actually does.
To do this, we can use `jsct wit` to extract the "WIT world" of the Component ([WIT](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md) is the typing language used for defining Components).
```sh
> jsct wit cowsay.wasm
world component {
default export interface {
enum cows {
default,
cheese,
daemon,
dragon-and-cow,
dragon,
elephant-in-snake,
elephant,
eyes,
flaming-sheep,
...
}
cow-say: func(text: string, cow: option<cows>) -> string
}
}
```
From the above we can see that this Component exports an interface with a single function export, `say`, which takes
as input a string, an optional cow, and returns a string.
Alternatively `jsct print cowsay.wasm -o out.wat` would output the full concrete Wasm WAT to inspect the Component,
with all the implementation details (don't forget the `-o` flag...).
### Transpiling to JS
To execute the Component in a JS environment, use the `jsct transpile` command to generate the JS for the Component:
```sh
> jsct transpile cowsay.wasm --minify -o wunderbar
Transpiled JS Component Files:
- cowsay/cowsay.core.wasm 2.01 MiB
- cowsay/cowsay.d.ts 0.73 KiB
- cowsay/cowsay.js 6.01 KiB
```
Now the Component can be directly imported and used as an ES module:
test.mjs
```js
import { cowSay } from './cowsawy/cowsawy.js';
console.log(cowSay('Hello Wasm Components!'));
```
The above JavaScript can be executed in Node.js:
```sh
> node test.mjs
________________________
< Hello Wasm Components! >
------------------------
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
```
Or it can be executed in a browser via a module script:
```html
<script type="module" src="test.mjs"></script>
```
There are a number of custom transpilation options available, detailed in the API section below.
## JSCT API
Note if using a synchronous API function, the `$init` method should be imported and awaited first:
```js
import { $init } from 'js-component-tools';
await $init;
```
This is because the JSCT API is built with top-level await compatibility (via `jsct transpile --tla-compat`).
The below is an outline of the available API functions, see [api.d.ts](api.d.ts) file for the exact options.
#### `transpile(component: Uint8Array, opts?): Promise<{ files: Record<string, Uint8Array> }>`
_Transpile a Component to JS._
Transpilation options:
* `name?: string` - name for the generated JS file.
* `instantiation?: bool` - instead of a direct ES module, output the raw instantiation function for custom virtualization.
* `map?: Record<string, string>` - remap component imports
* `validLiftingOptimization?: bool` - optimization to reduce code size
* `compat?: bool` - enables all compat options
* `noNodejsCompat?: bool` - disables Node.js compatible output
* `tlaCompat?: bool` - enable compat in JS runtimes without TLA support
* `base64Cutoff?: number` - size in bytes, under which Wasm modules get inlined as base64.
* `asm?: bool` - use asm.js instead of core WebAssembly for execution.
* `minify?: bool` - minify the output JS.
* `optimize?: bool` - optimize the component with Binaryen wasm-opt first.
* `optArgs?: string[]` - if using optimize, custom optimization options (defaults to best optimization, but this is very slow)
#### `opt(component: Uint8Array, opts?): Promise<{ component: Uint8Array }>`
_Optimize a Component with the [Binaryen Wasm-opt](https://www.npmjs.com/package/binaryen) project._
#### `parse(wat: string): Uint8Array`
_Parse a compoment WAT to output a Component binary._
#### `print(component: Uint8Array): string`
_Print the WAT for a Component binary._
#### `componentNew(coreWasm: Uint8Array | null, opts?): Uint8Array`
_"WIT Component" Component creation tool._
#### `componentWit(component: Uint8Array): string`
_Extract the WIT world from a component binary._
## JSCT CLI
The CLI is available via the `jsct` command, providing all the same
functions and options as the API.
# License
This project is licensed under the Apache 2.0 license with the LLVM exception.
See [LICENSE](LICENSE) for more details.
### Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in this project by you, as defined in the Apache-2.0 license,
shall be licensed as above, without any additional terms or conditions.
api.d.ts
Vendored
+39
View File
@@ -1,39 +1,78 @@
/**
* Optimize a Component with Binaryen wasm-opt optimizations
*/
export function opt(componentBytes: Uint8Array, opts?: { quiet: boolean; optArgs?: string[] }): Promise<{
component: Uint8Array,
compressionInfo: { beforeBytes: number, afterBytes: number }[]
}>;
export interface TranspileOpts {
/// name for the generated JS file.
name?: string,
/// instead of a direct ES module, output the raw
/// instantiation function for custom virtualization.
instantiation?: bool,
/// remap Component imports
map?: Record<string, string>,
/// optimization to reduce code size
validLiftingOptimization?: bool,
/// enables all compat options
compat?: bool,
/// disables Node.js compatible output
noNodejsCompat?: bool,
/// enable compat in JS runtimes without TLA support
tlaCompat?: bool,
/// size in bytes, under which Wasm modules get inlined as base64.
base64Cutoff?: number,
/// use asm.js instead of core WebAssembly for execution.
asm?: bool,
/// minify the output JS.
minify?: bool,
/// optimize the Component with Binaryen wasm-opt first.
optimize?: bool,
/// if using optimize, custom optimization options
/// (defaults to best optimization, but this is very slow)
optArgs?: string[],
}
/**
* Transpile a Component into a JS-executable package
*/
export function transpile(component: Uint8Array, opts?: TranspileOpts): Promise<{ files, imports, exports }>;
/**
* Parse a WAT string into a Wasm binary
*/
export function parse(wat: string): Uint8Array;
/**
* Print a Wasm binary as a WAT string
*/
export function print(binary: Uint8Array | ArrayBuffer): string;
/**
* WIT Component - create a Component from a Wasm core binary
*/
export function componentNew(binary: Uint8Array | ArrayBuffer | null, opts: ComponentOpts | null): Uint8Array;
/**
* Extract the WIT world from a Wasm Component
*/
export function componentWit(binary: Uint8Array | ArrayBuffer): string;
export type StringEncoding = 'utf8' | 'utf16' | 'compact-utf16';
export interface ComponentOpts {
/// wit world for the Component
/// (only needed if not provided in the Component itself,
/// which it usually is)
wit?: string,
/// create a type only Component shell, without implementations
typesOnly?: boolean,
/// adapters to use
adapters?: [string, Uint8Array][],
/// string encoding used by the Component (this should
/// also be picked up from the Component itself)
stringEncoding?: StringEncoding,
}
src/jsct.js
+11 -11
View File
@@ -46,17 +46,6 @@ program.command('opt')
.option('--', 'custom wasm-opt arguments (defaults to best size optimization)')
.action(asyncAction(opt));
program.command('new')
.description('create a WebAssembly component adapted from a component core Wasm [wasm-tools component new]')
.argument('[module]', 'Wasm core module filepath')
.requiredOption('-o, --output <output-file>', 'Wasm component output filepath')
.option('--name <name>', 'custom output name')
.option('--wit <wit>', 'WIT file to use')
.option('--types-only', 'types only component generation')
.option('--adapter <adapter>', 'adapter component')
.option('--encoding <utf8|utf16|compact-utf6>', 'string encoding for WIT')
.action(asyncAction(componentNew));
program.command('wit')
.description('extract the WIT from a WebAssembly Component [wasm-tools component wit]')
.argument('<component-path>', 'Wasm component binary filepath')
@@ -75,6 +64,17 @@ program.command('parse')
.requiredOption('-o, --output <output-file>', 'output binary file path')
.action(asyncAction(parse));
program.command('new')
.description('create a WebAssembly component adapted from a component core Wasm [wasm-tools component new]')
.argument('[module]', 'Wasm core module filepath')
.requiredOption('-o, --output <output-file>', 'Wasm component output filepath')
.option('--name <name>', 'custom output name')
.option('--wit <wit>', 'WIT file to use')
.option('--types-only', 'types only component generation')
.option('--adapter <adapter>', 'adapter component')
.option('--encoding <utf8|utf16|compact-utf6>', 'string encoding for WIT')
.action(asyncAction(componentNew));
program.parse();
function asyncAction (cmd) {