vapor-chamber API reference - v1.16.0

• Laravel — docs/integrations/laravel.md covers the backend deliverables (route, controller, action classes, CSRF flows, Sanctum, Inertia coexistence, Filament panels, Reverb realtime, queued commands). Runnable PHP companions in examples/laravel-backend/.
• Astro — examples/exo-astro is a declarative directive set (v-scope, v-command, v-bind-text, v-show) for coordinating independent page sections, with onMissing: 'buffer' so sections can dispatch before their handlers hydrate.
• Performance & tuning — docs/performance.md: what's optimized by default, the tuning knobs (persist({ coalesce: true }), configureUid, configureSignal), variant selection, benchmark snapshot.
• API reference — generate locally with npm run docs (TypeDoc → docs/api/). The generated site is .gitignored so it stays fresh per release.

// commands.ts
import { defineSchema, createSchemaCommandBus, setCommandBus, type CommandsOf } from 'vapor-chamber';

export const schema = defineSchema({
  cartAdd: {
    description: 'Add a product to the cart',
    target:  { id: 'number', name: 'string' },
    payload: { qty: 'number' },
    result:  { count: 'number', total: 'number' },
  },
});

setCommandBus(createSchemaCommandBus(schema));   // typed dispatch + runtime validation

declare module 'vapor-chamber' {                 // typed useCommand() everywhere
  interface GlobalCommands extends CommandsOf<typeof schema> {}
}
Copy

From the same schema: bus.toTools() (Anthropic/OpenAI), vapor-chamber/mcp (agents drive your commands over MCP, whitelisted, stamped meta.origin), and node scripts/generate-laravel.mjs commands.mjs (Laravel config registry + action-class stubs with validation rules). Misspell an action or a field in a component and it's a compile error, not a runtime 404.

Vue detection is asynchronous. A signal() / useCommandState() created at module scope (before createApp runs) may be created before Vue is detected — it stays a plain { value } object and never becomes reactive. A one-shot dev-mode warning fires when this happens.

// 1. Create reactive state inside components / after app boot (usual case), or
// 2. await detection explicitly for module-scope state:
import { waitForVueDetection, signal } from 'vapor-chamber';
await waitForVueDetection();
export const count = signal(0); // now Vue-reactive
Copy

import { createVaporChamberApp } from 'vapor-chamber';
import App from './App.vue';

createVaporChamberApp(App).mount('#app');   // no vDOM runtime
Copy

<script setup vapor>
import { useCommand } from 'vapor-chamber';
const { dispatch, loading } = useCommand();
</script>
Copy

import { createApp } from 'vue';
import { getVaporInteropPlugin } from 'vapor-chamber';

const app = createApp(App);
const interop = getVaporInteropPlugin();
if (interop) app.use(interop);
app.mount('#app');
Copy

Vapor and vDOM components can now nest inside each other.

Everything works without Vapor — the signal shim auto-detects Vue's ref(). In Vue 3.6+ that is alien-signals backed.

import { isVaporAvailable } from 'vapor-chamber';
if (isVaporAvailable()) { /* Vue 3.6+ with createVaporApp available */ }
Copy

Note that Vapor ships as a physically separate dist file (vue/dist/vue.runtime-with-vapor.esm-*.js) — a bare import 'vue' never resolves to it outside a bundler's per-app alias. Never mix that build with a plain import 'vue' in one context: two separately-imported Vue dists are two disconnected reactivity instances, and the failure is silent.

One handler per action. Returns a value or throws:

bus.register('cartAdd', (cmd) => {
  cart.items.push(cmd.target);
  return cart.items;    // becomes result.value
});

// with undo support and per-command throttling
bus.register('cartAdd', addHandler, {
  undo: (cmd) => { cart.items.pop(); },
  throttle: 300,   // max once per 300ms per target
});
Copy

Enforce naming conventions at register and dispatch time:

const bus = createCommandBus({
  naming: { pattern: /^[a-z][a-zA-Z0-9]+$/, onViolation: 'throw' },  // or 'warn' / 'ignore'
});
bus.register('cartAdd', handler);    // ✓
bus.register('cart_add', handler);   // ✗ throws
Copy

