@yoltra/core 0.1.0

package/dist/types/store/Store.d.ts

@@ -0,0 +1,834 @@
+import { Event, EventMapBase, EventKey, Change, DeepReadonly, EffectSpec, MiddlewareFunction, ReducersMapAny, ReducerSpec, StateFromReducers, StoreInstance, StoreSpec, Unsubscribe, EMFromReducersStrict, Emit, EventPhase, NarrowedEventHandler, When } from '../types';
+export declare class Store<EM extends EventMapBase, R extends string, S extends Record<R, any>> implements StoreInstance<R, S, EM> {
+    /**
+     * Store name (used by DevTools & diagnostics).
+     *
+     * @public
+     */
+    name: string;
+    /**
+     * Registered middleware pipeline (run **before** reducers).
+     * Stores either raw functions (legacy) or MiddlewareSpec objects.
+     * Return `false` from the middleware function to stop propagation.
+     *
+     * @internal
+     */
+    private readonly middleware;
+    /**
+     * Installed slice reducers keyed by slice name.
+     *
+     * @internal
+     */
+    private readonly reducers;
+    /**
+     * Current immutable snapshot of the store state.
+     * This reference changes whenever any slice changes (shallow immutability).
+     *
+     * @internal
+     */
+    private state;
+    /**
+     * Bus for reducer wiring (emit by `(channel, type)`).
+     *
+     * @internal
+     */
+    private readonly reducerBus;
+    /**
+     * Bus for **granular** connector events (emit by **dotted path** inside a slice).
+     *
+     * @internal
+     */
+    private readonly connectorBus;
+    /**
+     * Coarse-grained listeners (called once per committed event, only if state changed).
+     *
+     * @internal
+     */
+    private readonly listeners;
+    /**
+     * Registered effect handlers keyed by `"channel::type"` for O(1) lookup.
+     * Used for effects with explicit `keys` or legacy `events` targeting.
+     *
+     * @internal
+     */
+    private readonly effects;
+    /**
+     * Pattern-based effects that need runtime matching.
+     * Used for effects with `when: { any }`, `{ channel }`, or `{ channels }`.
+     * Stores tuples of [effect function, when matcher].
+     *
+     * @internal
+     */
+    private readonly patternEffects;
+    /**
+     * Committed event subscribers keyed by `"channel::type"` for O(1) lookup.
+     * Notified after reducers, before effects, for events that passed middleware.
+     *
+     * @internal
+     */
+    private readonly committedEventSubscribers;
+    /**
+     * Uncommitted event subscribers keyed by `"channel::type"` for O(1) lookup.
+     * Notified when middleware rejects an event.
+     *
+     * @internal
+     */
+    private readonly uncommittedEventSubscribers;
+    /**
+     * All-events subscribers keyed by `"channel::type"` for O(1) lookup.
+     * Notified for both committed and uncommitted events with phase parameter.
+     *
+     * @internal
+     */
+    private readonly allEventSubscribers;
+    /**
+     * Track reducerBus unsubs per slice for HMR/register/unregister.
+     *
+     * @internal
+     */
+    private readonly sliceUnsubs;
+    /**
+     * Pattern-based reducers that need runtime matching.
+     * Used for reducers with `when: { any }`, `{ channel }`, or `{ channels }`.
+     * Maps slice name to the `when` matcher.
+     *
+     * @internal
+     */
+    private readonly patternReducers;
+    /**
+     * Whether `__replayEvents()` is allowed.
+     * Set from `spec.devtools.allowReplay`.
+     *
+     * @internal
+     */
+    private readonly replayEnabled;
+    /**
+     * FIFO event queue for serialized emission.
+     *
+     * @internal
+     */
+    private readonly eventQueue;
+    /**
+     * Re-entrancy guard while draining the queue.
+     *
+     * @internal
+     */
+    private isProcessingQueue;
+    /**
+     * Tracks processed events by fingerprint with timestamps for TTL-based deduplication.
+     *
+     * **Deduplication Behavior:**
+     * - Events are fingerprinted using `channel::type::JSON(payload)`
+     * - If an identical fingerprint is seen within the dedup window, it's skipped
+     * - The window is 50ms in development, 100ms in production
+     *
+     * **Limitations:**
+     * - Non-serializable payloads (functions, symbols, circular refs) get unique
+     *   fingerprints and won't be deduplicated
+     * - Legitimate rapid-fire identical events may be incorrectly deduplicated
+     * - The cache is bounded to 1000 entries with lazy pruning
+     *
+     * @internal
+     */
+    private readonly processedEvents;
+    /**
+     * Configuration for event deduplication.
+     * @internal
+     */
+    private readonly dedupConfig;
+    /**
+     * Timer for periodic cleanup of processed events.
+     *
+     * @internal
+     */
+    private eventCleanupTimer;
+    /**
+     * Creates a store from a {@link StoreSpec}.
+     *
+     * @param spec - Store configuration (name, reducers, middleware, optional effects).
+     *
+     * @public
+     */
+    constructor(spec: StoreSpec<R, S, EM>);
+    /**
+     * Cleanup resources (timers, etc.) when disposing the store.
+     * Call this if you're dynamically creating/destroying stores.
+     *
+     * @example
+     * ```ts
+     * const store = createStore({ ... });
+     * // later
+     * store.dispose();
+     * ```
+     *
+     * @public
+     */
+    dispose(): void;
+    /**
+     * Generates a fingerprint for an event for deduplication purposes.
+     * Falls back gracefully for non-serializable payloads.
+     *
+     * @param channel - Event channel.
+     * @param type - Event type.
+     * @param payload - Event payload.
+     * @returns A string fingerprint for the event.
+     *
+     * @internal
+     */
+    private fingerprint;
+    /**
+     * Checks if an event should be deduplicated.
+     * Returns true if this is a duplicate that should be skipped.
+     *
+     * @param fp - Event fingerprint.
+     * @returns `true` if duplicate (should skip), `false` otherwise.
+     *
+     * @internal
+     */
+    private shouldDedupe;
+    /**
+     * Removes expired entries from the processed events cache.
+     *
+     * @param now - Current timestamp.
+     *
+     * @internal
+     */
+    private pruneProcessedEvents;
+    /**
+     * Checks if an event matches a `When` matcher.
+     *
+     * @param when - The When matcher (or undefined for "all events").
+     * @param event - The event to check.
+     * @returns `true` if the event matches, `false` otherwise.
+     *
+     * @remarks
+     * - `undefined` or missing `when` matches ALL events.
+     * - `{ any: true }` matches ALL events.
+     * - `{ keys: [...] }` matches if event's `[channel, type]` is in the array.
+     * - `{ channel: 'x' }` matches if event's channel equals 'x'.
+     * - `{ channels: ['x', 'y'] }` matches if event's channel is in the array.
+     *
+     * @internal
+     */
+    private matchesWhen;
+    /**
+     * Extracts the middleware function from a MiddlewareInput.
+     * Handles both raw functions (legacy) and MiddlewareSpec objects.
+     *
+     * @param input - MiddlewareInput (function or spec).
+     * @returns The middleware function.
+     *
+     * @internal
+     */
+    private getMiddlewareFunction;
+    /**
+     * Gets the `when` matcher from a MiddlewareInput.
+     *
+     * @param input - MiddlewareInput (function or spec).
+     * @returns The `when` matcher, or `undefined` for raw functions (match all).
+     *
+     * @internal
+     */
+    private getMiddlewareWhen;
+    /**
+     * Invokes all registered **effects** for a given event.
+     * Handles both key-based effects (O(1) lookup) and pattern-based effects (runtime matching).
+     * Errors are caught and logged.
+     *
+     * @param event - The event that was reduced.
+     * @internal
+     */
+    private notifyEffects;
+    /**
+     * Notifies event subscribers for a specific phase.
+     *
+     * Calls both phase-specific subscribers and 'all' subscribers.
+     * Errors are caught and logged, allowing other subscribers to continue.
+     *
+     * @param event - The event to notify about.
+     * @param phase - The phase ('committed' or 'uncommitted').
+     * @internal
+     */
+    private notifyEventSubscribers;
+    /**
+     * Applies a reduced event to a slice and emits **precise** connector events.
+     *
+     * For each changed **leaf path** (via {@link detectChangedProps}), emits that leaf and
+     * all of its **ancestors** once (e.g., `"data"`, `"data.123"`, `"data.123.title"`).
+     *
+     * **State Immutability**: When a slice changes, a new state object is created via
+     * shallow spread: `{ ...this.state, [sliceName]: newSlice }`. This ensures that
+     * `this.state` reference changes, enabling efficient change detection via `===`.
+     *
+     * @param rName - Slice name being updated.
+     * @param event - Reduced event with typed payload.
+     * @returns `true` if the slice actually changed, `false` otherwise.
+     *
+     * @internal
+     */
+    private forwardEvent;
+    /**
+     * Returns a structured introspection snapshot for DevTools UIs.
+     *
+     * @remarks
+     * Reads the internal middleware, effects, reducers, and subscriber
+     * registries and returns a plain-object summary matching the
+     * `STORE_SUBSCRIPTIONS` protocol message shape.
+     *
+     * @public
+     */
+    __devtoolsIntrospect(): {
+        reducers: {
+            name: string;
+            when: When<EM> | undefined;
+        }[];
+        effects: {
+            channel: string;
+            type: string;
+            name?: string;
+            description?: string;
+        }[];
+        middleware: {
+            name?: string;
+            description?: string;
+            when?: unknown;
+        }[];
+        atomic: {
+            reducer: string;
+            property: string;
+        }[];
+        event: {
+            channel: string;
+            type: string;
+            phase: string;
+        }[];
+        coarse: number;
+    };
+    /**
+     * Applies an externally provided **whole-state** (e.g., DevTools time travel) and emits
+     * fine-grained path changes for each slice.
+     *
+     * **State Immutability**: If any slices change, a new state object is created via
+     * shallow spread. This ensures consistent immutability with {@link forwardEvent}.
+     *
+     * @param nextPlain - Plain JS object to become the new state.
+     *
+     * @internal
+     */
+    private __applyExternalState;
+    /**
+     * Replays a sequence of events from a snapshot through reducers and event
+     * subscribers ONLY. Skips dedup, middleware, and effects.
+     *
+     * This method is gated by the `devtools.allowReplay` runtime config.
+     * If replay is not enabled, this method throws.
+     *
+     * @param snapshot - The state snapshot to restore before replaying.
+     * @param events - Array of events to replay (in order).
+     *
+     * @internal
+     */
+    __replayEvents(snapshot: any, events: Array<{
+        channel: string;
+        type: string;
+        payload: any;
+        id: string;
+    }>): void;
+    /**
+     * Emits a typed event `(channel, type, payload)`.
+     * Events are queued and processed **sequentially** (FIFO).
+     *
+     * **Pipeline per event:**
+     * 1. **Deduplication check** - Skip if event ID already processed (React Strict Mode safety)
+     * 2. **Middleware** - Pre-reducer hooks; may cancel by returning `false`
+     * 3. **Reducers** - Synchronous state updates via internal event bus
+     * 4. **Effects** - Async side-effects keyed by `(channel, type)` for O(1) lookup
+     * 5. **Coarse subscribers** - External store subscribers (only if state changed)
+     *
+     * **Change Detection**: Uses reference equality (`===`) on `this.state` to determine
+     * if any slice changed. Works because {@link forwardEvent} creates a new state reference
+     * via shallow spread when any slice changes.
+     *
+     * @typeParam C - Channel key in `EM`.
+     * @typeParam T - Type key within channel `C`.
+     * @param channel - Channel name.
+     * @param type - Event type name.
+     * @param payload - Payload typed as `EM[C][T]`.
+     * @returns A promise that resolves when the event has finished processing.
+     *
+     * @example Basic usage
+     * ```ts
+     * await store.emit('ui', 'increment', 1);
+     * ```
+     *
+     * @example With middleware cancellation
+     * ```ts
+     * store.registerMiddleware((state, event) => {
+     *   if (event.type === 'dangerous') return false; // cancel
+     *   return true; // allow
+     * });
+     *
+     * await store.emit('ui', 'dangerous', null); // cancelled, no state change
+     * ```
+     *
+     * @public
+     */
+    emit<C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, payload: EM[C][T]): Promise<void>;
+    /**
+     * Connects a **fine-grained** listener to a dotted path under a slice.
+     *
+     * @param spec - `{ reducer, property }` where `property` is a dotted path (e.g., `"items.0.title"`).
+     *        Supports wildcards: `*` (one segment) and `**` (zero or more segments).
+     * @param h - Handler receiving a {@link Change} with `{ oldValue, newValue, path }`.
+     * @returns Unsubscribe function.
+     *
+     * @example Exact path
+     * ```ts
+     * const off = store.connect(
+     *   { reducer: 'todos', property: 'items.0.title' },
+     *   (chg) => console.log('title changed:', chg.newValue)
+     * );
+     * off();
+     * ```
+     *
+     * @example Wildcard pattern
+     * ```ts
+     * // Listen to any item title change
+     * const off = store.connect(
+     *   { reducer: 'todos', property: 'items.*.title' },
+     *   (chg) => console.log('some title changed')
+     * );
+     * ```
+     *
+     * @public
+     */
+    connect(spec: {
+        reducer: R;
+        property: string;
+    }, h: (chg: Change) => void): () => void;
+    /**
+     * Subscribe to events by channel and type.
+     *
+     * Event subscriptions are intended for the View layer (e.g., React components)
+     * to react to events without affecting the event flow. They are fire-and-forget
+     * and cannot cancel event propagation.
+     *
+     * **Phases:**
+     * - `'committed'` (default): Events that passed middleware and reached reducers.
+     *   Notified after reducers, before effects.
+     * - `'uncommitted'`: Events rejected by middleware. Notified immediately after rejection.
+     * - `'all'`: Both committed and uncommitted events. Handler receives the phase parameter
+     *   to distinguish between the two.
+     *
+     * @typeParam C - Channel key within `EM`.
+     * @typeParam T - Event type key within channel `C`.
+     * @param channel - Channel to subscribe to.
+     * @param type - Event type to subscribe to.
+     * @param handler - Handler function `(event, getState, emit, phase)`.
+     * @param phase - Event phase to subscribe to (default: `'committed'`).
+     * @returns Unsubscribe function.
+     *
+     * @example Committed events (default)
+     * ```ts
+     * const off = store.onEvent('ui', 'save', (event, getState, emit, phase) => {
+     *   console.log('Save committed:', event.payload);
+     * });
+     * off();
+     * ```
+     *
+     * @example Uncommitted (rejected) events
+     * ```ts
+     * store.onEvent('ui', 'delete', (event, getState, emit, phase) => {
+     *   console.log('Delete was rejected by middleware');
+     * }, 'uncommitted');
+     * ```
+     *
+     * @example All events
+     * ```ts
+     * store.onEvent('ui', 'action', (event, getState, emit, phase) => {
+     *   console.log('Action:', phase); // 'committed' or 'uncommitted'
+     * }, 'all');
+     * ```
+     *
+     * @public
+     */
+    onEvent<C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, handler: NarrowedEventHandler<DeepReadonly<S>, EM, C, T>, phase?: EventPhase): Unsubscribe;
+    /**
+     * Subscribes to **coarse-grained** commits (called once per successful event, only if state changed).
+     *
+     * **Use Case**: React's `useSyncExternalStore` or similar external store integrations.
+     *
+     * @param fn - Listener invoked after reducers/effects have run and state has changed.
+     * @returns Unsubscribe function.
+     *
+     * @example
+     * ```ts
+     * const off = store.subscribe(() => console.log('state committed'));
+     * // Later:
+     * off();
+     * ```
+     *
+     * @public
+     */
+    subscribe(fn: () => void): () => void;
+    /**
+     * Returns the current immutable state snapshot.
+     *
+     * @returns Deep-readonly state object.
+     *
+     * @example
+     * ```ts
+     * const state = store.getState();
+     * console.log(state.counter.value);
+     * ```
+     *
+     * @public
+     */
+    getState(): DeepReadonly<S>;
+    /**
+     * Registers a middleware (runs **before** reducers).
+     *
+     * @param mw - Middleware `(state, event, emit) => boolean|Promise<boolean>`.
+     *        Return `false` to cancel event propagation.
+     * @returns Unsubscribe function that removes this middleware.
+     *
+     * @example Logging middleware
+     * ```ts
+     * const off = store.registerMiddleware(async (state, event) => {
+     *   console.log('Event:', event.channel, event.type, event.payload);
+     *   return true; // allow
+     * });
+     * off();
+     * ```
+     *
+     * @example Cancellation middleware
+     * ```ts
+     * store.registerMiddleware((state, event) => {
+     *   if (event.type === 'forbidden') return false; // cancel
+     *   return true;
+     * });
+     * ```
+     *
+     * @public
+     */
+    registerMiddleware(mw: MiddlewareFunction<DeepReadonly<S>, EM>): Unsubscribe;
+    /**
+     * Dynamically **adds** a named slice reducer at runtime.
+     *
+     * @param name - New slice name (must not already exist).
+     * @param spec - Reducer spec (state, events, reducer).
+     * @returns Disposer function that **removes** the slice (and its state).
+     *
+     * @example
+     * ```ts
+     * const dispose = store.registerReducer('filters', {
+     *   state: { q: '' },
+     *   events: [['ui', 'setQuery']],
+     *   reducer(s, evt) {
+     *     return evt.type === 'setQuery' ? { q: evt.payload } : s;
+     *   }
+     * });
+     * // Later:
+     * dispose();
+     * ```
+     *
+     * @public
+     */
+    registerReducer(name: string, spec: ReducerSpec<any, EM>): () => void;
+    /**
+     * Registers an **effect** (stateless async event consumer) that runs after reducers.
+     *
+     * Effects are **keyed** by `(channel, type)` for O(1) lookup (no scanning all effects).
+     *
+     * @param spec - Effect specification with `events` (EventKeys) and `effect` (handler).
+     * @returns Unsubscribe function.
+     *
+     * @example Logging effect
+     * ```ts
+     * const off = store.registerEffect({
+     *   events: [['ui', 'increment']],
+     *   effect: async (evt, getState, emit) => {
+     *     console.log('increment', evt.payload, getState().counter.value);
+     *   }
+     * });
+     * off();
+     * ```
+     *
+     * @example Multi-event effect
+     * ```ts
+     * store.registerEffect({
+     *   events: [['ui', 'increment'], ['ui', 'decrement']],
+     *   effect: async (evt, getState, emit) => {
+     *     // Runs for both increment and decrement
+     *     await saveToServer(getState());
+     *   }
+     * });
+     * ```
+     *
+     * @public
+     */
+    registerEffect(spec: EffectSpec<DeepReadonly<S>, EM>): () => void;
+    /**
+     * Convenience helper to register an **effect** filtered by a single `(channel, type)` pair.
+     *
+     * @typeParam C - Channel key within `EM`.
+     * @typeParam T - Event type key within channel `C`.
+     * @param channel - Channel to filter.
+     * @param type - Event type to filter.
+     * @param handler - Effect handler `(payload, getState, emit, event)`.
+     * @returns Unsubscribe/teardown function.
+     *
+     * @example
+     * ```ts
+     * const off = store.onEffect('ui', 'increment', async (n, get, emit) => {
+     *   if (n > 10) await emit('ui', 'increment', -10);
+     * });
+     * // later
+     * off();
+     * ```
+     *
+     * @public
+     */
+    onEffect<C extends keyof EM & string, T extends keyof EM[C] & string>(channel: C, type: T, handler: (payload: EM[C][T], getState: () => DeepReadonly<S>, emit: Emit<EM>, event: Event<EM, C, T>) => void | Promise<void>): () => void;
+    /**
+     * Replaces the **entire** middleware pipeline (HMR-friendly).
+     *
+     * @param next - New middleware array.
+     *
+     * @example Hot module replacement
+     * ```ts
+     * if (import.meta.hot) {
+     *   import.meta.hot.accept('./middleware', (newModule) => {
+     *     store.replaceMiddleware(newModule.middleware);
+     *   });
+     * }
+     * ```
+     *
+     * @public
+     */
+    replaceMiddleware(next: MiddlewareFunction<DeepReadonly<S>, EM>[]): void;
+    /**
+     * Replaces all registered **effects** (HMR-friendly).
+     *
+     * @param next - New effects array (as EffectSpecs).
+     *
+     * @example Hot module replacement
+     * ```ts
+     * if (import.meta.hot) {
+     *   import.meta.hot.accept('./effects', (newModule) => {
+     *     store.replaceEffects(newModule.effects);
+     *   });
+     * }
+     * ```
+     *
+     * @public
+     */
+    replaceEffects(next: Array<EffectSpec<DeepReadonly<S>, EM>>): void;
+    /**
+     * Replaces the entire **reducer set** (HMR-friendly).
+     *
+     * @param next - Map of slice specs keyed by slice name.
+     * @param opts - `{ preserveState?: boolean }` (default `true`).
+     *
+     * @example Hot module replacement
+     * ```ts
+     * if (import.meta.hot) {
+     *   import.meta.hot.accept('./reducers', (newModule) => {
+     *     store.replaceReducers(newModule.reducers, { preserveState: true });
+     *   });
+     * }
+     * ```
+     *
+     * @public
+     */
+    replaceReducers(next: Record<R, ReducerSpec<S[R], EM>>, opts?: {
+        preserveState?: boolean;
+    }): void;
+    /**
+     * Convenience API to replace **any subset** of store parts (HMR patterns).
+     *
+     * @param partial - Partial replacement set.
+     *
+     * @example Replace everything
+     * ```ts
+     * store.hotReplace({
+     *   reducer: newReducers,
+     *   middleware: newMiddleware,
+     *   effects: newEffects,
+     *   preserveState: true
+     * });
+     * ```
+     *
+     * @public
+     */
+    hotReplace(partial: {
+        reducer?: Record<R, ReducerSpec<S[R], EM>>;
+        middleware?: MiddlewareFunction<DeepReadonly<S>, EM>[];
+        effects?: Array<EffectSpec<DeepReadonly<S>, EM>>;
+        preserveState?: boolean;
+    }): void;
+    /**
+     * Mounts a slice: installs reducer, initializes state (unless preserved),
+     * and wires `(channel, type)` listeners on the reducer bus.
+     *
+     * @param name - Slice name.
+     * @param rSpec - Reducer spec (state, events, reducer).
+     * @param opts - `{ preserveState: boolean }` whether to keep existing state.
+     *
+     * @internal
+     */
+    private mountSlice;
+    /**
+     * Unmounts a slice: disposes reducer-bus listeners, removes reducer,
+     * and optionally deletes the slice state.
+     *
+     * @param name - Slice name.
+     * @param opts - `{ deleteState: boolean }`.
+     *
+     * @internal
+     */
+    private unmountSlice;
+    /**
+     * Normalizes event targeting from `when` or legacy `events` to an array of EventKeys.
+     *
+     * @param spec - Object with optional `when` and/or `events` properties.
+     * @returns Array of `[channel, type]` pairs.
+     *
+     * @internal
+     */
+    private normalizeEventKeys;
+    /**
+     * Reads a dotted path from an object (supports numeric array indices via string keys).
+     *
+     * @param obj - Root object (slice or value).
+     * @param path - Dotted path; leading dot is ignored.
+     * @returns The value at the path, or `undefined`.
+     *
+     * @internal
+     */
+    private getAtPath;
+    /**
+     * Builds ancestor paths for a dotted path.
+     *
+     * For `"a.b.c"`, returns `["a", "a.b", "a.b.c"]`. Leading dots are trimmed.
+     *
+     * @param path - Dotted path string.
+     * @returns Array of ancestor paths.
+     *
+     * @example
+     * ```ts
+     * Store.buildAncestorPaths('x.y.z'); // ['x','x.y','x.y.z']
+     * ```
+     *
+     * @public
+     */
+    static buildAncestorPaths(path: string): string[];
+}
+/**
+ * Creates a store with explicit State and EventMap types.
+ *
+ * Use this overload for:
+ * - **Event-only stores** (no reducers, just middleware/effects)
+ * - When TypeScript inference from reducers isn't sufficient
+ * - When you want to define the EventMap independently of reducers
+ *
+ * @typeParam S  - State record type (can be empty `{}` for event-only stores).
+ * @typeParam EM - Event map type defining all `channel → type → payload` combinations.
+ * @param cfg - Configuration with `name`, optional `reducer`, optional `middleware`, optional `effects`.
+ * @returns A typed {@link StoreInstance}.
+ *
+ * @example Event-only store
+ * ```ts
+ * type AppEM = {
+ *   notifications: { show: { message: string }; hide: void };
+ * };
+ *
+ * const store = createStore<{}, AppEM>({
+ *   name: 'NotificationBus',
+ *   effects: [{
+ *     when: { channel: 'notifications' },
+ *     effect: (evt) => {
+ *       if (evt.type === 'show') showToast(evt.payload.message);
+ *     },
+ *   }],
+ * });
+ * ```
+ *
+ * @example Explicit generics with reducers
+ * ```ts
+ * const store = createStore<AppState, AppEM>({
+ *   name: 'App',
+ *   reducer: { counter: counterSpec },
+ *   middleware: [loggingMiddleware],
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function createStore<S extends Record<string, any>, EM extends EventMapBase>(cfg: {
+    name: string;
+    reducer?: {
+        [K in keyof S]?: ReducerSpec<S[K], EM>;
+    };
+    middleware?: MiddlewareFunction<DeepReadonly<S>, EM>[];
+    effects?: Array<EffectSpec<DeepReadonly<S>, EM>>;
+    dedupWindowMs?: number;
+    devtools?: {
+        allowReplay?: boolean;
+    };
+}): StoreInstance<keyof S & string, S, EM>;
+/**
+ * Creates a store with types inferred from the reducers map.
+ *
+ * This is the primary overload for most use cases where reducers define
+ * both the state shape and the event map.
+ *
+ * @typeParam RM - Reducers map object with each slice's `ReducerSpec`.
+ * @param cfg - Configuration with `name`, `reducer`, optional `middleware`, optional `effects`.
+ * @returns A typed {@link StoreInstance}.
+ *
+ * @example
+ * ```ts
+ * const store = createStore({
+ *   name: 'App',
+ *   reducer: {
+ *     counter: {
+ *       state: { value: 0 },
+ *       when: { keys: eventKeys<MyEM>()([['ui', 'increment']]) },
+ *       reducer: (s, evt) => evt.type === 'increment' ? { value: s.value + evt.payload } : s
+ *     }
+ *   },
+ *   middleware: [],
+ *   effects: []
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function createStore<RM extends ReducersMapAny>(cfg: {
+    name: string;
+    reducer: RM;
+    middleware?: MiddlewareFunction<DeepReadonly<StateFromReducers<RM>>, EMFromReducersStrict<RM>>[];
+    effects?: Array<EffectSpec<DeepReadonly<StateFromReducers<RM>>, EMFromReducersStrict<RM>>>;
+    dedupWindowMs?: number;
+    devtools?: {
+        allowReplay?: boolean;
+    };
+}): StoreInstance<keyof RM & string, StateFromReducers<RM>, EMFromReducersStrict<RM>>;
+/**
+ * Utility to define **typed** `(channel, events[])` definitions for reducer specs.
+ *
+ * @typeParam EM - Event map for the store.
+ * @param _ - Internal marker parameter (usually `events` array placeholder). Not used at runtime.
+ * @returns A helper that, given a `channel` and a readonly `events` array, returns typed event keys.
+ *
+ * @example
+ * ```ts
+ * // In a ReducerSpec:
+ * const events = typedEvents<EM>([])('ui', ['increment', 'decrement'] as const);
+ * // events: ReadonlyArray<EventKey<EM>>
+ * ```
+ *
+ * @public
+ */
+export declare const typedEvents: <EM extends EventMapBase>(_: string[][]) => <C extends keyof EM & string, Evt extends readonly (keyof EM[C] & string)[]>(channel: C, events: Evt) => ReadonlyArray<EventKey<EM>>;