Skip to content

Commit d73c0e4

Browse files
mcabreradevstacksharebotgithub-actions[bot]
authored
feat: add Geospatial, DateTime operators, update MongoDB Operators, Playground Enhancements and Testing (#56)
* feat: introduce array OR syntax for filter expressions * feat: add visual debugging capabilities with filterDebug * feat: enhance filter functionality with new guides and options * feat: add re-check step to CI workflow for improved validation * chore: add interactive playground documentation * feat: add Node.js integration documentation for data filtering and backend processing * 5.5.3 * refactor: add checks to publish scripts for improved reliability * refactor: enhance pre-push script with additional verification step * refactor: add type tests to pre-push checks for improved validation * Create techstack.yml * Create techstack.md * chore: bump version to 5.5.0 [skip ci] * fix: update branch references from 'prod' and 'main' to 'master' in workflows * chore: bump package version * 5.5.1 * fix: update vercel configuration for deployment and security headers * Update npm-publish-manual.yml * feat: add Vercel Analytics integration and update test expectations for filter results * chore: remove vercel configuration file * feat: add composables for code analysis, editor, debounce, and filter builder - Implemented `useCodeAnalysis` for extracting fields and suggesting operators based on code input. - Created `useCodeEditor` for handling code highlighting and execution with mock console support. - Added `useDebouncedExecute` for debouncing function calls. - Developed `useEditorResize` for auto-resizing text areas and synchronizing scroll. - Introduced `useFilterBuilder` for managing filter rules and generating MongoDB-style expressions. - Added sample datasets and examples for demonstration purposes. * Delete outdated documentation files and features related to backend and nested object support; streamline frontend framework integration guide for @mcabreradev/filter with improved examples and performance optimizations. * chore: update changelog for v5.5.1 release; document new features, fixes, and performance improvements * chore: update roadmap for v5.5.1 release; reflect recent changes and improvements in features, stability, and performance * 5.5.2 * refactor: update type expectations in tests to use correct array types instead of ChainableArray * 5.5.3 * refactor: add checks to publish scripts for improved reliability * refactor: enhance pre-push script with additional verification step * refactor: add type tests to pre-push checks for improved validation * docs: add CLAUDE.md for project guidance and development commands * feat: add initial settings.local.json for permission configuration * feat: add Query Builder API proposal for improved query syntax and type safety * feat: add geospatial operators for location-based filtering - Introduced three new geospatial operators: $near, $geoBox, and $geoPolygon. - Implemented distance calculation using spherical law of cosines. - Added coordinate validation utilities for geospatial queries. - Enhanced documentation with examples for new operators. - Updated changelog to reflect new features and improvements. - Added comprehensive tests for geospatial functionalities. - Extend operator options to include object type and additional operators * feat: add comprehensive tests for geospatial operators and distance calculations * feat: update permissions in settings.local.json and enhance geospatial tests with utility functions * test: add comprehensive unit tests for geospatial edge cases - Add tests for evaluateNear handling points across date line - Add tests for evaluateGeoBox with full longitude range boxes - Add tests for evaluateGeoPolygon with star-shaped polygons - Add tests for filter with $near operator using minDistanceMeters - Add tests for filter with $geoPolygon for complex polygon shapes - All 98 geospatial tests passing * fix: remove non-null assertion to satisfy linter * refactor: streamline CI workflow by removing redundant type check, lint, and test steps * feat(datetime): add datetime operators and utilities - Implemented $recent, $upcoming, $dayOfWeek, $timeOfDay, $age, $isWeekday, $isWeekend, $isBefore, and $isAfter operators. - Created utility functions for validating dates, time ranges, day of the week, relative time, and age queries. - Added tests for all new operators and utilities to ensure correct functionality. - Integrated datetime operators into the operator processor and updated types accordingly. * feat: add International Date Line handling and JSDoc documentation - Add date line crossing support for evaluateGeoBox - Fix minDistanceMeters check to handle 0 explicitly with !== undefined - Add comprehensive JSDoc comments to all geospatial operators - Add 3 new tests for date line crossing boxes (101 tests total) - Document limitation for polygon date line crossing - All tests passing with improved edge case coverage * feat: add International Date Line handling for geospatial operators - Add date line crossing support in evaluateGeoBox - Fix minDistanceMeters check to handle 0 explicitly (use !== undefined) - Add 3 new comprehensive tests for date line crossing scenarios - All 101 tests passing * feat: enhance datetime filtering with new operators and examples * chore: update vitest configuration for improved test coverage and add separate config for documentation tests - Modified `vitest.config.ts` to include tests from the documentation theme and adjusted coverage settings. - Added a new `vitest.docs.config.ts` file for running tests in the documentation environment using jsdom. * feat: add cleanup function to useDebouncedExecute and useEditorResize for better resource management * fix: remove duplicate imports in Playground.vue * fix: correct media query styles for horizontal layout in Playground.vue --------- Co-authored-by: stacksharebot <team@stackshare.io> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
1 parent 3c31de3 commit d73c0e4

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

50 files changed

+10323
-252
lines changed

‎.claude/settings.local.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"WebSearch",
5+
"Bash(pnpm test:*)"
6+
],
7+
"deny": [],
8+
"ask": []
9+
}
10+
}

