feat(data): add run-length encode/decode utilities; docs + tests + example

docs/index.d.ts

@@ -101,6 +101,8 @@ export const examples: {
     readonly BloomFilter: 'examples/bloomFilter.ts';
     readonly SegmentTree: 'examples/segmentTree.ts';
     readonly SkipList: 'examples/skipList.ts';
+    readonly runLengthEncode: 'examples/rle.ts';
+    readonly runLengthDecode: 'examples/rle.ts';
   };
   readonly performance: {
     readonly debounce: 'examples/requestDedup.ts';
@@ -2998,6 +3000,15 @@ export class SkipList<T> {
   values(): IterableIterator<T>;
 }
 
+/**
+ * Run-length encoding for strings.
+ * Use for: simple compression of repetitive text.
+ * Import: data/rle.ts
+ */
+export interface RlePair { char: string; count: number }
+export function runLengthEncode(input: string): RlePair[];
+export function runLengthDecode(pairs: ReadonlyArray<RlePair>): string;
+
 /**
  * Disjoint Set Union (Union-Find) with path compression and union by size.
  * Use for: connectivity queries, Kruskal MST, clustering.

examples/rle.ts

@@ -0,0 +1,7 @@
+import { runLengthEncode, runLengthDecode } from '../src/index.js';
+
+const s = 'AAAABBBCCDAA';
+const pairs = runLengthEncode(s);
+console.log('pairs', pairs);
+console.log('decoded', runLengthDecode(pairs));
+

src/data/rle.ts

@@ -0,0 +1,42 @@
+/**
+ * Run-length encoding for strings.
+ * Useful for: simple compression on repetitive text.
+ */
+export interface RlePair {
+  char: string;
+  count: number;
+}
+
+/**
+ * Encodes a string into RLE pairs.
+ */
+export function runLengthEncode(input: string): RlePair[] {
+  if (input.length === 0) return [];
+  const out: RlePair[] = [];
+  let last = input[0];
+  let cnt = 1;
+  for (let i = 1; i < input.length; i += 1) {
+    const c = input[i];
+    if (c === last) cnt += 1;
+    else {
+      out.push({ char: last, count: cnt });
+      last = c;
+      cnt = 1;
+    }
+  }
+  out.push({ char: last, count: cnt });
+  return out;
+}
+
+/**
+ * Decodes RLE pairs into a string.
+ */
+export function runLengthDecode(pairs: ReadonlyArray<RlePair>): string {
+  let out = '';
+  for (const p of pairs) {
+    if (!p || typeof p.count !== 'number' || typeof p.char !== 'string') continue;
+    if (p.count <= 0 || p.char.length === 0) continue;
+    out += p.char.repeat(p.count);
+  }
+  return out;
+}

src/index.ts

@@ -99,6 +99,8 @@ export const examples = {
     BloomFilter: 'examples/bloomFilter.ts',
     SegmentTree: 'examples/segmentTree.ts',
     SkipList: 'examples/skipList.ts',
+    runLengthEncode: 'examples/rle.ts',
+    runLengthDecode: 'examples/rle.ts',
   },
   performance: {
     debounce: 'examples/requestDedup.ts',
@@ -1044,6 +1046,12 @@ export { BinaryHeap } from './data/binaryHeap.js';
  * Example file: examples/skipList.ts
  */
 export { SkipList } from './data/skipList.js';
+/**
+ * Run-length encoding helpers for strings.
+ *
+ * Example file: examples/rle.ts
+ */
+export { runLengthEncode, runLengthDecode } from './data/rle.js';
 
 export type {
   TreeNode,

tests/index.test.ts

@@ -128,6 +128,8 @@ describe('package entry point', () => {
       | 'BloomFilter'
       | 'SegmentTree'
       | 'SkipList'
+      | 'runLengthEncode'
+      | 'runLengthDecode'
     >();
 
     expectTypeOf<ExampleName<'search'>>().toEqualTypeOf<

tests/rle.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { runLengthEncode, runLengthDecode } from '../src/index.js';
+
+describe('RLE', () => {
+  it('encodes and decodes repetitive strings', () => {
+    const s = 'AAAABBBCCDAA';
+    const pairs = runLengthEncode(s);
+    expect(pairs).toEqual([
+      { char: 'A', count: 4 },
+      { char: 'B', count: 3 },
+      { char: 'C', count: 2 },
+      { char: 'D', count: 1 },
+      { char: 'A', count: 2 },
+    ]);
+    expect(runLengthDecode(pairs)).toBe(s);
+  });
+
+  it('handles empty and mixed content', () => {
+    expect(runLengthEncode('')).toEqual([]);
+    const s = 'ABAB';
+    expect(runLengthDecode(runLengthEncode(s))).toBe(s);
+  });
+});
+