@flexsurfer/reflex 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,150 @@
+import { Draft } from 'immer';
+
+type Db<T = Record<string, any>> = T;
+type Id = string;
+type EventVector = [Id, ...any[]];
+type EventHandler<T = Record<string, any>> = (coeffects: CoEffects<T>, ...params: any[]) => Effects | void;
+type EffectHandler = (value: any) => void;
+type CoEffectHandler<T = Record<string, any>> = (coeffects: CoEffects<T>, value?: any) => CoEffects<T>;
+type ErrorHandler = (originalError: Error, reFrameError: Error & {
+    data: any;
+}) => void;
+type SubVector = [Id, ...any[]];
+type Effects = [string, any][];
+interface DispatchLaterEffect {
+    ms: number;
+    dispatch: EventVector;
+}
+interface CoEffects<T = Record<string, any>> {
+    event: EventVector;
+    draftDb: Draft<Db<T>>;
+    [key: string]: any;
+}
+interface Context<T = Record<string, any>> {
+    coeffects: CoEffects<T>;
+    effects: Effects;
+    newDb: Db<T>;
+    patches: any[];
+    queue: Interceptor<T>[];
+    stack: Interceptor<T>[];
+    originalException: boolean;
+}
+interface Interceptor<T = Record<string, any>> {
+    id: string;
+    before?: (context: Context<T>) => Context<T>;
+    after?: (context: Context<T>) => Context<T>;
+    comment?: string;
+}
+
+declare function initAppDb<T = Record<string, any>>(value: Db<T>): void;
+
+/** Register an event handler with only a handler function (db event) */
+declare function regEvent<T = Record<string, any>>(id: Id, handler: EventHandler<T>): void;
+/** Register an event handler with interceptors and handler function (backward compatibility) */
+declare function regEvent<T = Record<string, any>>(id: Id, handler: EventHandler<T>, interceptors: Interceptor<T>[]): void;
+/** Register an event handler with cofx and handler function */
+declare function regEvent<T = Record<string, any>>(id: Id, handler: EventHandler<T>, cofx: [Id, ...any[]][]): void;
+/** Register an event handler with cofx, interceptors and handler function */
+declare function regEvent<T = Record<string, any>>(id: Id, handler: EventHandler<T>, cofx: [Id, ...any[]][], interceptors: Interceptor<T>[]): void;
+/**
+ * Register the given event error handler function that will catch unhandled exceptions
+ * thrown in the interceptors/handler chain.
+ *
+ * Only one handler can be registered. Registering a new handler clears the existing handler.
+ *
+ * This handler function has the signature:
+ * `(originalError: Error, reFrameError: Error & { data: any }) => void`
+ *
+ * - `originalError`: A platform-native Error object.
+ *    Represents the original error thrown by user code.
+ *    This is the error you see when no handler is registered.
+ *
+ * - `reFrameError`: An Error object with additional data.
+ *    Includes the stacktrace of reflex's internal functions,
+ *    and extra data about the interceptor process.
+ *    Access `reFrameError.data` to get this info.
+ *
+ *    The data includes:
+ *    - `interceptor`: the `id` of the throwing interceptor.
+ *    - `direction`: `'before'` or `'after'`.
+ *    - `eventV`: the reflex event which invoked this interceptor.
+ */
+declare function regEventErrorHandler(handler: ErrorHandler): void;
+/**
+ * Default error handler that logs errors to console
+ */
+declare function defaultErrorHandler(originalError: Error, reFrameError: Error & {
+    data: any;
+}): void;
+
+declare function regSub<R>(id: Id, computeFn?: (...values: any[]) => R, depsFn?: (...params: any[]) => SubVector[]): void;
+
+declare function regEffect(id: string, handler: EffectHandler): void;
+
+declare function regCoeffect(id: string, handler: CoEffectHandler): void;
+
+/**
+ * Register a global interceptor
+ */
+declare function regGlobalInterceptor(interceptor: Interceptor): void;
+/**
+ * Get all global interceptors
+ */
+declare function getGlobalInterceptors(): Interceptor[];
+/**
+ * Clear global interceptors - either all or by specific ID
+ */
+declare function clearGlobalInterceptors(): void;
+declare function clearGlobalInterceptors(id: string): void;
+/**
+ * Enable or disable debug mode
+ */
+declare function setDebugEnabled(enabled: boolean): void;
+/**
+ * Check if debug mode is enabled
+ */
+declare function isDebugEnabled(): boolean;
+
+/**
+ * Port of re-frame.router from ClojureScript to TypeScript.
+ * Implements an event queue with a finite-state-machine to schedule and process events.
+ */
+
+/**
+ * Dispatch an event asynchronously
+ */
+declare function dispatch(event: EventVector): void;
+
+/**
+ * Dispatches `event` iff it was not dispatched for the duration of `durationMs`.
+ * Cancels any existing timeout for the same event and sets a new one.
+ */
+declare function debounceAndDispatch(event: EventVector, durationMs: number): void;
+/**
+ * Dispatches event and ignores subsequent calls for the duration of `durationMs`.
+ * Unlike debouncing, this dispatches immediately on the first call.
+ */
+declare function throttleAndDispatch(event: EventVector, durationMs: number): void;
+
+declare function useSubscription<T>(subVector: SubVector, componentName?: string): T;
+
+type TraceID = number;
+interface TraceOpts {
+    operation?: string;
+    opType?: string;
+    tags?: Record<string, any>;
+    childOf?: TraceID;
+}
+interface Trace extends TraceOpts {
+    id: TraceID;
+    start: number;
+    end?: number;
+    duration?: number;
+}
+type TraceCallback = (traces: Trace[]) => void;
+declare function enableTracing(): void;
+declare function disableTracing(): void;
+declare function registerTraceCb(key: string, cb: TraceCallback): void;
+declare function enableTracePrint(): void;
+
+export { CoEffectHandler, CoEffects, Context, Db, DispatchLaterEffect, EffectHandler, Effects, ErrorHandler, EventHandler, EventVector, Id, Interceptor, SubVector, clearGlobalInterceptors, debounceAndDispatch, defaultErrorHandler, disableTracing, dispatch, enableTracePrint, enableTracing, getGlobalInterceptors, initAppDb, isDebugEnabled, regCoeffect, regEffect, regEvent, regEventErrorHandler, regGlobalInterceptor, regSub, registerTraceCb, setDebugEnabled, throttleAndDispatch, useSubscription };

