For a TypeSpec beginner, it may be difficult to understand how to
configure or format tspconfig.yaml to tweak the different options
available. Adding a basic example should help folks get started.
Related to #3336
## Summary
This PR introduces 2 changes:
1. adds a new `setExtension` API on the `@typespec/json-schema` emitter
to make it easier to author custom extension decorators.
2. updates the `@extension` decorator to support taking values to
obviate the need for the `Json<Data>` model.
Example usage of writing a custom extension `@added` decorator:
```js
export function $added(context, target, value) {
setExtension(context.program, target, "x-added", value);
}
```
Example usage of passing in value literals to `@extension` decorator:
```tsp
@extension("x-current", Json<["foo"]>)
@extension("x-new", #["foo"])
model Foo {}
```
## Background
The `@typespec/json-schema` package exports an `@extension` decorator
that allows customers to specify additional properties to be present as
part of their emitted JSON schema.
For example, we can add a property - converted to a schema - that
indicates when a field was added to the model:
```tsp
@jsonSchema
model Pet {
@extension("x-added", "2024-01-01")
name: string;
}
```
The decorator also supports emitting the property's value as raw code by
wrapping the parameter in the `Json<Data>` template:
```tsp
@jsonSchema
model Pet {
@extension("x-added", Json<"2024-01-01">)
name: string;
}
```
### Comparison
Below is a diff between the two ways of calling the decorator for
clarity:
```diff
$schema: https://json-schema.org/draft/2020-12/schema
$id: Pet.yaml
type: object
properties:
name:
type: string
- x-added:
- type: string
- const: 2024-01-01
+ x-added: 2024-01-01
required:
- name
```
## Pain Points
Currently, `@extension` only supports raw values by wrapping them with
the `TypeSpec.JsonSchema.Json` template. Since this type isn't available
in JS code, this forces authors to manually create the wrapped type
themselves, e.g.:
```js
/**
* @param {import("@typespec/compiler").DecoratorContext} context
* @param {import("@typespec/compiler").Type} target
* @param {import("@typespec/compiler").StringLiteral} value
*/
export function $added(context, target, value) {
$extension(context, target, "x-added", {
kind: "Model",
name: "Json",
namespace: { name: "JsonSchema" },
properties: createRekeyableMap([["value", { type: value }]]),
});
}
```
## Update `@extension` to accept values directly and expose
`setExtension` API
This PR exposes a new `setExtension` API that accepts types and values
as input, instead of just `Type`. This also means
`ExtensionRecord.value` has been loosened:
```diff
export interface ExtensionRecord {
key: string;
- value: Type;
+ value: Type | unknown;
}
```
In addition, the `@extension` decorator is updated to support accepting
values directly:
```diff
- extern dec extension(target: unknown, key: valueof string, value: unknown);
+ extern dec extension(target: unknown, key: valueof string, value: unknown | (valueof unknown));
```
While this change introduces breaking changes to the `@extensions`
decorator and `getExtensions` function, it also allows the `@extension`
decorator to support [value
kinds](https://typespec.io/docs/language-basics/values) as input - a
feature language feature introduced in `0.57.0`.
This would not cause additional breaking changes (beyond
`getExtensions`) for users that already use the
`TypeSpec.JsonSchema.Json` template to pass in raw values. However,
there is 1 scenario that would now fail:
1. Scalar literals/null would now be treated as values instead of types.
(e.g. `@extension("x-bool-literal", true)` would need to be updated to
`@extension("x-bool-literal", typeof true)` to preserve current
behavior)
## Alternatives
### Solution - only expose `setExtension` API
This PR exposes a new `setExtension` API that accepts types and values
as input, instead of just `Type`. This also means
`ExtensionRecord.value` has been loosened:
```diff
export interface ExtensionRecord {
key: string;
- value: Type;
+ value: Type | any;
}
```
This does introduce a **breaking change** in the **getExtensions** API
since `ExtensionRecord.value` is no longer guaranteed to be `Type`.
However, it is likely this API is not used much if at all outside of
this emitter.
### Create new `setExtensionValue`/`getExtensionValues` functions and
alternative `@extension` decorator
This change has the benefit of not requiring any breaking changes.
However, we would now have 2 different but very similar APIs for
settings/getting extensions that may lead to confusion, as well as 2
very similar extensions to do essentially the same thing.
---------
Co-authored-by: Christopher Radek <Christopher.Radek@microsoft.com>
This work-in-progress PR tracks merging the JavaScript server code
generator to the TypeSpec repository.
The JavaScript server code generator creates HTTP bindings for TypeSpec
HTTP services and exposes them for binding either to the Node.js http
server directly, or to an Express.js app as middleware.
Closes#3215
---------
Co-authored-by: Will Temple <will@wtemple.net>
fix [#3647](https://github.com/microsoft/typespec/issues/3647)
With node 22 the --test needs a glob to find files to test. As the docs
a written the tests don't run or pass. This fixes it for me.
---------
Co-authored-by: Timothee Guerin <tiguerin@microsoft.com>
fix#3038
This PR updates the `@typespec/openapi3` package to support converting
OpenAPI3 specs to TypeSpec.
## Example usage:
1. `npm install @typespec/openapi3`
2. `npx openapi3-to-tsp compile --output-dir ./tsp-output
/path/to/openapi-yaml-or-json`
## What's supported
- Parse OpenAPI3 specs in yml/json formats (via 3rd party package)
- Generates file namespace based on OpenAPI3 service name
- Populates `@info` decorator with OpenAPI3 service info
- Converts `#/components/schemas` into TypeSpec models/scalars.
- Converts `#/components/parameters` into TypeSpec models/model
properties as appropriate.
- Generates a response model for every operation/statusCode/contentType
combination.
- Operation tags
- Generates TypeSpec operations with routes/Http Method decorators
- Generates docs/extension decorators
- Most schema decorators
- Model inheritance via `allOf`
- Discriminators
## What's not supported (yet)
- auth
- deprecated directive
- combining multiple versions of an OpenAPI3-defined service into a
single TypeSpec project
- converting `#/components/requestBodies` and `#/components/responses`
into models - TypeSpec doesn't seem to generate these and I didn't find
examples in the wild where they were defined _and_ actually used so
deprioritized.
- emitting warnings/FIXMEs for unexpected/unsupported scenarios
- Probably a lot more that I'm still discovering
## Notes
When going through the TypeSpec -> OpenAPI3 -> TypeSpec loop, the
generated TypeSpec is going to be larger than the original. The biggest
contribution towards this is because I'm currently generating a model
for every possible response on every operation.
I can definitely pare this down with some simple heuristics that take
into account what default statusCode/contentTypes are, and extract the
referenced body type directly in the operation's return signature. I can
also eliminate the `@get` decorators, `@route("/")` routes, and likely
use some of the response models provided by TypeSpec.Http.
However - if I'm using this tool to convert from OpenAPI3 to TypeSpec -
I thought it might be preferable to be more explicit in the generated
output so there's no mystery on how things actually get defined. Will be
interested in feedback on this.
## Testing
For tests, I generate TypeSpec files for a number of OpenAPI3 specs.
Most of the OpenAPI3 specs I generated from our TypeSpec samples
packages. Then I'm able to compare the generated TypeSpec to the
corresponding original TypeSpec file. I've also been diffing the
OpenAPI3 specs generated from the original and generated TypeSpec files
<- these are what typically show no changes outside of known unsupported
conversions (e.g. auth).
---------
Co-authored-by: Christopher Radek <Christopher.Radek@microsoft.com>
fix #1016
Format multi lines string
```
@doc(
"""
multi line
do
${"abc"}
"""
)
@doc("""
def
""")
model Foo {}
alias T = """
abc
def ${"abc"}
ghi
""";
```
formats to
```
@doc("""
multi line
do
${"abc"}
""")
@doc("""
def
""")
model Foo {}
alias T = """
abc
def ${"abc"}
ghi
""";
```
resolve#3046
[Playground](https://cadlplayground.z22.web.core.windows.net/prs/3342/)
Add the following:
- `@multipartBody` decorator
- `File` type
- `HttpPart<Type, Options>` type
Had to do a decent amount of refactoring to be able to reuse the body
parsing, this result in a much cleaner resolution of the body and other
metadata properties across request, response and metadata.
The way it works now is instead of calling `gatherMetadata` that would
just get the properties that are metadata but also ones with `@body` and
`@bodyRoot` we now call a `resolveHtpProperties`, this does the same
resolution in term of filtering properties but it also figure out what
is the kind of property in the concept of http(header, query, body,
etc.) this leaves the error resolution to this function for duplicate
annotations.
What is nice is now we don't need to keep asking oh is this a query or a
header or a body we can just check the kind of `HttpProperty`
also resolve#1311
## Issue Description
There is a example of `TypeSpec.http.@statusCode`
[here](https://typespec.io/docs/next/libraries/http/reference/decorators#@TypeSpec.Http.statusCode).
However, the property name is missing in this example. Due to this, the
code did not work as expected.
```
op read(): {@statusCode: 200, @body pet: Pet}
op create(): {@statusCode: 201 | 202}
```
Instead, specifying the property name as follows made it work correctly:
```
op read(): {
@statusCode _: 200;
@body pet: Widget;
};
op create(): {
@statusCode _: 201 | 202;
};
```
## Fix Description
- Corrected examples of `TypeSpec.http.@statusCode` in the reference and
documentation.
---------
Co-authored-by: Timothee Guerin <tiguerin@microsoft.com>
Co-authored-by: Timothee Guerin <timothee.guerin@outlook.com>
Co-authored-by: Mark Cowlishaw <markcowl@microsoft.com>
Fixes#3369 by changing how types are bundled. In particular, when a
type is not a JSON Schema type, we never create a root schema for it.
Instead, it is inlined into the defs of any schema which references it,
and referenced using a JSON pointer. This PR makes bundling have
essentially no impact on emitted schemas, and is merely a way to bundle
them into a single file.
The approach is as follows:
* When a type references another type outside a JSON Schema namespace,
include the referenced type under $defs:
* Such referenced types do not have a $id or $schema field
* Such referenced types are referenced via JSON pointers not ids
* Bundling does not alter the bundled schemas or introduce new root
schemas. This changes two things from what we do today:
* The `$id` of the bundled schemas now includes the file path as it does
for non-bundled schemas (whereas before it was just the type name)
* non-JSON Schema types do not get $defs in the bundle, so the bundle
has the same root schemas as would be written to disk when not bundling.
In terms of implementation, the basic approach is to not handle bundling
via the emitter framework source files. Instead, we always create source
files for root schemas, and inline the necessary defs as we did before
(but now using JSON pointers). Then when we're about to write source
files, if we're bundling we assemble the bundle and emit that single
file, otherwise we emit each source file that contains a root schema.
Todo:
* [ ] Validate that the bundled schemas continue to work with ajv.
* [ ] Cleanups
---------
Co-authored-by: Vitalii Kryvenko <gersoh3@gmail.com>
Fixes#3370.
This also updates the generated documentation and typescript code to fix
lack of indentation on existing fenced blocks in this repo.
---------
Co-authored-by: Timothee Guerin <timothee.guerin@outlook.com>
Hopefully I got all the places I needed to get and added enough tests.
My methodology was pretty much "Look at what madeOptional does, and do
the opposite"
Closes#2731
---------
Co-authored-by: Timothee Guerin <tiguerin@microsoft.com>
Co-authored-by: Timothee Guerin <timothee.guerin@outlook.com>
resolves#2046
[Playround](https://cadlplayground.z22.web.core.windows.net/prs/3022/)
Add the new syntax for object literals using `#{`. For this first
version an object literal can only contain other object literal and
other literals(string, number, boolean))
## Values axioms
1. `alias` always produces a type. If you attempt to alias a value, you
get an error.
2. A string template produces a string template type if all
substitutions are types, and a value if all substitutions are numeric,
boolean, or string values. A mixture of types and values is an error.
3. The string literal syntax always results in a string literal type
4. A string literal type may be passed as a string value when the
signature expects a value. When the signature expects either a string
literal type or a string value, it is passed as a string value.
5. A string template type can be passed as a string value when all its
substitutions are string literal types.
## Breaking change
### Removal of the `ValueType` replacement with `MixedConstraint`
This shouldn't affect anyone as you were only exposed to this if you
digged into the template parameter and looked at the constraint
## Deprecation
## Using a tuple instead of a tuple literal
- ✅ still work
- emit a warning
<img width="1013" alt="image"
src="https://github.com/microsoft/typespec/assets/1031227/ab05359a-5ed9-4a27-a8d1-f40d1e21766f">
- provide a codefix
<img width="312" alt="image"
src="https://github.com/microsoft/typespec/assets/1031227/5ef93bdf-665f-4445-a6b2-62475efe8c16">
## Using a model expression instead of an object literal
This technically didn't work before(different from above where tuple was
used as a value) but allow this will allow us to convert most of our
decorators to use `valueof` without being breaking
## Old decorator marshalling
If a library had a decorator with `valueof` one of those types
`numeric`, `int64`, `uint64`, `integer`, `float`, `decimal`,
`decimal128`, `null` it used to marshall those as JS `number` and
`NullType` for `null`. With the introduction of values we have a new
marshalling logic which will marshall those numeric types as `Numeric`
and the others will remain numbers. `null` will also get marshalled as
`null`.
For now this is an opt-in behavior with a warning on decorators not
opt-in having a parameter with a constraint from the list above.
Example:
```
extern dec multipleOf(target: numeric | Reflection.ModelProperty, value: valueof numeric);
```
Will now emit a deprecated warning because `value` is of type `valueof
string` which would marshall to `Numeric` under the new logic but as
`number` previously.
To opt-in you can add the following to your library
```ts
export const $flags = defineModuleFlags({
decoratorArgMarshalling: "value",
});
```
---------
Co-authored-by: Brian Terlson <brian.terlson@microsoft.com>
Co-authored-by: Mark Cowlishaw <markcowl@microsoft.com>
## Backgrounds
I first reported this on discussion: #3194
## Issue description
There is a code sample
[here](https://typespec.io/docs/language-basics/namespaces#using-namespaces)
describing the scope of an item introduced by `using`.
```ts
namespace One {
model A {}
}
namespace Two {
using One;
alias B = A; // This is valid
}
alias C = One.A; // This is not valid
alias C = Two.B; // This is valid
```
## Expected result
The code should failed to compile because of `One.A`.
## Actual result
It compiles without any warning.
## How to fix
It appears that the original intent was to show that accessing an item
introduced with `using` outside the scope of `using` is not possible. In
this code, the 'invalid accessing' is `Two.A`.
## Changes
- change `One.A` to `Two.A`
Timothee Guerin
Christopher Radek
Mario Guerra
Kyle Zhang
Michelle
Greg Poirier
Laurent Mazuel
Will Temple
Sylvain Bruyère
Justin
Brian Terlson
☃ Elliot Shepherd
もっちー
Vitalii Kryvenko
Jim Borden
Abiria