typespec-stable@1.18.0

@typespec/compiler

Deprecations

• #11980 getDiscriminatedUnionFromInheritance(type, discriminator) is deprecated. Pass the program as the first argument so enum member discriminator values use their @encodedName.

  const [union, diagnostics] = getDiscriminatedUnionFromInheritance(program, type, discriminator);

Features

• #12095 Inspect inline suppressions and local linter disables without compiling a project. Inline results include declaration context and source locations; config results include rule-key locations and diagnostics. For compiled programs, inspect whether each project suppression matched a diagnostic using getSuppressions.

  import { collectLinterDisables } from "@typespec/compiler";
  import { collectSuppressions, getSuppressions, parse } from "@typespec/compiler/ast";
  
  const script = parse(source);
  const suppressions = collectSuppressions(script);
  const [disables, diagnostics] = collectLinterDisables(configText);
  const observedSuppressions = getSuppressions(program); // Includes a `used` flag.

  Usage is a snapshot of diagnostics matched so far in that compilation, including rejected attempts to suppress errors. An unmatched suppression may be needed under other settings: its rule could be disabled, its diagnostic source unavailable, its emitter skipped, or compilation could stop before the relevant stage runs.

• #12195 Override linter configuration for a single compilation without editing tspconfig.yaml. Select rulesets with --linter-ruleset, enable, disable, or configure individual rules with --linter-rule, and skip linting with --no-linter.

  tsp compile . --linter-ruleset @typespec/http/all
  tsp compile . --linter-rule @typespec/compiler/unused-using=true
  tsp compile . --no-linter

• #12166 Expose skipTrivia through @typespec/compiler/ast so codefixes can reuse the compiler whitespace and comment handling.

  import { skipTrivia } from "@typespec/compiler/ast";
  
  const cursor = skipTrivia(sourceText, property.end, property.parent?.end);

• #12461 Add typeref(Type) for referencing types from metadata values. Enable the typeref compiler feature in the calling project or library's tspconfig.yaml. Its result has type TypeRef<T>, where T is the referenced type. Use TypeRef to accept any type reference, or TypeRef<T> to constrain its target. JavaScript implementations and generated signatures use TypeRefValue from @typespec/compiler, whose target is the referenced compiler type. Type references are compilation metadata and cannot be represented as JSON values.

  model Item { id: string; }
  model Registration { name: string; type: TypeRef; }
  const entry: Registration = #{ name: "item", type: typeref(Item) };

• #12399 [API] Widen isTemplateDeclaration and isTemplateDeclarationOrInstance to accept any Type.

Bug Fixes

• #12314 Suppress deprecated type warnings in deprecated operations, including parameter and response types nested in inline models and template arguments.

• #12225 Preserve source model and property documentation in generated extern signatures.

• #11980 @encodedName on an enum member now sets the value the member is serialized as, including when it has an explicit value. Emitters can resolve it with resolveEncodedEnumMemberValue. A spec that relied on the encoded name being ignored can now report errors, such as an encoded name equal to another member's value, or a @discriminated union variant named after the member instead of its encoded name.

  enum ConversationStatus {
    // Keeps 0 for protobuf, serialized as "unknown" in JSON
    @encodedName("application/json", "unknown")
    CONVERSATION_STATUS_UNSPECIFIED: 0,
  }

• #12323 Fix the underline in the diagnostic source preview starting one character to the right of the target since the upgrade to @babel/code-frame 8.

• #12202 Highlight type-reference names without their template arguments when reporting diagnostics.

• #12358 Fix decorators being skipped when concrete types are first referenced from template declarations, including references through model properties, union variants, and enum members.

• #12204 Recommend npm run build instead of tsp compile . after initializing a TypeSpec library or emitter.

• #12180 Fix enumMember and exitEnumMember semantic navigation callbacks so linter rules can validate enum members. Scoped navigation uses the parent enum's namespace to avoid visiting members outside the requested scope.

• #12203 Explain that createTester requires a library root directory when its package.json cannot be found.

• #12461 Correct reflection type constraint comparisons in function signatures, template parameters, and type references so namespace and other non-model constraints are not accepted as model constraints.

@typespec/http

Bug Fixes

• #12225 Preserve source model and property documentation in generated extern signatures.
• #12087 Improve HTTP payload resolution performance for models with many properties by avoiding repeated metadata scans.

@typespec/openapi

Bug Fixes

• #12225 Preserve source model and property documentation in generated extern signatures.

@typespec/openapi3

Features

• #12461 Add typeref(Type) for referencing types from metadata values. Enable the typeref compiler feature in the calling project or library's tspconfig.yaml. Its result has type TypeRef<T>, where T is the referenced type. Use TypeRef to accept any type reference, or TypeRef<T> to constrain its target. JavaScript implementations and generated signatures use TypeRefValue from @typespec/compiler, whose target is the referenced compiler type. Type references are compilation metadata and cannot be represented as JSON values.

  model Item { id: string; }
  model Registration { name: string; type: TypeRef; }
  const entry: Registration = #{ name: "item", type: typeref(Item) };

