{"id":29710701,"url":"https://github.com/flexsurfer/reflex","last_synced_at":"2025-07-23T21:39:32.678Z","repository":{"id":303055461,"uuid":"1014250574","full_name":"flexsurfer/reflex","owner":"flexsurfer","description":"A reactive, functional state management library that brings the elegance and power of ClojureScript's re-frame to JavaScript and React/RN applications.","archived":false,"fork":false,"pushed_at":"2025-07-21T08:53:03.000Z","size":478,"stargazers_count":14,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-21T09:06:17.981Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flexsurfer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-05T10:45:39.000Z","updated_at":"2025-07-21T08:53:06.000Z","dependencies_parsed_at":"2025-07-05T12:31:53.830Z","dependency_job_id":"29ba9ad5-6981-4aad-b517-c2321b972526","html_url":"https://github.com/flexsurfer/reflex","commit_stats":null,"previous_names":["flexsurfer/reflex"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/flexsurfer/reflex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flexsurfer%2Freflex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flexsurfer%2Freflex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flexsurfer%2Freflex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flexsurfer%2Freflex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flexsurfer","download_url":"https://codeload.github.com/flexsurfer/reflex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flexsurfer%2Freflex/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266753992,"owners_count":23979146,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-23T21:39:26.089Z","updated_at":"2025-07-23T21:39:32.663Z","avatar_url":"https://github.com/flexsurfer.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"reflex-logo-300kb.png\" alt=\"Reflex Logo\" width=\"200\" /\u003e\n\u003c/div\u003e\n\n**re-frame for the JavaScript world**\n\nA reactive, functional state management library that brings the elegance and power of ClojureScript's re-frame to JavaScript and React/RN applications.\n\n\u003e ⚠️ **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.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![NPM Version](https://img.shields.io/npm/v/%40flexsurfer%2Freflex)](https://www.npmjs.com/package/@flexsurfer/reflex)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/flexsurfer/reflex/pulls)\n\n📚 **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.\n\n## ✨ Why Reflex?\n\nAfter many years of building applications with re-frame in the ClojureScript world, I wanted to bring the same architectural elegance to the JavaScript/TypeScript ecosystem. Reflex is not just another state management library—it's a battle-tested pattern that promotes:\n\n🎯 **Predictable State Management** - Unidirectional data flow with pure functions  \n🧩 **Composable Architecture** - Build complex apps from simple, reusable pieces  \n🔄 **Reactive Subscriptions** - UI automatically updates when state changes  \n⚡ **Interceptor Pattern** - Powerful middleware system for cross-cutting concerns  \n🛡️ **Type Safety** - Full TypeScript support with excellent IDE experience  \n🧪 **Testability** - Pure functions make testing straightforward and reliable  \n\n## 🚀 Quick Start\n\n```bash\nnpm install @flexsurfer/reflex\n```\n\n### Basic Example\n\n```typescript\nimport { \n  initAppDb, \n  regEvent, \n  regSub, \n  dispatch, \n  useSubscription \n} from '@flexsurfer/reflex';\n\n// Initialize your app database\ninitAppDb({ counter: 0 });\n\n// Register events (state transitions)\nregEvent('increment', ({ draftDb }) =\u003e {\n  draftDb.counter += 1; \n});\n\nregEvent('decrement', ({ draftDb }) =\u003e {\n   draftDb.counter -= 1; \n});\n\n// Register subscriptions (reactive queries)\nregSub('counter');\n\n// React component\nconst Counter = () =\u003e {\n  const counter = useSubscription\u003cnumber\u003e(['counter']);\n  \n  return (\n    \u003cdiv\u003e\n      \u003ch1\u003eCount: {counter}\u003c/h1\u003e\n      \u003cbutton onClick={() =\u003e dispatch(['increment'])}\u003e+\u003c/button\u003e\n      \u003cbutton onClick={() =\u003e dispatch(['decrement'])}\u003e-\u003c/button\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n## 🏗️ Core Concepts\n\n### Events \u0026 Effects\n\nEvents define state transitions and may declare side effects:\n\n```typescript\n// Simple state update\nregEvent('set-name', ({ draftDb }, name) =\u003e {\n   draftDb.user.name = name;\n});\n\n// Dispatch with parameters\ndispatch(['set-name', 'John Doe']);\n\n// Event with side effects\nregEvent('save-user', ({ draftDb }, user) =\u003e {\n  draftDb.saving = true; \n  return [\n    ['http', {\n      method: 'POST',\n      url: '/api/users',\n      body: user,\n      onSuccess: ['save-user-success'],\n      onFailure: ['save-user-error']\n    }]\n  ]\n});\n\n// Dispatch with parameters\ndispatch(['save-user', { id: 1, name: 'John', email: 'john@example.com' }]);\n```\n\n### Subscriptions\n\nCreate reactive queries that automatically update your UI:\n\n```typescript\nregSub('user');\nregSub('display-prefix');\nregSub('user-name', (user) =\u003e user.name, () =\u003e [['user']]);\n\n// Computed subscription with dependencies\nregSub('user-display-name',\n  (name, prefix) =\u003e `${prefix}: ${name}`,\n  () =\u003e [['user-name'], ['display-prefix']]\n);\n\n// Parameterized subscription\nregSub(\n  'todo-by-id',\n  (todos, id) =\u003e todos.find(todo =\u003e todo.id === id),\n  () =\u003e [['todos']]\n);\n\nregSub(\n  'todo-text-by-id',\n  (todo, _id) =\u003e todo.text,\n  (id) =\u003e [['todo-by-id' id]]\n);\n\n// Use in React components\nfunction UserProfile() {\n  const name = useSubscription\u003cstring\u003e(['user-display-name']);\n  const todo = useSubscription(['todo-by-id', 123])\n  const todoText = useSubscription(['todo-text-by-id', 123]);\n  \n  return \u003cdiv\u003e{name}\u003c/div\u003e;\n}\n```\n\n### Effects \u0026 Co-effects\n\nHandle side effects in a controlled, testable way:\n\n```typescript\nimport { \n  regEffect,\n  regCoeffect\n} from '@flexsurfer/reflex';\n\n// Register custom effects\nregEffect('local-storage', (payload) =\u003e {\n  localStorage.setItem(payload.key, JSON.stringify(payload.value));\n});\n\n// Use in events\nregEvent('save-to-storage', (_coeffects, data) =\u003e {\n  return [['local-storage', { key: 'app-data', value: data }]]\n});\n\n// Dispatch with data parameter\ndispatch(['save-to-storage', { user: 'John', preferences: { theme: 'dark' } }]);\n\n// Register co-effects\nregCoeffect('timestamp', (coeffects) =\u003e {\n  coeffects.timestamp = Date.now();\n  return coeffects;\n});\n\nregCoeffect('random', (coeffects) =\u003e {\n  coeffects.random = Math.random();\n  return coeffects;\n});\n\n// Use co-effect in events\nregEvent('log-action', \n  ({ draftDb, timestamp, random }, action) =\u003e {\n    draftDb.actionLog.push({\n      action,\n      timestamp: timestamp,\n      id: random.toString(36)\n    });\n  },\n  [['timestamp'], ['random']] \n);\n\n// Dispatch with action parameter\ndispatch(['log-action', 'some-action']);\n```\n\n### Interceptors\n\nCompose functionality with interceptors:\n\n```typescript\nconst loggingInterceptor = {\n  id: 'logging',\n  before: (context) =\u003e {\n    console.log('Event:', context.coeffects.event);\n    return context;\n  },\n  after: (context) =\u003e {\n    console.log('Updated DB:', context.coeffects.newDb);\n    return context;\n  }\n};\n\nregEvent('my-event', handler, [loggingInterceptor]);\n```\n\n## 🎯 Why Re-frame Pattern?\n\nThe re-frame pattern has proven itself in production applications over many years:\n\n- **Separation of Concerns**: Clear boundaries between events, effects, and subscriptions\n- **Time Travel Debugging**: Every state change is an event that can be replayed\n- **Testability**: Pure functions make unit testing straightforward\n- **Composability**: Build complex features from simple, reusable parts\n- **Maintainability**: Code becomes self-documenting and easy to reason about\n\n## 🔄 Migration from Other Libraries\n\n### From Redux\n\n```typescript\n// Redux style\nconst counterSlice = createSlice({\n  name: 'count',\n  initialState: { value: 0 },\n  reducers: {\n    increment: (state) =\u003e { state.value += 1; }\n  }\n});\n\n// Reflex style\ninitAppDb({ count: 0 });\nregEvent('increment', ({ draftDb }) =\u003e {\n   draftDb.count += 1; \n});\nregSub('count');\n```\n\n### From Zustand\n\n```typescript\n// Zustand style\nconst useStore = create((set) =\u003e ({\n  count: 0,\n  increment: () =\u003e set((state) =\u003e ({ count: state.count + 1 }))\n}));\n\n// Reflex style\ninitAppDb({ count: 0 });\nregEvent('increment', ({ draftDb }) =\u003e {\n   draftDb.count += 1; \n});\nregSub('count');\n```\n\n## 📚 Learn More\n\n- [re-frame Documentation](https://day8.github.io/re-frame/re-frame/) - The original and comprehensive guide to understanding the philosophy and patterns\n- Step-by-Step Tutorial - TBD\n- API Reference - TBD\n- Examples\n  - [TodoMVC](https://github.com/flexsurfer/reflex/tree/main/examples/todomvc) - Classic todo app implementation showcasing core reflex patterns\n  - [Einbürgerungstest](https://github.com/flexsurfer/einburgerungstest/) - German citizenship test app built with reflex ([Live Demo](https://www.ebtest.org/))\n- Best Practices - TBD\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request or file an issue with questions, suggestions, or ideas.\n\n## 📄 License\n\nMIT © [flexsurfer](https://github.com/flexsurfer)\n\n---\n\n*Bringing the wisdom of ClojureScript's re-frame to the JavaScript world. Now your React applications can enjoy the same architectural benefits that have made re-frame a joy to work with for over a decade.* ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflexsurfer%2Freflex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflexsurfer%2Freflex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflexsurfer%2Freflex/lists"}