@flexsurfer/reflex 0.1.0 → 0.1.2

package/README.md

@@ -8,8 +8,9 @@ A reactive, functional state management library that brings the elegance and pow
 
 > ⚠️ **Development Status**: This library is in active development and not yet ready for production use. Perfect for pet projects, experiments, and learning! The community is warmly invited to contribute to the development and improvement of the library, including optimizations for data comparison at different lifecycle stages.
 
-[![npm version](https://badge.fury.io/js/@flexsurfer%2Freflex.svg)](https://badge.fury.io/js/@flexsurfer%2Freflex)
 [![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)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/flexsurfer/reflex/pulls)
 
 📚 **Want to understand the philosophy behind this approach?** Check out the amazing [re-frame documentation](https://day8.github.io/re-frame/re-frame/) which describes the greatness of this framework in the finest details. Everything you learn there applies to reflex! Though we do lose some of ClojureScript's natural immutability magic. Immer helps bridge this gap, but it's not quite as elegant or efficient as CLJS persistent data structures.
 
@@ -57,7 +58,7 @@ regEvent('decrement', ({ draftDb }) => {
 regSub('counter');
 
 // React component
-function Counter() {
+const Counter = () => {
   const counter = useSubscription<number>(['counter']);
   
   return (
@@ -74,7 +75,7 @@ function Counter() {
 
 ### Events & Effects
 
-Events are pure functions that describe state transitions:
+Events define state transitions and may declare side effects:
 
 ```typescript
 // Simple state update
@@ -87,7 +88,6 @@ dispatch(['set-name', 'John Doe']);
 
 // Event with side effects
 regEvent('save-user', ({ draftDb }, user) => {
-  draftDb.user = user; 
   draftDb.saving = true; 
   return [
     ['http', {

package/dist/index.cjs

@@ -30,7 +30,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  HotReloadWrapper: () => HotReloadWrapper,
   clearGlobalInterceptors: () => clearGlobalInterceptors,
+  clearHandlers: () => clearHandlers,
+  clearHotReloadCallbacks: () => clearHotReloadCallbacks,
+  clearReactions: () => clearReactions,
+  clearSubs: () => clearSubs,
   debounceAndDispatch: () => debounceAndDispatch,
   defaultErrorHandler: () => defaultErrorHandler,
   disableTracing: () => disableTracing,
@@ -46,9 +51,14 @@ __export(src_exports, {
   regEventErrorHandler: () => regEventErrorHandler,
   regGlobalInterceptor: () => regGlobalInterceptor,
   regSub: () => regSub,
+  registerHotReloadCallback: () => registerHotReloadCallback,
   registerTraceCb: () => registerTraceCb,
   setDebugEnabled: () => setDebugEnabled,
+  setupSubsHotReload: () => setupSubsHotReload,
   throttleAndDispatch: () => throttleAndDispatch,
+  triggerHotReload: () => triggerHotReload,
+  useHotReload: () => useHotReload,
+  useHotReloadKey: () => useHotReloadKey,
   useSubscription: () => useSubscription
 });
 module.exports = __toCommonJS(src_exports);
@@ -96,6 +106,25 @@ function registerHandler(kind, id, handlerFn) {
   kindToIdToHandler[kind][id] = handlerFn;
   return handlerFn;
 }
+function clearHandlers(kind, id) {
+  if (kind == null) {
+    for (const k in kindToIdToHandler) {
+      kindToIdToHandler[k] = {};
+    }
+  } else if (id == null) {
+    if (!(kind in kindToIdToHandler)) {
+      consoleLog("error", `[reflex] Unknown kind: ${kind}`);
+      return;
+    }
+    kindToIdToHandler[kind] = {};
+  } else {
+    if (kindToIdToHandler[kind][id]) {
+      delete kindToIdToHandler[kind][id];
+    } else {
+      consoleLog("warn", `[reflex] can't clear ${kind} handler for ${id}. Handler not found.`);
+    }
+  }
+}
 function hasHandler(kind, id) {
   return !!kindToIdToHandler[kind][id];
 }
@@ -106,6 +135,18 @@ function getReaction(key) {
 function setReaction(key, reaction) {
   reactionsRegistry.set(key, reaction);
 }
+function clearReactions(id) {
+  if (id == null) {
+    reactionsRegistry.clear();
+  } else {
+    reactionsRegistry.delete(id);
+  }
+}
+function clearSubs() {
+  clearReactions();
+  clearHandlers("sub");
+  clearHandlers("subDeps");
+}
 var interceptorsRegistry = /* @__PURE__ */ new Map();
 function getInterceptors(eventId) {
   return interceptorsRegistry.get(eventId) || [];
@@ -1072,9 +1113,85 @@ function useSubscription(subVector, componentName = "react component") {
   }, []);
   return val;
 }
+
+// src/hot-reload.ts
+var import_react2 = __toESM(require("react"), 1);
+var hotReloadCallbacks = /* @__PURE__ */ new Set();
+function registerHotReloadCallback(callback) {
+  hotReloadCallbacks.add(callback);
+  return () => {
+    hotReloadCallbacks.delete(callback);
+  };
+}
+function triggerHotReload() {
+  consoleLog("log", "[reflex] Triggering hot reload callbacks");
+  for (const callback of hotReloadCallbacks) {
+    try {
+      callback();
+    } catch (error) {
+      consoleLog("error", "[reflex] Error in hot reload callback:", error);
+    }
+  }
+}
+function clearHotReloadCallbacks() {
+  hotReloadCallbacks.clear();
+}
+function useHotReload() {
+  const [, forceUpdate] = (0, import_react2.useState)({});
+  const callbackRef = (0, import_react2.useRef)(null);
+  (0, import_react2.useEffect)(() => {
+    const triggerUpdate = () => {
+      forceUpdate({});
+    };
+    callbackRef.current = triggerUpdate;
+    const unregister = registerHotReloadCallback(triggerUpdate);
+    return () => {
+      unregister();
+      callbackRef.current = null;
+    };
+  }, []);
+}
+var keyCounter = 0;
+function useHotReloadKey() {
+  const [key, setKey] = (0, import_react2.useState)(() => `hot-reload-${++keyCounter}`);
+  const callbackRef = (0, import_react2.useRef)(null);
+  (0, import_react2.useEffect)(() => {
+    const updateKey = () => {
+      setKey(`hot-reload-${++keyCounter}`);
+    };
+    callbackRef.current = updateKey;
+    const unregister = registerHotReloadCallback(updateKey);
+    return () => {
+      unregister();
+      callbackRef.current = null;
+    };
+  }, []);
+  return key;
+}
+function setupSubsHotReload() {
+  const dispose = () => {
+    clearSubs();
+  };
+  const accept = (newModule) => {
+    if (newModule) {
+      consoleLog("log", "[reflex] Hot reloading subs module");
+      triggerHotReload();
+    }
+  };
+  return { dispose, accept };
+}
+function HotReloadWrapper({ children }) {
+  const key = useHotReloadKey();
+  return import_react2.default.createElement("div", { key, style: { display: "contents" } }, children);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  HotReloadWrapper,
   clearGlobalInterceptors,
+  clearHandlers,
+  clearHotReloadCallbacks,
+  clearReactions,
+  clearSubs,
   debounceAndDispatch,
   defaultErrorHandler,
   disableTracing,
@@ -1090,8 +1207,13 @@ function useSubscription(subVector, componentName = "react component") {
   regEventErrorHandler,
   regGlobalInterceptor,
   regSub,
+  registerHotReloadCallback,
   registerTraceCb,
   setDebugEnabled,
+  setupSubsHotReload,
   throttleAndDispatch,
+  triggerHotReload,
+  useHotReload,
+  useHotReloadKey,
   useSubscription
 });

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { Draft } from 'immer';
+import React from 'react';
 
 type Db<T = Record<string, any>> = T;
 type Id = string;
@@ -105,6 +106,14 @@ declare function setDebugEnabled(enabled: boolean): void;
  */
 declare function isDebugEnabled(): boolean;
 
+type Kind = 'event' | 'fx' | 'cofx' | 'sub' | 'subDeps' | 'error';
+declare function clearHandlers(): void;
+declare function clearHandlers(kind: Kind): void;
+declare function clearHandlers(kind: Kind, id: string): void;
+declare function clearReactions(): void;
+declare function clearReactions(id: string): void;
+declare function clearSubs(): void;
+
 /**
  * Port of re-frame.router from ClojureScript to TypeScript.
  * Implements an event queue with a finite-state-machine to schedule and process events.
@@ -128,6 +137,49 @@ declare function throttleAndDispatch(event: EventVector, durationMs: number): vo
 
 declare function useSubscription<T>(subVector: SubVector, componentName?: string): T;
 
+type HotReloadCallback = () => void;
+/**
+ * Register a callback to be called when subs are hot reloaded
+ */
+declare function registerHotReloadCallback(callback: HotReloadCallback): () => void;
+/**
+ * Trigger all registered hot reload callbacks
+ */
+declare function triggerHotReload(): void;
+/**
+ * Clear all hot reload callbacks
+ */
+declare function clearHotReloadCallbacks(): void;
+/**
+ * React hook that forces component re-render when subs are hot reloaded
+ */
+declare function useHotReload(): void;
+/**
+ * React hook that provides a key that changes when subs are hot reloaded
+ * Useful for forcing complete re-mount of component trees
+ */
+declare function useHotReloadKey(): string;
+/**
+ * Utility for setting up hot reload in subs modules
+ * Returns dispose and accept functions for HMR
+ */
+declare function setupSubsHotReload(): {
+    dispose: () => void;
+    accept: (newModule?: any) => void;
+};
+/**
+ * React component that wraps children with hot reload support
+ * Uses a key that changes when subs are hot reloaded to force re-mount
+ */
+declare function HotReloadWrapper({ children }: {
+    children: React.ReactNode;
+}): React.DetailedReactHTMLElement<{
+    key: string;
+    style: {
+        display: "contents";
+    };
+}, HTMLElement>;
+
 type TraceID = number;
 interface TraceOpts {
     operation?: string;
@@ -147,4 +199,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, Id, Interceptor, SubVector, clearGlobalInterceptors, debounceAndDispatch, defaultErrorHandler, disableTracing, dispatch, enableTracePrint, enableTracing, getGlobalInterceptors, initAppDb, isDebugEnabled, regCoeffect, regEffect, regEvent, regEventErrorHandler, regGlobalInterceptor, regSub, registerTraceCb, setDebugEnabled, throttleAndDispatch, useSubscription };
+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, getGlobalInterceptors, initAppDb, isDebugEnabled, regCoeffect, regEffect, regEvent, regEventErrorHandler, regGlobalInterceptor, regSub, registerHotReloadCallback, registerTraceCb, setDebugEnabled, setupSubsHotReload, throttleAndDispatch, triggerHotReload, useHotReload, useHotReloadKey, useSubscription };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { Draft } from 'immer';
+import React from 'react';
 
 type Db<T = Record<string, any>> = T;
 type Id = string;
@@ -105,6 +106,14 @@ declare function setDebugEnabled(enabled: boolean): void;
  */
 declare function isDebugEnabled(): boolean;
 
+type Kind = 'event' | 'fx' | 'cofx' | 'sub' | 'subDeps' | 'error';
+declare function clearHandlers(): void;
+declare function clearHandlers(kind: Kind): void;
+declare function clearHandlers(kind: Kind, id: string): void;
+declare function clearReactions(): void;
+declare function clearReactions(id: string): void;
+declare function clearSubs(): void;
+
 /**
  * Port of re-frame.router from ClojureScript to TypeScript.
  * Implements an event queue with a finite-state-machine to schedule and process events.
@@ -128,6 +137,49 @@ declare function throttleAndDispatch(event: EventVector, durationMs: number): vo
 
 declare function useSubscription<T>(subVector: SubVector, componentName?: string): T;
 
+type HotReloadCallback = () => void;
+/**
+ * Register a callback to be called when subs are hot reloaded
+ */
+declare function registerHotReloadCallback(callback: HotReloadCallback): () => void;
+/**
+ * Trigger all registered hot reload callbacks
+ */
+declare function triggerHotReload(): void;
+/**
+ * Clear all hot reload callbacks
+ */
+declare function clearHotReloadCallbacks(): void;
+/**
+ * React hook that forces component re-render when subs are hot reloaded
+ */
+declare function useHotReload(): void;
+/**
+ * React hook that provides a key that changes when subs are hot reloaded
+ * Useful for forcing complete re-mount of component trees
+ */
+declare function useHotReloadKey(): string;
+/**
+ * Utility for setting up hot reload in subs modules
+ * Returns dispose and accept functions for HMR
+ */
+declare function setupSubsHotReload(): {
+    dispose: () => void;
+    accept: (newModule?: any) => void;
+};
+/**
+ * React component that wraps children with hot reload support
+ * Uses a key that changes when subs are hot reloaded to force re-mount
+ */
+declare function HotReloadWrapper({ children }: {
+    children: React.ReactNode;
+}): React.DetailedReactHTMLElement<{
+    key: string;
+    style: {
+        display: "contents";
+    };
+}, HTMLElement>;
+
 type TraceID = number;
 interface TraceOpts {
     operation?: string;
@@ -147,4 +199,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, Id, Interceptor, SubVector, clearGlobalInterceptors, debounceAndDispatch, defaultErrorHandler, disableTracing, dispatch, enableTracePrint, enableTracing, getGlobalInterceptors, initAppDb, isDebugEnabled, regCoeffect, regEffect, regEvent, regEventErrorHandler, regGlobalInterceptor, regSub, registerTraceCb, setDebugEnabled, throttleAndDispatch, useSubscription };
+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, getGlobalInterceptors, initAppDb, isDebugEnabled, regCoeffect, regEffect, regEvent, regEventErrorHandler, regGlobalInterceptor, regSub, registerHotReloadCallback, registerTraceCb, setDebugEnabled, setupSubsHotReload, throttleAndDispatch, triggerHotReload, useHotReload, useHotReloadKey, useSubscription };

package/dist/{index.js → index.mjs}

@@ -41,6 +41,25 @@ function registerHandler(kind, id, handlerFn) {
   kindToIdToHandler[kind][id] = handlerFn;
   return handlerFn;
 }
+function clearHandlers(kind, id) {
+  if (kind == null) {
+    for (const k in kindToIdToHandler) {
+      kindToIdToHandler[k] = {};
+    }
+  } else if (id == null) {
+    if (!(kind in kindToIdToHandler)) {
+      consoleLog("error", `[reflex] Unknown kind: ${kind}`);
+      return;
+    }
+    kindToIdToHandler[kind] = {};
+  } else {
+    if (kindToIdToHandler[kind][id]) {
+      delete kindToIdToHandler[kind][id];
+    } else {
+      consoleLog("warn", `[reflex] can't clear ${kind} handler for ${id}. Handler not found.`);
+    }
+  }
+}
 function hasHandler(kind, id) {
   return !!kindToIdToHandler[kind][id];
 }
@@ -51,6 +70,18 @@ function getReaction(key) {
 function setReaction(key, reaction) {
   reactionsRegistry.set(key, reaction);
 }
+function clearReactions(id) {
+  if (id == null) {
+    reactionsRegistry.clear();
+  } else {
+    reactionsRegistry.delete(id);
+  }
+}
+function clearSubs() {
+  clearReactions();
+  clearHandlers("sub");
+  clearHandlers("subDeps");
+}
 var interceptorsRegistry = /* @__PURE__ */ new Map();
 function getInterceptors(eventId) {
   return interceptorsRegistry.get(eventId) || [];
@@ -1017,8 +1048,84 @@ function useSubscription(subVector, componentName = "react component") {
   }, []);
   return val;
 }
+
+// src/hot-reload.ts
+import React, { useState as useState2, useEffect as useEffect2, useRef } from "react";
+var hotReloadCallbacks = /* @__PURE__ */ new Set();
+function registerHotReloadCallback(callback) {
+  hotReloadCallbacks.add(callback);
+  return () => {
+    hotReloadCallbacks.delete(callback);
+  };
+}
+function triggerHotReload() {
+  consoleLog("log", "[reflex] Triggering hot reload callbacks");
+  for (const callback of hotReloadCallbacks) {
+    try {
+      callback();
+    } catch (error) {
+      consoleLog("error", "[reflex] Error in hot reload callback:", error);
+    }
+  }
+}
+function clearHotReloadCallbacks() {
+  hotReloadCallbacks.clear();
+}
+function useHotReload() {
+  const [, forceUpdate] = useState2({});
+  const callbackRef = useRef(null);
+  useEffect2(() => {
+    const triggerUpdate = () => {
+      forceUpdate({});
+    };
+    callbackRef.current = triggerUpdate;
+    const unregister = registerHotReloadCallback(triggerUpdate);
+    return () => {
+      unregister();
+      callbackRef.current = null;
+    };
+  }, []);
+}
+var keyCounter = 0;
+function useHotReloadKey() {
+  const [key, setKey] = useState2(() => `hot-reload-${++keyCounter}`);
+  const callbackRef = useRef(null);
+  useEffect2(() => {
+    const updateKey = () => {
+      setKey(`hot-reload-${++keyCounter}`);
+    };
+    callbackRef.current = updateKey;
+    const unregister = registerHotReloadCallback(updateKey);
+    return () => {
+      unregister();
+      callbackRef.current = null;
+    };
+  }, []);
+  return key;
+}
+function setupSubsHotReload() {
+  const dispose = () => {
+    clearSubs();
+  };
+  const accept = (newModule) => {
+    if (newModule) {
+      consoleLog("log", "[reflex] Hot reloading subs module");
+      triggerHotReload();
+    }
+  };
+  return { dispose, accept };
+}
+function HotReloadWrapper({ children }) {
+  const key = useHotReloadKey();
+  return React.createElement("div", { key, style: { display: "contents" } }, children);
+}
 export {
+  HotReloadWrapper,
   clearGlobalInterceptors,
+  clearHandlers,
+  clearHotReloadCallbacks,
+  clearReactions,
+  clearSubs,
   debounceAndDispatch,
   defaultErrorHandler,
   disableTracing,
@@ -1034,8 +1141,13 @@ export {
   regEventErrorHandler,
   regGlobalInterceptor,
   regSub,
+  registerHotReloadCallback,
   registerTraceCb,
   setDebugEnabled,
+  setupSubsHotReload,
   throttleAndDispatch,
+  triggerHotReload,
+  useHotReload,
+  useHotReloadKey,
   useSubscription
 };

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@flexsurfer/reflex",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flexsurfer/reflex.git"
+  },
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -16,8 +20,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --dts --format esm,cjs --clean",
-    "dev": "tsup src/index.ts --watch --dts --format esm,cjs",
+    "build": "tsup",
+    "dev": "tsup --watch",
     "test": "jest --passWithNoTests",
     "test:clean": "jest --passWithNoTests --silent",
     "test:watch": "jest --passWithNoTests --watch"