Bug Fixes

• #11980 Enum members use their application/json @encodedName as their value, including in a server variable; an encoded integer member is emitted as a string.
• #12300 Reduce the visibility context of array declarations so that named array models are not incorrectly emitted with an Item suffix.
• #12368 Deduplicate identical summaries and descriptions across @sharedRoute operations.
• #12092 [converter] Escape quotes in the @service title generated from the OpenAPI info.title.
• #12021 Fix @terminalEvent on a variant with a payload emitting an unconstrained oneOf branch in OpenAPI 3.2 SSE output
• #11990 Preserve distinct discriminated union envelopes when variants share the same payload type.
• #12165 Emit minItems and maxItems for tuple types so generated schemas enforce the tuple's exact length.

@typespec/json-schema

Features

• #12461 Add typeref(Type) for referencing types from metadata values. Enable the typeref compiler feature in the calling project or library's tspconfig.yaml. Its result has type TypeRef<T>, where T is the referenced type. Use TypeRef to accept any type reference, or TypeRef<T> to constrain its target. JavaScript implementations and generated signatures use TypeRefValue from @typespec/compiler, whose target is the referenced compiler type. Type references are compilation metadata and cannot be represented as JSON values.

  model Item { id: string; }
  model Registration { name: string; type: TypeRef; }
  const entry: Registration = #{ name: "item", type: typeref(Item) };

Bug Fixes

• #11980 Enum members use their application/json @encodedName as their value, including members with an explicit value. An encoded integer member is emitted as a string.
• #12330 Report a diagnostic instead of crashing when @prefixItems receives an array type rather than a tuple.

typespec-vscode

No changes, version bump only.

@typespec/prettier-plugin-typespec

No changes, version bump only.

@typespec/xml@0.88.0

No changes, version bump only.

@typespec/versioning@0.88.0

Bug Fixes

• #11968 Preserve transformed property optionality in version snapshots and skip incompatible optionality diagnostics when the property differs from its original declaration, without special-casing transformation helpers.

@typespec/tspd@0.78.0

Features

• #12461 Add typeref(Type) for referencing types from metadata values. Enable the typeref compiler feature in the calling project or library's tspconfig.yaml. Its result has type TypeRef<T>, where T is the referenced type. Use TypeRef to accept any type reference, or TypeRef<T> to constrain its target. JavaScript implementations and generated signatures use TypeRefValue from @typespec/compiler, whose target is the referenced compiler type. Type references are compilation metadata and cannot be represented as JSON values.

  model Item { id: string; }
  model Registration { name: string; type: TypeRef; }
  const entry: Registration = #{ name: "item", type: typeref(Item) };

Bug Fixes

• #12225 Preserve source model and property documentation in generated extern signatures.
• #12435 Mark generated Typekit reference pages as JavaScript APIs so scoped website search includes them in api: searches instead of default documentation searches.
• #12169 Render line breaks in wrapped typekit documentation as whitespace instead of leaking TSDoc node names.

@typespec/streams@0.88.0

No changes, version bump only.

@typespec/sse@0.88.0

No changes, version bump only.

@typespec/rest@0.88.0

No changes, version bump only.

@typespec/protobuf@0.88.0

Features

• #12131 Add LongRunningOperation<Response, Metadata> for long-running operations (AIP-151), and WellKnown.Operation. An operation that returns LongRunningOperation returns a google.longrunning.Operation, and the emitter writes its response and metadata types in the method's google.longrunning.operation_info option.

  importBooks(...ImportBooksRequest): LongRunningOperation<ImportBooksResponse, ImportBooksMetadata>;

  rpc ImportBooks(ImportBooksRequest) returns (google.longrunning.Operation) {
    option (google.longrunning.operation_info) = {
      response_type: "ImportBooksResponse"
      metadata_type: "ImportBooksMetadata"
    };
  }

Bug Fixes

• #12191 An object value, such as an @opExample or const value, can now fill a Map<Key, Value>: Map is a Record of its values. The emitted map is unchanged.

@typespec/playground@0.19.0

Breaking Changes

• #12200 Move registerMonacoDefaultWorkersForVite from @typespec/playground to @typespec/playground/vite/workers. Update the import path; the registration call is unchanged.

  Custom Vite configurations must exclude @typespec/playground/vite/workers from optimizeDeps. definePlaygroundViteConfig configures this automatically.

Bug Fixes

• #12201 Highlight folders containing changed output files in the playground, including collapsed ancestor folders.
• #12200 Resolve Monaco worker assets through the consuming Vite application so published playground packages work under custom base paths.

@typespec/library-linter@0.88.0

No changes, version bump only.