0.58 - July 2024

warning

This release contains breaking changes

Examples in TypeSpec

This release introduce a new @example and @opExample decorator.

Those new decorators provide a way to specify some canonical examples for data types and operations. Each emitter is then able to serialize those examples in their own format.

@example(#{
  id: "some",
  date: utcDateTime.fromISO("2020-01-01T00:00:00Z"),
  timeout: duration.fromISO("PT1M"),
})
model Foo {
  id: string;
  date: utcDateTime;
  @encode("seconds", int32) timeout: duration;
}

@opExample(
  #{
    parameters: #{ pet: #{ id: "some", name: "Fluffy", dob: plainDate.fromISO("2020-01-01") } },
    returnType: #{ id: "some", name: "Fluffy", dob: plainDate.fromISO("2020-01-01") },
  },
  #{ title: "First", description: "Show creating a pet" }
)
op createPet(pet: Pet): Pet;

Breaking Changes

@typespec/compiler

• #3793 Do not carry over @friendlyName with model is or op is

  @friendlyName("Abc{T}", T)
  model Foo<T> {}
  
  model Bar is Foo<string>;
  
  // This can be changed to
  model Abcstring is Foo<string>;

• #3659 Disallows overriding a required inherited property with an optional property.

In previous versions of TypeSpec, it was possible to override a required property with an optional property. This is no longer allowed. This change may result in errors in your code if you were relying on this bug, but specifications that used this behavior are likely to have been exposed to errors resulting from incoherent type checking behavior.

The following example demonstrates the behavior that is no longer allowed:

model Base {
  example: string;
}

model Child extends Base {
  example?: string;
}

In this example, the Child model overrides the example property from the Base model with an optional property. This is no longer allowed.

@typespec/http

• #3737 Keep trailing slash when building http routes, this is breaking if you used to have @route() ending with /.

  TypeSpec	Before	After
  @route("users/")	users	users/
  @route("users")	users	users
  on interface @route("users/") and on op @route("addresses/")	users/addresses	users/addresses/
  on interface @route("users/") and on op @route("addresses")	users/addresses	users/addresses

Features

@typespec/compiler

• #3699 Moved compiler dependencies to peer and dev for scaffolded projects.

• 59daf90 Add new @example and @opExample decorator to provide examples on types and operations.

  @example(#{
    id: "some",
    date: utcDateTime.fromISO("2020-01-01T00:00:00Z"),
    timeout: duration.fromISO("PT1M"),
  })
  model Foo {
    id: string;
    date: utcDateTime;
    @encode("seconds", int32) timeout: duration;
  }

  @opExample(
    #{
      parameters: #{ pet: #{ id: "some", name: "Fluffy", dob: plainDate.fromISO("2020-01-01") } },
      returnType: #{ id: "some", name: "Fluffy", dob: plainDate.fromISO("2020-01-01") },
    },
    #{ title: "First", description: "Show creating a pet" }
  )
  op createPet(pet: Pet): Pet;

• #3751 Adds option to tsp init to generate .gitignore file

@typespec/http

• #3717 Allow overriding base operation verb
• #3676 Expose getHttpPart and types functions
• #3732 Expose model property on HttpAuth to retrieve original type used to define security scheme

@typespec/openapi

• #3626 Adds public function for setting info object

@typespec/openapi3

• bd0b3df Add support for new @example and @opExample decorator
• #3663 Adds support for converting OpenAPI3 specs to TypeSpec via the new tsp-openapi3 CLI included in the @typespec/openapi3 package.
• #3732 Apply openapi3 extension on Security schemes

@typespec/html-program-viewer

• #3713 Complete new dynamic UI to navigate the TypeSpec type graph

Bug Fixes

@typespec/compiler

• #3623 Fix crash of language server on firefox
• #3516 Deprecate getAssetEmitter and recommend calling createAssetEmitter directly
• #3767 Fix semantic highlighting of using of single namespace
• #3824 Do not cast model expression to object value if the constraint is allowing the type
• #3577 Fix formatting of object and array literal in decorator to hug parenthesis
• #3823 Fix formatting of scalar constructor called with no args
• #3743 Fix 'typespec vs install' command on windows
• #3605 Fix templates initialized on node 22

@typespec/openapi3

• #3516 Fix issue that could result in invalid document generation when running tsp compile from another directory
• #3794 Updates tsp-openapi3 to always emit main.tsp when formatting encounters an error.
• #3839 Updates tsp-openapi3 doc line wrapping to only automatically create newlines when they are present in the original documentation.

@typespec/html-program-viewer

• #3585 Fix crash in program viewer when trying to display new value type

@typespec/json-schema

• #3516 Fix issue that could result in invalid document generation when running tsp compile from another directory