Skip to main content

TreeSet

data-structure-typed

data-structure-typed / TreeSet

Class: TreeSet<K, R>

Defined in: data-structures/binary-tree/tree-set.ts:30

An ordered Set backed by a red-black tree.

  • Iteration order is ascending by key.
  • No node exposure: all APIs use keys only.

Example​

// Set multiple key-value pairs
 const ts = new TreeSet<number, string>();
    ts.setMany([[1, 'a'], [2, 'b'], [3, 'c']]);
    console.log(ts.size); // 3;

Type Parameters​

K​

K = any

R​

R = K

Implements​

  • Iterable<K>

Constructors​

Constructor​

new TreeSet<K, R>(elements?, options?): TreeSet<K, R>;

Defined in: data-structures/binary-tree/tree-set.ts:50

Create a TreeSet from an iterable of keys or raw elements.

Parameters​

elements?​

Iterable<K, any, any> | Iterable<R, any, any>

Iterable of keys, or raw elements if toElementFn is provided.

options?​

TreeSetOptions<K, R> = {}

Configuration options including optional toElementFn to transform raw elements.

Returns​

TreeSet<K, R>

Throws​

When using the default comparator and encountering unsupported key types, or invalid keys (e.g. NaN, invalid Date).

Example​

// Standard usage with keys
const set = new TreeSet([3, 1, 2]);

// Using toElementFn to transform raw objects
const users = [{ id: 3, name: 'Alice' }, { id: 1, name: 'Bob' }];
const set = new TreeSet<number, User>(users, { toElementFn: u => u.id });

Accessors​

size​

Get Signature​

get size(): number;

Defined in: data-structures/binary-tree/tree-set.ts:70

Number of elements in the set.

Returns​

number

Methods​

add()​

add(key): this;

Defined in: data-structures/binary-tree/tree-set.ts:133

Add a key to the set (no-op if already present).

Parameters​

key​

K

Returns​

this

Remarks​

Expected time O(log n)

Example​

// Unique tags with sorted order
 const tags = new TreeSet<string>(['javascript', 'typescript', 'react', 'typescript', 'node']);

    // Duplicates removed, sorted alphabetically
    console.log([...tags]); // ['javascript', 'node', 'react', 'typescript'];
    console.log(tags.size); // 4;

    tags.add('angular');
    console.log(tags.first()); // 'angular';
    console.log(tags.last()); // 'typescript';

addMany()​

addMany(keys): boolean[];

Defined in: data-structures/binary-tree/tree-set.ts:151

Add multiple keys at once.

Parameters​

keys​

Iterable<K>

Iterable of keys to add.

Returns​

boolean[]

Array of booleans indicating whether each key was newly added.

Remarks​

Expected time O(m log n), where m is the number of keys.

Example​

// Add multiple keys
 const ts = new TreeSet<number>();
    ts.addMany([5, 3, 7, 1, 9]);
    console.log(ts.size); // 5;

ceiling()​

ceiling(key): K | undefined;

Defined in: data-structures/binary-tree/tree-set.ts:550

Smallest key that is >= the given key.

Parameters​

key​

K

Returns​

K | undefined

Example​

// Finding nearest available time slot
 // Available appointment times (minutes from midnight)
    const slots = new TreeSet<number>([540, 600, 660, 720, 840, 900]);

    // Customer wants something around 10:30 (630 min)
    const nearest = slots.ceiling(630);
    console.log(nearest); // 660; // 11:00 AM

    // What's the latest slot before 2:00 PM (840)?
    const before2pm = slots.lower(840);
    console.log(before2pm); // 720; // 12:00 PM

    // Book the 11:00 slot
    slots.delete(660);
    console.log(slots.ceiling(630)); // 720;

clear()​

clear(): void;

Defined in: data-structures/binary-tree/tree-set.ts:218

Remove all keys.

Returns​

void

Example​

// Remove all
 const ts = new TreeSet<number>([1, 2]);
      ts.clear();
      console.log(ts.isEmpty()); // true;

clone()​

clone(): TreeSet<K>;

Defined in: data-structures/binary-tree/tree-set.ts:837

Deep copy

Returns​

TreeSet<K>

Example​

// Deep clone
 const ts = new TreeSet<number>([1, 2, 3]);
      const copy = ts.clone();
      copy.delete(1);
      console.log(ts.has(1)); // true;

delete()​

delete(key): boolean;

Defined in: data-structures/binary-tree/tree-set.ts:187

Delete a key.

Parameters​

key​

K

Returns​

boolean

true if the key existed; otherwise false.

