@typespec/versioning 0.79.0-dev.3 → 0.79.0-dev.4

package/README.md

@@ -214,7 +214,12 @@ op newName(): void;
 
 #### `@returnTypeChangedFrom`
 
-Identifies when the target type changed.
+Declares that the return type of an operation has changed starting at a given version,
+while keeping earlier versions consistent with the previous return type.
+
+This decorator is used to track return type changes across API versions. When applied,
+the operation will return `oldType` in versions before the specified `version`,
+and the current return type definition in the specified version and later.
 
 ```typespec
 @TypeSpec.Versioning.returnTypeChangedFrom(version: EnumMember, oldType: unknown)
@@ -226,14 +231,28 @@ Identifies when the target type changed.
 
 ##### Parameters
 
-| Name    | Type         | Description                                  |
-| ------- | ------------ | -------------------------------------------- |
-| version | `EnumMember` | The version that the target type changed in. |
-| oldType | `unknown`    | The previous type of the target.             |
+| Name    | Type         | Description                                                                                                                                                              |
+| ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| version | `EnumMember` | The version when the return type change takes effect. The new return type applies<br />from this version onwards, while the old return type applies to earlier versions. |
+| oldType | `unknown`    | The previous return type used before the specified version.                                                                                                              |
+
+##### Examples
+
+```tsp
+// In v1: returns a string
+// In v2+: returns an int32
+@returnTypeChangedFrom(Versions.v2, string)
+op getUserId(): int32;
+```
 
 #### `@typeChangedFrom`
 
-Identifies when the target type changed.
+Declares that the type of a model property has changed starting at a given version,
+while keeping earlier versions consistent with the previous type.
+
+This decorator is used to track type changes across API versions. When applied,
+the property will use `oldType` in versions before the specified `version`,
+and the current type definition in the specified version and later.
 
 ```typespec
 @TypeSpec.Versioning.typeChangedFrom(version: EnumMember, oldType: unknown)
@@ -245,10 +264,21 @@ Identifies when the target type changed.
 
 ##### Parameters
 
-| Name    | Type         | Description                                  |
-| ------- | ------------ | -------------------------------------------- |
-| version | `EnumMember` | The version that the target type changed in. |
-| oldType | `unknown`    | The previous type of the target.             |
+| Name    | Type         | Description                                                                                                                                         |
+| ------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| version | `EnumMember` | The version when the type change takes effect. The new type applies<br />from this version onwards, while the old type applies to earlier versions. |
+| oldType | `unknown`    | The previous type used before the specified version.                                                                                                |
+
+##### Examples
+
+```tsp
+model Foo {
+  // In v1: id is a string
+  // In v2+: id is an int32
+  @typeChangedFrom(Versions.v2, string)
+  id: int32;
+}
+```
 
 #### `@useDependency`
 

package/dist/generated-defs/TypeSpec.Versioning.d.ts

