Builder for Humaans API filter query parameters.

The Humaans API (a Feathers.js application) supports filtering list endpoints with operator suffixes like $in, $gt, etc. Hand-encoding these in keyword lists is awkward in Elixir because the keys contain characters that don't survive atom literals, e.g. ["status[$in]": ["active"]]. This module provides a small chainable builder so callers can express filters readably.

Field names and operator suffixes are stored as strings in the resulting params list. This avoids creating new atoms at runtime — important because atoms are not garbage-collected and untrusted or high-cardinality field names could otherwise exhaust the atom table. Req accepts string-keyed params transparently, so callers do not need to do anything different.

Example

query =
  Humaans.Query.new()
  |> Humaans.Query.eq(:companyId, "acme")
  |> Humaans.Query.in_(:status, ["active", "onboarding"])
  |> Humaans.Query.gte(:createdAt, "2025-01-01")
  |> Humaans.Query.to_params()

Humaans.People.list(client, query)

Supported operators

• eq/3 — exact match (no operator suffix)
• in_/3 — $in (any of)
• nin/3 — $nin (none of)
• gt/3 — $gt
• gte/3 — $gte
• lt/3 — $lt
• lte/3 — $lte

Field names are accepted as atoms or strings. The Humaans API uses camelCase field names (companyId, createdAt, etc.) — pass them as written. Operator-suffixed keys are produced for you.

Use merge/2 to combine a query with other params (e.g. pagination):

Humaans.Query.new()
|> Humaans.Query.in_(:status, ["active"])
|> Humaans.Query.merge("$limit": 50)
|> Humaans.Query.to_params()