@stacksjs/events 0.70.171 → 0.70.172

package/dist/discover.d.ts

@@ -0,0 +1,37 @@
+import type { Handler } from './index';
+/**
+ * Walk the listeners directory and register every default-exported
+ * listener that matches the `ListenerModule` shape. Returns the
+ * count of successfully registered listeners.
+ *
+ * @example
+ * ```ts
+ * // In your framework boot path:
+ * import { discoverListeners } from '@stacksjs/events'
+ *
+ * await discoverListeners()  // defaults to app/Listeners
+ * // or
+ * await discoverListeners({ dir: '/custom/path' })
+ * ```
+ */
+export declare function discoverListeners(options?: DiscoverOptions): Promise<number>;
+/**
+ * Shape of a listener module's default export. The `listensTo`
+ * field is the event name (matches the strict type of
+ * `StacksEvents` keys via `unknown` for cross-pkg flexibility);
+ * `handle` is the actual listener function.
+ */
+export declare interface ListenerModule<T = unknown> {
+  listensTo: string
+  handle: Handler<T>
+  name?: string
+}
+declare interface DiscoverOptions {
+  dir?: string
+  extensions?: string[]
+  log?: {
+    warn?: (msg: string) => void
+    error?: (msg: string) => void
+    info?: (msg: string) => void
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,153 @@
+import type { ModelEvents } from '@stacksjs/types';
+export type { ListenerModule } from './discover';
+/**
+ * Create a fresh Stacks event emitter. Most consumers want the singleton
+ * exported below — call this directly only when you need an isolated bus
+ * (tests, child workers, plugin sandboxes).
+ */
+// eslint-disable-next-line pickier/no-unused-vars
+export declare function createEmitter<Events extends Record<EventType, unknown>>(all?: EventHandlerMap<Events>): Emitter<Events>;
+/**
+ * Build a scoped wrapper around an emitter (stacksjs/stacks#1878 E-5).
+ * Every dispatch and listen call is prefixed with `${prefix}:` so
+ * different tenants / plugins / subsystems can share the same
+ * underlying bus without colliding on event names.
+ *
+ * Listeners registered through the scoped wrapper only receive events
+ * dispatched through the SAME wrapper — they don't see unprefixed
+ * events on the underlying bus. Apps that need to subscribe across
+ * scopes use the underlying emitter directly with a glob pattern.
+ *
+ * @example
+ * ```ts
+ * import { events, scope } from '@stacksjs/events'
+ *
+ * const tenantA = scope(events, 'tenant:42')
+ * tenantA.on('user:created', user => sendWelcome(user))
+ * tenantA.emit('user:created', { id: 1 })
+ * // ↑ fires the listener; on the underlying bus the event is
+ * // emitted as 'tenant:42:user:created'.
+ *
+ * // Listener on the raw bus DOES see the prefixed form:
+ * events.on('tenant:42:user:created', auditTrail)
+ * // Listener on the raw bus DOES NOT see the bare 'user:created' —
+ * // the prefix is mandatory.
+ * ```
+ */
+export declare function scope<Events extends Record<EventType, unknown>>(underlying: Emitter<Events>, prefix: string): {
+  on: (type: string, handler: Handler<unknown>, options?: { priority?: number }) => void
+  once: (type: string, handler: Handler<unknown>) => void
+  off: (type: string, handler?: Handler<unknown>) => void
+  emit: (type: string, event: unknown) => void
+  emitAsync: (type: string, event: unknown) => Promise<unknown[]>
+  emitAndCollect: (type: string, event: unknown) => Promise<Array<{ ok: true, value: unknown } | { ok: false, error: Error }>>
+  listenerCount: (type: string) => number
+};
+// Singleton-friendly scope alias (#1878 E-5). Use to create a
+// per-tenant / per-plugin wrapper that auto-prefixes event names.
+export declare function scopedEvents(prefix: string): void;
+/**
+ * Backward-compatible alias for the legacy `mitt()` export. Behaves
+ * identically to {@link createEmitter}.
+ */
+export declare const mitt: unknown;
+declare const events: Emitter<StacksEvents>;
+declare const emitter: Emitter<StacksEvents>;
+declare const useEvents: Emitter<StacksEvents>;
+declare const dispatch: Dispatch;
+declare const dispatchAsync: DispatchAsync;
+declare const dispatchAndCollect: DispatchAndCollect;
+declare const useEvent: Dispatch;
+declare const all: EventHandlerMap<StacksEvents>;
+declare const listen: Listen;
+declare const useListen: Listen;
+declare const once: Listen;
+declare const off: Off;
+export declare interface Emitter<Events extends Record<EventType, unknown>> {
+  all: EventHandlerMap<Events>
+  on: (<Key extends keyof Events>(_type: Key, _handler: Handler<Events[Key]>, _options?: { priority?: number }) => void) &
+    ((_type: '*', _handler: WildcardHandler<Events>, _options?: { priority?: number }) => void) &
+    ((_type: string, _handler: WildcardHandler<Events>, _options?: { priority?: number }) => void)
+  once: (<Key extends keyof Events>(_type: Key, _handler: Handler<Events[Key]>) => void) &
+    ((_type: '*', _handler: WildcardHandler<Events>) => void)
+  off: (<Key extends keyof Events>(_type: Key, _handler?: Handler<Events[Key]>) => void) &
+    ((_type: '*', _handler?: WildcardHandler<Events>) => void) &
+    ((_type: string, _handler?: WildcardHandler<Events>) => void)
+  emit: (<Key extends keyof Events>(_type: Key, _event: Events[Key]) => void) &
+    (<Key extends keyof Events>(_type: undefined extends Events[Key] ? Key : never) => void)
+  emitAsync: <Key extends keyof Events>(_type: Key, _event: Events[Key]) => Promise<unknown[]>
+  emitAndCollect: <Key extends keyof Events>(_type: Key, _event: Events[Key]) => Promise<Array<{ ok: true, value: unknown } | { ok: false, error: Error }>>
+  removeAllListeners: (_type?: keyof Events | '*') => void
+  listenerCount: (_type: keyof Events | '*') => number
+}
+/**
+ * Concrete payload shape for the auth-related events. Keeping these
+ * narrow (instead of `Record<string, any>`) means listeners don't need to
+ * cast or guess what fields are present — the handler signature reflects
+ * what RegisterAction / LoginAction actually dispatch.
+ */
+export declare interface UserRegisteredEvent {
+  id?: number | string
+  email: string
+  name?: string
+  to?: string
+}
+export declare interface UserLoggedInEvent {
+  id: number | string
+  email: string
+}
+export declare interface UserLoggedOutEvent {
+  id: number | string
+}
+export declare interface UserPasswordEvent {
+  id: number | string
+  email: string
+}
+/**
+ * Application-wide event types. Listeners and dispatchers below are
+ * pre-typed to this map; user-defined event names land here via
+ * `ModelEvents` (model-emitted events) + the explicit auth events listed.
+ */
+export declare interface StacksEvents extends ModelEvents, Record<EventType, unknown> {
+  'user:registered': UserRegisteredEvent
+  'user:logged-in': UserLoggedInEvent
+  'user:logged-out': UserLoggedOutEvent
+  'user:password-reset': UserPasswordEvent
+  'user:password-changed': UserPasswordEvent
+}
+export type EventType = string | symbol;
+export type Handler<T = unknown> = (_event: T) => void | Promise<void>;
+export type WildcardHandler<T = Record<string, unknown>> = (_type: keyof T, _event: T[keyof T]) => void | Promise<void>;
+export type EventHandlerList<T = unknown> = Array<Handler<T>>;
+export type WildCardEventHandlerList<T = Record<string, unknown>> = Array<WildcardHandler<T>>;
+export type EventHandlerMap<Events extends Record<EventType, unknown>> = Map<
+  keyof Events | '*',
+  EventHandlerList<Events[keyof Events]> | WildCardEventHandlerList<Events>
+>;
+declare type Dispatch = <Key extends keyof StacksEvents>(_type: Key, _event: StacksEvents[Key]) => void;
+// eslint-disable-next-line pickier/no-unused-vars
+declare type Listen = <Key extends keyof StacksEvents>(_type: Key, _handler: Handler<StacksEvents[Key]>, _options?: { priority?: number }) => void;
+// eslint-disable-next-line pickier/no-unused-vars
+declare type Off = <Key extends keyof StacksEvents>(_type: Key, handler?: Handler<StacksEvents[Key]>) => void;
+declare type DispatchAsync = <Key extends keyof StacksEvents>(_type: Key, _event: StacksEvents[Key]) => Promise<unknown[]>;
+declare type DispatchAndCollect = <Key extends keyof StacksEvents>(_type: Key, _event: StacksEvents[Key]) => Promise<Array<{ ok: true, value: unknown } | { ok: false, error: Error }>>;
+export {
+  all,
+  dispatch,
+  dispatchAndCollect,
+  dispatchAsync,
+  emitter,
+  events,
+  listen,
+  off,
+  once,
+  useEvent,
+  useEvents,
+  useListen,
+};
+// Boot-time listener auto-discovery (stacksjs/stacks#1878 E-3,
+// closing F-3 from #1874). Scans `app/Listeners/**/*.ts` for
+// default-exported `{ listensTo, handle }` modules and registers them.
+export { discoverListeners } from './discover';
+// Default export keeps `import mitt from '@stacksjs/events'` shape working.
+export default createEmitter;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/events",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.171",
+  "version": "0.70.172",
   "description": "Functional event emitting.",
   "author": "Chris Breuer",
   "contributors": [