fp-pack 0.5.0 → 0.6.0

package/dist/skills/fp-pack.md

@@ -1,6 +1,6 @@
 # fp-pack AI Agent Skills
 
-Document Version: 0.5.0
+Document Version: 0.6.0
 
 This document provides guidelines for AI coding assistants when working in projects that use fp-pack. Follow these instructions to write clean, declarative, functional code using fp-pack's utilities.
 
@@ -122,7 +122,7 @@ const finalValue = runPipeResult(processDataPipeline(input));
 **Key SideEffect functions:**
 - `SideEffect.of(fn, label?)` - Create a side effect container
 - `isSideEffect(value)` - Type guard for **runtime checking** whether a value is a SideEffect
-- `runPipeResult<T, R>(result)` - Execute SideEffect or return value (call **OUTSIDE** pipelines, provide generics for type safety). **⚠️ CRITICAL:** `runPipeResult<T, R=any>` has default `R=any`, so using it without generics returns `any` type. Always provide generics for type safety
+- `runPipeResult<T, R>(result)` - Execute SideEffect or return value (call **OUTSIDE** pipelines). If the input type is precise, inference is preserved. If the input is widened to `SideEffect<any>` or `any`, the result becomes `any` unless you provide generics.
 - `matchSideEffect(result, { value, effect })` - Pattern match on result
 
 **Type-safe result handling:**
