How dinhplus/typed-query-filter works
Project type and purpose
• This is an open-source TypeScript library (NPM package) called typed-query-filter.
• It provides a MongoDB-like, type-safe query engine for in-memory JS/TS arrays.
• It runs in both Node.js and browsers (with a planned WASM backend).
File structure
• Top-level:
• package.json / tsconfig.json / vitest.config.ts / README.md / LICENSE
• CI/CD configs in .github/workflows
• Husky / commitlint for pre-commit checks
• Core library under src:
• filterData.ts – main function export
• QueryBuilder.ts – chainable API
• core/ – compiler, fieldMatcher, getNestedValue, flatKey utilities
• types.ts – shared type definitions
• Entry point index.ts re-exports API
• Playground for manual experimentation (playground/index.ts + /data + /examples)
• Tests under src/__tests__ using Vitest
README for additional insights
• Describes API surfaces: filterData, QueryBuilder, projection, operators
• Details supported operators, nested queries, projection modes
• Mentions upcoming WASM backend
• Usage scenarios: frontend grid filtering, backend data processing, form builder integration
Main components
• API Layer
• filterData function
• QueryBuilder class
• Core Engine
• Compiler (parses query into predicate AST)
• FieldMatcher (maps operator to matching logic)
• getNestedValue (retrieves value by “a.b[0].c”)
• FlatKey helper (builds field-path autocomplete)
• Data Flow
• Input: arbitrary array of objects (User[])
• Query definition (object literal or builder chain)
• Query parsing → predicate generation
• Iteration over array → apply predicate → filtered subset
• Sorting / limiting
• Projection (three modes: field list, callback, template)
• Output: transformed array
• Environments
• Node.js runtime
• Browser runtime
• (Future) WASM backend
• Tooling & CI
• Vitest test runner
• GitHub Actions (test, lint, release, publish)
• Husky + commitlint
Relationships and interactions
• User code calls filterData or instantiates QueryBuilder
→ API Layer
→ Core Engine processes the query
→ Data Flow transforms input to output
• Core Engine utilities are loosely coupled:
• Compiler uses fieldMatcher & getNestedValue
• Projection logic uses FlatKey
• Playground imports the published library for manual demos
• CI/CD pipelines run tests & publish to NPM
Architectural patterns and design principles
• Modular separation: API layer vs. compiler vs. utilities
• Functional pipeline: parse → predicate → filter → sort/limit → project
• Type-safe generics for end-to-end TS support
• Single-responsibility modules (each file has one purpose)
• Extensible operator registry (operator implementations decoupled)
Detailed capture of architectural elements
• How core utilities plug into both filterData and QueryBuilder
• Optional WASM module hook replacing CPU-based filter