@flexsurfer/reflex 0.1.12 → 0.1.14

package/README.md

@@ -1,10 +1,10 @@
 <div align="center">
-  <img src="reflex-logo-300kb.png" alt="Reflex Logo" width="200" />
+  <img src="reflex_logo.jpg" alt="Reflex Logo" width="200" />
 </div>
 
 **re-frame for the JavaScript world**
 
-A reactive, functional state management library that brings the elegance and power of ClojureScript's re-frame to JavaScript and React/ReactNative applications.
+A reactive, functional state management library that brings the elegance and power of ClojureScript's re-frame to JavaScript/TypeScript and React/ReactNative applications.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![NPM Version](https://img.shields.io/npm/v/%40flexsurfer%2Freflex)](https://www.npmjs.com/package/@flexsurfer/reflex)
@@ -20,265 +20,23 @@ After many years of building applications with re-frame in the ClojureScript wor
 🧩 **Composable Architecture** - Build complex apps from simple, reusable pieces  
 🔄 **Reactive Subscriptions** - UI automatically updates when state changes  
 🌐 **Multi-Platform Support** - With effects separation, it's super easy to support multiple platforms with the same codebase, including web, mobile, and desktop  
-🤖 **AI Friendly** - Reviewing AI-generated changes is easier because all logic is expressed through pure, isolated functions, making each change understandable, verifiable, and deterministic.
-🛠️ **Integrated DevTools** - Reflex-devtools provides deep visibility into your app’s state, events, and subscriptions in real time, forming a powerful combo with Reflex for effective development and debugging.
+🤖 **AI Friendly** - Reviewing AI-generated changes is easier because all logic is expressed through pure, isolated functions, making each change understandable, verifiable, and deterministic.  
+🛠️ **Integrated DevTools** - [`@flexsurfer/reflex-devtools`](https://github.com/flexsurfer/reflex-devtools) provides deep visibility into your app’s state, events, and subscriptions in real time, forming a powerful combo with Reflex for effective development and debugging.  
 ⚡ **Interceptor Pattern** - Powerful middleware system for cross-cutting concerns  
 🛡️ **Type Safety** - Full TypeScript support with excellent IDE experience  
 🧪 **Testability** - Pure functions make testing straightforward and reliable  
 
-## 🚀 Quick Start
-
-```bash
-npm install @flexsurfer/reflex
-npm install --save-dev @flexsurfer/reflex-devtools
-
-npx reflex-devtools
-```
-
-### Basic Example
-
-```typescript
-import { 
-  initAppDb, 
-  regEvent, 
-  regSub, 
-  dispatch, 
-  useSubscription,
-  enableTracing
-} from '@flexsurfer/reflex';
-import { enableDevtools } from '@flexsurfer/reflex-devtools'
-
-enableTracing()
-enableDevtools();
-
-// Initialize your app database
-initAppDb({ counter: 0 });
-
-// Register events (state transitions)
-regEvent('increment', ({ draftDb }) => {
-  draftDb.counter += 1; 
-});
-
-regEvent('decrement', ({ draftDb }) => {
-   draftDb.counter -= 1; 
-});
-
-// Register subscriptions (reactive queries)
-regSub('counter');
-
-// React component
-const Counter = () => {
-  const counter = useSubscription<number>(['counter']);
-  
-  return (
-    <div>
-      <h1>Count: {counter}</h1>
-      <button onClick={() => dispatch(['increment'])}>+</button>
-      <button onClick={() => dispatch(['decrement'])}>-</button>
-    </div>
-  );
-}
-```
-
-## 🏗️ Core Concepts
-
-### Events & Effects
-
-Events define state transitions and may declare side effects:
-
-```typescript
-// Simple state update
-regEvent('set-name', ({ draftDb }, name) => {
-   draftDb.user.name = name;
-});
-
-// Dispatch with parameters
-dispatch(['set-name', 'John Doe']);
-
-// Event with side effects
-regEvent('save-user', ({ draftDb }, user) => {
-  draftDb.saving = true; 
-  return [
-    ['http', {
-      method: 'POST',
-      url: '/api/users',
-      body: user,
-      onSuccess: ['save-user-success'],
-      onFailure: ['save-user-error']
-    }]
-  ]
-});
-
-// Dispatch with parameters
-dispatch(['save-user', { id: 1, name: 'John', email: 'john@example.com' }]);
-```
-
-### Subscriptions
-
-Create reactive queries that automatically update your UI:
-
-```typescript
-regSub('user');
-regSub('display-prefix');
-regSub('user-name', (user) => user.name, () => [['user']]);
-
-// Computed subscription with dependencies
-regSub('user-display-name',
-  (name, prefix) => `${prefix}: ${name}`,
-  () => [['user-name'], ['display-prefix']]
-);
-
-// Parameterized subscription
-regSub(
-  'todo-by-id',
-  (todos, id) => todos.find(todo => todo.id === id),
-  () => [['todos']]
-);
-
-regSub(
-  'todo-text-by-id',
-  (todo, _id) => todo.text,
-  (id) => [['todo-by-id' id]]
-);
-
-// Use in React components
-function UserProfile() {
-  const name = useSubscription<string>(['user-display-name']);
-  const todo = useSubscription(['todo-by-id', 123])
-  const todoText = useSubscription(['todo-text-by-id', 123]);
-  
-  return <div>{name}</div>;
-}
-```
-
-### Effects & Co-effects
-
-Handle side effects in a controlled, testable way:
-
-```typescript
-import { 
-  regEffect,
-  regCoeffect
-} from '@flexsurfer/reflex';
-
-// Register custom effects
-regEffect('local-storage', (payload) => {
-  localStorage.setItem(payload.key, JSON.stringify(payload.value));
-});
-
-// Use in events
-regEvent('save-to-storage', (_coeffects, data) => {
-  return [['local-storage', { key: 'app-data', value: data }]]
-});
-
-// Dispatch with data parameter
-dispatch(['save-to-storage', { user: 'John', preferences: { theme: 'dark' } }]);
-
-// Register co-effects
-regCoeffect('timestamp', (coeffects) => {
-  coeffects.timestamp = Date.now();
-  return coeffects;
-});
-
-regCoeffect('random', (coeffects) => {
-  coeffects.random = Math.random();
-  return coeffects;
-});
-
-// Use co-effect in events
-regEvent('log-action', 
-  ({ draftDb, timestamp, random }, action) => {
-    draftDb.actionLog.push({
-      action,
-      timestamp: timestamp,
-      id: random.toString(36)
-    });
-  },
-  [['timestamp'], ['random']] 
-);
-
-// Dispatch with action parameter
-dispatch(['log-action', 'some-action']);
-```
-
-### Interceptors
-
-Compose functionality with interceptors:
-
-```typescript
-const loggingInterceptor = {
-  id: 'logging',
-  before: (context) => {
-    console.log('Event:', context.coeffects.event);
-    return context;
-  },
-  after: (context) => {
-    console.log('Updated DB:', context.coeffects.newDb);
-    return context;
-  }
-};
-
-regEvent('my-event', handler, [loggingInterceptor]);
-```
-
-## 🎯 Why Re-frame Pattern?
-
-The re-frame pattern has proven itself in production applications over many years:
-
-- **Separation of Concerns**: Clear boundaries between events, effects, and subscriptions
-- **Time Travel Debugging**: Every state change is an event that can be replayed
-- **Testability**: Pure functions make unit testing straightforward
-- **Composability**: Build complex features from simple, reusable parts
-- **Maintainability**: Code becomes self-documenting and easy to reason about
-
-## 🔄 Migration from Other Libraries
-
-### From Redux
-
-```typescript
-// Redux style
-const counterSlice = createSlice({
-  name: 'count',
-  initialState: { value: 0 },
-  reducers: {
-    increment: (state) => { state.value += 1; }
-  }
-});
-
-// Reflex style
-initAppDb({ count: 0 });
-regEvent('increment', ({ draftDb }) => {
-   draftDb.count += 1; 
-});
-regSub('count');
-```
-
-### From Zustand
-
-```typescript
-// Zustand style
-const useStore = create((set) => ({
-  count: 0,
-  increment: () => set((state) => ({ count: state.count + 1 }))
-}));
-
-// Reflex style
-initAppDb({ count: 0 });
-regEvent('increment', ({ draftDb }) => {
-   draftDb.count += 1; 
-});
-regSub('count');
-```
-
 ## 📚 Learn More
 
+- [Documentation](https://reflex.js.org/docs/)
+- [Step-by-Step Tutorial](https://reflex.js.org/docs/quick-start.html)
+- [Best Practices](https://reflex.js.org/docs/api-reference.html)
+- [API Reference](https://reflex.js.org/docs/best-practices.html)
 - [re-frame Documentation](https://day8.github.io/re-frame/re-frame/) - The original and comprehensive guide to understanding the philosophy and patterns
-- Step-by-Step Tutorial - TBD
-- API Reference - TBD
+
 - Examples
   - [TodoMVC](https://github.com/flexsurfer/reflex/tree/main/examples/todomvc) - Classic todo app implementation showcasing core reflex patterns
   - [Einbürgerungstest](https://github.com/flexsurfer/einburgerungstest/) - German citizenship test app built with reflex ([Live Demo](https://www.ebtest.org/))
-- Best Practices - TBD
 
 ## 🤝 Contributing
 

package/dist/index.cjs

@@ -30,12 +30,17 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  DISPATCH: () => DISPATCH,
+  DISPATCH_LATER: () => DISPATCH_LATER,
   HotReloadWrapper: () => HotReloadWrapper,
+  NOW: () => NOW,
+  RANDOM: () => RANDOM,
   clearGlobalInterceptors: () => clearGlobalInterceptors,
   clearHandlers: () => clearHandlers,
   clearHotReloadCallbacks: () => clearHotReloadCallbacks,
   clearReactions: () => clearReactions,
   clearSubs: () => clearSubs,
+  current: () => current,
   debounceAndDispatch: () => debounceAndDispatch,
   defaultErrorHandler: () => defaultErrorHandler,
   disableTracing: () => disableTracing,
@@ -47,7 +52,7 @@ __export(src_exports, {
   getHandler: () => getHandler,
   getSubscriptionValue: () => getSubscriptionValue,
   initAppDb: () => initAppDb,
-  isDebugEnabled: () => isDebugEnabled,
+  original: () => original,
   regCoeffect: () => regCoeffect,
   regEffect: () => regEffect,
   regEvent: () => regEvent,
@@ -56,7 +61,6 @@ __export(src_exports, {
   regSub: () => regSub,
   registerHotReloadCallback: () => registerHotReloadCallback,
   registerTraceCb: () => registerTraceCb,
-  setDebugEnabled: () => setDebugEnabled,
   setupSubsHotReload: () => setupSubsHotReload,
   throttleAndDispatch: () => throttleAndDispatch,
   triggerHotReload: () => triggerHotReload,
@@ -226,6 +230,15 @@ function updateAppDbWithPatches(newDb, patches) {
   }
 }
 
+// src/immer-utils.ts
+var import_immer = require("immer");
+function original(value) {
+  return (0, import_immer.isDraft)(value) ? (0, import_immer.original)(value) : value;
+}
+function current(value) {
+  return (0, import_immer.isDraft)(value) ? (0, import_immer.current)(value) : value;
+}
+
 // src/interceptor.ts
 function isInterceptor(m) {
   if (typeof m !== "object" || m === null)
@@ -314,8 +327,8 @@ function execute(eventV, interceptors) {
   try {
     return executeInterceptors(ctx);
   } catch (e) {
-    const reFrameError = mergeExData(e, { eventV });
-    errorHandler(e.cause || e, reFrameError);
+    const reflexError = mergeExData(e, { eventV });
+    errorHandler(e.cause || e, reflexError);
     return ctx;
   }
 }
@@ -343,11 +356,13 @@ function getInjectCofxInterceptor(id, value) {
     }
   };
 }
-regCoeffect("now", (coeffects) => ({
+var NOW = "now";
+var RANDOM = "random";
+regCoeffect(NOW, (coeffects) => ({
   ...coeffects,
   now: Date.now()
 }));
-regCoeffect("random", (coeffects) => ({
+regCoeffect(RANDOM, (coeffects) => ({
   ...coeffects,
   random: Math.random()
 }));
@@ -532,6 +547,8 @@ var doFxInterceptor = {
     return context;
   }
 };
+var DISPATCH_LATER = "dispatch-later";
+var DISPATCH = "dispatch";
 function dispatchLater(effect) {
   const { ms, dispatch: eventToDispatch } = effect;
   if (!Array.isArray(eventToDispatch) || typeof ms !== "number") {
@@ -543,10 +560,10 @@ function dispatchLater(effect) {
   }
   setTimeout(() => dispatch(eventToDispatch), Math.max(0, ms));
 }
-regEffect("dispatch-later", (value) => {
+regEffect(DISPATCH_LATER, (value) => {
   dispatchLater(value);
 });
-regEffect("dispatch", (value) => {
+regEffect(DISPATCH, (value) => {
   if (!Array.isArray(value)) {
     consoleLog("error", "[reflex] ignoring bad dispatch value. Expected a vector, but got:", value);
     return;
@@ -555,20 +572,15 @@ regEffect("dispatch", (value) => {
 });
 
 // src/events.ts
-var import_immer = require("immer");
+var import_immer2 = require("immer");
 
 // src/settings.ts
 var store = {
-  globalInterceptors: [],
-  debugEnabled: true
-  // Default to true, can be configured via setDebugEnabled
+  globalInterceptors: []
 };
 function replaceGlobalInterceptor(globalInterceptors, interceptor) {
   return globalInterceptors.reduce((ret, existingInterceptor) => {
     if (interceptor.id === existingInterceptor.id) {
-      if (store.debugEnabled) {
-        consoleLog("warn", "[reflex] replacing duplicate global interceptor id:", interceptor.id);
-      }
       return [...ret, interceptor];
     } else {
       return [...ret, existingInterceptor];
@@ -594,12 +606,6 @@ function clearGlobalInterceptors(id) {
     store.globalInterceptors = store.globalInterceptors.filter((interceptor) => interceptor.id !== id);
   }
 }
-function setDebugEnabled(enabled) {
-  store.debugEnabled = enabled;
-}
-function isDebugEnabled() {
-  return store.debugEnabled;
-}
 
 // src/trace.ts
 var nextId = 1;
@@ -700,6 +706,13 @@ function enableTracePrint() {
   });
 }
 
+// src/env.ts
+var IS_DEV = (
+  // Node.js check
+  typeof process !== "undefined" && process.env?.NODE_ENV === "development" || // React Native / bundler check
+  typeof __DEV__ !== "undefined" && __DEV__
+);
+
 // src/events.ts
 var KIND3 = "event";
 function regEvent(id, handler, cofxOrInterceptors, interceptors) {
@@ -748,22 +761,28 @@ function registerInterceptors(id, cofxOrInterceptors, interceptors) {
     setInterceptors(id, allInterceptors);
   }
 }
-(0, import_immer.enablePatches)();
+(0, import_immer2.enablePatches)();
 function eventHandlerInterceptor(handler) {
   return {
     id: "fx-handler",
     before(context) {
-      const coeffects = context.coeffects;
-      const event = coeffects.event;
+      const event = context.coeffects.event;
       const params = event.slice(1);
       let effects = [];
-      const [newDb, patches] = (0, import_immer.produceWithPatches)(
+      const [newDb, patches] = (0, import_immer2.produceWithPatches)(
         getAppDb(),
         (draftDb) => {
-          coeffects.draftDb = draftDb;
-          effects = handler({ ...coeffects }, ...params) || [];
+          const coeffectsWithDb = { ...context.coeffects, draftDb };
+          effects = handler(coeffectsWithDb, ...params) || [];
         }
       );
+      if (IS_DEV) {
+        try {
+          JSON.stringify(effects);
+        } catch (e) {
+          consoleLog("warn", `[reflex] Effects ${effects} contain Proxy (probably an Immer draft). Use current() for draftDb values.`);
+        }
+      }
       context.newDb = newDb;
       context.patches = patches;
       mergeTrace({ tags: { "patches": patches, "effects": effects } });
@@ -808,11 +827,11 @@ function handle(eventV) {
 function regEventErrorHandler(handler) {
   registerHandler("error", "event-handler", handler);
 }
-function defaultErrorHandler(originalError, reFrameError) {
+function defaultErrorHandler(originalError, reflexError) {
   consoleLog("error", "[reflex] Interceptor Exception:", {
     originalError,
-    reFrameError,
-    data: reFrameError.data
+    reflexError,
+    data: reflexError.data
   });
   throw originalError;
 }
@@ -1187,21 +1206,22 @@ function setupSubsHotReload() {
   return { dispose, accept };
 }
 function HotReloadWrapper({ children }) {
-  if (isDebugEnabled()) {
-    const key = useHotReloadKey();
-    return import_react2.default.createElement(import_react2.default.Fragment, { key }, children);
-  } else {
-    return children;
-  }
+  const key = useHotReloadKey();
+  return import_react2.default.createElement(import_react2.default.Fragment, { key }, children);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DISPATCH,
+  DISPATCH_LATER,
   HotReloadWrapper,
+  NOW,
+  RANDOM,
   clearGlobalInterceptors,
   clearHandlers,
   clearHotReloadCallbacks,
   clearReactions,
   clearSubs,
+  current,
   debounceAndDispatch,
   defaultErrorHandler,
   disableTracing,
@@ -1213,7 +1233,7 @@ function HotReloadWrapper({ children }) {
   getHandler,
   getSubscriptionValue,
   initAppDb,
-  isDebugEnabled,
+  original,
   regCoeffect,
   regEffect,
   regEvent,
@@ -1222,7 +1242,6 @@ function HotReloadWrapper({ children }) {
   regSub,
   registerHotReloadCallback,
   registerTraceCb,
-  setDebugEnabled,
   setupSubsHotReload,
   throttleAndDispatch,
   triggerHotReload,

package/dist/index.d.cts

@@ -7,7 +7,7 @@ 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 & {
+type ErrorHandler = (originalError: Error, reflexError: Error & {
     data: any;
 }) => void;
 type SubVector = [Id, ...any[]];
@@ -42,6 +42,23 @@ interface Interceptor<T = Record<string, any>> {
 declare function initAppDb<T = Record<string, any>>(value: Db<T>): void;
 declare function getAppDb<T = Record<string, any>>(): Db<T>;
 
+/**
+ * Safe versions of immer's original and current functions
+ * These check if the value is actually a draft before calling the immer functions
+ */
+/**
+ * Safe version of immer's original function
+ * Returns the original (frozen) version of a draft if the value is a draft,
+ * otherwise returns the value as-is
+ */
+declare function original<T>(value: T): T;
+/**
+ * Safe version of immer's current function
+ * Returns the current draft state as a plain object if the value is a draft,
+ * otherwise returns the value as-is
+ */
+declare function current<T>(value: T): T;
+
 /** 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) */
@@ -57,16 +74,16 @@ declare function regEvent<T = Record<string, any>>(id: Id, handler: EventHandler
  * 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: Error, reflexError: 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.
+ * - `reflexError`: 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.
+ *    Access `reflexError.data` to get this info.
  *
  *    The data includes:
  *    - `interceptor`: the `id` of the throwing interceptor.
@@ -77,7 +94,7 @@ declare function regEventErrorHandler(handler: ErrorHandler): void;
 /**
  * Default error handler that logs errors to console
  */
-declare function defaultErrorHandler(originalError: Error, reFrameError: Error & {
+declare function defaultErrorHandler(originalError: Error, reflexError: Error & {
     data: any;
 }): void;
 
@@ -85,8 +102,12 @@ declare function regSub<R>(id: Id, computeFn?: (...values: any[]) => R, depsFn?:
 declare function getSubscriptionValue<T>(subVector: SubVector): T;
 
 declare function regEffect(id: string, handler: EffectHandler): void;
+declare const DISPATCH_LATER = "dispatch-later";
+declare const DISPATCH = "dispatch";
 
 declare function regCoeffect(id: string, handler: CoEffectHandler): void;
+declare const NOW = "now";
+declare const RANDOM = "random";
 
 /**
  * Register a global interceptor
@@ -101,14 +122,6 @@ declare function getGlobalInterceptors(): Interceptor[];
  */
 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;
 
 type Kind = 'event' | 'fx' | 'cofx' | 'sub' | 'subDeps' | 'error';
 type RegistryHandler = EventHandler | EffectHandler | CoEffectHandler | ErrorHandler | SubHandler | SubDepsHandler;
@@ -179,9 +192,9 @@ declare function setupSubsHotReload(): {
  */
 declare function HotReloadWrapper({ children }: {
     children: React.ReactNode;
-}): string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.FunctionComponentElement<{
+}): React.FunctionComponentElement<{
     children?: React.ReactNode | undefined;
-}> | null | undefined;
+}>;
 
 type TraceID = number;
 interface TraceOpts {
@@ -202,4 +215,4 @@ 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, HotReloadWrapper, Id, Interceptor, SubVector, clearGlobalInterceptors, clearHandlers, clearHotReloadCallbacks, clearReactions, clearSubs, debounceAndDispatch, defaultErrorHandler, disableTracing, dispatch, enableTracePrint, enableTracing, getAppDb, getGlobalInterceptors, getHandler, getSubscriptionValue, initAppDb, isDebugEnabled, regCoeffect, regEffect, regEvent, regEventErrorHandler, regGlobalInterceptor, regSub, registerHotReloadCallback, registerTraceCb, setDebugEnabled, setupSubsHotReload, throttleAndDispatch, triggerHotReload, useHotReload, useHotReloadKey, useSubscription };
+export { CoEffectHandler, CoEffects, Context, DISPATCH, DISPATCH_LATER, Db, DispatchLaterEffect, EffectHandler, Effects, ErrorHandler, EventHandler, EventVector, HotReloadWrapper, Id, Interceptor, NOW, RANDOM, SubVector, clearGlobalInterceptors, clearHandlers, clearHotReloadCallbacks, clearReactions, clearSubs, current, debounceAndDispatch, defaultErrorHandler, disableTracing, dispatch, enableTracePrint, enableTracing, getAppDb, getGlobalInterceptors, getHandler, getSubscriptionValue, initAppDb, original, regCoeffect, regEffect, regEvent, regEventErrorHandler, regGlobalInterceptor, regSub, registerHotReloadCallback, registerTraceCb, setupSubsHotReload, throttleAndDispatch, triggerHotReload, useHotReload, useHotReloadKey, useSubscription };

package/dist/index.d.ts

@@ -7,7 +7,7 @@ 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 & {
+type ErrorHandler = (originalError: Error, reflexError: Error & {
     data: any;
 }) => void;
 type SubVector = [Id, ...any[]];
@@ -42,6 +42,23 @@ interface Interceptor<T = Record<string, any>> {
 declare function initAppDb<T = Record<string, any>>(value: Db<T>): void;
 declare function getAppDb<T = Record<string, any>>(): Db<T>;
 
+/**
+ * Safe versions of immer's original and current functions
+ * These check if the value is actually a draft before calling the immer functions
+ */
+/**
+ * Safe version of immer's original function
+ * Returns the original (frozen) version of a draft if the value is a draft,
+ * otherwise returns the value as-is
+ */
+declare function original<T>(value: T): T;
+/**
+ * Safe version of immer's current function
+ * Returns the current draft state as a plain object if the value is a draft,
+ * otherwise returns the value as-is
+ */
+declare function current<T>(value: T): T;
+
 /** 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) */
@@ -57,16 +74,16 @@ declare function regEvent<T = Record<string, any>>(id: Id, handler: EventHandler
  * 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: Error, reflexError: 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.
+ * - `reflexError`: 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.
+ *    Access `reflexError.data` to get this info.
  *
  *    The data includes:
  *    - `interceptor`: the `id` of the throwing interceptor.
@@ -77,7 +94,7 @@ declare function regEventErrorHandler(handler: ErrorHandler): void;
 /**
  * Default error handler that logs errors to console
  */
-declare function defaultErrorHandler(originalError: Error, reFrameError: Error & {
+declare function defaultErrorHandler(originalError: Error, reflexError: Error & {
     data: any;
 }): void;
 
@@ -85,8 +102,12 @@ declare function regSub<R>(id: Id, computeFn?: (...values: any[]) => R, depsFn?:
 declare function getSubscriptionValue<T>(subVector: SubVector): T;
 
 declare function regEffect(id: string, handler: EffectHandler): void;
+declare const DISPATCH_LATER = "dispatch-later";
+declare const DISPATCH = "dispatch";
 
 declare function regCoeffect(id: string, handler: CoEffectHandler): void;
+declare const NOW = "now";
+declare const RANDOM = "random";
 
 /**
  * Register a global interceptor
@@ -101,14 +122,6 @@ declare function getGlobalInterceptors(): Interceptor[];
  */
 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;
 
 type Kind = 'event' | 'fx' | 'cofx' | 'sub' | 'subDeps' | 'error';
 type RegistryHandler = EventHandler | EffectHandler | CoEffectHandler | ErrorHandler | SubHandler | SubDepsHandler;
@@ -179,9 +192,9 @@ declare function setupSubsHotReload(): {
  */
 declare function HotReloadWrapper({ children }: {
     children: React.ReactNode;
-}): string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.FunctionComponentElement<{
+}): React.FunctionComponentElement<{
     children?: React.ReactNode | undefined;
-}> | null | undefined;
+}>;
 
 type TraceID = number;
 interface TraceOpts {
@@ -202,4 +215,4 @@ 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, HotReloadWrapper, Id, Interceptor, SubVector, clearGlobalInterceptors, clearHandlers, clearHotReloadCallbacks, clearReactions, clearSubs, debounceAndDispatch, defaultErrorHandler, disableTracing, dispatch, enableTracePrint, enableTracing, getAppDb, getGlobalInterceptors, getHandler, getSubscriptionValue, initAppDb, isDebugEnabled, regCoeffect, regEffect, regEvent, regEventErrorHandler, regGlobalInterceptor, regSub, registerHotReloadCallback, registerTraceCb, setDebugEnabled, setupSubsHotReload, throttleAndDispatch, triggerHotReload, useHotReload, useHotReloadKey, useSubscription };
+export { CoEffectHandler, CoEffects, Context, DISPATCH, DISPATCH_LATER, Db, DispatchLaterEffect, EffectHandler, Effects, ErrorHandler, EventHandler, EventVector, HotReloadWrapper, Id, Interceptor, NOW, RANDOM, SubVector, clearGlobalInterceptors, clearHandlers, clearHotReloadCallbacks, clearReactions, clearSubs, current, debounceAndDispatch, defaultErrorHandler, disableTracing, dispatch, enableTracePrint, enableTracing, getAppDb, getGlobalInterceptors, getHandler, getSubscriptionValue, initAppDb, original, regCoeffect, regEffect, regEvent, regEventErrorHandler, regGlobalInterceptor, regSub, registerHotReloadCallback, registerTraceCb, setupSubsHotReload, throttleAndDispatch, triggerHotReload, useHotReload, useHotReloadKey, useSubscription };

package/dist/index.mjs

@@ -158,6 +158,15 @@ function updateAppDbWithPatches(newDb, patches) {
   }
 }
 
+// src/immer-utils.ts
+import { isDraft, original as immerOriginal, current as immerCurrent } from "immer";
+function original(value) {
+  return isDraft(value) ? immerOriginal(value) : value;
+}
+function current(value) {
+  return isDraft(value) ? immerCurrent(value) : value;
+}
+
 // src/interceptor.ts
 function isInterceptor(m) {
   if (typeof m !== "object" || m === null)
@@ -246,8 +255,8 @@ function execute(eventV, interceptors) {
   try {
     return executeInterceptors(ctx);
   } catch (e) {
-    const reFrameError = mergeExData(e, { eventV });
-    errorHandler(e.cause || e, reFrameError);
+    const reflexError = mergeExData(e, { eventV });
+    errorHandler(e.cause || e, reflexError);
     return ctx;
   }
 }
@@ -275,11 +284,13 @@ function getInjectCofxInterceptor(id, value) {
     }
   };
 }
-regCoeffect("now", (coeffects) => ({
+var NOW = "now";
+var RANDOM = "random";
+regCoeffect(NOW, (coeffects) => ({
   ...coeffects,
   now: Date.now()
 }));
-regCoeffect("random", (coeffects) => ({
+regCoeffect(RANDOM, (coeffects) => ({
   ...coeffects,
   random: Math.random()
 }));
@@ -464,6 +475,8 @@ var doFxInterceptor = {
     return context;
   }
 };
+var DISPATCH_LATER = "dispatch-later";
+var DISPATCH = "dispatch";
 function dispatchLater(effect) {
   const { ms, dispatch: eventToDispatch } = effect;
   if (!Array.isArray(eventToDispatch) || typeof ms !== "number") {
@@ -475,10 +488,10 @@ function dispatchLater(effect) {
   }
   setTimeout(() => dispatch(eventToDispatch), Math.max(0, ms));
 }
-regEffect("dispatch-later", (value) => {
+regEffect(DISPATCH_LATER, (value) => {
   dispatchLater(value);
 });
-regEffect("dispatch", (value) => {
+regEffect(DISPATCH, (value) => {
   if (!Array.isArray(value)) {
     consoleLog("error", "[reflex] ignoring bad dispatch value. Expected a vector, but got:", value);
     return;
@@ -491,16 +504,11 @@ import { enablePatches, produceWithPatches } from "immer";
 
 // src/settings.ts
 var store = {
-  globalInterceptors: [],
-  debugEnabled: true
-  // Default to true, can be configured via setDebugEnabled
+  globalInterceptors: []
 };
 function replaceGlobalInterceptor(globalInterceptors, interceptor) {
   return globalInterceptors.reduce((ret, existingInterceptor) => {
     if (interceptor.id === existingInterceptor.id) {
-      if (store.debugEnabled) {
-        consoleLog("warn", "[reflex] replacing duplicate global interceptor id:", interceptor.id);
-      }
       return [...ret, interceptor];
     } else {
       return [...ret, existingInterceptor];
@@ -526,12 +534,6 @@ function clearGlobalInterceptors(id) {
     store.globalInterceptors = store.globalInterceptors.filter((interceptor) => interceptor.id !== id);
   }
 }
-function setDebugEnabled(enabled) {
-  store.debugEnabled = enabled;
-}
-function isDebugEnabled() {
-  return store.debugEnabled;
-}
 
 // src/trace.ts
 var nextId = 1;
@@ -632,6 +634,13 @@ function enableTracePrint() {
   });
 }
 
+// src/env.ts
+var IS_DEV = (
+  // Node.js check
+  typeof process !== "undefined" && process.env?.NODE_ENV === "development" || // React Native / bundler check
+  typeof __DEV__ !== "undefined" && __DEV__
+);
+
 // src/events.ts
 var KIND3 = "event";
 function regEvent(id, handler, cofxOrInterceptors, interceptors) {
@@ -685,17 +694,23 @@ function eventHandlerInterceptor(handler) {
   return {
     id: "fx-handler",
     before(context) {
-      const coeffects = context.coeffects;
-      const event = coeffects.event;
+      const event = context.coeffects.event;
       const params = event.slice(1);
       let effects = [];
       const [newDb, patches] = produceWithPatches(
         getAppDb(),
         (draftDb) => {
-          coeffects.draftDb = draftDb;
-          effects = handler({ ...coeffects }, ...params) || [];
+          const coeffectsWithDb = { ...context.coeffects, draftDb };
+          effects = handler(coeffectsWithDb, ...params) || [];
         }
       );
+      if (IS_DEV) {
+        try {
+          JSON.stringify(effects);
+        } catch (e) {
+          consoleLog("warn", `[reflex] Effects ${effects} contain Proxy (probably an Immer draft). Use current() for draftDb values.`);
+        }
+      }
       context.newDb = newDb;
       context.patches = patches;
       mergeTrace({ tags: { "patches": patches, "effects": effects } });
@@ -740,11 +755,11 @@ function handle(eventV) {
 function regEventErrorHandler(handler) {
   registerHandler("error", "event-handler", handler);
 }
-function defaultErrorHandler(originalError, reFrameError) {
+function defaultErrorHandler(originalError, reflexError) {
   consoleLog("error", "[reflex] Interceptor Exception:", {
     originalError,
-    reFrameError,
-    data: reFrameError.data
+    reflexError,
+    data: reflexError.data
   });
   throw originalError;
 }
@@ -1119,20 +1134,21 @@ function setupSubsHotReload() {
   return { dispose, accept };
 }
 function HotReloadWrapper({ children }) {
-  if (isDebugEnabled()) {
-    const key = useHotReloadKey();
-    return React.createElement(React.Fragment, { key }, children);
-  } else {
-    return children;
-  }
+  const key = useHotReloadKey();
+  return React.createElement(React.Fragment, { key }, children);
 }
 export {
+  DISPATCH,
+  DISPATCH_LATER,
   HotReloadWrapper,
+  NOW,
+  RANDOM,
   clearGlobalInterceptors,
   clearHandlers,
   clearHotReloadCallbacks,
   clearReactions,
   clearSubs,
+  current,
   debounceAndDispatch,
   defaultErrorHandler,
   disableTracing,
@@ -1144,7 +1160,7 @@ export {
   getHandler,
   getSubscriptionValue,
   initAppDb,
-  isDebugEnabled,
+  original,
   regCoeffect,
   regEffect,
   regEvent,
@@ -1153,7 +1169,6 @@ export {
   regSub,
   registerHotReloadCallback,
   registerTraceCb,
-  setDebugEnabled,
   setupSubsHotReload,
   throttleAndDispatch,
   triggerHotReload,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flexsurfer/reflex",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -30,7 +30,9 @@
     "dev": "tsup --watch",
     "test": "jest --passWithNoTests",
     "test:clean": "jest --passWithNoTests --silent",
-    "test:watch": "jest --passWithNoTests --watch"
+    "test:watch": "jest --passWithNoTests --watch",
+    "test:ci": "jest --passWithNoTests --coverage --silent",
+    "prepublishOnly": "npm run test:ci && npm run build"
   },
   "devDependencies": {
     "@testing-library/dom": "^10.4.0",