New API - v2.0

[piotrwitek]

Road to v2.0: New API

I'm working on New API using the new language feature (conditional types) coming to TypesScript in the next release (v2.8)

I have already published working version that is compatible with recent typescript@rc release

> to install yarn add typesafe-actions@next

Some changes are inspired by the suggestion from the past and I would really appreciate some feedback from their authors:

• Isnt createAction type parameter redundant when creatorFunction used? #18 @CzBuCHi
• suggestion: a default value for createAction with payload and meta #17 @Jack-Works
• Did you consider pushing this further towards more boilerplate-saving? #12 @flq
• Suggestion: ability to create "routines" #21 @duro
• Type assertion on the whole action #19 @farzadmf @dziamid

The implementation of a new API is taking place on the next branch, and will be released on the release of TypeScript v2.8.

all of the examples are working and have test's against them so they should be rock solid

Finished

ActionsUnion

conditional mapped type, will provide much cleaner and experience to get Union Type of actions

import { ActionsUnion } from 'typesafe-actions';
import * as actions from './todos-duck-module';

type RootAction = ActionsUnion<typeof actions>;

• ActionsUnion works nicely with nested actions from new async action creator (check below)

const actions = {
    async: buildAction('GET_USER').async<number, { name: string }, string>(),
};
type RootAction = ActionsUnion<typeof actions>;
// { type: "GET_USER" & "REQUEST"; payload: number; } | { type: "GET_USER" & "SUCCESS"; payload: { name: string; }; } | { type: "GET_USER" & "FAILURE"; payload: string; }

• It also works recursively for deeply nested actions

const actions2 = {
      very: { deep: { empty: buildAction('INCREMENT').empty() } },
      payload: buildAction('ADD').payload<number>(),
};
type RootAction = ActionsUnion<typeof actions2>;
// { type: "INCREMENT"; } | { type: "ADD"; payload: number; }

ReturnType

getting type declaration of action will now be possible to derive from action creator on call site without the need to declare tons of boilerplate before-hand:

import { ReturnType, createAction } from 'typesafe-actions';

const increment = createAction('INCREMENT');