@@ -140,32 +140,34 @@ const processNumbers = pipeSideEffect(
 
 const result = processNumbers([1, 2, 3, 4, 5]);
 
-// ✅ CORRECT: Use isSideEffect for runtime checking + provide generics to runPipeResult
+// ✅ CORRECT: Use isSideEffect for runtime checking
 if (!isSideEffect(result)) {
   // TypeScript knows: result is number[]
   const sum: number = result.reduce((a, b) => a + b, 0);
 } else {
   // TypeScript knows: result is SideEffect<string>
-  // But runPipeResult still returns number[] | string (not fully narrowed)
-  const error = runPipeResult<number[], string>(result);  // error: number[] | string
+  // runPipeResult returns number[] | string (not fully narrowed)
+  const error = runPipeResult(result);  // number[] | string
 }
 
-// ❌ WRONG: runPipeResult without generics
-const value = runPipeResult(result);  // result: any (no type information!)
+// ⚠️ If the result type is widened to SideEffect<any>, inference is lost
+const widened: number[] | SideEffect<any> = result;
+const unsafeValue = runPipeResult(widened);  // number[] | any
 
-// ✅ CORRECT: Provide generics to runPipeResult
-const value = runPipeResult<number[], string>(result);  // result: number[] | string (union type - safe but not narrowed)
+// ✅ CORRECT: Provide generics to recover a safe union
+const safeValue = runPipeResult<number[], string>(result);  // result: number[] | string (union type - safe but not narrowed)
 ```
 
 **⚠️ CRITICAL: runPipeResult Type Safety**
 
 `runPipeResult<T, R=any>` has a default type parameter `R=any`. This means:
 
-- ❌ **Without generics**: `const result = runPipeResult(pipeline(data));` returns `any` type (unsafe!)
-- ✅ **With generics**: `runPipeResult<SuccessType, ErrorType>(result)` returns union type `SuccessType | ErrorType` (type-safe)
-- ✅ **With isSideEffect**: Use for runtime checking whether a value is SideEffect
+- ✅ **Precise input types**: `T | SideEffect<'E'>` preserves `T | 'E'` without extra annotations.
+- ⚠️ **Widened inputs**: `T | SideEffect<any>` (or `any`) collapses to `any`.
+- ✅ **With generics**: `runPipeResult<SuccessType, ErrorType>(result)` restores a safe union when inference is lost.
+- ✅ **With isSideEffect**: Prefer for runtime narrowing when you need branch-specific types.
 
-**Always provide generics to `runPipeResult`** for type safety. Use `isSideEffect` for runtime type checking.
+Provide generics when inference is lost; prefer `isSideEffect` for precise narrowing.
 
 ## Stream Functions - Lazy Iterable Processing
 
@@ -520,7 +522,7 @@ const gradeToLetter = cond([
 
 - `prop` returns `T[K] | undefined`. Use `propOr` (or guard) before array operations.
 - `ifElse` expects **functions** for both branches. If you already have a value, wrap it: `() => value` or use `from(value)` for cleaner constant branches.
-- Use `from(value)` when you need a unary function that ignores input (handy for `ifElse`/`cond` branches and data-first patterns).
+- Use `from(value)` when you need a unary function that ignores input (handy for `ifElse`/`cond` branches and data-first patterns). Pipelines that start with `from(...)` can be called without an initial input value.
 - `cond` returns `R | undefined`. Add a default branch and coalesce when you need a strict result.
 - In `pipeSideEffect`, keep step return types aligned to avoid wide unions.
 
@@ -673,8 +675,8 @@ const updateUser = assoc('lastLogin', new Date());
 - **Pure async operations**: `pipeAsync`
 - **Error handling with SideEffect**: `pipeSideEffect` (sync) / `pipeAsyncSideEffect` (async)
 - **Strict SideEffect unions**: `pipeSideEffectStrict` (sync) / `pipeAsyncSideEffectStrict` (async)
-- **Type-safe result handling**: `isSideEffect` for precise type narrowing (⚠️ **ALWAYS prefer this over bare `runPipeResult`** to avoid `any` types)
-- **Execute SideEffect**: `runPipeResult` (call OUTSIDE pipelines). **⚠️ CRITICAL:** Returns `any` type without type narrowing due to default `R=any` parameter
+- **Type-safe result handling**: `isSideEffect` for precise type narrowing (prefer this when you need branch-specific types)
+- **Execute SideEffect**: `runPipeResult` (call OUTSIDE pipelines). If the input is widened to `SideEffect<any>`/`any`, the result becomes `any`; provide generics to recover
 - **Large datasets**: `stream/*` functions
 - **Conditionals**: `ifElse`, `when`, `unless`, `cond`
 - **Object access**: `prop`, `propStrict`, `path`, `pick`, `omit`

package/dist/stream/index.d.ts

@@ -21,4 +21,5 @@ export { default as toArray } from './toArray';
 export { default as toAsync } from './toAsync';
 export { default as zip } from './zip';
 export { default as zipWith } from './zipWith';
+export type { AnyIterable, AnyIterableInput, PromiseLikeValue } from './utils';
 //# sourceMappingURL=index.d.ts.map

package/dist/stream/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/stream/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,OAAO,IAAI,GAAG,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,IAAI,GAAG,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/stream/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,OAAO,IAAI,GAAG,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,IAAI,GAAG,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/C,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fp-pack",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Functional programming utilities library for TypeScript",
   "keywords": [

package/src/implement/composition/curry.ts

@@ -3,14 +3,14 @@
  * Supports functions with 2-5 parameters and keeps data-last call order.
  */
 
-type Curry2<Fn> = Fn extends (a: infer A, b: infer B) => infer R
+export type Curry2<Fn> = Fn extends (a: infer A, b: infer B) => infer R
   ? {
       (...args: [A]): (b: B) => R;
       (...args: [A, B]): R;
     }
   : never;
 
-type Curry3<Fn> = Fn extends (a: infer A, b: infer B, c: infer C) => infer R
+export type Curry3<Fn> = Fn extends (a: infer A, b: infer B, c: infer C) => infer R
   ? {
       (...args: [A]): (b: B) => (c: C) => R;
       (...args: [A, B]): (c: C) => R;
@@ -18,7 +18,7 @@ type Curry3<Fn> = Fn extends (a: infer A, b: infer B, c: infer C) => infer R
     }
   : never;
 
-type Curry4<Fn> = Fn extends (a: infer A, b: infer B, c: infer C, d: infer D) => infer R
+export type Curry4<Fn> = Fn extends (a: infer A, b: infer B, c: infer C, d: infer D) => infer R
   ? {
       (...args: [A]): (b: B) => (c: C) => (d: D) => R;
       (...args: [A, B]): (c: C) => (d: D) => R;
@@ -27,7 +27,7 @@ type Curry4<Fn> = Fn extends (a: infer A, b: infer B, c: infer C, d: infer D) =>
     }
   : never;
 
-type Curry5<Fn> = Fn extends (a: infer A, b: infer B, c: infer C, d: infer D, e: infer E) => infer R
+export type Curry5<Fn> = Fn extends (a: infer A, b: infer B, c: infer C, d: infer D, e: infer E) => infer R
   ? {
       (...args: [A]): (b: B) => (c: C) => (d: D) => (e: E) => R;
       (...args: [A, B]): (c: C) => (d: D) => (e: E) => R;
@@ -53,7 +53,7 @@ type CurryByArity<Fn extends (...args: any[]) => any> = Parameters<Fn>['length']
         ? Curry5<Fn>
         : CurryVariadic<Fn>;
 
-type Curried<Fn extends (...args: any[]) => any> = CurryByArity<Fn>;
+export type Curried<Fn extends (...args: any[]) => any> = CurryByArity<Fn>;
 
 function curry<Fn extends (...args: any[]) => any>(fn: Fn): Curried<Fn>;
 

package/src/implement/composition/index.ts

@@ -3,15 +3,18 @@ export { default as pipeSideEffect } from './pipeSideEffect';
 export { default as pipeSideEffectStrict } from './pipeSideEffectStrict';
 export { default as compose } from './compose';
 export { default as curry } from './curry';
+export type { Curried, Curry2, Curry3, Curry4, Curry5 } from './curry';
 export { default as partial } from './partial';
 export { default as flip } from './flip';
 export { default as complement } from './complement';
 export { default as identity } from './identity';
 export { default as constant } from './constant';
 export { default as from } from './from';
+export type { FromFn } from './from';
 export { default as tap } from './tap';
 export { default as once } from './once';
 export { default as memoize } from './memoize';
 export { default as SideEffect } from './sideEffect';
 export { SideEffect as SideEffectClass } from './sideEffect';
 export { isSideEffect, matchSideEffect, runPipeResult } from './sideEffect';
+export type { MatchHandlers } from './sideEffect';

package/src/implement/composition/pipe.ts

@@ -1,3 +1,5 @@
+import type { FromFn } from './from';
+
 type UnaryFn<A, R> = (a: A) => R;
 type ZeroFn<R> = () => R;
 type PipeInput<Fns extends UnaryFn<any, any>[]> = Fns extends [UnaryFn<infer A, any>, ...UnaryFn<any, any>[]]
@@ -11,6 +13,7 @@ type PipeOutput<Fns extends UnaryFn<any, any>[]> = Fns extends [UnaryFn<any, inf
       : never
     : never;
 type Pipe<Fns extends UnaryFn<any, any>[]> = (input: PipeInput<Fns>) => PipeOutput<Fns>;
+type PipeFrom<Fns extends [FromFn<any>, ...UnaryFn<any, any>[]]> = (input?: PipeInput<Fns>) => PipeOutput<Fns>;
 
 function pipe<R>(ab: ZeroFn<R>): () => R;
 function pipe<B, R>(ab: ZeroFn<B>, bc: UnaryFn<B, R>): () => R;
@@ -73,6 +76,7 @@ function pipe<B, C, D, E, F, G, H, I, J, R>(
   ij: UnaryFn<I, J>,
   jk: UnaryFn<J, R>
 ): () => R;
+function pipe<Fns extends [FromFn<any>, ...UnaryFn<any, any>[]]>(...funcs: Fns): PipeFrom<Fns>;
 function pipe<A, R>(ab: UnaryFn<A, R>): (a: A) => R;
 function pipe<A, B, R>(ab: UnaryFn<A, B>, bc: UnaryFn<B, R>): (a: A) => R;
 function pipe<A, B, C, R>(ab: UnaryFn<A, B>, bc: UnaryFn<B, C>, cd: UnaryFn<C, R>): (a: A) => R;

package/src/implement/composition/pipe.type-test.ts

@@ -1,4 +1,4 @@
-import SideEffect from './sideEffect';
+import SideEffect, { runPipeResult } from './sideEffect';
 import from from './from';
 import pipe from './pipe';
 import pipeSideEffect from './pipeSideEffect';
@@ -71,6 +71,13 @@ export const pipeFromTenValue = pipeFromTen('input');
 type PipeFromTenValueExpected = string;
 export type PipeFromTenValueIsStrict = Expect<Equal<typeof pipeFromTenValue, PipeFromTenValueExpected>>;
 
+export const pipeFromTenValueNoInput = pipeFromTen();
+
+type PipeFromTenValueNoInputExpected = string;
+export type PipeFromTenValueNoInputIsStrict = Expect<
+  Equal<typeof pipeFromTenValueNoInput, PipeFromTenValueNoInputExpected>
+>;
+
 export const pipeWithSideEffectInput = pipeSideEffect(
   (value: number) => value + 1,
   (value) => value * 2,
@@ -289,6 +296,15 @@ type StrictSideEffectValue = ValueUnion<typeof strictPipeSideEffectResult>;
 type StrictSideEffectValueExpected = number;
 export type PipeSideEffectStrictValue = Expect<Equal<StrictSideEffectValue, StrictSideEffectValueExpected>>;
 
+export const strictPipeSideEffectRunResult = runPipeResult(strictPipeSideEffectResult);
+
+type StrictPipeSideEffectRunExpected =
+  | ValueUnion<typeof strictPipeSideEffectResult>
+  | EffectUnion<typeof strictPipeSideEffectResult>;
+export type PipeSideEffectStrictRunPipeResultIsStrict = Expect<
+  Equal<typeof strictPipeSideEffectRunResult, StrictPipeSideEffectRunExpected>
+>;
+
 export const strictPipeSideEffectInput = strictPipeSideEffect(SideEffect.of(() => 'INPUT' as const));
 
 type StrictSideEffectInputEffects = EffectUnion<typeof strictPipeSideEffectInput>;

package/src/implement/composition/sideEffect.ts

@@ -15,7 +15,7 @@ export class SideEffect<T = unknown> {
   }
 }
 
-type MatchHandlers<T, RValue, REffect> = {
+export type MatchHandlers<T, RValue, REffect> = {
   value: (value: T) => RValue;
   effect: (sideEffect: SideEffect) => REffect;
 };

package/src/implement/object/assocPath.ts

@@ -1,6 +1,5 @@
 import curry from '../composition/curry';
-
-type PathKey = string | number | symbol;
+import type { PathKey } from './pathKey';
 
 const isIndexKey = (key: PathKey): key is number | `${number}` => {
   if (typeof key === 'number') {
@@ -62,3 +61,4 @@ function assocPath<T = unknown>(pathArray: PathKey[], value: unknown, obj: unkno
 
 const curriedAssocPath = curry(assocPath) as AssocPath;
 export default curriedAssocPath;
+export type { PathKey };

package/src/implement/object/dissocPath.ts

@@ -1,6 +1,5 @@
 import curry from '../composition/curry';
-
-type PathKey = string | number | symbol;
+import type { PathKey } from './pathKey';
 
 const isIndexKey = (key: PathKey): key is number | `${number}` => {
   if (typeof key === 'number') {
@@ -78,3 +77,4 @@ function dissocPath<T = unknown>(pathArray: PathKey[], obj: T): T {
 
 const curriedDissocPath = curry(dissocPath) as DissocPath;
 export default curriedDissocPath;
+export type { PathKey };

package/src/implement/object/index.ts

@@ -19,3 +19,4 @@ export { default as mapValues } from './mapValues';
 export { default as evolve } from './evolve';
 export { default as has } from './has';
 export { default as hasPath } from './hasPath';
+export type { PathKey } from './pathKey';

package/src/implement/object/path.ts

@@ -1,16 +1,18 @@
 import curry from '../composition/curry';
+import type { PathKey } from './pathKey';
 
 type Path = {
-  (pathArray: string[]): <T>(obj: any) => T | undefined;
-  <T>(...args: [pathArray: string[], obj: any]): T | undefined;
+  (pathArray: PathKey[]): <T>(obj: any) => T | undefined;
+  <T>(...args: [pathArray: PathKey[], obj: any]): T | undefined;
 };
 
 /**
  * path - 안전한 깊은 프로퍼티 접근
  */
-function path<T>(pathArray: string[], obj: any): T | undefined {
+function path<T>(pathArray: PathKey[], obj: any): T | undefined {
   return pathArray.reduce((current, key) => (current == null ? undefined : current[key]), obj) as T | undefined;
 }
 
 const curriedPath = curry(path) as Path;
 export default curriedPath;
+export type { PathKey };

package/src/implement/object/pathKey.ts

@@ -0,0 +1 @@
+export type PathKey = string | number | symbol;

package/src/implement/object/pathOr.ts

@@ -1,18 +1,20 @@
 import curry from '../composition/curry';
+import type { PathKey } from './pathKey';
 
 type PathOr = {
-  <D>(...args: [defaultValue: D]): <T>(pathArray: string[]) => (obj: any) => T | D;
-  <D>(...args: [defaultValue: D, pathArray: string[]]): <T>(obj: any) => T | D;
-  <T, D>(...args: [defaultValue: D, pathArray: string[], obj: any]): T | D;
+  <D>(...args: [defaultValue: D]): <T>(pathArray: PathKey[]) => (obj: any) => T | D;
+  <D>(...args: [defaultValue: D, pathArray: PathKey[]]): <T>(obj: any) => T | D;
+  <T, D>(...args: [defaultValue: D, pathArray: PathKey[], obj: any]): T | D;
 };
 
 /**
  * pathOr - 기본값이 있는 깊은 프로퍼티 접근
  */
-function pathOr<T, D>(defaultValue: D, pathArray: string[], obj: any): T | D {
+function pathOr<T, D>(defaultValue: D, pathArray: PathKey[], obj: any): T | D {
   const value = pathArray.reduce((current, key) => (current == null ? undefined : current[key]), obj) as T | undefined;
   return value == null ? defaultValue : value;
 }
 
 const curriedPathOr = curry(pathOr) as PathOr;
 export default curriedPathOr;
+export type { PathKey };

package/src/index.ts

@@ -30,3 +30,6 @@ export * from './implement/nullable';
 
 // Debug
 export * from './implement/debug';
+
+// Stream Types
+export type { AnyIterable, AnyIterableInput, PromiseLikeValue } from './stream/utils';

package/src/stream/index.ts

@@ -21,3 +21,4 @@ export { default as toArray } from './toArray';
 export { default as toAsync } from './toAsync';
 export { default as zip } from './zip';
 export { default as zipWith } from './zipWith';
+export type { AnyIterable, AnyIterableInput, PromiseLikeValue } from './utils';