npm
npm i ts-roids
pnpm
pnpm i ts-roids
If you're only using types, you can install it as a devDependency
.
And if you're using decorators, set this.
{
"compilerOptions": {
// ...
"experimentalDecorators": true
}
}
Requires TypesScript v5.0
+
Checkout the full API reference for all usage examples with details.
PartializedUnion<T>
- Creates a union type where each variant has its specific properties required, while other properties are optional.
Prune<T,N = NotIncluded>
- Prune a type T
by recursively omitting properties of type N
(defaults to NotIncluded
).
DeepToPrimitive<Obj>
- Recursively transforms an object type T into a type where all properties are replaced with their corresponding primitive types.
Assign<Obj,ObjArr>
- Copies all enumerable own properties from one target object to a source array of objects.
DeepImmutable<Obj>
- Recursively turns the proprties within a given object type T
immutable, as in have all the properties with the readonly
modifier.
Deepmutable<Obj>
- Recursively mutates all the proprties within a given object type T
, as in have all the properties without the readonly
modifier.
DeepRequired<Obj>
- Recursively make all object properties required.
DeepNotRequired<Obj>
- Recursively make all object properties not required.
DeepOmit<Obj,P>
- Recursively omits specified nested properties from an object, based on a given predicate P
.
DeepPick<Obj,P>
- Deeply pick properties from a nested object, based on a given predicate P
.
EmptyObject
- Represents any non-nullish value, basically {}
.
EqualStrlen<S1, S2>
- Check if two strings S1
and S2
have the same length.
PartialExcept<T, P>
- Makes all properties in T
optional except those in K
which remain required.
FilterBy<Obj, P>
- Filters keys from the object type Obj
based on a specified predicate P
.
Flip<Obj>
- Flips keys with values of an object type Obj
.
Float<N>
- Type representing a float.
If<C, Do, Else>
- If C
evaluates true
, Do
, otherwise return Else
.
IfEquals<T, P, Do, Else>
- Checks if type T
is equal to type P
. If T
is equal to P
, the type resolves to Do
, otherwise Else
.
IfExtends<T, P, Do, Else>
- Checks if type T
extends type P
. if it does, the type resolves to Do
, otherwise Else
.
ImmutableKeys<Obj>
- Retrieves the keys that are immutable (readonly
) from an object of type Obj
.
Integer<N>
- Represents an integer.
And<B1,B2>
- Logical AND between two boolean types.
ArrayFilter<Arr,P>
- Filters elements from an array based on a given predicate type.
ArrayIncludes<Arr,T>
- Checks if a given type is in an array.
ArrayIntersection<Arr>
- Calculates the intersection of the types within an array Arr
of tuple types.
ArrayMax<Arr>
- Extracts the maximum Numeric
(positive and negative) value in a given array.
ArrayMin<Arr>
- Extracts the minimum Numeric
(positive and negative) value in a given array.
ArrayTranspose<Arr>
- Transposes a given 2xN array or matrix, flipping the matrix over its diagonal, switching its row and column indices.
ArrayUnique<Arr>
- Constructs a new array containing only unique elements from a given array type.
EitherOneOrMany<T>
- Represents a type that can be either a single value of type T
or an array of values of type T
.
Nullable
- Represents any non-nullish value, basically {}
.
Equals<X,Y>
- Checks if two types X
and Y
are exactly equal.
EvenNumeric<T>
- Represents an even Numeric
.
ExcludeNull<T>
- Excludes null
from a type T
.
ExcludeNullable<T>
- Excludes Nullable
from a type T
.
ExcludeUndefined<T>
- Excludes undefined
from a type T
.
KeysOfUnion<T>
- Extracts the union of keys from a given union of object types, useful for accessing all possible keys in unions.
Simplify<T>
- Flattens the structure of a type by resolving intersections and simplifying nested mapped types, enhancing readability.
Extends<T,U>
- Evaluates whether one type T
is assignable to another type U
.
FalsyProperties<T>
- Extracts falsy properties from an object type T
.
IsArrayIncludesTypeof<Arr, T>
- Checks if an array type Arr
includes one or more of T
type.
IsBigInt<T>
- Checks if T
is a bigint
.
IsBoolean<T>
- Checks if T
is a boolean
.
IsDeepImmutable<Obj>
- Checks if all the nested properties of a given object Obj
are immutable.
IsDeepMutable<Obj>
- Checks if all the nested properties of a given object Obj
are mutable.
IsDeepNotRequired<Obj>
- Checks if all the properties of a given object (nested) are not required, as in, all properties have the ?
modifier.
IsDeepRequired<Obj>
- Checks if all the properties of a given object (nested) are required, as in, all properties do not have the ?
modifier.
IsExactlyAny<T>
- Checks if a type T
is exactly any
.
IsExactlyBigInt<T>
- Checks if a type T
is exactly bigint
not a subtype of it.
IsExactlyNumber<T>
- Checks if a type T
is exactly number
not a subtype of it.
IsExactlyString<T>
- Checks if a type T
is exactly string
not a subtype of it.
IsExactlySymbol<T>
- Checks if a type T
is exactly symbol
not a subtype of it.
IsExactlyUnknown<T>
- Checks if a type T
is exactly unknown
not a subtype of it.
IsFalsy<T>
- Checks if a given type T
is Falsy
.
IsFloat<N>
- Checks if a given type T
is a Float<N>
.
IsFunction<T>
- Checks if a given type T
is a function.
IsInteger<N>
- Checks if a given Numeric
is an Integer<N>
.
IsNever<T>:
- Checks if a type T
does not resolve, so never
.
IsNewable<T>
- Checks if a type T
is Newable
.
IsNullable<T>
- Checks if a type T
is Nullable
.
IsNumber<T>
- Checks if a type T
is a number
.
IsNumeric<T>
- Checks if a type T
is Numeric
.
IsObject<T>
- Checks if a given type T
qualifies as an object.
IsString<T>
- Check if a given type T
is a string
.
IsSymbol<T>
- Check if a given type T
is a symbol
.
IsTruthy<T>
- Check if a given type T
resolves to a truthy value.
Keys<T>
- Retrieves the union type of keys (property names) of a type T
.
MaybeUndefined<T>
- Type that might undefined
.
MutableKeys<Obj>
- Retrieves the keys that are mutable from an object of type Obj
.
Nand<B1, B2>
- Logical NAND
between two boolean types B1
and B2
.
NegativeFloat<N>
- Represents a negative (]-∞, 0[) Float<N>
.
NegativeFloatString<S>
- Represents a negative Float<N>
parsed from a string
.
NegativeInteger<N>
- Represents a negative (]-∞, 0[) Integer<N>
.
NegativeIntegerString<S>
- Represents a negative Integer<N>
parsed from a string
.
NewType<New, Base>
- Represents a new unique type derived from an existing base type. (branded type)
Newable
- Represents constructor functions that can be invoked using the new keyword.
NonRequiredKeys<Obj>
- Returns all non required keys of an object Obj
, as in any property of an object that is marked with ?
operator.
Not<B>
- Negates a boolean type B
.
Nullable
- Represents a type that can either be null
or undefined
.
Numeric
- Represents a type that can either be number
or bigint
.
NumerifyString<S>
- Turn a given string literal to a Numeric
, if possible.
Methods<Obj>
- Get the literal names of keys that are methods in an object type Obj
.
Properties<Obj>
- Get the literal names of keys that are properties in an object type Obj
.
OddNumeric<T>
- Represents an odd Numeric
.
OmitByType<Obj, T>
- Get a set of properties from Obj
whose type are not assignable to T
.
OmitCommonKeys<Obj1, Obj2>
- Omit any common key between the the two objects,.
OmitExactlyByType<Obj, T>
- Omit properties from Obj
whose type exactly matches T
.
Optional<T>
- Represents a type that may be null
, similar to Python's Optional
type and Rust's Option
enum.
Or<B1, B2>
- Logical OR
between two boolean types B1
and B2
.
PickByType<Obj, T>
- Pick from Obj
a set of properties that match the type T
.
PickCommonKeys<Obj1, Obj2>
- Get the common keys between two objects.
PickExactlyByType<Obj, T>
- Get a set of properties from Obj
whose type exactly matches T
.
PositiveFloat<N>
- Represents a positive ([0, +∞[) Float<N>
.
PositiveFloatString<S>
- Represents a positive Float<N>
parsed from a string
.
PositiveInteger<N>
- Represents a positive ([0, +∞[) Integer<N>
.
PositiveIntegerString<S>
- Represents a negative Integer<N>
parsed from a string
.
ReplaceKeys<Obj1,P,Obj2>
- Constructs a new type by replacing properties P
of type Obj
with object type Obj2
.
RequiredKeys<Obj>
- Get the required keys of an object (shallow).
SizedTuple<T,N>
- Creates a tuple with a specific length, where each element is of a given type.
StringEndsWith<S,E>
- Checks if a string S
ends with E
StringStartsWith<S,St>
- Checks if a string S
starts with St
StringifyPrimitive<P>
- Turns a given Primitive
value (except symbol
) into its string representation.
Strlen<S>
- Get the length of a string S
.
TestType<T1, T2, Expected>
- Tests if type T1
and T2
are the same.
TruthyProperties<T>
- Extracts truthy properties from an object type T
.
UnionToIntersection<U>
- As the name implies, it turns a union into an intersection.
Vals<Obj>
- Get the set of type values in a given object.
Xor<B1, B2>
- Exclusive OR
between two boolean types B1
and B2
.
@Final
- Marks an object final, as in one cannot inherit from it.@Sealed
- Seals an object.@Frozen
- Freezes an object.Finalize and freeze objects
import type { Optional, NewType, MaybeUndefined } from 'ts-roids';
import { Final, Frozen } from 'ts-roids';
type Bar = NewType<'Bar', string>;
type Baz = NewType<'Baz', string>;
type Secret = NewType<'Secret', string>;
abstract class BaseFoo<T> {
abstract requestFoo(secret: Secret, baz: Baz): Optional<T>;
}
@Final
@Frozen
class Foo<T> extends BaseFoo<T> {
readonly foo: T;
bar: Optional<Bar>;
constructor(foo: T, bar?: MaybeUndefined<Bar>) {
super();
this.foo = foo;
this.bar = bar ?? null;
}
requestFoo(secret: Secret, baz: Baz): Optional<T> {
// A function whose declared type is neither 'undefined', 'void', nor 'any' must return a value
if (
secret.concat().toLowerCase() === '123' &&
baz.concat().toLowerCase() === 'baz' &&
this.bar !== null
) {
return this.foo;
}
return null; // So you have to explicitly return null here.
}
}
class SubFoo extends Foo<string> {
constructor(foo: string) {
super(foo);
}
}
// No problem with instantiation
const foo = new Foo<string>('foo');
// Since the object is final:
// The line below will cause a TypeError: Cannot inherit from the final class Foo
const _ = new SubFoo('subFoo');
// Since the object is frozen:
// The line below will cause a TypeError: Cannot add property 'requestFoo', object is not extensible
foo.requestFoo = () => {
return 'not foo';
};
// The line below will cause a TypeError: Cannot assign to read only property 'bar'
foo.bar = 'not bar' as Bar;
The TypeScript team has not yet introduced a built-in final modifier yet, check
this, this and many other requests.
Although they introduced override
in v4.3
.
Decorators like @Final
provide a limited way to emulate final behavior, these are merely band-aids for now, until TS officially supports a true final modifier.
You can also seal an object btw.
@Sealed
class Person {
constructor(name: string, age?: number) {}
}
const john = new Person('John', 30);
// Existing properties can still be modified
john.age = 31; // No Errors
// Existing properties cannot be re-configured nor deleted
(john as any).email = 'john@doe.com'; // TypeError: Cannot add property email,
// object is not extensible
delete john.age; // TypeError: Cannot delete property 'age'
See releases.