Skip to content

Export filter expression evaluation from structured-context/api #132

Open

Description

@mindsocket

Summary

Filter expressions (WHERE … / SELECT … WHERE …, JSONata over nodes augmented with ancestors[] / descendants[]) are only reachable via the CLI today. filterNodes and the per-node evaluation it builds on (src/filter/) are not exported from structured-context/api.

Use case

Library consumers want to reuse the same predicate language rather than reinvent it, e.g.:

  • selecting a subset of a space graph by a named filter view or inline expression (filterNodes(expression, graph)), and
  • evaluating a WHERE predicate against individual nodes without filtering the graph, e.g. to flag or style matching nodes in a UI.

Proposal

  • Export filterNodes from structured-context/api.
  • Export a per-node predicate evaluator, e.g. compileNodePredicate(expression, graph) => (node) => Promise<boolean>, reusing the existing augmentation and expression cache.
  • Export a helper to resolve a filter view name from space config to its expression (or document how to do it).

Activity

  1. mindsocket commented on Oct 6, 2026

    @mindsocket
    OwnerAuthor

    Findings from trying this for a browser consumer (a UI that receives space data as JSON and wants to evaluate filters client-side):

    • The filter code itself is browser-safe. src/filter/ imports only jsonata plus type-only and pure modules. Bundled with esbuild (--platform=browser), filterNodes over buildSpaceGraph(nodes, hierarchy) runs in Chrome and matches sctx dump --filter on a real space (three expressions, including an ancestors[] predicate and a SELECT descendants … WHERE). Cost: ~28 KB gzipped, almost all jsonata.
    • bun build --target=browser breaks it: jsonata.js is a browserify bundle that probes for require, and bun leaves __require undefined in the output. esbuild handles it.
    • Exporting from structured-context/api won't serve browser consumers. Importing anything from /api, even a constant, fails a browser bundle on node:fs, node:path, node:os and node:module. Bundlers resolve these before they can drop unused code.

    So the proposal here probably needs a runtime-agnostic entry point rather than /api alone. That ties into how the public API divides into areas (runtime-agnostic, plugin development, filesystem and config loading), the same open question #138 defers. Worth deciding the two together.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions