Stacks Events

Use the native event bus for process-local application and model events. Use
stacks-realtime for network broadcasting and stacks-queue for durable work.

Dispatch and completion

@stacksjs/events exports dispatch, dispatchAsync,
dispatchAndCollect, listen, once, off and emitter.

• dispatch(name, payload) invokes handlers immediately and returns void.
  Async handlers continue without blocking the caller; errors are logged.
• await dispatchAsync(name, payload) awaits matching handlers in sequence.
  Rejections are logged and appear as undefined results, so this does not prove
  that every handler succeeded.
• await dispatchAndCollect(name, payload) returns a result for each handler:
  { ok: true, value } or { ok: false, error }. Inspect failures when
  downstream work determines the response.

Payloadless events are supported by the emitter. Exact handlers receive the
payload; wildcard and glob handlers receive (eventName, payload).

emitter.on(name, handler, { priority }) sorts higher priorities first
within each handler bucket. Equal priority preserves registration order.
Exact handlers run before glob buckets, then * handlers. Snapshotting keeps
subscription changes during a dispatch from corrupting iteration.

Typed application events

StacksEvents combines built-in auth events and the augmentable
AppEvents interface. Declare an application event before dispatching it:

import { dispatch, listen } from '@stacksjs/events'

declare module '@stacksjs/events' {
  interface AppEvents {
    'invoice:settled': { id: number, total: number }
  }
}

listen('invoice:settled', invoice => {
  console.log(invoice.id, invoice.total)
})
dispatch('invoice:settled', { id: 1, total: 1200 })

Built-in auth names include user:registered, user:logged-in,
user:logged-out, user:password-reset and user:password-changed.
Read their payload types from core/events/src/index.ts rather than guessing.

Application listeners

app/Events.ts default-exports defineEvents({ event: [listenerName] }).
Names resolve against application listeners, application actions, then framework
defaults. A standalone module in app/Listeners/ may instead default-export
defineListener({ listensTo, handle }). Its handler is (payload, eventName),
including for a glob subscription, because the discovery layer adapts the bus.

registerAppListeners() loads both conventions at boot and deduplicates each
event/module pair. injectGlobalAutoImports() calls it for HTTP, CLI, scheduler
and seeding entrypoints. app/Listener.ts may call the same registration hook.
Adding a listener requires a process restart. See stacks-listeners for files.

Model lifecycle

traits.observe opts a model into lifecycle events. Before events are
saving, creating, updating and deleting; after events are
created, updated, deleted and saved. Names lowercase the model
name, for example teammember:saved.

Before handlers receive the model object, with its row under .attributes;
returning exactly false cancels the write. After handlers receive the row.
The ORM awaits the before-event result; that is separate from ordinary
fire-and-forget application dispatch. See stacks-models and stacks-orm
for which writes emit hooks, bulk operations and transaction boundaries.
Model event types derive from the models barrel in
storage/framework/types/model-events.d.ts.

Isolation and cleanup

createEmitter<EventMap>() creates an isolated emitter; the compatibility
mitt/default export is its alias. The application singleton uses a global
symbol so duplicate installed copies share the same bus in one process.
It is not cross-process messaging.

once removes its listener after the first invocation. off(name, handler)
removes by identity; off(name) clears that bucket.
emitter.removeAllListeners(name?) removes a bucket or all listeners;
listenerCount(name) counts only the exact bucket, not matching patterns.
scopedEvents(prefix) and scope(emitter, prefix) provide prefixed names
without creating another bus. Read their prefix composition in the source
before combining them with an application's named events.

Source and verification

• Public API and async behavior: storage/framework/core/events/src/index.ts.
• Discovery and typed listener adapters: core/events/src/discover.ts.
• Retained tests: native-emitter.test.ts, priority-and-collect.test.ts,
  scope.test.ts, register.test.ts, shared-emitter.test.ts under
  storage/framework/core/events/tests/.