Remarks​

Expected time O(log n)

Example​

// Removing elements while maintaining order
 const nums = new TreeSet<number>([1, 3, 5, 7, 9]);

    console.log(nums.delete(5)); // true;
    console.log(nums.delete(5)); // false; // already gone
    console.log([...nums]); // [1, 3, 7, 9];

deleteWhere()​

deleteWhere(predicate): boolean;

Defined in: data-structures/binary-tree/tree-set.ts:198

Delete all keys matching a predicate.

Parameters​

predicate​

(key, index, set) => boolean

Function (key, index, set) → boolean; return true to delete.

Returns​

boolean

True if at least one key was deleted.

Remarks​

Time O(N), Space O(N)

difference()​

difference(other): TreeSet<K>;

Defined in: data-structures/binary-tree/tree-set.ts:748

Return a new TreeSet containing elements in this set but not in the other.

Parameters​

other​

Iterable<K>

Any iterable of keys.

Returns​

TreeSet<K>

A new TreeSet.

Remarks​

Time O(n+m) with ordered merge when possible, otherwise O(n log m).

Example​

// Find exclusive elements
 console.log([...a.difference(b)]); // [1, 2];

entries()​

entries(): IterableIterator<[K, K]>;

Defined in: data-structures/binary-tree/tree-set.ts:255

Iterate over [value, value] pairs (native Set convention).

Note: TreeSet stores only keys internally; [k, k] is created on-the-fly during iteration.

Returns​

IterableIterator<[K, K]>

Example​

// Iterate entries
 const ts = new TreeSet<number>([3, 1, 2]);
      console.log([...ts.entries()].map(([k]) => k)); // [1, 2, 3];

every()​

every(callbackfn, thisArg?): boolean;

Defined in: data-structures/binary-tree/tree-set.ts:357

Test whether all values satisfy a predicate.

Parameters​

callbackfn​

TreeSetElementCallback<K, boolean, TreeSet<K, K>>

thisArg?​

unknown

Returns​

boolean

Remarks​

Time O(n), Space O(1)

Example​

// Test all
 const ts = new TreeSet<number>([2, 4, 6]);
      console.log(ts.every(k => k > 0)); // true;

filter()​

filter(callbackfn, thisArg?): TreeSet<K>;

Defined in: data-structures/binary-tree/tree-set.ts:315

Create a new TreeSet containing only values that satisfy the predicate.

Parameters​

callbackfn​

TreeSetElementCallback<K, boolean, TreeSet<K, K>>

thisArg?​

unknown

Returns​

TreeSet<K>

Remarks​

Time O(n log n) expected, Space O(n)

Example​

// Filter
 const ts = new TreeSet<number>([1, 2, 3, 4, 5]);
      const evens = ts.filter(k => k % 2 === 0);
      console.log([...evens]); // [2, 4];

find()​

find(callbackfn, thisArg?): K | undefined;

Defined in: data-structures/binary-tree/tree-set.ts:408

Find the first value that satisfies a predicate.

Parameters​

callbackfn​

TreeSetElementCallback<K, boolean, TreeSet<K, K>>

thisArg?​

unknown

Returns​

K | undefined

Remarks​

Time O(n), Space O(1)

Example​

// Find entry
 const ts = new TreeSet<number>([1, 2, 3]);
      const found = ts.find(k => k === 2);
      console.log(found); // 2;

first()​

first(): K | undefined;

Defined in: data-structures/binary-tree/tree-set.ts:480

Smallest key in the set.

Returns​

K | undefined

Example​

// Student grade ranking with custom comparator
 interface Student {
      name: string;
      gpa: number;
    }

    const ranking = new TreeSet<Student>(
      [
        { name: 'Alice', gpa: 3.8 },
        { name: 'Bob', gpa: 3.5 },
        { name: 'Charlie', gpa: 3.9 },
        { name: 'Diana', gpa: 3.5 }
      ],
      { comparator: (a, b) => b.gpa - a.gpa || a.name.localeCompare(b.name) }
    );

    // Sorted by GPA descending, then name ascending
    const names = [...ranking].map(s => s.name);
    console.log(names); // ['Charlie', 'Alice', 'Bob', 'Diana'];

    // Top student
    console.log(ranking.first()?.name); // 'Charlie';

    // Filter students with GPA >= 3.8
    const honors = ranking.filter(s => s.gpa >= 3.8);
    console.log(honors.toArray().map(s => s.name)); // ['Charlie', 'Alice'];

floor()​

floor(key): K | undefined;

Defined in: data-structures/binary-tree/tree-set.ts:566

