Decorator Compositions for Reusable Decorator Patterns

[btiernay]

Problem Statement

TypeSpec users currently face challenges when they need to apply the same combination of decorators to multiple entities. This leads to repetitive code, which is harder to maintain and more error-prone. This issue was raised in TypeSpec discussion #1850.

Consider this example:

model User {
  @key
  @format("hex")
  @pattern("^[a-f0-9]{64}$")
  @description("A unique identifier for a user.")
  userId: string;
}
model Member {
  @key
  @format("hex")
  @pattern("^[a-f0-9]{64}$")
  @description("A unique identifier for a member.")
  memberId: string;
}
model Proposal {
  @key
  @format("hex")
  @pattern("^[a-f0-9]{64}$")
  @description("A unique identifier for a proposal.")
  proposalId: string;
}

Repetition like this creates several challenges:

1. Maintenance Burden: When validation patterns need updates, developers must modify each occurrence, risking inconsistencies.
2. Cognitive Load: Repeated decorator patterns obscure the core API structure, making code harder to read.
3. Error Risk: Manual repetition increases the chance of typos or missed decorators.
4. Documentation Inconsistency: Maintaining consistent documentation patterns becomes difficult across related entities.

While custom scalars can help reduce some duplication, they don't provide a complete solution, particularly when:

1. You need to customize parts of the decorators (like description text)
2. You want to avoid explicit type references in generated outputs with some emitters
3. You need to apply decorators that aren't valid on scalars

Model inheritance and spread operators have similar limitations, as they don't allow for property name customization and may introduce unwanted inheritance semantics.

The decorator composition feature directly addresses these pain points by providing a mechanism for defining, parameterizing, and reusing decorator combinations without these limitations, aligning with TypeSpec's goals of creating clear, maintainable API definitions.

Proposed Solution: Decorator Compositions

We propose adding decorator composition to TypeSpec, allowing developers to define reusable decorator groups that can be parameterized. This is similar to how decorators themselves are defined in TypeSpec, but instead of implementing a single decorator function, a composition would expand to multiple decorators.

Syntax: Decorator Composition Definition

/**
 * Creates a typed unique identifier with consistent validation and documentation
 * @param entityType The type of entity this ID belongs to (user, member, etc.)
 */
dec uniqueId(entityType: string) {
  @key
  @format("hex")
  @pattern("^[a-f0-9]{64}$")
  @description(`A unique identifier for a ${entityType}.`)
}

Syntax: Decorator Composition Usage

model User {
  @uniqueId("user")
  userId: string;
}

model Member {
  @uniqueId("member")
  memberId: string;
}

model Proposal {
  @uniqueId("proposal")
  proposalId: string;
}

Decorator Composition Semantics

Expansion and Application

Decorator compositions are expanded at compile time, effectively inlining the constituent decorators. When a composition is applied, it's as if each decorator within the composition was applied individually in the order defined.

// This:
@uniqueId("user")
userId: string;

// Expands to:
@key
@format("hex")
@pattern("^[a-f0-9]{64}$")
@description("A unique identifier for a user.")
userId: string;

Type Checking and Parameters

Parameters to decorator compositions are type-checked according to their declared types. These parameters can be used in the composed decorators through string interpolation or direct reference:

/**
 * Applies standard API versioning decorators to a namespace or operation
 * @param version The API version string
 */
dec apiVersion(version: string) {
  @tag(`v${version}`)
  @path(`/v${version}`)
  @doc(`API Version: ${version}`)
}

@apiVersion("v2")
namespace Users {
  @route("/users")
  op list(): User[];
}

Documentation Propagation

Documentation for decorator compositions works on two levels:

1. Composition Definition Documentation: Documents the purpose and parameters of the composition itself
2. Applied Documentation: Any @doc or @description decorators within the composition are applied to the target

/**
 * Marks an entity as versioned with appropriate headers
 * @param apiVersion The API version this entity belongs to
 */
dec versioned(apiVersion: string) {
  @header("api-version", apiVersion)
  @doc(`API Version: ${apiVersion}`)
}

When a decorator composition is expanded, its documentation isn't directly propagated, but any documentation decorators within it are applied normally. This allows for targeted, contextual documentation.

Metadata and Emitter Interaction

Emitters interact with the expanded form of decorator compositions. By the time an emitter processes the TypeSpec program, compositions have been expanded to their constituent decorators. This ensures that emitters don't need special handling for compositions.

However, for debugging and tooling purposes, the compiler maintains references to the original composition in the program's metadata, allowing tools to show that a set of decorators came from a composition.

Benefits

1. Reduced Repetition: Encapsulate commonly used decorator combinations
2. Improved Maintainability: Change decorated behavior in a single place
3. Better Readability: Clear, concise code that expresses intent
4. Template Support: Parameterize decorator compositions for flexibility
5. Inlining: Compositions are expanded at compile time, so no unwanted references in output
6. Type Safety: Compositions are type-checked like any other TypeSpec construct
7. Transparency to Emitters: No special handling required in emitters

