0
# Typesafe Actions
1

2
Typesafe Actions is a TypeScript library that provides typesafe utilities designed to reduce types verbosity and complexity in Redux/Flux architectures. It offers a comprehensive set of action creators, action helpers, type helpers, and reducer utilities with full type safety and enhanced developer experience.
3

4
## Package Information
5

6
- **Package Name**: typesafe-actions
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install typesafe-actions`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  action, 
16
  createAction, 
17
  createCustomAction, 
18
  createAsyncAction, 
19
  createReducer,
20
  getType, 
21
  isActionOf, 
22
  isOfType,
23
  deprecated
24
} from "typesafe-actions";
25
```
26

27
For CommonJS:
28

29
```javascript
30
const { 
31
  action, 
32
  createAction, 
33
  createCustomAction, 
34
  createAsyncAction, 
35
  createReducer,
36
  getType, 
37
  isActionOf, 
38
  isOfType,
39
  deprecated
40
} = require("typesafe-actions");
41
```
42

43
For TypeScript types:
44

45
```typescript
46
import type {
47
  Action,
48
  ActionCreator,
49
  ActionType,
50
  StateType,
51
  EmptyAction,
52
  PayloadAction,
53
  PayloadMetaAction,
54
  ActionCreatorBuilder,
55
  AsyncActionCreatorBuilder
56
} from "typesafe-actions";
57
```
58

59
## Basic Usage
60

61
```typescript
62
import { createAction, createAsyncAction, createReducer } from "typesafe-actions";
63

64
// Create simple action
65
const increment = createAction('INCREMENT')<number>();
66
const decrement = createAction('DECREMENT')();
67

68
// Create async action
69
const fetchUser = createAsyncAction(
70
  'FETCH_USER_REQUEST',
71
  'FETCH_USER_SUCCESS', 
72
  'FETCH_USER_FAILURE'
73
)<void, User, Error>();
74

75
// Create reducer
76
const counterReducer = createReducer({ count: 0 })
77
  .handleAction(increment, (state, action) => ({
78
    count: state.count + action.payload,
79
  }))
80
  .handleAction(decrement, (state) => ({
81
    count: state.count - 1,
82
  }));
83
```
84

85
## Architecture
86

87
Typesafe Actions is built around several key components:
88

89
- **Action Creators**: Functions for creating type-safe actions (`createAction`, `createAsyncAction`, etc.)
90
- **Action Helpers**: Utilities for working with actions (`getType`, `isActionOf`, `isOfType`)
91
- **Type System**: Comprehensive TypeScript type definitions for full type safety
92
- **Reducer Utilities**: Type-safe reducer creation with `createReducer`
93
- **Legacy Support**: Deprecated API maintained for backward compatibility
94

95
## Capabilities
96

97
### Action Creators
98

99
Core action creation functionality providing type-safe action creators with payload and meta support, async action patterns, and reducer utilities.
100

101
```typescript { .api }
102
function action<T extends TypeConstant>(type: T): { type: T };
103

104
function createAction<TType extends string>(
105
  type: TType
106
): ActionCreatorBuilder<TType>;
107

108
function createCustomAction<
109
  TType extends TypeConstant,
110
  TArgs extends any[] = [],
111
  TReturn extends any = {}
112
>(
113
  type: TType,
114
  createHandler?: (...args: TArgs) => TReturn
115
): ((...args: TArgs) => ResolveType<{ type: TType } & TReturn>) &
116
  ActionCreatorTypeMetadata<TType>;
117

118
function createAsyncAction<
119
  TRequestType extends string,
120
  TSuccessType extends string, 
121
  TFailureType extends string
122
>(
123
  requestType: TRequestType,
124
  successType: TSuccessType,
125
  failureType: TFailureType
126
): AsyncActionCreatorBuilder<TRequestType, TSuccessType, TFailureType>;
127

128
function createReducer<TState, TRootAction extends Action = Types["RootAction"]>(
129
  initialState: TState
130
): ReducerBuilder<TState, TRootAction>;
131
```
132

133
[Action Creators](./action-creators.md)
134

135
### Action Helpers
136

137
Utilities for type-safe action inspection and filtering, including type guards and action creator type extraction.
138

139
```typescript { .api }
140
function getType<TType extends TypeConstant>(
141
  actionCreator: ActionCreator<TType> & ActionCreatorTypeMetadata<TType>
142
): TType;
143

144
function isActionOf<AC extends ActionCreator<{ type: string }>>(
145
  actionCreator: AC | AC[]
146
): (action: { type: string }) => action is ReturnType<AC>;
147

148
function isOfType<T extends string>(
149
  type: T | T[]
150
): <A extends { type: string }>(action: A) => action is A extends { type: T } ? A : never;
151
```
152

153
[Action Helpers](./action-helpers.md)
154

155
### Type Helpers
156

157
Complete TypeScript type definitions and interfaces for building type-safe Redux applications with action creators, reducers, and state management.
158

159
```typescript { .api }
160
type TypeConstant = string;
161

162
interface Action<TType extends TypeConstant = TypeConstant> {
163
  type: TType;
164
}
165

166
type ActionCreator<TAction extends Action = Action> = (
167
  ...args: any[]
168
) => TAction;
169

170
interface ActionCreatorTypeMetadata<TType extends TypeConstant> {
171
  getType?(): TType;
172
}
173

174
type ActionType<TActionCreatorOrMap extends any> = 
175
  TActionCreatorOrMap extends ActionCreator<infer TAction>
176
    ? TAction
177
    : TActionCreatorOrMap extends Record<any, any>
178
    ? ActionType<TActionCreatorOrMap[keyof TActionCreatorOrMap]>
179
    : never;
180

181
type ResolveType<T> = T extends (...args: any[]) => any ? ReturnType<T> : T;
182

183
interface Types {
184
  RootAction: Action;
185
}
186
```
187

188
[Type Helpers](./type-helpers.md)
189

190
### Deprecated API
191

192
Backward-compatible API for migrating from previous versions (v4.x.x). Available under the `deprecated` named import.
193

194
```typescript { .api }
195
import { deprecated } from "typesafe-actions";
196

197
const { createAction, createStandardAction, createCustomAction } = deprecated;
198
```
199

200
The deprecated API includes legacy versions of action creators that were available in v4.x.x and earlier versions for incremental migration support.