Added fast closure

Closure interface approach can filter faster than raw Perl.
Docs updated

Author: bwva

Changes

@@ -1,5 +1,39 @@
 Revision history for Params-Filter
 
+v0.011  2026-01-26 (STABLE RELEASE)
+    - NEW: Added closure interface with make_filter() function for maximum performance
+    - make_filter() creates optimized, reusable closures that can be 20-25% faster than
+      hand-written Perl filtering code due to pre-computed exclusion lookups and
+      specialized closure variants
+    - Three specialized closure variants:
+      * Required-only (empty accepted list) - 3.1M ops/sec
+      * Wildcard (accepted contains '*') - 1.3M ops/sec, 24% faster than raw Perl
+      * Accepted-specific (normal case) - 1.8M ops/sec, 20% faster than raw Perl
+    - OPTIMIZED: filter() function now uses same optimizations as closure interface:
+      * Pre-computed exclusion hash (O(1) lookups instead of O(n) array search)
+      * Hash slice for required field copying (faster bulk operations)
+      * Non-destructive operations with hash lookups instead of delete
+      * Single wildcard check instead of per-iteration checks
+    - All interfaces (functional, OO, closure) now use identical optimization techniques
+    - Closure interface is 142-239% faster than functional interface due to:
+      * No input parsing overhead (hashref-only input)
+      * No error message construction overhead
+      * Pre-compiled closures optimized for specific configuration
+    - Added comprehensive test suite for make_filter() (t/04-make_filter.t with 10 subtests)
+    - Added complete POD documentation for closure interface
+    - Added usage examples (examples/closure_interface.pl with 6 working examples)
+    - Added benchmark scripts:
+      * benchmark-three-variants.pl - Performance comparison of three closure types
+      * benchmark-optimized-filter.pl - Optimized filter() vs make_filter() comparison
+      * benchmark-make_filter.pl - Closure vs raw Perl performance
+    - Updated README.md with closure interface documentation and performance notes
+    - Updated performance considerations to clarify that closure interface provides
+      maximum speed while functional/OO have feature overhead
+    - Changed "database queries" to "database statements" for accuracy (includes inserts/updates)
+    - All 73 tests passing across 6 test files
+    - POD syntax validated
+    - Full backward compatibility maintained
+
 v0.010  2026-01-25 (STABLE RELEASE)
     - Updated documentation to emphasize security, compliance, and correctness
       over raw performance

MANIFEST

@@ -15,6 +15,16 @@ examples/realistic-benchmark.pl
 examples/strict_construction.pl
 examples/test-fastpath.pl
 examples/wildcard.pl
+examples/closure_interface.pl
+examples/benchmark-all-interfaces.pl
+examples/benchmark-make_filter.pl
+examples/benchmark-vs-raw.pl
+examples/CALL_CHAIN_ANALYSIS.md
+examples/CALL_CHAIN_VISUALIZATION.txt
+benchmark-make_filter.pl
+benchmark-optimized-filter.pl
+benchmark-three-variants.pl
+test-make_filter.pl
 lib/Params/Filter.pm
 Makefile.PL
 MANIFEST
@@ -25,3 +35,5 @@ t/00-load.t
 t/01-functional.t
 t/02-oo-interface.t
 t/03-modifier-methods.t
+t/04-make_filter.t
+t/benchmark.t

README.md

@@ -16,20 +16,20 @@ This module separates field filtering from value validation:
 The main advantages of using Params::Filter are:
 
 - **Consistency** - Converts varying incoming data formats to consistent key-value pairs
-- **Security** - Sensitive fields (passwords, SSNs, credit cards) never reach your validation code or database queries
+- **Security** - Sensitive fields (passwords, SSNs, credit cards) never reach your validation code or database statements
 - **Compliance** - Automatically excludes fields that shouldn't be processed or stored (e.g., GDPR, PCI-DSS)
 - **Correctness** - Ensures only expected fields are processed, preventing accidental data leakage or processing errors
 - **Maintainability** - Clear separation between data filtering (what fields to accept) and validation (whether values are correct)
 
 ### Performance Considerations
 
-**Important**: In many cases, Params::Filter is slower than manual hash lookups or similar operations, especially when the incoming data is in a known consistent format. The value of Params::Filter is in its capability to assure the security, compliance, and correctness benefits listed above.
+**Important**: The functional and OO interfaces include features that add overhead compared to manual hash lookups, especially when the incoming data is in a known consistent format. The value of Params::Filter is in its capability to assure the security, compliance, and correctness benefits listed above.
 
-Nonetheless, Params::Filter CAN improve overall performance when downstream validation is expensive (database queries, API calls, complex regex).
+However, the **Closure Interface** (`make_filter`) provides maximum performance and can be faster than hand-written Perl filtering code due to pre-computed exclusion lookups and specialized closure variants. Use `make_filter` for hot code paths or high-frequency filtering.
 