Comparison with Similar Concepts in Other Languages

The concept of decorator compositions is analogous to several patterns in other programming languages:

1. Attribute Compositions in C#: C# allows defining custom attributes that combine the functionality of other attributes.

   Example: ValidationAttributes

   // Creating a combined validation attribute
   public class ValidPhoneNumberAttribute : RegularExpressionAttribute
   {
       public ValidPhoneNumberAttribute() : base(@"^\d{3}-\d{3}-\d{4}$")
       {
           ErrorMessage = "Phone number must be in format: ###-###-####";
       }
   }
   
   // Usage
   public class Contact
   {
       [ValidPhoneNumber]
       public string PhoneNumber { get; set; }
   }

2. Java Annotation Grouping: Java allows defining meta-annotations that group multiple annotations together.

   Example: Spring's composed annotations

   // Defining a composed annotation
   @Target({ElementType.METHOD})
   @Retention(RetentionPolicy.RUNTIME)
   @Documented
   @RequestMapping(method = RequestMethod.GET)
   public @interface GetMapping {
       @AliasFor(annotation = RequestMapping.class)
       String[] value() default {};
   }
   
   // Usage
   @GetMapping("/users")
   public List<User> getUsers() { ... }

3. Rust Attribute Macros: Rust allows creating attribute-like macros that expand to multiple attributes.

   Example: Derive macros

   // A derive macro that adds multiple traits
   #[proc_macro_derive(MyTraits)]
   pub fn my_traits_derive(input: TokenStream) -> TokenStream {
       // Expands to implement multiple traits for the struct
   }
   
   // Usage
   #[derive(MyTraits)]
   struct MyStruct {}

4. Python Decorator Factories: Python allows creating functions that return combinations of decorators.

   Example: Stacked decorators

   def auth_required(roles):
       """Combined authentication decorator that checks both auth and roles"""
       def decorator(f):
           @login_required
           @has_role(roles)
           @wraps(f)
           def decorated_function(*args, **kwargs):
               return f(*args, **kwargs)
           return decorated_function
       return decorator
   
   # Usage
   @auth_required(['admin'])
   def sensitive_operation():
       pass

5. TypeScript Decorators: TypeScript's experimental decorators allow for decorator factories that can apply multiple behaviors.

   Example: Decorator Composition

   // Creating a composed decorator
   function StandardProperty(required: boolean = true) {
       return function(target: any, propertyKey: string) {
           Reflect.defineMetadata("required", required, target, propertyKey);
           Reflect.defineMetadata("serializable", true, target, propertyKey);
       }
   }
   
   // Usage
   class User {
       @StandardProperty()
       name: string;
   }

Each of these approaches demonstrates how other languages have solved the problem of decorator composition. TypeSpec's proposal aims to provide a similarly elegant solution while maintaining the language's focus on type safety and clarity.

What sets this proposal apart is that it's fully integrated into TypeSpec's type system, ensuring that compositions are type-checked at compile time rather than being simple textual macros.

Comparison with Current Workarounds

Custom Scalars

Current workaround using custom scalars:

@format("hex")
@pattern("^[a-f0-9]{64}$")
scalar HexId extends string;

model User {
  @key
  @description("A unique identifier for a user.")
  userId: HexId;
}

Issues with this approach:

• Creates references in OpenAPI output
• Can't customize description per entity
• Not all decorators can be applied to scalars

Model Inheritance/Spread

Current workaround using inheritance:

model BaseId {
  @key
  @format("hex")
  @pattern("^[a-f0-9]{64}$")
  id: string;
}

model User extends BaseId {
  // Can't customize the property name
}

Issues with this approach:

• Can't customize property names
• Inheritance semantics might be too heavy for decorator reuse

Advanced Examples

Authentication Requirements

/**
 * Specifies authentication requirements for an operation
 * @param scopes Required OAuth scopes for this operation
 */
dec requiresAuth(scopes: string[]) {
  @tag("secured")
  @doc(`Requires authentication with scopes: ${scopes.join(", ")}`)
  @useAuth("oauth2")
  @response(401, "Unauthorized")
  @response(403, "Forbidden - insufficient permissions")
}

/**
 * Creates a new user in the system
 * @param user User details to create
 * @returns The created user
 */
@requiresAuth(["admin", "create:users"])
op createUser(user: User): {
  @statusCode statusCode: 201;
  @body createdUser: User;
}

Standard Response Codes

/**
 * Applies standard CRUD response codes with appropriate documentation
 * @param resourceName Name of the resource being operated on
 */
dec standardResponses(resourceName: string) {
  @response(200, `${resourceName} processed successfully`)
  @response(404, `${resourceName} not found`)
  @response(500, "Internal server error")
}

@standardResponses("User")
op getUser(userId: string): User;

Conditional Use Cases without Non-Standard Syntax

While we should avoid introducing new syntax constructs for conditional decoration, the same patterns can be achieved by creating specific composition variants:

/**
 * Marks an API as deprecated
 */
