@appnest/typed-actions/lib/index.cjs.d.ts

A lightweight library to create and type check flux/redux actions in typescript

/**
 * Type for the "id" field of actions.
 */
declare type ActionIdType = string;
/**
 * Default type for action payload if not specified.
 */
declare type DefaultActionPayloadType = void;
/**
 * Default type for action metadata if not specified.
 */
declare type DefaultActionMetaType = void;
/**
 * All actions come with a "status" field.
 */
declare enum ActionStatusKind {
    START = "START",
    SUCCESS = "SUCCESS",
    FAILURE = "FAILURE"
}
/**
 * Default action to use when the user doesn't specify an action status.
 */
declare const DEFAULT_ACTION_STATUS_KIND = ActionStatusKind.SUCCESS;
/**
 * The action type used for all action.
 * This type can be used with and without generic parameters.
 * If generic parameters aren't specified it defaults to the "unknown" type.
 */
declare type Action<Payload = unknown, Meta = unknown> = {
    type: string;
    id: ActionIdType;
    status: ActionStatusKind;
    payload: Payload;
    meta: Meta;
    error: boolean;
};
/**
 * Defines a start action.
 */
interface StartAction<Start, Meta> extends Action<Start, Meta> {
    status: ActionStatusKind.START;
    error: false;
    payload: Start;
    meta: Meta;
}
/**
 * Defines a success action.
 */
interface SuccessAction<Success, Meta> extends Action<Success, Meta> {
    status: ActionStatusKind.SUCCESS;
    error: false;
    payload: Success;
    meta: Meta;
}
/**
 * Defines a failure action.
 */
interface FailureAction<Failure, Meta> extends Action<Failure, Meta> {
    status: ActionStatusKind.FAILURE;
    error: true;
    payload: Failure;
    meta: Meta;
}
/**
 * Defines an discriminated union used if needing to switch/case "status" field type guarded.
 */
declare type AsyncAction<Start = DefaultActionPayloadType, Success = DefaultActionPayloadType, Failure = DefaultActionPayloadType, Meta = DefaultActionMetaType> = StartAction<Start, Meta> | SuccessAction<Success, Meta> | FailureAction<Failure, Meta>;
/**
 * Optional spread two generic parameters.
 * <undefined, undefined>   =>  [T?, U?]
 * <defined, undefined>     =>  [T, U?]
 * <undefined, defined>     =>  [T, U]
 * <defined, defined>       =>  [T, U]
 */
declare type OptionalSpreadTuple<T, U> = IfVoid<U, IfVoid<T, [T?, U?], [T, U?]>, [T, U]>;
/**
 * Optional spread two generic parameters always forcing the last one to be optional.
 * <undefined, undefined>   =>  [T?, U?]
 * <defined, undefined>     =>  [T, U?]
 * <undefined, defined>     =>  [T, U?]
 * <defined, defined>       =>  [T, U?]
 */
declare type OptionalSpreadTupleAlwaysOptional<T, U> = IfVoid<T, [T?, U?], [T, U?]>;
/**
 * Choose the first type if T is "void".
 * Choose the second type if T is not "void".
 * Checks for undefined and null because "void" matches both.
 */
declare type IfVoid<T, VoidType, ElseType> = T extends undefined ? ElseType : (T extends null ? ElseType : (T extends void ? VoidType : ElseType));
/**
 * Creates an action object.
 * Payload and metadata is optional if their corresponding type is undefined.
 * @param id
 * @param status
 * @param payloadAndMeta
 */
declare function mkAction<Payload = DefaultActionPayloadType, Meta = DefaultActionMetaType>(id: ActionIdType, status: ActionStatusKind, ...payloadAndMeta: OptionalSpreadTuple<Payload, Meta>): Action<Payload, Meta>;
declare type P = DefaultActionPayloadType;
declare type M = DefaultActionMetaType;
/**
 * The base of actions creators.
 * Every action creator comes with an "id" and "status" in order to type guard with the "isAction" function.
 */
interface ActionCreatorBase<Payload, Meta> {
    id: ActionIdType;
    status: ActionStatusKind;
}
/**
 * An action creator which is a function used to make actions.
 */
interface ActionCreator<Payload = P, Meta = M> extends ActionCreatorBase<Payload, Meta> {
    (...args: OptionalSpreadTuple<Payload, Meta>): Action<Payload, Meta>;
}
/**
 * An action creator with pre assigned "meta".
 * This can be used to create actions with specific metadata without needing to specify metadata every time.
 */
interface ActionCreatorWithMeta<Payload = P, Meta = M> extends ActionCreatorBase<Payload, Meta> {
    meta: Meta;
    (...args: OptionalSpreadTupleAlwaysOptional<Payload, Meta>): Action<Payload, Meta>;
}
/**
 * Creates an action creator that binds a specific "id" and "status".
 * An action creator is a function that can be called to create an action.
 * If needed the action creator can be assigned an optional metadata which makes it possible create actions without needing to add the metadata every time.
 * @param id
 * @param status
 */
declare function actionCreator<Payload = P, Meta = M>(id: ActionIdType, status?: ActionStatusKind): IfVoid<Meta, ActionCreatorWithMeta<Payload, Meta>, ActionCreator<Payload, Meta>>;
declare function actionCreator<Payload = P, Meta = M>(id: ActionIdType, status: ActionStatusKind, defaultMeta: Meta): ActionCreatorWithMeta<Payload, Meta>;
/**
 * Checks if an action was made from a specific action creator using a type guard.
 * An action is created by an action creator if "id" and "status" of the action corresponds to the action creator.
 * @param action
 * @param actionCreator
 */
