@matthew.ngo/react-filter-pilot NPM

Source Code Structure

This directory contains the complete source code for react-filter-pilot.

Directory Structure

src/
├── hooks/                  # Core React hooks
│   ├── useFilterPilot.ts          # Main hook with filter, pagination, sort
│   ├── useFilterPilotInfinite.ts  # Infinite scrolling variant
│   ├── useFilterMutation.ts       # Mutation helper for data updates
│   ├── useDebounce.ts            # Debounce hook for performance
│   └── useUrlHandler.ts          # Default URL synchronization
│
├── adapters/              # URL synchronization adapters
│   ├── reactRouterDom.ts         # React Router v6 integration
│   ├── nextJs.ts                 # Next.js App Router integration  
│   ├── nextJsPages.ts            # Next.js Pages Router integration
│   └── universal.ts              # Universal adapters (hash, memory, custom)
│
├── types/                 # TypeScript type definitions
│   └── index.ts                  # All interfaces and types
│
├── utils/                 # Utility functions
│   ├── index.ts                  # Utility exports
│   ├── transformUtils.ts         # Value transformation helpers
│   ├── urlUtils.ts               # URL parameter parsing/building
│   ├── filterUtils.ts            # Filter state management utilities
│   └── debounce.ts               # Debounce implementation
│
├── test-utils/            # Testing utilities
│   └── index.ts                  # Mock creators and test helpers
│
├── examples/              # Usage examples
│   ├── mutations.example.tsx     # CRUD operations with mutations
│   └── infinite-scroll.example.tsx # Infinite scrolling implementation
│
└── index.ts               # Main package exports

Core Concepts

1. Hooks

The main functionality is provided through React hooks:

useFilterPilot: Primary hook for filter, pagination, and sorting
useFilterPilotInfinite: Specialized for infinite scrolling
useFilterMutation: Helper for data mutations with optimistic updates

2. Adapters

URL synchronization is handled through adapters:

Each routing library has its own adapter
Custom adapters can be created using createUrlHandler
Memory adapter available for testing

3. Type Safety

Full TypeScript support with:

Generic types for data and filters
Strict type checking for configurations
Exported types for custom implementations

4. Utilities

Helper functions for:

URL parameter transformation
Filter value comparison
Debouncing for performance
Test utilities for mocking

Key Features Implementation

Filter Management

Filters are stored in React state
Debouncing is handled per-filter
URL synchronization is automatic
Value transformations for URL/API

TanStack Query Integration

Deep integration with v4 and v5
All query options supported
Mutation helpers with optimistic updates
Smart cache invalidation

URL Synchronization

Two-way binding with URL
Custom transformation functions
Support for complex data types
Adapter pattern for flexibility

Performance Optimizations

Individual filter debouncing
Efficient re-render prevention
Smart query key structure
Request cancellation support

Extension Points

Custom Adapters

const myAdapter = createUrlHandler({
  getUrl: () => myCustomUrlGetter(),
  setUrl: (url) => myCustomUrlSetter(url),
});

Custom Transformations

{
  name: 'dateRange',
  transformToUrl: (value) => customSerialize(value),
  transformFromUrl: (value) => customDeserialize(value),
  transformForApi: (value) => apiFormat(value),
}

Custom Fetch Logic

fetchFn: async (params) => {
  // Your custom API logic
  const result = await myApi.search(params);
  return {
    data: result.items,
    totalRecords: result.total,
    meta: result.additionalInfo,
  };
}

Testing

The package includes comprehensive test utilities:

Mock creators for all main functions
Test wrappers with providers
Debounce helpers for async testing
Type-safe mock data generators

Development

🚀 Modern Build System

This package uses tsup for ultra-fast, zero-config builds:

# Development with watch mode
pnpm dev

# Production build
pnpm build

# Clean build artifacts
pnpm clean

📊 Performance & Analysis

# Bundle size analysis
pnpm run size
pnpm run analyze:bundle

# Build performance benchmarks
pnpm run benchmark

# Test console log removal
node test-console-removal.js

🔧 Build Features

⚡ 10x faster builds with esbuild (159ms vs 1000ms+)
🗑️ Automatic console removal in production
📦 Dual format output: ESM + CJS
🎯 Tree-shaking optimized
🗺️ Source maps for debugging
📋 TypeScript declarations auto-generated

Contributing

When adding new features: 1. Add types to /types/index.ts 2. Export from /index.ts 3. Add tests using test utilities 4. Update documentation 5. Add usage examples 6. Run pnpm build to verify build works