-A simple benchmark comparing the validation cost of typical input to that of input restricted to required fields would reveal any speed gain with expensive downstream validations.
+For all interfaces, Params::Filter CAN improve overall performance when downstream validation is expensive (database statements, API calls, complex regex) by failing fast when required fields are missing.
 
-For simple cases and when validation is cheap, raw speed is not the reason to use Params::Filter.
+A simple benchmark comparing the validation cost of typical input to that of input restricted to required fields would reveal any speed gain with expensive downstream validations.
 
 ### Common Use Cases
 
@@ -87,7 +87,7 @@ This module provides important security benefits by separating data filtering fr
 
 #### Preventing Sensitive Data Leakage
 
-By excluding sensitive fields early in the request processing pipeline, you ensure they never reach validation code, database queries, or logging systems:
+By excluding sensitive fields early in the request processing pipeline, you ensure they never reach validation code, database statements, or logging systems:
 
 ```perl
 my $user_filter = Params::Filter->new_filter({
@@ -210,10 +210,48 @@ my ($user2, $msg2) = $user_filter->apply($api_request_data);
 my ($user3, $msg3) = $user_filter->apply($db_record_data);
 ```
 
+### Closure Interface (Maximum Speed)
+
+```perl
+use Params::Filter qw/make_filter/;
+
+# Create a reusable filter closure
+my $fast_filter = make_filter(
+    [qw(id username)],      # required
+    [qw(email bio)],        # accepted
+    [qw(password token)],   # excluded
+);
+
+# Apply to high-volume data stream
+for my $record (@large_dataset) {
+    my $filtered = $fast_filter->($record);
+    next unless $filtered;  # Skip if required fields missing
+    process($filtered);
+}
+
+# Wildcard example - accept everything except sensitive fields
+my $safe_filter = make_filter(
+    [qw(id type)],
+    ['*'],                      # accept all other fields
+    [qw(password token ssn)],   # but exclude these
+);
+
+# Safe logging - sensitive fields automatically excluded
+my $log_entry = $safe_filter->($incoming_data);
+log_to_file($log_entry);  # Passwords, tokens, SSNs never logged
+```
+
+The closure interface provides maximum performance for hot code paths and high-frequency filtering operations. It only accepts data in the form of a hashref. It creates a specialized, optimized closure based on your configuration:
+
+- **Required-only** - When accepted list is empty, returns only required fields
+- **Wildcard** - When accepted contains `'*'`, accepts all input fields except exclusions
+- **Accepted-specific** - When accepted has specific fields, returns required plus those accepted fields (minus exclusions)
+
 ## Features
 
-- **Dual interface**: Functional or OO usage
+- **Three interfaces**: Functional, OO, or Closure (for maximum speed)
 - **Security-first**: Excludes sensitive fields before they reach validation code
+- **Performance**: Closure interface can be faster than hand-written Perl filtering
 - **Fail-closed**: Returns immediately on missing required parameters
 - **Early validation**: Returns immediately if all required parameters are provided and no others are provided or will be accepted
 - **Non-destructive**: Allows multiple filters and conditional use without affecting data
@@ -796,6 +834,7 @@ NOTE: The original `$data` is not modified during filtering, so the same data ca
 See the `examples/` directory for complete working scripts:
 - `basic_usage.pl` - Simple form input filtering
 - `oo_interface.pl` - Reusable filters
+- `closure_interface.pl` - High-performance closure interface
 - `wildcard.pl` - Wildcard acceptance patterns
 - `error_handling.pl` - Various error handling strategies
 - `debug_mode.pl` - Development-time warnings

benchmark-optimized-filter.pl

