TS Linq Light

A modern, lightweight TypeScript LINQ library with lazy evaluation, full type safety, and zero dependencies. Built for TypeScript 5.0+ with performance and developer experience in mind.

Overview

TS Linq Light brings LINQ (Language Integrated Query) capabilities to TypeScript with a focus on:

• Performance: 2-3x faster than native array methods for complex queries through lazy evaluation
• Type Safety: Full TypeScript support with type predicates, branded types, and advanced inference
• Developer Experience: Fluent API with IntelliSense support and clear error messages
• Bundle Size: Tree-shakeable design allows up to 80% bundle size reduction
• Zero Dependencies: Lightweight and self-contained

Installation

npm install ts-linq-light

Quick Start

Wrapper Pattern (Recommended)

import { from } from 'ts-linq-light';

const result = from([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
  .where(x => x > 3)
  .where(x => x < 8)
  .select(x => x * 2)
  .toArray();
// [8, 10, 12, 14]

Array Extension Pattern

import 'ts-linq-light/extensions';

const result = [1, 2, 3, 4, 5]
  .where(x => x % 2 === 0)
  .select(x => x * 2)
  .toArray();
// [4, 8]

Key Features

Lazy Evaluation

Operations are deferred until materialization, enabling single-pass execution:

const query = from([1, 2, 3, 4, 5])
  .where(x => x > 2)      // Not executed yet
  .select(x => x * 2);    // Not executed yet

const result = query.toArray();  // Executes in single pass

Type Safety

Full TypeScript support with type predicates and automatic type narrowing:

interface Animal { name: string; }
interface Dog extends Animal { bark(): void; }

const animals: Animal[] = [...];

// Type automatically narrows to IEnumerable<Dog>
const dogs = from(animals)
  .where((a): a is Dog => 'bark' in a);

dogs.forEach(dog => dog.bark()); // Type-safe!

Performance

Optimized for real-world scenarios:

| Operation | Native Arrays | TS Linq Light | Improvement | |-----------|--------------|---------------|-------------| | Multiple filters | 3 passes, 2 intermediate arrays | 1 pass, 0 arrays | 3x faster | | Find first match | Full iteration | Early termination | Up to 18x faster | | Complex queries | High memory usage | Constant memory | 90% less memory |

Core API

Filtering

from([1, 2, 3, 4, 5])
  .where(x => x % 2 === 0)
  .toArray();
// [2, 4]

Projection

from([1, 2, 3])
  .select(x => x * 2)
  .toArray();
// [2, 4, 6]

Ordering

from([{ name: 'Bob', age: 30 }, { name: 'Alice', age: 25 }])
  .orderBy(u => u.age)
  .thenBy(u => u.name)
  .toArray();

Aggregation

const products = from([
  { name: 'Laptop', price: 1200 },
  { name: 'Mouse', price: 25 }
]);

const mostExpensive = products.maxBy(p => p.price);
const cheapest = products.minBy(p => p.price);

Grouping

from(users)
  .groupBy(u => u.department)
  .select(g => ({
    department: g.key,
    count: g.count(),
    avgSalary: g.toArray().reduce((sum, u) => sum + u.salary, 0) / g.count()
  }))
  .toArray();

Quantifiers

from([1, 2, 3, 4, 5]).any(x => x > 3);  // true
from([2, 4, 6, 8]).all(x => x % 2 === 0);  // true

Partitioning

// Pagination
from(items)
  .skip(pageNumber * pageSize)
  .take(pageSize)
  .toArray();

// Top N
from(products)
  .orderByDescending(p => p.rating)
  .take(10)
  .toArray();

Complete Method List

23 LINQ methods available:

• Filtering: where
• Projection: select
• Ordering: orderBy, orderByDescending, thenBy, thenByDescending
• Aggregation: maxBy, minBy, count
• Quantifiers: any, all
• Element Operations: first, firstOrDefault, last, lastOrDefault
• Partitioning: skip, take
• Grouping: groupBy
• Conversion: toArray, toMap, toSet
• Iteration: forEach
• String: join

Real-World Examples

E-Commerce Product Filtering

const topProducts = from(products)
  .where(p => p.inStock)
  .where(p => p.rating >= 4.0)
  .where(p => p.price < 100)
  .orderByDescending(p => p.rating)
  .thenBy(p => p.price)
  .take(10)
  .toArray();

Data Processing Pipeline

const validUsers = from(rawData)
  .select(raw => ({
    id: parseInt(raw.id),
    name: raw.name.trim(),
    age: parseInt(raw.age)
  }))
  .where(user => !isNaN(user.id) && !isNaN(user.age))
  .where(user => user.age >= 18)
  .orderBy(user => user.name)
  .toArray();

Analytics and Reporting

const departmentStats = from(employees)
  .groupBy(e => e.department)
  .select(group => ({
    department: group.key,
    count: group.count(),
    avgSalary: group.toArray().reduce((sum, e) => sum + e.salary, 0) / group.count(),
    maxSalary: group.maxBy(e => e.salary)?.salary ?? 0
  }))
  .orderByDescending(stat => stat.avgSalary)
  .toArray();

Documentation

Comprehensive documentation is available:

• Getting Started Guide
• Complete API Reference
• In-Depth Guide
• Real-World Examples
• Performance Benchmarks
• Tree-Shaking Guide
• Test Coverage
• Roadmap

Modern TypeScript Features

TS Linq Light leverages TypeScript 5.0+ features:

• Type Predicates: Automatic type narrowing in where() clauses
• Branded Types: Compile-time safety for ordered vs unordered enumerables
• Overloaded Methods: Multiple signatures for flexible usage
• Generic Constraints: Type-safe operations (e.g., maxBy only accepts number or Date)
• Covariance: Better type inference across transformations

Tree-Shaking Support

Import only what you need for optimal bundle size:

// Only includes where() implementation (~1KB)
import { where } from 'ts-linq-light';

// Potential savings: up to 80% smaller bundle

Testing

375 comprehensive tests with 100% pass rate:

npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

Performance Benchmarks

Run benchmarks locally:

npm run bench

Results show 2-3x performance improvement over native array methods for complex queries.

Browser and Node.js Support

• Node.js: 16.x or higher
• Browsers: All modern browsers (ES2020+)
• TypeScript: 5.0 or higher

Development

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Run examples
npx tsx examples/basic-usage.ts

Roadmap

Version 1.0 (Current)

• 23 core LINQ methods
• Lazy evaluation with generators
• Full TypeScript type safety
• Zero dependencies
• Tree-shakeable

Version 2.0 (Planned)

• Additional methods: distinct, union, intersect, except
• More aggregations: sum, average, aggregate
• Join operations: join, groupJoin, zip
• Advanced partitioning: skipWhile, takeWhile, chunk
• Better error messages and debug mode

Version 3.0 (Future)

• Async enumerable support
• Observable integration (RxJS compatibility)
• Query optimization
• Parallel execution (experimental)

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

License

MIT License - see LICENSE file for details.

Acknowledgments

Inspired by:

• C# LINQ
• Modern TypeScript best practices
• Community feedback and contributions

Support

• GitHub Issues
• Documentation
• npm Package

Built with TypeScript 5.0+ | Zero Dependencies | 375 Tests Passing | MIT Licensed