https://github.com/gosuperscript/axiom-lookup
https://github.com/gosuperscript/axiom-lookup
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/gosuperscript/axiom-lookup
- Owner: gosuperscript
- Created: 2025-11-21T09:16:58.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-01-12T16:26:07.000Z (5 months ago)
- Last Synced: 2026-01-12T21:58:05.586Z (5 months ago)
- Language: PHP
- Size: 5.33 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Lookup Resolver
A high-performance PHP library for querying CSV/TSV files with streaming, dynamic filtering, aggregate functions, and range-based banding.
## Features
- **Memory-Efficient Streaming**: O(1) memory complexity - processes records one-at-a-time
- **Seven Aggregate Functions**: `first`, `last`, `min`, `max`, `count`, `sum`, `avg`, `all`
- **Explicit Filter API**: `ValueFilter` and `RangeFilter` for clear, self-documenting code
- **Range-Based Banding**: Support for scenarios like tax brackets, premium tiers, shipping rates
- **Dynamic Filter Resolution**: Use nested lookups and symbols as filter values
- **Strongly-Typed Value Objects**: Enhanced type safety with immutable aggregates
- **Early Exit Optimization**: `first` aggregate stops reading after first match (465x faster)
- **PHP 8.4 Compatible**: Full compatibility with latest PHP features
## Installation
```bash
composer require gosuperscript/axiom-lookup
```
## Quick Start
```php
use Superscript\Axiom\Lookup\{LookupSource, ValueFilter, StaticSource};
// Simple lookup
$lookup = new LookupSource(
filePath: '/data/products.csv',
filters: [new ValueFilter('category', new StaticSource('Electronics'))],
columns: 'price'
);
```
## Requirements
- PHP 8.4+
- league/csv ^9.27.0
- gosuperscript/monads
## Documentation
For detailed documentation, examples, and API reference, see the main README.md file.
## Testing
```bash
composer test # Run all tests
composer test:unit # Run unit tests
composer test:types # Run static analysis
composer test:infection # Run mutation tests
```
## Benchmarking
```bash
composer bench # Run all benchmarks
composer bench:aggregate # Test aggregate functions
composer bench:memory # Test memory efficiency
```
## Performance Characteristics
- **Memory**: ~6.86MB constant usage regardless of file size
- **Early Exit**: First aggregate is 465x faster than full scan
- **Scalability**: Linear time scaling with row count
- **Validated**: Comprehensive benchmarks with files up to 100k rows
## License
Proprietary
## Credits
Developed by GoSuperscript