Plugins wrap handlers — they can modify commands, short-circuit, observe results, or transform output:

const timingPlugin: Plugin = (cmd, next) => {
  const start = Date.now();
  const result = next();
  console.log(`${cmd.action} took ${Date.now() - start}ms`);
  return result;
};
bus.use(timingPlugin);
Copy

Execution is by priority (highest first), then registration order:

bus.use(validatorPlugin, { priority: 10 }); // first
bus.use(analyticsPlugin, { priority: 1 });
bus.use(loggerPlugin);                      // priority 0 (default), last
Copy

Before hooks run ahead of the handler; throw to cancel (the dispatch returns { ok: false }):

bus.onBefore((cmd) => {
  if (!user.isAuth && protectedActions.includes(cmd.action)) throw new Error('Unauthenticated');
});
bus.onBefore(() => { isLoading.value = true; });
bus.onAfter(()  => { isLoading.value = false; });

// on an async bus, hooks can be async
asyncBus.onBefore(async (cmd) => { await rateLimiter.check(cmd.action); });
Copy

bus.on('*', (cmd, result) => analytics.track(cmd.action));   // all commands
bus.on('cart*', (cmd, result) => console.log(cmd.action));   // prefix
bus.once('cartAdd', () => showConfetti());                   // fires once
bus.offAll('cart*');                                         // remove by pattern
bus.offAll();                                                // remove all

// Auto-unsubscribe on abort — matches DOM addEventListener semantics
bus.on('cartAdd', trackAdd, { signal: controller.signal });

// Every unsubscribe fn also carries Symbol.dispose, for `using`
{
  using off = bus.once('checkout', showConfetti);
} // unsubscribed automatically at scope exit
Copy

query() is dispatch() minus the onBefore hooks — reads shouldn't trigger mutation gates (auth checks, spinners, optimistic updates). Plugins and onAfter still fire. This is the CQRS separation: dispatch() writes, query() reads.

bus.register('getUser', (cmd) => db.users.find(cmd.target.id));
const result = bus.query('getUser', { id: 42 });
Copy

emit() fires a domain event — notifies on() listeners, needs no handler, returns no result:

bus.on('orderCreated', (cmd) => analytics.track('order', cmd.target));
bus.emit('orderCreated', { orderId: 42, total: 99.50 });
Copy

Every dispatched command is auto-stamped with meta:

bus.onAfter((cmd) => {
  cmd.meta.id;              // unique per dispatch (counter-based; UUID via configureUid)
  cmd.meta.ts;              // Date.now()
  cmd.meta.correlationId;   // trace ID for command chains
});

bus.dispatch('orderShip', order, {
  __correlationId: originalCommand.meta.id,
  __causationId:   originalCommand.meta.id,
});
Copy

Every error has a machine-readable code, severity, and emitter:

import { BusError } from 'vapor-chamber';

const result = bus.dispatch('missing', {});
if (!result.ok && result.error instanceof BusError) {
  result.error.code;      // 'VC_CORE_NO_HANDLER'
  result.error.severity;  // 'error'
  result.error.emitter;   // 'core'
  result.error.context;   // extra data (e.g. retryIn for throttle)
}
Copy

Codes include VC_CORE_NO_HANDLER, VC_CORE_THROTTLED, VC_CORE_REQUEST_TIMEOUT, VC_PLUGIN_CIRCUIT_OPEN, VC_PLUGIN_RATE_LIMITED. ERROR_CODE_REGISTRY is the full lookup table with fix suggestions.

inspectBus() returns a topology snapshot — tree-shakeable, not bundled unless imported:

const info = inspectBus(bus);
info.actions;          // ['cartAdd', 'cartRemove', ...]
info.undoActions;      // actions with registered undo handlers
info.pluginCount;      // 3
info.pluginPriorities; // [10, 5, 0]
info.sealed;           // false
info.dispatchDepth;    // 0 (increments during nested dispatch)
info.activeTimers;     // throttle timers currently running
Copy

import { createChamber, createWorkflow, createReaction } from 'vapor-chamber';

// Group handlers under a namespace
const cart = createChamber('cart', { add: handleAdd, remove: handleRemove });
cart.install(bus);   // registers cartAdd, cartRemove

