lfi: Lazy Functional Iteration Library

In lfi, functions are automatically curried where applicable. This means that if a function (like filter or map) accepts multiple parameters, calling it with only its first few parameters will return a new function that expects the remaining parameters (typically the iterable).

This pattern is designed to work seamlessly with the pipe function. When you use curried functions inside pipe, you can provide the transformation logic (like a predicate or a mapper) first, and the resulting function will wait for the data to be passed in by pipe.

Benefits of this approach:

1. Readability: The code follows a top-to-bottom reading order that matches the logical flow of data transformations.
2. Tree Shaking: Unlike method chaining on prototypes, using curried functions with pipe allows bundlers to effectively remove unused functions from your final bundle.

import { filter, map, pipe } from 'lfi'

// Instead of filter(predicate, iterable)
// You use the curried version: filter(predicate)
// which returns a function: (iterable) => filteredIterable

const processData = (data) => pipe(
  data,
  filter(item => item.active),
  map(item => item.value)
)

A full Reducer (or AsyncReducer) is an object that allows the accumulator's type to differ from the type of the values in the iterable. This is useful for maintaining complex state (like a sum and a count simultaneously).

Sync Reducer

Pass an object to reduce() with:

• create: A function to produce the initial accumulator value.
• add: A function to combine the current accumulator with the next value.
• finish (optional): A function to transform the final accumulator. Note: reduce() with a full reducer does not return an optional because create handles the zero-value case.

Async Reducer

Pass an object to reduceAsync() with:

• create: An async function to produce the initial accumulator.
• add: An async function to combine the accumulator and value.
• combine (optional): An async function to combine two accumulators (useful for concurrent reductions).
• finish (optional): An async function to transform the final accumulator.

// Sync Full Reducer (e.g., calculating mean)
import { map, pipe, reduce } from 'lfi'

const meanSquares = numbers =>
  pipe(
    numbers,
    map(number => number * number),
    reduce({
      create: () => ({ sum: 0, count: 0 }),
      add: ({ sum, count }, number) => ({ sum: sum + number, count: count + 1 }),
      finish: ({ sum, count }) => (count === 0 ? NaN : sum / count),
    }),
  )

// Async Full Reducer
import { asAsync, mapAsync, pipe, reduceAsync } from 'lfi'

const meanSquares = async numbers => {
  return await pipe(
    asAsync(numbers),
    mapAsync(number => number * number),
    reduceAsync({
      create: async () => ({ sum: 0, count: 0 }),
      add: async ({ sum, count }, number) => ({ sum: sum + number, count: count + 1 }),
      combine: async (acc1, acc2) => ({
        sum: acc1.sum + acc2.sum,
        count: acc1.count + acc2.count
      }),
      finish: async ({ sum, count }) => (count === 0 ? NaN : sum / count),
    }),
  )
}

A FunctionReducer is the simplest type of reducer. It defines how to combine two values of the same type into a single value of that same type.

• Sync: Pass a function to reduce(). Because it doesn't define a behavior for empty iterables, reduce() returns an Optional. Use or() to provide a default value.
• Async: Pass an async function to reduceAsync(). This works with async iterables (via asAsync) or concurrent iterables. reduceAsync() returns an AsyncOptional, so use orAsync() for defaults.

// Sync Function Reducer
import { map, or, pipe, reduce } from 'lfi'

const sumSquares = numbers =>
  pipe(
    numbers,
    map(number => number * number),
    reduce((number1, number2) => number1 + number2),
    or(() => 0),
  )

// Async Function Reducer
import { asAsync, mapAsync, orAsync, pipe, reduceAsync } from 'lfi'

const sumSquares = async numbers => {
  return await pipe(
    asAsync(numbers),
    mapAsync(number => number * number),
    reduceAsync(async (number1, number2) => number1 + number2),
    orAsync(() => 0),
  )
}

Concur iterables offer two primary advantages over chaining standard promise utilities like p-map or p-filter:

1. Laziness (No Intermediate Arrays): Concur iterables do not create intermediate arrays for each operation. Chaining p-map and p-filter creates $N-1$ intermediate arrays for $N$ operations, whereas lfi pipes process items through the pipeline without extra allocations.
2. Independent Flow (No Bottlenecks): In a chain of p-map calls, the second operation cannot start until the first operation has completed for all items. In a ConcurIterable pipeline, each item flows through the operations independently. If one item is delayed by a specific operation, other items can continue through the rest of the pipeline.

Example: Independent Flow

import { asConcur, filterConcur, mapConcur, pipe, reduceConcur, toArray } from 'lfi'

// Each item flows through operations independently.
// Even if one item is slow in mapConcur, others can finish filterConcur.
const withLfi = await pipe(
  asConcur([0, 1, 2]),
  mapConcur(mapFn),
  filterConcur(filterFn),
  reduceConcur(toArray()),
)

AsyncIterable (Sequential/Pull-based)

• Behavior: Sequential. The next value is only pulled when the caller requests it (e.g., via for await...of).
• Use Case: When the next value depends on the previous one, or when you need to manage backpressure.
• Performance: Slower for independent async tasks because tasks are awaited one after another.

Concur Iterable (Concurrent/Push-based)

• Behavior: Concurrent. Values are pushed through the pipeline as fast as possible.
• Use Case: When tasks are independent and you want maximum throughput.
• Performance: Faster for independent async tasks as they run in parallel.

Example Comparison

import { asConcur, forEachConcur, mapConcur, pipe, rangeTo } from 'lfi'

const delay = ms => new Promise(resolve => setTimeout(resolve, ms))

// Concur Iterable: Takes ~100ms (concurrent)
const createConcurIterable = () =>
  pipe(
    rangeTo(0, 3),
    asConcur,
    mapConcur(() => delay(100)),
  )

await forEachConcur(unused => console.log(`Iterated!`), createConcurIterable())

// Async Iterable: Takes ~300ms (sequential)
async function* createAsyncIterable() {
  yield delay(100)
  yield delay(100)
  yield delay(100)
}

for await (const unused of createAsyncIterable()) {
  console.log(`Iterated!`)
}

An OptionalReducer is an object that allows you to transform the final result of a reduction using a finish function.

• Structure: An object containing an add function (matching a FunctionReducer) and an optional finish function.
• Sync: Pass to reduce(). Use or() to handle empty iterables.
• Async: Pass to reduceAsync(). Use orAsync() to handle empty iterables.

// Sync Optional Reducer
import { map, or, pipe, reduce } from 'lfi'

const sumSquaresMessage = numbers =>
  pipe(
    numbers,
    map(number => number * number),
    reduce({
      add: (number1, number2) => number1 + number2,
      finish: sum => `The sum of the squares is ${sum}`,
    }),
    or(() => `There were no numbers!`),
  )

// Async Optional Reducer
import { asAsync, mapAsync, orAsync, pipe, reduceAsync } from 'lfi'

const sumSquaresMessage = async numbers => {
  return await pipe(
    asAsync(numbers),
    mapAsync(number => number * number),
    reduceAsync({
      add: async (number1, number2) => number1 + number2,
      finish: async sum => `The sum of the squares is ${sum}`,
    }),
    orAsync(() => `There were no numbers!`),
  )
}