@typespec/versioning 0.47.0-dev.1 → 0.47.0

package/README.md

@@ -1,163 +1,147 @@
-# `@typespec/versioning` library
+# @typespec/versioning
 
-This package provide [TypeSpec](https://github.com/microsoft/typespec) decorators and projections to define versioning in a service.
+TypeSpec library for declaring and emitting versioned APIs
 
 ## Install
 
-Run the following command in your typespec project root directory.
-
 ```bash
 npm install @typespec/versioning
 ```
 
 ## Usage
 
-```typespec
-import "@typespec/versioning";
-
-using Versioning;
-```
+### Consuming versioning library from an emitter
 
-### Enable versioning for Service or Library
+#### Get the service representation at a given version
 
-Use [`@versioned`](#versioned) decorator to mark a namespace as versioned.
+Versioning library works with projection to project the service at a given version.
 
-```typespec
-@versioned(Versions)
-namespace MyService;
+```ts
+// Get a list of all the different version of the service and the projections
+const projections = buildVersionProjections(program, serviceNamespace);
 
-enum Versions {
-  v1,
-  v2,
-  v3,
+for (const projection of projections) {
+  const projectedProgram = projectProgram(program, projection.projections);
+  // projectedProgram now contains the representation of the service at the given version.
 }
 ```
 
-The following decorators can then be used to provide version evolution of a service.
+#### Get list of versions and version dependency across namespaces
+
+Versioning library works with projection to project the service at a given version.
+
+```ts
+const versions = resolveVersions(program, serviceNamespace);
+// versions now contain a list of all the version of the service namespace and what version should all the other dependencies namespace use.
+```
 
-- [`@added`](#added)
-- [`@removed`](#removed)
-- [`@renamedFrom`](#renamedfrom)
-- [`@madeOptional`](#madeoptional)
+#### Consume versioning manually
 
-### Consume a versioned library
+If the emitter needs to have the whole picture of the service evolution across the version then using the decorator accessor will provide the metadata for each type:
 
-When consuming a versioned library, it is required to indicate which version of the library to use.
-See [`@useDependency`](#useDependency) decorator for information about this.
+- `getAddedOn`
+- `getRemovedOn`
+- `getRenamedFromVersion`
+- `getMadeOptionalOn`
 
-## References
+## Decorators
 
-Decorators:
+### TypeSpec.Versioning
 
-- [`@versioned`](#versioned) <!-- no toc -->
-- [`@useDependency`](#usedependency)
-- [`@added`](#added)
-- [`@removed`](#removed)
-- [`@renamedFrom`](#renamedfrom)
-- [`@madeOptional`](#madeoptional)
+- [`@added`](#@added)
+- [`@madeOptional`](#@madeoptional)
+- [`@removed`](#@removed)
+- [`@renamedFrom`](#@renamedfrom)
+- [`@returnTypeChangedFrom`](#@returntypechangedfrom)
+- [`@typeChangedFrom`](#@typechangedfrom)
+- [`@useDependency`](#@usedependency)
+- [`@versioned`](#@versioned)
 
-### `@versioned`
+#### `@added`
 
-Mark a namespace as being versioned. It takes as an argument an `enum` of versions for that namespace.
+Identifies when the target was added.
 
 ```typespec
-@versioned(Versions)
-namespace MyService;
-
-enum Versions {
-  v1,
-  v2,
-  v3,
-}
+@TypeSpec.Versioning.added(version: EnumMember)
 ```
 
-### `@useDependency`
+##### Target
 
-When using elements from another versioned namespace, the consuming namespace **MUST** specify which version of the consumed namespace to use even if the consuming namespace is not versioned itself.
+`(intrinsic) unknown`
 
-The decorator can either target:
+##### Parameters
 
-- an unversioned namespace.
-- individual enum members of a versioned namespace's version enum.
+| Name    | Type         | Description                               |
+| ------- | ------------ | ----------------------------------------- |
+| version | `EnumMember` | The version that the target was added in. |
 
-If we have a library with the following definition:
+##### Examples
 
-```typespec
-@versioned(Versions)
-namespace MyLib;
-
-enum Versions {
-  v1,
-  v1_1,
-  v2,
-}
-```
+```tsp
+@added(Versions.v2)
+op addedInV2(): void;
 
-Pick a specific version to be used for all version of the service.
+@added(Versions.v2)
+model AlsoAddedInV2 {}
 
-```typespec
-@versioned(Versions)
-@useDependency(MyLib.Versions.v1_1)
-namespace MyService1;
+model Foo {
+  name: string;
 
-enum Version {
-  v1,
-  v2,
-  v3,
+  @added(Versions.v3)
+  addedInV3: string;
 }
 ```
 
-Service is not versioned, pick which version of `MyLib` should be used.
-
-```typespec
-@useDependency(MyLib.Versions.v1_1)
-namespace NonVersionedService;
-```
+#### `@madeOptional`
 
-Select mapping of version to use
+Identifies when a target was made optional.
 
 ```typespec
-@versioned(Versions)
-namespace MyService1;
-
-enum Version {
-  @useDependency(MyLib.Versions.v1_1) // V1 use lib v1_1
-  v1,
-  @useDependency(MyLib.Versions.v1_1) // V2 use lib v1_1
-  v2,
-  @useDependency(MyLib.Versions.v2) // V3 use lib v2
-  v3,
-}
+@TypeSpec.Versioning.madeOptional(version: EnumMember)
 ```
 
-### `@added`
+##### Target
 
-Specify which version an entity was added. Take the enum version member.
+`(intrinsic) unknown`
 
-Version enum member **MUST** be from the version enum for the containing namespace.
+##### Parameters
 
-```typespec
-@added(Versions.v2)
-op addedInV2(): void;
+| Name    | Type         | Description                                       |
+| ------- | ------------ | ------------------------------------------------- |
+| version | `EnumMember` | The version that the target was made optional in. |
 
-@added(Versions.v2)
-model AlsoAddedInV2 {}
+##### Examples
 
+```tsp
 model Foo {
   name: string;
 
-  @added(Versions.v3)
-  addedInV3: string;
+  @madeOptional(Versions.v2)
+  nickname: string;
 }
 ```
 
-### `@removed`
+#### `@removed`
 
-Specify which version an entity was removed. Take the enum version member.
-
-Version enum member **MUST** be from the version enum for the containing namespace.
+Identifies when the target was removed.
 
 ```typespec
+@TypeSpec.Versioning.removed(version: EnumMember)
+```
+
+##### Target
+
+`(intrinsic) unknown`
+
+##### Parameters
+
+| Name    | Type         | Description                                 |
+| ------- | ------------ | ------------------------------------------- |
+| version | `EnumMember` | The version that the target was removed in. |
+
+##### Examples
+
+```tsp
 @removed(Versions.v2)
 op removedInV2(): void;
 
@@ -172,62 +156,138 @@ model Foo {
 }
 ```
 
-### `@renamedFrom`
+#### `@renamedFrom`
 
-Specify which version an entity was renamed and what is is old name.
-
-Version enum member **MUST** be from the version enum for the containing namespace.
+Identifies when the target has been renamed.
 
 ```typespec
+@TypeSpec.Versioning.renamedFrom(version: EnumMember, oldName: valueof string)
+```
+
+##### Target
+
+`(intrinsic) unknown`
+
+##### Parameters
+
+| Name    | Type                    | Description                                 |
+| ------- | ----------------------- | ------------------------------------------- |
+| version | `EnumMember`            | The version that the target was renamed in. |
+| oldName | `valueof scalar string` | The previous name of the target.            |
+
+##### Examples
+
+```tsp
 @renamedFrom(Versions.v2, "oldName")
 op newName(): void;
 ```
 
-### `@madeOptional`
+#### `@returnTypeChangedFrom`
+
+Identifies when the target type changed.
+
+```typespec
+@TypeSpec.Versioning.returnTypeChangedFrom(version: EnumMember, oldType: unknown)
+```
+
+##### Target
+
+`Operation`
+
+##### Parameters
+
+| Name    | Type                  | Description                                  |
+| ------- | --------------------- | -------------------------------------------- |
+| version | `EnumMember`          | The version that the target type changed in. |
+| oldType | `(intrinsic) unknown` | The previous type of the target.             |
 
-Specify which version a property was made optional
+#### `@typeChangedFrom`
 
-Version enum member **MUST** be from the version enum for the containing namespace.
+Identifies when the target type changed.
 
 ```typespec
-model Foo {
-  name: string;
+@TypeSpec.Versioning.typeChangedFrom(version: EnumMember, oldType: unknown)
+```
 
-  @madeOptional(Versions.v2)
-  nickname: string;
-}
+##### Target
+
+`(intrinsic) unknown`
+
+##### Parameters
+
+| Name    | Type                  | Description                                  |
+| ------- | --------------------- | -------------------------------------------- |
+| version | `EnumMember`          | The version that the target type changed in. |
+| oldType | `(intrinsic) unknown` | The previous type of the target.             |
+
+#### `@useDependency`
+
+Identifies that a namespace or a given versioning enum member relies upon a versioned package.
+
+```typespec
+@TypeSpec.Versioning.useDependency(...versionRecords: EnumMember[])
 ```
 
-## Consuming versioning library from an emitter
+##### Target
 
-### Get the service representation at a given version
+`union EnumMember | Namespace`
 
-Versioning library works with projection to project the service at a given version.
+##### Parameters
 
-```ts
-// Get a list of all the different version of the service and the projections
-const projections = buildVersionProjections(program, serviceNamespace);
+| Name           | Type                 | Description                                                           |
+| -------------- | -------------------- | --------------------------------------------------------------------- |
+| versionRecords | `model EnumMember[]` | The dependent library version(s) for the target namespace or version. |
 
-for (const projection of projections) {
-  const projectedProgram = projectProgram(program, projection.projections);
-  // projectedProgram now contains the representation of the service at the given version.
+##### Examples
+
+###### Select a single version of `MyLib` to use
+
+```tsp
+@useDependency(MyLib.Versions.v1_1)
+namespace NonVersionedService;
+```
+
+###### Select which version of the library match to which version of the service.
+
+```tsp
+@versioned(Versions)
+namespace MyService1;
+enum Version {
+  @useDependency(MyLib.Versions.v1_1) // V1 use lib v1_1
+  v1,
+  @useDependency(MyLib.Versions.v1_1) // V2 use lib v1_1
+  v2,
+  @useDependency(MyLib.Versions.v2) // V3 use lib v2
+  v3,
 }
 ```
 
-### Get list of versions and version dependency across namespaces
+#### `@versioned`
 
-Versioning library works with projection to project the service at a given version.
+Identifies that the decorated namespace is versioned by the provided enum.
 
-```ts
-const versions = resolveVersions(program, serviceNamespace);
-// versions now contain a list of all the version of the service namespace and what version should all the other dependencies namespace use.
+```typespec
+@TypeSpec.Versioning.versioned(versions: Enum)
 ```
 
-### Consume versioning manually
+##### Target
 
-If the emitter needs to have the whole picture of the service evolution across the version then using the decorator accessor will provide the metadata for each type:
+`Namespace`
 
-- `getAddedOn`
-- `getRemovedOn`
-- `getRenamedFromVersion`
-- `getMadeOptionalOn`
+##### Parameters
+
+| Name     | Type   | Description                                     |
+| -------- | ------ | ----------------------------------------------- |
+| versions | `Enum` | The enum that describes the supported versions. |
+
+##### Examples
+
+```tsp
+@versioned(Versions)
+namespace MyService;
+enum Versions {
+  v1,
+  v2,
+  v3,
+}
+```

package/lib/decorators.tsp

@@ -7,24 +7,91 @@ namespace TypeSpec {
     /**
      * Identifies that the decorated namespace is versioned by the provided enum.
      * @param versions The enum that describes the supported versions.
+     *
+     * @example
+     *
+     * ```tsp
+     *  @versioned(Versions)
+     *  namespace MyService;
+     *  enum Versions {
+     *    v1,
+     *    v2,
+     *    v3,
+     *  }
+     * ```
      */
     extern dec versioned(target: Namespace, versions: Enum);
 
     /**
      * Identifies that a namespace or a given versioning enum member relies upon a versioned package.
      * @param versionRecords The dependent library version(s) for the target namespace or version.
+     *
+     * @example Select a single version of `MyLib` to use
+     *
+     * ```tsp
+     * @useDependency(MyLib.Versions.v1_1)
+     * namespace NonVersionedService;
+     * ```
+     *
+     * @example Select which version of the library match to which version of the service.
+     *
+     * ```tsp
+     * @versioned(Versions)
+     * namespace MyService1;
+     * enum Version {
+     *   @useDependency(MyLib.Versions.v1_1) // V1 use lib v1_1
+     *   v1,
+     *   @useDependency(MyLib.Versions.v1_1) // V2 use lib v1_1
+     *   v2,
+     *   @useDependency(MyLib.Versions.v2) // V3 use lib v2
+     *   v3,
+     * }
+     * ```
      */
     extern dec useDependency(target: EnumMember | Namespace, ...versionRecords: EnumMember[]);
 
     /**
      * Identifies when the target was added.
      * @param version The version that the target was added in.
+     *
+     * @example
+     *
+     * ```tsp
+     * @added(Versions.v2)
+     * op addedInV2(): void;
+     *
+     * @added(Versions.v2)
+     * model AlsoAddedInV2 {}
+     *
+     * model Foo {
+     *   name: string;
+     *
+     *   @added(Versions.v3)
+     *   addedInV3: string;
+     * }
+     * ```
      */
     extern dec added(target: unknown, version: EnumMember);
 
     /**
      * Identifies when the target was removed.
      * @param version The version that the target was removed in.
+     *
+     * @example
+     * ```tsp
+     * @removed(Versions.v2)
+     * op removedInV2(): void;
+     *
+     * @removed(Versions.v2)
+     * model AlsoRemovedInV2 {}
+     *
+     * model Foo {
+     *   name: string;
+     *
+     *   @removed(Versions.v3)
+     *   removedInV3: string;
+     * }
+     * ```
      */
     extern dec removed(target: unknown, version: EnumMember);
 
@@ -32,12 +99,28 @@ namespace TypeSpec {
      * Identifies when the target has been renamed.
      * @param version The version that the target was renamed in.
      * @param oldName The previous name of the target.
+     *
+     * @example
+     * ```tsp
+     * @renamedFrom(Versions.v2, "oldName")
+     * op newName(): void;
+     * ```
      */
     extern dec renamedFrom(target: unknown, version: EnumMember, oldName: valueof string);
 
     /**
      * Identifies when a target was made optional.
      * @param version The version that the target was made optional in.
+     *
+     * @example
+     *
+     * ```tsp
+     * model Foo {
+     *   name: string;
+     *   @madeOptional(Versions.v2)
+     *   nickname: string;
+     * }
+     * ```
      */
     extern dec madeOptional(target: unknown, version: EnumMember);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typespec/versioning",
-  "version": "0.47.0-dev.1",
+  "version": "0.47.0",
   "author": "Microsoft Corporation",
   "description": "TypeSpec library for declaring and emitting versioned APIs",
   "homepage": "https://microsoft.github.io/typespec",
@@ -42,16 +42,16 @@
     "!dist/test/**"
   ],
   "peerDependencies": {
-    "@typespec/compiler": "~0.46.0 || >=0.47.0-dev <0.47.0"
+    "@typespec/compiler": "~0.47.0"
   },
   "devDependencies": {
     "@types/mocha": "~10.0.1",
     "@types/node": "~18.11.9",
-    "@typespec/compiler": "~0.46.0 || >=0.47.0-dev <0.47.0",
-    "@typespec/eslint-config-typespec": "~0.46.0 || >=0.47.0-dev <0.47.0",
-    "@typespec/library-linter": "~0.46.0 || >=0.47.0-dev <0.47.0",
-    "@typespec/eslint-plugin": "~0.46.0 || >=0.47.0-dev <0.47.0",
-    "@typespec/tspd": "~0.46.0 || >=0.47.0-dev <0.47.0",
+    "@typespec/compiler": "~0.47.0",
+    "@typespec/eslint-config-typespec": "~0.47.0",
+    "@typespec/library-linter": "~0.47.0",
+    "@typespec/eslint-plugin": "~0.47.0",
+    "@typespec/tspd": "~0.46.0",
     "eslint": "^8.42.0",
     "mocha": "~10.2.0",
     "mocha-junit-reporter": "~2.2.0",
@@ -60,7 +60,6 @@
     "rimraf": "~5.0.1",
     "typescript": "~5.1.3"
   },
-  "dependencies": {},
   "scripts": {
     "clean": "rimraf ./dist ./temp",
     "build": "tsc -p . && npm run lint-typespec-library",