as-labs 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [Unreleased]
+
+- Added support for branch hinting

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jairus Tanaka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,183 @@
+<h1 align="center"><pre>
+╔═╗╔═╗  ╦  ╔═╗╔╗ ╔═╗
+╠═╣╚═╗══║  ╠═╣╠╩╗╚═╗
+╩ ╩╚═╝  ╩═╝╩ ╩╚═╝╚═╝</pre></h1>
+
+<details>
+<summary>Table of Contents</summary>
+
+- [Installation](#installation)
+- [Docs](#docs)
+- [Usage](#usage)
+- [Examples](#examples)
+  - [Root Import](#root-import)
+  - [Feature-specific Import](#feature-specific-import)
+  - [Feature-specific Transform](#feature-specific-transform)
+  - [Aggregate Transform](#aggregate-transform)
+- [Debugging](#debugging)
+- [Architecture](#architecture)
+- [Contributing](#contributing)
+- [Who uses it?](#who-uses-it)
+- [License](#license)
+- [Contact](#contact)
+
+</details>
+
+# Installation
+
+```sh
+npm install as-labs
+```
+
+Add the transform to your `asc` command:
+
+```sh
+asc assembly/index.ts --transform as-labs -o build/module.wasm
+```
+
+If you only want branch hinting, use the feature-specific transform:
+
+```sh
+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:
+
+```ts
+import { likely, unlikely } from "as-labs";
+```
+
+Or import the feature directly if you want an explicit dependency on branch hinting:
+
+```ts
+import { likely, unlikely } from "as-labs/branch-hinting";
+```
+
+Use the helpers as wrappers around branch conditions:
+
+```ts
+if (likely(condition)) {
+  // hot path
+}
+
+if (unlikely(condition)) {
+  // cold path
+}
+```
+
+# Examples
+
+## Root Import
+
+```ts
+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
+
+```ts
+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
+
+```sh
+asc assembly/index.ts --transform as-labs/branch-hinting -o build/module.wasm
+```
+
+## Aggregate Transform
+
+```sh
+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
+
+# Who uses it?
+
+This package is early and experimental. If you are using it, that likely means you are testing proposal support or custom AssemblyScript workflows before they are ready for a more stable package.
+
+## 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](https://github.com/sponsors/JairusSW) page.
+
+You can view the full license using the following link: [License](./LICENSE)
+
+## Contact
+
+Please send all issues to [GitHub Issues](https://github.com/JairusSW/as-extensions/issues) and to converse, please send me an email at [me@jairus.dev](mailto:me@jairus.dev)
+
+- **Email:** Send me inquiries, questions, or requests at [me@jairus.dev](mailto:me@jairus.dev)
+- **GitHub:** Visit the official GitHub repository [Here](https://github.com/JairusSW/as-extensions)
+- **Website:** Visit my official website at [jairus.dev](https://jairus.dev/)
+- **Discord:** Contact me at [My Discord](https://discord.com/users/600700584038760448) or on the [AssemblyScript Discord Server](https://discord.gg/assemblyscript/)

package/branch-hinting/index.ts

@@ -0,0 +1,9 @@
+@inline
+export function likely(value: bool): bool {
+  return value;
+}
+
+@inline
+export function unlikely(value: bool): bool {
+  return value;
+}

package/branch-hinting/package.json

@@ -0,0 +1,5 @@
+{
+  "main": "../dist/branch-hinting/transform/index.js",
+  "type": "module",
+  "types": "./index.ts"
+}