@rplx/core 0.2.0

package/README.md

@@ -0,0 +1,132 @@
+# @rplx/core
+
+A re-frame inspired state management library for TypeScript.
+
+## Installation
+
+```bash
+npm install @rplx/core
+```
+
+## Usage
+
+```typescript
+import { createStore } from '@rplx/core'
+
+// Define your state
+interface AppState {
+  count: number
+}
+
+// Define your coeffects (optional)
+interface AppCoeffects {
+  uuid: string
+  now: Date
+}
+
+// Create store with coeffect providers
+const store = createStore<AppState, AppCoeffects>({
+  initialState: { count: 0 },
+  coeffects: {
+    uuid: () => crypto.randomUUID(),
+    now: () => new Date()
+  }
+})
+
+// Register event handlers - fully type-safe!
+store.registerEvent('increment', (context, payload) => {
+  // context.db is AppState
+  // context.uuid is string
+  // context.now is Date
+  return [
+    { count: context.db.count + 1 },
+    {} // no effects
+  ]
+})
+
+// Dispatch events
+await store.dispatch('increment')
+
+// Get state
+const state = store.getState()
+```
+
+## Core Concepts
+
+### Events
+Events are dispatched to trigger state changes. Each event has a handler that receives the current state (via context) and a payload, and returns a new state and effects.
+
+### Coeffects (Context)
+Coeffects are the **inputs** to event handlers. Define your coeffect types and provide functions to compute them:
+
+```typescript
+interface MyCoeffects {
+  uuid: string
+  now: Date
+}
+
+const store = createStore<AppState, MyCoeffects>({
+  initialState,
+  coeffects: {
+    uuid: () => crypto.randomUUID(),
+    now: () => new Date()
+  }
+})
+
+// Handlers get type-safe access
+store.registerEvent('create', (context, data) => {
+  const { db, uuid, now } = context  // ✅ Fully typed!
+  return [newState, effects]
+})
+```
+
+**Benefits:**
+- ✅ Full type safety
+- ✅ Easy to test (mock coeffect providers)
+- ✅ Lazy evaluation
+
+### Effects
+Effects are side effects that can be triggered by event handlers. Common effects include:
+- `dispatch` - Dispatch another event
+- `dispatch-n` - Dispatch multiple events
+- Custom effects (HTTP requests, localStorage, etc.)
+
+### Interceptors
+Interceptors wrap event handlers to add cross-cutting concerns. They have `:before` and `:after` phases that run in opposite order (like middleware):
+
+```typescript
+import { path, debug } from '@rplx/core'
+
+store.registerEventWithInterceptors(
+  'update-todo',
+  [path(['todos']), debug()],
+  handler
+)
+```
+
+## API
+
+### `createStore<State, Cofx>(config)`
+
+Factory function to create a store instance. Generic over State and Coeffects.
+
+**Parameters:**
+- `config.initialState` - Initial application state
+- `config.coeffects` - Optional coeffect providers
+- `config.tracing` - Optional tracing configuration
+
+**Returns:** A store instance with the following methods:
+- `registerEventDb<Payload>(eventKey, handler, interceptors?)` - Register an event handler that returns state
+- `registerEvent<Payload>(eventKey, handler, interceptors?)` - Register an event handler that returns effects
+- `registerEffect<Config>(effectType, handler)` - Register an effect handler
+- `dispatch<Payload>(eventKey, payload)` - Dispatch an event
+- `getState()` - Get current state
+- `flush()` - Flush event queue (for testing)
+- `registerSubscription(key, config)` - Register a subscription
+- `subscribe(key, params, callback)` - Subscribe to state changes
+- `query(key, params)` - Query a subscription once
+
+## License
+
+MIT
+

package/dist/index.d.mts

