writing-hashql-jexpr

The writing-hashql-jexpr skill provides comprehensive documentation and guidance for developers working with HashQL J-Expr, a JSON-based expression syntax designed for the HASH database. This skill is intended for engineers and data analysts who need to construct, debug, or refactor complex queries within HashQL query files (.jsonc). It covers the fundamental data structures, including strings for path identifiers, arrays for function invocations, and objects utilizing special # prefix keys for typed data construction. Users will find detailed explanations of how to handle primitives, structs, lists, tuples, and dictionaries, alongside essential patterns for let-bindings, function definitions, and conditional logic. Whether you are writing a filter expression, defining a custom graph function, or structuring data for an agent, this skill provides the necessary syntax standards to ensure your queries are valid and performant.

• Detailed syntax for J-Expr primitives including #literal, #struct, #list, #tuple, #dict, and #type.

• Guidance on path resolution using string identifiers and dotted notation or namespace-rooted paths (::).

• Support for functional programming patterns within J-Expr, such as function calls in arrays and labeled arguments using the :prefix convention.

• Best practices for combining #type annotations with data constructors to maintain schema integrity.

• Clear instructions on structural constraints to prevent common errors like incorrect nesting of # keys.

• Always wrap primitive values like numbers, booleans, and null in the #literal constructor to ensure correct parsing.

• Use the :: prefix for all namespaced paths to maintain accurate references to the HASH graph.

• Distinguish clearly between #list (variable-size collections) and #tuple (fixed-size, heterogeneous collections) to prevent schema mismatches.

• When defining logic, utilize standard forms like if, let, and fn provided by the HASH ecosystem to build dynamic, reactive query components.

• Input for this skill is typically raw JSONC or pseudocode intended for translation into J-Expr, while the output is optimized, type-safe J-Expr syntax ready for integration into the HASH runtime environment.