`) and runs `compose()`.
**What the example does:**
* `ThemeSelect` is a feature — it returns the chosen theme and a way to choose it.
* `LanguageSelect` is a feature — it returns the chosen language and a way to choose it.
* `Appearance` is a layout — through its context it reads the language from a shared Tag and the widgets from another Tag.
* `ThemeProvider` is a provider — through its context it reads the chosen theme.
* The Render Task mounts the `Layout` from `Appearance` wrapped in the `Provider` from `ThemeProvider`.
* `compose()` wires it all; the Render Task runs last.
[nanostores](https://github.com/nanostores/nanostores) here is only for the `task.api` demo. Features can use any state manager.
Best on desktop edit & run it live Copy link
```ts
```
# AI tools
> Plug App-Compose docs into Cursor, Claude, ChatGPT, Copilot, or DeepWiki via llms.txt.
App-Compose publishes LLM-friendly docs and is available on [DeepWiki](https://deepwiki.com/grlt-hub/app-compose).
## Cursor
[Section titled “Cursor”](#cursor)
1. Open chat and type `@docs`
2. Click **Add new doc**
3. Paste the URL and confirm:
```plaintext
https://app-compose.dev/llms-full.txt
```
## Claude / ChatGPT / Copilot
[Section titled “Claude / ChatGPT / Copilot”](#claude--chatgpt--copilot)
Paste this URL into the chat — most assistants accept URLs as context:
```plaintext
https://app-compose.dev/llms-full.txt
```
Use [`llms-small.txt`](https://app-compose.dev/llms-small.txt) for models with a smaller context window (e.g. GPT-3.5, free-tier plans).
## DeepWiki
[Section titled “DeepWiki”](#deepwiki)
Open [deepwiki.com/grlt-hub/app-compose](https://deepwiki.com/grlt-hub/app-compose) and ask anything about the codebase.
# Installation
> Install @grlt-hub/app-compose with your package manager — or try it in the sandbox without installing.
App-Compose has zero dependencies. Written in TypeScript — no `@types` package needed.
## Try App-Compose
[Section titled “Try App-Compose”](#try-app-compose)
You don’t need to install anything to try App-Compose. Open the [sandbox](/sandbox/) in a new tab.
## Install the package
[Section titled “Install the package”](#install-the-package)
Use your preferred package manager.
* npm
```bash
npm install --save-exact @grlt-hub/app-compose
```
* pnpm
```bash
pnpm add --save-exact @grlt-hub/app-compose
```
* yarn
```bash
yarn add --exact @grlt-hub/app-compose
```
* bun
```bash
bun add --exact @grlt-hub/app-compose
```
# Linting
> Enforce App-Compose conventions with the ESLint plugin.
An ESLint plugin enforces App-Compose conventions in TypeScript code. It requires ESLint 9+.
## Installation
[Section titled “Installation”](#installation)
Use your preferred package manager.
* npm
```bash
npm install --save-dev --save-exact @grlt-hub/eslint-plugin-app-compose
```
* pnpm
```bash
pnpm add --save-dev --save-exact @grlt-hub/eslint-plugin-app-compose
```
* yarn
```bash
yarn add --dev --exact @grlt-hub/eslint-plugin-app-compose
```
* bun
```bash
bun add --dev --exact @grlt-hub/eslint-plugin-app-compose
```
## Usage
[Section titled “Usage”](#usage)
Import the plugin and add it to your config. Use the recommended preset for a quick start.
```js
import appCompose from "@grlt-hub/eslint-plugin-app-compose"
import tseslint from "typescript-eslint"
export default tseslint.config(appCompose.configs.recommended)
```
You can also configure it manually.
```js
{
plugins: {
'app-compose': appCompose,
},
rules: {
'app-compose/task-options-order': 'warn',
},
}
```
## Rules
[Section titled “Rules”](#rules)
### no-async-shape-callback
[Section titled “no-async-shape-callback”](#no-async-shape-callback)
❗ This rule errors in the `recommended` config.
💭 This rule requires [typed linting](https://typescript-eslint.io/getting-started/typed-linting/).
***
In a `shape()` callback, async work runs outside the chain, and App-Compose cannot order it. The plugin reports every callback that returns a `Promise`.
```ts
// ❌ Wrong
shape(user.result, async (u) => await fetchAvatar(u.id))
// ✅ Correct
shape(fetchAvatar.result, (a) => a.url)
```
### no-coda-debug
[Section titled “no-coda-debug”](#no-coda-debug)
❗ This rule errors in the `recommended` config.
***
The `debug()` helper from `@grlt-hub/app-coda` prints task state to the console. The plugin reports every call to it, so it stays out of committed code.
```ts
import { compose } from "@grlt-hub/app-compose"
import { debug } from "@grlt-hub/app-coda"
// ❌ Wrong
compose().step(login).step(debug(login)).run()
// ✅ Correct
compose().step(login).run()
```
### task-options-order
[Section titled “task-options-order”](#task-options-order)
⚠️ This rule warns in the `recommended` config.
🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
***
This order matches how a Task reads top-to-bottom: `name` first, then `run` before the optional `enabled`. Inside both, `context` comes before `fn`. The plugin reports when the order differs.
```ts
// ❌ Wrong
createTask({
name: "alpha",
enabled: {
fn: check,
context: { authorized: authorizedTag },
},
run: {
context: { timeout: timeoutTag },
fn: init,
},
})
// ✅ Correct
createTask({
name: "alpha",
run: {
context: { timeout: timeoutTag },
fn: init,
},
enabled: {
context: { authorized: authorizedTag },
fn: check,
},
})
```
### wire-options-order
[Section titled “wire-options-order”](#wire-options-order)
⚠️ This rule warns in the `recommended` config.
🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
***
A Wire carries data from a source to a destination tag, so `from` is listed before `to`. The plugin reports when the order differs.
```ts
// ❌ Wrong
createWire({
to: apiUrl,
from: literal("https://api.example.com"),
})
// ✅ Correct
createWire({
from: literal("https://api.example.com"),
to: apiUrl,
})
```
# Quick Start
> Walk through App-Compose in five steps — create a Task, run it, pass data, disable it, handle failures.
App-Compose is built on the three key pieces: *Task*, *Tag*, and *Wire*. A Task does the work. A Tag holds a value. A Wire supplies it.
No magic, no copy-paste, no surprises at startup — everything else flows from these three. Five short steps follow.
You will learn
* How to create a Task
* How to run a Task
* How to pass data to a Task
* How to disable a Task
* When a Task fails or is skipped
## How to create a Task
[Section titled “How to create a Task”](#how-to-create-a-task)
A Task is one unit of work — it has a `name` and a function to `run`. A Task can be as small as a single API request, or as large as a product feature.
```ts
const fetchUser = createTask({
name: "fetch-user",
run: {
fn: async () => {
const response = await fetch("https://jsonplaceholder.typicode.com/users/1")
const result = await response.json()
console.log(JSON.stringify(result, null, 2))
return result
},
},
})
```
**Note** that every Task must have a `name` and a `run.fn`. These are the only required properties. The `run.fn` can be either a synchronous or an asynchronous function. It can return a value to be used by other Tasks, or return nothing if the Task only performs a side effect.
## How to run a Task
[Section titled “How to run a Task”](#how-to-run-a-task)
To run a Task, place it in a *Step*. A Step is a position in the run order. Steps let you say what runs before what, and what runs together.
Steps follow two rules:
1. **Each `.step()` runs after the previous one.** `.step(a).step(b)` — first `a`, then `b`.
2. **Passing an array runs Tasks in parallel.** `.step([a, b])` — `a` and `b` run at the same time.
```js
.step(alpha)
.step([beta, gamma])
.step(delta)
// is equivalent to:
alpha()
.then(() => Promise.all([beta(), gamma()]))
.then(() => delta())
```
Once all the Steps are listed, all that’s left is to call `run()`.
Best on desktop edit & run it live Copy link
```ts
import { compose, createTask } from "@grlt-hub/app-compose"
const fetchUser = createTask({
name: "fetch-user",
run: {
fn: async () => {
const response = await fetch("https://jsonplaceholder.typicode.com/users/1")
const result = await response.json()
console.log(JSON.stringify(result, null, 2))
return result
},
},
})
compose()
// 👇 define
.step(fetchUser)
// 👇 run
.run()
```
## How to pass data to a Task
[Section titled “How to pass data to a Task”](#how-to-pass-data-to-a-task)
Most Tasks need data from outside — a username, a product ID, the current locale. To stay reusable, they read it through a *Context* (a property of the Task config) instead of hardcoding values. `run.fn` receives whatever `run.context` resolves to.
```ts
const fetchUser = createTask({
name: "fetch-user",
run: {
context: { id: userId.value },
fn: (ctx) => console.log(`Fetching user ${ctx.id}`),
},
})
```
There are two ways to fill it.
### Through a Tag
[Section titled “Through a Tag”](#through-a-tag)
A *Tag* is a placeholder for data. A Task reads it through `tag.value`. A `createWire` supplies that value — so the Task never knows where it came from.
```ts
.step(logIn)
.step(createWire({ from: logIn.result.id, to: userId }))
.step(fetchUser)
// is equivalent to:
[ logIn.result.id ] => [ userId ] => [ fetchUser reads userId.value ]
(source) (Tag) (reader)
```
Have a look at the result:
Best on desktop edit & run it live Copy link
```ts
import { createWire, compose, tag, createTask } from "@grlt-hub/app-compose"
const userId = tag
("userId")
const fetchUser = createTask({
name: "fetch-user",
run: {
context: { userId: userId.value },
fn: async (ctx) => {
const response = await fetch(
// 👇 userId is passed from Context
`https://jsonplaceholder.typicode.com/users/${ctx.userId}`,
)
const result = await response.json()
console.log(JSON.stringify(result, null, 2))
},
},
})
const logIn = createTask({
name: "log-in",
run: {
fn: () => {
// 👇 Try different values here
return { id: 1 }
},
},
})
compose()
.step(logIn)
.step(createWire({ from: logIn.result.id, to: userId }))
.step(fetchUser)
.run()
```
For values you already know upfront — a primitive or object — wrap them in `literal`. That tells App-Compose the value is data, not a reference to another Task or Tag.
```ts
import { literal } from "@grlt-hub/app-compose"
.step(createWire({ from: literal(42), to: userId }))
```
The path is the same — only the source changes.
Caution
Keep `createWire` and Tasks in separate `.step()` calls. If they share a Step, App-Compose throws an error.
```ts
// ❌ Wrong
.step([createWire(...), task])
// ✅ Correct
.step(createWire(...)).step(task)
// ✅ Correct
.step(
compose().step(createWire(...)).step(task)
)
```
### Task to Task
[Section titled “Task to Task”](#task-to-task)
One Task reads another’s result directly — no Tag, no Wire. The two are now coupled. Reasonable when they always run together; otherwise, prefer a Tag.
Best on desktop edit & run it live Copy link
```ts
import { compose, createTask } from "@grlt-hub/app-compose"
const logIn = createTask({
name: "log-in",
run: {
fn: () => ({ userId: 1 }),
},
})
const fetchUser = createTask({
name: "fetch-user",
run: {
context: {
// 👇 directly coupled to logIn
userId: logIn.result.userId,
},
fn: async (ctx) => {
const response = await fetch(`https://jsonplaceholder.typicode.com/users/${ctx.userId}`)
const result = await response.json()
console.log(JSON.stringify(result, null, 2))
},
},
})
compose()
.step(logIn)
.step(fetchUser)
.run()
```
Caution
Coupled Tasks need separate `.step()` calls. In `.step([logIn, fetchUser])` they run in parallel — `fetchUser` tries to read `logIn`’s result before it exists. App-Compose throws an error.
```ts
// ❌ Wrong
.step([logIn, fetchUser])
// ✅ Correct
.step(logIn).step(fetchUser)
```
## How to disable a Task
[Section titled “How to disable a Task”](#how-to-disable-a-task)
Every Task is enabled by default. To skip one based on a feature flag, the current user, or any other state — add an `enabled` block next to `run`.
`enabled` has the same shape as `run`, but `enabled.fn` returns `boolean | Promise`. A `false` result skips the Task.
Best on desktop edit & run it live Copy link
```ts
import { compose, createTask } from "@grlt-hub/app-compose"
const featureFlags = createTask({
name: "feature-flags",
run: {
fn: () => {
// 👇 true = Task runs, false = Task is skipped
const flags = { logInAllowed: true }
console.log(JSON.stringify(flags, undefined, 2))
return flags
},
},
})
const logIn = createTask({
name: "log-in",
run: {
fn: () => console.log("[log-in]: user logged"),
},
enabled: {
context: featureFlags.result.logInAllowed,
// 👇 Return false to skip this Task
fn: (enabled) => enabled,
},
})
compose()
.step(featureFlags)
.step(logIn)
.run()
```
## When a Task fails or is skipped
[Section titled “When a Task fails or is skipped”](#when-a-task-fails-or-is-skipped)
When a Task fails or is skipped, every Task that reads from it is **skipped** too. The path doesn’t matter — Tag or direct, the result is the same. Your app keeps running.
Best on desktop edit & run it live Copy link
```ts
import { compose, createTask, createWire, tag } from "@grlt-hub/app-compose"
const userId = tag("userId")
const logIn = createTask({
name: "log-in",
run: {
fn: () => {
// 👇 uncomment to make logIn fail
// throw new Error("oops")
return { userId: 1 }
},
},
// 👇 or uncomment to skip logIn instead
// enabled: { fn: () => false },
})
// reads through a Tag
const fetchUser = createTask({
name: "fetch-user",
run: {
context: userId.value,
fn: () => {},
},
})
// reads directly
const loadCart = createTask({
name: "load-cart",
run: {
context: logIn.result.userId,
fn: () => {},
},
})
// independent — runs no matter what
const sendAnalytics = createTask({
name: "send-analytics",
run: { fn: () => {} },
})
// 👇 prints every task's status
const debug = createTask({
name: "debug",
run: {
context: {
[logIn.name]: logIn.status,
[fetchUser.name]: fetchUser.status,
[loadCart.name]: loadCart.status,
[sendAnalytics.name]: sendAnalytics.status,
},
fn: (ctx) => {
Object.entries(ctx).forEach(([name, status]) => {
console.log(`${name} status: ${status}`)
})
},
},
})
compose()
.step(logIn)
.step(createWire({ from: logIn.result.userId, to: userId }))
.step([fetchUser, loadCart, sendAnalytics])
.step(debug)
.run()
```
An [optional](/guides/optional) modifier lets a Task keep running even when its source fails or skips. That’s a topic for the guides.
## Next Steps
[Section titled “Next Steps”](#next-steps)
The guides cover more. But first, set up your project — head to **[Installation](/learn/installation/)**.
# Using TypeScript
> Type your App-Compose code so TypeScript catches mismatches on supply and read.
App-Compose is written in TypeScript. This page shows how to type your code.
For the full list of exported types, see [reference/types](/reference/types)
## Typing a Tag
[Section titled “Typing a Tag”](#typing-a-tag)
A Tag holds a typed value. TypeScript then catches mismatches on both ends — supply and read.
Best on desktop edit & run it live Copy link
```ts
import { tag } from "@grlt-hub/app-compose"
const title = tag("title")
```
# Overview
> Public API reference for App-Compose — one page per function, type, or helper.
Each page documents one piece of the public API. Use it to look something up, not to learn a pattern.
Missing one? [Tell us](/community/) or send a PR.
# compose
> Creates a Composer — chains Tasks and Wires through .step(), then runs, inspects, or guards them.
`compose()` returns a Composer. `.step()` adds Tasks and Wires; `.run()`, `.graph()`, and `.guard()` consume the chain.
## graph
[Section titled “graph”](#graph)
Returns the chain as a tree without executing it.
* `.graph()` — Returns a JSON-serializable tree
* Each node has a `type`: `"seq"`, `"con"`, or `"run"`
* `seq` — Sequential group; children run one after another. The tree’s root is always a `seq`
* `con` — Concurrent group; children run in parallel
* Both `seq` and `con` have `meta.name` (from `.meta({ name })`, or `undefined`) and `children`
* `children` may contain `run`, `seq`, or `con` nodes; a nested `compose()` appears as a nested `seq`
* `run` — Leaf for a Task or Wire with `meta.name` (Task name, or destination Tag names joined with `+` for a Wire), `meta.kind` (`"task"` or `"wire"`), `id`, and `dependencies`
* `id` — Increments in tree-traversal order from `0`
* `dependencies` — `{ required: number[], optional: number[] }`. IDs of `run` nodes this leaf reads from. In `required`, an entry of `-1` means no earlier `run` produces that value; `optional` omits missing producers
```ts
compose()
.meta({ name: "app" })
.step(createWire({ from: literal(1), to: userId }))
.step([fetchUser, fetchPermissions])
.step(compose().meta({ name: "cleanup" }).step(close))
.graph()
```
```json
{
"type": "seq",
"meta": { "name": "app" },
"children": [
{
"type": "run",
"meta": { "name": "userId", "kind": "wire" },
"id": 0,
"dependencies": { "required": [], "optional": [] }
},
{
"type": "con",
"meta": {},
"children": [
{
"type": "run",
"meta": { "name": "fetchUser", "kind": "task" },
"id": 1,
"dependencies": { "required": [0], "optional": [] }
},
{
"type": "run",
"meta": { "name": "fetchPermissions", "kind": "task" },
"id": 2,
"dependencies": { "required": [0], "optional": [] }
}
]
},
{
"type": "seq",
"meta": { "name": "cleanup" },
"children": [
{
"type": "run",
"meta": { "name": "close", "kind": "task" },
"id": 3,
"dependencies": { "required": [], "optional": [] }
}
]
}
]
}
```
## guard
[Section titled “guard”](#guard)
Checks the chain configuration without executing it.
* `.guard()` — Returns nothing; throws on the first problem found
* Duplicate Task or Wire — same instance added twice
* Missing context — a Spot has no producer in the chain
* Unused Wire — its value is never read
```ts
expect(() => app.guard()).not.toThrow()
```
Same checks run inside `.run()`, where unused Wires log a warning via `console.warn` instead of throwing.
## meta
[Section titled “meta”](#meta)
Attaches metadata to the chain: a `name` and lifecycle hooks.
* `.meta({ name?, hooks? })` — Updates `name` and/or `hooks` on the chain
* `name` — String identifier. Appears in `.graph()` output, in messages from the guard, and in `onStart`/`onComplete` payloads
* `hooks.onStart({ meta })` — Fires when the chain starts; receives the chain’s meta
* `hooks.onComplete({ meta })` — Fires when the chain completes; receives the chain’s meta
* `hooks.onTaskFail({ task, error })` — Fires when a Task inside the chain fails; receives the failing Task and its error
* Returns a Composer
```ts
compose()
.meta({
name: "app",
hooks: {
onStart: ({ meta }) => console.log(`${meta?.name}: start`),
onComplete: ({ meta }) => console.log(`${meta?.name}: complete`),
onTaskFail: ({ task, error }) => console.error(`${task.name}:`, error),
},
})
.step(loadUser)
```
## run
[Section titled “run”](#run)
Executes the chain.
* `.run()` — Returns `Promise`
* `scope.get(spot)` — Returns the resolved value of `spot`, or `undefined`
```ts
const scope = await compose()
.step(loadUser)
.step(createWire({ from: loadUser.result.id, to: userId }))
.run()
scope.get(loadUser.result) // { id, name }
scope.get(loadUser.status) // "done"
scope.get(userId.value) // the id
```
Before execution, `.run()` runs the guard. Duplicate Tasks or Wires and missing context throw; unused Wires log a warning via `console.warn`. Use `.guard()` for a strict variant where unused Wires also throw.
`.get` returns `undefined` when the Spot has no value — a Task’s `result` after it failed or was skipped, or a Tag that no Wire has supplied.
## step
[Section titled “step”](#step)
Appends a Task, Wire, or nested Composer to the chain.
* `.step(child)` — Appends `child` as the next sequential step
* `.step([...children])` — Appends an array as a concurrent group. Members start together
* `child`, array member — A Task, a Wire, or another Composer
* Returns a Composer
* Throws when the argument is anything else
```ts
compose()
.step(loadConfig)
.step([fetchUser, fetchPermissions])
.step(createWire({ from: literal("/api"), to: apiUrl }))
.step(compose().step(setup).step(start))
.step([compose().step(dashboard), compose().step(analytics)])
```
Each `.step()` runs after the previous one completes; later steps can read values produced by earlier steps. Members of a concurrent group cannot read each other’s values.
# createTask
> Creates a Task — one unit of work with a name, a run function, and optional inputs.
Creates a Task — one unit of work with a `name` and a `run.fn`.
* `createTask(config)` — Returns a Task
* `config.name` — Required string used in errors and `task.name`
* `config.run.fn` — Required function; receives `config.run.context` resolved, returns the Task’s value. Sync or async
* `config.run.context` — Optional `Spot`, or record or array of Spots
* `config.enabled.fn` — Optional function; receives `config.enabled.context` resolved, returns a boolean. `false` skips the Task. Sync or async
* `config.enabled.context` — Optional `Spot`, or record or array of Spots
* `task.name` — Mirror of `config.name`
* `task.kind` — Literal string `"task"`
* `task.result` — What `run.fn` returns
* `task.status` — `Spot<"done" | "fail" | "skip">`
* `task.error` — `Spot`; set when status is `"fail"`
```ts
createTask({
name: "ping",
run: { fn: () => "pong" },
})
createTask({
name: "fetchUser",
run: {
context: userId.value,
fn: (id) => fetch(`/users/${id}`).then((r) => r.json()),
},
})
createTask({
name: "loadProfile",
run: { context: user.result, fn: (u) => u.profile },
enabled: { context: featureFlag.value, fn: (f) => f.profile },
})
```
Status is `"fail"` when `run.fn` or `enabled.fn` throws, `"skip"` when `enabled.fn` returns `false` or any required context is missing, `"done"` otherwise.
# createWire
> Builds a Wire — supplies a value to a Tag so Tasks reading the Tag can use it.
Supplies a value to a Tag.
* `createWire(config)` — Returns a Wire
* `config.from` — A `Spot`, or a record or array of Spots
* `config.to` — A Tag, or a record or array of Tags; must match `from`’s shape
* `wire.name` — Destination Tag names joined with `+`
* `wire.kind` — Literal string `"wire"`
```ts
const userId = tag("userId")
createWire({ from: user.result.id, to: userId })
const userRole = tag("userRole")
createWire({
from: { id: user.result.id, role: user.result.role },
to: { id: userId, role: userRole },
})
createWire({
from: [user.result.id, user.result.role],
to: [userId, userRole],
})
```
# is
> Runtime checks for App-Compose units.
Runtime checks for App-Compose units.
* `is.tag` — Predicate for values returned by `tag(...)`
* `is.task` — Predicate for values returned by `createTask(...)`
* `is.wire` — Predicate for values returned by `createWire(...)`
* `is.runnable` — Predicate for any value returned by `createTask(...)` or `createWire(...)`
Best on desktop edit & run it live Copy link
```ts
const apiUrl = tag("apiUrl")
const auth = createTask({
name: "auth",
run: { fn: () => {} },
})
const apiUrlWire = createWire({
from: literal(""),
to: apiUrl,
})
describe("is", () => {
it("is.tag", () => {
expect(is.tag(apiUrl)).toBeTruthy()
expect(is.tag(auth)).toBeFalsy()
expect(is.tag(apiUrlWire)).toBeFalsy()
})
it("is.task", () => {
expect(is.task(auth)).toBeTruthy()
expect(is.task(apiUrl)).toBeFalsy()
expect(is.task(apiUrlWire)).toBeFalsy()
})
it("is.wire", () => {
expect(is.wire(apiUrlWire)).toBeTruthy()
expect(is.wire(auth)).toBeFalsy()
expect(is.wire(apiUrl)).toBeFalsy()
})
it("is.runnable", () => {
expect(is.runnable(apiUrlWire)).toBeTruthy()
expect(is.runnable(auth)).toBeTruthy()
expect(is.runnable(apiUrl)).toBeFalsy()
})
})
```
# literal
> Wraps a known value (primitive or object) so a Wire or Task can use it as a source.
Wraps a value as data — not a reference to a Task or Tag.
`literal(value)` — Returns a `Spot`. Use for values you already know upfront — a primitive or object
```ts
literal(42)
literal("https://api.example.com")
literal({ retries: 3, timeout: 1000 })
```
# optional
> Marks a value as not required — works inside run.context, enabled.context, createWire.from, and shape.
Marks a value as not required — the Task still runs when the source is missing.
`optional(spot)` — Wraps a `Spot` and returns a `Spot`. Works inside `run.context`, `enabled.context`, `createWire.from`, and `shape`
```ts
optional(user.result)
optional(myTag.value)
```
# shape
> Transforms one or several source values into a new one — inside run.context, enabled.context, or a Wire.
Transforms one or several Spots into a new value. Works inside `run.context`, `enabled.context`, and `createWire.from`.
* `shape(spot, fn)` — Returns a `Spot`. `fn` receives the value of `spot`
* `shape(sources, fn)` — Returns a `Spot` from a record or array of `Spot`s. `fn` receives an object or array of their values
* `shape(sources)` — Returns a `Spot` without remapping the value of record or array of `Spot`s, only grouping them into one `Spot`.
```ts
shape(user.result, (u) => u.name.toUpperCase())
shape({ first: firstName.result, last: lastName.result }, (v) => `${v.first} ${v.last}`)
shape([firstName.result, lastName.result], ([first, last]) => `${first} ${last}`)
shape({ first: firstName.result, last: lastName.result }) // Spot<{ first: string; last: string }>
```
When `shape` fails, the downstream Task skips — the source Task fails, or the callback throws
# tag
> Creates a Tag — a typed, named placeholder that a Wire supplies and a Task reads.
Creates a typed placeholder for a value that a Wire supplies and a Task reads.
* `tag(name)` — Returns a Tag of value type `T` (default `never`). `name` is a debug string used in error messages and Wire names
* `tag.name` — The string passed to `tag(...)`
* `tag.value` — Typed reference to the Tag’s value, used inside `run.context`
```ts
const userId = tag("userId")
userId.name // "userId"
userId.value // Spot
```
# Exported Types
> Public TypeScript types exported from App-Compose.
Types exported from `@grlt-hub/app-compose`
## ComposeHookMap
[Section titled “ComposeHookMap”](#composehookmap)
Type for compose lifecycle hooks: `onStart`, `onComplete`, `onTaskFail`.
Best on desktop edit & run it live Copy link
```ts
import { type ComposeHookMap } from "@grlt-hub/app-compose"
const hookMap: ComposeHookMap = {
onStart: (event) => console.log(event.meta),
onComplete: (event) => console.log(event.meta),
onTaskFail: (event) => console.log(event.task, event.error),
}
```
## Composer
[Section titled “Composer”](#composer)
The type returned by `compose()`.
Best on desktop edit & run it live Copy link
```ts
import { type Composer, compose } from "@grlt-hub/app-compose"
const app: Composer = compose()
```
## Spot\
[Section titled “Spot\”](#spott)
The type of a value source — created by `literal`, `optional`, `shape`, or exposed as `task.result`, `task.status`, `task.error`, and `tag.value`. `T` is the value type.
## SpotValue\
[Section titled “SpotValue\”](#spotvaluet)
Extracts the value type from a Spot — `T` is the Spot type.
Best on desktop edit & run it live Copy link
```ts
import { type SpotValue, createTask, literal, optional } from "@grlt-hub/app-compose"
const apiUrl = literal("https://api.example.com")
type ApiUrlValue = SpotValue // => "https://api.example.com"
const port = optional(literal(8080))
type PortValue = SpotValue // => 8080 | undefined
const fetchUser = createTask({
name: "fetchUser",
run: { fn: () => ({ id: 1 }) },
})
type FetchUserResult = SpotValue // => { id: string; name: string }
```
## Task\
[Section titled “Task\”](#taskt)
The type of a Task — `T` is its return type. Use it for parameters and variables that hold a Task.
Best on desktop edit & run it live Copy link
```ts
import { type Task, createTask } from "@grlt-hub/app-compose"
const alpha = createTask({
name: "alpha",
run: { fn: () => ({ value: "hello" }) },
})
const ref: Task<{ value: string }> = alpha
```
## TaskResult\
[Section titled “TaskResult\”](#taskresultt)
Extracts the return type from a Task — `T` is the Task type.
Best on desktop edit & run it live Copy link
```ts
import { type TaskResult, createTask } from "@grlt-hub/app-compose"
const alpha = createTask({
name: "alpha",
run: { fn: () => ({ value: "hello" }) },
})
type AlphaResult = TaskResult // => { value: string }
```
## TaskStatus
[Section titled “TaskStatus”](#taskstatus)
A Task’s final state: `done`, `fail`, or `skip`.
```ts
type TaskStatus = "done" | "fail" | "skip"
```