Troubleshooting

Common issues and solutions when using @mcabreradev/filter.

Installation Issues

Package Not Found

Problem: npm install @mcabreradev/filter fails with 404 error.

Solution:

npm cache clean --force
npm install @mcabreradev/filter

TypeScript Errors After Installation

Problem: TypeScript cannot find type definitions.

Solution:

npm install --save-dev @types/node

Ensure tsconfig.json includes:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

React Integration Issues

Hook Returns Undefined

Problem: useFilter returns undefined for filtered.

Cause: Data prop is null or undefined.

Solution:

const { filtered } = useFilter(data ?? [], expression);

Infinite Re-renders

Problem: Component re-renders infinitely when using useFilter.

Cause: Expression or options object recreated on every render.

Solution:

const expression = useMemo(() => ({ age: { $gte: 18 } }), []);
const options = useMemo(() => ({ memoize: true }), []);

const { filtered } = useFilter(data, expression, options);

Stale Closure in useEffect

Problem: filtered data is stale inside useEffect.

Solution:

useEffect(() => {
  console.log(filtered);
}, [filtered]);

Vue Integration Issues

Reactivity Not Working

Problem: Filtered results don't update when data changes.

Cause: Data is not reactive.

Solution:

import { ref } from 'vue';

const data = ref([...]);
const expression = ref({ status: 'active' });

const { filtered } = useFilter(data, expression);

ComputedRef Type Errors

Problem: TypeScript errors when accessing filtered.value.

Solution:

import type { ComputedRef } from 'vue';

const { filtered }: { filtered: ComputedRef<User[]> } = useFilter(data, expression);

Svelte Integration Issues

Store Not Updating

Problem: $filtered doesn't update in template.

Cause: Not subscribing to store properly.

Solution:

<script lang="ts">
  import { useFilter } from '@mcabreradev/filter/svelte';

  const { filtered } = useFilter(data, expression);
</script>

{#each $filtered as item}
  <div>{item.name}</div>
{/each}

TypeScript Errors with Stores

Problem: Type errors when using Svelte stores.

Solution:

import type { Readable } from 'svelte/store';
import type { User } from './types';

const { filtered }: { filtered: Readable<User[]> } = useFilter(data, expression);

Performance Issues

Slow Filtering on Large Datasets

Problem: Filtering takes too long with 10,000+ items.

Solution 1: Enable memoization

const { filtered } = useFilter(data, expression, { memoize: true });

Solution 2: Use lazy evaluation

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

const lazyFilter = createLazyFilter(data, expression);
const first10 = lazyFilter.take(10).toArray();

Solution 3: Use pagination

const { filtered, currentPage, nextPage } = usePaginatedFilter(
  data,
  expression,
  50
);

Memory Leaks

Problem: Memory usage grows over time.

Cause: Memoization cache not cleared.

Solution:

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

useEffect(() => {
  return () => {
    clearMemoizationCache();
  };
}, []);

Expression Syntax Issues

Operator Not Working

Problem: Custom operator doesn't filter correctly.

Check: Operator name and syntax

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

Available operators:

• $eq, $ne, $gt, $gte, $lt, $lte
• $in, $nin, $contains, $startsWith, $endsWith
• $regex, $and, $or, $not

Nested Property Access Fails

Problem: Cannot filter by nested properties.

Solution:

const expression = {
  'address.city': { $eq: 'New York' }
};

Or use dot notation:

const expression = {
  address: {
    city: { $eq: 'New York' }
  }
};

Case-Sensitive String Matching

Problem: String comparisons are case-sensitive.

Solution: Use $regex with case-insensitive flag

const expression = {
  name: { $regex: /john/i }
};

Type Safety Issues

Generic Type Not Inferred

Problem: TypeScript doesn't infer item type.

Solution: Explicitly provide generic type

interface User {
  id: number;
  name: string;
}

const { filtered } = useFilter<User>(data, expression);

Expression Type Errors

Problem: Expression doesn't match data type.

Solution: Use type-safe expression builder

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

const expression: Expression<User> = {
  age: { $gte: 18 },
  status: { $eq: 'active' }
};

Debugging Tips

Enable Debug Logging

const options = {
  debug: true
};

const { filtered } = useFilter(data, expression, options);

Inspect Expression

console.log('Expression:', JSON.stringify(expression, null, 2));
console.log('Data count:', data.length);
console.log('Filtered count:', filtered.length);

Check Operator Processing

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

const result = processOperator(value, operator, operand);
console.log('Operator result:', result);

Common Patterns Issues

Combining Multiple Filters

Problem: Multiple filters not working together.

Solution: Use $and operator

const expression = {
  $and: [
    { age: { $gte: 18 } },
    { status: { $eq: 'active' } },
    { role: { $in: ['admin', 'user'] } }
  ]
};

Dynamic Filter Building

Problem: Building filters dynamically is complex.

Solution: Use configuration builder

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

const config = createFilterConfig<User>()
  .where('age', { $gte: 18 })
  .where('status', { $eq: 'active' })
  .build();

Getting Help

If you're still experiencing issues:

1. Check the API Reference
2. Review Examples
3. Search GitHub Issues
4. Open a new issue with:
   • Library version
   • Framework and version
   • Minimal reproduction code
   • Expected vs actual behavior

Related Resources

• Configuration Guide
• Best Practices
• Performance Optimization
• Migration Guide