Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/the-dr-lazy/deox

Functional Type-safe Flux Standard Utilities
https://github.com/the-dr-lazy/deox

action action-creator deox flux ngrx reducer redux typesafe-actions typescript

Last synced: 5 days ago
JSON representation

Functional Type-safe Flux Standard Utilities

Host: GitHub
URL: https://github.com/the-dr-lazy/deox
Owner: the-dr-lazy
License: mit
Created: 2019-01-13T11:43:47.000Z (almost 6 years ago)
Default Branch: master
Last Pushed: 2022-12-12T10:34:08.000Z (about 2 years ago)
Last Synced: 2024-12-09T02:23:34.183Z (15 days ago)
Topics: action, action-creator, deox, flux, ngrx, reducer, redux, typesafe-actions, typescript
Language: TypeScript
Homepage: https://deox.js.org
Size: 4.04 MB
Stars: 206
Watchers: 5
Forks: 12
Open Issues: 19
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

        
Deox


Functional type-safe Flux standard utilities




  

    

  

  

    

  

  

    

  

  

    

  

  

    

  

  

    

  



The only completely functional **type-safe** approach to Flux that its main goals are to diminish types **verbosity**, **repetition** and **complexity** without losing any type information (type-safe alternative of [redux-actions](https://github.com/redux-utilities/redux-actions)).

Behold, the art of Deox:



  



## Highlights

-   **Minimalist** (almost no import cost) - checkout [Bundle Phobia](https://bundlephobia.com/result?p=deox@latest).

-   **Simple** - focused on self-declarative API.

-   **Secure** - complete test-suits for all of the edge and corners.

## Motivation

The most common complaint about Flux is how it makes you write a lot of boilerplate.

Also, existing solutions like redux-actions or redux-starter-kit are not type-safe by the idea (although there are some other ideas with classes 😱).

So, this is where Deox takes place to **make maintenance of Flux architecture simpler and more readable** by sticking to **functional programming paradigm**.

## Installation

You can install Deox package by running:

```bash

# YARN

yarn add deox

# NPM

npm install deox

```

> **Typescript tip**: notice that Deox internally uses some ES2015 type definitions to represent better developer experience.

> So if you are using [`Typescript`](https://github.com/Microsoft/TypeScript) and targeting `es5`, be sure `es2015` lib has been added in tsconfig.json:

```json

{

  "compilerOptions": {

    ...

    "target": "es5",

    "lib": ["es2015"]

  }

}

```

The Deox NPM package contains a [CommonJS](http://www.commonjs.org/specs/modules/1.0/) build that can be use with [Node.js](https://nodejs.org/en/) or module bundlers (e.g. [Rollup](https://github.com/rollup/rollup), [Webpack](https://github.com/webpack/webpack), etc.). it also includes an [ESM](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) build that works well with [tree-shaking](https://webpack.js.org/guides/tree-shaking/).

If you don't use module bundler, it's also fine. The Deox NPM package also includes a production minified [UMD](https://github.com/umdjs/umd) build that makes Deox available as global variable called `window.Deox`; you can add it simply to your page via following script tag:

```html

```

## Usage

```ts

import { createActionCreator, createReducer } from 'deox'

const increment = createActionCreator('INCREMENT')

const decrement = createActionCreator('DECREMENT')

const reset = createActionCreator('RESET', resolve => (count: number) => resolve(count))

const defaultState = 0

const counterReducer = createReducer(defaultState, handleAction => [

    handleAction(increment, state => state + 1),

    handleAction(decrement, state => state - 1),

    handleAction(reset, (_state, { payload }) => payload),

])

counterReducer(undefined, increment()) //=> 1

counterReducer(undefined, decrement()) //=> -1

counterReducer(3, reset(0)) //=> 0

```

## Documentation

-   [Introduction](https://deox.js.org)

-   [Getting started](https://deox.js.org/getting-started)

-   [API reference](https://deox.js.org/api-reference)

-   [FAQ](https://deox.js.org/api-reference)

    -   [Using redux-thunk with Deox](https://deox.js.org/faq#using-redux-thunk-with-deox)

    -   [Using redux-saga with Deox](https://deox.js.org/faq#using-redux-saga-with-deox)

    -   [Using redux-observable with Deox](https://deox.js.org/faq#using-redux-observable-with-deox)

## FAQ

### Why not `redux-actions`, `redux-starter-kit` ?

Both `redux-actions` and `redux-starter-kit` are neat and almost similar to each other.

Actually `deox` is similar to those projects in the idea, but not in implementation and promise.

The main goal of `deox` is to use the full power of **type-safety** and **type inferring** in typescript.

If you have some experience with those libraries, the following piece of code should be familiar for you:

```ts

type Actions

  = ReturnType

  | ReturnType

  | ReturnType

const todosReducer = createReducer(...)

```

This is horrible; Why define a type like actions that a reducer can handle?! It's completely obvious which actions a reducer handles.

On another hand there is a big problem with the pattern that `redux-actions` and `redux-starter-kit` follows. it's lack of correct type for action handler:

```ts

const todosReducer = createReducer(defaultState, {

  [addTodo]: (state, action) => {...}, // action: Actions

  [removeTodo]: (state, action) => {...}, // action: Actions

  [editTodo]: (state, action) => {...}, // action: Actions

})

```

Type of action parameter in `addTodo` action handler is overall `Actions` type. It's inaccurate!

And this is where Deox comes in action and practice:

```ts

const todosReducer = createReducer(defaultState, handleAction => [

  handleAction(addTodo, (state, action) => {...}), // action: AddTodoAction

  handleAction(removeTodo, (state, action) => {...}), // action: RemoveTodoAction

  handleAction(editTodo, (state, action) => {...}) // action: EditTodoAction

])

```

That's it. Thanks to typescript type inferring **there is no type verbosity** at all. You can be sure `todos` reducer have the proper type of state and actions that it can handle.

And every action handler's type is just what it should be. It's completely safe and correct!

### What's the difference with `typesafe-actions` ?

The `typesafe-actions` is a great project that Deox carries huge inspiration from that.

But `typesafe-actions` doesn't have any plan for a complete set of utilities (specially reducers); **It's all about actions and action creators**.

## Versioning

Deox uses [Semantic Versioning 2.0.0](https://semver.org/)

## Contributing

Please read through our [contributing guidelines](CONTRIBUTING.md).

## Inspiration

-   [redux-actions](https://github.com/redux-utilities/redux-actions) - Flux Standard Action utilities for Redux

-   [typesafe-actions](https://github.com/piotrwitek/typesafe-actions) - Typesafe Action Creators for Redux / Flux Architectures (in TypeScript)

## License

Deox is released under [MIT license](LICENSE).