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 (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).

``typescript
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

`bash
npm install array-ts
`

Usage

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

const sparseArray = new SparseArray([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();
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;
}
``