Add multiple filter values support

[jdesboeufs]

Add multiple filter values support and adapt to addok-geocode-stream v0.27

This PR adds support for multiple values in filters, compatible with addok-cluster 0.11.0, and adapts the CSV endpoint to the new addok-geocode-stream v0.27.0 API.

🎯 Overview

addok-cluster 0.11.0 introduced the ability to provide multiple values for filters (as arrays of strings). This PR implements this feature across all API endpoints while maintaining backward compatibility.

✨ Features

1. Multiple Filter Values Support

All endpoints now accept multiple values for filters using two syntaxes:

Using + separator:

GET /search?q=paris&citycode=75001+75002+75003

Using repeated parameters:

GET /search?q=paris&citycode=75001&citycode=75002&citycode=75003

Both syntaxes can be combined and will be automatically deduplicated.

2. Batch Endpoint Enhancement

Filters in batch requests now support:

• String values with + separator: "citycode": "75001+75002"
• Array values: "citycode": ["75001", "75002"]
• Global filters (applied to all requests via params)
• Per-request filters (merged with global filters)

Example:

{
  "params": {
    "filters": {"type": "municipality+locality"}
  },
  "requests": [
    {
      "id": "req1",
      "operation": "geocode",
      "params": {
        "q": "lille",
        "filters": {"citycode": ["59000", "59100"]}
      }
    }
  ]
}

3. CSV Endpoint Adaptation

Updated to work with addok-geocode-stream v0.27.0:

• Migrated from hardcoded filter parameters (citycode, postcode, type) to dynamic filters object
• Filter configuration is now driven by ADDOK_FILTERS environment variable
• More extensible architecture for future filter additions

🔧 Implementation Details

New utility function:

• parseFilterValues(value): Parses, splits (on + or space), trims, and deduplicates filter values

Modified functions:

• formatParams() in search.js: Now returns filter values as arrays
• normalizeFilters() in batch.js: Processes both global and per-request filters

CSV changes:

• Import ADDOK_FILTERS in csv.js
• Build geocodeOptions.filters dynamically from environment configuration
• Remove hardcoded filter parameters

✅ Testing

• 42 tests passing (0 failing)
• Added 15+ new test cases covering:
  • parseFilterValues() behavior (single value, multiple values, arrays, duplicates, whitespace)
  • formatParams() with multiple filter values
  • Batch endpoint with various filter configurations
• Updated existing tests to reflect new array-based filter format
• Code coverage: search.js 98%, batch.js 100%

📚 Documentation

• Updated README with:
  • Multi-value filter syntax examples for all endpoints
  • Batch request examples with filters
  • CSV filter behavior clarification (parameters specify column names)
• Added inline code comments for new functions

🔄 Breaking Changes

None. The implementation is backward compatible:

• Single filter values still work (automatically converted to arrays internally)
• Existing API consumers will continue to work without changes
• Filter values are normalized consistently across all endpoints

📦 Dependencies

• Updated addok-geocode-stream from ^0.26.0 to ^0.27.0
• Updated addok-cluster to ^0.11.0

🎬 Commits

1. chore(deps): update addok-cluster to 0.11.0
2. Adapt CSV endpoint to new addok-geocode-stream filters API
3. Add support for multiple filter values

---

Ready for review ✅

[Copilot]

Pull Request Overview

This PR adds support for multiple filter values across all API endpoints, maintaining backward compatibility, and updates dependencies to work with addok-cluster 0.11.0 and addok-geocode-stream 0.27.0.

Key changes:

• Filters now accept multiple values using + separator or repeated parameters (e.g., ?citycode=59000+59100 or ?citycode=59000&citycode=59100)
• CSV endpoint migrated from hardcoded filter parameters to dynamic filters object driven by ADDOK_FILTERS environment variable
• Batch endpoint enhanced to support filters in both global and per-request configurations

Reviewed Changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
package.json	Updated dependencies to addok-cluster 0.11.0 and addok-geocode-stream 0.27.0
lib/search.js	Added parseFilterValues() utility to parse, split, and deduplicate filter values; updated formatParams() to return arrays
lib/csv.js	Replaced hardcoded filter parameters with dynamic filters object based on ADDOK_FILTERS
lib/batch.js	Added normalizeFilters() function to process filters from both global and per-request params
test/search.js	Added comprehensive tests for parseFilterValues() and multi-value filter scenarios
test/batch.js	Added tests for batch endpoint with various filter configurations
README.md	Updated documentation with multi-value filter syntax examples and CSV filter clarification

---

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