Largest key that is <= the given key.

Parameters​

key​

K

Returns​

K | undefined

Example​

// Largest element ≤ target
 const breakpoints = new TreeSet<number>([320, 768, 1024, 1280, 1920]);

    // Current width is 800 → which breakpoint applies?
    console.log(breakpoints.floor(800)); // 768;
    console.log(breakpoints.floor(1024)); // 1024; // exact match
    console.log(breakpoints.floor(100)); // undefined;

forEach()​

forEach(cb, thisArg?): void;

Defined in: data-structures/binary-tree/tree-set.ts:274

Visit each value in ascending order.

Callback follows native Set convention: (value, value2, set).

Parameters​

cb​

(value, value2, set) => void

thisArg?​

unknown

Returns​

void

Example​

// Execute for each
 const ts = new TreeSet<number>([3, 1, 2]);
      const keys: number[] = [];
      ts.forEach(k => keys.push(k));
      console.log(keys); // [1, 2, 3];

getByRank()​

getByRank(k): K | undefined;

Defined in: data-structures/binary-tree/tree-set.ts:650

Returns the element at the k-th position in tree order (0-indexed).

Parameters​

k​

number

Returns​

K | undefined

Remarks​

Time O(log n). Requires enableOrderStatistic: true.

Example​

// Find k-th element in a TreeSet
 const set = new TreeSet<number>([30, 10, 50, 20, 40], { enableOrderStatistic: true });
      console.log(set.getByRank(0)); // 10;
      console.log(set.getByRank(2)); // 30;
      console.log(set.getRank(30)); // 2;

getRank()​

getRank(key): number;

Defined in: data-structures/binary-tree/tree-set.ts:670

Returns the 0-based rank of a key (number of elements that precede it in tree order).

Parameters​

key​

K

Returns​

number

Remarks​

Time O(log n). Requires enableOrderStatistic: true.

Example​

// Get the rank of a key in sorted order
 const tree = new TreeSet<number>(
        [10, 20, 30, 40, 50],
        { enableOrderStatistic: true }
      );
      console.log(tree.getRank(10)); // 0;  // smallest → rank 0
      console.log(tree.getRank(30)); // 2;  // 2 elements before 30 in tree order
      console.log(tree.getRank(50)); // 4;  // largest → rank 4
      console.log(tree.getRank(25)); // 2;

has()​

has(key): boolean;

Defined in: data-structures/binary-tree/tree-set.ts:170

Test whether a key exists.

Parameters​

key​

K

Returns​

boolean

Remarks​

Expected time O(log n)

Example​

// Checking membership in a sorted collection
 const allowed = new TreeSet<string>(['admin', 'editor', 'viewer']);

    console.log(allowed.has('admin')); // true;
    console.log(allowed.has('guest')); // false;

higher()​

higher(key): K | undefined;

Defined in: data-structures/binary-tree/tree-set.ts:580

Smallest key that is > the given key.

Parameters​

key​

K

Returns​

K | undefined

Example​

// Smallest element strictly > target
 const levels = new TreeSet<number>([1, 5, 10, 25, 50, 100]);

    console.log(levels.higher(10)); // 25;
    console.log(levels.higher(100)); // undefined;

intersection()​

intersection(other): TreeSet<K>;

Defined in: data-structures/binary-tree/tree-set.ts:730

Return a new TreeSet containing only elements present in both sets.

Parameters​

other​

Iterable<K>

Any iterable of keys (converted to Set for fast lookup if not a TreeSet).

Returns​

TreeSet<K>

A new TreeSet.

Remarks​

Time O(n+m) with ordered merge when possible, otherwise O(n log m).

Example​

// Find common elements
 console.log([...a.intersection(b)]); // [3, 4, 5];

isDisjointFrom()​

isDisjointFrom(other): boolean;

Defined in: data-structures/binary-tree/tree-set.ts:820

Check whether this set and the other share no common elements.

Parameters​

other​

Iterable<K>

Any iterable of keys (converted to Set for fast lookup if not a TreeSet).

Returns​

boolean

true if sets are disjoint.

Remarks​

Time O(min(n,m)), can short-circuit on first overlap.

Example​

// Check disjoint
 console.log(a.isDisjointFrom(new TreeSet([8, 9]))); // true;

isEmpty()​

isEmpty(): boolean;

Defined in: data-structures/binary-tree/tree-set.ts:114

Whether the set is empty.

Returns​

boolean

Example​

// Check empty
 console.log(new TreeSet().isEmpty()); // true;

isSubsetOf()​

