{"id":13395405,"url":"https://github.com/hydux/hydux","last_synced_at":"2025-04-09T18:16:42.628Z","repository":{"id":57269864,"uuid":"113385501","full_name":"hydux/hydux","owner":"hydux","description":"A light-weight type-safe Elm-like alternative for Redux ecosystem, inspired by hyperapp and Elmish","archived":false,"fork":false,"pushed_at":"2019-02-01T06:13:06.000Z","size":3742,"stargazers_count":219,"open_issues_count":2,"forks_count":7,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-09T18:16:37.634Z","etag":null,"topics":["2kb","elm-architecture","framework","hydux","hyperapp","preact","react","router","ssr","state-management","type-safe","typescript","virtual-dom"],"latest_commit_sha":null,"homepage":"","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/hydux.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-07T01:12:43.000Z","updated_at":"2025-03-19T09:16:32.000Z","dependencies_parsed_at":"2022-08-25T02:12:46.469Z","dependency_job_id":null,"html_url":"https://github.com/hydux/hydux","commit_stats":null,"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydux%2Fhydux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydux%2Fhydux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydux%2Fhydux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydux%2Fhydux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hydux","download_url":"https://codeload.github.com/hydux/hydux/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248085323,"owners_count":21045139,"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","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":["2kb","elm-architecture","framework","hydux","hyperapp","preact","react","router","ssr","state-management","type-safe","typescript","virtual-dom"],"created_at":"2024-07-30T17:01:57.127Z","updated_at":"2025-04-09T18:16:42.596Z","avatar_url":"https://github.com/hydux.png","language":"TypeScript","funding_links":[],"categories":["Uncategorized","TypeScript"],"sub_categories":["Uncategorized"],"readme":"# Hydux\n\n[![Build Status](https://travis-ci.org/hydux/hydux.svg?branch=master)](https://travis-ci.org/hydux/hydux) [![npm](https://img.shields.io/npm/v/hydux.svg)](https://www.npmjs.com/package/hydux) [![npm](https://img.shields.io/npm/dm/hydux.svg)](https://www.npmjs.com/package/hydux) [![Join the chat at https://gitter.im/hydux/hydux](https://badges.gitter.im/hydux/hydux.svg)](https://gitter.im/hydux/hydux?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nA light-weight Elm-like alternative for Redux ecosystem, inspired by [Hyperapp](https://github.com/hyperapp/hyperapp) and [Elmish](https://github.com/fable-elmish/elmish).\n\n## Contents\n\n- [Hydux](#hydux)\n  - [Contents](#contents)\n  - [Features](#features)\n  - [Try it online!](#try-it-online)\n  - [Install](#install)\n  - [React-hooks like dependency injection for state/actions\u003csup style=\"color: red;\"\u003eNew!\u003c/sup\u003e](#react-hooks-like-dependency-injection-for-stateactionssup-style%22color-red%22newsup)\n  - [Quick Example](#quick-example)\n  - [Init with Command](#init-with-command)\n  - [Actions with Command](#actions-with-command)\n  - [Parent-Child Components Communication](#parent-child-components-communication)\n  - [Documentation](#documentation)\n  - [Ecosystem](#ecosystem)\n    - [Libraries](#libraries)\n    - [Samples](#samples)\n  - [Counter App](#counter-app)\n  - [Why](#why)\n  - [License](#license)\n\n## Features\n\n* Elm Architecture, split your whole app with **init**, **state**, **actions**.\n* [hyperapp](https://github.com/hyperapp/hyperapp) compatible API\n* Elm-like [side effect manager](https://github.com/hydux/hydux#actions-with-cmd) and subscribe API\n* Support any vdom library, including react ([official support](https://github.com/hydux/hydux-react))\n* [Router (**Recommended**)](https://github.com/hydux/hydux/tree/master/examples/router)\n* [Official support for react-router](https://github.com/hydux/hydux-react-router)\n* Hot reload (hmr)\n* [Server-Side Rendering(SSR)](https://github.com/hydux/hydux/tree/master/docs/ssr.md)\n* [code splitting](https://github.com/hydux/hydux/tree/master/examples/code-splitting), seamlessly integrated with SSR.\n* logger, persist, [Redux Devtools with time traveling](https://github.com/zalmoxisus/redux-devtools-extension), [ultradom](https://github.com/jorgebucaran/ultradom)(1kb vdom), **\\*\\*All in One\\*\\***, easily setup all these fancy stuff without pain!\n\n![timetravel](media/timetravel.gif)\n\n## [Try it online!](https://codepen.io/zaaack/pen/zPgodL)\n\n## Install\n\n```sh\nyarn add hydux # or npm i hydux\n```\n\n## React-hooks like dependency injection for state/actions\u003csup style=\"color: red;\"\u003eNew!\u003c/sup\u003e\n\nThis is an experimental dependency injection API for actions inspired by react-hooks, totally downward compatible, with this we don't need curring to inject state and actions or manually markup types for the return value any more!\n\n```sh\nyarn add hydux@^v0.5.8\n```\n\n```ts\nimport { inject } from 'hydux'\n\nexport default {\n  init: () =\u003e ({ count: 1 }),\n  actions: {\n    down() {\n      let { state, actions, setState, Cmd } = inject\u003cState, Actions\u003e()\n      setState({ count: state.count - 1 })\n      Cmd.addSub(_ =\u003e _.log('down -1'))\n      actions.up()\n    },\n    up() {\n      let { state, actions } = inject\u003cState, Actions\u003e()\n      return { count: state.count + 1 }\n    },\n    log(msg) {\n      console.log(msg)\n    }\n  },\n  view: (state, actions) =\u003e {\n    return (\n      \u003cdiv\u003e\n        \u003ch1\u003e{state.count}\u003c/h1\u003e\n        \u003cbutton onclick={actions.down}\u003e–\u003c/button\u003e\n        \u003cbutton onclick={actions.up}\u003e+\u003c/button\u003e\n      \u003c/div\u003e\n    )\n  }\n}\n\n```\n\n## Quick Example\n\nLet's say we got a counter, like this.\n\n```js\n// Counter.js\nexport default {\n  init: () =\u003e ({ count: 1 }),\n  actions: {\n    down: () =\u003e state =\u003e ({ count: state.count - 1 }),\n    up: () =\u003e state =\u003e ({ count: state.count + 1 })\n  },\n  view: (state: State, actions: Actions) =\u003e\n    \u003cdiv\u003e\n      \u003ch1\u003e{state.count}\u003c/h1\u003e\n      \u003cbutton onclick={actions.down}\u003e–\u003c/button\u003e\n      \u003cbutton onclick={actions.up}\u003e+\u003c/button\u003e\n    \u003c/div\u003e\n}\n```\n\nThen we can compose it in Elm way, you can easily reuse your components.\n\n```js\nimport _app from 'hydux'\nimport withUltradom, { h, React } from 'hydux/lib/enhancers/ultradom-render'\nimport Counter from './counter'\n\n// use built-in 1kb ultradom to render the view.\nlet app = withUltradom()(_app)\n\nconst actions = {\n  counter1: Counter.actions,\n  counter2: Counter.actions,\n}\n\nconst state = {\n  counter1: Counter.init(),\n  counter2: Counter.init(),\n}\n\nconst view = (\n  state: State,\n  actions: Actions,\n) =\u003e\n    \u003cmain\u003e\n      \u003ch1\u003eCounter1:\u003c/h1\u003e\n      {Counter.view(state.counter1, actions.counter1)}\n      \u003ch1\u003eCounter2:\u003c/h1\u003e\n      {Counter.view(state.counter2, actions.counter2)}\n    \u003c/main\u003e\n\nexport default app({\n  init: () =\u003e state,\n  actions,\n  view,\n})\n```\n\n## Init with Command\n\nYou can init the state of your app via plain object, or with side effects, like fetch remote data.\n\n```ts\nimport * as Hydux from 'hydux'\n\nconst { Cmd } = Hydux\n\nexport function init() {\n  return {\n    state: { // pojo state\n      count: 1,\n    },\n    cmd: Cmd.ofSub( // update your state via side effects.\n      _ =\u003e fetch('https://your.server/init/count') // `_` is the real actions, don't confuse with the plain object `actions` that we created below, calling functions from plain object won't trigger state update!\n        .then(res =\u003e res.json())\n        .then(count =\u003e _.setCount(count))\n    )\n  }\n}\n\nexport const actions = {\n  setCount: n =\u003e (state, actions) =\u003e {\n    return { count: n }\n  }\n}\n\n```\n\nIf we want to init a child component with init command, we need to map it to the sub level via lambda function, just like **type lifting** in Elm.\n```ts\n// App.tsx\nimport { React } from 'hydux-react'\nimport * as Hydux from 'hydux'\nimport * as Counter from 'Counter'\nconst Cmd = Hydux.Cmd\n\nexport const init = () =\u003e {\n  const counter1 = Counter.init()\n  const counter2 = Counter.init()\n  return {\n    state: {\n      counter1: counter1.state,\n      counter2: counter2.state,\n    },\n    cmd: Cmd.batch(\n      Cmd.map((_: Actions) =\u003e _.counter1, counter1.cmd), // Map counter1's init command to parent component\n      Cmd.map((_: Actions) =\u003e _.counter2, counter2.cmd), // Map counter2's init command to parent component\n      Cmd.ofSub(\n        _ =\u003e // some other commands of App\n      )\n    )\n  }\n}\n\nexport const actions = {\n  counter1: Counter.actions,\n  counter2: Counter.actions,\n  // ... other actions\n}\n\nexport const view = (state: State, actions: Actions) =\u003e (\n  \u003cmain\u003e\n    \u003ch1\u003eCounter1:\u003c/h1\u003e\n    {Counter.view(state.counter1, actions.counter1)}\n    \u003ch1\u003eCounter2:\u003c/h1\u003e\n    {Counter.view(state.counter2, actions.counter2)}\n  \u003c/main\u003e\n)\n\nexport type Actions = typeof actions\nexport type State = ReturnType\u003ctypeof init\u003e['state']\n```\n\nThis might be too much boilerplate code, but hey, we provide a type-friendly helper function! See:\n\n```ts\n// Combine all sub components's init/actions/views, auto map init commands.\nconst subComps = Hydux.combine({\n  counter1: [Counter, Counter.init()],\n  counter2: [Counter, Counter.init()],\n})\nexport const init2 = () =\u003e {\n  return {\n    state: {\n      ...subComps.state,\n      // other state\n    },\n    cmd: Cmd.batch(\n      subComps.cmd,\n      // other commands\n    )\n  }\n}\n\n\nexport const actions = {\n  ...subComps.actions,\n  // ... other actions\n}\n\nexport const view = (state: State, actions: Actions) =\u003e (\n  \u003cmain\u003e\n    \u003ch1\u003eCounter1:\u003c/h1\u003e\n    {subComps.render('counter1', state, actions)}\n    // euqal to:\n    // {subComps.views.counter1(state.counter1, actions.counter1)}\n    // .render('\u003ckey\u003e', ...) won't not work with custom views that not match `(state, actions) =\u003e any` or `(props) =\u003e any` signature\n    // So we still need `.views.counter1(...args)` in this case.\n    \u003ch1\u003eCounter2:\u003c/h1\u003e\n    {subComps.render('counter2', state, actions)}\n  \u003c/main\u003e\n)\n```\n\n## Actions with Command\n\nThis library also implemented a Elm-like side effects manager, you can simple return a record with state, cmd in your action\ne.g.\n\n```ts\nimport app, { Cmd } from 'hydux'\n\nfunction upLater(n) {\n  return new Promise(resolve =\u003e setTimeout(() =\u003e resolve(n + 10), 1000))\n}\napp({\n  init: () =\u003e ({ count: 1}),\n  actions: {\n    down: () =\u003e state =\u003e ({ count: state.count - 1 }),\n    up: () =\u003e state =\u003e ({ count: state.count + 1 }),\n    upN: n =\u003e state =\u003e ({ count: state.count + n }),\n    upLater: n =\u003e (\n      state,\n      actions/* actions of same level */\n    ) =\u003e ({\n      state, // don't change the state, won't trigger view update\n      cmd: Cmd.ofPromise(\n        upLater /* a function with single parameter and return a promise */,\n        n /* the parameter of the funciton */,\n        actions.upN /* success handler, optional */,\n        console.error /* error handler, optional */ )\n    }),\n    // Short hand of command only\n    upLater2: n =\u003e (\n      state,\n      actions/* actions of same level */\n    ) =\u003e Cmd.ofPromise(\n      upLater /* a function with single parameter and return a promise */,\n      n /* the parameter of the funciton */,\n      actions.upN /* success handler, optional */,\n      console.error /* error handler, optional */\n    ),\n  },\n  view: () =\u003e {/*...*/} ,\n})\n```\n\n## Parent-Child Components Communication\n\nIn Elm, we can intercept child component's message in parent component, because child's update function is called in parent's update function. But how can we do this in hydux?\n\n```js\nimport * as assert from 'assert'\nimport * as Hydux from '../index'\nimport Counter from './counter'\n\nconst { Cmd } = Hydux\n\nexport function init() {\n  return {\n    state: {\n      counter1: Counter.init(),\n      counter2: Counter.init(),\n    }\n  }\n}\nconst actions = {\n  counter2: counter.actions,\n  counter1: counter.actions\n}\nHydux.overrideAction(\n  actions,\n  _ =\u003e _.counter1.upN,\n  (n: number) =\u003e (\n      action,\n      ps: State, // parent state (State)\n      pa, // parent actions (Actions)\n      // s: State['counter1'], // child state\n      // a: Actions['counter1'], // child actions\n  ) =\u003e {\n    const { state, cmd } = action(n + 1)\n    assert.equal(state.count, ps.counter1.count + n + 1, 'call child action work')\n    return {\n      state,\n      cmd: Cmd.batch(\n        cmd,\n        Cmd.ofFn(\n          () =\u003e pa.counter2.up()\n        )\n      )\n    }\n  }\n)\ntype State = ReturnType\u003ctypeof init\u003e['state']\ntype Actions = typeof actions\nlet ctx = Hydux.app\u003cState, Actions\u003e({\n  init: () =\u003e initState,\n  actions,\n  view: noop,\n  onRender: noop\n})\n\n```\n\n## Documentation\n\n* [API tutorial with examples](https://github.com/hydux/hydux/tree/master/docs/api.md)\n* [Generated API Reference](https://hydux.github.io/hydux/api)\n* [Server-Side Rendering(SSR) Tutorial](https://github.com/hydux/hydux/tree/master/docs/ssr.md)\n\n## Ecosystem\n\n### Libraries\n\n* [hydux-react](https://github.com/hydux/hydux-react): Hydux's react integration\n* [hydux-preact](https://github.com/hydux/hydux-preact): Hydux's [preact](https://github.com/developit/preact) integration\n* [hydux-react-router](https://github.com/hydux/hydux-react-router): Hydux's react-router integration\n* [hydux-mutator](https://github.com/hydux/hydux-mutator): A statically-typed immutable update help package, which also contains immutable collections.\n* [hydux-transitions](https://github.com/hydux/hydux-transitions): A css transition library inspired by [animajs](http://animejs.com/)'s timeline, follow **The Elm Architecture**.\n* [hydux-data](https://github.com/hydux/hydux-data): Statically-typed data-driven development for hydux, in the Elm way. Inspired by apollo-client.\n* [hydux-pixi](https://github.com/hydux/hydux-pixi): High performance [pixi.js](https://github.com/pixijs/pixi.js) renderer for Hydux.\n* [hydux code snippets for vscode (TS)](https://github.com/hydux/hydux/tree/master/docs/hydux.code-snippets) Best practice for using hydux + typescript without boilerplate code.\n\n### Samples\n\n* [samples-antd](https://github.com/hydux/samples-antd): Admin sample in hydux.\n\n## Counter App\n\n```sh\ngit clone https://github.com/hydux/hydux.git\ncd hydux\nyarn # or npm i\ncd examples/counter\nyarn # or npm i\nnpm start\n```\n\nNow open \u003chttp://localhost:8080\u003e and hack!\n\n## Why\n\nAfter trying [Fable](https://fable.io) + [Elmish](https://github.com/fable-elmish/elmish) for several month, I need to write a small web App in my company, for many reasons I cannot choose some fancy stuff like [Fable](https://fable.io) + [Elmish](https://github.com/fable-elmish/elmish), simply speaking, I need to use the mainstream JS stack but don't want to bear Redux's cumbersome, complex toolchain, etc anymore.\n\nAfter some digging around, hyperapp looks really good to me, but I quickly find out it doesn't work with React, and many libraries don't work with the newest API. So I create this to support ****different**** vdom libraries, like React([official support](https://github.io/hydux/hydux-react)), [ultradom](https://github.com/jorgebucaran/ultradom)([built-in](https://github.com/hydux/hydux/blob/master/src/enhancers/ultradom-render.ts)), Preact, [inferno](https://github.com/infernojs/inferno) or what ever you want, just need to write a simple enhancer!\n\nAlso, to avoid breaking change, we have ****built-in**** support for HMR, logger, persist, [Redux Devtools](https://github.com/zalmoxisus/redux-devtools-extension), you know you want it!\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhydux%2Fhydux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhydux%2Fhydux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhydux%2Fhydux/lists"}