Fp Pack

fp-pack AI Agent Skills

Document Version: {{version}}

Additional materials (optional):

• constraints/ (rules, mistakes, troubleshooting)
• reference/ (composition, currying, TypeScript inference)
• examples/ (quick examples)

⚠️ Activation Condition (Read First)

These guidelines apply only when fp-pack is installed in the current project.

Before following this document:

• Check package.json for fp-pack in dependencies/devDependencies
• Check node_modules/fp-pack exists
• Check existing code imports from fp-pack or fp-pack/stream

If fp-pack is not installed, use the project's existing conventions. Do not suggest adding fp-pack unless the user asks.

Core Rules (Keep In Memory)

• Use pipe/pipeAsync for 2+ steps; for a single step, call the function directly.
• Every pipe checks each step; do not use the deprecated *Strict variants (pipeStrict, pipeAsyncStrict, pipeSideEffectStrict, pipeAsyncSideEffectStrict).
• Prefer value-first: pipe(value, ...) / pipeAsync(value, ...) runs immediately and improves inference (the input anchors types). Use functions-first only when you need a reusable pipeline.
• Let pipe infer intermediate parameters; do not add assertions to silence a broken chain. Contextual inference covers 32 steps after the first argument. Compose smaller pipelines beyond that limit; longer already typed chains remain checked.
• pipeWithDeps infers intermediate values and intersects dependency contracts. Default and deprecated variants have identical checks. Annotate the dependency contract where needed, not every value parameter.
• If the first arg is a function, it's treated as composition; wrap function values with from().
• Keep pipeline functions unary; prefer data-last, curried helpers.
• map/filter are for arrays/iterables, not single values.
• Use from() only for constants or 0-arg pipelines (including function values you need to pass as data). Otherwise pass data as the first argument.
• Use pipeSideEffect* only when you need early exit; otherwise use pipe/pipeAsync.
• Never call runPipeResult/matchSideEffect inside pipelines; call at boundaries.
• Prefer isSideEffect for precise narrowing; runPipeResult for unwrapping (pipe results are precise; use generics only for values you widened yourself).
• SideEffect is an instance type: use SideEffect<E> (not typeof SideEffect).
• If TS inference stalls in data-last generics, use pipeHint or a tiny wrapper.
• Use fp-pack/stream for large/lazy iterables; array/object utils for small/eager data.
• Keep DOM/imperative work at the edge; use fp-pack for data transforms.
• Avoid mutation; return new objects/arrays.
• When unsure, check dist/index.d.ts or dist/stream/index.d.ts.

Note: For trivial one-liners, using native JS directly is fine. Reach for fp-pack when composition adds clarity or reuse. Keep pipelines short and readable.

Common Mistakes & Fixes (Top Issues)

Don't wrap data in zero-arg functions

// ❌ BAD
pipe(() => [1, 2, 3], filter((n: number) => n % 2 === 0));

// ✅ GOOD (value-first)
pipe([1, 2, 3], filter((n: number) => n % 2 === 0));

// ✅ GOOD (no-input pipeline)
pipe(from([1, 2, 3]), filter((n: number) => n % 2 === 0))();

ifElse/cond need total branches

const status = ifElse((n: number) => n > 0, from('ok'), from('fail'));

const label = cond<number, string>([
  [(n) => n > 0, () => 'positive'],
  [() => true, () => 'non-positive'] // default keeps it total
]);

map is for arrays/iterables (not single values)

const save = pipe(
  (s: AppState) => JSON.stringify({ todos: s.todos, nextId: s.nextId }),
  tap((json) => localStorage.setItem(STORAGE_KEY, json))
);
save(state);

SideEffect pipelines + runPipeResult belong at the boundary

const pipeline = pipeSideEffect(findUser, (user) => user.email);
const result = runPipeResult(pipeline(input)); // outside the pipeline

DOM APIs are imperative by nature—keep them outside or at the boundary (use tap for final effects).

Troubleshooting Type Errors (Fast Checks)

• Is every step unary? (Pipelines expect one input each.)
• Are you using array/iterable helpers (map, filter, reduce) on non-arrays?
• Did you forget a default case in cond ([() => true, () => ...])?
• Are you returning SideEffect from a pipe pipeline? (Use pipeSideEffect*.)
• Are you calling runPipeResult inside a pipeline? (Move it to the boundary.)
• Are you mixing async steps in pipe instead of pipeAsync?
• Did a data-last generic fail to infer? (Use pipeHint or a tiny wrapper.)
• Are you using from() for constants only, not normal input?
• Is a DOM/imperative step inside the pipeline? (Move it to the edge or use tap.)
• Check dist/index.d.ts / dist/stream/index.d.ts for the expected signature.

If the error persists, reduce the pipeline to the smallest failing step and add types there first.

Quick Examples (3)

Example 1: User Data Processing Pipeline

import { pipe, filter, map, take, sortBy } from 'fp-pack';

const result = pipe(
  users,
  filter((user: User) => user.active),
  sortBy((user) => -user.activityScore),
  map((user) => user.name),
  take(10)
);

Example 2: API Request with Early Exit

import { pipeAsyncSideEffect, SideEffect, runPipeResult } from 'fp-pack';

const result = runPipeResult(
  await pipeAsyncSideEffect(
    'user-123',
    async (userId: string) => {
      const res = await fetch(`/api/users/${userId}`);
      return res.ok ? res : SideEffect.of(() => `HTTP ${res.status}`);
    },
    async (res) => res.json()
  )
);

Example 3: Value-first pipeline

import { pipe, filter, map } from 'fp-pack';

const result = pipe(
  [1, 2, 3, 4, 5],
  filter((n: number) => n % 2 === 0),
  map((n) => n * 2)
);

Core Composition

pipe (sync)

import { pipe, filter, map, take } from 'fp-pack';

const result = pipe(
  users,
  filter((u: User) => u.active),
  map((u) => u.name),
  take(10)
);

pipeAsync (async)

import { pipeAsync } from 'fp-pack';

const user = await pipeAsync(
  userId,
  async (id: string) => fetch(`/api/users/${id}`),
  async (res) => res.json(),
  (data) => data.user
);

Currying & Data-Last

Most multi-arg helpers are data-last and curried. Pair them with value-first pipe(value, ...) to anchor types:

• Good: map(fn), filter(pred), replace(from, to), assoc('k', v), path(['a','b'])
• Single-arg helpers are already unary—just use them directly

TypeScript: Data-last Generic Inference

Some data-last helpers return a generic function whose type is only determined by the final data argument. Prefer value-first pipe(value, ...) so the input anchors generics; use hints when needed.

Quick fix (pipeHint or wrapper)

import { pipe, pipeHint, zip, some } from 'fp-pack';

// Prefer value-first to anchor generics
const values: number[] = [1, 2, 3];
const withValueFirst = pipe(
  values,
  zip([1, 2, 3]),
  some(([a, b]) => a > b)
);

const withPipeHint = pipe(
  pipeHint<number[], Array<[number, number]>>(zip([1, 2, 3])),
  some(([a, b]) => a > b)
);

If you prefer, a tiny wrapper like (values) => zip([1, 2, 3], values) works too.

Utilities that may need a hint in data-last pipelines:

• Array: chunk, drop, take, zip
• Object: assoc, assocPath, dissocPath, evolve, mapValues, merge, mergeDeep, omit, path, pick, prop
• Async: timeout
• Stream: chunk, drop, take, zip