Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

More value docs #9

Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 16 additions & 4 deletions docs/extending-typespec/basics.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ Open `./src/lib.ts` and create your library definition that registers your libra
If `$lib` is not accessible from your library package (for example, `import {$lib} from "my-library";`), some features such as linting and emitter option validation will not be available.
:::

Here's an example:
For example:

```typescript
import { createTypeSpecLibrary } from "@typespec/compiler";
Expand All @@ -122,7 +122,19 @@ export const { reportDiagnostic, createDiagnostic } = $lib;

Diagnostics are used for linters and decorators, which are covered in subsequent topics.

### f. Create `index.ts`
### f. Set package flags

You can optionally set any package flags by exporting a `$flags` const that is initialized with the `definePackageFlags`. Like `$lib`, this value must be exported from your package.

It is strongly recommended to set `valueMarshalling` to `"new"` as this will be the default behavior in future TypeSpec versions.

```typescript
export const $flags = definePackageFlags({
valueMarshalling: "new",
});
```

### g. Create `index.ts`

Open `./src/index.ts` and import your library definition:

Expand All @@ -131,7 +143,7 @@ Open `./src/index.ts` and import your library definition:
export { $lib } from "./lib.js";
```

### g. Build TypeScript
### h. Build TypeScript

TypeSpec can only import JavaScript files, so any changes made to TypeScript sources need to be compiled before they are visible to TypeSpec. To do this, run `npx tsc -p .` in your library's root directory. If you want to re-run the TypeScript compiler whenever files are changed, you can run `npx tsc -p . --watch`.

Expand All @@ -148,7 +160,7 @@ Alternatively, you can add these as scripts in your `package.json` to make them

You can then run `npm run build` or `npm run watch` to build or watch your library.

### h. Add your main TypeSpec file
### i. Add your main TypeSpec file

Open `./lib/main.tsp` and import your JS entrypoint. This ensures that when TypeSpec imports your library, the code to define the library is run. When we add decorators in later topics, this import will ensure those get exposed as well.

Expand Down
70 changes: 38 additions & 32 deletions docs/extending-typespec/create-decorators.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,44 +35,41 @@ using TypeSpec.Reflection;
extern dec track(target: Model | Enum);
```

### Optional parameters
## Optional parameters

You can mark a decorator parameter as optional using `?`.

```typespec
extern dec track(target: Model | Enum, name?: valueof string);
```

### Rest parameters
## Rest parameters

You can prefix the last parameter of a decorator with `...` to collect all the remaining arguments. The type of this parameter must be an `array expression`.

```typespec
extern dec track(target: Model | Enum, ...names: valueof string[]);
```

## Requesting a value type
## Value parameters

It's common for decorator parameters to expect a value (e.g., a string or a number). However, using `: string` as the type would also allow a user of the decorator to pass `string` itself or a custom scalar extending string, as well as a union of strings. Instead, the decorator can use `valueof <T>` to specify that it expects a value of that kind.

| Example | Description |
| ----------------- | ----------------- |
| `valueof string` | Expects a string |
| `valueof float64` | Expects a float |
| `valueof int32` | Expects a number |
| `valueof boolean` | Expects a boolean |
A decorator parameter can receive [values](../language-basics/values.md) by using the `valueof` operator. For example the parameter `valueof string` expects a string value. Values are provided to the decorator implementation according the [decorator parameter marshalling](#decorator-parameter-marshalling) rules.

```tsp
extern dec tag(target: unknown, value: valueof string);

// bad
// error: string is not a value
@tag(string)

// good
@tag("This is the tag name")
// ok, a string literal can be a value
@tag("widgets")

// ok, passing a value from a const
const tagName: string = "widgets";
@tag(tagName)
```

## Implement the decorator in JavaScript
## JavaScript decorator implementation

Decorators can be implemented in JavaScript by prefixing the function name with `$`. A decorator function must have the following parameters:

Expand All @@ -89,7 +86,7 @@ export function $logType(context: DecoratorContext, target: Type, name: valueof
}
```

Or in pure JavaScript:
Or in JavaScript:

