or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

dom-enhancements.mdes2015-features.mdes5-core.mdindex.mdjson-types.mdtyped-arrays.md
tile.json

tessl/npm-better-typescript-lib

An alternative TypeScript standard library with better type definitions

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/better-typescript-lib@2.11.x

To install, run

npx @tessl/cli install tessl/npm-better-typescript-lib@2.11.0

index.mddocs/

Better TypeScript Lib

Better TypeScript Lib is an alternative TypeScript standard library that provides improved type definitions with better type safety. It replaces TypeScript's built-in any types with safer alternatives like JSONValue for JSON.parse() return values, and includes other improvements that became possible as TypeScript evolved.

Package Information

  • Package Name: better-typescript-lib
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install -D better-typescript-lib

Core Imports

For TypeScript 5.8+, add to your tsconfig.json:

{
  "compilerOptions": {
    "libReplacement": true
  }
}

For pnpm users, add to .npmrc:

public-hoist-pattern[]=@typescript/*

No explicit imports needed - the package automatically replaces TypeScript's built-in lib definitions through the @typescript/lib-* mapping mechanism.

Basic Usage

// JSON.parse now returns JSONValue instead of any
const data = JSON.parse('{"name": "Alice", "age": 30}');
// data is typed as JSONValue, not any

// eval returns unknown instead of any
const result = eval('2 + 2');
// result is typed as unknown, not any

// Better Object.hasOwnProperty type narrowing
const obj: unknown = { name: 'Bob' };
if (obj && typeof obj === 'object' && 'name' in obj) {
  // obj.name is now properly typed
}

Architecture

Better TypeScript Lib is built around several key components:

  • Lib Replacement System: Uses TypeScript 4.5+ compiler feature to detect and replace @typescript/lib-* packages
  • Type Safety Improvements: Replaces any with safer alternatives throughout the standard library
  • Build System: Generates individual npm packages from improved TypeScript lib definitions
  • Version Alignment: Tracks TypeScript releases while providing more frequent type definition improvements

The system works by mapping standard TypeScript lib imports to improved alternatives:

  • @typescript/lib-es5 → @better-typescript-lib/es5
  • @typescript/lib-dom → @better-typescript-lib/dom
  • etc.

Capabilities

Enhanced ES5 Core Library

Core JavaScript functionality with improved type safety, focusing on eval(), JSON interface, and Object methods with better type narrowing.

// JSON with safer types
interface JSON {
  parse(text: string): JSONValue;
  parse<T>(
    text: string,
    reviver: (this: any, key: string, value: JSONValueF<T>) => JSONValueF<T>
  ): JSONValueF<T>;
}

// Global functions with safer return types
declare function eval(x: string): unknown;

// Enhanced Object methods
interface Object {
  hasOwnProperty<Obj, Key extends PropertyKey>(
    this: Obj,
    v: Key
  ): this is Obj & (Key extends PropertyKey ? { [key in Key]: unknown } : {});
}

ES5 Core Library

JSON Type System

Comprehensive type definitions for JSON data structures, providing type-safe alternatives to any for JSON operations.

type JSONPrimitive = string | number | boolean | null;
type JSONValue = JSONPrimitive | JSONObject | JSONValue[];
type JSONObject = { [key: string]: JSONValue };
type JSONValueF<A> = JSONPrimitive | JSONComposite<A>;
type JSONHolder<K extends string, A> = Record<K, JSONValueF<A>>;

JSON Types

DOM and Web API Enhancements

Enhanced Body interface with safer JSON handling that returns JSONValue instead of any.

interface Body {
  json(): Promise<JSONValue>;
}

DOM Enhancements

ES2015+ Feature Improvements

Enhanced type definitions for modern JavaScript features including Promises, Collections, Iterables, and Symbols.

// Promise improvements
interface Promise<T> {
  then<TResult1 = T, TResult2 = never>(
    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined,
    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined
  ): Promise<TResult1 | TResult2>;
}

ES2015+ Features

Typed Array Enhancements

Improved method signatures for typed arrays with better this typing and type safety.

interface TypedNumberArray<TArrayBuffer extends ArrayBufferLike = ArrayBufferLike> {
  every<This = undefined>(
    predicate: (this: This, value: number, index: number, array: this) => boolean,
    thisArg?: This
  ): boolean;
  
  filter<This = undefined>(
    predicate: (this: This, value: number, index: number, array: this) => boolean,
    thisArg?: This
  ): TypedNumberArray;
}

Typed Arrays

Types

Core Utility Types

/**
 * Type casting utility
 */
type Cast<T, U> = T extends U ? T : U;

/**
 * Make all properties in T writable
 */
type Writable<T> = {
  -readonly [P in keyof T]: T[P];
};

/**
 * Intersection of array types
 */
type Intersect<T extends readonly any[]> = ((
  ...args: { [K in keyof T]: Cast<Writable<T[K]>, {}> }
) => void) extends (...args: { [K in keyof T]: infer S }) => void
  ? S
  : never;

JSON Type Definitions

type JSONPrimitive = string | number | boolean | null;
type JSONComposite<A> = { [key: string]: JSONValueF<A> } | JSONValueF<A>[];
type JSONValueF<A> = JSONPrimitive | JSONComposite<A>;
type JSONValue = JSONPrimitive | JSONObject | JSONValue[];
type JSONObject = { [key: string]: JSONValue };
type JSONHolder<K extends string, A> = Record<K, JSONValueF<A>>;