Skip to content

Reflection and hosts ​

Descriptors ​

DynamicObjects.property_descriptor Function
julia
property_descriptor(T::Type, property::Symbol)

Return a backward-safe, pure-data descriptor for one DynamicObjects property, or nothing when the type or property has no DO metadata. The result describes inputs/output, lifecycle semantics, option domains, and declared materialization without reading or computing an object property.

The descriptor's own domain is the domain of the property's value, and each entry of inputs carries the domain of that argument. Read the top-level one for a parameter a consumer sets — a fixed field, or an overrideable default like n_chain::Integer = 8, which is a computed property with no signature and therefore no inputs entry to hang a domain on. Every domain has one of three kinds:

  • :static — a finite domain the type proves (Bool, or an Enum), with the values in options.

  • :declared — an @options declaration governs this parameter name; see option_declarations. domain.declaration is the record (declared expression, its dependencies, and static); options is empty because reflection reports the declaration without running it. Call property_options(o, name) for the domain's actual value.

  • :unrestricted — no domain is known; the type is the only constraint.

A domain's multiple is true exactly when the input is an AbstractVector (tags::Vector{String}): its value holds several elements, and the domain — declared or type-inferred — governs each ELEMENT. An @options(tags) declaration lists the allowed elements, and stages::Vector{Stage} for an Enum Stage reports the Stage instances as a :static domain. A consumer checks every element and offers a multiple-choice control.

source
DynamicObjects.property_descriptors Function
julia
property_descriptors(T::Type)

Return descriptors in declaration order. Duplicate property declarations are preserved so consumers can inspect multiple indexed signatures.

source
DynamicObjects.type_descriptor Function
julia
type_descriptor(T::Type)

Type-level counterpart to property_descriptor: what a reflection consumer needs about the node as a whole, so "what is this thing called" has exactly one answer rather than one per consumer.

Returns (; type, name, description, options).

  • description is T's own user-attached docstring, stripped, or nothing when none was attached. The auto-generated property-list docstring @dynamicstruct installs as a ?T fallback is deliberately not reported: it is reference text, not a label.

  • options is option_declarations(T) — including any declaration whose parameter no input of T happens to carry.

source
DynamicObjects.property_signature Function
julia
property_signature(T::Type, prop::Symbol) -> Union{Nothing, NamedTuple}
    property_signature(info::NamedTuple, mod::Module) -> NamedTuple

Structured call signature for an indexed property, parsed from info.indices (the argument list the macro captured from the LHS call). The structured counterpart to property_source_info's stringy signature.

Two entry points:

  • property_signature(T, prop) — look prop up in meta(T) (first declaration, via metafirst) and parse it against parentmodule(T). Returns nothing if meta(T) is undefined or prop isn't a property of T.

  • property_signature(info, mod) — parse an already-selected meta info against module mod, without re-looking it up. Use this when the caller holds a specific declaration. The key case is multi-verb / duplicate-name routes: several declarations can share one property name (e.g. a @get and a @post on user), so meta(T) carries duplicates and metafirst would collapse them to the first. Walk metaall(T, prop) and call this per declaration. Always returns a (possibly empty) (; positional, kwargs).

Both yield (; positional, kwargs), where every entry is a NamedTuple (; name, type, required, default, vararg):

  • name::Union{Symbol,Nothing} — the argument name (nothing for an anonymous ::T positional).

  • type::Union{Type,Nothing} — the annotation resolved against mod by DynamicObjects.resolve_annotation, or nothing when un-annotated OR unresolvable (e.g. a free static-parameter type-var like the V in Verb{V}). Consumers map nothing to their permissive default (HTMXObjects → String). The answer is the same while a package image is written (a @compile_workload, or an __init__ run while another package precompiles) as at run time, though mod is then closed to evaluation.

  • required::Bool — true unless the arg carries a default or is a vararg.

  • default — the default-value expression when required === false; nothing (and meaningless) when required === true. A literal nothing default is told apart from "no default" only by required === false.

  • vararg::Bool — true for a splat (x... / x::T...), which is otherwise indistinguishable from a plain optional arg: both report required=false. Consumers that build a call template need the difference (an open-ended path... segment is not a single optional path).

A non-indexed property (no call signature) yields empty positional and kwargs. A vararg is unwrapped to its inner name/type with required=false and vararg=true.