// Saga: sequential steps with automatic compensation
const checkout = createWorkflow([
  { action: 'cartValidate' },
  { action: 'paymentReserve', compensate: 'paymentRelease' },
  { action: 'orderCreate',    compensate: 'orderCancel' },
]);
await checkout.run(bus, { cartId });   // compensates on failure

// Declarative cross-domain reaction
createReaction('cartAdd', 'inventoryCheck', {
  when: (cmd, result) => result.ok,
  map:  (cmd) => ({ itemId: cmd.payload.itemId }),
}).install(bus);
Copy

Genuinely aborts the stale request via AbortController rather than ignoring it on arrival. Ideal for type-ahead search, autosave, or any rapidly re-fired command where only the latest matters.

import { createAsyncCommandBus, supersede } from 'vapor-chamber';

const bus = createAsyncCommandBus();
bus.use(supersede());   // default key = commandKey(action, target)

bus.use(supersede({
  actions: ['searchQuery', 'draftSave'],                   // globs; default: all
  key: (cmd) => `${cmd.action}:${cmd.target?.id ?? ''}`,   // null/undefined to skip
}));
Copy

Because the bridges forward cmd.signal into their outbound fetch, a superseded HTTP request is cancelled at the network layer.

const result = bus.dispatchBatch([
  { action: 'cartAdd',      target: cart, payload: item },
  { action: 'totalsUpdate', target: cart },
]);
// stops at first failure by default

bus.dispatchBatch(commands, { continueOnError: true });
// result.successCount / result.failCount / result.results
Copy

transactional: true gives all-or-nothing execution — on failure, previously successful commands roll back via their registered undo handlers:

bus.register('paymentCharge', chargeHandler, { undo: refundHandler });

const result = bus.dispatchBatch([
  { action: 'inventoryReserve', target: item },
  { action: 'paymentCharge',    target: payment },
], { transactional: true });

if (!result.ok) console.log('Rollbacks:', result.rollbacks);
Copy

What happens when no handler is registered is configurable:

createCommandBus()                                // default: { ok: false, error }
createCommandBus({ onMissing: 'throw' })
createCommandBus({ onMissing: 'ignore' })         // { ok: true, value: undefined }
createCommandBus({ onMissing: (cmd) => { … } })   // custom fallback
Copy

import { createAsyncCommandBus } from 'vapor-chamber';

const bus = createAsyncCommandBus();
bus.register('userFetch', async (cmd) => (await fetch(`/api/users/${cmd.target.id}`)).json());
const result = await bus.dispatch('userFetch', { id: 123 });
Copy

Request/response with timeout — falls back to normal dispatch() if no responder is registered:

bus.respond('getAuthToken', async () => (await fetch('/api/token')).json());
const result = await bus.request('getAuthToken', { userId: 42 }, { timeout: 3000 });
Copy

Schemas for LLM system prompts, so models don't hallucinate methods or error codes:

import { describeErrorCodes, busApiSchema, getErrorEntry } from 'vapor-chamber';

const errorTable = describeErrorCodes();
const apiSchema  = busApiSchema();
getErrorEntry('VC_CORE_NO_HANDLER')?.fix;   // "Register a handler with bus.register(...)"
Copy

// logger / validator
bus.use(logger({ collapsed: true, filter: (cmd) => cmd.action.startsWith('cart') }));
bus.use(validator({
  cartAdd: (cmd) => cmd.target?.id ? null : 'Product must have an ID',   // null = valid
}));

// history — optionally bus-backed, so undo() executes registered inverse handlers
const historyPlugin = history({ maxSize: 100, bus });
bus.use(historyPlugin);
historyPlugin.undo();
historyPlugin.redo();
historyPlugin.getState();   // { past, future, canUndo, canRedo }

// debounce / throttle
bus.use(debounce(['searchQuery'], 300));
bus.use(throttle(['uiScroll'], 100));

// authGuard
bus.use(authGuard({
  isAuthenticated: () => !!user.value,
  protected: ['shopCart', 'shopWishlist'],
  onUnauthenticated: (cmd) => router.push('/login'),
}));