package/dist/index.d.ts

@@ -0,0 +1,150 @@
+import { Draft } from 'immer';
+
+type Db<T = Record<string, any>> = T;
+type Id = string;
+type EventVector = [Id, ...any[]];
+type EventHandler<T = Record<string, any>> = (coeffects: CoEffects<T>, ...params: any[]) => Effects | void;
+type EffectHandler = (value: any) => void;
+type CoEffectHandler<T = Record<string, any>> = (coeffects: CoEffects<T>, value?: any) => CoEffects<T>;
+type ErrorHandler = (originalError: Error, reFrameError: Error & {
+    data: any;
+}) => void;
+type SubVector = [Id, ...any[]];
+type Effects = [string, any][];
+interface DispatchLaterEffect {
+    ms: number;
+    dispatch: EventVector;
+}
+interface CoEffects<T = Record<string, any>> {
+    event: EventVector;
+    draftDb: Draft<Db<T>>;
+    [key: string]: any;
+}
+interface Context<T = Record<string, any>> {
+    coeffects: CoEffects<T>;
+    effects: Effects;
+    newDb: Db<T>;
+    patches: any[];
+    queue: Interceptor<T>[];
+    stack: Interceptor<T>[];
+    originalException: boolean;
+}
+interface Interceptor<T = Record<string, any>> {
+    id: string;
+    before?: (context: Context<T>) => Context<T>;
+    after?: (context: Context<T>) => Context<T>;
+    comment?: string;
+}
+
+declare function initAppDb<T = Record<string, any>>(value: Db<T>): void;
+
+/** Register an event handler with only a handler function (db event) */
+declare function regEvent<T = Record<string, any>>(id: Id, handler: EventHandler<T>): void;
+/** Register an event handler with interceptors and handler function (backward compatibility) */
+declare function regEvent<T = Record<string, any>>(id: Id, handler: EventHandler<T>, interceptors: Interceptor<T>[]): void;
+/** Register an event handler with cofx and handler function */
+declare function regEvent<T = Record<string, any>>(id: Id, handler: EventHandler<T>, cofx: [Id, ...any[]][]): void;
+/** Register an event handler with cofx, interceptors and handler function */
+declare function regEvent<T = Record<string, any>>(id: Id, handler: EventHandler<T>, cofx: [Id, ...any[]][], interceptors: Interceptor<T>[]): void;
+/**
+ * Register the given event error handler function that will catch unhandled exceptions
+ * thrown in the interceptors/handler chain.
+ *
+ * Only one handler can be registered. Registering a new handler clears the existing handler.
+ *
+ * This handler function has the signature:
+ * `(originalError: Error, reFrameError: Error & { data: any }) => void`
+ *
+ * - `originalError`: A platform-native Error object.
+ *    Represents the original error thrown by user code.
+ *    This is the error you see when no handler is registered.
+ *
+ * - `reFrameError`: An Error object with additional data.
+ *    Includes the stacktrace of reflex's internal functions,
+ *    and extra data about the interceptor process.
+ *    Access `reFrameError.data` to get this info.
+ *
+ *    The data includes:
+ *    - `interceptor`: the `id` of the throwing interceptor.
+ *    - `direction`: `'before'` or `'after'`.
+ *    - `eventV`: the reflex event which invoked this interceptor.
+ */
+declare function regEventErrorHandler(handler: ErrorHandler): void;
+/**
+ * Default error handler that logs errors to console
+ */
+declare function defaultErrorHandler(originalError: Error, reFrameError: Error & {
+    data: any;
+}): void;
+
+declare function regSub<R>(id: Id, computeFn?: (...values: any[]) => R, depsFn?: (...params: any[]) => SubVector[]): void;
+
+declare function regEffect(id: string, handler: EffectHandler): void;
+
+declare function regCoeffect(id: string, handler: CoEffectHandler): void;
+
+/**
+ * Register a global interceptor
+ */
+declare function regGlobalInterceptor(interceptor: Interceptor): void;
+/**
+ * Get all global interceptors
+ */
+declare function getGlobalInterceptors(): Interceptor[];
+/**
+ * Clear global interceptors - either all or by specific ID
+ */
+declare function clearGlobalInterceptors(): void;
+declare function clearGlobalInterceptors(id: string): void;
+/**
+ * Enable or disable debug mode
+ */
+declare function setDebugEnabled(enabled: boolean): void;
+/**
+ * Check if debug mode is enabled
+ */
+declare function isDebugEnabled(): boolean;
+
+/**
+ * Port of re-frame.router from ClojureScript to TypeScript.
+ * Implements an event queue with a finite-state-machine to schedule and process events.
+ */
+
+/**
+ * Dispatch an event asynchronously
+ */
+declare function dispatch(event: EventVector): void;
+
+/**
+ * Dispatches `event` iff it was not dispatched for the duration of `durationMs`.
+ * Cancels any existing timeout for the same event and sets a new one.
+ */
+declare function debounceAndDispatch(event: EventVector, durationMs: number): void;
+/**
+ * Dispatches event and ignores subsequent calls for the duration of `durationMs`.
+ * Unlike debouncing, this dispatches immediately on the first call.
+ */
+declare function throttleAndDispatch(event: EventVector, durationMs: number): void;
+
+declare function useSubscription<T>(subVector: SubVector, componentName?: string): T;
+
+type TraceID = number;
+interface TraceOpts {
+    operation?: string;
+    opType?: string;
+    tags?: Record<string, any>;
+    childOf?: TraceID;
+}
+interface Trace extends TraceOpts {
+    id: TraceID;
+    start: number;
+    end?: number;
+    duration?: number;
+}
+type TraceCallback = (traces: Trace[]) => void;
+declare function enableTracing(): void;
+declare function disableTracing(): void;
+declare function registerTraceCb(key: string, cb: TraceCallback): void;
+declare function enableTracePrint(): void;
+
+export { CoEffectHandler, CoEffects, Context, Db, DispatchLaterEffect, EffectHandler, Effects, ErrorHandler, EventHandler, EventVector, Id, Interceptor, SubVector, clearGlobalInterceptors, debounceAndDispatch, defaultErrorHandler, disableTracing, dispatch, enableTracePrint, enableTracing, getGlobalInterceptors, initAppDb, isDebugEnabled, regCoeffect, regEffect, regEvent, regEventErrorHandler, regGlobalInterceptor, regSub, registerTraceCb, setDebugEnabled, throttleAndDispatch, useSubscription };