• Installation
• Docs
• Usage
• Examples
  • Root Import
  • Feature-specific Import
  • Feature-specific Transform
  • Aggregate Transform
• Debugging
• Architecture
• Contributing
• License
• Contact

Installation

npm install as-labs

Add the transform to your asc command:

asc assembly/index.ts --transform as-labs -o build/module.wasm

If you only want branch hinting, use the feature-specific transform:

asc assembly/index.ts --transform as-labs/branch-hinting -o build/module.wasm

Docs

as-labs is an experimental AssemblyScript package for unstable APIs, proposal shims, and compiler transforms.

The first feature included today is WebAssembly branch hinting. It exposes likely() and unlikely() helpers and emits the metadata.code.branch_hint custom section described by the branch hinting proposal.

Available entrypoints:

• as-labs
• as-labs/branch-hinting

Available transform entrypoints:

• as-labs
• as-labs/branch-hinting

Behavior:

• likely() and unlikely() are erased during compilation.
• The transform emits a single metadata.code.branch_hint custom section.
• Hint offsets are computed from the final emitted wasm.
• The custom section is inserted before the code section to match the proposal.
• Statement conditions are supported right now: if, while, do, and for.
• assume() is intentionally not included. Branch hints are non-semantic metadata, while assume() would change optimizer assumptions.

Usage

Import from the root package if you want the default experimental surface:

import { likely, unlikely } from "as-labs";

Or import the feature directly if you want an explicit dependency on branch hinting:

import { likely, unlikely } from "as-labs/branch-hinting";

Use the helpers as wrappers around branch conditions:

if (likely(condition)) {
  // hot path
}

if (unlikely(condition)) {
  // cold path
}

Examples

Root Import

import { likely, unlikely } from "as-labs";

export function classify(n: i32): i32 {
  if (likely(n > 0)) return 1;
  if (unlikely(n < 0)) return -1;
  return 0;
}

Feature-specific Import

import { likely, unlikely } from "as-labs/branch-hinting";

export function parse(code: i32): i32 {
  if (likely(code == 200)) return 1;
  if (unlikely(code == 500)) return -1;
  return 0;
}

Feature-specific Transform

asc assembly/index.ts --transform as-labs/branch-hinting -o build/module.wasm

Aggregate Transform

asc assembly/index.ts --transform as-labs -o build/module.wasm

The root transform is an umbrella entrypoint. It calls all feature-scoped transforms that are currently included in as-labs.

Debugging

If branch hints do not appear to be emitted:

• verify the transform is enabled
• verify the condition is wrapped directly in likely(...) or unlikely(...)
• verify you are using statement conditions such as if, while, do, or for
• inspect the final wasm for a metadata.code.branch_hint custom section

Architecture

The package is split into:

• a root AssemblyScript entrypoint
• feature-specific AssemblyScript entrypoints such as branch-hinting
• a root transform that aggregates all feature transforms
• feature-specific transforms that own the actual implementation

Branch hinting currently works in two phases:

1. collect and erase likely() / unlikely() calls from the AssemblyScript AST
2. read the final emitted wasm, compute real branch instruction offsets, and inject the custom section

Contributing

The package is intentionally experimental. Contributions should prefer:

• feature isolation by subpath
• conservative root-transform behavior
• tests that validate final wasm output, not just AST rewrites

License

This project is distributed under an open source license. Work on this project is done by passion, but if you want to support it financially, you can do so by making a donation to the project's GitHub Sponsors page.

You can view the full license using the following link: License

Contact

Please send all issues to GitHub Issues and to converse, please send me an email at [email protected]

• Email: Send me inquiries, questions, or requests at [email protected]
• GitHub: Visit the official GitHub repository Here
• Website: Visit my official website at jairus.dev
• Discord: Contact me at My Discord or on the AssemblyScript Discord Server