isSubsetOf(other): boolean;

Defined in: data-structures/binary-tree/tree-set.ts:787

Check whether every element in this set is also in the other.

Parameters​

other​

Iterable<K>

Any iterable of keys (converted to Set for fast lookup if not a TreeSet).

Returns​

boolean

true if this is a subset of other.

Remarks​

Time O(n).

Example​

// Check subset
 console.log(new TreeSet([3, 4]).isSubsetOf(a)); // true;

isSupersetOf()​

isSupersetOf(other): boolean;

Defined in: data-structures/binary-tree/tree-set.ts:804

Check whether every element in the other set is also in this set.

Parameters​

other​

Iterable<K>

Any iterable of keys.

Returns​

boolean

true if this is a superset of other.

Remarks​

Time O(m).

Example​

// Check superset
 console.log(a.isSupersetOf(new TreeSet([2, 3]))); // true;

keys()​

keys(): IterableIterator<K>;

Defined in: data-structures/binary-tree/tree-set.ts:229

Iterate over keys in ascending order.

Returns​

IterableIterator<K>

Example​

// Get sorted keys
 const ts = new TreeSet<number>([30, 10, 20]);
      console.log([...ts.keys()]); // [10, 20, 30];

last()​

last(): K | undefined;

Defined in: data-structures/binary-tree/tree-set.ts:494

Largest key in the set.

Returns​

K | undefined

Example​

// Get the maximum element
 const temps = new TreeSet<number>([18, 22, 15, 30, 25]);
    console.log(temps.last()); // 30;
    console.log(temps.first()); // 15;

lower()​

lower(key): K | undefined;

Defined in: data-structures/binary-tree/tree-set.ts:594

Largest key that is < the given key.

Parameters​

key​

K

Returns​

K | undefined

Example​

// Largest element strictly < target
 const tiers = new TreeSet<number>([100, 200, 500, 1000]);

    console.log(tiers.lower(500)); // 200;
    console.log(tiers.lower(100)); // undefined;

map()​

map<MK>(
   callbackfn, 
   options?, 
thisArg?): TreeSet<MK>;

Defined in: data-structures/binary-tree/tree-set.ts:289

Create a new TreeSet by mapping each value to a new key.

This mirrors RedBlackTree.map: mapping produces a new ordered container.

Type Parameters​

MK​

MK

Parameters​

callbackfn​

TreeSetElementCallback<K, MK, TreeSet<K, K>>

options?​

Omit<TreeSetOptions<MK, MK>, "toElementFn"> & object = {}

thisArg?​

unknown

Returns​

TreeSet<MK>

Remarks​

Time O(n log n) expected, Space O(n)

Example​

// Transform
 const ts = new TreeSet<number>([1, 2, 3]);
      const doubled = ts.map(k => k * 2);
      console.log([...doubled]); // [2, 4, 6];

pollFirst()​

pollFirst(): K | undefined;

Defined in: data-structures/binary-tree/tree-set.ts:508

Remove and return the smallest key.

Returns​

K | undefined

Example​

// Remove and return minimum
 const queue = new TreeSet<number>([5, 1, 8, 3]);

    console.log(queue.pollFirst()); // 1;
    console.log(queue.pollFirst()); // 3;
    console.log(queue.size); // 2;

pollLast()​

pollLast(): K | undefined;

Defined in: data-structures/binary-tree/tree-set.ts:524

Remove and return the largest key.

Returns​

K | undefined

Example​

// Remove and return maximum
 const stack = new TreeSet<number>([10, 20, 30]);

    console.log(stack.pollLast()); // 30;
    console.log(stack.size); // 2;

print()​

print(): void;

Defined in: data-structures/binary-tree/tree-set.ts:445

Print a human-friendly representation.

Returns​

void

Remarks​

Time O(n), Space O(n)

Example​

// Display tree
 const ts = new TreeSet<number>([1, 2, 3]);
      expect(() => ts.print()).not.toThrow();

rangeByRank()​

rangeByRank(start, end): K[];

Defined in: data-structures/binary-tree/tree-set.ts:689

Returns elements by rank range (0-indexed, inclusive on both ends).

Parameters​

start​

number

end​

number

Returns​

K[]

Remarks​

Time O(log n + k). Requires enableOrderStatistic: true.

Example​