declare function isAction<Payload, Meta>(action: Action<unknown, unknown>, actionCreator: ActionCreator<Payload, Meta> | ActionCreatorWithMeta<Payload, Meta>): action is Action<Payload, Meta>;
declare type P_$0 = DefaultActionPayloadType;
declare type M_$0 = DefaultActionMetaType;
/**
 * The base of async actions creators.
 * An async action creator comes with an "id" field used for type guarding.
 */
interface AsyncActionCreatorBase<Start, Success, Failure, Meta> {
    id: ActionIdType;
}
/**
 * Defines an async action creator that provides "start", "success" and "failure" action creator functions.
 * If this action creator is used as a function it will return an action creator with predefined metadata.
 */
interface AsyncActionCreator<Start = P_$0, Success = P_$0, Failure = P_$0, Meta = M_$0> extends AsyncActionCreatorBase<Start, Success, Failure, Meta> {
    start: ActionCreator<Start, Meta>;
    success: ActionCreator<Success, Meta>;
    failure: ActionCreator<Failure, Meta>;
    (defaultMeta: Meta): AsyncActionCreatorWithMeta<Start, Success, Failure, Meta>;
}
/**
 * An async action creator with predefined metadata.
 */
interface AsyncActionCreatorWithMeta<Start = P_$0, Success = P_$0, Failure = P_$0, Meta = M_$0> extends AsyncActionCreatorBase<Start, Success, Failure, Meta> {
    meta: Meta;
    start: ActionCreatorWithMeta<Start, Meta>;
    success: ActionCreatorWithMeta<Success, Meta>;
    failure: ActionCreatorWithMeta<Failure, Meta>;
}
/**
 * Makes an async action creator with "start", "success" and "failure" action creator functions.
 * Use it as a function to add predefined metadata to the action creator.
 * @param id
 */
declare function asyncActionCreator<Start = P_$0, Success = P_$0, Failure = P_$0, Meta = M_$0>(id: ActionIdType): IfVoid<Meta, AsyncActionCreatorWithMeta<Start, Success, Failure, Meta>, AsyncActionCreator<Start, Success, Failure, Meta>>;
declare function asyncActionCreator<Start = P_$0, Success = P_$0, Failure = P_$0, Meta = M_$0>(id: ActionIdType, defaultMeta: Meta): AsyncActionCreatorWithMeta<Start, Success, Failure, Meta>;
/**
 * Checks if the "action" has been made from a specific "actionCreator".
 * This function returns a discriminated union that can be used to switch/case the "status" field if that's your style of programming.
 * @param action
 * @param actionCreator
 */
declare function isAsyncAction<Start, Success, Failure, Meta>(action: Action<unknown, unknown>, actionCreator: AsyncActionCreator<Start, Success, Failure, Meta> | AsyncActionCreatorWithMeta<Start, Success, Failure, Meta>): action is AsyncAction<Start, Success, Failure, Meta>;
/**
 * Default action creator with built in metadata where only the Success and Meta types are user defined.
 * Started Type: void
 * Success Type: user defined
 * Failure Type: Error
 */
declare type DefaultAsyncActionCreatorWithMeta<Success = DefaultActionPayloadType, Meta = DefaultActionMetaType> = AsyncActionCreatorWithMeta<void, Success, Error, Meta>;
/**
 * Default action creator where only the Success and Meta types are user defined.
 * Started Type: void
 * Success Type: user defined
 * Failure Type: Error
 */
declare type DefaultAsyncActionCreator<Success = DefaultActionPayloadType, Meta = DefaultActionMetaType> = AsyncActionCreator<void, Success, Error, Meta>;
/**
 * Creates a default async action creator where only the Success and Meta types are user defined.
 * If no id is given and id is auto-generated:                   `ACTION_${n}`.
 * If both "idOrNamespace" and "id" is given, the id will be    `${namespace}/${id}`.
 * @param idOrNamespace
 * @param id
 */
declare function defaultAsyncActionCreator<Success = DefaultActionPayloadType, Meta = DefaultActionMetaType>(idOrNamespace?: ActionIdType, id?: ActionIdType): IfVoid<Meta, DefaultAsyncActionCreatorWithMeta<Success, Meta>, DefaultAsyncActionCreator<Success, Meta>>;
/**
 * Returns a curried function with a action dispatcher function.
 * The returned function will take an "actionCreator" and a async "handler" function that must return a successful value.
 * If the "handler" function throws an error a "failure" action will be dispatched an the error will be rethrown.
 * The function will always dispatch a "start" action.
 * @param dispatch
 */
declare const tryCatchDispatch: (dispatch: (action: Action<unknown, unknown>) => void) => <Success, Meta>(actionCreator: AsyncActionCreatorWithMeta<void, Success, Error, Meta>, handler: () => Success | Promise<Success>) => Promise<Success>;
export { ActionIdType, DefaultActionPayloadType, DefaultActionMetaType, ActionStatusKind, DEFAULT_ACTION_STATUS_KIND, Action, ActionCreatorBase, ActionCreator, ActionCreatorWithMeta, actionCreator, isAction, mkAction, StartAction, SuccessAction, FailureAction, AsyncAction, AsyncActionCreatorBase, AsyncActionCreator, AsyncActionCreatorWithMeta, asyncActionCreator, isAsyncAction, DefaultAsyncActionCreatorWithMeta, DefaultAsyncActionCreator, defaultAsyncActionCreator, tryCatchDispatch, OptionalSpreadTuple, OptionalSpreadTupleAlwaysOptional, IfVoid };
//# sourceMappingURL=index.cjs.d.ts.map