Add preserveRelativeDates parse option

[rob-ghost]

Summary

Adds an opt-in preserveRelativeDates option to nql-lang.parse(). When enabled, relative-date expressions like now-7d are emitted as a tagged value rather than being resolved to an absolute SQL-formatted date at parse time:

parse('created_at:>=now-7d', {preserveRelativeDates: true});
// → {created_at: {$gte: {$relativeDate: {op: 'sub', amount: 7, unit: 'days'}}}}

Default behaviour is unchanged for callers that don't pass the option.

Why

UI clients that round-trip NQL strings through the parser currently lose the relative form (e.g. "in the last 7 days" becomes a fixed date the moment parse() runs). Consumers wanting to render the relative form have to detect it via string-level regex before calling the parser — duplicating the grammar's tokenisation work, and inevitably falling short for nested or compound expressions.

The grammar already recognises relative-date syntax as a distinct production rule (NOW DATEOP AMOUNT INTERVAL in nql.y); this PR just lets that recognition reach the AST when the caller asks for it. Server-side / SQL callers continue to get absolute dates.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0b1f4caf-efae-4810-bb4a-4bc6cea560f9

📥 Commits

Reviewing files that changed from the base of the PR and between 4b310a6 and 4d7f005.

📒 Files selected for processing (4)

• packages/nql-lang/lib/nql.js
• packages/nql-lang/lib/scope.js
• packages/nql-lang/test/parser.test.js
• packages/nql-lang/test/scope.test.js

---

Walkthrough

This pull request adds a preserveRelativeDates option to the NQL parser. When enabled, relative date expressions like now-7d are emitted as structured $relativeDate objects containing the operation, amount, and unit rather than being resolved to absolute SQL timestamps. The core logic in scope.js conditionally returns the tagged object format when the flag is set. The nql.js module wires the option through the public parse() API by toggling a scope flag before parsing and resetting it afterward to prevent state leakage. Test coverage validates the feature across simple and compound expressions, unit mappings, and isolation between parse calls.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Add preserveRelativeDates parse option' directly and clearly summarizes the main feature being introduced—a new optional parameter to the parse function.
Description check	✅ Passed	The description is well-organized, explains the feature, provides concrete examples, and articulates the motivation for the change—all clearly related to the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/preserve-relative-dates

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.69%. Comparing base (4b310a6) to head (4d7f005).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #141      +/-   ##
==========================================
+ Coverage   81.42%   81.69%   +0.26%     
==========================================
  Files           9        9              
  Lines        1701     1726      +25     
  Branches      339      342       +3     
==========================================
+ Hits         1385     1410      +25     
  Misses        311      311              
  Partials        5        5              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[kevinansfield]

As mentioned in the mob call, I think there's an argument for not needing the preserveRelativeDates option at all and having the parse output always fully encode the NQL string's intent in the AST, keeping any absolute date conversions on the AST->Output side.

However, change looks good and won't break anything so we can always look at simplifying the options later and do a major bump when publishing in case there are any consumers depending on the absolute dates after parsing 👍

[rob-ghost]

Thanks @kevinansfield, I checked for other users of the library and there's a good few leveraging the same entrypoint so it would be a breaking change for them to not resolve the relative dates by default.

It's true that filters is the only thing that uses the AST results, but its not the only thing that parses filters so we can't break compatibility, so adding the option is the best non-breaking change we can add today.