‎.github/workflows/npm-publish-manual.yml‎

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -50,14 +50,8 @@ jobs:
5050
pnpm install --no-frozen-lockfile
5151
fi
5252
53-
- name: 🔍 Type check
54-
run: pnpm run typecheck
55-
56-
- name: 🧹 Lint
57-
run: pnpm run lint
58-
59-
- name: 🃏 Run tests
60-
run: pnpm run test
53+
- name: 🔍 Running Check/Test Suite
54+
run: pnpm run check
6155

6256
- name: 🏗️ Build
6357
run: pnpm run build

‎.husky/pre-push‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,17 @@ echo "🧪 Running pre-push checks..."
33
echo "🧪 Running tests..."
44
pnpm run test
55

6+
echo "🧪 Running type tests..."
7+
pnpm run test:types
8+
69
echo "📝 Type checking..."
710
pnpm run typecheck
811

912
echo "🔍 Linting all files..."
1013
pnpm run lint
1114

15+
echo "✅ All checks passed! Verifying final conditions..."
16+
pnpm run check
17+
1218
echo "✅ Pre-push checks passed! Ready to push."
1319

‎CLAUDE.md‎

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
**@mcabreradev/filter** is a TypeScript-first filtering engine for arrays with SQL-like wildcards, MongoDB-style operators, lazy evaluation, memoization, and framework integrations (React, Vue, Svelte). It provides 18+ operators for advanced filtering with zero dependencies (except Zod for validation).
8+
9+
## Development Commands
10+
11+
### Core Development
12+
```bash
13+
# Install dependencies
14+
pnpm install
15+
16+
# Build project (outputs to build/)
17+
pnpm build
18+
19+
# Type checking
20+
pnpm typecheck
21+
```
22+
23+
### Testing
24+
```bash
25+
# Run all unit tests
26+
pnpm test
27+
28+
# Run tests in watch mode
29+
pnpm test:watch
30+
31+
# Run tests with UI
32+
pnpm test:ui
33+
34+
# Generate coverage report
35+
pnpm test:coverage
36+
37+
# Run TypeScript type tests (tsd)
38+
pnpm test:types
39+
40+
# Run all checks (lint, typecheck, type tests, test)
41+
pnpm run check
42+
```
43+
44+
### Linting & Formatting
45+
```bash
46+
# Lint code
47+
pnpm lint
48+
49+
# Fix linting issues
50+
pnpm lint:fix
51+
52+
# Format code with Prettier
53+
pnpm format
54+
```
55+
56+
### Publishing
57+
```bash
58+
# Publish major version (runs check, version bump, publish)
59+
pnpm run publish:major
60+
61+
# Publish minor version
62+
pnpm run publish:minor
63+
64+
# Publish patch version
65+
pnpm run publish:patch
66+
67+
# Release (push tags to remote)
68+
pnpm run release
69+
70+
# Full release workflow (publish + push tags)
71+
pnpm run release:major
72+
pnpm run release:minor
73+
pnpm run release:patch
74+
```
75+
76+
### Documentation
77+
```bash
78+
# Start docs dev server (http://localhost:5173/)
79+
pnpm run docs:dev
80+
81+
# Build documentation
82+
pnpm run docs:build
83+
84+
# Preview built docs
85+
pnpm run docs:preview
86+
87+
# Generate API documentation
88+
pnpm run docs:api
89+
```
90+
91+
## Code Architecture
92+
93+
### Module Structure
94+
- **`src/index.ts`** - Main entry point that re-exports all public APIs
95+
- **`src/core/`** - Core filtering logic
96+
- `filter.ts` - Main filter function with caching and debug support
97+
- `filter-lazy.ts` - Lazy evaluation with generators for large datasets
98+
- **`src/operators/`** - MongoDB-style operator implementations
99+
- `comparison.operators.ts` - $gt, $gte, $lt, $lte, $eq, $ne
100+
- `array.operators.ts` - $in, $nin, $contains, $size
101+
- `string.operators.ts` - $startsWith, $endsWith, $contains, $regex, $match
102+
- `logical.operators.ts` - $and, $or, $not
103+
- `operator-processor.ts` - Processes operator-based expressions
104+
- **`src/predicate/`** - Predicate function builders
105+
- `predicate-factory.ts` - Creates appropriate predicate based on expression type
106+
- `string-predicate.ts` - Handles wildcards (%, _), negation (!)
107+
- `object-predicate.ts` - Handles object-based filtering
108+
- `function-predicate.ts` - Handles custom predicate functions
109+
- **`src/comparison/`** - Deep comparison logic
110+
- `deep-compare.ts` - Recursive deep equality for nested objects
111+
- `object-compare.ts` - Object comparison with maxDepth support
112+
- `property-compare.ts` - Property-level comparison with wildcards
113+
- **`src/config/`** - Configuration management
114+
- `default-config.ts` - Default configuration values
115+
- `config-builder.ts` - Merges user options with defaults
116+
- **`src/validation/`** - Runtime validation with Zod
117+
- `schemas.ts` - Zod schemas for expressions and options
118+
- `validator.ts` - Validates expressions and options at runtime
119+
- **`src/debug/`** - Debug mode with tree visualization
120+
- `debug-filter.ts` - Debug-enabled filter with statistics
121+
- `debug-tree-builder.ts` - Builds expression tree for visualization
122+
- `debug-formatter.ts` - Formats debug output with colors
123+
- `debug-evaluator.ts` - Tracks condition evaluations
124+
- **`src/utils/`** - Utility functions
125+
- `cache.ts` - Result caching with WeakMap
126+
- `memoization.ts` - Predicate and regex memoization
127+
- `lazy-iterators.ts` - Generator utilities (take, skip, map, etc.)
128+
- `pattern-matching.ts` - SQL wildcard matching (%, _)
129+
- `type-guards.ts` - TypeScript type guards
130+
- **`src/integrations/`** - Framework integrations
131+
- `react/` - React hooks (useFilter, useDebouncedFilter, etc.)
132+
- `vue/` - Vue composables with reactivity
133+
- `svelte/` - Svelte stores
134+
- `shared/` - Shared utilities (debounce, pagination)
135+
- **`src/types/`** - TypeScript type definitions
136+
- `expression.types.ts` - Expression and operator types
137+
- `config.types.ts` - Configuration types
138+
- `operators.types.ts` - Operator-specific types
139+
- `lazy.types.ts` - Lazy evaluation types
140+
141+
### Key Design Patterns
142+
143+
**Predicate Factory Pattern**: The `predicate-factory.ts` determines the appropriate predicate builder based on expression type (string, object, function, or primitive).
144+
145+
**Operator Processing**: Operators are processed in `operator-processor.ts`, which detects operator-based expressions and delegates to specific operator implementations.
146+
147+
**Multi-Layer Caching**: Three-tier caching strategy:
148+
1. Result cache - Complete filter results (WeakMap-based)
149+
2. Predicate cache - Compiled predicate functions
150+
3. Regex cache - Compiled regex patterns
151+
152+
**Lazy Evaluation**: Generator-based filtering in `filter-lazy.ts` enables early exit and memory-efficient processing of large datasets.
153+
154+
**Debug Tree**: Debug mode builds an expression tree showing condition evaluations, match counts, and execution timings.
155+
156+
## Test Organization
157+
158+
- **`src/**/*.test.ts`** - Unit tests co-located with source files
159+
- **`__test__/filter.test.ts`** - Integration tests for main filter function
160+
- **`__test__/test-d/`** - TypeScript type tests using tsd
161+
- **`__test__/memoization-integration.test.ts`** - Caching integration tests
162+
163+
Tests use Vitest and must achieve comprehensive coverage.
164+
165+
## Git Hooks
166+
167+
### pre-commit
168+
Runs automatically on commit:
169+
1. lint-staged (eslint + prettier on staged files)
170+
2. Type checking
171+
172+
### pre-push
173+
Runs automatically on push:
174+
1. All unit tests
175+
2. Type tests (tsd)
176+
3. Type checking
177+
4. Linting all files
178+
5. Full check command
179+
180+
## Branch Strategy
181+
182+
- **Main branch**: `dev`
183+
- **Feature branches**: Use prefixes `feat/`, `fix/`, `docs/`, `refactor/`, `test/`, `chore/`
184+
185+
## Development Guidelines
186+
187+
### TypeScript
188+
- All source code must be TypeScript (no `.js` in `src/`)
189+
- Strict mode enabled - all compiler options are strict
190+
- Target: ES2022 with ESM modules
191+
- Tests excluded from build output
192+
193+
### Code Style
194+
- Functional programming preferred - pure functions, avoid side effects
195+
- Modular design - small, focused modules with single responsibility
196+
- Export from `index.ts` barrels for clean imports
197+
- Dont add jsdoc and comments
198+
199+
### Operator Extensibility
200+
To add new operators:
201+
1. Create implementation in appropriate `src/operators/*.operators.ts` file
202+
2. Add type definitions to `src/types/operators.types.ts`
203+
3. Update operator detection in `src/utils/operator-detection.ts`
204+
4. Add comprehensive tests
205+
206+
### Configuration
207+
- All config options defined in `src/config/default-config.ts`
208+
- Options: caseSensitive, maxDepth, enableCache, debug, verbose, showTimings, colorize, customComparator
209+
- Merge user options via `mergeConfig()` in `config-builder.ts`
210+
211+
### Framework Integrations
212+
Framework-specific code lives in `src/integrations/<framework>/`:
213+
- React uses hooks pattern
214+
- Vue uses Composition API
215+
- Svelte uses stores
216+
- Shared utilities in `src/integrations/shared/`
217+
- All optional peer dependencies
218+
219+
## Publishing Workflow
220+
221+
The project uses semantic versioning:
222+
1. Run `pnpm run publish:[major|minor|patch]` - runs all checks, bumps version, publishes to npm
223+
2. Run `pnpm run release` to push git tags
224+
3. Or use combined commands: `pnpm run release:[major|minor|patch]`
225+
226+
Pre-publish checks ensure:
227+
- All tests pass
228+
- Type tests pass
229+
- Type checking succeeds
230+
- Linting passes
231+
- No uncommitted changes
232+
233+
## Key Files
234+
235+
- **`package.json`** - Main: `build/index.js`, Types: `build/index.d.ts`
236+
- **`tsconfig.json`** - TypeScript config with strict mode
237+
- **`.husky/`** - Git hooks configuration
238+
- **`docs/`** - VitePress documentation site
239+
- **`examples/`** - Usage examples referenced in docs

0 commit comments

Comments
 (0)