SCIM Query Filter & Sorter Parser

Common errors

• SyntaxError: Unexpected token 'export'

  cause Attempting to `require()` an ES Module (ESM) package in a strict CommonJS environment without proper transpilation or configuration, or when a tool incorrectly picks the ESM bundle for `require`.
  fix Use `import { symbol } from 'package';` instead of `const { symbol } = require('package');` in modern JavaScript or TypeScript environments. Ensure your `package.json` has `"type": "module"` if your files are ESM, or configure your bundler (e.g., Webpack, Rollup) to correctly handle dual packages.

• TypeError: compileFilter is not a function

  cause This typically occurs if the import path is incorrect, or if `require` is used and the package's CommonJS export structure is not directly compatible with destructuring the top-level `module.exports` object.
  fix Verify the exact import statement: `import { compileFilter } from 'scim-query-filter-parser';`. If using `require`, ensure it's `const { compileFilter } = require('scim-query-filter-parser');` and not `const compileFilter = require('scim-query-filter-parser');`.

• Error: Invalid SCIM filter string: '...' (details about parsing error)

  cause The input string provided to `compileFilter` or `compileSorter` does not conform to the SCIM Protocol RFC 7644 specification for filter or sort expressions.
  fix Carefully review the provided filter or sort string against RFC 7644 section 3.4.2.2 and 3.4.2.3. Common mistakes include mismatched quotes, incorrect logical operators (e.g., `and` vs `&&`), invalid attribute names, or improper use of comparison operators.

Warnings

• breaking Version 2.0.0 introduced ES Module (ESM) support. While the package maintains CommonJS compatibility via its `main` entry point, projects relying solely on CommonJS or specific bundler configurations might need adjustments, especially if `package.json`'s `exports` field is used by tooling.
  Fix: Prefer `import` statements for consuming the library. If using CommonJS, ensure your bundler or Node.js environment correctly resolves the `main` entry point. Test existing `require` statements thoroughly after upgrading.
• gotcha The parser strictly adheres to the SCIM Protocol RFC 7644 for filter and sort expressions. Malformed or non-compliant query strings will lead to runtime errors when `compileFilter` or `compileSorter` are called.
  Fix: Validate SCIM query strings before passing them to the compiler functions. Refer to RFC 7644, sections 3.4.2.2 (filtering) and 3.4.2.3 (sorting) for correct syntax. Implement robust error handling around calls to `compileFilter` and `compileSorter`.
• gotcha Performance considerations: While efficient for typical use cases, compiling very complex filters or executing them against extremely large datasets in a hot path might introduce overhead. The compiled functions are pure, so reuse the compiled function if the filter string doesn't change.
  Fix: Cache the results of `compileFilter` and `compileSorter` if the filter or sort string is static or frequently reused. Avoid recompiling the same string multiple times within a tight loop. For extremely high-performance scenarios with huge datasets, consider pre-filtering or indexing strategies.

Install

• npm install scim-query-filter-parser npm
• yarn add scim-query-filter-parser yarn
• pnpm add scim-query-filter-parser pnpm

Imports

• compileFilter
  wrong:

  const compileFilter = require('scim-query-filter-parser').compileFilter;

  correct:

  import { compileFilter } from 'scim-query-filter-parser';

  ESM import is recommended, especially when using TypeScript. While CommonJS `require` might work due to dual package builds, it is not the idiomatic way to consume this library in modern environments.
• compileSorter
  wrong:

  const compileSorter = require('scim-query-filter-parser').compileSorter;

  correct:

  import { compileSorter } from 'scim-query-filter-parser';

  ESM import is recommended. CommonJS `require` is technically supported but less preferred for new projects or TypeScript contexts.
• Type definitions

  import type { ScimFilterFunction, ScimSorterFunction } from 'scim-query-filter-parser';

  Importing types explicitly helps with static analysis and IntelliSense in TypeScript projects without adding runtime overhead.

Quickstart

Demonstrates how to import `compileFilter` and `compileSorter` and use them to filter and sort an array of objects based on SCIM query strings, including complex filters and extended attributes.

import { compileFilter, compileSorter } from "scim-query-filter-parser";

const users = [
  { id: 'u1', userName: 'alice', active: true, 'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber': 'EMP001' },
  { id: 'u2', userName: 'bob', active: false, 'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber': 'EMP002' },
  { id: 'u3', userName: 'charlie', active: true, 'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber': 'EMP003' }
];

// Example 1: Filtering users where userName equals 'alice'
const aliceFilter = compileFilter('userName eq "alice"');
const filteredUsers = users.filter(aliceFilter);
console.log('Filtered for Alice:', filteredUsers);

// Example 2: Filtering active users with an employee number greater than 'EMP001'
const complexFilter = compileFilter('active eq true and urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber gt "EMP001"');
const complexFilteredUsers = users.filter(complexFilter);
console.log('Complex filter results:', complexFilteredUsers);

// Example 3: Sorting users by userName in ascending order
const userNameSorter = compileSorter('userName asc');
const sortedUsers = [...users].sort(userNameSorter);
console.log('Sorted by Username:', sortedUsers);