```ts
// model.js
Expand All @@ -113,26 +110,35 @@ model Dog {

### Decorator parameter marshalling

For certain TypeSpec types (Literal types), the decorator does not receive the actual type but a marshalled value if the decorator parameter type is a `valueof`. This simplifies the most common cases.
When decorators are passed types, the type is passed as-is. When a decorator is passed a TypeSpec value, the decorator receives a JavaScript value with a type that is appropriate for representing that value.

| TypeSpec Type | Marshalled value in JS |
| ----------------- | ---------------------- |
| `valueof string` | `string` |
| `valueof numeric` | `number` |
| `valueof boolean` | `boolean` |
:::note
This behavior depends on the value of the `valueMarshalling` [package flag](../extending-typespec/basics.md#f-set-package-flags). This section describes the behavior when `valueMarshalling` is set to `"new"`. In a future release this will become the default value marshalling so it is strongly recommended to set this flag. But for now, the default value marshalling is `"legacy"` which is described in the next section. In a future release the `valueMarshalling` flag will need to be set to `"legacy"` to keep the previous marshalling behavior, but the flag will eventually be removed entirely.
:::

For all other types, they are not transformed.
| TypeSpec value type | Marshalled type in JS |
| ------------------- | --------------------------------- |
| `string` | `string` |
| `boolean` | `boolean` |
| `numeric` | `Numeric` or `number` (see below) |
| `null` | `null` |
| enum member | `EnumMemberValue` |

Example:
When marshalling numeric values, either the `Numeric` wrapper type is used, or a `number` is passed directly, depending on whether the value can be represented as a JavaScript number without precision loss. In particular, the types `numeric`, `integer`, `decimal`, `float`, `int64`, `uint64`, and `decimal128` are marshalled as a `Numeric` type. All other numeric types are marshalled as `number`.

```ts
export function $tag(
context: DecoratorContext,
target: Type,
stringArg: string, // Here instead of receiving a `StringLiteral`, the string value is being sent.
modelArg: Model // Model has no special handling so we receive the Model type
) {}
```
When marshalling custom scalar subtypes, the marshalling behavior of the known supertype is used. For example, a `scalar customScalar extends numeric` will marshal as a `Numeric`, regardless of any value constraints that might be present.

#### Legacy value marshalling

With legacy value marshalling, TypeSpec strings, numbers, and booleans values are always marshalled as JS values. All other values are marshalled as their corresponding type. For example, `null` is marshalled as `NullType`.

| TypeSpec Value Type | Marshalled value in JS |
| ------------------- | ---------------------- |
| `string` | `string` |
| `numeric` | `number` |
| `boolean` | `boolean` |

Note that with legacy marshalling, because JavaScript numbers have limited range and precision, it is possible to define values in TypeSpec that cannot be accurately represented in JavaScript.

#### String templates and marshalling

Expand Down
2 changes: 1 addition & 1 deletion docs/language-basics/decorators.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,4 +61,4 @@ model Dog {

## Creating decorators

_For more information on creating decorators, see the [Creating Decorators Documentation](../extending-typespec/create-decorators.md)._
For more information on creating decorators, see [Creating Decorators](../extending-typespec/create-decorators.md).
16 changes: 15 additions & 1 deletion docs/language-basics/scalars.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,23 @@ scalar Password extends string;

## Scalars with template parameters

Scalars can also support template parameters. However, it's important to note that these templates are primarily used for decorators.
Scalars can also support template parameters. These template parameters are primarily used for decorators.

```typespec
@doc(Type)
scalar Unreal<Type extends string>;
```

## Scalar initializers

Scalars can be declared with an initializer for creating specific scalar values based on other values. For example:

```typespec
scalar ipv4 extends string {
init fromInt(value: uint32);
}

const homeIp = ipv4.fromInt(2130706433);
```

Initializers do not have any runtime code associated with them. Instead, they merely record the scalar initializer invoked along with the arguments passed so that emitters can construct the proper value when needed.
42 changes: 42 additions & 0 deletions docs/language-basics/templates.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,3 +108,45 @@ alias Example3 = Test<
Since template arguments can be specified by name, the names of template parameters are part of the template's public API. **Renaming a template parameter may break existing specifications that use the template.**

**Note**: Template arguments are evaluated in the order the parameters are defined in the template _definition_, not the order in which they are written in the template _instance_. While this is usually inconsequential, it may be important in some cases where evaluating a template argument may trigger decorators with side effects.

## Templates with values
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could talk about using typeof here


Templates can be declared to accept values using a `valueof` constraint. This is useful for providing default values and parameters for decorators that take values.

```typespec
alias TakesValue<StringType extends string, StringValue extends valueof string> = {
@doc(StringValue)
property: StringType;
};

alias M1 = TakesValue<"a", "b">;
```

When a passing a literal or an enum or union member reference directly as a template parameter that accepts either a type or a value, we pass the value. In particular, `StringTypeOrValue` is a value with the string literal type `"a"`.

```typespec
alias TakesTypeOrValue<StringTypeOrValue extends string | (valueof string)> = {
@customDecorator(StringOrValue)
property: string;
};

alias M1 = TakesValue<"a">;
```

The [`typeof` operator](./values.md#the-typeof-operator) can be used to get the declared type of a value if needed.

### Template parameter value types

When a template is instantiated with a value, the type of the value and the result of the `typeof` operator is determined based on the argument rather than the template parameter constraint. This follows the same rules as [const declaration type inference](./values.md#const-declarations). In particular, inside the template `TakesValue`, the type of `StringValue` is the string literal type `"b"`. If we passed a `const` instead, the type of the value would be the const's type. In the following example, the type of `property` in `M1` is `"a" | "b"`.

```typespec
alias TakesValue<
StringValue extends valueof string
> = {
@doc(StringValue)
property: typeof StringValue;
};