// optimistic — apply returns its own rollback
bus.use(optimistic({
  cartAdd: { apply: (cmd) => { cartCount.value++; return () => { cartCount.value--; }; } },
}));

// extras
bus.use(cache({ ttl: 60_000, actions: ['getUser*'] }));
bus.use(circuitBreaker({ threshold: 5, resetTimeout: 30_000 }));
bus.use(rateLimit({ max: 10, window: 1000 }));

const m = metrics();
bus.use(m);
m.summary();   // { cartAdd: { count: 42, avgMs: 1.2, errorRate: 0.02 } }
Copy

optimisticUndo — automatic rollback using registered undo handlers, on sync or async buses:

bus.register('cartAdd', async (cmd) => api.addToCart(cmd.target), {
  undo: (cmd) => api.removeFromCart(cmd.target.id),
});

bus.use(optimisticUndo(bus, ['cartAdd'], {
  predict: (cmd) => ({ ...cart, items: [...cart.items, cmd.target] }),
  onRollback: (cmd, error) => toast.error(`Rolled back: ${error.message}`),
  onRollbackError: (cmd, undoErr, origErr) => console.error('Undo failed:', undoErr),
}));
Copy

retry — async bus only:

bus.use(retry({ maxAttempts: 3, baseDelay: 200 }));            // exponential (default)
bus.use(retry({
  actions: ['api*'], maxAttempts: 5, baseDelay: 500, strategy: 'fixed',
  isRetryable: (err) => err.message !== 'Unauthorized',
}));
Copy

persist — auto-save after each successful command:

const cartPersist = persist({ key: 'vc:cart', getState: () => cartState.value });
bus.use(cartPersist);

const saved = cartPersist.load();      // rehydrate before rendering
if (saved) cartState.value = saved;

cartPersist.save();    // force
cartPersist.clear();
bus.use(persist({ key: 'vc:cart', getState, storage: sessionStorage }));   // custom backend
Copy

sync — broadcast successful commands to other tabs via BroadcastChannel:

const tabSync = sync(
  { channel: 'vapor-chamber:app', filter: (cmd) => cmd.action.startsWith('cart') },
  bus,   // pass the bus so received messages are re-dispatched locally
);
bus.use(tabSync);
tabSync.close();
Copy

import { createAsyncCommandBus } from 'vapor-chamber';
import { createHttpBridge } from 'vapor-chamber/transports';

const bus = createAsyncCommandBus({ onMissing: 'ignore' });

bus.use(createHttpBridge({
  endpoint: '/api/commands',
  csrf: true,                                 // reads XSRF-TOKEN cookie / meta tag
  csrfCookieUrl: '/sanctum/csrf-cookie',      // default; '' disables the refresh fetch
  retry: 2,                                   // 5xx / 429 / 408
  noRetry: ['paymentCharge', 'orderPlace'],   // never retry non-idempotent commands
  timeout: 8000,
  actions: ['order*'],                        // only forward these; others stay local
}));

await bus.dispatch('orderCreate', { items: cart });
// → POST /api/commands  { command: 'orderCreate', target: { items: … } }
Copy

Response shape — result.value is the contents of state:

{ "state": { "orderId": 42, "status": "pending" } }
Copy

Cancel in-flight requests when a Vapor scope is disposed:

const ctrl = new AbortController();
onScopeDispose(() => ctrl.abort());
bus.use(createHttpBridge({ endpoint: '/api/vc', scopeController: ctrl }));
Copy

Same backend contract as createHttpBridge (CSRF, retry, timeout, session-expiry all reuse the same request path), but commands dispatched within a window coalesce into a single POST and are matched back to each caller by id. Invisible to the call site — each dispatch() still resolves with its own result.

bus.use(createBatchingHttpBridge({
  endpoint: '/api/vc/batch',
  csrf: true,
  window: 'microtask',   // default: same-tick coalescing, zero added latency
  // window: 20,         // or hold the queue open N ms to catch separate ticks
}));

bus.dispatch('formSet', { field: 'email' }, { value: 'a@b.com' });
bus.dispatch('cartAdd', product, { quantity: 2 });
// → ONE HTTP round trip
Copy

