ts-util-helpers

TypeScript first utility helpers

The problem

Sometimes, in particular with developer tooling, you want to have immensely
tight type strictness in your TypeScript codebase. However, to make your
extremely code type strict can be
difficult to maintain, to say the least.

While type strictness can be overused in some instances, in others it allows you
to be confident in the code you’re shipping, and provide a uniquely strong
developer experience.

This solution

This library provides extremely restrictive typings to common (and somewhat
niche) utilities such as picking keys from an object.

We’ve written some utilities that don’t exist elsewhere that contain extremely
complex TypeScript typings in the name of retaining as strict of type
information as the compiler allows us to. We pull out all the stops to make that
happen.

Installation

This module is distributed via npm which is bundled with node and
should be installed as one of your project’s dependencies:

npm install --save ts-util-helpers

Usage

We provide a myriad of utilities for your usage.

String Helpers

String Concatination

You can choose to use the implemented TS logic:

import {concatStr} from 'ts-util-helpers'

// Pseudo-code typing:
// concatStr<R extends string>(...string[]): R;
concatStr('H', 'i', '!') // Type is "Hi!"
concatStr('Hi!') // Type is "Hi!"
const constStr = 'Hi!' as const
concatStr(constStr) // Type is "Hi!"
// Strings must be `as const` for type strictness to apply
const str = 'Hi!'
concatStr(str) // Type is string

Or, if you just need the TS typing:

import type {JoinStr} from 'ts-util-helpers';

JoinStr<["H", "i"]> // Type is "Hi!"

Object Helpers

Immutability Set Property

This function takes three properties:

  1. An object
  2. A key name
  3. A value to set to the key name

And returns a new object for you to use with said key updated.

import {objectImmutablySetProp} from 'ts-util-helpers'

// Return type is `{welcomeMsg: "Hello, world!"}
objectImmutablySetProp({welcomeMsg: 'Hey'}, 'welcomeMsg', 'Hello, world!')

This is what it’s doing under-the-hood at runtime:

return {...object, [key]: val}

While the logic of this is quite simple, the typings can be somewhat tricky if
you’re not familiar with mapped generics to get only the single key updating.

Object Filter

Similar to Array.filter, objectFilter allows you to take:

  1. An object to iterate through
  2. A callback

And filter out the keys based on said callback from the returned object.

The callback receives three properties:

  1. The value of the key being inspected
  2. The key name being inspected
  3. The full object

import {objectFilter} from 'ts-util-helpers'

// Return type is Optional<{a: 1, b: 2, c: 3}>
// Return value is {a: 1, b: 2}
objectFilter({a: 1, b: 2, c: 3}, val => val <= 2)

If you know how to make this function more type-strict, please make a pull
request or open an issue and let us know! We tried for ages to
experiment different ways

Object Map

Similar to Array.map, objectMap allows you to take:

  1. An object to iterate through
  2. A callback

And map keys’ values based on said callback from the returned object.

The callback receives three properties:

  1. The value of the key being inspected
  2. The key name being inspected
  3. The full object

import {objectMap} from 'ts-util-helpers'

// Return type is Optional<{a: number, b: number, c: number}>
// Return value is {a: 3, b: 4, c: 5}
objectMap({a: 1, b: 2, c: 3}, val => val + 2)

// Return type is Optional<{a: "a" | "b" | "c", b: "a" | "b" | "c", c: "a" | "b" | "c"}>
// Return value is {a: "a", b: "b", c: "c"}
objectMap({a: 1, b: 2, c: 3}, (_, key) => key)

// Return type is Optional<{a: number, b: number, c: number}>
// Return value is {a: 3, b: 3, c: 3}
objectMap({a: 1, b: 2, c: 3}, (_, __, obj) => Object.keys(obj).length)

If you know how to make this function more type-strict, please make a pull
request or open an issue and let us know! We tried for ages to
experiment different ways

Pick

There are often times where you may want to object destructure values from an
array that’s passed in during runtime, but don’t want to lose your type
strictness.

While solutions like _.pick allow you
to get the values, you’d have to manually re-type everything.

This is where pick comes into play.

import {pick} from 'ts-util-helpers'

// Return type is {test: 1, other: 2}
pick({test: 1, other: 2, ignored: 3} as const, ['test', 'other'])

This utility only supports the top-most level of keys in an object. If you
need something that can handle any depth,
see our “pick deep” utility if you need arbitrary depth

Pick Deep

This utility provides an almost-GQL-like query interface
to pick only the keys you need from an object at any depth.

It takes two arguments:

  1. The object to get values from
  2. The query object, telling the utility what object to get values from

import {pickDeep} from 'ts-util-helpers'

const obj = {
  key: 'Hello',
  ignored: 1,
  exlcluded: 2,
  arr: [{objVal: 3}],
  deepObj: {
    num: 4,
    deeper: {
      val: 5,
      ignored: 6,
    },
  },
} as const

const queryObj = {
  key: true,
  excluded: false,
  arr: {
    objVal: true,
  },
  deepObj: {
    num: true,
    deeper: {
      val: true,
    },
  },
} as const

pickDeep(obj, queryObj)

/*
// Return type and value is:
{
    key: "Hello",
    arr: [
        {objVal: 3}
    ],
    deepObj: {
        num: 4,
        deeper: {
            val: 5
        }
    }
}
*/

The query object must have a true or false value passed to grab the
underlying value or not. To query for arrays, simply pass an argument that
aligns with the underlying types.

We will also enforce the required queryObj to be the same expected shape as
the obj, if you don’t see this behavior – consider it a bug.

While you can true or false any object key, you cannot do so if the key’s
value is an array or object currently.

This means that while this works:

pickDeep(
  {parent: {child: 1}},
  {
    parent: {
      child: true,
    },
  },
)

This does not:

pickDeep(
  {parent: {child: 1}},
  {
    parent: true,
  },
)

This is a limitation with our typings currently and should be fixed in the
future.

Utility Types

import type {OnlyOptional, OnlyNonOptional} from 'ts-util-helpers';

type Obj = {
    optional?: 1,
    required: 2
}
OnlyOptional<Obj>; // Type will be {optional?: 1}
OnlyNonOptional<Obj>; // Type will be {required: 2}

Other Solutions

  • Type Fest provides some great
    utility types without implementations
  • Lodash provides some (usually less strictly typed)
    utility functions

If you know more, please make a pull request and add it here!

Issues

Looking to contribute? Look for the Good First Issue
label.

? Bugs

Please file an issue for bugs, missing documentation, or unexpected behavior.

See Bugs

? Feature Requests

Please file an issue to suggest new features. Vote on feature requests by adding
a ?. This helps maintainers prioritize what to work on.

See Feature Requests

Contributors ✨

Thanks goes to these people (emoji key):


Corbin Crutchley
? ? ? ⚠️

This project follows the all-contributors specification.
Contributions of any kind welcome!

LICENSE

MIT

GitHub