Layering — intentionally verb-agnostic: this returns every positional arg, including any framework-injected leading arg (e.g. HTMXObjects' injected __verb__::Verb{V}). Filtering such args — and selecting which declaration a verb maps to — is the consumer's job. @param-derived properties are not indexed properties and carry no info.indices; their parsed shape lives in info.rhs and is the consumer's concern.

Pure data extraction. See also property_source_info.

source
DynamicObjects.property_source_info Function
julia
property_source_info(T::Type, prop::Symbol)
    -> Union{Nothing, NamedTuple{(:rhs_string, :signature, :macros, :dependson), …}}

Extract a property's RHS expression, signature, macro chain, and dependson set from meta(T). Returns:

  • nothing if meta(T) is undefined,

  • (; rhs_string=:meta_missing, signature, …) if the prop isn't on T,

  • otherwise a NamedTuple with:

    • rhs_string::String — the lnn-stripped expression as a string, or "(no rhs — forwarded/typed property)" if info.rhs === nothing.

    • signature::String — "name" or "name(arg, …)".

    • macros::String — "@cached " etc. (trailing space if non-empty).

    • dependson::Vector{Symbol} — sorted dependency names.

Pure data extraction. Renderers turn this into HTML / markdown / terminal output.

source
DynamicObjects.property_doc Function
julia
property_doc(info::NamedTuple)

Return the property's declared docstring, or nothing. Obtain the declaration record with metafirst or metaall; this accessor computes no property value.

source

Domains ​

DynamicObjects.static_domain Function
julia
static_domain(values; multiple=false, allow_custom=false)

Normalize raw values or option records already available to a descriptor consumer. This is a framework-facing normalization helper, not an application authoring convention.

source
DynamicObjects.option_declarations Function
julia
option_declarations(::Type{T}) -> Vector{Pair{Symbol,NamedTuple}}

Every @options(<parameter>) = <domain expression> declaration in T's body, in declaration order. A parameter may be declared only once: duplicate declarations are rejected where the @dynamicstruct is defined so reflection and the generated __options__(::Val{parameter}) method can never disagree.

@options declares which values a parameter may take. It is the one thing the structural descriptors cannot infer: a finite domain is proved by the type only for Bool and Enum, and a domain that depends on another input cannot be proved at all. Both spellings are accepted — @options(x) = … (the marker binds its parenthesized argument, so it sits on the assignment's LHS) and @options x = ….

A declaration lowers to the dunder indexed property __options__(::Val{x}), so the domain is an ordinary lazily computed DO value. Nothing is evaluated at macro-expansion time and nothing is evaluated by reflection: the expression runs only when a consumer asks for the value, via property_options. That is what lets a domain be written in terms of application functions and data DO knows nothing about, and it is why the value memoizes and invalidates like every other property.

This function reports the declarations. Each entry's NamedTuple carries:

  • parameter::Symbol — the input this domain governs. It is matched by name against every input of T: a fixed field, a positional or keyword argument of an indexed property, or a fixed field promoted into an operation's :context inputs. One declaration therefore covers every operation that takes that name.

  • expression — the declared expression, verbatim and unevaluated.

  • expression_string::String — string(expression), for display.

  • dependencies::Vector{Symbol} — the sibling properties/fields the expression reads, from the same dependson walk every property RHS gets.

  • static::Bool — isempty(dependencies): true when the domain is fixed for the type, false when it is context-dependent and a consumer must re-read it whenever one of dependencies changes.

  • source::Symbol — which declaration form produced this record (:options).

  • lnn — the declaration's LineNumberNode, or nothing.

The same records reach consumers through the descriptor graph: an input governed by a declaration reports domain.kind === :declared with the record under domain.declaration (see property_descriptor). Reading them here is for whole-type inspection — e.g. a declaration whose parameter no attached input happens to carry.

source
DynamicObjects.has_option_declaration Function
julia
has_option_declaration(T::Type, parameter::Symbol) -> Bool

Whether T declares an @options domain for parameter. The cheap check a consumer makes before property_options — it reads declarations only and never touches an object.

source
DynamicObjects.property_options Function
julia
property_options(o, parameter::Symbol)

The declared domain for parameter on this object — the value of the @options expression, computed against o and memoized like any other property. Returns nothing when no declaration governs parameter.

This is the evaluating half of the option contract, and it needs an object for the same reason a dependent domain exists at all: @options(model) = models_for(study) is only answerable once study is fixed, and study is fixed by o. Reflection (option_declarations, property_descriptor) reports the declaration without running it; this runs it.

A domain is any value supporting in — a vector of nodes, a range, an interval, a type. What a consumer does with it (membership check, control choice, rejecting a submission made against a stale domain) is the consumer's; DO neither interprets the value nor caches a rendering of it.

source
DynamicObjects.option_domain Function
julia
option_domain(values)

Wrap a finite collection as a domain with presentation metadata. Each entry may be a bare value, a value => label pair, or a record with value, label, group, help and disabled fields. Missing labels default to string(value). Membership is defined on the machine values, independently of their labels.

Use the result in an @options declaration. A dependent declaration recomputes when its inputs change. Reflection reports the declaration without evaluating it; read the evaluated domain through property_options, then use option_records for its per-value metadata.

source
DynamicObjects.option_records Function
julia
option_records(domain) -> Vector{NamedTuple} or nothing

The option records of an evaluated domain — one (; value, label, group, help, disabled) per value, in domain order. Use these records to render an evaluated domain.

An option_domain returns its declared labels. Any other finite collection — a vector, tuple, range, or Set — is normalized with default labels (string(value)), so an unlabelled @options declaration still renders. Returns nothing for a domain that is not a finite collection (a type, an interval): there is no list to render, and the consumer falls back to a free input.

source

Structure ​

DynamicObjects.structure Function
julia
structure(T::Type; max_depth=typemax(Int)) -> Node{:pre}

Build a target-agnostic DOM-ish representation of T's DO/HTMXO tree. The root is a Node{:pre} so it renders as <pre class="do-structure">…</pre> in HTML, fenced ````` blocks in markdown, and bare indented text in the terminal. display(s) picks the right MIME for the active display.

source
DynamicObjects.print_structure Function
julia
print_structure([io::IO=stdout,] T::Type; max_depth=typemax(Int))

Convenience: show(io, MIME"text/plain"(), structure(T)). For markdown or HTML output, build the structure with structure(T) and show it under the desired MIME.

source
DynamicObjects.tree_children_map Function
julia
tree_children_map(root::Type) -> Dict{Type, Vector{Tuple{Symbol, Type}}}

Build a parent → [(prop_name, child_type), …] map for every DO/HTMXO type reachable from root. Children are sorted alphabetically by prop_name. The inverse of _build_parent_map. Pure data — no rendering.

source
DynamicObjects.lookup_type Function
julia
lookup_type(root::Type, name::AbstractString) -> Union{Type, Nothing}

Find a DO/HTMXO type in the tree rooted at root by its bare nameof string. Returns nothing if no match.

source
DynamicObjects.callers_by_name Function
julia
callers_by_name(prop::Symbol, root::Type) -> Vector{Tuple{Type, Symbol, Vector{Any}}}

Return every site (caller_type, caller_prop, arg_exprs) that calls a property named prop anywhere in the tree rooted at root. Matches by callee NAME, not by resolved owner type, so cross-type name collisions appear together. Backed by _build_call_index.

source
DynamicObjects.lint_index Function
julia
lint_index(root::Type) -> Dict{Type, NamedTuple{(:warns, :errors, :msgs), …}}

Group analyze_structure(root) output by LintMessage.type. Each entry carries warn/error counts and the underlying messages. Returns an empty Dict if analyze_structure throws (e.g. partially-defined tree).

source
DynamicObjects.LintMessage Type
julia
LintMessage

A declaration diagnostic returned by lint_index. Fields identify the type, optional prop, severity (:warn or :error), short and long messages, and optional source line node lnn. Rendering a structure exposes these diagnostics; defining a type does not print them automatically.

source
DynamicObjects.metafirst Function
julia
metafirst(T, name::Symbol) -> Union{Nothing, NamedTuple}

Return the first info for name in meta(T), or nothing if absent. Use when you expect at most one entry and don't care about duplicates.

source
DynamicObjects.metaall Function
julia
metaall(T, name::Symbol) -> Vector{NamedTuple}

Return all infos for name in meta(T) in declaration order. Empty if absent. Use when duplicates are expected (e.g. coexisting route + indexed include).

source

Declaration graphs ​

DynamicObjects.declaration_metadata Function
julia
declaration_metadata(T::Type) -> NamedTuple
declaration_metadata(T::Type, ::Val{property}) -> NamedTuple
declaration_metadata(T::Type, ::Val{property}, ::Val{declaration}) -> NamedTuple

Extension hook for declaration-site metadata that belongs on a type or property node in declaration_graph. The default is an empty NamedTuple.

A declaration macro in another package can emit a method beside the declaration it expands, just as a docstring attaches information to a binding. The three-argument form distinguishes duplicate declarations with the same property name; by default it falls back to the two-argument property method. Return only pure data. DynamicObjects stores the result verbatim under node.metadata.extensions and does not interpret its keys.

source
DynamicObjects.declaration_graph Function
julia
declaration_graph(root::Type; contributions=())
declaration_graph(object; contributions=())

Build a deterministic, non-evaluating application declaration graph from DynamicObjects metadata. The object overload reflects typeof(object); it does not read the object. The result is pure Julia data:

(; schema="dynamicobjects.declaration-graph/v1", root, nodes, edges, metadata)

root is the stable ID of the root :type node. Every node has at least (;id::String, kind::Symbol, label::String, metadata, fragment::String) and every edge at least (;id::String, kind::Symbol, from::String, to::String, metadata, fragment::String). DynamicObjects emits :type, :property, and :domain nodes, connected only by explicit :contains, direct :depends_on, and :describes relations. Property metadata includes its owner type ID, semantic name, duplicate-declaration occurrence, normalized semantic descriptor, structured signature, declaration extensions, and full captured source AST, code, and file/line provenance. Property and domain metadata also include dependency_analysis=(;opaque, missing, nested) for unresolved declared reads. Sibling dependency edges target every same-name declaration conservatively; the graph does not determine runtime dispatch. Use declaration_selection to select requirements and explicit boundaries without computing properties.

Each contribution is a pure-data (;namespace::String, nodes, edges) fragment using the same envelopes. Base DO data comes first; fragments and the node/edge vectors inside each fragment keep caller order. The namespace is recorded as fragment for provenance but never rewrites IDs. IDs must be globally unique across all nodes and edges; collisions (including with DO IDs) and dangling endpoints are rejected after every fragment is present, so cross-fragment edges may target later fragments.

Use declaration_node_id to connect external nodes to a DO declaration without depending on the spelling of DO IDs. Runtime state is deliberately not part of this graph; see declaration_observations.

source
DynamicObjects.declaration_node_id Function
julia
declaration_node_id(graph, T::Type) -> Union{String,Nothing}
declaration_node_id(graph, T::Type, property::Symbol; declaration=1)
    -> Union{String,Nothing}

Look up stable DO node IDs without depending on their encoded spelling. The property form selects the one-based occurrence among same-name declarations.

source
DynamicObjects.declaration_selection Function
julia
declaration_selection(graph, roots; boundaries=())

Select declarations without reading properties or executing their bodies. graph is a declaration_graph result; roots and boundaries are node ID strings (a single string is also accepted). Use declaration_node_id to identify DO declarations, and the contributed IDs for framework nodes.

Follow outgoing :depends_on and :describes edges. A reached explicit boundary is reported but its outgoing edges are not followed. For A → B → C, selecting A with boundary B requires A, reports B, and omits C; a separate local path to C still retains it. A root cannot also be a boundary. Boundary IDs which are not reached are omitted. Selections may overlap and need not exhaust the graph. Duplicate IDs in either input are harmless; unknown IDs are errors.

Return pure data with schema "dynamicobjects.declaration-selection/v1":

  • graph: the original graph's root ID; roots: normalized root IDs.

  • required: IDs of the roots and their transitive local requirements.

  • boundaries: IDs of the reached explicit boundaries, excluded from required.

  • context: additional ancestor IDs reached by following :contains backwards. These preserve owner/mount context, not an assertion that their computations are selected. Containment never selects siblings or descendants, even for a type root. Select an owning/mount property as a root too when its computation must be included, rather than merely described.

  • nodes: original records for the union of those three disjoint ID sets; edges: original edges whose endpoints are in that union. Their source, metadata and fragment provenance are preserved, with no rewriting of IDs.

  • reasons: (;node, kind, from, edge) records for roots, traversed requirement edges, and containing context. A root has from=edge=nothing; other reasons cite an original edge. These distinguish traversal from merely retained edges.

  • unresolved: (;node, kind, dependency) diagnostics on local requirements. DO reports opaque self access, unrepresented dependency names, known nested/parent reads whose member-level requirements are not in the graph, and unavailable analysis from older graphs. Explicit boundaries suppress these diagnostics for the external node. Arbitrary helpers, runtime dispatch and effects are not inferred: an empty vector is not a proof of purity or whole-program completeness. Contributed nodes are governed by their supplied edges.

ID vectors, nodes and edges keep graph order, independent of input order. Reasons keep root order then edge order. Work is linear in graph size plus diagnostics; cycles terminate. Inputs are never mutated. Node and edge metadata remain shared read-only data; this is a plan, not executable source pruning or automatic remote-call rewriting. Same-name dependency declarations are retained conservatively because a declared edge does not determine runtime dispatch.

source
DynamicObjects.declaration_observations Function
julia
declaration_observations(
    object, graph=declaration_graph(typeof(object)); calls=())

Return a separate, non-computing runtime-state overlay:

(;schema="dynamicobjects.declaration-observations/v1", graph=graph.root, observations)

Each observation is keyed by a stable property node ID as (;node, call, observation). Fixed and scalar properties owned by the root type are observed automatically. Indexed properties are omitted unless calls contains an explicit (;node, args=(), kwargs=(;)) record; this avoids inventing a call key. Nodes owned by nested types and contributed nodes are omitted unless a future composer binds an object for them.

The implementation only calls materialization_observation, which inspects fields, memory caches, pending state, and existing disk paths without calling getproperty, an indexed property, or a property body.

source
DynamicObjects.materialization_observation Function
julia
materialization_observation(object, property::Symbol, args...; kwargs...)

Observe a property's current memory/disk/pending/progress state without computing that property. For disk-backed properties this resolves the ordinary DO cache path and inspects the file; it never creates or loads the target file.

source

Host lifecycle ​

DynamicObjects.execute_materialization Function
julia
execute_materialization(f, context, root)
execute_materialization(context, root) do
    # explicitly selected DynamicObjects access mode
end
execute_materialization(context, root, target, property, args...; kwargs...)
execute_materialization(context, object, property, args...; kwargs...)

Execute a DynamicObjects property under framework-owned storage governance. context is the pure-data (; scope, key, retention) record supplied by a semantic host; ordinary applications call their operations normally and never construct a store. root is the retained application root and target is the mounted object that owns property. For indexed properties, fetch selects synchronous or deferred execution; it reaches the property cache without entering the application argument key or automatic storage path.

The executor adds an active lease around the existing DO property machinery. For an ordinary property on a retained root it observes the actual result and automatically keeps small/cheap values in memory, serializes large or expensive values, and memory-maps large plain Arrays of supported isbits eltypes. Fresh request roots recompute across requests. The root's cache directory and its ownership marker are created only when a value is actually written to disk, so an execution that stores nothing — any fresh request root, the callback form, a result kept in memory — touches no files. Existing @fresh, @cached, and @mmap declarations remain compatibility overrides; applications do not need them for governed execution.

Governance covers exactly the executed property on target. Properties it reads while computing — siblings, nested DO objects, @struct children — run through their ordinary declaration-site semantics and are never automatically promoted; only the executed property's own returned value is observed.

The callback form applies the same active lease and root ownership while leaving value access to the semantic host. It performs no automatic storage read or write itself. Hosts use it with an explicit access mode such as fresh(property, args...) or maybeprogress!(progress, property, args...) when one operation must recompute without changing the property's declaration or its ordinary memoized value. The callback's return value is passed through, and its lease is released even if the callback throws.

source
DynamicObjects.release_materialization! Function
julia
release_materialization!(context, root; reason=:released)

Mark a retained semantic root as released by its provider. Cleanup is deferred until active executions finish and the root's shared cache becomes unreachable. An unknown or mismatched owner is reported as :unowned and nothing is deleted.

source
DynamicObjects.materialization_ownership Function
julia
materialization_ownership(context, root)

Inspect framework storage ownership without computing a property. Returns :unowned, :active, or :released, including lease/reachability and the derived cache identity/version used for fail-closed cleanup.

source
DynamicObjects.materialization_gc! Function
julia
materialization_gc!()

Collect storage owned by semantic roots that their provider has released and that are no longer reachable or executing. Framework lifecycle hooks call this opportunistically; applications do not need a cleanup loop. Cache directories that pre-date governance, are symlinks, or have conflicting ownership markers are preserved.

source