feat(utils): add composition utilities barrel

[ericelliott]

Add aidd/utils with asyncPipe, pipe, compose

Refactor export tests to verify imports only

Enable optimal tree-shaking with sideEffects: false

---

Note

Introduce aidd/utils barrel exporting asyncPipe, pipe, and compose with TypeScript types; update exports/imports, docs, and tests, and enable tree-shaking.

• Utils (new):
  • Add aidd/utils barrel (utils/index.js, index.d.ts) exporting asyncPipe, pipe, compose.
  • Implement utils/async-pipe.js, pipe.js, compose.js with tests.
• Package Exports & Build:
  • Replace ./asyncPipe export with ./utils (with types); add sideEffects: false; include utils/** in files.
• Refactor Imports:
  • Migrate usages from lib/asyncPipe to aidd/utils or utils/async-pipe in src/server/*, lib/release-helpers.js.
  • Remove legacy lib/asyncPipe.{js,d.ts}.
• Docs:
  • Update docs/server/README.md examples to import asyncPipe from aidd/utils.
• Tests:
  • Update lib/exports.test.js to validate aidd/utils and expanded aidd/server exports and types.
  • Add unit tests for asyncPipe, pipe, and compose.

^{Written by Cursor Bugbot for commit c874274. This will update automatically on new commits. Configure here.}

[ericelliott]

@cursoragent please /review (see ai/rules)

[cursor]

Excellent! I have all the information needed. Let me conduct a comprehensive code review.

🔬 Code Review

🎯 Summary

I've reviewed this PR which adds a aidd/utils barrel export with composition utilities (asyncPipe, pipe, compose), refactors existing code to use the new exports, and enables tree-shaking optimizations.

---

✅ Strengths

1. Code Structure & Organization

• ✅ Clean barrel export pattern with proper TypeScript definitions
• ✅ Well-organized utilities in dedicated /utils folder
• ✅ Successful migration from legacy lib/asyncPipe to new structure
• ✅ All legacy files properly removed (no stray files detected)

2. Coding Standards Adherence

• ✅ Excellent adherence to JavaScript style guide principles:
  • Point-free style with arrow functions
  • Functional composition patterns
  • Concise, expressive code
  • Proper use of reduce and reduceRight
• ✅ Consistent naming conventions (verbs for functions)
• ✅ Minimal, valuable docblocks

3. Test Coverage & Quality

• ✅ All 97 tests passing with comprehensive coverage
• ✅ Tests follow riteway/vitest patterns correctly
• ✅ Proper test isolation with given/should assertions
• ✅ Tests answer the 5 questions (unit, behavior, actual, expected, debugging)
• ✅ Export tests validate both functionality and TypeScript types
• ✅ Edge cases covered (single function, multiple functions)

4. Performance Considerations

• ✅ sideEffects: false enables optimal tree-shaking
• ✅ Pure functions with no side effects
• ✅ Efficient use of native reduce/reduceRight

5. Security (OWASP Top 10 Review)

• ✅ No injection vulnerabilities
• ✅ No authentication/authorization issues
• ✅ No sensitive data exposure
• ✅ No XML external entities (XXE)
• ✅ No broken access control
• ✅ No security misconfiguration
• ✅ No XSS vulnerabilities
• ✅ No insecure deserialization
• ✅ No components with known vulnerabilities
• ✅ No insufficient logging/monitoring issues

6. Architecture & Design

• ✅ Excellent functional composition patterns
• ✅ Proper separation of concerns
• ✅ Consistent with project's functional programming philosophy
• ✅ Package exports configured correctly with types

7. Documentation

• ✅ Server README updated with correct aidd/utils import examples
• ✅ JSDoc comments are minimal yet adequate
• ✅ TypeScript overloads provide clear type guidance

---

🔍 Issues Found

Minor Issues

1. Missing Edge Case Tests

The test suites are good but could be more thorough per the TDD guide's "Thorough - Test expected/very likely edge cases" requirement:

import { assert } from "riteway/vitest";
import { describe, test } from "vitest";

import { asyncPipe } from "./async-pipe.js";

describe("asyncPipe", () => {
  test("pipes async functions in sequence", async () => {
    const add1 = async (x) => x + 1;
    const multiply2 = async (x) => x * 2;
    const subtract3 = async (x) => x - 3;

    const pipeline = asyncPipe(add1, multiply2, subtract3);
    const result = await pipeline(5);

    assert({
      given: "multiple async functions",
      should: "apply functions left-to-right, awaiting each result",
      actual: result,
      expected: 9,
    });
  });

  test("handles single function", async () => {
    const double = async (x) => x * 2;
    const pipeline = asyncPipe(double);
    const result = await pipeline(4);

    assert({
      given: "a single async function",
      should: "apply the function and return its result",
      actual: result,
      expected: 8,
    });
  });
});

Missing test cases:

• Empty function array: asyncPipe()(value)
• Mix of sync and async functions (the implementation supports this per the docblock)
• Error handling/propagation through the pipe

Same applies to pipe.test.js and compose.test.js.

2. TypeScript Type Definitions Could Be More Precise

The type definitions use function overloads but are quite permissive with the any fallback:

export function asyncPipe<T>(...fns: Array<(x: T) => T | Promise<T>>): (x: T) => Promise<T>;
export function asyncPipe<T, U>(...fns: Array<(x: T | U) => U | Promise<U>>): (x: T) => Promise<U>;
export function asyncPipe(...fns: Array<(x: any) => any>): (x: any) => Promise<any>;

While functional, this doesn't provide type safety for longer pipelines with different input/output types at each stage. However, this is a complex TypeScript problem and the current approach is pragmatic.

3. Documentation Comments Could Note Empty Array Behavior

The implementations don't explicitly document what happens with an empty function array, though the behavior is predictable (returns the input unchanged via reduce's identity).

---

💭 Observations & Questions

1. Consistent Formatting
All three utility implementations follow the same elegant multi-line arrow function pattern:

const asyncPipe =
  (...fns) =>
  (x) =>
    fns.reduce(async (y, f) => f(await y), x);

This is excellent - clear, scannable, and consistent.

2. Package Export Strategy
The PR removes the standalone ./asyncPipe export in favor of the ./utils barrel. This is the right call for maintainability, though it is a breaking change for any external users importing aidd/asyncPipe.

3. Documentation Alignment
The server docs correctly updated all examples to import from aidd/utils:

import { asyncPipe } from 'aidd/utils';

Great attention to detail!

---

⚖️ Recommendations

High Priority: None

All critical aspects are solid. Tests pass, no security issues, architecture is sound.

Medium Priority: Enhance Test Coverage

Consider adding edge case tests:

// For all three utilities
test("handles empty function array", () => {
  const pipeline = pipe();
  const result = pipeline(5);
  
  assert({
    given: "no functions",
    should: "return input unchanged",
    actual: result,
    expected: 5,
  });
});

// For asyncPipe specifically
test("handles mix of sync and async functions", async () => {
  const syncAdd = (x) => x + 1;  // sync
  const asyncDouble = async (x) => x * 2;  // async
  
  const pipeline = asyncPipe(syncAdd, asyncDouble);
  const result = await pipeline(5);
  
  assert({
    given: "mixed sync and async functions",
    should: "handle both types correctly",
    actual: result,
    expected: 12,
  });
});

Low Priority: Document Edge Cases

Add a brief note about empty array behavior in the JSDoc comments.

---

📊 Final Assessment

Code Quality: ⭐⭐⭐⭐⭐ (5/5)
Test Coverage: ⭐⭐⭐⭐☆ (4/5) - Could add edge cases
Security: ⭐⭐⭐⭐⭐ (5/5)
Documentation: ⭐⭐⭐⭐⭐ (5/5)
Architecture: ⭐⭐⭐⭐⭐ (5/5)

Overall: ⭐⭐⭐⭐⭐ (4.8/5)

---

✅ Verdict: APPROVED with minor suggestions

This is excellent work that demonstrates:

• Strong functional programming discipline
• Excellent attention to detail (all imports updated, legacy files removed)
• Comprehensive test coverage with proper TDD practices
• Clean architecture aligned with project principles
• Zero security concerns

The suggestions for additional edge case tests are nice-to-haves that would make the test suite even more robust, but they don't block approval. The code is production-ready as-is.

Great job on this refactor! The composition utilities are now properly packaged with tree-shaking support, and the migration from lib/asyncPipe was executed cleanly.

---

 

_{Learn more about Cursor Agents}

[Copilot]

Pull Request Overview

This PR refactors utility functions from the lib directory into a new utils directory with a barrel export pattern, enabling better tree-shaking and consistent import paths across the codebase.

• Introduces a new aidd/utils export providing asyncPipe, pipe, and compose utilities
• Adds comprehensive TypeScript definitions and test coverage for all utilities
• Updates all internal imports and documentation to use the new import paths

Reviewed Changes

Copilot reviewed 17 out of 19 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
utils/pipe.js	New synchronous left-to-right function composition utility
utils/pipe.test.js	Test coverage for the pipe utility
utils/compose.js	New synchronous right-to-left function composition utility
utils/compose.test.js	Test coverage for the compose utility
utils/async-pipe.js	Moved asyncPipe implementation from lib directory with updated file naming convention
utils/async-pipe.test.js	Updated asyncPipe tests with corrected import path and improved test descriptions
utils/index.js	Barrel export aggregating all utility functions
utils/index.d.ts	Comprehensive TypeScript definitions for all exported utilities
package.json	Updated exports to point to new utils barrel, removed main field, added sideEffects: false for tree-shaking
lib/asyncPipe.js	Removed - functionality moved to utils/async-pipe.js
lib/asyncPipe.d.ts	Removed - TypeScript definitions moved to utils/index.d.ts
lib/release-helpers.js	Updated import path to reference new utils/async-pipe.js location
lib/exports.test.js	Updated tests to verify new utils export and expanded server export coverage
src/server/index.js	Updated example import to use new aidd/utils path
src/server/create-route.js	Updated internal import to reference new utils/async-pipe.js location
docs/server/README.md	Updated documentation examples to use new aidd/utils import path
tasks/archive/library-exports-epic.md	Updated documentation to reflect completion of utils barrel export
ai/rules/review.mdc	Added guidance to check for forgotten files and redundancies
ai/rules/review-example.md	Updated example to show new async-pipe.js file naming convention

Comments suppressed due to low confidence (1)

utils/async-pipe.test.js:35

• Consider adding test coverage for the edge case where no functions are provided. For example:

test("handles empty function list", async () => {
  const pipeline = asyncPipe();
  const result = await pipeline(5);

  assert({
    given: "no functions",
    should: "return the initial value unchanged",
    actual: result,
    expected: 5,
  });
});

This would verify the behavior when asyncPipe() is called with no arguments, ensuring it acts as an identity function.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}