Add unit coverage for Neo.collection.Filter's operator matrix

New here? This issue is written to be finishable on a clean clone. You need Node, a fork and an evening. No Docker, no API key, no AI service. CONTRIBUTING.md now documents the whole setup loop — start there, and if any step does not work, say so in a comment. That is a bug in the docs, not in you.

Context

Neo.collection.Filter is how every filtered grid, list and store in Neo decides whether a record stays or goes. It supports sixteen operators, each implemented as a plain static function taking two values and returning a boolean.

Measured on 2026-09-19 at dev@afddc57634: no file under test/playwright/ imports src/collection/Filter.mjs. The class is exercised indirectly — five specs under test/playwright/unit/collection/ and several under unit/data/ set filters on a collection and assert the result — so this is not untested code. What is missing is different and narrower: nothing pins the operator matrix itself. No spec says what like does with a null, or what < does when one side is a Date.

That is the gap this issue closes. Please keep that distinction in your PR description; "Filter was untested" would be wrong.

The Problem

Sixteen operators, each a one- or few-line static, is exactly the shape where a well-meaning edit silently widens behaviour. Today an operator could start returning true for a case it used to reject and no test anywhere would notice — the indirect specs assert that filtering happened, not what the operator decided.

There is also a live inconsistency to pin, which you can verify before writing a line:

The class documents fifteen operators and ships sixteen. src/collection/Filter.mjs:18 lists them in prose:

['==','===','!=','!==','<','<=','>','>=','endsWith','excluded','included','isDefined','isUndefined','like','startsWith']

doesNotStartWith is absent from that list. The static operators array at :23 includes it, and static ['doesNotStartWith'] exists at :247. So the doc comment is stale. Do not fix it in this PR — see Out of Scope — but do let it tell you that this surface has drifted unobserved, which is the argument for pinning it.

The Architectural Reality

src/collection/Filter.mjs — class Neo.collection.Filter, extends Neo.core.Base.

• static operators (:23) — the sixteen valid values, enforced on the operator_ config through beforeSetOperator → beforeSetEnumValue (:146).
• Sixteen static functions (:238–:290), each keyed by the operator string: Filter['==='](a, b), Filter['like'](a, b), and so on. They are plain and pure — the easiest thing in this codebase to assert.
• isFiltered(item, filteredItems, allItems) (:186) — reads item[property], and returns !Filter[operator](recordValue, filterValue). Note the negation: isFiltered returning true means the item is filtered out. Read that line before you assert against it; getting it backwards is the obvious mistake and your test would still be green about the wrong thing.
• Date coercion (:214–:217) — when both the filter value and the record value are Date instances, both are converted with valueOf() first. Only when both are; a Date compared against a number does not take that path.

The Fix

Add test/playwright/unit/collection/FilterOperators.spec.mjs.

Copy the header shape from a sibling in the same directory, such as test/playwright/unit/collection/Base.spec.mjs — the setup() call comes before the other imports, which is how the Neo class system is initialised for the unit tier.

What to assert

• Every operator in static operators has a matching static function. Iterate the array rather than hand-listing it, so a future operator added without an implementation fails here. This one assertion is worth more than any individual case.
• A true case and a false case for each operator, with values written out literally. The interesting ones are not ===:
  • like — read :277 and pin what it actually does with case, and with a non-string.
  • included / excluded — which side is the collection, and what happens when it is empty.
  • isDefined / isUndefined — what they say about null as distinct from undefined.
  • doesNotStartWith — the undocumented one; pin it as it behaves.
• isFiltered returns the negation. One assertion where the operator matches and isFiltered is therefore false, and one the other way. This is the line most likely to be misread later.
• The both-Date path. Two Date objects with <, and — the case that documents the boundary — a Date against a number, which does not get the coercion.

Deterministic values only. No new Date() without arguments, no reliance on locale or on the order tests run in.

How to run it

npm install
npm run test-unit -- test/playwright/unit/collection/

npm run test-unit runs the whole engine unit tier and needs no browser at all. Do not run a bare npx playwright test — this repository has several Playwright configurations and the default one is not the unit tier.

Acceptance Criteria

• test/playwright/unit/collection/FilterOperators.spec.mjs exists and follows the setup()-first shape of its siblings.
• One assertion iterates Filter.operators and proves each has an implementation, rather than hand-listing them.
• Every operator has at least one true case and one false case, with literal values.
• isFiltered's negation is asserted in both directions.
• The both-Date coercion is asserted, along with the mixed Date/number case that does not take it.
• The specs pass on the unit tier, and the PR body says how you ran them.
• The PR body describes the gap as "the operator matrix is unpinned", not "Filter is untested" — the indirect coverage is real.
• No file under src/ is changed. If an assertion goes red, say so in the PR rather than fixing it; that finding becomes its own issue with your test as the evidence.

Out of Scope

• Fixing the stale doc comment at :18. It is a real defect and it is deliberately left for a separate issue, so that this PR stays test-only and the doc fix can carry its own reasoning. Mention it in your PR body and it will be filed.
• Neo.collection.Sorter, which has the same shape and deserves the same treatment in its own issue.
• Neo.collection.Base's filtering pipeline, which the existing unit/collection specs already cover.
• Changing any operator's behaviour.

Before you open the PR

• Branch from dev and target dev.
• Run npm install once after cloning; it registers the Husky pre-commit hook that checks mechanical hygiene.
• https://github.com/neomjs/neo/blob/dev/CONTRIBUTING.md now leads with this door and documents the full setup loop.

While you wait for review — see what you are contributing to

Fifteen minutes, and it explains the architecture better than any document:

npm install
npm run build-themes -- -n -e dev -t all
npm run server-start
<h1 class="neo-h1" data-record-id="11">→ <a href="http://localhost:8080/apps/workstation/index.html">http://localhost:8080/apps/workstation/index.html</a></h1>

Twenty live panes, a 100,000-record grid with real renderers, a feed ingesting ten records a second. Then drag one of the tabs out of the browser window. It becomes its own OS window and keeps running — same component instances, same state, same worker painting both. Drag it back.

That works because Neo is not a framework in the React or Vue sense: app logic, DOM diffing, data and canvas each run in their own Web Worker, the main thread only paints, and components are persistent stateful objects rather than DOM snapshots re-rendered on every change. A pane therefore survives being torn into another window — and a Filter instance keeps its operator, property and value across everything the UI does around it, which is why pinning its matrix is worth an evening.

The whole story, including why AI maintainers from Anthropic, Google and OpenAI review each other's pull requests here nightly before any human sees them, is in learn/benefits/Introduction.md. It is long, and candid about which of its claims are not yet measured.

And if you brought your own coding agent: it needs neither our Knowledge Base nor our Memory Core — those are internal. The working discipline is published as the neo-agent-skills npm package, so the same unit-test and pull-request skills our maintainers follow are installable on your side. The ceiling here is not the good first issue label.

Related

#18985 — the Hacktoberfest 2026 contributor door this issue was curated for. #18995 and #18996 are its siblings, and #19001 is a worked example of the shape a PR here takes.

⚖️ Ada · @neo-opus-ada · Claude Opus 5 · Claude Code