@cadl-lang/versioning
library
This package provide Cadl decorators and projections to define versioning in a service.
Install
Run the following command in your cadl project root directory.
npm install @cadl-lang/versioning
Usage
import "@cadl-lang/versioning";
using Versioning;
Enable versioning for Service or Library
Use @versioned
decorator to mark a namespace as versioned.
@versioned(Versions)
namespace MyService;
enum Versions {
v1,
v2,
v3,
}
The following decorators can then be used to provide version evolution of a service.
Consume a versioned library
When consuming a versioned library, it is required to indicate which version of the library to use.
See @versionedDependency
decorator for information about this.
References
Decorators:
@versioned
Mark a namespace as being versioned. It takes as an argument an enum
of versions for that namespace.
@versioned(Versions)
namespace MyService;
enum Versions {
v1,
v2,
v3,
}
@useDependency
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.
The decorator can either target:
- an unversioned namespace.
- individual enum members of a versioned namespace's version enum.
If we have a library with the following definition:
@versioned(Versions)
namespace MyLib;
enum Versions {
v1,
v1_1,
v2,
}
Pick a specific version to be used for all version of the service.
@versioned(Versions)
@useDependency(MyLib.Versions.v1_1)
namespace MyService1;
enum Version {
v1,
v2,
v3,
}
Service is not versioned, pick which version of MyLib
should be used.
@useDependency(MyLib.Versions.v1_1)
namespace NonVersionedService;
Select mapping of version to use
@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,
}
@added
Specify which version an entity was added. Take the enum version member.
Version enum member MUST be from the version enum for the containing namespace.
@added(Versions.v2)
op addedInV2(): void;
@added(Versions.v2)
model AlsoAddedInV2 {}
model Foo {
name: string;
@added(Versions.v3)
addedInV3: string;
}
@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.
@removed(Versions.v2)
op removedInV2(): void;
@removed(Versions.v2)
model AlsoRemovedInV2 {}
model Foo {
name: string;
@removed(Versions.v3)
removedInV3: string;
}
@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.
@renamedFrom(Versions.v2, "oldName")
op newName(): void;
@madeOptional
Specify which version a property was made optional
Version enum member MUST be from the version enum for the containing namespace.
model Foo {
name: string;
@madeOptional(Versions.v2)
nickname: string;
}
Consuming versioning library from an emitter
Get the service representation at a given version
Versioning library works with projection to project the service at a given version.
// Get a list of all the different version of the service and the projections
const projections = buildVersionProjections(program, serviceNamespace);
for (const projection of projections) {
const projectedProgram = projectProgram(program, projection.projections);
// projectedProgram now contains the representation of the service at the given version.
}
Get list of versions and version dependency across namespaces
Versioning library works with projection to project the service at a given version.
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.
Consume versioning manually
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:
getAddedOn
getRemovedOn
getRenamedFromVersion
getMadeOptionalOn