// Pagination by position in tree order
 const tree = new TreeSet<number>([10, 20, 30, 40, 50, 60, 70, 80, 90], { enableOrderStatistic: true });
      const pageSize = 3;

      // Page 1
      console.log(tree.rangeByRank(0, pageSize - 1)); // [10, 20, 30];
      // Page 2
      console.log(tree.rangeByRank(pageSize, 2 * pageSize - 1)); // [40, 50, 60];
      // Page 3
      console.log(tree.rangeByRank(2 * pageSize, 3 * pageSize - 1)); // [70, 80, 90];

rangeSearch()​

rangeSearch(range, options?): K[];

Defined in: data-structures/binary-tree/tree-set.ts:622

Return all keys in a given range.

Parameters​

range​

[K, K]

[low, high]

options?​

TreeSetRangeOptions = {}

Inclusive/exclusive bounds (defaults to inclusive).

Returns​

K[]

Example​

// IP address blocklist with range checking
 // Simplified: use numeric IP representation
    const blocklist = new TreeSet<number>([
      167772160, // 10.0.0.0
      167772416, // 10.0.1.0
      167772672, // 10.0.2.0
      167773184 // 10.0.4.0
    ]);

    // Check if any blocked IP is in range 10.0.1.0 - 10.0.3.0
    const inRange = blocklist.rangeSearch([167772416, 167772928]);
    console.log(inRange); // [167772416, 167772672];

    // Quick membership check
    console.log(blocklist.has(167772416)); // true;
    console.log(blocklist.has(167772800)); // false;

reduce()​

reduce<A>(callbackfn, initialValue): A;

Defined in: data-structures/binary-tree/tree-set.ts:342

Reduce values into a single accumulator.

Type Parameters​

A​

A

Parameters​

callbackfn​

TreeSetReduceCallback<K, A, TreeSet<K, K>>

initialValue​

A

Returns​

A

Remarks​

Time O(n), Space O(1)

Example​

// Aggregate
 const ts = new TreeSet<number>([1, 2, 3]);
      const sum = ts.reduce((acc, k) => acc + k, 0);
      console.log(sum); // 6;

some()​

some(callbackfn, thisArg?): boolean;

Defined in: data-structures/binary-tree/tree-set.ts:382

Test whether any value satisfies a predicate.

Parameters​

callbackfn​

TreeSetElementCallback<K, boolean, TreeSet<K, K>>

thisArg?​

unknown

Returns​

boolean

Remarks​

Time O(n), Space O(1)

Example​

// Test any
 const ts = new TreeSet<number>([1, 3, 5]);
      console.log(ts.some(k => k === 3)); // true;

symmetricDifference()​

symmetricDifference(other): TreeSet<K>;

Defined in: data-structures/binary-tree/tree-set.ts:766

Return a new TreeSet containing elements in either set but not both.

Parameters​

other​

Iterable<K>

Any iterable of keys.

Returns​

TreeSet<K>

A new TreeSet.

Remarks​

Time O(n+m).

Example​

// Find symmetric difference
 console.log([...a.symmetricDifference(b)]); // [1, 2, 6, 7];

toArray()​

toArray(): K[];

Defined in: data-structures/binary-tree/tree-set.ts:433

Materialize the set into an array of keys.

Returns​

K[]

Remarks​

Time O(n), Space O(n)

Example​

// Convert to array
 const ts = new TreeSet<number>([3, 1, 2]);
      console.log(ts.toArray()); // [1, 2, 3];

union()​

union(other): TreeSet<K>;

Defined in: data-structures/binary-tree/tree-set.ts:702

Return a new TreeSet containing all elements from both sets.

Parameters​

other​

Iterable<K>

Any iterable of keys.

Returns​

TreeSet<K>

A new TreeSet.

Remarks​

When both sets share the same comparator, uses O(n+m) merge. Otherwise O(m log n).

Example​

// Merge two sets
 console.log([...a.union(b)]); // [1, 2, 3, 4, 5, 6, 7];

values()​

values(): IterableIterator<K>;

Defined in: data-structures/binary-tree/tree-set.ts:242

Iterate over values in ascending order.

Note: for Set-like containers, values() is the same as keys().

Returns​

IterableIterator<K>

Example​

// Get values (same as keys for Set)
 const ts = new TreeSet<number>([2, 1, 3]);
      console.log([...ts.values()]); // [1, 2, 3];

createDefaultComparator()​

static createDefaultComparator<K>(): Comparator<K>;

Defined in: data-structures/binary-tree/tree-set.ts:84

Create the strict default comparator.

Supports:

  • number (rejects NaN; treats -0 and 0 as equal)
  • string
  • Date (orders by getTime(), rejects invalid dates)

For other key types, a custom comparator must be provided.

Type Parameters​

K​

K

Returns​

Comparator<K>