Ts-roids NPM | npm.io

ts-roids

100+ types and decorators to bullet proof TypeScript even more.

Types

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.
Abs<N> - Get the absolute value of a Numeric.
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.
Falsy - Represents a type that is falsy JavaScript.
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.
Maybe<T> - Type that might be Nullable
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.
Primitive - All primitive types.
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.

Decorators

@Final - Marks an object final, as in one cannot inherit from it.
@Sealed - Seals an object.
@Frozen - Freezes an object.

Basic Usage

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'