Writing Hashql Jexpr

Writing HashQL J-Expr

J-Expr is a JSON-based expression syntax for HashQL. It represents typed expressions using JSON primitives.

Expression Types

J-Expr has three expression types:

Paths (Strings)

Strings are parsed as paths or identifiers:

"x"                           // Simple variable
"vertex.id.entity_id"         // Dotted path access
"::core::types::String"       // Namespaced/rooted path
"::graph::head::entities"     // Graph function path

Function Calls (Arrays)

Arrays represent function calls: [function, arg1, arg2, ...]

// Basic function call
["add", {"#literal": 1}, {"#literal": 2}]

// Namespaced function
["::graph::head::entities", ["::graph::tmp::decision_time_now"]]

// Labeled argument with :prefix in object
["greet", {":name": {"#literal": "Alice"}}]

// Shorthand labeled argument (string with :prefix)
["func", ":name"]

Data Constructors (Objects with # Keys)

Objects with special # keys construct data:

Literals

{"#literal": 42}
{"#literal": "hello"}
{"#literal": true}
{"#literal": null}
{"#literal": 3.14, "#type": "Float"}

Struct

{"#struct": {"name": {"#literal": "Alice"}, "age": {"#literal": 30}}}
{"#struct": {"x": {"#literal": 1}}, "#type": "Point"}

List and Tuple

{"#list": [{"#literal": 1}, {"#literal": 2}]}
{"#tuple": [{"#literal": 1}, {"#literal": "text"}]}

Dict

{"#dict": {"key": {"#literal": "value"}}}

Common Patterns

Let Binding

["let", "varName", {"#literal": 10}, ["add", "varName", {"#literal": 5}]]

Function Definition

["fn", {"#tuple": []}, {"#struct": {"vertex": "_"}}, "_", body_expr]

Conditionals

["if", condition_expr, then_expr, else_expr]

Comparison

["==", "left", "right"]
[">", {"#literal": 5}, {"#literal": 3}]

Do

• Use #literal for all primitive values (numbers, strings, booleans, null)
• Use :: prefix for namespaced paths
• Use : prefix for labeled arguments
• Combine #type with other constructors for type annotations

Don't

• Don't use bare JSON numbers/booleans - wrap in {"#literal": ...}
• Don't confuse #list (variable-size) with #tuple (fixed-size)
• Don't use # prefix for labeled arguments (use :)
• Don't nest # keys incorrectly - each object should have one primary # key

Examples

Entity query:

["::graph::head::entities", ["::graph::tmp::decision_time_now"]]

Filtering with comparison:

["filter", "entities", 
  ["fn", {"#tuple": []}, {"#struct": {"entity": "_"}}, "_",
    ["==", "entity.draft_id", {"#literal": null}]]]

Struct with type:

{"#struct": {"value": {"#literal": 100}}, "#type": "Amount"}

References

• Syntax Reference - Paths, function calls, operators
• Special Forms - Language constructs (if, let, fn, type, use, etc.)
• Data Constructors - Typed data (#literal, #struct, #tuple, #list, #dict, #type)
• Type DSL - Embedded type annotation syntax
• Parser: libs/@local/hashql/syntax-jexpr/src/parser/
• Object forms: libs/@local/hashql/syntax-jexpr/src/parser/object/
• Type DSL: libs/@local/hashql/syntax-jexpr/src/parser/string/type.rs

J-Expr Data Constructors Reference

Data constructors are JSON objects with # prefixed keys that construct typed data values in J-Expr.

Overview

#literal - Primitive Values

Wraps JSON primitives (numbers, strings, booleans, null) as typed expressions.

Syntax:

{"#literal": <json-primitive>}
{"#literal": <json-primitive>, "#type": "<type>"}

Accepted primitives:

• Numbers: integers and floats
• Strings: quoted text
• Booleans: true / false
• Null: null

Examples:

{"#literal": 42}
{"#literal": 3.14}
{"#literal": "hello world"}
{"#literal": true}
{"#literal": null}
{"#literal": 42, "#type": "Int64"}
{"#literal": "2024-01-01", "#type": "Date"}

Important: Never use bare JSON primitives. Always wrap in #literal:

// ✗ Wrong - bare number
["add", 1, 2]

// ✓ Correct - wrapped literals
["add", {"#literal": 1}, {"#literal": 2}]

#struct - Named Fields

Creates a record/struct with named fields. Keys are parsed as identifiers.

Syntax:

{"#struct": {<field>: <expr>, ...}}
{"#struct": {<field>: <expr>, ...}, "#type": "<type>"}

Field names: Must be valid identifiers (parsed by parse_ident). Snake_case and camelCase are valid.

Examples:

// Simple struct
{"#struct": {"name": {"#literal": "Alice"}, "age": {"#literal": 30}}}

// Empty struct
{"#struct": {}}

// With type annotation
{"#struct": {"x": {"#literal": 10}, "y": {"#literal": 20}}, "#type": "Point"}

// Nested structs
{"#struct": {
  "user": {"#struct": {"name": {"#literal": "Bob"}}},
  "role": {"#literal": "admin"}
}}

// With function call values
{"#struct": {
  "sum": ["add", {"#literal": 1}, {"#literal": 2}]
}}

Invalid field names:

// ✗ Wrong - numeric prefix
{"#struct": {"123field": {"#literal": 1}}}

// ✗ Wrong - hyphenated
{"#struct": {"my-field": {"#literal": 1}}}

#tuple - Fixed-Size Ordered Collection

Creates a fixed-size ordered collection. Each position has a distinct type.

Syntax:

{"#tuple": [<expr>, ...]}
{"#tuple": [<expr>, ...], "#type": "<type>"}

Examples:

// Empty tuple (unit type)
{"#tuple": []}

// Pair
{"#tuple": [{"#literal": 1}, {"#literal": "text"}]}

// Triple
{"#tuple": [{"#literal": 1}, {"#literal": "a"}, {"#literal": true}]}

// With type annotation
{"#tuple": [{"#literal": 10}, {"#literal": "hello"}], "#type": "(Int, String)"}

// Nested tuples
{"#tuple": [
  {"#tuple": [{"#literal": 1}, {"#literal": 2}]},
  {"#literal": 3}
]}

Use cases:

• Return multiple values of different types
• Function parameters
• Coordinates/pairs
• Type parameters (often empty {"#tuple": []})

#list - Variable-Size Ordered Collection

Creates a homogeneous, variable-size collection. All elements share the same type.

Syntax:

{"#list": [<expr>, ...]}
{"#list": [<expr>, ...], "#type": "<type>"}

Examples:

// Empty list
{"#list": []}

// Numbers
{"#list": [{"#literal": 1}, {"#literal": 2}, {"#literal": 3}]}

// Empty list with type
{"#list": [], "#type": "List<Int>"}

// List of structs
{"#list": [
  {"#struct": {"id": {"#literal": 1}}},
  {"#struct": {"id": {"#literal": 2}}}
]}

#list vs #tuple:

• #list: Variable size, homogeneous types
• #tuple: Fixed size, heterogeneous types

// List of integers (any length, all Int)
{"#list": [{"#literal": 1}, {"#literal": 2}]}

// Tuple of (Int, String) - exactly 2 elements, different types
{"#tuple": [{"#literal": 1}, {"#literal": "a"}]}

#dict - Key-Value Map

Creates a dictionary/map. Supports two formats: object format and array format.

Object Format

Keys are always strings. Convenient for string-keyed maps.

Syntax:

{"#dict": {"<key>": <expr>, ...}}

Examples:

// Empty dict
{"#dict": {}}

// String keys
{"#dict": {
  "key1": {"#literal": "value1"},
  "key2": {"#literal": 42}
}}

// With type
{"#dict": {"name": {"#literal": "Alice"}}, "#type": "Dict<String, String>"}

Array Format

Allows arbitrary expressions as keys. Each entry is [key, value].

Syntax:

{"#dict": [[<key-expr>, <value-expr>], ...]}

Examples:

// Empty dict
{"#dict": []}

// Key-value pairs
{"#dict": [
  [{"#literal": "key1"}, {"#literal": "value1"}],
  [{"#literal": "key2"}, {"#literal": 42}]
]}

// Complex keys (computed)
{"#dict": [
  [["concat", {"#literal": "pre"}, {"#literal": "fix"}], {"#literal": "value"}]
]}

When to use each:

• Object format: Simple string keys, more readable
• Array format: Non-string keys, computed keys, complex key expressions

#type - Type Annotation

Modifies other special forms to specify an explicit type. Uses the embedded type DSL.

Syntax: Always paired with another special form:

{"#literal": <value>, "#type": "<type>"}
{"#struct": {...}, "#type": "<type>"}
{"#tuple": [...], "#type": "<type>"}
{"#list": [...], "#type": "<type>"}
{"#dict": ..., "#type": "<type>"}

Examples:

{"#literal": 42, "#type": "Int64"}
{"#literal": 3.14, "#type": "Float"}
{"#struct": {"x": {"#literal": 0}}, "#type": "Origin"}
{"#list": [], "#type": "List<String>"}
{"#tuple": [], "#type": "()"}
{"#dict": {}, "#type": "Dict<String, Int>"}

See type-dsl.md for complete type syntax.

Common Patterns

Function Parameters

Empty tuple for type params, struct for named params:

["fn", {"#tuple": []}, {"#struct": {"x": "_"}}, "_", body_expr]

Let Binding

["let", "varName", {"#literal": 10}, body_expr]

Conditional

["if", condition, {"#literal": "then"}, {"#literal": "else"}]

Entity Filtering

["filter", "entities",
  ["fn", {"#tuple": []}, {"#struct": {"e": "_"}}, "_",
    ["==", "e.archived", {"#literal": false}]]]

Error Handling

Duplicate Keys

Only one primary # key allowed:

// ✗ Error - duplicate primary key
{"#literal": 42, "#literal": 24}

Empty Object

Empty objects are invalid:

// ✗ Error - must have a # key
{}

Unknown Keys

Regular keys not allowed in special form objects:

// ✗ Error - unknown key
{"#literal": 42, "extra": "value"}

Invalid Values

Each special form expects specific value types:

// ✗ Error - #literal expects primitive, not object
{"#literal": {"nested": "object"}}

// ✗ Error - #struct expects object, not array
{"#struct": ["not", "an-object"]}

Source Files

• Parser entry: libs/@local/hashql/syntax-jexpr/src/parser/object/initial.rs
• Literal: libs/@local/hashql/syntax-jexpr/src/parser/object/literal.rs
• Struct: libs/@local/hashql/syntax-jexpr/src/parser/object/struct.rs
• Tuple: libs/@local/hashql/syntax-jexpr/src/parser/object/tuple.rs
• List: libs/@local/hashql/syntax-jexpr/src/parser/object/list.rs
• Dict: libs/@local/hashql/syntax-jexpr/src/parser/object/dict.rs
• Type: libs/@local/hashql/syntax-jexpr/src/parser/object/type.rs

J-Expr Special Forms Reference

Special forms are syntactic constructs with special evaluation semantics. Unlike regular function calls, special forms control evaluation order and introduce bindings.

Overview

HashQL has 10 special forms:

if - Conditional

Evaluates condition and branches.

if/2 - Without else branch (result wrapped in Option):

["if", condition, then_expr]
// Returns Option<T>: Some(then_expr) if true, None if false

if/3 - With else branch:

["if", condition, then_expr, else_expr]

Examples:

// Without else
["if", [">", "x", {"#literal": 0}],
  {"#literal": "positive"}]

// With else
["if", [">", "x", {"#literal": 0}],
  {"#literal": "positive"},
  {"#literal": "non-positive"}]

// Nested conditionals
["if", [">", "value", {"#literal": 0}],
  ["if", ["<", "value", {"#literal": 100}],
    {"#literal": "in range"},
    {"#literal": "too high"}],
  {"#literal": "too low"}]

let - Variable Binding

Binds a value to a name in the body expression. Binds in the value namespace only.

let/3 - Without type annotation:

["let", "name", value_expr, body_expr]

let/4 - With type annotation (equivalent to let/3 with ["as", value, type]):

["let", "name", type_expr, value_expr, body_expr]
// Equivalent to: ["let", "name", ["as", value_expr, type_expr], body_expr]

Examples:

// Simple binding
["let", "x", {"#literal": 10},
  ["add", "x", {"#literal": 5}]]

// With type annotation
["let", "x", "Int", {"#literal": 10},
  ["add", "x", {"#literal": 5}]]

// Nested bindings
["let", "a", {"#literal": 1},
  ["let", "b", {"#literal": 2},
    ["add", "a", "b"]]]

// Binding a computed value
["let", "sum", ["add", {"#literal": 1}, {"#literal": 2}],
  ["multiply", "sum", {"#literal": 3}]]

fn - Function Definition

Defines a closure/function with generic parameters, typed parameters, and return type.

Syntax:

["fn", generics, params, return_type, body]

Components:

• generics: Type parameters
• Tuple form {"#tuple": [...]}: Unbounded type parameters
• Struct form {"#struct": {...}}: Type parameters with bounds ({name: bound})
• params: Struct of {name: type} pairs (always a struct)
• return_type: Type expression or "_" for inference
• body: Function body expression

Examples:

// Simple function, inferred types
["fn", {"#tuple": []}, {"#struct": {"x": "_"}}, "_",
  ["add", "x", {"#literal": 1}]]

// With explicit types
["fn", {"#tuple": []}, {"#struct": {"x": "Int", "y": "Int"}}, "Int",
  ["add", "x", "y"]]

// With generic parameters - tuple form (unbounded)
["fn", {"#tuple": ["T"]}, {"#struct": {"x": "T"}}, "T",
  "x"]

// With generic parameters - struct form (with bounds)
["fn", {"#struct": {"T": "Comparable"}}, {"#struct": {"a": "T", "b": "T"}}, "Boolean",
  [">", "a", "b"]]

// Unbounded in struct form (use "_" for no bound)
["fn", {"#struct": {"T": "_", "U": "Clone"}}, {"#struct": {"x": "T", "y": "U"}}, "_",
  body_expr]

// Filter predicate
["fn", {"#tuple": []}, {"#struct": {"entity": "_"}}, "_",
  ["==", "entity.draft_id", {"#literal": null}]]

as - Type Assertion

Asserts that a value conforms to a type.

Syntax:

["as", value_expr, type_expr]

Examples:

["as", {"#literal": 42}, "Int"]
["as", "some_value", "String"]
["as", ["get_result"], "Option<Int>"]

type - Type Alias

Defines a type alias scoped to the body expression. Binds in the type namespace only.

Syntax:

["type", "Name<constraints>", type_expr, body]

Examples:

// Simple alias
["type", "UserId", "String",
  ["let", "id", {"#literal": "abc"}, "id"]]

// Generic alias
["type", "Pair<T>", {"#tuple": ["T", "T"]},
  body_expr]

// With constraints
["type", "ComparablePair<T: Comparable>", {"#tuple": ["T", "T"]},
  body_expr]

newtype - Nominal Type Wrapper

Creates a new nominal type wrapping an existing type structure. Binds in both namespaces:

• Type namespace: The new type itself
• Value namespace: A constructor function

Syntax:

["newtype", "Name<constraints>", type_expr, body]

Examples:

// Simple newtype - brings `UserId` type and `UserId(String)` constructor
["newtype", "UserId", "String",
  ["UserId", {"#literal": "abc-123"}]]  // Use constructor

// Generic newtype
["newtype", "Wrapper<T>", "T",
  body_expr]

// Unit-like newtype (Null value = no-argument constructor)
["newtype", "Marker", "Null",
  ["Marker"]]  // Constructor takes no arguments

Difference from `type`:

• type: Structural alias (type namespace only), types are interchangeable
• newtype: Nominal wrapper (both namespaces), creates a distinct type with constructor

use - Module Import

Imports items from a module path.

Syntax:

["use", "path", imports, body]

Import forms:

• "*" - Glob import (all items)
• {"#tuple": ["name1", "name2"]} - Named imports
• {"#struct": {"name": "_", "alias": "original"}} - Imports with aliases

Examples:

// Glob import
["use", "::core::math", "*",
  ["add", {"#literal": 1}, {"#literal": 2}]]

// Named imports (tuple)
["use", "::core::types", {"#tuple": ["String", "Int"]},
  body_expr]

// Named imports with aliases (struct)
["use", "::core::types", {"#struct": {"Str": "String", "Integer": "Int"}},
  body_expr]

// Self-named import
["use", "::graph::head", {"#struct": {"entities": "_"}},
  ["entities", ["::graph::tmp::decision_time_now"]]]

input - Host Input Declaration

Declares an input parameter from the host environment.

input/2 - Required input:

["input", "name", type_expr]

input/3 - With default value:

["input", "name", type_expr, default_expr]

Examples:

// Required input
["input", "userId", "String"]

// With default
["input", "limit", "Int", {"#literal": 100}]

// Complex type
["input", "filters", {"#struct": {"status": "String", "active": "Boolean"}}]

access - Field Access

Accesses a field on a value. Alias: .

Syntax:

["access", value_expr, field]
[".", value_expr, field]

Field types:

• Identifier: Named field access
• Integer literal: Tuple index access

Examples:

// Named field
["access", "entity", "properties"]
[".", "entity", "properties"]

// Tuple index
["access", "pair", {"#literal": 0}]
[".", "tuple", {"#literal": 1}]

// Chained access (typically via path strings)
"entity.properties.name"  // Preferred for chained access

index - Index Access

Accesses an element by index. Alias: []

Syntax:

["index", collection_expr, index_expr]
["[]", collection_expr, index_expr]

Shortcut syntax (preferred): Index access can be embedded in path strings:

"items[0]"              // Literal index
"matrix[i]"             // Variable index
"data[0][1]"            // Chained index
"entity.items[0].name"  // Mixed field and index access

Examples:

// Prefer shortcut syntax when possible
"items[0]"

// Explicit form for computed indices
["index", "items", ["add", "i", {"#literal": 1}]]

// Mixed access via string
"entity.properties[0].value"

Namespaces

Special forms bind names in different namespaces:

Common Patterns

Enum via Newtype Union

Create sum types by combining newtypes with union types:

// Define enum variants as newtypes
["newtype", "None", "Null",
  ["newtype", "Some<T>", "T",
    // Define the Option type as a union
    ["type", "Option<T>", "None | Some<T>",
      // Use the constructors
      ["let", "value", ["Some", {"#literal": 42}],
        ["if", ["==", "value", ["None"]],
          {"#literal": "empty"},
          {"#literal": "has value"}]]]]]

Status Enum Pattern

["newtype", "Pending", "Null",
  ["newtype", "Active", "Null",
    ["newtype", "Completed", "Null",
      ["type", "Status", "Pending | Active | Completed",
        body_expr]]]]

Entity Query with Filter

["let", "entities",
  ["::graph::head::entities", ["::graph::tmp::decision_time_now"]],
  ["filter", "entities",
    ["fn", {"#tuple": []}, {"#struct": {"e": "_"}}, "_",
      ["==", "e.archived", {"#literal": false}]]]]

Type-safe Input Processing

["let", "userId", ["input", "userId", "String"],
  ["let", "limit", ["input", "limit", "Int", {"#literal": 50}],
    ["fetch_user_items", "userId", "limit"]]]

Module Import Pattern

["use", "::graph::head", {"#struct": {"entities": "_"}},
  ["use", "::graph::tmp", {"#struct": {"decision_time_now": "_"}},
    ["entities", ["decision_time_now"]]]]

Error Handling

Argument Count Errors

Each special form has specific arity requirements:

// ✗ Error - if needs 2 or 3 arguments
["if", "condition"]

// ✗ Error - let needs 3 or 4 arguments  
["let", "x", {"#literal": 1}]

// ✗ Error - fn needs exactly 4 arguments
["fn", {"#tuple": []}, {"#struct": {"x": "_"}}]

Labeled Arguments Not Supported

Special forms don't accept labeled arguments:

// ✗ Error - labeled argument in special form
["if", {":condition": "x"}, "then", "else"]

Binding Name Errors

Binding names must be simple identifiers:

// ✗ Error - qualified path as binding name
["let", "module::x", {"#literal": 1}, body]

Source Files

• Definition: libs/@local/hashql/core/src/module/std_lib/kernel/special_form.rs
• Lowering: libs/@local/hashql/ast/src/lowering/special_form_expander/mod.rs
• Name resolution: libs/@local/hashql/ast/src/lowering/pre_expansion_name_resolver.rs

J-Expr Syntax Reference

Core syntax reference for J-Expr, the JSON expression syntax for HashQL.

Expression Types

J-Expr maps JSON types to expression semantics:

Paths (String Expressions)

Strings are parsed as paths or identifiers.

Simple Identifiers

"x"
"myVariable"
"entity"

Dotted Paths

Access nested fields:

"vertex.id"
"vertex.id.entity_id"
"entity.properties.name"

Namespaced Paths

Use :: for namespacing:

"Std::String"
"Std::Collections::HashMap"

Rooted paths start with :: (absolute reference):

"::core::types::String"
"::graph::head::entities"
"::graph::tmp::decision_time_now"

Function Calls (Array Expressions)

Arrays represent function calls: [function, arg1, arg2, ...]

Basic Calls

["add", {"#literal": 1}, {"#literal": 2}]
["not", {"#literal": true}]
["concat", {"#literal": "hello"}, {"#literal": " world"}]

Namespaced Functions

["::graph::head::entities", ["::graph::tmp::decision_time_now"]]
["::core::math::sqrt", {"#literal": 16}]

Nested Calls

["add", 
  ["multiply", {"#literal": 2}, {"#literal": 3}],
  {"#literal": 4}]

Labeled Arguments

Use : prefix for named/labeled arguments.

Object syntax:

["greet", {":name": {"#literal": "Alice"}, ":greeting": {"#literal": "Hello"}}]

Shorthand string syntax:

["func", ":varName"]  // References variable "varName" as labeled argument

Operators

Comparison

["==", "left", "right"]
["!=", "left", "right"]
[">", {"#literal": 5}, {"#literal": 3}]
["<", "a", "b"]
[">=", "x", {"#literal": 0}]
["<=", "y", {"#literal": 100}]

Logical

["and", {"#literal": true}, {"#literal": false}]
["or", "condition1", "condition2"]
["not", "flag"]

Arithmetic

["add", {"#literal": 1}, {"#literal": 2}]
["sub", {"#literal": 5}, {"#literal": 3}]
["multiply", {"#literal": 2}, {"#literal": 3}]
["div", {"#literal": 10}, {"#literal": 2}]

Graph Query Patterns

Fetching Entities

["::graph::head::entities", ["::graph::tmp::decision_time_now"]]

Filtering

["filter", "entities",
  ["fn", {"#tuple": []}, {"#struct": {"entity": "_"}}, "_",
    ["==", "entity.draft_id", {"#literal": null}]]]

Property Access

Use dotted paths:

"vertex.id.entity_id"
"entity.properties.name"

Complete Examples

Entity Query with Filter

["let", "entities",
  ["::graph::head::entities", ["::graph::tmp::decision_time_now"]],
  ["filter", "entities",
    ["fn", {"#tuple": []}, {"#struct": {"e": "_"}}, "_",
      ["==", "e.archived", {"#literal": false}]]]]

Nested Conditional

["let", "value", {"#literal": 42},
  ["if", [">", "value", {"#literal": 0}],
    ["if", ["<", "value", {"#literal": 100}],
      {"#literal": "in range"},
      {"#literal": "too high"}],
    {"#literal": "too low"}]]

Multiple Variable Bindings

["let", "x", {"#literal": 1},
  ["let", "y", {"#literal": 2},
    ["let", "z", ["add", "x", "y"],
      ["multiply", "z", {"#literal": 2}]]]]

Related References

• Special Forms - Control flow (if, let, fn, type, use, etc.)
• Data Constructors - Typed data (#literal, #struct, #tuple, #list, #dict)
• Type DSL - Type annotation syntax

Source Files

• Expression parser: libs/@local/hashql/syntax-jexpr/src/parser/
• String/path parser: libs/@local/hashql/syntax-jexpr/src/parser/string/
• Array parser: libs/@local/hashql/syntax-jexpr/src/parser/array/

J-Expr Type DSL Reference

Types in J-Expr are written as strings and parsed by an embedded DSL. Used with the #type key in special forms.

Grammar (ABNF)

From libs/@local/hashql/syntax-jexpr/src/parser/string/type.rs:

infer        = "_"
tuple        = "()" / "(" +(type ",") ?(type) ")"
struct       = "(:)" / "(" ident ":" type *("," ident ":" type) ?"," ")"
paren        = "(" type ")"
atom         = path / tuple / struct / infer / paren
union        = atom *("|" atom)
intersection = union *("&" union)
type         = intersection

Type Forms

Infer Type

Placeholder for type inference:

"_"

Used when the type should be inferred by the compiler.

Path Types (Named Types)

Simple identifiers or qualified paths:

"Int"
"String"
"Boolean"
"std::String"
"std::collections::HashMap"
"::core::types::String"

Rooted paths: Start with :: to reference from root namespace.

Generic Types

Path with type arguments in angle brackets:

"Vec<T>"
"Map<K, V>"
"Option<String>"
"Result<T, E>"
"HashMap<String, Vec<Option<T>>>"

Nested generics:

"Container<Wrapper<T>>"
"Result<Option<T>, E>"

Generic Constraints

Type parameters with bounds:

"Vec<T: Clone>"
"Map<K: Hashable, V: Clone>"
"Container<T: Serializable & Comparable>"

Composite Types

Tuple Types

Fixed-size, ordered, heterogeneous:

"()"                    // Empty tuple (unit)
"(Int,)"                // Single-element (trailing comma required)
"(Int, String)"         // Pair
"(Int, String, Bool)"   // Triple
"(_, _, _)"             // Inferred tuple

Note: Single-element tuples require a trailing comma to distinguish from grouping.

Struct Types (Anonymous Records)

Named fields in parentheses:

"(:)"                                    // Empty struct
"(name: String)"                         // Single field
"(name: String, age: Int)"               // Multiple fields
"(name: String, age: Int,)"              // Trailing comma allowed
"(key: K, value: V)"                     // Generic field types
"(person: (name: String, age: Int))"     // Nested struct

Syntax: (field1: Type1, field2: Type2, ...)

Union Types

One of several types (sum type):

"Int | String"
"Int | String | Boolean"
"Option<T> | Error"

Operator: | (pipe)

Intersection Types

Combines multiple types (must satisfy all):

"Serializable & Comparable"
"Int & Positive"
"Readable & Writable & Closeable"

Operator: & (ampersand)

Operator Precedence

From highest to lowest:

1. Atoms (paths, tuples, structs, infer, parenthesized) 2. Union (|) 3. Intersection (&)

Examples:

// Intersection binds tighter than union
"Int & String | Boolean & Char"
// Parses as: (Int & String) | (Boolean & Char)

// Use parentheses to override
"Int & (String | Boolean) & Char"

Whitespace

Whitespace is allowed around operators and inside structures:

"Int | String"          // Around union
"( Int , String )"      // Inside tuple
"( name : String )"     // Around colon
" Int & String "        // Around intersection
"( name : String , age : Int )"

Complete Examples

Simple Types

{"#literal": 42, "#type": "Int"}
{"#literal": "hello", "#type": "String"}
{"#literal": true, "#type": "Boolean"}

Generic Types

{"#list": [], "#type": "List<Int>"}
{"#dict": {}, "#type": "Dict<String, Int>"}
{"#literal": null, "#type": "Option<String>"}

Tuple Types

{"#tuple": [], "#type": "()"}
{"#tuple": [{"#literal": 1}, {"#literal": "a"}], "#type": "(Int, String)"}

Struct Types

{"#struct": {"x": {"#literal": 0}}, "#type": "(x: Int)"}
{"#struct": {
  "name": {"#literal": "Alice"},
  "age": {"#literal": 30}
}, "#type": "(name: String, age: Int)"}

Complex Entity Types

{"#type": "(id: ID, attrs: (name: String, metadata: (created: Timestamp, modified: Timestamp | Null)))"}

Union and Intersection

{"#literal": null, "#type": "String | Null"}
{"#struct": {}, "#type": "Readable & Writable"}

Common Patterns

Optional Values

"Option<T>"
"T | Null"

Result/Either

"Result<T, E>"
"Success<T> | Error<E>"

Collections

"List<T>"
"Set<T>"
"Dict<K, V>"
"Vec<T>"

Function Types (in context)

Used within function definitions:

["fn", 
  {"#tuple": []},           // Type parameters (empty)
  {"#struct": {"x": "_"}},  // Parameter struct (inferred types)
  "_",                      // Return type (inferred)
  body_expr]

With explicit types:

["fn",
  {"#tuple": []},
  {"#struct": {"x": "Int", "y": "Int"}},  // Explicit param types
  "Int",                                   // Explicit return type
  ["add", "x", "y"]]

Error Cases

Unclosed Structures

"(Int, String"      // Missing )
"Vec<T"             // Missing >
"(name: String"     // Missing )

Empty Generic Arguments

"Vec<>"             // Error - empty generics

Missing Elements

"(name: )"          // Missing field type
"Int |"             // Incomplete union
"Int &"             // Incomplete intersection

Invalid Separators

"Vec<T U>"          // Missing comma
"(name String)"     // Missing colon

Source Files

• Type parser: libs/@local/hashql/syntax-jexpr/src/parser/string/type.rs
• Path parser: libs/@local/hashql/syntax-jexpr/src/parser/string/path.rs
• Generic parser: libs/@local/hashql/syntax-jexpr/src/parser/string/generic.rs
• Identifier parser: libs/@local/hashql/syntax-jexpr/src/parser/string/ident.rs