Array-TS

Type-first dense vs sparse array abstractions for TypeScript.

Goal: Let the type system tell you when undefined is possible. No reliance on runtime hole or undefined detection for correctness; correctness is encoded in the APIs you can call.

The Problem

TypeScript's native Array<T> (or T[]) does not distinguish between a logically dense sequence and a sparse structure with holes. That means both indexed access and iteration claim T even when runtime values are missing (T | undefined is possible in reality).

function getArrayWithHoles(): number[] {
  const myArray: number[] = [];
  myArray[2] = 777;
  return myArray; // [undefined, undefined, 777]
}

const myArray = getArrayWithHoles();
for (const arrayElement of myArray) {
  // type = number; but in reality it can be undefined!!!
  type justNumber = typeof arrayElement;

  console.log(arrayElement);
  // 1st iteration: undefined
  // 2nd iteration: undefined
  // 3rd iteration: 777
}

Installation

npm install array-ts

Usage

import { SparseArray, DenseArray } from "array-ts";

const sparseArray = new SparseArray<number>([1, undefined, 3]);
sparseArray.push(1);
sparseArray.set(8, 777); // add 777 at index 8, leaving holes
for (const arrayElement of sparseArray) {
  // type = number | undefined; as expected
  type numberOrUndefined = typeof arrayElement;
}

const denseArray = new DenseArray<number>();
denseArray.push(1);
denseArray.push(2);
denseArray.push(3); // no holes allowed
for (const arrayElement of denseArray) {
  // type = number; as expected
  type justNumber = typeof arrayElement;
}