sgerrand / ex_humaans / 25323253278

99%

push

github

feat(query): add chainable filter query builder (#93)

* feat(query): add chainable filter query builder

Filtering Humaans list endpoints requires Feathers.js operator suffixes
like field[\$in]=value. Hand-encoding these in keyword lists is
awkward in Elixir because the keys contain characters that don't fit
standard atom literals. Most callers ended up reaching for raw atom
sigils.

Humaans.Query exposes a small chainable builder:

    Humaans.Query.new()
    |> Humaans.Query.in_(:status, ["active", "onboarding"])
    |> Humaans.Query.gte(:createdAt, "2025-01-01")
    |> Humaans.Query.to_params()
    |> then(&Humaans.People.list(client, &1))

Operators implemented: eq, in_, nin, gt, gte, lt, lte. \$or is
intentionally omitted in this first pass — the encoding is
finicky enough to warrant a dedicated follow-up if/when needed.

* test(humaans): cover query/0 accessor

* test(query): cover string field name in eq/3

* refactor(query): use string keys to avoid runtime atom creation

Building atoms from arbitrary field names via String.to_atom/1 risks
exhausting the atom table since atoms are not garbage-collected. Store
filter params as {string, value} tuples instead. Req accepts string-keyed
params unchanged, so callers don't need to do anything different.

* feat(query): validate merge/2 input is a proper keyword list

Previously merge/2 silently accepted any list, producing an invalid
params shape that could fail later in the HTTP layer. Validate with
Keyword.keyword?/1 and raise ArgumentError on invalid input, matching
the pattern in Humaans.validate_req_options/1.

* docs(humaans): list merge/2 in query/0 helper docs

The query/0 module helper docstring listed the operator builders and
to_params/1 but omitted merge/2, even though it is part of the public
Humaans.Query API and shown in the README.

19 of 19 new or added lines in 2 files covered. (100.0%)

192 of 192 relevant lines covered (100.0%)

19.72 hits per line