const str: "a" | "b" = "a";
alias M1 = TakesValue<str>;
```
76 changes: 69 additions & 7 deletions docs/language-basics/values.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,15 @@ title: Values

# Values

TypeSpec can define values in addition to types. Values are useful in an API description to define default values for types or provide example values. They are also useful when passing data to decorators, and for template parameters that are ultimately passed to decorators.
TypeSpec can define values in addition to types. Values are useful in an API description to define default values for types or provide example values. They are also useful when passing data to decorators, and for template parameters that are ultimately passed to decorators or used as default values.

There are three kinds of values: objects, arrays, and scalars. These values can be created with object literals, array literals, and scalar literals and initializers. Additionally, values can result from referencing enum members and union variants.
Values cannot be used as types, and types cannot be used as values, they are completely separate. However, string, number, boolean, and null literals can be either a type or a value depending on context (see also [scalar literals](#scalar-literals)). Additionally, union and enum member references may produce a type or a value depending on context (see also [enum member &amp; union variant references](#enum-member--union-variant-references)).

## Object values
## Value kinds

There are four kinds of values: objects, arrays, scalars. and null. These values can be created with object literals, array literals, scalar literals and initializers, and the null literal respectively. Additionally, values can result from referencing enum members and union variants.

### Object values

Object values use the syntax `#{}` and can define any number of properties. For example:

Expand All @@ -27,7 +31,7 @@ const example = #{
}
```

## Array values
### Array values

Array values use the syntax `#[]` and can define any number of items. For example:

Expand All @@ -48,11 +52,11 @@ const exampleTags1: Tags = #["TypeSpec", "JSON"]; // ok
const exampleTags2: Tags = #["TypeSpec", "JSON", "OpenAPI"]; // error
```

## Scalar values
### Scalar values

There are two ways to create scalar values: with a literal syntax like `"string value"`, and with a scalar initializer like `utcDateTime.fromISO("2020-12-01T12:00:00Z")`.

### Scalar literals
#### Scalar literals

The literal syntax for strings, numerics, booleans and null can evaluate to either a type or a value depending on the surrounding context of the literal. When the literal is in _type context_ (a model property type, operation return type, alias definition, etc.) the literal becomes a literal type. When the literal is in _value context_ (a default value, property of an object value, const definition, etc.), the literal becomes a value. When the literal is in an _ambiguous context_ (e.g. an argument to a template or decorator that can accept either a type or a value) the literal becomes a value. The `typeof` operator can be used to convert the literal to a type in such ambiguous contexts.

Expand All @@ -67,7 +71,7 @@ extern dec setNumberTypeOrValue(target: unknown, color: numeric | (valueof numer
model A {}
```

### Scalar initializers
#### Scalar initializers

Scalar initializers create scalar values by calling an initializer with one or more values. Scalar initializers for types extended from `numeric`, `string`, and `boolean` are called by adding parenthesis after the scalar reference:

Expand All @@ -86,6 +90,64 @@ scalar ipv4 extends string {
const ip = ipv4.fromInt(2341230);
```

#### Null values

Null values are created with the `null` literal.

```typespec
const value: string | null = null;
```

The `null` value, like the `null` type, doesn't have any special behavior in the TypeSpec language. It is just the value `null` like that in JSON.

## Const declarations

Const declarations allow storing values in a variable for later reference. Const declarations have an optional type annotation. When the type annotation is absent, the type is inferred from the value by constructing an exact type from the initializer.

```typespec
const stringValue: string = "hello";
// ^-- type: string

const oneValue = 1;
// ^-- type: 1

const objectValue = #{ x: 0, y: 0 };
// ^-- type: { x: 0, y: 0 }
```

## The `typeof` operator

The `typeof` operator returns the declared or inferred type of a value reference. Note that the actual value being stored by the referenced variable may be more specific than the declared type of the value. For example, if a const is declared with a union type, the value will only ever store one specific variant at a time, but typeof will give you the declared union type.

```typespec
const stringValue: string = "hello";
// typeof stringValue returns `string`.

const oneValue = 1;
// typeof stringValue returns `1`

const stringOrOneValue: string | 1 = 1;
// typeof stringOrOneValue returns `string | 1`
```

## Validation

TypeSpec will validate values against built-in validation decorators like `@minLength` and `@maxValue`.

```typespec
@maxLength(3)
scalar shortString extends string;

const s1: shortString = "abc"; // ok
const s2: shortString = "abcd"; // error:

model Entity {
a: shortString;
}

const e1: Entity = #{ a: "abcd" } // error
```

## Enum member &amp; union variant references

References to enum members and union variants can be either types or values and follow the same rules as scalar literals. When an enum member reference is in _type context_, the reference becomes an enum member type. When in _value context_ or _ambiguous context_ the reference becomes the enum member's value.
Expand Down