@yoltra/core 0.1.0

package/dist/types/eventBus/LooseEventBus.d.ts

@@ -0,0 +1,219 @@
+/**
+ * @module @yoltra/core
+ */
+/**
+ * Flexible, synchronous pub/sub bus that supports **exact** and **pattern** event subscriptions.
+ *
+ * @typeParam C - Channel name type (defaults to `string`).
+ * @typeParam T - Event type name type (defaults to `string`). Types are treated as **dot-separated paths** (e.g. `"a.b.c"`).
+ * @typeParam P - Payload type for all events (defaults to `any`).
+ *
+ * @remarks
+ * - **Exact handlers** subscribe to a specific `(channel, type)` pair. Type keys are **normalized** by stripping a single leading dot (`".foo"` → `"foo"`).
+ * - **Pattern handlers** subscribe using wildcards over dot-separated segments:
+ *   - `*`   matches **one** segment.
+ *   - `**`  matches **zero or more** segments (greedy).
+ * - On {@link LooseEventBus.emit | `emit`}, exact handlers fire first, then any matching pattern handlers.
+ * - Handlers are **de-duplicated**: if the same function is both exact and pattern-registered, it is called **once**.
+ * - Handler invocation is **synchronous**. Exceptions are caught and logged; remaining handlers still run.
+ *
+ * @example
+ * ```ts
+ * type C = 'ui' | 'data';
+ * type T = string;
+ * type P = unknown;
+ *
+ * const bus = new LooseEventBus<C, T, P>();
+ *
+ * // Exact
+ * const offA = bus.on('ui', 'panel.open', () => console.log('panel opened'));
+ *
+ * // Patterns
+ * const offB = bus.on('ui', 'panel.*', () => console.log('any single sub-event under panel'));
+ * const offC = bus.on('ui', 'panel.**', () => console.log('any depth under panel'));
+ *
+ * bus.emit('ui', 'panel.open', null);
+ * // => exact fires, then 'panel.*', then 'panel.**'
+ *
+ * offA(); offB(); offC(); // unsubscribe
+ * ```
+ *
+ * @public
+ */
+export declare class LooseEventBus<C extends string = string, T extends string = string, P = any> {
+    /**
+     * Exact handlers: `channel → type → [handlers]`.
+     * @internal
+     */
+    private handlers;
+    /**
+     * Pattern handlers with `*` and `**`: `channel → pattern(string) → [handlers]`.
+     * @internal
+     */
+    private patternHandlers;
+    /**
+     * Subscribes a handler to either an **exact** type or a **pattern**.
+     *
+     * @param channel - Channel to subscribe on.
+     * @param type - Exact event type (e.g. `"a.b"`) or pattern (contains `*`/`**`).
+     * @param handler - Function invoked with the emitted payload.
+     * @returns An **unsubscribe** function that removes this handler.
+     *
+     * @remarks
+     * - Exact subscriptions are stored under a **normalized** key (leading `.` removed).
+     * - Pattern subscriptions are stored **as provided**; matching normalizes the subject.
+     *
+     * @example Exact subscription
+     * ```ts
+     * const off = bus.on('data', 'items.loaded', ({ count }) => {
+     *   console.log('Loaded', count);
+     * });
+     * // Later
+     * off();
+     * ```
+     *
+     * @example Pattern subscription
+     * ```ts
+     * // Match any single sub-event: 'panel.open', 'panel.close', etc.
+     * const offStar = bus.on('ui', 'panel.*', () => {});
+     *
+     * // Match any depth: 'panel.open', 'panel.items.add', 'panel', etc.
+     * const offGlob = bus.on('ui', 'panel.**', () => {});
+     * ```
+     *
+     * @public
+     */
+    on(channel: C, type: T, handler: (payload: P) => void): () => void;
+    /**
+     * Unsubscribes an **exact** handler. The `type` key is normalized internally,
+     * so callers can pass `"foo"` or `".foo"` interchangeably.
+     *
+     * @param channel - Channel name.
+     * @param type - Exact event type key to remove (normalization applied).
+     * @param handler - The same handler reference previously passed to {@link LooseEventBus.on | `on`}.
+     *
+     * @example
+     * ```ts
+     * const h = () => {};
+     * bus.on('ui', 'panel.open', h);
+     * // Remove it (with or without leading dot)
+     * bus.off('ui', '.panel.open', h);
+     * ```
+     *
+     * @public
+     */
+    off(channel: C, type: T, handler: (payload: P) => void): void;
+    /**
+     * Internal exact unsubscription using an already **normalized** type key.
+     *
+     * @param channel - Channel name.
+     * @param normalizedType - Event type key with leading dot removed.
+     * @param handler - Handler to remove.
+     * @internal
+     */
+    private offExactNormalized;
+    /**
+     * Internal removal for a **pattern** subscription. No-ops if missing.
+     *
+     * @param channel - Channel name.
+     * @param pattern - Pattern string as originally subscribed.
+     * @param handler - Handler to remove.
+     * @internal
+     */
+    private offPattern;
+    /**
+     * Emits an event to all exact subscribers first, then to **matching pattern** subscribers.
+     * Duplicate handler references are called **once** (de-duped).
+     *
+     * @param channel - Channel to emit on.
+     * @param type - Event type (subject). A leading dot is ignored for matching.
+     * @param payload - Payload delivered to handlers.
+     *
+     * @example
+     * ```ts
+     * // Suppose:
+     * //  - on('ui', 'panel.open', h)
+     * //  - on('ui', 'panel.*', h)       // same handler ref!
+     * //  - on('ui', 'panel.**', other)
+     * bus.emit('ui', 'panel.open', { id: 1 });
+     * // => 'h' runs once (de-duped), then 'other'
+     * ```
+     *
+     * @public
+     */
+    emit(channel: C, type: T, payload: P): void;
+    /**
+     * Determines if a string is a **pattern** (contains `*`).
+     * @param s - Event type or pattern string.
+     * @returns `true` if it contains at least one `*`, else `false`.
+     * @internal
+     */
+    private isPattern;
+    /**
+     * Normalizes event type keys for exact matching by stripping a **single** leading dot.
+     *
+     * @param s - Event type key.
+     * @returns Normalized key without a leading dot.
+     * @example
+     * ```ts
+     * normalizeTypeKey('.a.b') // 'a.b'
+     * normalizeTypeKey('a.b')  // 'a.b'
+     * ```
+     * @internal
+     */
+    private normalizeTypeKey;
+    /**
+     * Splits a path into dot-separated segments after normalization and removes empties.
+     * @param p - Event type or pattern string.
+     * @internal
+     */
+    private splitPath;
+    /**
+     * Pattern matcher over dot-separated segments.
+     *
+     * Rules:
+     * - **literal**: exact match.
+     * - `*`   : matches exactly **one** segment.
+     * - `**`  : matches **zero or more** remaining segments (including empty).
+     *
+     * @param pattern - Pattern (may include `*`/`**`).
+     * @param path - Subject event type key to test.
+     * @returns `true` if the pattern matches the path; otherwise `false`.
+     *
+     * @example
+     * ```ts
+     * matchPattern('a.*', 'a.b')        // true
+     * matchPattern('a.*', 'a.b.c')      // false
+     * matchPattern('a.**', 'a')         // true
+     * matchPattern('a.**', 'a.b.c')     // true
+     * matchPattern('**.end', 'x.y.end') // true
+     * ```
+     *
+     * @internal
+     */
+    private matchPattern;
+    /**
+     * Removes **all** listeners (exact and pattern). Useful for tests/HMR teardown.
+     *
+     * @example
+     * ```ts
+     * afterEach(() => bus.clear());
+     * ```
+     *
+     * @public
+     */
+    clear(): void;
+    /**
+     * Returns a snapshot of all registered subscriptions for DevTools introspection.
+     *
+     * @returns An array of `{ channel, type, count }` entries for each distinct
+     *          (channel, type/pattern) pair with at least one handler.
+     *
+     * @internal
+     */
+    __introspect(): Array<{
+        channel: string;
+        type: string;
+        count: number;
+    }>;
+}

