diff --git a/package.json b/package.json index 82bbd1d..259a1c5 100644 --- a/package.json +++ b/package.json @@ -5,6 +5,7 @@ "description": "Wraps react-redux up for Preact, without preact-compat", "main": "dist/preact-redux.js", "module": "dist/preact-redux.esm.js", + "types": "src/preact-redux.d.ts", "jsnext:main": "dist/preact-redux.esm.js", "minified:main": "dist/preact-redux.min.js", "scripts": { diff --git a/src/preact-redux.d.ts b/src/preact-redux.d.ts new file mode 100644 index 0000000..8b2d4cf --- /dev/null +++ b/src/preact-redux.d.ts @@ -0,0 +1,279 @@ +// Type definitions for preact-redux 2.0.1 +// Definitions by: Qubo , +// Thomas Hasner , +// Kenzie Togami , +// Curits Layne +// Frank Tan +// Daniil Kolesnik +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +// TypeScript Version: 2.4 + +import { AnyComponent, Component, ComponentConstructor, VNode } from 'preact'; +import { Store, Dispatch, ActionCreator } from 'redux'; + +// Diff / Omit taken from https://github.com/Microsoft/TypeScript/issues/12215#issuecomment-311923766 +type Diff = ({ [P in T]: P } & { [P in U]: never } & { [x: string]: never })[T]; +type Omit = Pick>; + +export interface DispatchProp { + dispatch?: Dispatch; +} + +interface AdvancedComponentDecorator { + (component: AnyComponent): ComponentConstructor; +} + +// Injects props and removes them from the prop requirements. +// Will not pass through the injected props if they are passed in during +// render. Also adds new prop requirements from TNeedsProps. +export interface InferableComponentEnhancerWithProps { +

( + component: AnyComponent + ): ComponentConstructor & TNeedsProps, {}> +} + +// Injects props and removes them from the prop requirements. +// Will not pass through the injected props if they are passed in during +// render. +export type InferableComponentEnhancer = + InferableComponentEnhancerWithProps + +/** + * Connects a Preact component to a Redux store. + * + * - Without arguments, just wraps the component, without changing the behavior / props + * + * - If 2 params are passed (3rd param, mergeProps, is skipped), default behavior + * is to override ownProps (as stated in the docs), so what remains is everything that's + * not a state or dispatch prop + * + * - When 3rd param is passed, we don't know if ownProps propagate and whether they + * should be valid component props, because it depends on mergeProps implementation. + * As such, it is the user's responsibility to extend ownProps interface from state or + * dispatch props or both when applicable + * + * @param mapStateToProps + * @param mapDispatchToProps + * @param mergeProps + * @param options + */ +export declare function connect(): InferableComponentEnhancer>; + +export declare function connect( + mapStateToProps: MapStateToPropsParam +): InferableComponentEnhancerWithProps, TOwnProps>; + +export declare function connect( + mapStateToProps: null | undefined, + mapDispatchToProps: MapDispatchToPropsParam +): InferableComponentEnhancerWithProps; + +export declare function connect( + mapStateToProps: MapStateToPropsParam, + mapDispatchToProps: MapDispatchToPropsParam +): InferableComponentEnhancerWithProps; + +export declare function connect( + mapStateToProps: MapStateToPropsParam, + mapDispatchToProps: null | undefined, + mergeProps: MergeProps, +): InferableComponentEnhancerWithProps; + +export declare function connect( + mapStateToProps: null | undefined, + mapDispatchToProps: MapDispatchToPropsParam, + mergeProps: MergeProps, +): InferableComponentEnhancerWithProps; + +export declare function connect( + mapStateToProps: null | undefined, + mapDispatchToProps: null | undefined, + mergeProps: MergeProps, +): InferableComponentEnhancerWithProps; + +export declare function connect( + mapStateToProps: MapStateToPropsParam, + mapDispatchToProps: MapDispatchToPropsParam, + mergeProps: MergeProps, +): InferableComponentEnhancerWithProps; + +export declare function connect( + mapStateToProps: MapStateToPropsParam, + mapDispatchToProps: null | undefined, + mergeProps: null | undefined, + options: Options +): InferableComponentEnhancerWithProps & TStateProps, TOwnProps>; + +export declare function connect( + mapStateToProps: null | undefined, + mapDispatchToProps: MapDispatchToPropsParam, + mergeProps: null | undefined, + options: Options +): InferableComponentEnhancerWithProps; + +export declare function connect( + mapStateToProps: MapStateToPropsParam, + mapDispatchToProps: MapDispatchToPropsParam, + mergeProps: null | undefined, + options: Options +): InferableComponentEnhancerWithProps; + +export declare function connect( + mapStateToProps: MapStateToPropsParam, + mapDispatchToProps: MapDispatchToPropsParam, + mergeProps: MergeProps, + options: Options +): InferableComponentEnhancerWithProps; + +interface MapStateToProps { + (state: any, ownProps: TOwnProps): TStateProps; +} + +interface MapStateToPropsFactory { + (initialState: any, ownProps: TOwnProps): MapStateToProps; +} + +type MapStateToPropsParam = MapStateToProps | MapStateToPropsFactory; + +interface MapDispatchToPropsFunction { + (dispatch: Dispatch, ownProps: TOwnProps): TDispatchProps; +} + +type MapDispatchToProps = + MapDispatchToPropsFunction | TDispatchProps; + +interface MapDispatchToPropsFactory { + (dispatch: Dispatch, ownProps: TOwnProps): MapDispatchToProps; +} + +type MapDispatchToPropsParam = MapDispatchToProps | MapDispatchToPropsFactory; + +interface MergeProps { + (stateProps: TStateProps, dispatchProps: TDispatchProps, ownProps: TOwnProps): TMergedProps; +} + +interface Options extends ConnectOptions { + /** + * If true, implements shouldComponentUpdate and shallowly compares the result of mergeProps, + * preventing unnecessary updates, assuming that the component is a “pure” component + * and does not rely on any input or state other than its props and the selected Redux store’s state. + * Defaults to true. + * @default true + */ + pure?: boolean; + + /** + * When pure, compares incoming store state to its previous value. + * @default strictEqual + */ + areStatesEqual?: (nextState: any, prevState: any) => boolean; + + /** + * When pure, compares incoming props to its previous value. + * @default shallowEqual + */ + areOwnPropsEqual?: (nextOwnProps: TOwnProps, prevOwnProps: TOwnProps) => boolean; + + /** + * When pure, compares the result of mapStateToProps to its previous value. + * @default shallowEqual + */ + areStatePropsEqual?: (nextStateProps: TStateProps, prevStateProps: TStateProps) => boolean; + + /** + * When pure, compares the result of mergeProps to its previous value. + * @default shallowEqual + */ + areMergedPropsEqual?: (nextMergedProps: TMergedProps, prevMergedProps: TMergedProps) => boolean; +} + +/** + * Connects a React component to a Redux store. It is the base for {@link connect} but is less opinionated about + * how to combine state, props, and dispatch into your final props. It makes no + * assumptions about defaults or memoization of results, leaving those responsibilities to the caller.It does not + * modify the component class passed to it; instead, it returns a new, connected component class for you to use. + * + * @param selectorFactory The selector factory. See {@type SelectorFactory} for details. + * @param connectOptions If specified, further customizes the behavior of the connector. Additionally, any extra + * options will be passed through to your selectorFactory in the factoryOptions argument. + */ +export declare function connectAdvanced( + selectorFactory: SelectorFactory, + connectOptions?: ConnectOptions & TFactoryOptions +): AdvancedComponentDecorator; + +/** + * Initializes a selector function (during each instance's constructor). That selector function is called any time the + * connector component needs to compute new props, as a result of a store state change or receiving new props. The + * result of selector is expected to be a plain object, which is passed as the props to the wrapped + * component. If a consecutive call to selector returns the same object (===) as its previous + * call, the component will not be re-rendered. It's the responsibility of selector to return that + * previous object when appropriate. + */ +export interface SelectorFactory { + (dispatch: Dispatch, factoryOptions: TFactoryOptions): Selector +} + +export interface Selector { + (state: S, ownProps: TOwnProps): TProps +} + +export interface ConnectOptions { + /** + * Computes the connector component's displayName property relative to that of the wrapped component. Usually + * overridden by wrapper functions. + * + * @default name => 'ConnectAdvanced('+name+')' + * @param componentName + */ + getDisplayName?: (componentName: string) => string + /** + * Shown in error messages. Usually overridden by wrapper functions. + * + * @default 'connectAdvanced' + */ + methodName?: string + /** + * If defined, a property named this value will be added to the props passed to the wrapped component. Its value + * will be the number of times the component has been rendered, which can be useful for tracking down unnecessary + * re-renders. + * + * @default undefined + */ + renderCountProp?: string + /** + * Controls whether the connector component subscribes to redux store state changes. If set to false, it will only + * re-render on componentWillReceiveProps. + * + * @default true + */ + shouldHandleStateChanges?: boolean + /** + * The key of props/context to get the store. You probably only need this if you are in the inadvisable position of + * having multiple stores. + * + * @default 'store' + */ + storeKey?: string + /** + * If true, stores a ref to the wrapped component instance and makes it available via getWrappedInstance() method. + * + * @default false + */ + withRef?: boolean +} + +export interface ProviderProps { + /** + * The single Redux store in your application. + */ + store?: Store; + children?: VNode; +} + +/** + * Makes the Redux store available to the connect() calls in the component hierarchy below. + */ +export class Provider extends Component { + render(props: ProviderProps): VNode +}