tiny-array-kit

A tiny, well-typed TypeScript utility for array operations by index/value.

• Zero-dependency, tree-shakeable
• ESM + CJS builds with .d.ts
• Immutable and mutable variants for most operations

Table of Contents

• Install
• Quick Start
• API
  • Index-based
  • Value-based
  • Predicate-based
• Behaviour Notes
• Development
• Publish to npm
• License

Install

npm i tiny-array-kit
# or
pnpm add tiny-array-kit
# or
yarn add tiny-array-kit

Quick Start

import removeAt, {
  removeAtMutable,
  getAt,
  addAt,
  addAtMutable,
  removeValue,
  removeValueMutable,
  removeWhere,
  addWhere,
  addWhereMutable,
} from 'tiny-array-kit';

removeAt([1, 2, 3, 4], 2);        // [1, 2, 4]
removeAtMutable(['a', 'b', 'c'], 1); // ['a', 'c']
getAt(['x', 'y', 'z'], 1);           // 'y'

addAt([1, 3], 1, 2);                 // [1, 2, 3]
addAtMutable(['a'], 0, 'x', 'y');    // ['x', 'y', 'a']

removeValue([1, 2, 2, 3], 2);        // [1, 3]
removeWhere([1, 2, 3, 4], n => n % 2 === 0); // [1, 3]

addWhere([1, 2, 3], n => n === 2, ['x']);                     // [1, 'x', 2, 3]
addWhere(['a','b','c'], ch => ch === 'b', ['X'], { position: 'after' }); // ['a','b','X','c']

API

Index-based

• removeAt<T>(input: readonly T[], index: number): T[]
• removeAtMutable<T>(input: T[], index: number): T[]
• getAt<T>(input: readonly T[], index: number): T | undefined
• addAt<T>(input: readonly T[], index: number, ...items: T[]): T[]
• addAtMutable<T>(input: T[], index: number, ...items: T[]): T[]

Value-based

• removeValue<T>(input: readonly T[], value: T, options?: { comparator?: (a: T, b: T) => boolean; deep?: boolean }): T[]
• removeValueMutable<T>(input: T[], value: T, options?: { comparator?: (a: T, b: T) => boolean; deep?: boolean }): T[]

Examples:

removeValue(['A','b','a'], 'a', { comparator: (x, y) => x.toLowerCase() === y.toLowerCase() }); // ['b']
const a1 = [1,2], a2 = [1,2];
removeValue([a1, a2], [1,2], { deep: true }); // []

Predicate-based

• removeWhere<T>(input: readonly T[], predicate: (item: T, index: number, array: readonly T[]) => boolean): T[]
• addWhere<T>(input: readonly T[], predicate: (item: T, index: number, array: readonly T[]) => boolean, items: readonly T[], options?: { position?: 'before' | 'after'; mode?: 'first' | 'all' }): T[]
• addWhereMutable<T>(input: T[], predicate: (item: T, index: number, array: readonly T[]) => boolean, items: readonly T[], options?: { position?: 'before' | 'after'; mode?: 'first' | 'all' }): T[]

Examples:

removeWhere([1,2,3,4], n => n % 2 === 0); // [1,3]
addWhere([2,1,2,3,2], n => n === 2, ['x'], { mode: 'all' }); // ['x',2,1,'x',2,3,'x',2]

Behaviour Notes

• Out-of-range index (negative, or >= length):
  • removeAt returns a shallow clone of the input array
  • removeAtMutable is a no-op
  • getAt returns undefined
  • addAt and addAtMutable clamp index into [0, length]
• Non-integer index:
  • removal: same as out-of-range (removeAt clone, removeAtMutable no-op)
  • add: append to end (addAt appends in result; addAtMutable pushes)

Development

npm i
npm run test
npm run build

Publish to npm

1. Update package.json fields (name, author, repository, etc.)
2. Login: npm login
3. Publish: npm publish --access public

If the name tiny-array-kit is taken, change package.json.name (e.g. @scope/tiny-array-kit).

License

MIT