@kellanjs/eventcraft 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lanny Kenneth Lung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,390 @@
+# Eventcraft
+
+A tiny TypeScript event helper for components that need to emit events and subscribe to exactly the events they care about.
+
+Eventcraft gives you a typed event tree. Emit from leaf events, then subscribe to one event, a whole branch, the root, a named group, or a one-off selection.
+
+```ts
+import { event, eventcraft, group } from "@kellanjs/eventcraft";
+
+const events = eventcraft()
+  .events({
+    notes: {
+      created: event<{ id: string; title: string }>(),
+      updated: event<{ id: string; title: string }>(),
+      deleted: event<{ id: string }>(),
+    },
+    saved: event(),
+  })
+  .groups((events) => ({
+    searchInvalidating: group(events.notes),
+  }))
+  .build();
+
+events.searchInvalidating.$subscribe((event) => {
+  console.log("Refresh search because:", event.name);
+});
+
+await events.notes.updated({
+  id: "note-1",
+  title: "Updated title",
+});
+```
+
+## Install
+
+```sh
+npm install @kellanjs/eventcraft
+```
+
+## Why Use It?
+
+- **Typed payloads**: `event<T>()` controls what can be emitted.
+- **Tree-shaped subscriptions**: subscribe to `events.notes` instead of string wildcards like `"notes.*"`.
+- **Small runtime API**: events are callable functions with `$emit`, `$subscribe`, `$once`, and metadata.
+- **Reusable groups**: name important event sets once and use them across the app.
+- **React-friendly**: optional `useEvent` hook handles component cleanup.
+- **No required React dependency**: the core package is framework-agnostic.
+
+## Define Events
+
+Create a registry with `eventcraft().events(...).build()`.
+
+```ts
+import { event, eventcraft } from "@kellanjs/eventcraft";
+
+const events = eventcraft()
+  .events({
+    notes: {
+      created: event<{ id: string; title: string }>(),
+      updated: event<{ id: string; title: string }>(),
+      deleted: event<{ id: string }>(),
+    },
+    saved: event(),
+  })
+  .build();
+```
+
+Use `event<T>()` for payloadful events. Use `event()` for payloadless events.
+
+## Emit Events
+
+Events are callable.
+
+```ts
+await events.notes.created({
+  id: "note-1",
+  title: "First note",
+});
+
+await events.saved();
+```
+
+You can also use `$emit`.
+
+```ts
+await events.notes.deleted.$emit({ id: "note-1" });
+await events.saved.$emit();
+```
+
+## Subscribe To One Event
+
+Leaf event listeners receive `(payload, event)`.
+
+```ts
+const unsubscribe = events.notes.updated.$subscribe((payload, event) => {
+  console.log(payload.title);
+  console.log(event.name); // "notes.updated"
+});
+
+unsubscribe();
+```
+
+Every emitted event includes:
+
+```ts
+type EventEnvelope = {
+  id: string;
+  name: string;
+  payload: unknown;
+  timestamp: number;
+};
+```
+
+By default, ids come from `crypto.randomUUID()` and timestamps come from `Date.now()`. You can override both for tests or custom tracing.
+
+```ts
+const events = eventcraft({
+  createId: () => "event-1",
+  now: () => 123,
+})
+  .events({
+    saved: event(),
+  })
+  .build();
+```
+
+## Subscribe To Event Sources
+
+Branches, the root registry, named groups, and selections are all event sources. They receive the full event object.
+
+### Branch
+
+```ts
+events.notes.$subscribe((event) => {
+  console.log(event.name); // notes.created | notes.updated | notes.deleted
+});
+```
+
+### Root
+
+```ts
+events.$subscribe((event) => {
+  console.log("Something happened:", event.name);
+});
+```
+
+### Named Group
+
+```ts
+import { group } from "@kellanjs/eventcraft";
+
+const events = eventcraft()
+  .events({
+    notes: {
+      created: event<{ id: string }>(),
+      updated: event<{ id: string }>(),
+      deleted: event<{ id: string }>(),
+    },
+    tags: {
+      updated: event<{ id: string }>(),
+    },
+  })
+  .groups((events) => ({
+    searchInvalidating: group(events.notes, events.tags.updated),
+  }))
+  .build();
+
+events.searchInvalidating.$subscribe((event) => {
+  console.log(event.name);
+});
+```
+
+### One-Off Selection
+
+```ts
+events
+  .$select([events.notes, events.tags.updated])
+  .$subscribe((event) => {
+    console.log(event.name);
+  });
+```
+
+You can also create a selection without the root registry.
+
+```ts
+import { select } from "@kellanjs/eventcraft";
+
+select([events.notes.updated, events.tags.updated]).$subscribe((event) => {
+  console.log(event.name);
+});
+```
+
+Overlapping sources are deduplicated by event node identity. If you select both a branch and one of its child events, the listener runs once for that child event. Separate registries can still contain distinct events with the same `$name`.
+
+## Cleanup
+
+`$subscribe` returns an unsubscribe function.
+
+```ts
+const unsubscribe = events.notes.updated.$subscribe(listener);
+
+unsubscribe();
+```
+
+You can bind subscriptions to an `AbortSignal`.
+
+```ts
+const controller = new AbortController();
+
+events.notes.updated.$subscribe(listener, {
+  signal: controller.signal,
+});
+
+controller.abort();
+```
+
+Use `$once` when you only want the next matching event.
+
+```ts
+events.saved.$once((payload, event) => {
+  console.log(event.id);
+});
+
+events.notes.$once((event) => {
+  console.log(event.name);
+});
+```
+
+## React
+
+The React hook is available from the React subpath.
+
+```ts
+import { useEvent } from "@kellanjs/eventcraft/react";
+
+type AppEvents = typeof events;
+
+function NoteListener({ events }: { events: AppEvents }) {
+  useEvent(events.notes.updated, (payload) => {
+    console.log("Note updated:", payload.id);
+  });
+
+  return null;
+}
+```
+
+`useEvent` accepts the same event sources as the core API.
+
+```ts
+useEvent(events.notes, (event) => {
+  console.log(event.name);
+});
+
+useEvent(events.searchInvalidating, (event) => {
+  console.log(event.name);
+});
+
+useEvent(events.$select([events.notes, events.tags.updated]), (event) => {
+  console.log(event.name);
+});
+
+useEvent(events, (event) => {
+  console.log(event.name);
+});
+
+useEvent([events.notes.created, events.tags.updated], (event) => {
+  console.log(event.name);
+});
+```
+
+The hook unsubscribes on unmount. If the source changes, it cleans up the old subscription before subscribing to the new source. The listener can change every render without resubscribing, and inline arrays are compared by member identity.
+
+## Async Iteration
+
+Every event source is an async iterable.
+
+```ts
+for await (const event of events.notes) {
+  console.log(event.name);
+}
+```
+
+Use `break`, `return`, or `throw` to stop the iterator and clean up its internal subscription.
+
+## Error Handling
+
+Listeners can be synchronous or asynchronous. Eventcraft runs every listener for an emit and waits for all of them to settle. One failing listener does not stop the others.
+
+```ts
+events.notes.created.$subscribe(async (payload) => {
+  await saveToDatabase(payload);
+});
+```
+
+After listeners settle:
+
+- If one handler failed, the emit promise rejects with that error.
+- If multiple handlers failed, the emit promise rejects with an `AggregateError`.
+
+Use `onEmit` and `onListenerError` for observability.
+
+```ts
+const events = eventcraft({
+  onEmit(event) {
+    console.log("Emitted:", event.name);
+  },
+  onListenerError(error, event) {
+    console.error("Listener failed:", event.name, error);
+  },
+})
+  .events({
+    saved: event(),
+  })
+  .build();
+```
+
+If `onEmit` throws or rejects, Eventcraft still delivers the event to listeners, then rejects the emit promise after listener delivery settles. `onListenerError` runs for listener failures and preserves the normal emit rejection behavior.
+
+## Naming Rules
+
+Eventcraft uses `$` properties internally, such as `$emit`, `$subscribe`, `$once`, `$name`, `$members`, and `$select`.
+
+Event and group keys cannot start with `$` or include `.`. Dots are reserved for nested event names like `notes.updated`.
+
+```ts
+eventcraft()
+  .events({
+    $saved: event(),
+  })
+  .build();
+```
+
+That throws at `build()` time.
+
+Groups also cannot shadow existing events or branches.
+
+```ts
+eventcraft()
+  .events({
+    notes: {
+      updated: event<{ id: string }>(),
+    },
+  })
+  .groups((events) => ({
+    notes: group(events.notes.updated),
+  }))
+  .build();
+```
+
+That throws because `notes` is already a branch.
+
+## Public API
+
+Core:
+
+```ts
+import { event, eventcraft, group, select } from "@kellanjs/eventcraft";
+```
+
+React:
+
+```ts
+import { useEvent } from "@kellanjs/eventcraft/react";
+```
+
+Types:
+
+```ts
+import type {
+  AnyEventSource,
+  BranchNode,
+  EventDef,
+  EventEnvelope,
+  EventListener,
+  EventNode,
+  EventcraftOptions,
+  EventRegistry,
+  GroupNode,
+  RootNode,
+  SubscribeOptions,
+} from "@kellanjs/eventcraft";
+```
+
+## Thanks
+
+If you made it this far, thanks for checking out the library, and I hope you find it useful in your projects!
+
+## License
+
+Keycraft is open source under the terms of the [MIT license](https://github.com/kellanjs/eventcraft/blob/main/LICENSE).

package/dist/core/eventcraft.d.ts

@@ -0,0 +1,108 @@
+type EventEnvelope<Name extends string, Payload> = {
+    id: string;
+    name: Name;
+    payload: Payload;
+    timestamp: number;
+};
+type EventListener<Name extends string, Payload> = (payload: Payload, event: EventEnvelope<Name, Payload>) => void | Promise<void>;
+type GroupListener<TEvent> = (event: TEvent) => void | Promise<void>;
+type SubscribeOptions = {
+    signal?: AbortSignal;
+};
+type EventcraftOptions = {
+    createId?: () => string;
+    now?: () => number;
+    onEmit?: (event: AnyEvent) => void | Promise<void>;
+    onListenerError?: (error: unknown, event: AnyEvent) => void | Promise<void>;
+};
+type EventArgs<Payload> = [Payload] extends [void] ? [] : [payload: Payload];
+type EventNode<Name extends string, Payload> = ((...args: EventArgs<Payload>) => Promise<void>) & {
+    $emit: (...args: EventArgs<Payload>) => Promise<void>;
+    $name: Name;
+    $once: (listener: EventListener<Name, Payload>, options?: SubscribeOptions) => () => void;
+    $subscribe: (listener: EventListener<Name, Payload>, options?: SubscribeOptions) => () => void;
+    [Symbol.asyncIterator]: () => AsyncIterableIterator<EventEnvelope<Name, Payload>>;
+};
+type AnyEventNode = ((...args: never[]) => Promise<void>) & {
+    $emit: (...args: never[]) => Promise<void>;
+    $name: string;
+    $once: (listener: never, options?: SubscribeOptions) => () => void;
+    $subscribe: (listener: never, options?: SubscribeOptions) => () => void;
+    [Symbol.asyncIterator]: () => AsyncIterableIterator<AnyEvent>;
+};
+type GroupNode<Name extends string, TEvent> = {
+    $members: readonly string[];
+    $name: Name;
+    $once: (listener: GroupListener<TEvent>, options?: SubscribeOptions) => () => void;
+    $subscribe: (listener: GroupListener<TEvent>, options?: SubscribeOptions) => () => void;
+    [Symbol.asyncIterator]: () => AsyncIterableIterator<TEvent>;
+};
+type SubscribableNode<Name extends string, TEvent> = GroupNode<Name, TEvent>;
+type BranchNode<Name extends string, TEvent> = SubscribableNode<Name, TEvent>;
+type RootNode<TEvent> = SubscribableNode<"", TEvent> & {
+    $select: <const TSources extends readonly AnyEventSource[]>(sources: TSources) => SubscribableNode<"$selection", GroupEventOf<TSources>>;
+};
+type AnySubscribableNode = {
+    $members: readonly string[];
+    $name: string;
+    $once: (listener: GroupListener<unknown>, options?: SubscribeOptions) => () => void;
+    $subscribe: (listener: GroupListener<unknown>, options?: SubscribeOptions) => () => void;
+};
+type AnyEvent = {
+    id: string;
+    name: string;
+    payload: unknown;
+    timestamp: number;
+};
+declare const EVENT_MARKER: unique symbol;
+type EventDef<Payload = void> = {
+    readonly [EVENT_MARKER]: true;
+    readonly __payload?: Payload;
+};
+type EventDefs = {
+    [key: string]: EventDef<unknown> | EventDefs;
+};
+type GroupDefs = {
+    [key: string]: readonly AnyEventSource[] | GroupDefs;
+};
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+};
+type JoinPath<Prefix extends string, Key extends string> = Prefix extends "" ? Key : `${Prefix}.${Key}`;
+type EventTreeEventFromDefs<TDefs, Prefix extends string = ""> = {
+    [K in keyof TDefs]: TDefs[K] extends EventDef<infer Payload> ? EventEnvelope<JoinPath<Prefix, Extract<K, string>>, Payload> : TDefs[K] extends EventDefs ? EventTreeEventFromDefs<TDefs[K], JoinPath<Prefix, Extract<K, string>>> : never;
+}[keyof TDefs];
+type EventTreeFromDefs<TDefs, Prefix extends string = ""> = Simplify<{
+    [K in keyof TDefs]: TDefs[K] extends EventDef<infer Payload> ? EventNode<JoinPath<Prefix, Extract<K, string>>, Payload> : TDefs[K] extends EventDefs ? BranchNode<JoinPath<Prefix, Extract<K, string>>, EventTreeEventFromDefs<TDefs[K], JoinPath<Prefix, Extract<K, string>>>> & EventTreeFromDefs<TDefs[K], JoinPath<Prefix, Extract<K, string>>> : never;
+}>;
+type EventNameOf<T> = T extends {
+    $name: infer Name extends string;
+} ? Name : never;
+type EventPayloadOf<T> = T extends {
+    $emit: (...args: infer Args) => Promise<void>;
+} ? Args extends [] ? void : Args[0] : never;
+type AnyEventSource = AnyEventNode | AnySubscribableNode;
+type EventSourceEventOf<T> = T extends AnyEventNode ? EventEnvelope<EventNameOf<T>, EventPayloadOf<T>> : T extends SubscribableNode<string, infer TEvent> ? TEvent : never;
+type GroupEventOf<TMembers extends readonly AnyEventSource[]> = {
+    [Index in keyof TMembers]: EventSourceEventOf<TMembers[Index]>;
+}[number];
+type GroupTreeFromDefs<TDefs, Prefix extends string = ""> = Simplify<{
+    [K in keyof TDefs]: TDefs[K] extends readonly AnyEventSource[] ? GroupNode<JoinPath<Prefix, Extract<K, string>>, GroupEventOf<TDefs[K]>> : TDefs[K] extends GroupDefs ? GroupTreeFromDefs<TDefs[K], JoinPath<Prefix, Extract<K, string>>> : never;
+}>;
+type Registry<TDefs extends EventDefs, TGroups extends GroupDefs> = Simplify<EventTreeFromDefs<TDefs> & GroupTreeFromDefs<TGroups> & RootNode<EventTreeEventFromDefs<TDefs>>>;
+declare class Builder<TDefs extends EventDefs, TGroups extends GroupDefs = Record<never, never>> {
+    private readonly options;
+    private readonly defs;
+    private readonly resolveGroups?;
+    constructor(defs: TDefs, options: EventcraftOptions, resolveGroups?: (events: EventTreeFromDefs<TDefs>) => TGroups);
+    groups<TNextGroups extends GroupDefs>(resolve: (events: EventTreeFromDefs<TDefs>) => TNextGroups): Builder<TDefs, TNextGroups>;
+    build(): Registry<TDefs, TGroups>;
+}
+export declare function event(): EventDef<void>;
+export declare function event<Payload>(): EventDef<Payload>;
+export declare function group<const TMembers extends readonly AnyEventSource[]>(...members: TMembers): TMembers;
+export declare function select<const TSources extends readonly AnyEventSource[]>(sources: TSources): SubscribableNode<"$selection", GroupEventOf<TSources>>;
+export declare function eventcraft(options?: EventcraftOptions): {
+    events<TDefs extends EventDefs>(defs: TDefs): Builder<TDefs, Record<never, never>>;
+};
+export type { AnyEventNode, AnyEventSource, BranchNode, GroupNode, RootNode, EventDef, EventEnvelope, EventListener, EventNode, EventcraftOptions, Registry as EventRegistry, SubscribeOptions, };