// → POST /api/vc/batch
{ "commands": [{ "id": "c1", "command": "formSet", "target": { "field": "email" } }] }
// ←
{ "results": [{ "id": "c1", "ok": true, "state": {} }] }
Copy

const ws = createWsBridge({
  url: 'wss://api.example.com/commands',
  actions: ['chat*', 'presence*'],
  timeout: 10_000,     // per-message response timeout
  maxQueueSize: 100,   // queued messages while disconnected
  reconnect: true,
  maxReconnects: 10,
});
bus.use(ws);
ws.connect();

ws.isConnected();      // imperative
ws.connected.value;    // reactive signal — bindable in templates, no polling
ws.disconnect();       // intentional close, suppresses reconnect
Copy

bus.use(createSseBridge({ url: '/api/events' }));
Copy

Echo / Reverb — you pass your own instance, so the library never imports laravel-echo:

const realtime = createEchoBridge({
  echo,
  channels: [
    { name: `user.${userId}`, type: 'private',  events: ['OrderShipped'] },
    { name: 'lobby',          type: 'presence', events: ['MessagePosted'] },
  ],
});
realtime.install(bus);   // OrderShipped → bus.emit('OrderShipped', payload)
// realtime.teardown();
Copy

import { createHttpClient } from 'vapor-chamber';

const http = createHttpClient({ baseURL: '/api', csrf: true });

await http.get('/users', { params: { page: 1 } });
await http.post('/cart', { itemId: 1, qty: 2 });
await http.delete('/cart/1');

const result = await http.safe.post('/login', credentials);   // never throws
if (result.error) console.log(result.error.message);

await http.download('/export/csv', 'products.csv');

http.interceptors.request.use((config) => {
  config.headers = { ...config.headers, 'X-Custom': '1' };
  return config;
});

const adminHttp = http.create({ baseURL: '/admin/api' });   // shares interceptors
Copy

Retry (default 2 for GET, 0 for mutations) covers 5xx/429/408 and timeouts — a timeout competes for the same retry budget instead of always failing on the first attempt. TimeoutError stays distinct from a caller-triggered AbortError.

Caching (GET only) — cache: true for a flat TTL, or an object for more:

// Stale-while-revalidate: a hit past `ttl` but inside `ttl + staleTtl` is served
// instantly (stale: true) while a background fetch refreshes it.
const res = await http.get('/dashboard/stats', { cache: { ttl: 30_000, staleTtl: 5 * 60_000 } });
if (res.revalidation) { const fresh = await res.revalidation; }

// serveStaleOnError: a *transient* failure with a retained entry resolves instead
// of rejecting — { data, stale: true, servedOnError: true, error }.
// Business errors (4xx) are never masked this way.
await http.get('/dashboard/stats', { cache: { ttl: 30_000, serveStaleOnError: true } });
Copy

classifyError(error) is the one named transience rule behind serveStaleOnError: transient = timeout || no response || status >= 500. A 4xx is always a business error, never transient, no matter how tempting it is to retry a flaky-looking 429.

silent — per-request opt-out for a host-provided global error handler:

await http.post('/analytics/beacon', payload, { silent: true }).catch((e) => {
  e.silent;   // true — a global handler can check this and skip the toast
});
Copy

vapor-chamber/stream-parser — a dependency-free incremental JSON parser for progressively consuming a streamed fetch()/SSE body without buffering the whole payload (LLM completions, large exports). Subpath-only; adds nothing to the IIFE bundles.

import { createStreamParser } from 'vapor-chamber/stream-parser';

const parser = createStreamParser({
  onValue: (key, value, path) => console.log(key, value, path),
});
await parser.stream(await fetch('/api/stream'));
Copy

<script setup vapor>
const { dispatch, register, on, emit, loading, lastError, dispose } = useCommand();

register('cartAdd', (cmd) => addToCart(cmd.target));   // scoped to this component
on('cart*', (cmd, result) => console.log('Cart event:', cmd.action));
dispatch('cartAdd', product, { quantity: 1 });
emit('cartChanged', { count: 1 });
// auto-cleanup via onScopeDispose — or call dispose() manually
</script>
Copy

