@rcompat/type

TypeScript utility types for JavaScript runtimes.

What is @rcompat/type?

A collection of TypeScript utility types for type-level programming. Includes type predicates, transformations, and common type aliases. Works consistently across Node, Deno, and Bun.

Installation

npm install @rcompat/type

pnpm add @rcompat/type

yarn add @rcompat/type

bun add @rcompat/type

Usage

Basic types

import type { Dict, Maybe, Nullish, Primitive } from "@rcompat/type";

// Dict<V> = Record<string, V>
const config: Dict<string> = { host: "localhost", port: "3000" };

// Maybe<T> = T | undefined
function find(id: number): Maybe<User> {
  return users.get(id);
}

// Nullish = null | undefined
function isNullish(value: unknown): value is Nullish {
  return value == null;
}

// Primitive = bigint | boolean | null | number | string | symbol | undefined
function isPrimitive(value: unknown): value is Primitive {
  return value !== Object(value);
}

Type predicates

import type { IsAny, IsNever, IsUnion, IsTuple, IsArray } from "@rcompat/type";

// check if type is `any`
type A = IsAny<any>; // true
type B = IsAny<string>; // false

// check if type is `never`
type C = IsNever<never>; // true
type D = IsNever<void>; // false

// check if type is a union
type E = IsUnion<string | number>; // true
type F = IsUnion<string>; // false

// check if type is a tuple
type G = IsTuple<[string, number]>; // true
type H = IsTuple<string[]>; // false

// check if type is an array
type I = IsArray<string[]>; // true
type J = IsArray<[string]>; // true (tuples are arrays)

Type transformations

import type {
  Mutable, DeepMutable, Not, UnionToTuple, TupleToUnion,
} from "@rcompat/type";

// remove readonly modifier
type Writable = Mutable<Readonly<{ a: string }>>;
// { a: string }

// recursively remove readonly
type DeepWritable = DeepMutable<
    Readonly<{ nested: Readonly<{ value: number }> }>
>;
// { nested: { value: number } }

// boolean negation
type Yes = Not<false>; // true
type No = Not<true>; // false

// convert union to tuple
type Tuple = UnionToTuple<"a" | "b" | "c">;
// ["a", "b", "c"]

// convert tuple to union
type Union = TupleToUnion<["a", "b", "c"]>;
// "a" | "b" | "c"

Function types

import type { Newable, UnknownFunction } from "@rcompat/type";

// constructor type
function createInstance<T>(Ctor: Newable<T>): T {
  return new Ctor();
}

// generic function signature
function wrap(fn: UnknownFunction) {
  return (...args: unknown[]) => fn(...args);
}

JSON types

import type { JSONValue, Serializable } from "@rcompat/type";

// calid JSON value
const data: JSONValue = {
  name: "Bob",
  age: 30,
  active: true,
  tags: ["admin", "user"],
};

// implement custom serialization
class User implements Serializable {
  constructor(private id: number, private name: string) {}

  toJSON(): JSONValue {
    return { id: this.id, name: this.name };
  }
}

Async types

import type { MaybePromise } from "@rcompat/type";

// value or Promise of value
async function process(input: MaybePromise<string>): Promise<string> {
  const value = await input;
  return value.toUpperCase();
}

process("hello"); // works
process(Promise.resolve("hello")); // also works

API Reference

Basic Types

| Type | Definition | | ---------------- | ---------------------------------------------------------------------- | | Dict<V> | Record<string, V> | | PartialDict<V> | Partial<Record<string, V>> | | Entry<K, T> | [K, T] tuple | | EmptyObject | Empty object {} | | Maybe<T> | T \| undefined | | Nullish | null \| undefined | | Primitive | bigint \| boolean \| null \| number \| string \| symbol \| undefined | | Boolish | "true" \| "false" | | Some<T> | true if any element in boolean tuple is true |

Type Predicates

| Type | Returns true when... | | -------------- | ----------------------- | | IsAny<T> | T is any | | IsNever<T> | T is never | | IsUnknown<T> | T is unknown | | IsVoid<T> | T is void | | IsUnion<T> | T is a union type | | IsArray<T> | T is an array type | | IsTuple<T> | T is a tuple type | | IsClass<T> | T is a class instance |

Transformations

| Type | Description | | ------------------------ | -------------------------------------- | | Mutable<T> | Remove readonly modifier | | DeepMutable<T> | Recursively remove readonly | | Not<T> | Boolean negation (true ↔ false) | | UnionToTuple<U> | Convert union to tuple type | | TupleToUnion<T> | Convert tuple to union type | | UndefinedToOptional<T> | Make undefined properties optional | | Unpack<T> | Flatten/expand type for better display |

Function Types

| Type | Definition | | ----------------------- | ----------------------------------- | | Newable<I, A> | new (...args: A) => I | | AbstractNewable<I, A> | Abstract constructor type | | UnknownFunction | (...params: unknown[]) => unknown |

JSON & Serialization

| Type | Description | | -------------- | ---------------------------------------------- | | JSONValue | Valid JSON types (primitives, arrays, objects) | | Serializable | Interface with toJSON(): JSONValue method | | JSONPointer | JSON pointer path type |

Async Types

| Type | Definition | | ----------------- | ----------------- | | MaybePromise<T> | T \| Promise<T> |

Special Types

| Type | Description | | ------------- | --------------------------------------------- | | Print<T> | Convert type to string literal representation | | TypedArray | Union of all typed array types | | Join<T, D> | Join string tuple with delimiter | | StringLike | string \| { toString(): string } | | StringClass | Interface for string-like classes | | Printable | Interface with print(): string method | | Import<T> | Dynamic import result type |

Examples

Type-safe event emitter

import type { Dict, UnknownFunction } from "@rcompat/type";

type Events = Dict<UnknownFunction[]>;

class Emitter<E extends Events> {
  #events: Partial<E> = {};

  on<K extends keyof E>(event: K, handler: E[K][number]) {
    (this.#events[event] ??= [] as E[K]).push(handler);
  }
}

Conditional type utilities

import type { IsUnion, UnionToTuple } from "@rcompat/type";

type UnionLength<U> = UnionToTuple<U>["length"];

type A = UnionLength<"a" | "b" | "c">; // 3
type B = UnionLength<string>; // 1

JSON validation

import type { JSONValue } from "@rcompat/type";

function parseJSON(text: string): JSONValue {
  return JSON.parse(text);
}

function stringify(value: JSONValue): string {
  return JSON.stringify(value);
}

Optional undefined properties

import type { UndefinedToOptional } from "@rcompat/type";

type Input = {
  required: string;
  optional: string | undefined;
};

type Output = UndefinedToOptional<Input>;
// { required: string; optional?: string }

Cross-Runtime Compatibility

| Runtime | Supported | | ------- | --------- | | Node.js | ✓ | | Deno | ✓ | | Bun | ✓ |

No configuration required — just import and use.

License

MIT

Contributing

See CONTRIBUTING.md in the repository root.