function incrementReducer(state: State, action: ReturnType<typeof increment>) {
...

buildAction

import { buildAction } from 'typesafe-actions'

function will accept action type and return an object with multiple methods to create different action creators described below:

• buildAction('INCREMENT').empty()

const increment = buildAction('INCREMENT').empty();
expect(increment()).toEqual({ type: 'INCREMENT' }); //  { type: 'INCREMENT' }
expect(getType(increment)).toBe('INCREMENT'); // 'INCREMENT'

• buildAction('INCREMENT').payload<P>()

const add = buildAction('ADD').payload<number>();
expect(add(10)).toEqual({ type: 'ADD', payload: 10 }); // { type: 'ADD'; payload: number }
expect(getType(add)).toBe('ADD'); // 'ADD'

• buildAction('INCREMENT').async<R, S, F>()

type User = { name: string };
const fetchUsers = buildAction('LIST_USERS').async<void, User[], string>();
expect(fetchUsers.request())
    .toEqual({ type: 'LIST_USERS_REQUEST' }); // { type: 'LIST_USERS' & 'REQUEST' }
expect(fetchUsers.success([{ name: 'Piotr' }]))
    .toEqual({ type: 'LIST_USERS_SUCCESS', payload: [{ name: 'Piotr' }] }); // { type: 'LIST_USERS' & 'SUCCESS'; payload: User[] }
expect(fetchUsers.failure('error message'))
    .toEqual({ type: 'LIST_USERS_FAILURE', payload: 'error message' }); // { type: 'LIST_USERS' & 'FAILURE'; payload: string }
expect(getType(fetchUsers.request)).toBe('LIST_USERS_REQUEST'); // 'LIST_USERS' & 'REQUEST'
expect(getType(fetchUsers.success)).toBe('LIST_USERS_SUCCESS'); // 'LIST_USERS' & 'SUCCESS'
expect(getType(fetchUsers.failure)).toBe('LIST_USERS_FAILURE'); // 'LIST_USERS' & 'FAILURE'

• buildAction('NOTIFY').fsa<P>(payloadCreator, metaCreator)

API compatible with redux-actions

const notify = buildAction('NOTIFY').fsa<{ username: string; message?: string }>(
    ({ username, message }) => `${username}: ${message || ''}`,
    ({ username, message }) => ({ username, message })
); // { type: 'NOTIFY'; payload: string; meta: { username: string; message?: string }; }
...

Breaking changes

🎉NO BREAKING CHANGES 🎉

Known Issues

• ActionsUnion not working with buildAction().async() #24

Migration to 1.2.0

Here is an migration example of example in the docs:

• simple payload action

// current v1.0
const add = createAction('ADD',
  (amount: number) => ({ type: 'ADD', payload: amount }),
);

// migration to v1.2 (complete type-safety is still preserved)
const add = buildAction('ADD').payload<number>;

• advanced Flux Standard Action

// current v1.0
const notify = createAction('NOTIFY',
  (username: string, message?: string) => ({
    type: 'NOTIFY',
    payload: `${username}: ${message || ''}`,
    meta: { username, message },
  }),
);
// migration to v1.2 (complete type-safety is still preserved)
const notify = buildAction('NOTIFY').fsa<{ username: string; message?: string }>(
    ({ username, message }) => `${username}: ${message || ''}`,
    ({ username, message }) => ({ username, message })
);

[flq]

This all looks very useful to me. With regard to

buildAction('INCREMENT').payload<P>()

The following one we also use quite often:

a1 = buildAction('FAIL').error();
a1(new Error("Damn"));

[piotrwitek]

@flq thanks for feedback, could you also add what would be expected action shape from calling a1 and it's type signature? :)
More specifically, are you're interested in setting error: boolean property of action like in the FSA standard?

[flq]

See, I never stop learning, I wasn't quite aware of said standard. In that context it'd probably have the same signature as payload<P>, but the resulting action also sets error to true.

[piotrwitek]

yes .payload<Error>() would be enough, I could add logic in action creator to check if payload is instanceOf Error and in this case add an error property with the value true to the action and of course change the type signature accordingly

[farzadmf]

Looking forward to using this new API. Just one thing, it maybe a stupid question, but can you please explain what fsa stands for? Is it flux-specific? (I haven't ever used flux)

[piotrwitek]

@farzadmf as @flq mentioned above it stands for Flux Standard Action: https://github.com/redux-utilities/flux-standard-action, most redux related libraries are following it more or less

[duro]

@piotrwitek Do you think it would be useful to add a way to set the async suffix that is used? For example if I wanted the suffix the be /@REQUEST instead of _REQUEST

Could make creating generic middleware for promisifying these action creators more sane.

Let me know if I'm not making sense.

[duro]

@piotrwitek Not sure if I found a bug, or am just doing something wrong.

Given the following code:

setToken: buildAction(SessionActionType.SET_TOKEN).fsa<{
  token: string
  resolve?: () => void
  reject?: (error: Error) => void
}>(
  ({ token }) => ({ token }),
  ({ resolve, reject }) => ({ resolve, reject })
)

I am getting the following type errors in VSCode using TS2.8

[duro]

I was able to get my use case to work with the following:

setToken: buildAction(SessionActionType.SET_TOKEN).fsa<
  { token: string; resolve: () => void; reject: (error: Error) => void },
  { token: string },
  { resolve: () => void; reject: (error: Error) => void }
>(
  ({ token }) => ({ token: 'fgfg' }),
  ({ resolve, reject }) => ({ resolve, reject })
)

Now I seem to be having some oddities around using the ActionsUnion with .async() created actions. Since that call returns three methods, instead of what would normally satisfy a the Redux.Action type, the compiler is complaining.

Any thoughts there?

[piotrwitek]

@duro fsa is WIP, for the moment it works differently like this:

setToken: buildAction(SessionActionType.SET_TOKEN).fsa(
  ({ token }: { token: string }) => ({ token }),
  ({ token }) => ({ resolve: ..., reject: ... })
)

But I plan to change it to using only the generic type for payload, and the rest will use inference

[duro]

@piotrwitek Did you see my last comment #22 (comment). I was able to get it working with three type args.

That said, see the second half of the comment. New issue is with use of .async() and ActionsUnion

I'm no TS wiz, but perhaps for that case, we could have a named interface for the return of the .async and do an additional conditional that digs one level deeper if that type?

[piotrwitek]

Yes I saw it and working on it :) Trying to modify mapped with conditional type