@@ -124,17 +124,45 @@ export type MadeOptionalDecorator = (context: DecoratorContext, target: ModelPro
  */
 export type MadeRequiredDecorator = (context: DecoratorContext, target: ModelProperty, version: EnumMember) => DecoratorValidatorCallbacks | void;
 /**
- * Identifies when the target type changed.
+ * Declares that the type of a model property has changed starting at a given version,
+ * while keeping earlier versions consistent with the previous type.
  *
- * @param version The version that the target type changed in.
- * @param oldType The previous type of the target.
+ * This decorator is used to track type changes across API versions. When applied,
+ * the property will use `oldType` in versions before the specified `version`,
+ * and the current type definition in the specified version and later.
+ *
+ * @param version The version when the type change takes effect. The new type applies
+ * from this version onwards, while the old type applies to earlier versions.
+ * @param oldType The previous type used before the specified version.
+ * @example
+ * ```tsp
+ * model Foo {
+ *   // In v1: id is a string
+ *   // In v2+: id is an int32
+ *   @typeChangedFrom(Versions.v2, string)
+ *   id: int32;
+ * }
+ * ```
  */
 export type TypeChangedFromDecorator = (context: DecoratorContext, target: ModelProperty, version: EnumMember, oldType: Type) => DecoratorValidatorCallbacks | void;
 /**
- * Identifies when the target type changed.
+ * Declares that the return type of an operation has changed starting at a given version,
+ * while keeping earlier versions consistent with the previous return type.
+ *
+ * This decorator is used to track return type changes across API versions. When applied,
+ * the operation will return `oldType` in versions before the specified `version`,
+ * and the current return type definition in the specified version and later.
  *
- * @param version The version that the target type changed in.
- * @param oldType The previous type of the target.
+ * @param version The version when the return type change takes effect. The new return type applies
+ * from this version onwards, while the old return type applies to earlier versions.
+ * @param oldType The previous return type used before the specified version.
+ * @example
+ * ```tsp
+ * // In v1: returns a string
+ * // In v2+: returns an int32
+ * @returnTypeChangedFrom(Versions.v2, string)
+ * op getUserId(): int32;
+ * ```
  */
 export type ReturnTypeChangedFromDecorator = (context: DecoratorContext, target: Operation, version: EnumMember, oldType: Type) => DecoratorValidatorCallbacks | void;
 export type TypeSpecVersioningDecorators = {

package/dist/generated-defs/TypeSpec.Versioning.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TypeSpec.Versioning.d.ts","sourceRoot":"","sources":["../../generated-defs/TypeSpec.Versioning.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"TypeSpec.Versioning.d.ts","sourceRoot":"","sources":["../../generated-defs/TypeSpec.Versioning.ts"],"names":[],"mappings":"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"}

package/lib/decorators.tsp

@@ -178,15 +178,49 @@ extern dec madeOptional(target: ModelProperty, version: EnumMember);
 extern dec madeRequired(target: ModelProperty, version: EnumMember);
 
 /**
- * Identifies when the target type changed.
- * @param version The version that the target type changed in.
- * @param oldType The previous type of the target.
+ * Declares that the type of a model property has changed starting at a given version,
+ * while keeping earlier versions consistent with the previous type.
+ *
+ * This decorator is used to track type changes across API versions. When applied,
+ * the property will use `oldType` in versions before the specified `version`,
+ * and the current type definition in the specified version and later.
+ *
+ * @param version The version when the type change takes effect. The new type applies
+ *                from this version onwards, while the old type applies to earlier versions.
+ * @param oldType The previous type used before the specified version.
+ *
+ * @example
+ *
+ * ```tsp
+ * model Foo {
+ *   // In v1: id is a string
+ *   // In v2+: id is an int32
+ *   @typeChangedFrom(Versions.v2, string)
+ *   id: int32;
+ * }
+ * ```
  */
 extern dec typeChangedFrom(target: ModelProperty, version: EnumMember, oldType: unknown);
 
 /**
- * Identifies when the target type changed.
- * @param version The version that the target type changed in.
- * @param oldType The previous type of the target.
+ * Declares that the return type of an operation has changed starting at a given version,
+ * while keeping earlier versions consistent with the previous return type.
+ *
+ * This decorator is used to track return type changes across API versions. When applied,
+ * the operation will return `oldType` in versions before the specified `version`,
+ * and the current return type definition in the specified version and later.
+ *
+ * @param version The version when the return type change takes effect. The new return type applies
+ *                from this version onwards, while the old return type applies to earlier versions.
+ * @param oldType The previous return type used before the specified version.
+ *
+ * @example
+ *
+ * ```tsp
+ * // In v1: returns a string
+ * // In v2+: returns an int32
+ * @returnTypeChangedFrom(Versions.v2, string)
+ * op getUserId(): int32;
+ * ```
  */
 extern dec returnTypeChangedFrom(target: Operation, version: EnumMember, oldType: unknown);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typespec/versioning",
-  "version": "0.79.0-dev.3",
+  "version": "0.79.0-dev.4",
   "author": "Microsoft Corporation",
   "description": "TypeSpec library for declaring and emitting versioned APIs",
   "homepage": "https://typespec.io",