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.

Table of Contents

• Installation
• Usage
  • String Helpers
    • String Concatination
  • Object Helpers
    • Immutability Set Property
    • Object Filter
    • Object Map
    • Pick
    • Pick Deep
  • Utility Types
• Other Solutions
• Issues
  • 🐛 Bugs
  • 💡 Feature Requests
• Contributors ✨
• LICENSE

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):

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

LICENSE

MIT