@@ -0,0 +1,189 @@
+#!/usr/bin/env perl
+use v5.40;
+use strict;
+use warnings;
+use Benchmark qw(:all);
+
+use Params::Filter qw/filter make_filter/;
+
+say "=" x 80;
+say "Benchmark: Optimized filter() vs make_filter() Closure";
+say "=" x 80;
+say "";
+say "Testing if optimized functional approach matches closure performance";
+say "";
+
+# Test data
+my $test_data = {
+    id => 123,
+    name => 'Alice',
+    email => '[email protected]',
+    phone => '555-1234',
+    city => 'NYC',
+    password => 'secret',
+    extra => 'ignored',
+};
+
+# ============================================================================
+# Scenario 1: Required-only (no accepted fields)
+# ============================================================================
+say "=" x 80;
+say "SCENARIO 1: Required-only (no accepted fields)";
+say "=" x 80;
+say "Config: required=['id','name','email'], accepted=[], excluded=[]";
+say "";
+
+my @req1 = qw/id name email/;
+my @ok1 = ();
+my @no1 = ();
+
+my $closure1 = make_filter(\@req1, \@ok1, \@no1);
+
+cmpthese(-5, {
+    'filter() functional' => sub {
+        my $result = filter($test_data, \@req1, \@ok1, \@no1);
+    },
+    'make_filter() closure' => sub {
+        my $result = $closure1->($test_data);
+    },
+});
+
+say "";
+
+# ============================================================================
+# Scenario 2: Wildcard (accept all except exclusions)
+# ============================================================================
+say "=" x 80;
+say "SCENARIO 2: Wildcard (accept all except exclusions)";
+say "=" x 80;
+say "Config: required=['id','name'], accepted=['*'], excluded=['password']";
+say "";
+
+my @req2 = qw/id name/;
+my @ok2 = ('*');
+my @no2 = qw/password extra/;
+
+my $closure2 = make_filter(\@req2, \@ok2, \@no2);
+
+cmpthese(-5, {
+    'filter() functional' => sub {
+        my $result = filter($test_data, \@req2, \@ok2, \@no2);
+    },
+    'make_filter() closure' => sub {
+        my $result = $closure2->($test_data);
+    },
+});
+
+say "";
+
+# ============================================================================
+# Scenario 3: Accepted-specific (normal case)
+# ============================================================================
+say "=" x 80;
+say "SCENARIO 3: Accepted-specific (normal case)";
+say "=" x 80;
+say "Config: required=['id','name','email'], accepted=['phone','city'], excluded=['password']";
+say "";
+
+my @req3 = qw/id name email/;
+my @ok3 = qw/phone city/;
+my @no3 = qw/password/;
+
+my $closure3 = make_filter(\@req3, \@ok3, \@no3);
+
+cmpthese(-5, {
+    'filter() functional' => sub {
+        my $result = filter($test_data, \@req3, \@ok3, \@no3);
+    },
+    'make_filter() closure' => sub {
+        my $result = $closure3->($test_data);
+    },
+});
+
+say "";
+
+# ============================================================================
+# Scenario 4: Multiple filters (simulating high-volume processing)
+# ============================================================================
+say "=" x 80;
+say "SCENARIO 4: High-volume processing (100K operations)";
+say "=" x 80;
+say "Applying 3 different filters to same data";
+say "";
+
+cmpthese(-5, {
+    'filter() functional' => sub {
+        my $r1 = filter($test_data, \@req1, \@ok1, \@no1);
+        my $r2 = filter($test_data, \@req2, \@ok2, \@no2);
+        my $r3 = filter($test_data, \@req3, \@ok3, \@no3);
+    },
+    'make_filter() closure' => sub {
+        my $r1 = $closure1->($test_data);
+        my $r2 = $closure2->($test_data);
+        my $r3 = $closure3->($test_data);
+    },
+});
+
+say "";
+
+# ============================================================================
+# Correctness verification
+# ============================================================================
+say "=" x 80;
+say "CORRECTNESS VERIFICATION";
+say "=" x 80;
+say "";
+
+my $f1 = filter($test_data, \@req1, \@ok1, \@no1);
+my $c1 = $closure1->($test_data);
+
+say "Scenario 1 (required-only):";
+say "  filter():    ", join(", ", sort keys %$f1);
+say "  make_filter(): ", join(", ", sort keys %$c1);
+say "  Match: ", (join(" ", sort keys %$f1) eq join(" ", sort keys %$c1) ? "✅" : "❌");
+say "";
+
+my $f2 = filter($test_data, \@req2, \@ok2, \@no2);
+my $c2 = $closure2->($test_data);
+
+say "Scenario 2 (wildcard):";
+say "  filter():    ", join(", ", sort keys %$f2);
+say "  make_filter(): ", join(", ", sort keys %$c2);
+say "  Match: ", (join(" ", sort keys %$f2) eq join(" ", sort keys %$c2) ? "✅" : "❌");
+say "";
+
+my $f3 = filter($test_data, \@req3, \@ok3, \@no3);
+my $c3 = $closure3->($test_data);
+
+say "Scenario 3 (accepted-specific):";
+say "  filter():    ", join(", ", sort keys %$f3);
+say "  make_filter(): ", join(", ", sort keys %$c3);
+say "  Match: ", (join(" ", sort keys %$f3) eq join(" ", sort keys %$c3) ? "✅" : "❌");
+say "";
+
+say "=" x 80;
+say "ANALYSIS";
+say "=" x 80;
+say "";
+say "Key insights:";
+say "  • Both interfaces now use identical optimization techniques";
+say "  • Pre-computed exclusion hash (O(1) lookups)";
+say "  • Hash slice for required field copying";
+say "  • Non-destructive operations";
+say "  • Single wildcard check";
+say "";
+say "Performance differences expected:";
+say "  • filter() has overhead for input parsing";
+say "  • filter() builds error messages each call";
+say "  • make_filter() closures are pre-compiled";
+say "";
+say "Use filter() when you need:";
+say "  - Input format flexibility (hashref, arrayref, scalar)";
+say "  - Detailed error messages";
+say "  - One-time filtering operations";
+say "";
+say "Use make_filter() when you need:";
+say "  - Maximum performance";
+say "  - Reusable filters";
+say "  - High-frequency filtering (hot code paths)";
+say "";