# Host

The filesystem host namespace, with its build, event, and runtime types.

`Host` is the only export of `zyzz/node`. It holds [`Host.create`](/docs/api/node/create) and the types of the host it returns, keeping filesystem access and watching out of the pure compiler entrypoints.

```ts title="scripts/build.ts"
// The namespace import that every Node example uses
import { Host } from 'zyzz/node'

await using host = await Host.create({ packageId: 'my-app', root: 'src' })

await host.build()
```

## Members

[Host.create](/docs/api/node/create)

Open a host that compiles a source directory into an owned output directory.

[build](/docs/api/node/create/build)

Scan, compile, and publish the source tree, and list the changed output
files.

[watch](/docs/api/node/create/watch)

Rebuild after source or dependency changes, and report each build or
failure.

[close](/docs/api/node/create/close)

Stop watching, finish queued builds, and release the output directory lock.

## Types

* **`Host.Build`:** The result of a build, with `changed` and `files`.
* **`Host.Event`:** A watch notification, `{ result }` or `{ error }`.
* **`Host.Runtime`:** The host, with `build`, `watch`, `close`, and `[Symbol.asyncDispose]`.
* **`Host.create.Options`:** The options of `Host.create`.
* **`Host.watch.Options`:** The options of `watch`.

```ts title="scripts/run.ts"
import { Host } from 'zyzz/node'

// Builds once, or watches when the script runs with --watch
export async function run(host: Host.Runtime) {
  if (!process.argv.includes('--watch')) return host.build()

  host.watch({ onResult: (event: Host.Event) => console.log(event) })
}
```

## Errors

`Host` defines no error class. It throws plain `Error` instances for lock, ownership, and lifecycle failures, and passes compiler errors through unchanged.

* **`Source.ExtractError`:** From `zyzz/compiler`. A source value the compiler cannot read, or an import that does not resolve.
* **`Css.CompileError`:** From `zyzz/web`. Conflicting web rules, such as two modules emitting one class with different declarations.
* **`Native.CompileError`:** From `zyzz/compiler`. A native module that uses web-only features, such as CSS contributions.
* **`StyleSheet.CompileError`:** From `zyzz/react-native`. A style the native context cannot compile, such as a `rem` length without `units.rem`.
* **`StyleSheet.SelectionError`:** From `zyzz/react-native`. A `native.set` label missing from the compiled tables, in a build without `contextual`.
* **`Variants.CompileError`:** From `zyzz/react-native`. Invalid native recipe data, such as a recipe with more than 256 selections.

```ts
import { Source } from 'zyzz/compiler'
import { Host } from 'zyzz/node'

await using host = await Host.create({ packageId: 'my-app', root: 'src' })

await host.build().catch((error: unknown) => {
  // Compiler diagnostics name the module and position
  if (error instanceof Source.ExtractError) console.error(error.message)
  else throw error
})
```