Checker functions getValueForNode and getTypeOrValueForNode marked as internal

[singh-harsh]

I would like to understand the rationale behind making the following methods of the Checker class internal:

1. getValueForNode
2. getTypeOrValueForNode

Use Case

• I am working with a TypeSpec file that includes a constant defined something as follows:

const example = #[
  #{
    key: "value"
  }
]

• In my decorator implementation, I am reading this constant and attempting to parse it into a Value.
• I am able to read the file and convert it into a TypeSpecScriptNode. From there, I iterate over the statements and extract the individual Node elements.
• At this point, I would like to construct a Value from a Node.

Concern

• Currently, I do not see a straightforward way to achieve this without implementing a custom Checker.
• I would like to understand:
  • Is there a supported or recommended way to construct a Value from a Node using public APIs?
  • If not, is there a reason these methods (getValueForNode, getTypeOrValueForNode) are restricted to internal use?

[timotheeguerin]

As we are release 1.0 we did a cleanup of every API that shouldn't be used and were not meant to be exported.

Using the AST(nodes) of typespec is not a scenario that we consider a supported scenarios for libraries and emitter expect for very specific cases see our Breaking change policy for more details.

Can you explain a bit more on why you need to inspect the node here, where do you get the node from in your decorator.

[singh-harsh]

We have a custom operation in our TypeSpec API specification where we wanted to dynamically attach example data. To achieve this, we developed a custom decorator that encapsulates the logic for applying examples to an operation in a reusable way. This allows us to separate the example definitions from the operation declarations, making our TypeSpec files cleaner and more maintainable.

The example data is stored externally in a file named example.tsp. This file contains well-structured TypeSpec code that defines various example payloads we want to associate with our operations. Instead of hardcoding these examples directly within the operation definitions, our decorator reads the contents of this file at runtime and parses it to extract usable data.

To process the contents of the example.tsp file, we parse it into a TypeSpecScriptNode, which represents the script's abstract syntax tree (AST). This parsed node allows us to programmatically inspect and manipulate the contents of the example file. Our ultimate goal is to pass these extracted examples to the built-in $opExample decorator, which is responsible for attaching examples to TypeSpec operations.

However, $opExample expects its arguments to be of type Value. Since the parsed TypeSpecScriptNode provides raw AST statements rather than Value instances, we must first transform these statements. This involves interpreting the AST nodes, extracting the relevant definitions, and constructing the equivalent Value objects from them. Only after this conversion can we successfully pass the data to $opExample, thereby completing the process of dynamically applying operation examples via our custom decorator.

[timotheeguerin]

So just to be clear what you have is something of the sort

@autoExample
model MyModel {...}

in a file that is not imported MyModel.example.tsp

const example = #{....};

and that @autoDecorator somehow goes and parse that known file get the expected const, used to call the checker to get the value type of this and then calls $opExample?

The general idea of TypeSpec is that we have this typegraph which represent the understood respresentation of the spec and we don't really want to encourage any use out of that scope.

[singh-harsh]

That’s almost correct and aligns closely with what I’m trying to achieve. However, I’ve run into a limitation—specifically, the function getValueForNode is not exported by the TypeSpec compiler or its associated modules. This presents a challenge because that function would typically be responsible for converting syntax nodes into the Value type required by the $opExample decorator. Without access to it, I'm currently blocked in terms of how to reliably construct Value instances from the parsed TypeSpecScriptNode.

Just to clarify the use case further, the custom decorator we’ve created is specifically designed to target Operation elements. Its sole purpose is to read example data, transform it appropriately, and then attach it to the corresponding operation using $opExample.

[timotheeguerin]

This statement is exactly why this was made internal

how to reliably construct Value instances from the parsed TypeSpecScriptNode.

we do not want define this workflow as a reliable use of the TypeSpec API.

The function is only internal so its still there and you can use it at your own risk.

while it might work for your use case now, dynimacally loading and parsing a separate file like that out of the program will most likely result in a lot of broken things if you try to reference anything outside of it(including built-in scalars).

We do want at some point to provide a way to achieve this kind of separation for examples.

[singh-harsh]

Thank you so much for your response and explanation. Appreciate it!