Configuration

Filter provides flexible configuration options to customize behavior for your specific needs. Configure globally or per-filter call.

Overview

Available configuration options:

• caseSensitive - Control case sensitivity for string matching
• maxDepth - Set maximum depth for nested object traversal
• enableCache - Enable performance caching
• customComparator - Provide custom comparison logic
• debug - Enable debug mode with visual tree output
• verbose - Show additional debug details (requires debug: true)
• showTimings - Display execution timings (requires debug: true)
• colorize - Use ANSI colors in debug output (requires debug: true)

Configuration Options

caseSensitive

Controls whether string comparisons are case-sensitive.

Type: booleanDefault: false

filter(users, 'alice');

filter(users, 'Alice', { caseSensitive: true });

Use Cases:

• Case-insensitive search (default)
• Exact case matching for codes/IDs
• Case-sensitive email validation

Examples:

const users = [
  { name: 'Alice' },
  { name: 'alice' },
  { name: 'ALICE' },
];

filter(users, 'alice');

filter(users, 'alice', { caseSensitive: true });

maxDepth

Controls how deep the filter traverses nested objects.

Type: numberDefault: 3Range: 0-10 (recommended: 1-5)

filter(data, expression, { maxDepth: 5 });

Use Cases:

• Limit traversal for performance
• Control nested object filtering depth
• Prevent excessive recursion

Examples:

interface DeepObject {
  level1: {
    level2: {
      level3: {
        value: string;
      };
    };
  };
}

filter(data, {
  level1: {
    level2: {
      level3: {
        value: 'test'
      }
    }
  }
}, { maxDepth: 3 });

Performance Impact:

• Lower values = faster filtering
• Higher values = more flexible but slower
• Default (3) balances flexibility and performance

enableCache

Enables caching of filter predicates and regex patterns for improved performance.

Type: booleanDefault: false

filter(data, expression, { enableCache: true });

Use Cases:

• Repeated filtering with same expression
• High-frequency filtering operations
• Performance-critical applications

Performance Gains:

• Up to 530x faster for cached predicates
• Significant improvement for regex patterns
• Best for repeated identical queries

Examples:

const expression = { age: { $gte: 18 } };

filter(users, expression, { enableCache: true });
filter(users, expression, { enableCache: true });

Cache Management:

import { clearFilterCache, getFilterCacheStats } from '@mcabreradev/filter';

clearFilterCache();

const stats = getFilterCacheStats();
console.log(stats);

debug

Enable debug mode to visualize filter execution with tree output and statistics.

Type: booleanDefault: false

filter(users, { city: 'Berlin' }, { debug: true });

Use Cases:

• Understanding complex filter logic
• Debugging why items match or don't match
• Performance analysis
• Development and testing

Output:

Filter Debug Tree
└── city = "Berlin" (2/3 matched, 66.7%)

Statistics:
├── Matched: 2 / 3 items (66.7%)
├── Execution Time: 0.45ms
├── Cache Hit: No
└── Conditions Evaluated: 1

Examples:

filter(users, {
  $and: [
    { city: 'Berlin' },
    { age: { $gte: 25 } }
  ]
}, { debug: true });

Debug Options:

Combine with verbose, showTimings, and colorize for enhanced output:

filter(users, expression, {
  debug: true,
  verbose: true,
  showTimings: true,
  colorize: true
});

See Debug Mode Guide for complete documentation.

verbose

Show additional details in debug output (only works with debug: true).

Type: booleanDefault: false

filter(users, expression, {
  debug: true,
  verbose: true
});

showTimings

Display execution time for each node in debug tree (only works with debug: true).

Type: booleanDefault: false

filter(users, expression, {
  debug: true,
  showTimings: true
});

colorize

Use ANSI colors in debug output for better readability (only works with debug: true).

Type: booleanDefault: false

filter(users, expression, {
  debug: true,
  colorize: true
});

customComparator

Provide custom comparison logic for string matching.

Type: (actual: unknown, expected: unknown) => booleanDefault: Case-insensitive substring matching

filter(data, expression, {
  customComparator: (actual, expected) => {
    return String(actual) === String(expected);
  }
});

Use Cases:

• Custom string comparison logic
• Locale-specific comparisons
• Special matching rules
• Domain-specific equality

Examples:

filter(users, 'alice', {
  customComparator: (actual, expected) => {
    return String(actual).toLowerCase() === String(expected).toLowerCase();
  }
});

Advanced Comparator:

filter(products, 'widget', {
  customComparator: (actual, expected) => {
    const actualStr = String(actual).toLowerCase().trim();
    const expectedStr = String(expected).toLowerCase().trim();

    return actualStr.includes(expectedStr) ||
           expectedStr.includes(actualStr);
  }
});

Configuration Methods

Per-Filter Configuration

Pass options to individual filter calls:

filter(users, expression, {
  caseSensitive: true,
  maxDepth: 5,
  enableCache: true
});

Configuration Builder

Use the configuration builder for reusable configs:

import { createFilterConfig } from '@mcabreradev/filter';

const config = createFilterConfig({
  caseSensitive: true,
  enableCache: true,
  maxDepth: 4
});

filter(users, expression, config);

Merging Configurations

Merge multiple configurations:

