yanick/updux
1
0
Fork 0
Code Issues 6 Pull Requests Projects Releases 10 Wiki Activity

feat: add support for subscriptions

Browse Source
This commit is contained in:
Yanick Champoux 2020-06-19 19:29:12 -04:00
parent 86dd272603
commit 9c45ee7efc
6 changed files with 964 additions and 752 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
README.md
View File

@ -1,4 +1,3 @@
# What's Updux?
So, I'm a fan of [Redux](https://redux.js.org). Two days ago I discovered
@ -16,17 +15,16 @@ is the fun in that? And I'm also having a strong love for
All that to say, say hello to `Updux`. Heavily inspired by `rematch`, but twisted
to work with `updeep` and to fit my peculiar needs. It offers features such as
* Mimic the way VueX has mutations (reducer reactions to specific actions) and
- Mimic the way VueX has mutations (reducer reactions to specific actions) and
effects (middleware reacting to actions that can be asynchronous and/or
have side-effects), so everything pertaining to a store are all defined
in the space place.
* Automatically gather all actions used by the updux's effects and mutations,
- Automatically gather all actions used by the updux's effects and mutations,
and makes then accessible as attributes to the `dispatch` object of the
store.
* Mutations have a signature that is friendly to Updux and Immer.
* Also, the mutation signature auto-unwrap the payload of the actions for you.
* TypeScript types.
- Mutations have a signature that is friendly to Updux and Immer.
- Also, the mutation signature auto-unwrap the payload of the actions for you.
- TypeScript types.
Fair warning: this package is still very new, probably very buggy,
definitively very badly documented, and very subject to changes. Caveat
@ -78,6 +76,8 @@ store.dispatch.inc(3);
# Description
Full documentation can be [found here](https://yanick.github.io/updux/).
Right now the best way to understand the whole thing is to go
through the [tutorial](https://yanick.github.io/updux/#/tutorial)
## Exporting upduxes
@ -94,7 +94,6 @@ const updux = new Updux({ ... });
export default updux;
```
Then you can use them as subduxes like this:
```
@ -196,7 +195,6 @@ const updux = new Updux({
Converting it to Immer would look like:
```
import Updux from 'updux';
import { produce } from 'Immer';
@ -213,7 +211,6 @@ const updux = new Updux({
But since typing `produce` over and over is no fun, `groomMutations`
can be used to wrap all mutations with it:
```
import Updux from 'updux';
import { produce } from 'Immer';
@ -227,6 +224,3 @@ const updux = new Updux({
});
```

52
docs/tutorial.md
View File

@ -101,7 +101,6 @@ For TypeScript projects I recommend declaring the actions as part of the
configuration passed to the constructors, as it makes them accessible to the class
at compile-time, and allows Updux to auto-add them to its aggregated `actions` type.
```
const todosUpdux = new Updux({
actions: {
@ -210,7 +209,6 @@ todosUpdux.addMutation( '*', (payload,action) => state => {
});
```
## Effects
In addition to mutations, Updux also provides action-specific middleware, here
@ -498,7 +496,7 @@ todosUpdux.addMutation( add_todo_with_id, payload =>
export default updux.asDux;
```
Note the special '*' subdux key used here. This
Note the special '\*' subdux key used here. This
allows the updux to map every item present in its
state to a `todo` updux. See [this recipe](/recipes?id=mapping-a-mutation-to-all-values-of-a-state) for details.
We could also have written the updux as:
@ -519,11 +517,9 @@ const updux = new Updux({
```
Note how we are using the `upreducer` accessor in the first case (which yields
a reducer for the dux using the signature `(payload,action) => state =>
new_state`) and `reducer` in the second case (which yield an equivalent
a reducer for the dux using the signature `(payload,action) => state => new_state`) and `reducer` in the second case (which yield an equivalent
reducer using the classic signature `(state,action) => new_state`).
### Main store
```
@ -573,6 +569,50 @@ at the main level is actually defined as:
const getNextId = state => next_id.selectors.getNextId(state.next_id);
```
## Subscriptions
Subscriptions can be added by default to a updux store via the initial config
or the method `addSubscription`. The signature of a subscription is:
```
(store) => (state,unsubscribe) => {
...
}
```
Subscriptions registered for an updux and its subduxes are automatically
subscribed to the store when calling `createStore`.
The `state` passed to the subscriptions of the subduxes is the local state.
Also, all subscriptions are wrapped such that they are called only if the
local `state` changed since their last invocation.
Example:
```
const set_nbr_todos = action('set_nbr_todos', payload() );
const todos = dux({
initial: [],
subscriptions: [
({dispatch}) => todos => dispatch(set_nbr_todos(todos.length))
],
});
const myDux = dux({
initial: {
nbr_todos: 0
},
subduxes: {
todos,
},
mutations: [
[ set_nbr_todos, nbr_todos => u({nbr_todos}) ]
]
})
```
## Exporting upduxes
As a general rule, don't directly export your upduxes, but rather use the accessor `asDux`.

4
package.json
View File

@ -43,7 +43,9 @@
"scripts": {
"docsify:serve": "docsify serve docs",
"build": "tsc",
"test": "tap src/**test.ts"
"test": "tap src/**test.ts",
"lint": "prettier -c --",
"lint:fix": "prettier --write --"
},
"version": "2.0.0",
"repository": {

107
src/subscriptions.test.ts Normal file
View File

@ -0,0 +1,107 @@
import tap from 'tap';
import Updux from '.';
import { action, payload } from 'ts-action';
import u from 'updeep';
const inc = action('inc');
const set_double = action('set_double', payload<number>());
const dux = new Updux({
initial: {
x: 0,
double: 0,
},
actions: {
inc,
},
mutations: [
[inc, payload => u({ x: x => x + 1 })],
[set_double, double => u({ double })],
],
});
dux.addSubscription(store => (state, unsubscribe) => {
if (state.x > 2) return unsubscribe();
store.dispatch(set_double(state.x * 2));
});
const store = dux.createStore();
store.dispatch(inc());
tap.same(store.getState(), { x: 1, double: 2 });
store.dispatch(inc());
store.dispatch(inc());
tap.same(store.getState(), { x: 3, double: 4 }, 'we unsubscribed');
tap.test('subduxes subscriptions', async t => {
const inc_top = action('inc_top');
const inc_bar = action('inc_bar');
const transform_bar = action('transform_bar', payload());
const bar = new Updux({
initial: 'a',
mutations: [
[inc_bar, () => state => state + 'a'],
[transform_bar, outcome => () => outcome],
],
subscriptions: [
store => (state, unsubscribe) => {
console.log({ state });
if (state.length <= 2) return;
unsubscribe();
store.dispatch(transform_bar('look at ' + state));
},
],
});
const dux = new Updux({
initial: {
count: 0,
},
subduxes: {
bar: bar.asDux,
},
mutations: [[inc_top, () => u({ count: count => count + 1 })]],
effects: [
[
'*',
() => next => action => {
console.log('before ', action.type);
next(action);
console.log({ action });
},
],
],
subscriptions: [
store => {
let previous: any;
return ({ count }) => {
if (count !== previous) {
previous = count;
store.dispatch(inc_bar());
}
};
},
],
});
const store = dux.createStore();
store.dispatch(inc_top());
store.dispatch(inc_top());
t.same(store.getState(), {
count: 2,
bar: 'look at look at aaa',
});
store.dispatch(inc_top());
t.same(store.getState(), {
count: 3,
bar: 'look at look at aaaa',
});
});

577
src/types.ts
View File

@ -37,324 +37,339 @@ export type UnionToIntersection<U> = (U extends any
export type StateOf<D> = D extends { initial: infer I } ? I : unknown;
export type DuxStateCoduxes<C> = C extends Array<infer U> ? UnionToIntersection<StateOf<U>>: unknown
export type DuxStateSubduxes<C> =
C extends { '*': infer I } ? {
[ key: string ]: StateOf<I>,
[ index: number ]: StateOf<I>,
} :
C extends object ? { [ K in keyof C]: StateOf<C[K]>}: unknown;
export type DuxStateCoduxes<C> = C extends Array<infer U>
? UnionToIntersection<StateOf<U>>
: unknown;
export type DuxStateSubduxes<C> = C extends { '*': infer I }
? {
[key: string]: StateOf<I>;
[index: number]: StateOf<I>;
}
: C extends object
? { [K in keyof C]: StateOf<C[K]> }
: unknown;
type DuxStateGlobSub<S> = S extends { '*': infer I } ? StateOf<I> : unknown;
type LocalDuxState<S> = S extends never[] ? unknown[] : S;
/** @ignore */
type AggDuxState2<L,S,C> = (
L extends never[] ? Array<DuxStateGlobSub<S>> : L & DuxStateSubduxes<S> ) & DuxStateCoduxes<C>;
type AggDuxState2<L, S, C> = (L extends never[]
? Array<DuxStateGlobSub<S>>
: L & DuxStateSubduxes<S>) &
DuxStateCoduxes<C>;
/** @ignore */
export type AggDuxState<O,S extends UpduxConfig> = unknown extends O ?
AggDuxState2<S['initial'],S['subduxes'],S['coduxes']> : O
export type AggDuxState<O, S extends UpduxConfig> = unknown extends O
? AggDuxState2<S['initial'], S['subduxes'], S['coduxes']>
: O;
type SelectorsOf<C> = C extends { selectors: infer S } ? S : unknown;
/** @ignore */
export type DuxSelectorsSubduxes<C> = C extends object ? UnionToIntersection<SelectorsOf<C[keyof C]>> : unknown;
export type DuxSelectorsSubduxes<C> = C extends object
? UnionToIntersection<SelectorsOf<C[keyof C]>>
: unknown;
/** @ignore */
export type DuxSelectorsCoduxes<C> = C extends Array<infer U> ? UnionToIntersection<SelectorsOf<U>> : unknown;
export type DuxSelectorsCoduxes<C> = C extends Array<infer U>
? UnionToIntersection<SelectorsOf<U>>
: unknown;
type MaybeReturnType<X> = X extends (...args: any) => any ? ReturnType<X> : unknown;
type MaybeReturnType<X> = X extends (...args: any) => any
? ReturnType<X>
: unknown;
type RebaseSelector<S,X> = {
[ K in keyof X]: (state: S) => MaybeReturnType< X[K] >
}
type RebaseSelector<S, X> = {
[K in keyof X]: (state: S) => MaybeReturnType<X[K]>;
};
type ActionsOf<C> = C extends { actions: infer A } ? A : {};
type DuxActionsSubduxes<C> = C extends object ? ActionsOf<C[keyof C]> : unknown;
export type DuxActionsCoduxes<C> = C extends Array<infer I> ? UnionToIntersection<ActionsOf<I>> : {};
export type DuxActionsCoduxes<C> = C extends Array<infer I>
? UnionToIntersection<ActionsOf<I>>
: {};
type ItemsOf<C> = C extends object? C[keyof C] : unknown
type ItemsOf<C> = C extends object ? C[keyof C] : unknown;
export type DuxActions<A,C extends UpduxConfig> = A extends object ? A: (
UnionToIntersection<ActionsOf<C|ItemsOf<C['subduxes']>|ItemsOf<C['coduxes']>>>
);
export type DuxActions<A, C extends UpduxConfig> = A extends object
? A
: UnionToIntersection<
ActionsOf<C | ItemsOf<C['subduxes']> | ItemsOf<C['coduxes']>>
>;
export type DuxSelectors<S,X,C extends UpduxConfig> = unknown extends X ? (
RebaseSelector<S,
C['selectors'] & DuxSelectorsCoduxes<C['coduxes']> &
DuxSelectorsSubduxes<C['subduxes']> >
): X
export type DuxSelectors<S, X, C extends UpduxConfig> = unknown extends X
? RebaseSelector<
S,
C['selectors'] &
DuxSelectorsCoduxes<C['coduxes']> &
DuxSelectorsSubduxes<C['subduxes']>
>
: X;
export type Dux<
S = unknown,
A = unknown,
X = unknown,
C = unknown,
> = {
subduxes: Dictionary<Dux>,
coduxes: Dux[],
initial: AggDuxState<S,C>,
actions: A,
}
export type Dux<S = unknown, A = unknown, X = unknown, C = unknown> = {
subduxes: Dictionary<Dux>;
coduxes: Dux[];
initial: AggDuxState<S, C>;
actions: A;
subscriptions: Function[];
};
/**
* Configuration object given to Updux's constructor.
*
* #### arguments
*
* ##### initial
*
* Default initial state of the reducer. If applicable, is merged with
* the subduxes initial states, with the parent having precedence.
*
* If not provided, defaults to an empty object.
*
* ##### actions
*
* [Actions](/concepts/Actions) used by the updux.
*
* ```js
* import { dux } from 'updux';
* import { action, payload } from 'ts-action';
*
* const bar = action('BAR', payload<int>());
* const foo = action('FOO');
*
* const myDux = dux({
* actions: {
* bar
* },
* mutations: [
* [ foo, () => state => state ]
* ]
* });
*
* myDux.actions.foo({ x: 1, y: 2 }); // => { type: foo, x:1, y:2 }
* myDux.actions.bar(2); // => { type: bar, payload: 2 }
* ```
*
* New actions used directly in mutations and effects will be added to the
* dux actions -- that is, they will be accessible via `dux.actions` -- but will
* not appear as part of its Typescript type.
*
* ##### selectors
*
* Dictionary of selectors for the current updux. The updux also
* inherit its subduxes' selectors.
*
* The selectors are available via the class' getter.
*
* ##### mutations
*
* mutations: [
* [ action, mutation, isSink ],
* ...
* ]
*
* or
*
* mutations: {
* action: mutation,
* ...
* }
*
* List of mutations for assign to the dux. If you want Typescript goodness, you
* probably want to use `addMutation()` instead.
*
* In its generic array-of-array form,
* each mutation tuple contains: the action, the mutation,
* and boolean indicating if this is a sink mutation.
*
* The action can be an action creator function or a string. If it's a string, it's considered to be the
* action type and a generic `action( actionName, payload() )` creator will be
* generated for it. If an action is not already defined in the `actions`
* parameter, it'll be automatically added.
*
* The pseudo-action type `*` can be used to match any action not explicitly matched by other mutations.
*
* ```js
* const todosUpdux = updux({
* mutations: {
* add: todo => state => [ ...state, todo ],
* done: done_id => u.map( u.if( ({id} => id === done_id), {done: true} ) ),
* '*' (payload,action) => state => {
* console.warn( "unexpected action ", action.type );
* return state;
* },
* }
* });
* ```
*
* The signature of the mutations is `(payload,action) => state => newState`.
* It is designed to play well with `Updeep` (and [Immer](https://immerjs.github.io/immer/docs/introduction)). This way, instead of doing
*
* ```js
* mutation: {
* renameTodo: newName => state => { ...state, name: newName }
* }
* ```
*
* we can do
*
* ```js
* mutation: {
* renameTodo: newName => u({ name: newName })
* }
* ```
*
* The final argument is the optional boolean `isSink`. If it is true, it'll
* prevent subduxes' mutations on the same action. It defaults to `false`.
*
* The object version of the argument can be used as a shortcut when all actions
* are strings. In that case, `isSink` is `false` for all mutations.
*
* ##### groomMutations
*
* Function that can be provided to alter all local mutations of the updux
* (the mutations of subduxes are left untouched).
*
* Can be used, for example, for Immer integration:
*
* ```js
* import Updux from 'updux';
* import { produce } from 'Immer';
*
* const updux = new Updux({
* initial: { counter: 0 },
* groomMutations: mutation => (...args) => produce( mutation(...args) ),
* mutations: {
* add: (inc=1) => draft => draft.counter += inc
* }
* });
* ```
*
* Or perhaps for debugging:
*
* ```js
* import Updux from 'updux';
*
* const updux = new Updux({
* initial: { counter: 0 },
* groomMutations: mutation => (...args) => state => {
* console.log( "got action ", args[1] );
* return mutation(...args)(state);
* }
* });
* ```
* ##### subduxes
*
* Object mapping slices of the state to sub-upduxes. In addition to creating
* sub-reducers for those slices, it'll make the parend updux inherit all the
* actions and middleware from its subduxes.
*
* For example, if in plain Redux you would do
*
* ```js
* import { combineReducers } from 'redux';
* import todosReducer from './todos';
* import statisticsReducer from './statistics';
*
* const rootReducer = combineReducers({
* todos: todosReducer,
* stats: statisticsReducer,
* });
* ```
*
* then with Updux you'd do
*
* ```js
* import { updux } from 'updux';
* import todos from './todos';
* import statistics from './statistics';
*
* const rootUpdux = updux({
* subduxes: {
* todos,
* statistics
* }
* });
* ```
*
* ##### effects
*
* Array of arrays or plain object defining asynchronous actions and side-effects triggered by actions.
* The effects themselves are Redux middleware, with the `dispatch`
* property of the first argument augmented with all the available actions.
*
* ```
* updux({
* effects: {
* fetch: ({dispatch}) => next => async (action) => {
* next(action);
*
* let result = await fetch(action.payload.url).then( result => result.json() );
* dispatch.fetchSuccess(result);
* }
* }
* });
* ```
*
* @example
*
* ```
* import Updux from 'updux';
* import { actions, payload } from 'ts-action';
* import u from 'updeep';
*
* const todoUpdux = new Updux({
* initial: {
* done: false,
* note: "",
* },
* actions: {
* finish: action('FINISH', payload()),
* edit: action('EDIT', payload()),
* },
* mutations: [
* [ edit, note => u({note}) ]
* ],
* selectors: {
* getNote: state => state.note
* },
* groomMutations: mutation => transform(mutation),
* subduxes: {
* foo
* },
* effects: {
* finish: () => next => action => {
* console.log( "Woo! one more bites the dust" );
* }
* }
* })
* ```
*/
* Configuration object given to Updux's constructor.
*
* #### arguments
*
* ##### initial
*
* Default initial state of the reducer. If applicable, is merged with
* the subduxes initial states, with the parent having precedence.
*
* If not provided, defaults to an empty object.
*
* ##### actions
*
* [Actions](/concepts/Actions) used by the updux.
*
* ```js
* import { dux } from 'updux';
* import { action, payload } from 'ts-action';
*
* const bar = action('BAR', payload<int>());
* const foo = action('FOO');
*
* const myDux = dux({
* actions: {
* bar
* },
* mutations: [
* [ foo, () => state => state ]
* ]
* });
*
* myDux.actions.foo({ x: 1, y: 2 }); // => { type: foo, x:1, y:2 }
* myDux.actions.bar(2); // => { type: bar, payload: 2 }
* ```
*
* New actions used directly in mutations and effects will be added to the
* dux actions -- that is, they will be accessible via `dux.actions` -- but will
* not appear as part of its Typescript type.
*
* ##### selectors
*
* Dictionary of selectors for the current updux. The updux also
* inherit its subduxes' selectors.
*
* The selectors are available via the class' getter.
*
* ##### mutations
*
* mutations: [
* [ action, mutation, isSink ],
* ...
* ]
*
* or
*
* mutations: {
* action: mutation,
* ...
* }
*
* List of mutations for assign to the dux. If you want Typescript goodness, you
* probably want to use `addMutation()` instead.
*
* In its generic array-of-array form,
* each mutation tuple contains: the action, the mutation,
* and boolean indicating if this is a sink mutation.
*
* The action can be an action creator function or a string. If it's a string, it's considered to be the
* action type and a generic `action( actionName, payload() )` creator will be
* generated for it. If an action is not already defined in the `actions`
* parameter, it'll be automatically added.
*
* The pseudo-action type `*` can be used to match any action not explicitly matched by other mutations.
*
* ```js
* const todosUpdux = updux({
* mutations: {
* add: todo => state => [ ...state, todo ],
* done: done_id => u.map( u.if( ({id} => id === done_id), {done: true} ) ),
* '*' (payload,action) => state => {
* console.warn( "unexpected action ", action.type );
* return state;
* },
* }
* });
* ```
*
* The signature of the mutations is `(payload,action) => state => newState`.
* It is designed to play well with `Updeep` (and [Immer](https://immerjs.github.io/immer/docs/introduction)). This way, instead of doing
*
* ```js
* mutation: {
* renameTodo: newName => state => { ...state, name: newName }
* }
* ```
*
* we can do
*
* ```js
* mutation: {
* renameTodo: newName => u({ name: newName })
* }
* ```
*
* The final argument is the optional boolean `isSink`. If it is true, it'll
* prevent subduxes' mutations on the same action. It defaults to `false`.
*
* The object version of the argument can be used as a shortcut when all actions
* are strings. In that case, `isSink` is `false` for all mutations.
*
* ##### groomMutations
*
* Function that can be provided to alter all local mutations of the updux
* (the mutations of subduxes are left untouched).
*
* Can be used, for example, for Immer integration:
*
* ```js
* import Updux from 'updux';
* import { produce } from 'Immer';
*
* const updux = new Updux({
* initial: { counter: 0 },
* groomMutations: mutation => (...args) => produce( mutation(...args) ),
* mutations: {
* add: (inc=1) => draft => draft.counter += inc
* }
* });
* ```
*
* Or perhaps for debugging:
*
* ```js
* import Updux from 'updux';
*
* const updux = new Updux({
* initial: { counter: 0 },
* groomMutations: mutation => (...args) => state => {
* console.log( "got action ", args[1] );
* return mutation(...args)(state);
* }
* });
* ```
* ##### subduxes
*
* Object mapping slices of the state to sub-upduxes. In addition to creating
* sub-reducers for those slices, it'll make the parend updux inherit all the
* actions and middleware from its subduxes.
*
* For example, if in plain Redux you would do
*
* ```js
* import { combineReducers } from 'redux';
* import todosReducer from './todos';
* import statisticsReducer from './statistics';
*
* const rootReducer = combineReducers({
* todos: todosReducer,
* stats: statisticsReducer,
* });
* ```
*
* then with Updux you'd do
*
* ```js
* import { updux } from 'updux';
* import todos from './todos';
* import statistics from './statistics';
*
* const rootUpdux = updux({
* subduxes: {
* todos,
* statistics
* }
* });
* ```
*
* ##### effects
*
* Array of arrays or plain object defining asynchronous actions and side-effects triggered by actions.
* The effects themselves are Redux middleware, with the `dispatch`
* property of the first argument augmented with all the available actions.
*
* ```
* updux({
* effects: {
* fetch: ({dispatch}) => next => async (action) => {
* next(action);
*
* let result = await fetch(action.payload.url).then( result => result.json() );
* dispatch.fetchSuccess(result);
* }
* }
* });
* ```
*
* @example
*
* ```
* import Updux from 'updux';
* import { actions, payload } from 'ts-action';
* import u from 'updeep';
*
* const todoUpdux = new Updux({
* initial: {
* done: false,
* note: "",
* },
* actions: {
* finish: action('FINISH', payload()),
* edit: action('EDIT', payload()),
* },
* mutations: [
* [ edit, note => u({note}) ]
* ],
* selectors: {
* getNote: state => state.note
* },
* groomMutations: mutation => transform(mutation),
* subduxes: {
* foo
* },
* effects: {
* finish: () => next => action => {
* console.log( "Woo! one more bites the dust" );
* }
* }
* })
* ```
*/
export type UpduxConfig = Partial<{
initial: unknown, /** foo */
subduxes: Dictionary<Dux>,
coduxes: Dux[],
actions: Dictionary<ActionCreator>,
selectors: Dictionary<Selector>,
mutations: any,
groomMutations: (m: Mutation) => Mutation,
effects: any,
initial: unknown /** foo */;
subduxes: Dictionary<Dux>;
coduxes: Dux[];
actions: Dictionary<ActionCreator>;
selectors: Dictionary<Selector>;
mutations: any;
groomMutations: (m: Mutation) => Mutation;
effects: any;
subscriptions: Function[];
}>;
export type Upreducer<S = any> = (action: Action) => (state: S) => S;
/** @ignore */
export interface UpduxMiddlewareAPI<S=any,X = Dictionary<Selector>> {
export interface UpduxMiddlewareAPI<S = any, X = Dictionary<Selector>> {
dispatch: Function;
getState(): S;
selectors: X;
actions: Dictionary<ActionCreator>;
}
export type UpduxMiddleware<S=any,X = Dictionary<Selector>,A = Action> = (
api: UpduxMiddlewareAPI<S,X>
export type UpduxMiddleware<S = any, X = Dictionary<Selector>, A = Action> = (
api: UpduxMiddlewareAPI<S, X>
) => (next: Function) => (action: A) => any;
export type Selector<S = any> = (state: S) => unknown;

850
src/updux.ts
View File

@ -1,6 +1,6 @@
import fp from 'lodash/fp';
import { action, payload, ActionCreator, ActionType } from 'ts-action';
import {AnyAction} from 'redux';
import { AnyAction } from 'redux';
import buildInitial from './buildInitial';
import buildMutations from './buildMutations';
@ -51,6 +51,39 @@ type StoreWithDispatchActions<
dispatch: { [type in keyof Actions]: (...args: any) => void };
};
function wrap_subscription(sub) {
return store => {
const sub_curried = sub(store);
let previous: unknown;
return (state, unsubscribe) => {
if (state === previous) return;
previous = state;
return sub_curried(state, unsubscribe);
};
};
}
function _subscribeToStore(store: any, subscriptions: Function[] = []) {
subscriptions.forEach(sub => {
const subscriber = sub(store);
let unsub = store.subscribe(() => {
const state = store.getState();
return subscriber(state, unsub);
});
});
}
function sliced_subscription(slice, sub) {
return store => {
const sub_curried = sub(store);
return (state, unsubscribe) =>
sub_curried(fp.get(slice, state), unsubscribe);
};
}
/**
* @public
* `Updux` is a way to minimize and simplify the boilerplate associated with the
@ -59,80 +92,85 @@ type StoreWithDispatchActions<
* In true `Redux`-like fashion, upduxes can be made of sub-upduxes (`subduxes` for short) for different slices of the root state.
*/
export class Updux<
S = unknown,
A = null,
X = unknown,
C extends UpduxConfig = {}
> {
subduxes: Dictionary<Dux>;
coduxes: Dux[];
S = unknown,
A = null,
X = unknown,
C extends UpduxConfig = {}
> {
subduxes: Dictionary<Dux>;
coduxes: Dux[];
private localSelectors: Dictionary<Selector> = {};
private localSelectors: Dictionary<Selector> = {};
private localInitial: unknown;
private localInitial: unknown;
groomMutations: (mutation: Mutation<S>) => Mutation<S>;
groomMutations: (mutation: Mutation<S>) => Mutation<S>;
private localEffects: Effect[] = [];
private localEffects: Effect[] = [];
private localActions: Dictionary<ActionCreator> = {};
private localActions: Dictionary<ActionCreator> = {};
private localMutations: Dictionary<
Mutation<S> | [Mutation<S>, boolean | undefined]
> = {};
private localMutations: Dictionary<
Mutation<S> | [Mutation<S>, boolean | undefined]
> = {};
get initial(): AggDuxState<S, C> {
return buildInitial(
this.localInitial,
this.coduxes.map(({ initial }) => initial),
fp.mapValues('initial', this.subduxes)
) as any;
}
private localSubscriptions: Function[] = [];
/**
* @param config an [[UpduxConfig]] plain object
*
*/
constructor(config: C = {} as C) {
this.localInitial = config.initial ?? {};
this.localSelectors = config.selectors ?? {};
this.coduxes = config.coduxes ?? [];
this.subduxes = config.subduxes ?? {};
get initial(): AggDuxState<S, C> {
return buildInitial(
this.localInitial,
this.coduxes.map(({ initial }) => initial),
fp.mapValues('initial', this.subduxes)
) as any;
}
Object.entries(config.actions ?? {}).forEach((args) =>
(this.addAction as any)(...args)
);
/**
* @param config an [[UpduxConfig]] plain object
*
*/
constructor(config: C = {} as C) {
this.localInitial = config.initial ?? {};
this.localSelectors = config.selectors ?? {};
this.coduxes = config.coduxes ?? [];
this.subduxes = config.subduxes ?? {};
this.coduxes.forEach((c: any) =>
Object.entries(c.actions).forEach((args) =>
(this.addAction as any)(...args)
)
);
Object.values(this.subduxes).forEach((c: any) => {
Object.entries(c.actions).forEach((args) => {
(this.addAction as any)(...args);
});
});
Object.entries(config.actions ?? {}).forEach(args =>
(this.addAction as any)(...args)
);
this.groomMutations =
config.groomMutations ?? ((x: Mutation<S>) => x);
this.coduxes.forEach((c: any) =>
Object.entries(c.actions).forEach(args =>
(this.addAction as any)(...args)
)
);
Object.values(this.subduxes).forEach((c: any) => {
Object.entries(c.actions).forEach(args => {
(this.addAction as any)(...args);
});
});
let effects = config.effects ?? [];
if (config.subscriptions) {
config.subscriptions.forEach(sub => this.addSubscription(sub));
}
if (!Array.isArray(effects)) {
effects = (Object.entries(effects) as unknown) as Effect[];
}
effects.forEach((effect) => (this.addEffect as any)(...effect));
this.groomMutations = config.groomMutations ?? ((x: Mutation<S>) => x);
let mutations = config.mutations ?? [];
let effects = config.effects ?? [];
if (!Array.isArray(mutations)) {
mutations = fp.toPairs(mutations);
}
if (!Array.isArray(effects)) {
effects = (Object.entries(effects) as unknown) as Effect[];
}
effects.forEach(effect => (this.addEffect as any)(...effect));
mutations.forEach((args) => (this.addMutation as any)(...args));
let mutations = config.mutations ?? [];
/*
if (!Array.isArray(mutations)) {
mutations = fp.toPairs(mutations);
}
mutations.forEach(args => (this.addMutation as any)(...args));
/*
Object.entries(selectors).forEach(([name, sel]: [string, Function]) =>
this.addSelector(name, sel as Selector)
@ -150,373 +188,389 @@ export class Updux<
);
*/
}
}
/**
* Array of middlewares aggregating all the effects defined in the
* updux and its subduxes. Effects of the updux itself are
* done before the subduxes effects.
* Note that `getState` will always return the state of the
* local updux.
*
* @example
*
* ```
* const middleware = updux.middleware;
* ```
*/
get middleware(): UpduxMiddleware<
AggDuxState<S, C>,
DuxSelectors<AggDuxState<S, C>, X, C>
> {
const selectors = this.selectors;
const actions = this.actions;
return buildMiddleware(
this.localEffects.map((effect) =>
effectToMw(effect, actions as any, selectors as any)
),
(this.coduxes as any).map(fp.get('middleware')) as any,
fp.mapValues('middleware', this.subduxes)
) as any;
}
/**
* Array of middlewares aggregating all the effects defined in the
* updux and its subduxes. Effects of the updux itself are
* done before the subduxes effects.
* Note that `getState` will always return the state of the
* local updux.
*
* @example
*
* ```
* const middleware = updux.middleware;
* ```
*/
get middleware(): UpduxMiddleware<
AggDuxState<S, C>,
DuxSelectors<AggDuxState<S, C>, X, C>
> {
const selectors = this.selectors;
const actions = this.actions;
return buildMiddleware(
this.localEffects.map(effect =>
effectToMw(effect, actions as any, selectors as any)
),
(this.coduxes as any).map(fp.get('middleware')) as any,
fp.mapValues('middleware', this.subduxes)
) as any;
}
/**
* Action creators for all actions defined or used in the actions, mutations, effects and subduxes
* of the updux config.
*
* Non-custom action creators defined in `actions` have the signature `(payload={},meta={}) => ({type,
* payload,meta})` (with the extra sugar that if `meta` or `payload` are not
* specified, that key won't be present in the produced action).
*
* The same action creator can be included
* in multiple subduxes. However, if two different creators
* are included for the same action, an error will be thrown.
*
* @example
*
* ```
* const actions = updux.actions;
* ```
*/
get actions(): DuxActions<A, C> {
// UpduxActions<Updux<S,A,SUB,CO>> {
return this.localActions as any;
}
/**
* Action creators for all actions defined or used in the actions, mutations, effects and subduxes
* of the updux config.
*
* Non-custom action creators defined in `actions` have the signature `(payload={},meta={}) => ({type,
* payload,meta})` (with the extra sugar that if `meta` or `payload` are not
* specified, that key won't be present in the produced action).
*
* The same action creator can be included
* in multiple subduxes. However, if two different creators
* are included for the same action, an error will be thrown.
*
* @example
*
* ```
* const actions = updux.actions;
* ```
*/
get actions(): DuxActions<A, C> {
// UpduxActions<Updux<S,A,SUB,CO>> {
return this.localActions as any;
}
get upreducer(): Upreducer<S> {
return buildUpreducer(
this.initial,
this.mutations as any
) as any;
}
get upreducer(): Upreducer<S> {
return buildUpreducer(this.initial, this.mutations as any) as any;
}
/**
* A Redux reducer generated using the computed initial state and
* mutations.
*/
get reducer(): (state: S | undefined, action: Action) => S {
return (state, action) => this.upreducer(action)(state as S);
}
/**
* A Redux reducer generated using the computed initial state and
* mutations.
*/
get reducer(): (state: S | undefined, action: Action) => S {
return (state, action) => this.upreducer(action)(state as S);
}
/**
* Merge of the updux and subduxes mutations. If an action triggers
* mutations in both the main updux and its subduxes, the subduxes
* mutations will be performed first.
*/
get mutations(): Dictionary<Mutation<S>> {
return buildMutations(
this.localMutations,
fp.mapValues('upreducer', this.subduxes as any),
fp.map('upreducer', this.coduxes as any)
);
}
/**
* Merge of the updux and subduxes mutations. If an action triggers
* mutations in both the main updux and its subduxes, the subduxes
* mutations will be performed first.
*/
get mutations(): Dictionary<Mutation<S>> {
return buildMutations(
this.localMutations,
fp.mapValues('upreducer', this.subduxes as any),
fp.map('upreducer', this.coduxes as any)
);
}
/**
* Returns the upreducer made of the merge of all sudbuxes reducers, without
* the local mutations. Useful, for example, for sink mutations.
*
* @example
*
* ```
* import todo from './todo'; // updux for a single todo
* import Updux from 'updux';
* import u from 'updeep';
*
* const todos = new Updux({ initial: [], subduxes: { '*': todo } });
* todos.addMutation(
* todo.actions.done,
* ({todo_id},action) => u.map( u.if( u.is('id',todo_id) ), todos.subduxUpreducer(action) )
* true
* );
* ```
*
*
*
*/
get subduxUpreducer() {
return buildUpreducer(
this.initial,
buildMutations({}, this.subduxes)
);
}
/**
* Returns the upreducer made of the merge of all sudbuxes reducers, without
* the local mutations. Useful, for example, for sink mutations.
*
* @example
*
* ```
* import todo from './todo'; // updux for a single todo
* import Updux from 'updux';
* import u from 'updeep';
*
* const todos = new Updux({ initial: [], subduxes: { '*': todo } });
* todos.addMutation(
* todo.actions.done,
* ({todo_id},action) => u.map( u.if( u.is('id',todo_id) ), todos.subduxUpreducer(action) )
* true
* );
* ```
*
*
*
*/
get subduxUpreducer() {
return buildUpreducer(this.initial, buildMutations({}, this.subduxes));
}
/**
* Returns a `createStore` function that takes two argument:
* `initial` and `injectEnhancer`. `initial` is a custom
* initial state for the store, and `injectEnhancer` is a function
* taking in the middleware built by the updux object and allowing
* you to wrap it in any enhancer you want.
*
* @example
*
* ```
* const createStore = updux.createStore;
*
* const store = createStore(initial);
* ```
*
*
*
*/
get createStore() {
return buildCreateStore<AggDuxState<S, C>, DuxActions<A, C>>(
this.reducer as any,
this.middleware as any,
this.actions
);
}
/**
* Returns a `createStore` function that takes two argument:
* `initial` and `injectEnhancer`. `initial` is a custom
* initial state for the store, and `injectEnhancer` is a function
* taking in the middleware built by the updux object and allowing
* you to wrap it in any enhancer you want.
*
* @example
*
* ```
* const createStore = updux.createStore;
*
* const store = createStore(initial);
* ```
*
*
*
*/
createStore(...args: any) {
const store = buildCreateStore<AggDuxState<S, C>, DuxActions<A, C>>(
this.reducer as any,
this.middleware as any,
this.actions
)(...args);
/**
* Returns a <a href="https://github.com/erikras/ducks-modular-redux">ducks</a>-like
* plain object holding the reducer from the Updux object and all
* its trimmings.
*
* @example
*
* ```
* const {
* createStore,
* upreducer,
* subduxes,
* coduxes,
* middleware,
* actions,
* reducer,
* mutations,
* initial,
* selectors,
* } = myUpdux.asDux;
* ```
*
*
*
*
*/
get asDux() {
return {
createStore: this.createStore,
upreducer: this.upreducer,
subduxes: this.subduxes,
coduxes: this.coduxes,
middleware: this.middleware,
actions: this.actions,
reducer: this.reducer,
mutations: this.mutations,
initial: this.initial,
selectors: this.selectors,
};
}
_subscribeToStore(store, this.subscriptions);
/**
* Adds a mutation and its associated action to the updux.
*
* @param isSink - If `true`, disables the subduxes mutations for this action. To
* conditionally run the subduxes mutations, check out [[subduxUpreducer]]. Defaults to `false`.
*
* @remarks
*
* If a local mutation was already associated to the action,
* it will be replaced by the new one.
*
*
* @example
*
* ```js
* updux.addMutation(
* action('ADD', payload<int>() ),
* inc => state => state + in
* );
* ```
*/
addMutation<A extends ActionCreator>(
creator: A,
mutation: Mutation<S, ActionType<A>>,
isSink?: boolean
);
addMutation<A extends ActionCreator = any>(
creator: string,
mutation: Mutation<S, any>,
isSink?: boolean
);
addMutation<A extends ActionCreator = any>(
creator,
mutation,
isSink
) {
const c = this.addAction(creator);
return store;
}
this.localMutations[c.type] = [
this.groomMutations(mutation as any) as Mutation<S>,
isSink,
];
}
/**
* Returns an array of all subscription functions registered for the dux.
* Subdux subscriptions are wrapped such that they are getting their
* local state. Also all subscriptions are further wrapped such that
* they are only called when the local state changed
*/
get subscriptions() {
let subscriptions = ([
this.localSubscriptions,
Object.entries(this.subduxes).map(([slice, subdux]) => {
return subdux.subscriptions.map(sub =>
sliced_subscription(slice, sub)
);
}),
] as any).flat(Infinity);
addEffect<AC extends ActionCreator>(
creator: AC,
middleware: UpduxMiddleware<
AggDuxState<S, C>,
DuxSelectors<AggDuxState<S, C>, X, C>,
ReturnType<AC>
>,
isGenerator?: boolean
);
addEffect(
creator: string,
middleware: UpduxMiddleware<
AggDuxState<S, C>,
DuxSelectors<AggDuxState<S, C>, X, C>
>,
isGenerator?: boolean
);
addEffect(creator, middleware, isGenerator = false) {
const c = this.addAction(creator);
this.localEffects.push([c.type, middleware, isGenerator] as any);
}
return subscriptions.map(sub => wrap_subscription(sub));
}
// can be
//addAction( actionCreator )
// addAction( 'foo', transform )
/**
* Adds an action to the updux. It can take an already defined action
* creator, or any arguments that can be passed to `actionCreator`.
* @example
* ```
* const action = updux.addAction( name, ...creatorArgs );
* const action = updux.addAction( otherActionCreator );
* ```
* @example
* ```
* import {actionCreator, Updux} from 'updux';
*
* const updux = new Updux();
*
* const foo = updux.addAction('foo');
* const bar = updux.addAction( 'bar', (x) => ({stuff: x+1}) );
*
* const baz = actionCreator( 'baz' );
*
* foo({ a: 1}); // => { type: 'foo', payload: { a: 1 } }
* bar(2); // => { type: 'bar', payload: { stuff: 3 } }
* baz(); // => { type: 'baz', payload: undefined }
* ```
*/
addAction(
theaction: string,
transform?: any
): ActionCreator<string, any>;
addAction(
theaction: string | ActionCreator<any>,
transform?: never
): ActionCreator<string, any>;
addAction(actionIn: any, transform: any) {
let name: string;
let creator: ActionCreator;
/**
* Returns a <a href="https://github.com/erikras/ducks-modular-redux">ducks</a>-like
* plain object holding the reducer from the Updux object and all
* its trimmings.
*
* @example
*
* ```
* const {
* createStore,
* upreducer,
* subduxes,
* coduxes,
* middleware,
* actions,
* reducer,
* mutations,
* initial,
* selectors,
* subscriptions,
* } = myUpdux.asDux;
* ```
*
*
*
*
*/
get asDux() {
return {
createStore: this.createStore,
upreducer: this.upreducer,
subduxes: this.subduxes,
coduxes: this.coduxes,
middleware: this.middleware,
actions: this.actions,
reducer: this.reducer,
mutations: this.mutations,
initial: this.initial,
selectors: this.selectors,
subscriptions: this.subscriptions,
};
}
if (typeof actionIn === 'string') {
name = actionIn;
/**
* Adds a mutation and its associated action to the updux.
*
* @param isSink - If `true`, disables the subduxes mutations for this action. To
* conditionally run the subduxes mutations, check out [[subduxUpreducer]]. Defaults to `false`.
*
* @remarks
*
* If a local mutation was already associated to the action,
* it will be replaced by the new one.
*
*
* @example
*
* ```js
* updux.addMutation(
* action('ADD', payload<int>() ),
* inc => state => state + in
* );
* ```
*/
addMutation<A extends ActionCreator>(
creator: A,
mutation: Mutation<S, ActionType<A>>,
isSink?: boolean
);
addMutation<A extends ActionCreator = any>(
creator: string,
mutation: Mutation<S, any>,
isSink?: boolean
);
addMutation<A extends ActionCreator = any>(creator, mutation, isSink) {
const c = this.addAction(creator);
if (transform) {
creator = transform.type
? transform
: action(name, (...args: any) => ({
payload: transform(...args),
}));
} else {
creator =
this.localActions[name] ?? action(name, payload());
}
} else {
name = actionIn.type;
creator = actionIn;
}
this.localMutations[c.type] = [
this.groomMutations(mutation as any) as Mutation<S>,
isSink,
];
}
const already = this.localActions[name];
addEffect<AC extends ActionCreator>(
creator: AC,
middleware: UpduxMiddleware<
AggDuxState<S, C>,
DuxSelectors<AggDuxState<S, C>, X, C>,
ReturnType<AC>
>,
isGenerator?: boolean
);
addEffect(
creator: string,
middleware: UpduxMiddleware<
AggDuxState<S, C>,
DuxSelectors<AggDuxState<S, C>, X, C>
>,
isGenerator?: boolean
);
addEffect(creator, middleware, isGenerator = false) {
const c = this.addAction(creator);
this.localEffects.push([c.type, middleware, isGenerator] as any);
}
if (!already)
return ((this.localActions as any)[name] = creator) as any;
// can be
//addAction( actionCreator )
// addAction( 'foo', transform )
/**
* Adds an action to the updux. It can take an already defined action
* creator, or any arguments that can be passed to `actionCreator`.
* @example
* ```
* const action = updux.addAction( name, ...creatorArgs );
* const action = updux.addAction( otherActionCreator );
* ```
* @example
* ```
* import {actionCreator, Updux} from 'updux';
*
* const updux = new Updux();
*
* const foo = updux.addAction('foo');
* const bar = updux.addAction( 'bar', (x) => ({stuff: x+1}) );
*
* const baz = actionCreator( 'baz' );
*
* foo({ a: 1}); // => { type: 'foo', payload: { a: 1 } }
* bar(2); // => { type: 'bar', payload: { stuff: 3 } }
* baz(); // => { type: 'baz', payload: undefined }
* ```
*/
addAction(theaction: string, transform?: any): ActionCreator<string, any>;
addAction(
theaction: string | ActionCreator<any>,
transform?: never
): ActionCreator<string, any>;
addAction(actionIn: any, transform: any) {
let name: string;
let creator: ActionCreator;
if (already !== creator && already.type !== '*') {
throw new Error(`action ${name} already exists`);
}
if (typeof actionIn === 'string') {
name = actionIn;
return already;
}
if (transform) {
creator = transform.type
? transform
: action(name, (...args: any) => ({
payload: transform(...args),
}));
} else {
creator = this.localActions[name] ?? action(name, payload());
}
} else {
name = actionIn.type;
creator = actionIn;
}
get _middlewareEntries() {
const groupByOrder = (mws: any) =>
fp.groupBy(
([, , actionType]: any) =>
['^', '$'].includes(actionType)
? actionType
: 'middle',
mws
);
const already = this.localActions[name];
const subs = fp.flow([
fp.toPairs,
fp.map(([slice, updux]) =>
updux._middlewareEntries.map(([u, ps, ...args]: any) => [
u,
[slice, ...ps],
...args,
])
),
fp.flatten,
groupByOrder,
])(this.subduxes);
if (!already)
return ((this.localActions as any)[name] = creator) as any;
const local = groupByOrder(
this.localEffects.map((x) => [this, [], ...x])
);
if (already !== creator && already.type !== '*') {
throw new Error(`action ${name} already exists`);
}
return fp.flatten(
[
local['^'],
subs['^'],
local.middle,
subs.middle,
subs['$'],
local['$'],
].filter((x) => x)
);
}
return already;
}
addSelector(name: string, selector: Selector) {
this.localSelectors[name] = selector;
}
get _middlewareEntries() {
const groupByOrder = (mws: any) =>
fp.groupBy(
([, , actionType]: any) =>
['^', '$'].includes(actionType) ? actionType : 'middle',
mws
);
/**
const subs = fp.flow([
fp.toPairs,
fp.map(([slice, updux]) =>
updux._middlewareEntries.map(([u, ps, ...args]: any) => [
u,
[slice, ...ps],
...args,
])
),
fp.flatten,
groupByOrder,
])(this.subduxes);
const local = groupByOrder(
this.localEffects.map(x => [this, [], ...x])
);
return fp.flatten(
[
local['^'],
subs['^'],
local.middle,
subs.middle,
subs['$'],
local['$'],
].filter(x => x)
);
}
addSelector(name: string, selector: Selector) {
this.localSelectors[name] = selector;
}
/**
A dictionary of the updux's selectors. Subduxes'
selectors are included as well (with the mapping to the
sub-state already taken care of you).
*/
get selectors(): DuxSelectors<AggDuxState<S, C>, X, C> {
return buildSelectors(
this.localSelectors,
fp.map('selectors', this.coduxes),
fp.mapValues('selectors', this.subduxes)
) as any;
}
}
get selectors(): DuxSelectors<AggDuxState<S, C>, X, C> {
return buildSelectors(
this.localSelectors,
fp.map('selectors', this.coduxes),
fp.mapValues('selectors', this.subduxes)
) as any;
}
/**
* Add a subscription to the dux.
*/
addSubscription(subscription: Function) {
this.localSubscriptions = [...this.localSubscriptions, subscription];
}
}
export default Updux;