defineVaporCommand creates no reactive loading/lastError signals — for telemetry, scroll sampling, debounced search, autosave:

<script setup vapor>
const { dispatch } = defineVaporCommand('telemetryEvent', (cmd) => {
  sendMetric(cmd.target.name, cmd.target.params);
});
dispatch({ event: 'page_view', params: { page: '/shop' } });
</script>
Copy

// state reduced by commands
const { state: cart } = useCommandState({ items: [], total: 0 }, {
  cartAdd: (state, cmd) => ({
    items: [...state.items, cmd.target],
    total: state.total + cmd.target.price,
  }),
});

// reactive undo/redo
const { canUndo, canRedo, undo, redo } = useCommandHistory({
  filter: (cmd) => cmd.action.startsWith('editor'),
});

// namespace isolation — all calls prefixed in camelCase
const cart = useCommandGroup('cart');
cart.register('add', handler);   // registers 'cartAdd'
cart.dispatch('add', product);   // dispatches 'cartAdd'
cart.on('*', listener);          // listens to 'cart*'

// component-scoped error boundary
const { errors, latestError, clearErrors } = useCommandError({
  filter: (cmd) => cmd.action.startsWith('cart'),
});
Copy

Per-field validation, dirty tracking, and the full plugin pipeline on every form command.

const form = createFormBus({
  fields: { email: '', password: '' },
  rules: {
    email:    (v) => v.includes('@') ? null : 'Invalid email',   // sync — runs on every set()
    password: (v) => v.length >= 8   ? null : 'Too short',
    username: async (v) => await api.isUsernameTaken(v) ? 'Taken' : null,  // async — only on submit()
  },
  onSubmit: async (values) => await api.login(values),
});

form.use(logger());   // plugins attach like any bus

form.values.value; form.errors.value; form.isDirty.value; form.isValid.value; form.isSubmitting.value;

form.set('email', 'user@example.com');   // update + re-validate
form.touch('email');
await form.submit();                     // validate → onSubmit → boolean
form.reset();
Copy

Headless mode — reactive: false skips signal allocation for server-side, batch, or non-UI use. All APIs work identically.

<input :value="form.values.value.email"
       @input="form.set('email', $event.target.value)"
       @blur="form.touch('email')" />
<span v-if="form.touched.value.email && form.errors.value.email">
  {{ form.errors.value.email }}
</span>
<button :disabled="!form.isValid.value || form.isSubmitting.value" @click="form.submit()">
  Submit
</button>
Copy

<!-- core: dispatch over HTTP, CSRF auto-wired -->
<script src=".../vapor-chamber-core.iife.min.js"></script>
<script>
  const { dispatch } = VaporChamber.connect({ endpoint: '/api/vc' });
  document.getElementById('add')
    .addEventListener('click', () => dispatch('cartAdd', { id: 42 }));
</script>
Copy

<!-- elements: register a custom-element widget in one call -->
<script src=".../vapor-chamber-elements.iife.min.js"></script>
<script>
  VaporChamber.defineWidget('vc-cart', {
    props: { sku: String },
    setup(props) { return () => h('span', `SKU ${props.sku}`); },
  });
</script>
<vc-cart sku="ABC-123"></vc-cart>
Copy

Variant contents are not under semver before v2.0. While Vue 3.6 is in RC, the lib reserves the right to move APIs between IIFE variants. ESM consumers get the full surface and are unaffected.

const snap = bus.snapshot();          // immutable RecordedDispatch[]
bus.travelTo(1);                      // commands 0..1 inclusive
bus.travelToAction('cartAdd');        // up to last occurrence
bus.travelTo(999);                    // out-of-range indices clamp
Copy

Requires @vue/devtools-api; silently no-ops if not installed.

import { setupDevtools } from 'vapor-chamber/devtools';

const app = createApp(App);
setupDevtools(getCommandBus(), app);
app.mount('#app');
Copy

CommandBusOptions

Router — see docs/router.md for the full surface: createRouter, useRouter, useRoute, useQueryParam, useRouteData, useRouteError, useMenu, useBreadcrumbs, usePagination, onBeforeLeave, RouterOutlet.