import { mergeConfig } from '@mcabreradev/filter';

const baseConfig = { caseSensitive: true };
const cacheConfig = { enableCache: true };

const merged = mergeConfig(baseConfig, cacheConfig);

Real-World Examples

Case-Sensitive Code Matching

const products = [
  { sku: 'PRD-001' },
  { sku: 'prd-001' },
];

filter(products, { sku: 'PRD-001' }, {
  caseSensitive: true
});

Deep Object Filtering

interface Organization {
  department: {
    team: {
      lead: {
        name: string;
      };
    };
  };
}

filter(orgs, {
  department: {
    team: {
      lead: {
        name: 'Alice'
      }
    }
  }
}, {
  maxDepth: 4
});

High-Performance Dashboard

const dashboardConfig = {
  enableCache: true,
  caseSensitive: false,
  maxDepth: 3
};

const activeUsers = filter(users, { status: 'active' }, dashboardConfig);
const premiumUsers = filter(users, { premium: true }, dashboardConfig);

Custom Fuzzy Matching

filter(products, 'laptop', {
  customComparator: (actual, expected) => {
    const actualStr = String(actual).toLowerCase();
    const expectedStr = String(expected).toLowerCase();

    const distance = levenshteinDistance(actualStr, expectedStr);
    return distance <= 2;
  }
});

Configuration Patterns

Development vs Production

const config = {
  enableCache: process.env.NODE_ENV === 'production',
  caseSensitive: false,
  maxDepth: 3
};

filter(data, expression, config);

Feature Flags

const config = {
  enableCache: featureFlags.caching,
  caseSensitive: featureFlags.strictMatching,
  maxDepth: featureFlags.deepSearch ? 5 : 3
};

User Preferences

const getUserConfig = (preferences) => ({
  caseSensitive: preferences.exactMatch,
  enableCache: preferences.performanceMode,
  maxDepth: preferences.searchDepth || 3
});

filter(data, expression, getUserConfig(userPreferences));

Performance Guidelines

When to Enable Caching

Enable caching when:

• Filtering the same data repeatedly
• Using identical expressions multiple times
• Performance is critical
• Working with large datasets

Don't enable caching when:

• Expressions change frequently
• Memory is constrained
• Filtering small datasets
• One-time queries

Optimal maxDepth

Use Case	Recommended maxDepth
Flat objects	1
Simple nesting	2-3 (default)
Complex structures	4-5
Very deep nesting	6+ (use sparingly)

caseSensitive Impact

• Case-insensitive (default): Slightly slower but more flexible
• Case-sensitive: Faster but stricter matching

Best Practices

1. Use Sensible Defaults

const defaultConfig = {
  caseSensitive: false,
  maxDepth: 3,
  enableCache: false
};

2. Enable Caching for Repeated Queries

const config = { enableCache: true };

setInterval(() => {
  const active = filter(users, { status: 'active' }, config);
  updateDashboard(active);
}, 1000);

3. Adjust maxDepth Based on Data

const shallowConfig = { maxDepth: 2 };
const deepConfig = { maxDepth: 5 };

filter(simpleData, expression, shallowConfig);
filter(complexData, expression, deepConfig);

4. Document Custom Comparators

const fuzzyComparator = (actual, expected) => {
  return similarity(actual, expected) > 0.8;
};

filter(data, expression, {
  customComparator: fuzzyComparator
});

5. Clear Cache Periodically

import { clearFilterCache } from '@mcabreradev/filter';

setInterval(() => {
  clearFilterCache();
}, 60000);

TypeScript Support

Full type safety for configuration:

import type { FilterOptions } from '@mcabreradev/filter';

const config: FilterOptions = {
  caseSensitive: true,
  maxDepth: 4,
  enableCache: true,
  customComparator: (a, b) => String(a) === String(b)
};

filter(users, expression, config);

Troubleshooting

Nested Properties Not Matching

Increase maxDepth:

filter(data, expression, { maxDepth: 5 });

Case Sensitivity Issues

Check caseSensitive setting:

filter(users, 'Alice', { caseSensitive: false });

Performance Problems

Enable caching:

filter(data, expression, { enableCache: true });

Custom Comparator Not Working

Verify comparator signature:

const comparator = (actual: unknown, expected: unknown): boolean => {
  return String(actual) === String(expected);
};

filter(data, expression, { customComparator: comparator });

Advanced Configuration

Combining All Options

const advancedConfig = {
  caseSensitive: true,
  maxDepth: 5,
  enableCache: true,
  customComparator: (actual, expected) => {
    if (typeof actual === 'string' && typeof expected === 'string') {
      return actual.localeCompare(expected, 'en', { sensitivity: 'base' }) === 0;
    }
    return actual === expected;
  }
};

filter(data, expression, advancedConfig);

Environment-Based Configuration

const getConfig = (): FilterOptions => {
  const env = process.env.NODE_ENV;

  return {
    caseSensitive: env === 'production',
    maxDepth: env === 'development' ? 5 : 3,
    enableCache: env === 'production',
  };
};

filter(data, expression, getConfig());

See Also

• Memoization - Caching and performance
• Nested Objects - maxDepth usage
• Wildcards - Case sensitivity
• Performance Benchmarks - Optimization tips