@fullsnacklab/astro-flow

Declarative control flow components and async iteration primitives for Astro.

An independently maintained derivative of @astropub/flow, originally authored by Jonathan Neal. Credit for the original control-flow implementation belongs to Jonathan Neal and the upstream contributors.

Origins and maintenance

We maintain this derivative to preserve a control-flow API we rely on, strengthen its TypeScript contracts, and support current Astro versions. Full Snack Lab's changes include the shared-package extraction, typed boundaries, slot-rendering compatibility fixes, and regression coverage. This is a continuation of the original work, not a claim that we invented it.

The original @astropub/flow package declares CC0-1.0. Full Snack Lab's additions and modifications are provided under MIT; this does not replace the upstream CC0 dedication. See LICENSE for the licensing distinction and the original repository for its source and history.

This package is maintained independently; no endorsement by Jonathan Neal or the upstream project is implied.

Installation

bun add @fullsnacklab/astro-flow

Usage

Declarative Components

---
import { Iterate, Switch, Case, When } from "@fullsnacklab/astro-flow";
---

<Switch of={status}>
  <Case of="loading">Loading...</Case>
  <Case of="success">Loaded successfully!</Case>
  <Case default>Fallback state</Case>
</Switch>

<When ready={isReady} loggedIn={isLoggedIn}>
  <p>Welcome!</p>
  <Fragment slot="else">
    <p>Please log in.</p>
  </Fragment>
</When>

<Iterate of={items}>
  {(item, index) => <li>{index}: {item}</li>}
</Iterate>

Function children receive (value, index) for iterables and (value, key) for records. Async sources and async function children render sequentially. Missing sources or default slots render nothing.

The factories bind raw Astro slots through their render context. They must not be invoked with mock objects that pretend raw slots already have Astro.slots.render() or has(). Source component wrappers share renderIteration(source, Astro.slots), which uses the documented slot argument API rather than inspecting compiler expressions.

Astro owns escaping and child rendering. Already-marked slot strings retain their rendering instructions. The exported HTMLString preserves its legacy string tag and Astro's native trusted-HTML marker; only construct it from trusted HTML, never raw user input.

Async Iteration Utilities

import { iterate, isIterable, HTMLString } from "@fullsnacklab/astro-flow";

if (isIterable(data)) {
  for await (const val of iterate(data, (x) => x * 2)) {
    console.log(val);
  }
}