ts-util-helpers
TypeScript first utility helpers
!Build Statusbuild-badgebuild !Code Coveragecoverage-badgecoverage !versionversion-badgepackage !downloadsdownloads-badgenpmtrends !MIT Licenselicense-badgelicense !All Contributorsall-contributors-badge !PRs Welcomeprs-badgeprs !Code of Conductcoc-badgecoc
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 aspick
ing 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
- String Helpers
- [String Concatination](#string-concatination)
- Object Helpers- [Immutability Set Property](#immutability-set-property)
- [Object Filter](#object-filter)
- [Object Map](#object-map)
- [Pick](#pick)
- [Pick Deep](#pick-deep)
- Utility Types
- 🐛 Bugs
- 💡 Feature RequestsInstallation
This module is distributed via npmnpm which is bundled with nodenode and should be installed as one of your project'sdependencies
: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:- An object
- A key name
- 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 toArray.filter
, objectFilter
allows you to take:- An object to iterate through
- A callback
And filter out the keys based on said callback from the returned object.
The callback receives three properties:
- The value of the key being inspected
- The key name being inspected
- 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 requestprs or open an issue and let us know! We tried for ages to experiment different ways
Object Map
Similar toArray.map
, objectMap
allows you to take:- An object to iterate through
- A callback
And map keys' values based on said callback from the returned object.
The callback receives three properties:
- The value of the key being inspected
- The key name being inspected
- 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 requestprs 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:
- The object to get values from
- 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 cantrue
orfalse
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
- Lodash provides some (usually less strictly typed)
If you know more, please make a pull requestprs and add it here!
Issues
Looking to contribute? Look for the Good First Issuegood-first-issue label.🐛 Bugs
Please file an issue for bugs, missing documentation, or unexpected behavior.See Bugsbugs
💡 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 Requestsrequests
Contributors ✨
Thanks goes to these people (emoji keyemojis):This project follows the all-contributorsall-contributors specification. Contributions of any kind welcome!