package/dist/types/eventBus/index.d.ts

@@ -0,0 +1,2 @@
+export * from './EventBus';
+export * from './LooseEventBus';

package/dist/types/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @module @yoltra/core
+ *
+ * yoltra Core - Channel/Event-driven state management
+ *
+ * @packageDocumentation
+ */
+export { EventBus } from './eventBus/EventBus';
+export { LooseEventBus } from './eventBus/LooseEventBus';
+export { Reducer } from './reducer/Reducer';
+export { Store, createStore, typedEvents } from './store/Store';
+export { detectChangedProps } from './utils/detectChangedProps';
+export { freezeState } from './utils/immutability';
+export { eventKeys } from './types';
+export type { EventMapBase, EventKey, Event, EventUnion, Change, Emit, Unsubscribe, StoreSpec, StoreInstance, ReducerSpec, ReducerFunction, EffectSpec, EffectFunction, MiddlewareFunction, MiddlewareSpec, MiddlewareInput, DeepReadonly, DeepRO, Primitive, Path, PathValue, WithGlob, Dotted, EventPhase, EventSubscriptionHandler, NarrowedEventHandler, When, EventFromWhen, EventConsumerType, EventConsumerMeta, } from './types';

package/dist/types/reducer/Reducer.d.ts

@@ -0,0 +1,81 @@
+import { EventMapBase, EventUnion, ReducerFunction } from '../types';
+/**
+ * Thin wrapper around a pure reducer function (stateful event consumer):
+ * given a state `S` and an event (from {@link EventUnion | `EventUnion<EM>`}),
+ * returns the next state `S`.
+ *
+ * @typeParam S  - State shape handled by this reducer.
+ * @typeParam EM - Event map describing the valid event keys and payload types.
+ *
+ * @remarks
+ * - The reducer function is expected to be **pure** and **side-effect free**.
+ * - Use this class when you want to pass a reducer around as a value, or to
+ *   unify the reducer interface across the core API.
+ *
+ * @example Basic counter
+ * ```ts
+ * type State = { count: number };
+ * type EM = { math: { add: number; set: number } };
+ *
+ * const rf: ReducerFunction<State, EM> = (s, evt) => {
+ *   if (evt.channel === 'math' && evt.type === 'add') {
+ *     return { count: s.count + evt.payload };
+ *   }
+ *   if (evt.channel === 'math' && evt.type === 'set') {
+ *     return { count: evt.payload };
+ *   }
+ *   return s;
+ * };
+ *
+ * const r = new Reducer<State, EM>(rf);
+ *
+ * const s0 = { count: 0 };
+ * const s1 = r.reduce(s0, {
+ *   channel: 'math',
+ *   type: 'add',
+ *   payload: 2,
+ *   id: crypto.randomUUID()
+ * } as EventUnion<EM>);
+ * // s1.count === 2
+ * ```
+ *
+ * @public
+ */
+export declare class Reducer<S, EM extends EventMapBase = EventMapBase> {
+    /**
+     * The underlying pure reducer function.
+     * @internal
+     */
+    private readonly _reduce;
+    /**
+     * Creates a new {@link Reducer} from a pure reducer function.
+     *
+     * @param reduce - A function `(state, event) => nextState` that implements your update logic.
+     *
+     * @example
+     * ```ts
+     * const reducer = new Reducer<MyState, MyEM>((state, event) => {
+     *   // implement your transitions here
+     *   return state;
+     * });
+     * ```
+     *
+     * @public
+     */
+    constructor(reduce: ReducerFunction<S, EM>);
+    /**
+     * Applies the reducer to produce the next state.
+     *
+     * @param state  - Current state.
+     * @param event - An event drawn from {@link EventUnion | `EventUnion<EM>`}.
+     * @returns The next state produced by the underlying reducer function.
+     *
+     * @example
+     * ```ts
+   * const next = reducer.reduce(curr, someEvent as EventUnion<MyEM>);
+     * ```
+     *
+     * @public
+     */
+    reduce(state: S, event: EventUnion<EM>): S;
+}