package/dist/core/eventcraft.js

@@ -0,0 +1,406 @@
+const EVENT_MARKER = Symbol("eventcraft.event");
+const INTERNAL_EVENTS = Symbol("eventcraft.events");
+function assignGroupAtPath(root, path, value) {
+    const parts = path.split(".");
+    let cursor = root;
+    for (let index = 0; index < parts.length - 1; index += 1) {
+        const part = parts[index];
+        const next = cursor[part];
+        if (next === undefined) {
+            cursor[part] = Object.create(null);
+        }
+        else if (typeof next !== "object" || next === null) {
+            throw new Error(`Eventcraft group "${path}" conflicts with an existing event at "${parts.slice(0, index + 1).join(".")}"`);
+        }
+        cursor = cursor[part];
+    }
+    const leaf = parts.at(-1);
+    const existing = cursor[leaf];
+    if (existing !== undefined) {
+        throw new Error(`Eventcraft group "${path}" conflicts with an existing ${typeof existing === "function" ? "event" : "branch"} at the same path`);
+    }
+    cursor[leaf] = value;
+}
+function isEventDef(value) {
+    return Boolean(value &&
+        typeof value === "object" &&
+        EVENT_MARKER in value);
+}
+function isGroupMembers(value) {
+    return Array.isArray(value);
+}
+function isEventNode(value) {
+    if (typeof value !== "function") {
+        return false;
+    }
+    const node = value;
+    return (typeof node.$emit === "function" &&
+        typeof node.$name === "string" &&
+        typeof node.$subscribe === "function");
+}
+function isSubscribableNode(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const node = value;
+    return (Array.isArray(node.$members) &&
+        typeof node.$name === "string" &&
+        typeof node.$subscribe === "function");
+}
+function assertEventSource(value, context) {
+    if (isEventNode(value) || isSubscribableNode(value)) {
+        return;
+    }
+    throw new TypeError(`Eventcraft ${context} must be an Eventcraft event, branch, group, selection, or registry.`);
+}
+function assertEventSourceList(value, context) {
+    if (!Array.isArray(value)) {
+        throw new TypeError(`Eventcraft ${context} must be an array.`);
+    }
+    value.forEach((source, index) => {
+        assertEventSource(source, `${context} source at index ${index}`);
+    });
+}
+function assertPublicKey(key, path) {
+    if (key.startsWith("$")) {
+        throw new Error(`Eventcraft keys cannot start with "$": ${path}`);
+    }
+    if (key.includes(".")) {
+        throw new Error(`Eventcraft keys cannot include ".": ${path}`);
+    }
+}
+function noop() { }
+function createOnceSubscription(subscribe, listener, options) {
+    let active = true;
+    let unsubscribe = noop;
+    const cleanup = () => {
+        if (!active) {
+            return;
+        }
+        active = false;
+        unsubscribe();
+    };
+    const onceListener = (...args) => {
+        if (!active) {
+            return;
+        }
+        cleanup();
+        return listener(...args);
+    };
+    unsubscribe = subscribe(onceListener, options);
+    return cleanup;
+}
+function bindAbortSignal(unsubscribe, signal) {
+    let active = true;
+    const cleanup = () => {
+        if (!active) {
+            return;
+        }
+        active = false;
+        signal?.removeEventListener("abort", cleanup);
+        unsubscribe();
+    };
+    signal?.addEventListener("abort", cleanup, { once: true });
+    return cleanup;
+}
+function createAsyncIterator(subscribe) {
+    const events = [];
+    const resolvers = [];
+    let active = true;
+    const unsubscribe = subscribe((event) => {
+        const resolve = resolvers.shift();
+        if (resolve) {
+            resolve({ done: false, value: event });
+            return;
+        }
+        events.push(event);
+    });
+    return {
+        [Symbol.asyncIterator]() {
+            return this;
+        },
+        next() {
+            const event = events.shift();
+            if (event !== undefined) {
+                return Promise.resolve({ done: false, value: event });
+            }
+            if (!active) {
+                return Promise.resolve({
+                    done: true,
+                    value: undefined,
+                });
+            }
+            return new Promise((resolve) => {
+                resolvers.push(resolve);
+            });
+        },
+        return() {
+            if (active) {
+                active = false;
+                unsubscribe();
+            }
+            for (const resolve of resolvers.splice(0)) {
+                resolve({
+                    done: true,
+                    value: undefined,
+                });
+            }
+            return Promise.resolve({
+                done: true,
+                value: undefined,
+            });
+        },
+        throw(error) {
+            if (active) {
+                active = false;
+                unsubscribe();
+            }
+            for (const resolve of resolvers.splice(0)) {
+                resolve({
+                    done: true,
+                    value: undefined,
+                });
+            }
+            return Promise.reject(error);
+        },
+    };
+}
+function createEventNode(name, options) {
+    const listeners = new Set();
+    const emit = async (...args) => {
+        const payload = args[0];
+        const event = {
+            id: options.createId?.() ?? crypto.randomUUID(),
+            name,
+            payload,
+            timestamp: options.now?.() ?? Date.now(),
+        };
+        let onEmitPromise;
+        if (options.onEmit) {
+            try {
+                onEmitPromise = Promise.resolve(options.onEmit(event));
+            }
+            catch (error) {
+                onEmitPromise = Promise.reject(error);
+            }
+        }
+        const results = await Promise.allSettled([...listeners].map(async (listener) => listener(payload, event)));
+        const listenerErrors = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+        const onEmitHookResults = onEmitPromise
+            ? await Promise.allSettled([onEmitPromise])
+            : [];
+        const listenerErrorHookResults = await Promise.allSettled(listenerErrors.map(async (error) => options.onListenerError?.(error, event)));
+        const errors = [
+            ...listenerErrors,
+            ...onEmitHookResults.flatMap((result) => result.status === "rejected" ? [result.reason] : []),
+            ...listenerErrorHookResults.flatMap((result) => result.status === "rejected" ? [result.reason] : []),
+        ];
+        if (errors.length === 1) {
+            throw errors[0];
+        }
+        if (errors.length > 1) {
+            throw new AggregateError(errors, `${errors.length} event handlers failed for "${name}"`);
+        }
+    };
+    return Object.assign(emit, {
+        $emit: emit,
+        $name: name,
+        $once(listener, subscribeOptions) {
+            return createOnceSubscription(this.$subscribe.bind(this), listener, subscribeOptions);
+        },
+        $subscribe(listener, subscribeOptions) {
+            if (subscribeOptions?.signal?.aborted) {
+                return noop;
+            }
+            listeners.add(listener);
+            const unsubscribe = () => {
+                listeners.delete(listener);
+            };
+            return bindAbortSignal(unsubscribe, subscribeOptions?.signal);
+        },
+        [Symbol.asyncIterator]() {
+            return createAsyncIterator((listener) => this.$subscribe((_payload, event) => listener(event)));
+        },
+    });
+}
+function collectEventNodes(value) {
+    if (isEventNode(value)) {
+        return [value];
+    }
+    if (!value || typeof value !== "object") {
+        return [];
+    }
+    const internal = value[INTERNAL_EVENTS];
+    if (Array.isArray(internal)) {
+        return internal;
+    }
+    return Object.entries(value).flatMap(([key, child]) => key.startsWith("$") ? [] : collectEventNodes(child));
+}
+function uniqueEventNodes(members) {
+    return [...new Set(members)];
+}
+function subscribeToSource(source, listener, options) {
+    const eventListener = listener;
+    if (isEventNode(source)) {
+        const eventNode = source;
+        return eventNode.$subscribe((_payload, event) => eventListener(event), options);
+    }
+    const subscribableNode = source;
+    return subscribableNode.$subscribe(eventListener, options);
+}
+function createBranchNode(name, members) {
+    const uniqueMembers = uniqueEventNodes(members);
+    const node = {
+        $members: uniqueMembers.map((member) => member.$name),
+        $name: name,
+        $once(listener, options) {
+            return createOnceSubscription(this.$subscribe.bind(this), listener, options);
+        },
+        $subscribe(listener, options) {
+            if (options?.signal?.aborted) {
+                return noop;
+            }
+            const unsubscribes = uniqueMembers.map((member) => {
+                const eventNode = member;
+                return eventNode.$subscribe((_payload, event) => listener(event));
+            });
+            const unsubscribe = () => {
+                for (const unsubscribe of unsubscribes) {
+                    unsubscribe();
+                }
+            };
+            return bindAbortSignal(unsubscribe, options?.signal);
+        },
+        [Symbol.asyncIterator]() {
+            return createAsyncIterator((listener) => this.$subscribe(listener));
+        },
+    };
+    Object.defineProperty(node, INTERNAL_EVENTS, {
+        value: uniqueMembers,
+        enumerable: false,
+    });
+    return node;
+}
+function createSelectionNode(members) {
+    assertEventSourceList(members, "selection");
+    const expandedMembers = [];
+    for (const member of members) {
+        if (isEventNode(member)) {
+            expandedMembers.push(member);
+            continue;
+        }
+        expandedMembers.push(...collectEventNodes(member));
+    }
+    const uniqueMembers = uniqueEventNodes(expandedMembers);
+    const node = {
+        $members: uniqueMembers.map((member) => member.$name),
+        $name: "$selection",
+        $once(listener, options) {
+            return createOnceSubscription(this.$subscribe.bind(this), listener, options);
+        },
+        $subscribe(listener, options) {
+            if (options?.signal?.aborted) {
+                return noop;
+            }
+            const unsubscribes = uniqueMembers.map((member) => subscribeToSource(member, listener, options));
+            const unsubscribe = () => {
+                for (const unsubscribe of unsubscribes) {
+                    unsubscribe();
+                }
+            };
+            return bindAbortSignal(unsubscribe, options?.signal);
+        },
+        [Symbol.asyncIterator]() {
+            return createAsyncIterator((listener) => this.$subscribe(listener));
+        },
+    };
+    Object.defineProperty(node, INTERNAL_EVENTS, {
+        value: uniqueMembers,
+        enumerable: false,
+    });
+    return node;
+}
+function buildEvents(defs, options, prefix = "") {
+    const result = Object.create(null);
+    for (const [key, value] of Object.entries(defs)) {
+        const name = prefix ? `${prefix}.${key}` : key;
+        assertPublicKey(key, name);
+        if (isEventDef(value)) {
+            result[key] = createEventNode(name, options);
+            continue;
+        }
+        const subtree = buildEvents(value, options, name);
+        const members = collectEventNodes(subtree);
+        Object.assign(subtree, createBranchNode(name, members));
+        result[key] = subtree;
+    }
+    return result;
+}
+class Builder {
+    options;
+    defs;
+    resolveGroups;
+    constructor(defs, options, resolveGroups) {
+        this.options = options;
+        this.defs = defs;
+        this.resolveGroups = resolveGroups;
+    }
+    groups(resolve) {
+        return new Builder(this.defs, this.options, resolve);
+    }
+    build() {
+        const events = buildEvents(this.defs, this.options);
+        const registry = events;
+        const groups = this.resolveGroups?.(events) ?? {};
+        const attachGroups = (defs, prefix = "") => {
+            for (const [key, value] of Object.entries(defs)) {
+                const name = prefix ? `${prefix}.${key}` : key;
+                assertPublicKey(key, name);
+                if (isGroupMembers(value)) {
+                    const members = value;
+                    const selection = createSelectionNode(members);
+                    const node = {
+                        ...selection,
+                        $name: name,
+                    };
+                    Object.defineProperty(node, INTERNAL_EVENTS, {
+                        value: selection[INTERNAL_EVENTS],
+                        enumerable: false,
+                    });
+                    assignGroupAtPath(registry, name, node);
+                    continue;
+                }
+                attachGroups(value, name);
+            }
+        };
+        attachGroups(groups);
+        const rootMembers = collectEventNodes(registry);
+        const rootNode = createBranchNode("", rootMembers);
+        Object.assign(registry, rootNode, {
+            $select: createSelectionNode,
+        });
+        return registry;
+    }
+}
+export function event() {
+    return {
+        [EVENT_MARKER]: true,
+    };
+}
+export function group(...members) {
+    members.forEach((member, index) => {
+        assertEventSource(member, `group() source at index ${index}`);
+    });
+    return members;
+}
+export function select(sources) {
+    assertEventSourceList(sources, "select()");
+    return createSelectionNode(sources);
+}
+export function eventcraft(options = {}) {
+    return {
+        events(defs) {
+            return new Builder(defs, options);
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { group, select, event, eventcraft } from "./core/eventcraft.js";
+export type { AnyEventSource, BranchNode, GroupNode, RootNode, EventDef, EventEnvelope, EventListener, EventNode, EventcraftOptions, EventRegistry, SubscribeOptions, } from "./core/eventcraft.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { group, select, event, eventcraft } from "./core/eventcraft.js";

package/dist/react/index.d.ts

@@ -0,0 +1 @@
+export { useEvent } from "./use-event.js";

package/dist/react/index.js

@@ -0,0 +1 @@
+export { useEvent } from "./use-event.js";

package/dist/react/use-event.d.ts

@@ -0,0 +1,23 @@
+import type { AnyEventNode, AnyEventSource, EventListener, GroupNode } from "../core/eventcraft.js";
+type EventNameOf<T> = T extends {
+    $name: infer Name extends string;
+} ? Name : never;
+type EventPayloadOf<T> = T extends {
+    $emit: (...args: infer Args) => Promise<void>;
+} ? Args extends [] ? void : Args[0] : never;
+type EventOf<T extends AnyEventNode> = {
+    id: string;
+    name: EventNameOf<T>;
+    payload: EventPayloadOf<T>;
+    timestamp: number;
+};
+type SubscribableEventOf<TSubscribable extends GroupNode<string, unknown>> = TSubscribable extends GroupNode<string, infer TEvent> ? TEvent : never;
+type EventSourceEventOf<TSource> = TSource extends AnyEventNode ? EventOf<TSource> : TSource extends GroupNode<string, infer TEvent> ? TEvent : never;
+type EventArrayEventOf<TEvents extends readonly AnyEventSource[]> = {
+    [Index in keyof TEvents]: EventSourceEventOf<TEvents[Index]>;
+}[number];
+type AnySubscribableNode = GroupNode<string, unknown>;
+export declare function useEvent<TEvent extends AnyEventNode>(event: TEvent, listener: EventListener<EventNameOf<TEvent>, EventPayloadOf<TEvent>>): void;
+export declare function useEvent<const TSources extends readonly AnyEventSource[]>(sources: TSources, listener: (event: EventArrayEventOf<TSources>) => void | Promise<void>): void;
+export declare function useEvent<TSubscribable extends AnySubscribableNode>(subscribable: TSubscribable, listener: (event: SubscribableEventOf<TSubscribable>) => void | Promise<void>): void;
+export {};

package/dist/react/use-event.js

@@ -0,0 +1,98 @@
+"use client";
+import * as React from "react";
+function isEventArray(source) {
+    return Array.isArray(source);
+}
+function isEventNode(source) {
+    if (typeof source !== "function") {
+        return false;
+    }
+    const node = source;
+    return (typeof node.$emit === "function" &&
+        typeof node.$name === "string" &&
+        typeof node.$subscribe === "function");
+}
+function isSubscribableNode(source) {
+    if (!source || typeof source !== "object" || Array.isArray(source)) {
+        return false;
+    }
+    const node = source;
+    return (Array.isArray(node.$members) &&
+        typeof node.$name === "string" &&
+        typeof node.$subscribe === "function");
+}
+function assertEventSource(source, context) {
+    if (isEventNode(source) || isSubscribableNode(source)) {
+        return;
+    }
+    throw new TypeError(`Eventcraft ${context} must be an Eventcraft event, branch, group, selection, or registry.`);
+}
+function assertEventSourceInput(source) {
+    if (!Array.isArray(source)) {
+        assertEventSource(source, "useEvent() source");
+        return;
+    }
+    source.forEach((member, index) => {
+        assertEventSource(member, `useEvent() source at index ${index}`);
+    });
+}
+function subscribeToSource(source, listener) {
+    if (isEventNode(source)) {
+        const event = source;
+        return event.$subscribe((_payload, event) => listener(event));
+    }
+    const subscribable = source;
+    return subscribable.$subscribe(listener);
+}
+function useStableListener(listener) {
+    const listenerRef = React.useRef(listener);
+    listenerRef.current = listener;
+    return listenerRef;
+}
+function areSourcesEqual(left, right) {
+    if (Object.is(left, right)) {
+        return true;
+    }
+    if (!Array.isArray(left) || !Array.isArray(right)) {
+        return false;
+    }
+    return (left.length === right.length &&
+        left.every((member, index) => Object.is(member, right[index])));
+}
+function useStableSource(source) {
+    const sourceRef = React.useRef(source);
+    if (!areSourcesEqual(sourceRef.current, source)) {
+        sourceRef.current = source;
+    }
+    return sourceRef.current;
+}
+export function useEvent(source, listener) {
+    assertEventSourceInput(source);
+    const listenerRef = useStableListener(listener);
+    const stableSource = useStableSource(source);
+    React.useEffect(() => {
+        if (isEventArray(stableSource)) {
+            const unsubscribes = stableSource.map((member) => subscribeToSource(member, (event) => {
+                const current = listenerRef.current;
+                return current(event);
+            }));
+            return () => {
+                for (const unsubscribe of unsubscribes) {
+                    unsubscribe();
+                }
+            };
+        }
+        if (isEventNode(stableSource)) {
+            const event = stableSource;
+            return event.$subscribe((payload, event) => {
+                const current = listenerRef.current;
+                return current(payload, event);
+            });
+        }
+        const subscribable = stableSource;
+        return subscribable.$subscribe((event) => {
+            const current = listenerRef.current;
+            return current(event);
+        });
+    }, [listenerRef, stableSource]);
+}

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@kellanjs/eventcraft",
+  "version": "0.1.0",
+  "description": "A tiny, type-safe event library with inferred payloads, selective subscriptions, and optional React hooks.",
+  "keywords": [
+    "events",
+    "subscribers",
+    "pub-sub",
+    "event-emitter",
+    "typescript",
+    "type-safety",
+    "type-inference",
+    "react",
+    "hooks",
+    "dx"
+  ],
+  "author": "kellanjs",
+  "license": "MIT",
+  "homepage": "https://github.com/kellanjs/eventcraft",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kellanjs/eventcraft.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kellanjs/eventcraft/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "dev": "vitest tests/eventcraft.test.ts tests/use-event.test.ts",
+    "prebuild": "npm run clean",
+    "build": "tsc",
+    "lint": "eslint .",
+    "type": "tsc --noEmit",
+    "type:test": "tsc --noEmit -p tsconfig.test.json",
+    "prepack": "npm run build",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "pretest:coverage": "npm run build",
+    "test:coverage": "vitest run --coverage",
+    "format": "prettier --write .",
+    "check-format": "prettier --check .",
+    "check-exports": "attw --pack . --ignore-rules cjs-resolves-to-esm no-resolution",
+    "ci": "npm run lint && npm run type && npm run build && npm run type:test && npm run check-format && npm run check-exports && npm run test"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@eslint/js": "^10.0.1",
+    "@testing-library/react": "^16.3.2",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/node": "^25.6.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/coverage-v8": "^4.0.8",
+    "eslint": "^10.2.1",
+    "globals": "^16.5.0",
+    "jsdom": "^29.1.1",
+    "prettier": "^3.8.3",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.46.2",
+    "vitest": "^4.1.5"
+  }
+}