How can I create an instantiation of a template type using compiler API in a decorator?

[Veetaha]

Problem statement

I want to create a decorator @foo for the JSONSchema emitter. This decorator is basically a shortcut for the following decorator

@extension("x-foo", Json<"value here">)

which should simplify this to:

@foo("value here")

I didn't find any way to instantiate a template Type using the Program interface, so as a hacky workaround I created the foo decorator as specified below. This implementation is fragile, because it doesn't pass the entire Type as a parameter to $extension, but the object with the properties that I know that decorator accesses:

import { createRekeyableMap } from "@typespec/compiler/utils";
import { $extension } from "@typespec/json-schema";

/**
* @param {import("@typespec/compiler").DecoratorContext} context
* @param {import("@typespec/compiler").Type} target
* @param {import("@typespec/compiler").StringLiteral} value
*/
export function $foo(context, target, value) {
   $extension(context, target, "x-foo", {
       kind: "Model",
       name: "Json",
       namespace: { name: "JsonSchema" },
       properties: createRekeyableMap([["value", { type: value }]])
   })
}

Basically there is quite a lack of documentation in the @typespec/compiler library. I can only speculate and assume what the method does by its name. For example, Checker.createType() seems like a method I'd need to use, but its signature requires passing a Type as an input though with several properties omitted.

export type CreateTypeProps = Omit<Type, "isFinished" | keyof TypePrototype>;
export interface Checker {
   createType<T extends Type extends any ? CreateTypeProps : never>(typeDef: T): T & TypePrototype & {
        isFinished: boolean;
    };
}

---

Another thing I tried is this:

context.program.resolveTypeReference("TypeSpec.JsonSchema.Json");

but it returns:

[
  undefined,
  [
    {
      code: 'invalid-template-args',
      severity: 'error',
      message: "Template argument 'Data' is required and not specified.",
      target: [Object]
    }
  ]
]

Then I tried

context.program.resolveTypeReference("TypeSpec.JsonSchema.Json<\"foo\">");

but it returns

[ undefined, [] ]

[timotheeguerin]

Yeah resolveTypeReference is explicitly designed to not instantiate further templates(readonly). I don't think we have a good API for this.

But seeing this is to simplify the @JsonSchema.extension decorator i think there is a few things:

1. we have a new way of defining values in TypeSpec(coming next version) and part of this would be not requiring the Json<T> wrapper for values in this decorator. However that is a breaking change(to change that specific decorator) and we haven't decided yet if we'll take it.
2. We could consider exporting the setter directly instead so you don't have to call another decorator and build this dummy ojbect just for that

[Veetaha]

we have a new way of defining values in TypeSpec(coming next version) and part of this would be not requiring the Json wrapper for values in this decorator.

I would love some syntax better than Json<T>, which seems a bit clunky. I can think of several options:

• Swap the defaults such that regular extension(key, value) expects a value by default, and Json<Y> (or maybe renamed to JsonSchema<T>) turns the T into a schema in the added field.
• Split the decorator into extensionSchema(key, T) and extensionValue(key, value) to separate the use cases, because it really looks to me as totally separate use cases

Anyway, it's just my 5 cents, and it seems like you already have a better idea for the direction of extension in this regard to its ergonomics.

However that is a breaking change(to change that specific decorator) and we haven't decided yet if we'll take it.

Only if this matters to you or someone else. I don't mind any breaking changes at the stage I'm using TypeSpec yet, and would even prefer improvement over a breaking change from my side.

We could consider exporting the setter directly instead so you don't have to call another decorator and build this dummy ojbect just for that

That would be perfect, indeed! In my use case, I'm writing a library that simplifies adding several x-* attributes to the schema for some tools, and I'd be happy to have a public TS function that let's me achieve this without a hack.

Created an issue for this #3336