@@ -0,0 +1,237 @@
+interface EffectMap {
+    db?: any;
+    dispatch?: {
+        event: string;
+        payload: any;
+    };
+    'dispatch-n'?: Array<{
+        event: string;
+        payload: any;
+    }>;
+    'dispatch-later'?: Array<{
+        ms: number;
+        event: string;
+        payload: any;
+    }>;
+    fx?: Array<[string, any] | null>;
+    'deregister-event-handler'?: string | string[];
+}
+type Context<State, Cofx = {}> = {
+    db: State;
+    event?: any;
+} & Cofx;
+type EventHandlerDb<State, Cofx = {}, Payload = any> = (context: Context<State, Cofx>, payload: Payload) => State;
+type EventHandlerFx<State, Cofx = {}, Payload = any> = (context: Context<State, Cofx>, payload: Payload) => EffectMap;
+interface ErrorContext {
+    eventKey: string;
+    payload: any;
+    phase: 'interceptor' | 'effect' | 'subscription';
+    interceptor?: {
+        id?: string;
+        direction: 'before' | 'after';
+    };
+}
+interface ErrorHandlerConfig {
+    /** Whether to re-throw the error after handling (default: false) */
+    rethrow?: boolean;
+}
+type ErrorHandler = (error: Error, context: ErrorContext, config: ErrorHandlerConfig) => void | Promise<void>;
+type EffectHandler<Config = any> = (config: Config, store: any) => Promise<void> | void;
+type CoeffectProviders<Cofx> = {
+    [K in keyof Cofx]: () => Cofx[K];
+};
+interface EffectExecutionTrace {
+    effectType: string;
+    config: any;
+    start: number;
+    end: number;
+    duration: number;
+    error?: Error;
+}
+interface EventTrace<State = any> {
+    id: number;
+    eventKey: string;
+    payload: any;
+    timestamp: number;
+    stateBefore: State;
+    stateAfter: State;
+    interceptors: Array<{
+        id?: string;
+        order: number;
+    }>;
+    effectMap: EffectMap;
+    effectsExecuted: EffectExecutionTrace[];
+    duration: number;
+    error?: Error;
+}
+type TraceCallback<State = any> = (traces: EventTrace<State>[]) => void;
+interface StoreConfig<State, Cofx = {}> {
+    initialState: State;
+    coeffects?: CoeffectProviders<Cofx>;
+    onStateChange?: (state: State) => void;
+    /** Error handler configuration */
+    errorHandler?: {
+        handler?: ErrorHandler;
+        rethrow?: boolean;
+    };
+    /** Tracing configuration */
+    tracing?: {
+        enabled?: boolean;
+        debounceTime?: number;
+    };
+}
+interface QueuedEvent {
+    eventKey: string;
+    payload: any;
+}
+
+interface InterceptorContext<State, Cofx = {}> {
+    coeffects: Context<State, Cofx>;
+    effects: EffectMap;
+    queue: Interceptor<State, Cofx>[];
+    stack: Interceptor<State, Cofx>[];
+}
+interface Interceptor<State, Cofx = {}> {
+    id?: string;
+    before?: (context: InterceptorContext<State, Cofx>) => InterceptorContext<State, Cofx>;
+    after?: (context: InterceptorContext<State, Cofx>) => InterceptorContext<State, Cofx>;
+}
+/**
+ * Path interceptor - focus handler on a path in state
+ */
+declare function path<State, Cofx = {}>(pathKeys: (keyof State)[]): Interceptor<State, Cofx>;
+/**
+ * Debug interceptor - log events
+ */
+declare function debug<State, Cofx = {}>(): Interceptor<State, Cofx>;
+/**
+ * After interceptor - run side effect after handler
+ */
+declare function after<State, Cofx = {}>(fn: (db: State, effects: EffectMap) => void): Interceptor<State, Cofx>;
+/**
+ * Inject coeffect interceptor - adds a dynamic coeffect value
+ * Note: With the new coeffect provider system, this is rarely needed
+ * Use it only for one-off dynamic values that aren't in your Cofx type
+ */
+declare function injectCofx<State, Cofx = {}>(key: string, value: any): Interceptor<State, Cofx>;
+/**
+ * Validation interceptor
+ */
+declare function validate<State, Cofx = {}>(schema: (state: State) => boolean | string): Interceptor<State, Cofx>;
+
+/**
+ * Subscription system
+ */
+type SubscriptionFn<State, Result, Params extends any[] = []> = (state: State, ...params: Params) => Result;
+type SubscriptionConfig<State, Result, Params extends any[] = [], Deps extends any[] = any[]> = {
+    compute?: SubscriptionFn<State, Result, Params>;
+    deps?: string[];
+    combine?: (deps: Deps, ...params: Params) => Result;
+};
+/**
+ * Shared subscription object - same instance for same key+params
+ * This enables React memoization and matches re-frame behavior
+ */
+declare class Subscription<State = any, Result = any, Params extends any[] = []> {
+    readonly key: string;
+    readonly params: Params;
+    constructor(key: string, params: Params);
+}
+type SubscriptionErrorHandler = (error: Error, key: string, params: any[]) => void;
+declare class SubscriptionRegistry<State> {
+    private subscriptions;
+    private subscriptionCache;
+    private resultCache;
+    private refCounts;
+    private listeners;
+    register<Result, Params extends any[] = [], Deps extends any[] = any[]>(key: string, config: SubscriptionConfig<State, Result, Params, Deps>): void;
+    /**
+     * Get or create a shared Subscription object for the given key+params
+     * Returns the same object for the same key+params (like re-frame)
+     */
+    getSubscription<Result, Params extends any[]>(key: string, params: Params): Subscription<State, Result, Params>;
+    subscribe<Result, Params extends any[]>(state: State, key: string, params: Params, callback: (result: Result) => void, onError?: SubscriptionErrorHandler): () => void;
+    query<Result, Params extends any[]>(state: State, key: string, params: Params, onError?: SubscriptionErrorHandler): Result;
+    notifyListeners(newState: State): void;
+    private getCacheKey;
+    private deepEqual;
+}
+
+/**
+ * Store Factory Module
+ * Creates a store instance by composing all modules together
+ *
+ * This is the primary API for creating stores (replaces the Store class)
+ */
+
+/**
+ * Store API interface - all public methods available on a store instance
+ */
+interface StoreAPI<State, Cofx = {}> {
+    registerEventDb<Payload = any>(eventKey: string, handler: EventHandlerDb<State, Cofx, Payload>, interceptors?: Interceptor<State, Cofx>[]): void;
+    registerEvent<Payload = any>(eventKey: string, handler: EventHandlerFx<State, Cofx, Payload>, interceptors?: Interceptor<State, Cofx>[]): void;
+    deregisterEvent(eventKey: string): void;
+    registerEffect<Config = any>(effectType: string, handler: EffectHandler<Config>): void;
+    dispatch<Payload = any>(eventKey: string, payload: Payload): Promise<void>;
+    flush(): Promise<void>;
+    getState(): Readonly<State>;
+    getInterceptors(eventKey: string): Interceptor<State, Cofx>[] | undefined;
+    registerErrorHandler(handler: ErrorHandler, config?: ErrorHandlerConfig): void;
+    registerSubscription<Result, Params extends any[] = [], Deps extends any[] = any[]>(key: string, config: SubscriptionConfig<State, Result, Params, Deps>): void;
+    subscribe<Result, Params extends any[]>(key: string, params: Params, callback: (result: Result) => void): () => void;
+    query<Result, Params extends any[]>(key: string, params: Params): Result;
+    getSubscription<Result, Params extends any[]>(key: string, params: Params): any;
+    registerTraceCallback(key: string, callback: TraceCallback<State>): void;
+    removeTraceCallback(key: string): void;
+}
+/**
+ * Create a new store instance by composing all modules
+ *
+ * This is the recommended way to create a store (replaces `new Store()`)
+ *
+ * @param config - Store configuration
+ * @returns Store API instance
+ */
+declare function createStore<State, Cofx = {}>(config: StoreConfig<State, Cofx>): StoreAPI<State, Cofx>;
+
+/**
+ * Error Handler Module
+ * Handles error registration and execution
+ */
+
+/**
+ * Default error handler
+ * Logs error details to console
+ */
+declare function defaultErrorHandler(error: Error, context: ErrorContext, config: ErrorHandlerConfig): void;
+
+/**
+ * Effects Module
+ * Handles effect execution and built-in effects
+ * Inspired by re-frame's fx.cljc
+ */
+
+/**
+ * Merge multiple effect maps into a single effect map
+ *
+ * Handles special merging rules for:
+ * - `dispatch-n`: Arrays are concatenated
+ * - `dispatch-later`: Arrays are concatenated
+ * - `fx`: Arrays are concatenated
+ * - `deregister-event-handler`: Arrays or strings are merged
+ * - Other effects: Last one wins
+ *
+ * @example
+ * ```typescript
+ * import { mergeEffects } from '@rplx/core'
+ *
+ * const effects = mergeEffects(
+ *   { db: newState },
+ *   { dispatch: { event: 'save', payload: {} } },
+ *   { 'dispatch-n': [{ event: 'log', payload: {} }] }
+ * )
+ * ```
+ */
+declare function mergeEffects(...effects: EffectMap[]): EffectMap;
+
+export { type CoeffectProviders, type Context, type EffectExecutionTrace, type EffectHandler, type EffectMap, type ErrorContext, type ErrorHandler, type ErrorHandlerConfig, type EventHandlerDb, type EventHandlerFx, type EventTrace, type Interceptor, type InterceptorContext, type QueuedEvent, type StoreAPI, type StoreConfig, Subscription, type SubscriptionConfig, type SubscriptionErrorHandler, type SubscriptionFn, SubscriptionRegistry, type TraceCallback, after, createStore, debug, defaultErrorHandler, injectCofx, mergeEffects, path, validate };

