@tsonic/types

TypeScript type definitions for CLR/.NET primitives.

Installation

npm install @tsonic/types

Usage

Named Imports

import { int, decimal, bool, long } from "@tsonic/types";

const age: int = 42 as int;
const price: decimal = 99.99 as decimal;
const isActive: bool = true as bool;
const timestamp: long = Date.now() as long;

Global Types

Add to your tsconfig.json:

{
  "compilerOptions": {
    "types": ["@tsonic/types/global"]
  }
}

Or use a triple-slash reference:

/// <reference types="@tsonic/types/global" />

const count: int = 10 as int;

Available Types

Integer Types

| Type | CLR Type | Range | Bytes | |------|----------|-------|-------| | sbyte | System.SByte | -128 to 127 | 1 | | byte | System.Byte | 0 to 255 | 1 | | short | System.Int16 | -32,768 to 32,767 | 2 | | ushort | System.UInt16 | 0 to 65,535 | 2 | | int | System.Int32 | -2,147,483,648 to 2,147,483,647 | 4 | | uint | System.UInt32 | 0 to 4,294,967,295 | 4 | | long | System.Int64 | ~-9.2e18 to ~9.2e18 | 8 | | ulong | System.UInt64 | 0 to ~1.8e19 | 8 | | nint | System.IntPtr | Platform-dependent | 4/8 | | nuint | System.UIntPtr | Platform-dependent | 4/8 | | int128 | System.Int128 | 128-bit signed | 16 | | uint128 | System.UInt128 | 128-bit unsigned | 16 |

Floating-Point Types

| Type | CLR Type | Precision | Bytes | |------|----------|-----------|-------| | half | System.Half | 16-bit float | 2 | | float | System.Single | 32-bit float | 4 | | double | System.Double | 64-bit float | 8 | | decimal | System.Decimal | 128-bit decimal | 16 |

Other Types

| Type | CLR Type | Description | |------|----------|-------------| | bool | System.Boolean | Boolean value | | char | System.Char | Single UTF-16 code unit |

Parameter Modifiers

| Type | C# Modifier | Description | |------|-------------|-------------| | ref<T> | ref | Reference parameter (read/write) | | out<T> | out | Output parameter (write-only) | | In<T> | in | Readonly reference parameter |

Unsafe Types

| Type | C# Type | Description | |------|---------|-------------| | ptr<T> | T* | Unsafe pointer type |

Implementation

These types use TypeScript's branded types pattern to provide type safety without runtime overhead:

export type int = number & { __brand: "int" };

The types are distinguishable at compile time but compile down to standard JavaScript primitives. There are no wrapper classes or runtime checks.

Examples

Type Safety

import { int, long } from "@tsonic/types";

const age: int = 42 as int;
const timestamp: long = Date.now() as long;

// Type error: Type 'long' is not assignable to type 'int'
const invalid: int = timestamp;

// Explicit cast required
const valid: int = timestamp as unknown as int;

Collections

import { int, decimal } from "@tsonic/types";

const scores: Array<int> = [95, 87, 92].map(x => x as int);
const prices: Array<decimal> = [9.99, 14.99].map(x => x as decimal);

Function Parameters

import { int, bool } from "@tsonic/types";

function setAge(age: int): void {
  console.log(`Age set to ${age}`);
}

function isValid(value: int): bool {
  return (value > 0) as bool;
}

setAge(25 as int);
const result: bool = isValid(10 as int);

Parameter Modifiers

import { int, ref, out, In } from "@tsonic/types";

// ref parameter - can read and write
function swap(a: ref<int>, b: ref<int>): void {
  const temp = a;
  a = b;
  b = temp;
}

// out parameter - must write before return
function tryParse(input: string, value: out<int>): bool {
  // Parser sets value through out parameter
  return true as bool;
}

// in parameter - readonly reference
function process(data: In<Array<int>>): void {
  // Can read data but not modify it
  console.log(data);
}

Unsafe Pointers

import { ptr, int } from "@tsonic/types";

// Pointer types require explicit handling
declare function getPointer(): ptr<int>;
declare function dereferenceInt(p: ptr<int>): int;

const pointer = getPointer();
// pointer is ptr<int>, not directly usable as int
const value = dereferenceInt(pointer); // Explicit dereference required

License

MIT