Nanoscale Parts Manufacturing

    @martin_hotell/rex-tils
    TypeScript icon, indicating that this package has built-in type declarations

    2.1.1 • Public • Published

    rex-tils 🦖 ⚛ ️🖖

    Type safe utils for redux actions and various guard utils for React and Angular

    WHY/WHAT? 👉 https://medium.com/@martin_hotell/improved-redux-type-safety-with-typescript-2-8-2c11a8062575

    Greenkeeper badge

    Build Status NPM version Downloads Standard Version styled with prettier Conventional Commits

    Installing

    yarn add @martin_hotell/rex-tils
    # OR 
    npm install @martin_hotell/rex-tils

    Note:

    1. This library supports only TS >= 3.1 ( because it uses conditional types and generic rest arguments #dealWithIt )
    2. For leveraging Rx ofType operator within your Epics/Effects you need to install rxjs>= 6.x

    Getting started

    Let's demonstrate simple usage with old good Counter example:

    Edit counter-example

    1. Create Type-safe Redux Actions
    // actions.ts
    import { ActionsUnion, createAction } from '@martin_hotell/rex-tils'
     
    export const INCREMENT = 'INCREMENT'
    export const DECREMENT = 'DECREMENT'
    export const INCREMENT_IF_ODD = 'INCREMENT_IF_ODD'
     
    export const Actions = {
      increment: () => createAction(INCREMENT),
      decrement: () => createAction(DECREMENT),
      incrementIfOdd: () => createAction(INCREMENT_IF_ODD),
    }
     
    // we leverage TypeScript token merging, so our consumer can use `Actions` for both runtime and compile time types 💪
    export type Actions = ActionsUnion<typeof Actions>
    1. Use Type-safe Redux Actions within Reducer
    // reducer.ts
    import * as fromActions from './actions'
     
    export const initialState = 0 as number
    export type State = typeof initialState
     
    export const reducer = (
      state = initialState,
      actionfromActions.Actions
    )State => {
      switch (action.type) {
        case fromActions.INCREMENT: {
          // $ExpectType 'INCREMENT'
          const { type } = action
     
          return state + 1
        }
        case fromActions.DECREMENT: {
          // $ExpectType 'DECREMENT'
          const { type } = action
     
          return state - 1
        }
        default:
          return state
      }
    }
    1. Use Type-safe Redux Actions within Epics with ofType Rx operator
    // epics.ts
     
    import { ofType } from '@martin_hotell/rex-tils'
    import { ActionsObservable, StateObservable } from 'redux-observable'
    import { filter, map, withLatestFrom } from 'rxjs/operators'
     
    import * as fromActions from './actions'
    import { AppState } from './store'
     
    export const incrementIfOddEpic = (
      // provide all our Actions type that can flow through the stream
      // everything else is gonna be handled by TypeScript so we don't have to provide any explicit type annotations. Behold... top notch DX 👌❤️🦖
      action$ActionsObservable<fromActions.Actions>,
      state$: StateObservable<AppState>
    ) =>
      action$.pipe(
        ofType(fromActions.INCREMENT_IF_ODD),
        withLatestFrom(state$),
        filter(
          (
            [action, state] // $ExpectType ['INCREMENT_IF_ODD', {counter:number}]
          ) => state.counter % 2 === 1
        ),
        map(() => fromActions.Actions.increment())
      )

    Examples

    Go checkout examples !

    API

    rex-tils API is tiny and consist of 2 categories:

    1. Runtime JavaScript helpers
    2. Compile time TypeScript type helpers

    1. Runtime javascript helpers

    createAction<T extends string,P>(type: T,payload?: P): Action<T,P>

    • use for declaring action creators

    ofType(...keys:string[]): Observable<Action>

    • use within Epic/Effect for filtering actions

    Type guards:

    • all following type guards properly narrow your types 💪:

    isBlank(value:any)

    • checks if value is null or undefined

    isPresent(value:any)

    • checks if value is not null nor undefined

    isEmpty<T extends string | object>(value:T): Empty<T>

    • checks if value is empty for string | array | object otherwise it throws an error.
    • also it narrows the type to empty type equivalent

    isFunction(value:any)

    isBoolean(value:any)

    isString(value:any)

    isNumber(value:any)

    isArray(value:any)

    isObject<T>(value:T): T

    • normalized check if JS value is an object. That means anything that is not an array, not null/undefined but typeof value equals to 'object'
    • it will also properly narrow type within the branch
    type MyMap = { who: string; age: number }
    declare const someObj: MyMap | string | number
     
    if (isObject(someObj)) {
      // $ExpectType MyMap
      someObj
    } else {
      // $ExpectType string | number
      someObj
    }

    isDate(value:any): value is Date

    isPromise(value:any): value is PromiseLike<any>

    Utils:

    noop(): void

    identity<T>(value:T):T

    Enum(...tokens:string[]): object

    As described in 10 TypeScript Pro tips article, we don't recommend to use enum feature within your codebase. Instead you can leverage this small utility function which comes as both function and type alias to get proper enum object map and type literal, if you really need enums in runtime.

    // enums.ts
     
    // $ExpectType Readonly<{ No: "No"; Yes: "Yes"; }>
     export const AnswerResponse = Enum('No', 'Yes')
     // $ExpectType 'No' | 'Yes'
     export type AnswerResponse = Enum(typeof AnswerResponse)
     
     // consumer.ts
     
     import {AnswerResponse} from './enums'
     
     export const respond = (
       recipientstring,
       // 1. 👉 enum used as type
       messageAnswerResponse
      ) => { /*...*/}
     
     // usage.ts
     
     import {respond} from './consumer'
     import {AnswerResponse} from './enums'
     
     respond('Johnny 5','Yes')
     respond(
       'Johnny 5',
       // 2. 👉  enum used as reference
       AnswerResponse.No
       )

    tuple(...args: T): T

    • Implicitly create a tuple with proper tuple types instead of widened array of union types
    // $ExpectType (string | number | boolean)[]
    const testWidened = ['one', 1, false]
     
    // $ExpectType [string, number, boolean]
    const testProperTuple = tuple('one', 1, false)

    React/Preact related helpers:

    isEmptyChildren( children: ReactNode )

    • checks if Children.count === 0

    ChildrenAsFunction<T extends AnyFunction>( children: T ): T

    • similar to Children.only although checks if children is only a function. Useful for children as a function pattern. If not will throw an error otherwise narrows children type to function and returns it.
    type Props = {
      userId: string
      children: (props: { data: UserModel }) => ReactElement
    }
     
    type State = { data: UserModel | null }
     
    class UserRenderer extends Component<Props, State> {
      render() {
        const { data } = this.state
        // Will throw on runtime if children is not a function
        // $ExpectType (props: {data: UserModel}) => ReactElement
        const childrenFn = ChildrenAsFunction(children)
     
        return data ? children(data) : 'Loading...'
      }
     
      componentDidMount() {
        fetch(`api/users/${this.props.userId}`)
          .json()
          .then((data) => this.setState({ data }))
      }
    }
     
    const App = () => (
      <UserRenderer userId={7}>
        {({ data }) => <div>name: {data.name}}</div>}
      </UserRenderer>
    )

    pickWithRest<Props, PickedProps>( props: object, pickProps: keyof PickedProps[] )

    • use for getting generic ...rest from object ( TS cannot do that by default )
    • you need to explicitly state generic params
    • Props generic props intersection
    • PickedProps props type from which you wanna pick properties so you get them via destructuring
    type InjectedProps = { one: number; two: boolean }
    function test<OriginalProps>(props: OriginalProps) {
      type Props = OriginalProps & InjectedProps
      const {
        // $ExpectType number
        one,
        // $ExpectType OriginalProps
        rest,
      } = pickWithRest<Props, InjectedProps>(props, ['one'])
    }

    DefaultProps<T>(props: T): Readonly<T>

    • returns frozen object ( useful for default props )

    createPropsGetter<T>(props: T): T

    Why ?

    https://medium.com/@martin_hotell/react-typescript-and-defaultprops-dilemma-ca7f81c661c7

    • use for resolving defaultProps within component implementation
    • goes side by side with DefaultProps helper/type alias
    • it's just identity function with proper props type resolution
    // $ExpectType {onClick: (e: MouseEvent<HTMLElement>) => void, children: ReactNode, color?:'blue' | 'green' | 'red', type?: 'button' | 'submit'}
    type Props = {
      onClick: (e: MouseEvent<HTMLElement>) => void
      children: ReactNode
    } & DefaultProps<typeof defaultProps>
     
    // $ExpectType Readonly<{color:'blue' | 'green' | 'red', type: 'button' | 'submit'}>
    const defaultProps = DefaultProps({
      color: 'blue' as 'blue' | 'green' | 'red',
      type: 'button' as 'button' | 'submit',
    })
    const getProps = createPropsGetter(defaultProps)
     
    class Button extends Component<Props> {
      static readonly defaultProps = defaultProps
      render() {
        const {
          // $ExpectType (e: MouseEvent<HTMLElement>) => void
          onClick: handleClick,
          // $ExpectType 'blue' | 'green' | 'red'
          color,
          // $ExpectType 'button' | 'submit'
          type,
          // $ExpectType ReactNode
          children,
        } = getProps(this.props)
     
        return (
          <button onClick={handleClick} type={type} className={color}>
            {children}
          </button>
        )
      }
    }

    React/Preact components:

    <Pre/>

    • for debugging data within your render

    2. Compile time TypeScript type helpers

    ActionsUnion<A extends StringMap<AnyFunction>> = ReturnType<A[keyof A]>

    • use for getting action types from action creators implementation
    type Actions = ActionsUnion<typeof Actions>

    ActionsOfType<ActionUnion, ActionType extends string>

    • helper for getting particular action type from ActionsUnion
    const SET_AGE = '[core] set age'
    const SET_NAME = '[core] set name'
     
    const Actions = {
      setAge: (age: number) => createAction(SET_AGE, age),
      setName: (name: string) => createAction(SET_NAME, name),
    }
     
    type Actions = ActionsUnion<typeof Actions>
     
    type AgeAction = ActionsOfType<Actions, typeof SET_AGE>
     
    const action: AgeAction = {
      type: '[core] set age',
      payload: 23,
    }

    AnyFunction = (...args: any[]) => any

    • use this type definition instead of Function type constructor

    StringMap<T> = { [key: string]: T }

    • simple alias to save you keystrokes when defining JS typed object maps
    type Users = StringMap<{ name: string; email: string }>
     
    const users: Users = {
      1: { name: 'Martin', email: 'goo@gl.com' },
      2{ name'John', email'doe@john.com' },
    }

    Constructor<T>

    • alias for the construct signature that describes a type which can construct objects of the generic type T and whose constructor function accepts an arbitrary number of parameters of any type

    Omit<T,K>

    type Result = Omit<
      {
        one: string
        two: number
        three: boolean
      },
      'two'
    >
     
    const obj: Result = {
      one: '123',
      three: false,
    }

    Diff<T extends object,K extends object>

    type Result = Diff<
      {
        one: string
        two: number
        three: boolean
      },
      {
        two: number
      }
    >
     
    const obj: Result = {
      one: '123',
      three: false,
    }

    Primitive<T>

    • narrows type to primitive JS value ( boolean, string, number, symbol )

    NonPrimitive<T>

    • narrows type to non-primitive JS value ( object, function, array )

    Nullable<T>

    • opposite of standard library NonNullable

    Maybe<T>

    • Maybe types accept the provided type as well as null or undefined

    InstanceTypes<T>

    • obtain the return type of a constructor function type within array or object.

      Like native lib.d.ts InstanceType but for arrays/tuples or objects

    class Foo {
      hello = 'world'
    }
    class Moo {
      world = 'hello'
    }
     
    const arr: [typeof Foo, typeof Moo] = [Foo, Moo]
    const obj: { foo: typeof Foo; moo: typeof Moo } = { foo: Foo, moo: Moo }
     
    // $ExpectType [Foo, Moo]
    type TestArr = InstanceTypes<typeof arr>
     
    // $ExpectType {foo: Foo, moo: Moo}
    type TestObj = InstanceTypes<typeof obj>

    Brand<T,K>

    type USD = Brand<number, 'USD'>
    type EUR = Brand<number, 'EUR'>
     
    const usd = 10 as USD
    const eur = 10 as EUR
     
    function gross(net: USD, tax: USD): USD {
      return (net + tax) as USD
    }
     
    gross(usd, usd) // ok
    gross(eur, usd) // Type '"EUR"' is not assignable to type '"USD"'.

    UnionFromTuple<T>

    • extracts union type from tuple

    FunctionArgsTuple<T>

    @DEPRECATED 👉 Instead use standard library Parameters mapped type

    This is useful with React's children as a function(render prop) pattern, when implementing HoC

    const funcTestOneArgs = (one: number) => {
      return
    }
    // $ExpectType [number]
    type Test = FunctionArgsTuple<typeof funcTestNoArgs>

    Values<T>

    • Values<T> represents the union type of all the value types of the enumerable properties in an object Type T.
    type Props = {
      name: string
      age: number
    }
     
    // The following two types are equivalent:
    // $ExpectType string | number
    type Prop$Values = Values<Props>
     
    // $ExpectType string
    const name: Prop$Values = 'Jon'
    // $ExpectType number
    const age: Prop$Values = 42

    Keys<T>

    • keyof doesn't work/distribute on union types. This mapped type fixes this issue

    KnownKeys<T>

    • gets proper known keys from object which contains index type [key:string]: any

    RequiredKnownKeys<T>

    • gets required only known keys from object which contains index type [key:string]: any

    OptionalKnownKeys<T>

    • gets optional only known keys from object which contains index type [key:string]: any

    PickWithTypeUnion<Base, Condition>

    • Pick key-values from Base provided by Condition generic type. Generic can be an union.

    NOTE: It doesn't work for undefined | null values. for that use PickWithType

    PickWithType<Base, Condition>

    • Pick key-values from Base provided by Condition generic type. Generic needs to be one type from null | undefined | object | string | number | boolean

    React related types:

    ElementProps<T>

    Gets the props for a React element type, without preserving the optionality of defaultProps. Type could be a React class component or a stateless functional component. This type is used for the props property on React.Element<typeof Component>.

    Like React.Element<typeof Component>, Type must be the type of a React component, so you need to use typeof as in React.ElementProps<typeof MyComponent>.

    NOTE: Because ElementProps does not preserve the optionality of defaultProps, ElementConfig (which does) is more often the right choice, especially for simple props pass-through as with higher-order components.

    import React from 'react'
     
    class MyComponent extends React.Component<{ foo: number }> {
      render() {
        return this.props.foo
      }
    }
     
    ;({ foo: 42 } as ElementProps<typeof MyComponent>)

    ElementConfig<T>

    Like ElementProps<typeof Component> this utility gets the type of a component’s props but preserves the optionality of defaultProps!

    Like React.Element, Type must be the type of a React component so you need to use typeof as in React.ElementProps.

    import React from 'react'
    class MyComponent extends React.Component<{ foo: number }> {
      static defaultProps = { foo: 42 }
      render() {
        return this.props.foo
      }
    }
     
    // `ElementProps<>` requires `foo` even though it has a `defaultProp`.
    ;(({ foo: 42 } as ElementProps<typeof MyComponent>)(
      // `ElementConfig<>` does not require `foo` since it has a `defaultProp`.
      {} as ElementConfig<typeof MyComponent>
    ))
    type Props = { who: string }
    type State = { count: number }
    class Test extends Component<Props, State> {}
    const TestFn = (_props: Props) => null
    const TestFnViaGeneric: SFC<Props> = (_props) => null
     
    // $ExpectType {who: string}
    type PropsFromComponent = GetComponentProps<Test>
     
    // $ExpectType {who: string}
    type PropsFromFunction = GetComponentProps<typeof TestFn>
     
    // $ExpectType {who: string}
    type PropsFromFunction2 = GetComponentProps<typeof TestFnViaGeneric>

    ElementState<T>

    Gets Component/PureComponent state type

    class MyComponent extends React.Component<{}, { foo: number }> {
      state = { foo: 42 }
      render() {
        return this.props.foo
      }
    }
     
    // $ExpectType {foo: number}
    type State = ElementState<typeof MyComponent>

    DefaultProps<T>(props: T): Partial<T>

    • type alias
    • useful for declaring Component props intersection with defaultProps

    Guides

    @TODO


    Publishing

    Execute yarn release which will handle following tasks:

    • bump package version and git tag
    • update/(create if it doesn't exist) CHANGELOG.md
    • push to github master branch + push tags
    • publish build packages to npm

    releases are handled by awesome standard-version

    Pre-release

    • To get from 1.1.2 to 1.1.2-0:

    yarn release --prerelease

    • Alpha: To get from 1.1.2 to 1.1.2-alpha.0:

    yarn release --prerelease alpha

    • Beta: To get from 1.1.2 to 1.1.2-beta.0:

    yarn release --prerelease beta

    Dry run mode

    See what commands would be run, without committing to git or updating files

    yarn release --dry-run

    Check what files are gonna be published to npm

    • yarn pack OR yarn release:preflight which will create a tarball with everything that would get published to NPM

    Tests

    Test are written and run via Jest 💪

    yarn test
    # OR
    yarn test:watch
    

    Style guide

    Style guides are enforced by robots, I meant prettier and tslint of course 🤖 , so they'll let you know if you screwed something, but most of the time, they'll autofix things for you. Magic right ?

    Style guide npm scripts

    #Format and fix lint errors 
    yarn ts:style:fix

    Generate documentation

    yarn docs

    Commit ( via commitizen )

    • this is preferred way how to create conventional-changelog valid commits
    • if you prefer your custom tool we provide a commit hook linter which will error out, it you provide invalid commit message
    • if you are in rush and just wanna skip commit message validation just prefix your message with WIP: something done ( if you do this please squash your work when you're done with proper commit message so standard-version can create Changelog and bump version of your library appropriately )

    yarn commit - will invoke commitizen CLI

    Troubleshooting

    Licensing

    MIT as always

    Keywords

    none

    Install

    npm i @martin_hotell/rex-tils

    DownloadsWeekly Downloads

    3,382

    Version

    2.1.1

    License

    MIT

    Unpacked Size

    176 kB

    Total Files

    120

    Last publish

    Collaborators

    • avatar