@j2blasco/ts-pipe

A TypeScript utility library providing strongly-typed function composition through pipe operations. Chain together synchronous and asynchronous functions with full type safety.

Features

• 🔗 Function Composition: Chain multiple functions together in a readable, left-to-right manner
• 🔄 Sync & Async Support: Handle both synchronous and asynchronous operations seamlessly
• 🛡️ Type Safety: Full TypeScript support with proper type inference across the chain
• 📦 Zero Dependencies: Lightweight with no external dependencies
• ⚡ Performance: Optimized implementations for up to 10 function arguments with fallback for more

Installation

1npm install @j2blasco/ts-pipe

Usage

Synchronous Pipe

The pipe function allows you to chain synchronous functions together:

1import { pipe } from '@j2blasco/ts-pipe';
2
3// Basic example
4const result = pipe(
5  "5",
6  (str) => parseInt(str, 10),  // string → number
7  (num) => num * 2,            // number → number  
8  (num) => num.toString(),     // number → string
9  (str) => `Result: ${str}`    // string → string
10);
11console.log(result); // "Result: 10"
12
13// Object transformations
14const user = pipe(
15  { name: "john", age: 25 },
16  (user) => ({ ...user, name: user.name.toUpperCase() }),
17  (user) => ({ ...user, age: user.age + 1 }),
18  (user) => `${user.name} is ${user.age} years old`
19);
20console.log(user); // "JOHN is 26 years old"

Asynchronous Pipe

The asyncPipe function handles both synchronous and asynchronous functions, always returning a Promise:

1import { asyncPipe } from '@j2blasco/ts-pipe';
2
3// Mixed sync/async operations
4const result = await asyncPipe(
5  "https://api.example.com/data",
6  async (url) => fetch(url),           // async
7  (response) => response.json(),       // sync (returns Promise)
8  async (data) => processData(data),   // async
9  (processed) => processed.result      // sync
10);
11
12// All async operations
13const transformed = await asyncPipe(
14  "hello",
15  async (str) => `${str} world`,
16  async (str) => str.toUpperCase(),
17  async (str) => `${str}!`
18);
19console.log(transformed); // "HELLO WORLD!"

Array Processing

1import { pipe, asyncPipe } from '@j2blasco/ts-pipe';
2
3// Synchronous array processing
4const numbers = pipe(
5  [1, 2, 3, 4, 5],
6  (arr) => arr.filter(x => x % 2 === 0),    // [2, 4]
7  (arr) => arr.map(x => x * 2),             // [4, 8]
8  (arr) => arr.reduce((sum, x) => sum + x, 0) // 12
9);
10
11// Asynchronous array processing
12const processedData = await asyncPipe(
13  [1, 2, 3],
14  (arr) => arr.map(x => x * 2),
15  async (arr) => Promise.all(arr.map(async x => {
16    // Simulate async operation
17    await new Promise(resolve => setTimeout(resolve, 10));
18    return x + 1;
19  })),
20  (arr) => arr.join(', ')
21);

Type Safety

The library maintains full type safety throughout the chain:

1import { pipe } from '@j2blasco/ts-pipe';
2
3// TypeScript will infer types at each step
4const result = pipe(
5  5,                           // number
6  (x) => x.toString(),        // number → string
7  (s) => s.toUpperCase(),     // string → string
8  (s) => s.length             // string → number
9); // result is inferred as number
10
11// Compilation error if types don't match
12const invalid = pipe(
13  5,
14  (x) => x.toString(),
15  (s) => s.toUpperCase(),
16  (s) => s * 2  // ❌ Error: can't multiply string by number
17);

API Reference

pipe(value, ...functions)

Composes synchronous functions from left to right.

Parameters:

• value: Initial value to pass through the pipe
• ...functions: Up to 10 transformation functions (more supported via fallback)

Returns: The final transformed value

asyncPipe(value, ...functions)

Composes functions that may be synchronous or asynchronous.

Parameters:

• value: Initial value to pass through the pipe
• ...functions: Up to 10 transformation functions that can return values or Promises

Returns: Promise<T> where T is the type of the final transformed value

Advanced Examples

Error Handling

1import { asyncPipe } from '@j2blasco/ts-pipe';
2
3try {
4  const result = await asyncPipe(
5    "invalid-url",
6    async (url) => {
7      const response = await fetch(url);
8      if (!response.ok) throw new Error('Failed to fetch');
9      return response;
10    },
11    (response) => response.json(),
12    (data) => data.result
13  );
14} catch (error) {
15  console.error('Pipeline failed:', error);
16}

Conditional Processing

1import { pipe } from '@j2blasco/ts-pipe';
2
3const processUser = (includeEmail: boolean) => pipe(
4  { name: 'John', age: 25, email: 'john@example.com' },
5  (user) => ({ ...user, name: user.name.toUpperCase() }),
6  (user) => includeEmail ? user : { name: user.name, age: user.age },
7  (user) => JSON.stringify(user)
8);

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.