@brixtol/tsutils
TypeScript utility types used within the Brixtol Textiles monorepo workspace. This module is loosely based on type-fest in the sense that is provides some essential TypeScript types.
Install
pnpm add @brixtol/tsutils
Usage
Import the module via namespace. The below example shows a couple of utilities. For additional context look in the test directory.
import { AnyCase, ArrayMin, ConcatUnion } from '@brixtol/tsutils';
let string: AnyCase<'foo'>; // 'FOO' | 'FoO' | 'fOO' etc etc
let concat: ConcatUnion<'A' | 'B', '-'>; // 'A' | 'B' | 'A-B' etc etc
let arrmin: ArrayMin<2, string>; // ['a', 'b']
// etc etc
Utilities
The package provides several useful TypeScript utilities. If you require more then look at type-fest. Below are some basic examples of whats included and how to use them.
AnyCase<string>
Converts a string union into and AnyCase combination,
const anycase: AnyCase<'foo'> = (
| 'FOO'
| 'fOO'
| 'foO'
| 'Foo'
| 'FOo'
| 'foo'
| 'fOo'
| 'FoO'
);
ArrayFixed<number, type>
Ensures an array has a fixed length, where it cannot be any more or any less than the length provided.
// ✓ VALID
const a: ArrayFixed<2, string> = ['A', 'B'];
const b: ArrayFixed<3, string> = ['A', 'B', 'C'];
// 𐄂 INVALID
const c: ArrayFixed<2, string> = ['A'];
ArrayMax<number, type>
Ensures an array has a max length. If the size of the array exceeds the length an error will be thrown.
// ✓ VALID
const a: ArrayMax<3, string> = ['A', 'B'];
const b: ArrayMax<4, string> = ['A', 'B', 'C'];
// 𐄂 INVALID
const c: ArrayMax<2, string> = ['A', 'B', 'C'];
ArrayMin<number, type>
Ensures an array type has a minimum length. If the size of the array is less than the length an error will be thrown.
// ✓ VALID
const a: ArrayMin<2, string> = ['A', 'B'];
const b: ArrayMin<3, string> = ['A', 'B', 'C'];
// 𐄂 INVALID
const c: ArrayMin<2, string> = ['A'];
ArrayRange<number, number, type>
Ensures an array length is more than the from size and less than the to size.
// ✓ VALID
const a: ArrayRange<2, 4, string> = ['A', 'B'];
const b: ArrayRange<1, 3, string> = ['A', 'B', 'C'];
// 𐄂 INVALID
const c: ArrayRange<2, 4, string> = ['A'];
ConcatUnion<union, separator>
Concatenates a string union including values from the union type and custom separator.
const union: ConcatUnion<'A' | 'B' | 'C', '-'> = (
| 'A'
| 'B'
| 'C'
| 'A-B'
| 'B-A'
| 'A-C'
| 'B-C'
| 'A-B-C'
| 'B-A-C'
| 'C-A'
| 'C-B'
| 'C-A-B'
| 'C-B-A'
);
Join<string, separator>
Join an array of strings and/or numbers using the given string as a delimiter. Used for defining key paths in a nested object.
Lifted from type-fest
// Mixed (strings & numbers) items; result is: 'foo.0.baz'
const path: Join<['foo', 0, 'baz'], '.'> = 'foo.0.baz';
*
// Only string items; result is: 'foo.bar.baz'
const path: Join<['foo', 'bar', 'baz'], '.'> = 'foo.bar.baz'
*
// Only number items; result is: '1.2.3'
const path: Join<[1, 2, 3], '.'> = [1, 2, 3].join('.');
JoinProps<object, separator?>
Deeply references object keys to generate a string literal flattened union with an option separator character which will default to . dot.
const props: JoinProps<{
a: string;
b: {
c: string;
d: {
e: {
f: string;
g: string;
}[];
}
}
> = (
| "a"
| "b"
| "b.c"
| "b.d.e"
| "b.d"
| `b.d.e.${number}.f`
| `b.d.e.${number}.g`
| `b.d.e.${number}`
)
LiteralUnion<union>
Allows string types to be passed while respecting intellisense completions.
const literal: LiteralUnion<'A' | 'B'> = (
| 'A'
| 'C'
| 'D' // D is allowed to pass
)
Merge<object, object>
Merge two types into a new type. Keys of the second type overrides keys of the first type.
Lifted from type-fest
type Foo = { a: number; b: string };
type Bar = { b: number };
const ab: Merge<Foo, Bar> = { a: 1, b: 2 };
NumberRange<number, number>
Generates a number union between 2 numbers excluding the TO number limit, returning only the range between.
const range: Range<1, 5> = (
| 1
| 2
| 3
| 4
)
ObjectEntries<object>
Converts an object to a array entries list. Its a type equivalent for Object.entries() method.
const entries: ObjectEntries<{
foo: { a: 1 },
bar: { a: 2 }
}> = (
[
['foo', { a: 1 }],
['bar', { a: 2 }],
]
)
OmitProps<string[], object | object[]>
Used to exclude object properties from a string list and will return the retained properties of the object. When passing an Array interface type the returning value will be array, else return value is object.
// OBJECT RETURN TYPE
const array: OmitProps<[
'foo',
'baz'
], {
foo: { a: string },
bar: { a: string },
baz: { a: string }
}> = {
bar: { a: 'one' },
}
// ARRAY RETURN TYPE
const array: OmitProps<[
'foo',
'baz'
], Array<{
foo: { a: string },
bar: { a: string },
baz: { a: string }
}>
> = [
{
bar: { a: 'one' },
}
]
PartialDeep<object>
Used to create a type from another type with all keys and nested keys set to optional.
Lifted from type-fest
interface IObject {
deep: {
a: string;
b: string;
c: {
d: any;
e: number;
f: {
g: string[]
}
}
}
}
// RESULT
const object: PartialDeep<IObject> = {
deep: {
a: 'foo'
}
};
PickProps<string[], object | object[]>
Used to pick object properties from a string list and will return the selected properties on the object. When passing an Array interface type the returning value will be array, else return value is object.
// OBJECT RETURN TYPE
const array: PickProps<[
'foo',
'baz'
], {
foo: { a: string },
bar: { a: string },
baz: { a: string }
}> = {
foo: { a: 'one' },
baz: { a: 'one' },
}
// ARRAY RETURN TYPE
const array: OmitProps<[
'foo',
'baz'
], Array<{
foo: { a: string },
bar: { a: string },
baz: { a: string }
}>
> = [
{
foo: { a: 'one' },
baz: { a: 'one' },
}
]
Split<string, separator>
Represents an array of strings split using a given character or character set. Typically used on a return type method like String.prototype.split.
Lifted from type-fest
const split: Split<'a,b,c,d', ','> = ['a','b','c','d']
Valueof<object>
Opposite of keyof returning object values as a union type.
const values: Valueof<{
foo: 'a',
bar: 'b',
baz: 'c'
}> = (
| 'a'
| 'b'
| 'c'
)
License
Licensed under MIT
We ♡ open source!