package/dist/index.d.ts

@@ -0,0 +1,237 @@
+interface EffectMap {
+    db?: any;
+    dispatch?: {
+        event: string;
+        payload: any;
+    };
+    'dispatch-n'?: Array<{
+        event: string;
+        payload: any;
+    }>;
+    'dispatch-later'?: Array<{
+        ms: number;
+        event: string;
+        payload: any;
+    }>;
+    fx?: Array<[string, any] | null>;
+    'deregister-event-handler'?: string | string[];
+}
+type Context<State, Cofx = {}> = {
+    db: State;
+    event?: any;
+} & Cofx;
+type EventHandlerDb<State, Cofx = {}, Payload = any> = (context: Context<State, Cofx>, payload: Payload) => State;
+type EventHandlerFx<State, Cofx = {}, Payload = any> = (context: Context<State, Cofx>, payload: Payload) => EffectMap;
+interface ErrorContext {
+    eventKey: string;
+    payload: any;
+    phase: 'interceptor' | 'effect' | 'subscription';
+    interceptor?: {
+        id?: string;
+        direction: 'before' | 'after';
+    };
+}
+interface ErrorHandlerConfig {
+    /** Whether to re-throw the error after handling (default: false) */
+    rethrow?: boolean;
+}
+type ErrorHandler = (error: Error, context: ErrorContext, config: ErrorHandlerConfig) => void | Promise<void>;
+type EffectHandler<Config = any> = (config: Config, store: any) => Promise<void> | void;
+type CoeffectProviders<Cofx> = {
+    [K in keyof Cofx]: () => Cofx[K];
+};
+interface EffectExecutionTrace {
+    effectType: string;
+    config: any;
+    start: number;
+    end: number;
+    duration: number;
+    error?: Error;
+}
+interface EventTrace<State = any> {
+    id: number;
+    eventKey: string;
+    payload: any;
+    timestamp: number;
+    stateBefore: State;
+    stateAfter: State;
+    interceptors: Array<{
+        id?: string;
+        order: number;
+    }>;
+    effectMap: EffectMap;
+    effectsExecuted: EffectExecutionTrace[];
+    duration: number;
+    error?: Error;
+}
+type TraceCallback<State = any> = (traces: EventTrace<State>[]) => void;
+interface StoreConfig<State, Cofx = {}> {
+    initialState: State;
+    coeffects?: CoeffectProviders<Cofx>;
+    onStateChange?: (state: State) => void;
+    /** Error handler configuration */
+    errorHandler?: {
+        handler?: ErrorHandler;
+        rethrow?: boolean;
+    };
+    /** Tracing configuration */
+    tracing?: {
+        enabled?: boolean;
+        debounceTime?: number;
+    };
+}
+interface QueuedEvent {
+    eventKey: string;
+    payload: any;
+}
+
+interface InterceptorContext<State, Cofx = {}> {
+    coeffects: Context<State, Cofx>;
+    effects: EffectMap;
+    queue: Interceptor<State, Cofx>[];
+    stack: Interceptor<State, Cofx>[];
+}
+interface Interceptor<State, Cofx = {}> {
+    id?: string;
+    before?: (context: InterceptorContext<State, Cofx>) => InterceptorContext<State, Cofx>;
+    after?: (context: InterceptorContext<State, Cofx>) => InterceptorContext<State, Cofx>;
+}
+/**
+ * Path interceptor - focus handler on a path in state
+ */
+declare function path<State, Cofx = {}>(pathKeys: (keyof State)[]): Interceptor<State, Cofx>;
+/**
+ * Debug interceptor - log events
+ */
+declare function debug<State, Cofx = {}>(): Interceptor<State, Cofx>;
+/**
+ * After interceptor - run side effect after handler
+ */
+declare function after<State, Cofx = {}>(fn: (db: State, effects: EffectMap) => void): Interceptor<State, Cofx>;
+/**
+ * Inject coeffect interceptor - adds a dynamic coeffect value
+ * Note: With the new coeffect provider system, this is rarely needed
+ * Use it only for one-off dynamic values that aren't in your Cofx type
+ */
+declare function injectCofx<State, Cofx = {}>(key: string, value: any): Interceptor<State, Cofx>;
+/**
+ * Validation interceptor
+ */
+declare function validate<State, Cofx = {}>(schema: (state: State) => boolean | string): Interceptor<State, Cofx>;
+
+/**
+ * Subscription system
+ */
+type SubscriptionFn<State, Result, Params extends any[] = []> = (state: State, ...params: Params) => Result;
+type SubscriptionConfig<State, Result, Params extends any[] = [], Deps extends any[] = any[]> = {
+    compute?: SubscriptionFn<State, Result, Params>;
+    deps?: string[];
+    combine?: (deps: Deps, ...params: Params) => Result;
+};
+/**
+ * Shared subscription object - same instance for same key+params
+ * This enables React memoization and matches re-frame behavior
+ */
+declare class Subscription<State = any, Result = any, Params extends any[] = []> {
+    readonly key: string;
+    readonly params: Params;
+    constructor(key: string, params: Params);
+}
+type SubscriptionErrorHandler = (error: Error, key: string, params: any[]) => void;
+declare class SubscriptionRegistry<State> {
+    private subscriptions;
+    private subscriptionCache;
+    private resultCache;
+    private refCounts;
+    private listeners;
+    register<Result, Params extends any[] = [], Deps extends any[] = any[]>(key: string, config: SubscriptionConfig<State, Result, Params, Deps>): void;
+    /**
+     * Get or create a shared Subscription object for the given key+params
+     * Returns the same object for the same key+params (like re-frame)
+     */
+    getSubscription<Result, Params extends any[]>(key: string, params: Params): Subscription<State, Result, Params>;
+    subscribe<Result, Params extends any[]>(state: State, key: string, params: Params, callback: (result: Result) => void, onError?: SubscriptionErrorHandler): () => void;
+    query<Result, Params extends any[]>(state: State, key: string, params: Params, onError?: SubscriptionErrorHandler): Result;
+    notifyListeners(newState: State): void;
+    private getCacheKey;
+    private deepEqual;
+}
+
+/**
+ * Store Factory Module
+ * Creates a store instance by composing all modules together
+ *
+ * This is the primary API for creating stores (replaces the Store class)
+ */
+
+/**
+ * Store API interface - all public methods available on a store instance
+ */
+interface StoreAPI<State, Cofx = {}> {
+    registerEventDb<Payload = any>(eventKey: string, handler: EventHandlerDb<State, Cofx, Payload>, interceptors?: Interceptor<State, Cofx>[]): void;
+    registerEvent<Payload = any>(eventKey: string, handler: EventHandlerFx<State, Cofx, Payload>, interceptors?: Interceptor<State, Cofx>[]): void;
+    deregisterEvent(eventKey: string): void;
+    registerEffect<Config = any>(effectType: string, handler: EffectHandler<Config>): void;
+    dispatch<Payload = any>(eventKey: string, payload: Payload): Promise<void>;
+    flush(): Promise<void>;
+    getState(): Readonly<State>;
+    getInterceptors(eventKey: string): Interceptor<State, Cofx>[] | undefined;
+    registerErrorHandler(handler: ErrorHandler, config?: ErrorHandlerConfig): void;
+    registerSubscription<Result, Params extends any[] = [], Deps extends any[] = any[]>(key: string, config: SubscriptionConfig<State, Result, Params, Deps>): void;
+    subscribe<Result, Params extends any[]>(key: string, params: Params, callback: (result: Result) => void): () => void;
+    query<Result, Params extends any[]>(key: string, params: Params): Result;
+    getSubscription<Result, Params extends any[]>(key: string, params: Params): any;
+    registerTraceCallback(key: string, callback: TraceCallback<State>): void;
+    removeTraceCallback(key: string): void;
+}
+/**
+ * Create a new store instance by composing all modules
+ *
+ * This is the recommended way to create a store (replaces `new Store()`)
+ *
+ * @param config - Store configuration
+ * @returns Store API instance
+ */
+declare function createStore<State, Cofx = {}>(config: StoreConfig<State, Cofx>): StoreAPI<State, Cofx>;
+
+/**
+ * Error Handler Module
+ * Handles error registration and execution
+ */
+
+/**
+ * Default error handler
+ * Logs error details to console
+ */
+declare function defaultErrorHandler(error: Error, context: ErrorContext, config: ErrorHandlerConfig): void;
+
+/**
+ * Effects Module
+ * Handles effect execution and built-in effects
+ * Inspired by re-frame's fx.cljc
+ */
+
+/**
+ * Merge multiple effect maps into a single effect map
+ *
+ * Handles special merging rules for:
+ * - `dispatch-n`: Arrays are concatenated
+ * - `dispatch-later`: Arrays are concatenated
+ * - `fx`: Arrays are concatenated
+ * - `deregister-event-handler`: Arrays or strings are merged
+ * - Other effects: Last one wins
+ *
+ * @example
+ * ```typescript
+ * import { mergeEffects } from '@rplx/core'
+ *
+ * const effects = mergeEffects(
+ *   { db: newState },
+ *   { dispatch: { event: 'save', payload: {} } },
+ *   { 'dispatch-n': [{ event: 'log', payload: {} }] }
+ * )
+ * ```
+ */
+declare function mergeEffects(...effects: EffectMap[]): EffectMap;
+
+export { type CoeffectProviders, type Context, type EffectExecutionTrace, type EffectHandler, type EffectMap, type ErrorContext, type ErrorHandler, type ErrorHandlerConfig, type EventHandlerDb, type EventHandlerFx, type EventTrace, type Interceptor, type InterceptorContext, type QueuedEvent, type StoreAPI, type StoreConfig, Subscription, type SubscriptionConfig, type SubscriptionErrorHandler, type SubscriptionFn, SubscriptionRegistry, type TraceCallback, after, createStore, debug, defaultErrorHandler, injectCofx, mergeEffects, path, validate };