# WebAssembly в Elide

Підтримка WebAssembly у версії 1.6.0 експериментальна.

| Що у вас є | Що використати | Результат |
| --- | --- | --- |
| Команда WASI | `elide run app.wasm` | Запускає модуль з імпортами WASI Preview 1. |
| Бібліотека WASM | API `WebAssembly` або імпорт ES-модуля з JS/TS | Робить доступними експорти модуля. |

<img src="/assets/demos/wasm.gif" alt="elide app.wasm — команди WASI та бібліотеки WASM з JavaScript" width="1591" height="546" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

Про компіляцію Java або Kotlin у WebAssembly див. [WebImage](/docs/toolchain/jvm/webimage); результату потрібен власний
завантажувач JavaScript, а не `elide run`. Посібники за цільовими платформами: [Browser WASM](/docs/toolchain/web/wasm) і
[Edge WASM](/docs/toolchain/edge/wasm).

## Запуск файлу WASM

```bash
elide run app.wasm
elide app.wasm
elide run app.wasm -- first second   # program arguments
elide run --timeout=5s app.wasm      # exit 124 after 5 seconds
```

Elide викликає експортовану функцію `_start`, а якщо її немає — `_main`. Модуль без жодної з них завантажуйте з
JavaScript.

| Поведінка | Значення |
| --- | --- |
| Нульовий аргумент | Абсолютний шлях до модуля. |
| Код завершення | Задається викликом WASI `proc_exit`, а не значенням, яке повертає функція. |
| Пастки (traps), пошкоджені бінарні файли | Ненульовий код завершення. |
| `--timeout` | Охоплює створення екземпляра й виконання; завершення з кодом `124`. |

### Точки входу проєкту

Укажіть модуль як точку входу в `elide.pkl`, потім виконайте `elide run`:

```pkl
amends "elide:project.pkl"
name = "wasm-app"
entrypoint { "app.wasm" }
```

Див. [Налаштування проєкту](/docs/projects).

## WASI

Команди отримують імпорти WASI Preview 1 у просторі `wasi_snapshot_preview1`: стандартні потоки, аргументи, код
завершення та операції з файловою системою. Бібліотеки, завантажені з JavaScript, WASI не отримують.

### Доступ до каталогів

Команди WASI не бачать каталогів хоста, доки ви не відобразите хоча б один:

```bash
elide -Xpolyglot.wasm.WasiMapDirs=work::./data run app.wasm
```

Ця команда відображає `./data` у гостьовий каталог `work`. Кілька відображень розділяйте комами:
`work::./data,output::./results`.

Пісочниця при цьому діє як завжди. Щоб відкрити файл через WASI, потрібні права на читання й запис, навіть для
читання:

```bash
elide -Xpolyglot.wasm.WasiMapDirs=work::./data run \
  --sandbox --allow-read=./data --allow-write=./data app.wasm
```

Див. [Пісочниця та обмеження](/docs/sandbox).

## Взаємодія з JavaScript і TypeScript

Глобальний API `WebAssembly` не потребує прапорців:

```javascript
import { readFile } from "node:fs/promises";

const bytes = await readFile(new URL("./math.wasm", import.meta.url));
const { instance } = await WebAssembly.instantiate(bytes, {});
console.log(instance.exports.add(20, 22));
```

Модулі, завантажені з JavaScript, не запускають `_start` чи `_main`. Другий аргумент передає імпорти модуля:

```javascript
const imports = { env: { log: (value) => console.log(value) } };
const { instance } = await WebAssembly.instantiate(bytes, imports);
```

API містить `validate`, `compile`, `Module`, `Instance`, `Memory`, `Table`, `Global`, а також перегляд імпортів і
експортів. Зі скомпільованого `Module` можна створити кілька екземплярів. Читання файлів підпорядковується звичайним
дозволам.

### Імпорт ES-модулів

```javascript
import { add } from "./math.wasm";
console.log(add(20, 22));
```

```javascript
const math = await import("./math.wasm");
console.log(math.add(20, 22));
```

Специфікаторами можуть бути шляхи, URL `file:` або експорти пакетів, які розв'язуються в `.wasm`. Імпорт у фазі
вихідного коду (source phase) повертає скомпільований модуль, екземпляр якого ви створюєте самі:

```javascript
import source mathModule from "./math.wasm";
const math = await WebAssembly.instantiate(mathModule, {});
console.log(math.exports.add(20, 22));
```

## Підтримувані пропозиції WebAssembly

Увімкнені за замовчуванням для команд і взаємодії з JS/TS:

- Змінювані глобальні змінні та операції розширення знака
- Перетворення чисел з рухомою комою на цілі без пасток
- Кілька результатів у функцій і блоків
- Масові операції з пам'яттю та типи-посилання
- Кілька областей пам'яті
- Розширені константні вирази
- Обробка винятків
- Типізовані посилання на функції
- Типи зі збиранням сміття (WasmGC)
- Хвостові виклики
- SIMD фіксованої ширини (`v128`) і relaxed SIMD

Вимкнені за замовчуванням:

| Пропозиція | Параметр | Примітки |
| --- | --- | --- |
| Memory64 | `wasm.Memory64` | Також потребує `wasm.UseUnsafeMemory`. |
| Потоки й атомарні операції | `wasm.Threads` | API хоста WASI для запуску потоків не надається. |
| Арифметика широких цілих | `wasm.WideArithmetic` | Не стосується звичайної арифметики `i64`. |
| Застаріла обробка винятків | `wasm.LegacyExceptions` | Нова пропозиція щодо обробки винятків увімкнена за замовчуванням. |

Увімкніть потрібну за допомогою `-Xpolyglot.<option>=true`, наприклад `-Xpolyglot.wasm.WideArithmetic=true`. Імпортів
хоста, потрібних модулю, це не надає.

## Обмеження

- **Лише бінарні модулі.** Немає `.wat`, компіляції C чи Rust і REPL для WASM.
- **Лише WASI Preview 1.** Немає WASI Preview 2, компонентної моделі та `node:wasi`; немає загального доступу до
  мережі.
- **Імпорти хоста.** `elide run` надає лише WASI, без API браузера й сполучного коду Emscripten.

## Приклади

- [WebAssembly з JavaScript](/docs/code-samples#webassembly-from-javascript)
- [Команда WASI](/docs/code-samples#wasi-command)