dec deprecatedApi() {
  @deprecated
  @doc("This API is deprecated and will be removed in a future version.")
  @header("Warning", "Deprecated API version")
}

/**
 * Applies versioning decorators to an API entity
 * @param version API version string
 */
dec apiVersion(version: string) {
  @tag(`v${version}`)
  @path(`/v${version}`)
  @doc(`API Version: ${version}`)
}

// Usage
@apiVersion("v1")
@deprecatedApi
namespace OldApi {}

@apiVersion("v2")
namespace NewApi {}

Technical Details

1. Decorator compositions are expanded at compile time
2. Parameters can be used within decorators (string interpolation)
3. Compositions can be used anywhere normal decorators can be used
4. Compositions use the same syntax for application as regular decorators
5. Type checking ensures that composition parameters are used correctly
6. Compositions maintain source location information for error reporting
7. Emitters see only the expanded decorators, with no special handling required

Next Steps

1. Gather community feedback on the proposal
2. Refine syntax and semantics based on feedback
3. Implement an MVP version
4. Document the feature and provide examples

Questions for Discussion

Q: How should compositions interact with TypeSpec's type system?

• Should we support direct reference to TypeSpec types as composition parameters?
• What kinds of type references should be supported (Model, Scalar, Interface, etc.)?
• Could compositions be generic over TypeSpec types?
• How would type constraints and inference work for composition type parameters?
• What operations on type references should be allowed within compositions?

Q: How should composition naming and namespaces be handled?

• Should compositions have their own independent namespace?
• How should name collisions between regular decorators and compositions be resolved?
• What scoping rules should apply to imported compositions?
• How should version compatibility of compositions be managed across libraries?
• Should we enforce naming conventions to avoid collisions (e.g., prefixes)?

Q: Should we support composition nesting and extension?

• What would be the syntax for compositions that reference other compositions?
• How would parameter passing work between nested compositions?
• What would extension of existing compositions look like?
• How would conflicting decorators be resolved in an extension hierarchy?
• How deep should nesting be allowed before raising complexity concerns?

Q: How should we handle composition recursion and safety?

• How should we detect and prevent infinite recursion in compositions?
• What should happen if a composition directly or indirectly references itself?
• Should there be static analysis to identify potential recursion issues at compile time?
• Should there be limits on composition complexity for performance reasons?

Q: How should compositions interact with decorator targets?

• How would we validate that compositions are only used on appropriate targets?
• Can we define compositions that are restricted to specific TypeSpec constructs?
• What happens if a composition contains decorators with conflicting target requirements?
• How will decorator compositions interact with augment decorators (@@)?

Q: How should diagnostic messages and error reporting work with compositions?

• Should errors point to the composition definition, the usage site, or both?
• How can we make stack traces clear when multiple levels of expansion are involved?
• How should parameter substitution errors be reported?
• Should there be a way to debug the expanded form of a composition?

Q: What are the compiler and performance implications?

• At what point in the compilation pipeline should compositions be expanded?
• How might compiler performance be affected by heavy use of compositions?
• Are there compile-time optimizations for frequently used compositions?
• How should caching work with parameterized compositions?

Q: How should IDE and tooling support compositions?

• What hover/IntelliSense information should be shown for compositions?
• Should "Go to Definition" navigate to the composition or expand inline?
• How should self-documenting code features work with compositions?
• Should refactoring tools understand composition relationships?

Q: How should documentation generation handle compositions?

• Should generated documentation show the composition or its expanded form?
• How can documentation for compositions be made accessible to users?
• How should parameter documentation within compositions be displayed?
• How can we ensure traceability between composition usage and expanded decorators?

Q: What constraints should apply to decorator compositions?

• Should compositions be limited to certain kinds of decorators?
• Are there restrictions on what can be parameterized?
• How should side-effecting decorators be handled in compositions?
• Should extension of built-in compositions be restricted?

[timotheeguerin]

there is a few things we want to make sure we do before we'd move forward with this. We did have the vision that this decorator syntax would be used for some more complex decorator implementation at some point(Without having to write the js implementation). So while supporting a subset of that as your proposal define sounds like a good initial step we do want to be sure it will be compatible with that potential future syntax and not back ourself into a corner.

On thing I am thinking for example might be more appropriate is something of the sort

dec uniqueId(target: ModelProperty, entityType: string) {
  @@key(target);
  @@format(target, "hex");
  @@pattern(target, "^[a-f0-9]{64}$");
  @@description(target, `A unique identifier for a ${entityType}.`);
}

(using the augment decorator syntax to be explicit about what you target

I think this answer a few of the questions above as well as yoiu can see this as basically jsut an implementation of the decorator and isn't to be treated much differently from the outside as if it was implemented in JS. This means it wouldn't really apply the @key decorator it would just run it(meaning if you try to list the decorators on the property it would only list @uniqueId).
In the inside we'd definitely have to decide how does the type checking works, do we do more of an eval system like projections used to do or do we try to "compile" that implemenation linking everything and running it after.