GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/typespec

Public

mirrored from https://github.com/microsoft/typespecAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
copilot/add-max-overloads-with-models

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

typespec/packages/compiler/generated-defs

packages/compiler/generated-defs/TypeSpec.ts

1227lines · modecode

RawDownload
Latest commit unavailable.
1import type {
2 DecoratorContext,
3 DecoratorValidatorCallbacks,
4 Enum,
5 EnumValue,
6 FunctionContext,
7 Interface,
8 Model,
9 ModelProperty,
10 Namespace,
11 Numeric,
12 Operation,
13 Scalar,
14 ScalarValue,
15 Type,
16 Union,
17 UnionVariant,
18} from "../src/index.js";
19
20export interface ServiceOptions {
21 readonly title?: string;
22}
23
24export interface DiscriminatedOptions {
25 readonly envelope?: "object" | "none";
26 readonly discriminatorPropertyName?: string;
27 readonly envelopePropertyName?: string;
28}
29
30export interface ExampleOptions {
31 readonly title?: string;
32 readonly description?: string;
33}
34
35export interface OperationExample {
36 readonly parameters?: unknown;
37 readonly returnType?: unknown;
38}
39
40export interface VisibilityFilter {
41 readonly any?: readonly EnumValue[];
42 readonly all?: readonly EnumValue[];
43 readonly none?: readonly EnumValue[];
44}
45
46/**
47 * Applies a media type hint to a TypeSpec type. Emitters and libraries may choose to use this hint to determine how a
48 * type should be serialized. For example, the `@typespec/http` library will use the media type hint of the response
49 * body type as a default `Content-Type` if one is not explicitly specified in the operation.
50 *
51 * Media types (also known as MIME types) are defined by RFC 6838. The media type hint should be a valid media type
52 * string as defined by the RFC, but the decorator does not enforce or validate this constraint.
53 *
54 * Notes: the applied media type is _only_ a hint. It may be overridden or not used at all. Media type hints are
55 * inherited by subtypes. If a media type hint is applied to a model, it will be inherited by all other models that
56 * `extend` it unless they delcare their own media type hint.
57 *
58 * @param mediaType The media type hint to apply to the target type.
59 * @example create a model that serializes as XML by default
60 *
61 * ```tsp
62 * @mediaTypeHint("application/xml")
63 * model Example {
64 * @visibility(Lifecycle.Read)
65 * id: string;
66 *
67 * name: string;
68 * }
69 * ```
70 */
71export type MediaTypeHintDecorator = (
72 context: DecoratorContext,
73 target: Model | Scalar | Enum | Union,
74 mediaType: string,
75) => DecoratorValidatorCallbacks | void;
76
77/**
78 * Specify how to encode the target type.
79 *
80 * @param encodingOrEncodeAs Known name of an encoding or a scalar type to encode as(Only for numeric types to encode as string).
81 * @param encodedAs What target type is this being encoded as. Default to string.
82 * @example offsetDateTime encoded with rfc7231
83 *
84 * ```tsp
85 * @encode("rfc7231")
86 * scalar myDateTime extends offsetDateTime;
87 * ```
88 * @example utcDateTime encoded with unixTimestamp
89 *
90 * ```tsp
91 * @encode("unixTimestamp", int32)
92 * scalar myDateTime extends unixTimestamp;
93 * ```
94 * @example encode numeric type to string
95 *
96 * ```tsp
97 * model Pet {
98 * @encode(string) id: int64;
99 * }
100 * ```
101 */
102export type EncodeDecorator = (
103 context: DecoratorContext,
104 target: Scalar | ModelProperty,
105 encodingOrEncodeAs: Scalar | string | EnumValue,
106 encodedAs?: Scalar,
107) => DecoratorValidatorCallbacks | void;
108
109/**
110 * Attach a documentation string. Content support CommonMark markdown formatting.
111 *
112 * @param doc Documentation string
113 * @param formatArgs Record with key value pair that can be interpolated in the doc.
114 * @example
115 * ```typespec
116 * @doc("Represent a Pet available in the PetStore")
117 * model Pet {}
118 * ```
119 */
120export type DocDecorator = (
121 context: DecoratorContext,
122 target: Type,
123 doc: string,
124 formatArgs?: Type,
125) => DecoratorValidatorCallbacks | void;
126
127/**
128 * Returns the model with required properties removed.
129 */
130export type WithOptionalPropertiesDecorator = (
131 context: DecoratorContext,
132 target: Model,
133) => DecoratorValidatorCallbacks | void;
134
135/**
136 * Returns the model with non-updateable properties removed.
137 */
138export type WithUpdateablePropertiesDecorator = (
139 context: DecoratorContext,
140 target: Model,
141) => DecoratorValidatorCallbacks | void;
142
143/**
144 * Returns the model with the given properties omitted.
145 *
146 * @param omit List of properties to omit
147 */
148export type WithoutOmittedPropertiesDecorator = (
149 context: DecoratorContext,
150 target: Model,
151 omit: Type,
152) => DecoratorValidatorCallbacks | void;
153
154/**
155 * Returns the model with only the given properties included.
156 *
157 * @param pick List of properties to include
158 */
159export type WithPickedPropertiesDecorator = (
160 context: DecoratorContext,
161 target: Model,
162 pick: Type,
163) => DecoratorValidatorCallbacks | void;
164
165/**
166 * Returns the model with any default values removed.
167 */
168export type WithoutDefaultValuesDecorator = (
169 context: DecoratorContext,
170 target: Model,
171) => DecoratorValidatorCallbacks | void;
172
173/**
174 * Set the visibility of key properties in a model if not already set.
175 *
176 * This will set the visibility modifiers of all key properties in the model if the visibility is not already _explicitly_ set,
177 * but will not change the visibility of any properties that have visibility set _explicitly_, even if the visibility
178 * is the same as the default visibility.
179 *
180 * Visibility may be set explicitly using any of the following decorators:
181 *
182 * - `@visibility`
183 * - `@removeVisibility`
184 * - `@invisible`
185 *
186 * @param visibility The desired default visibility value. If a key property already has visibility set, it will not be changed.
187 */
188export type WithDefaultKeyVisibilityDecorator = (
189 context: DecoratorContext,
190 target: Model,
191 visibility: EnumValue,
192) => DecoratorValidatorCallbacks | void;
193
194/**
195 * Typically a short, single-line description.
196 *
197 * @param summary Summary string.
198 * @example
199 * ```typespec
200 * @summary("This is a pet")
201 * model Pet {}
202 * ```
203 */
204export type SummaryDecorator = (
205 context: DecoratorContext,
206 target: Type,
207 summary: string,
208) => DecoratorValidatorCallbacks | void;
209
210/**
211 * Attach a documentation string to describe the successful return types of an operation.
212 * If an operation returns a union of success and errors it only describes the success. See `@errorsDoc` for error documentation.
213 *
214 * @param doc Documentation string
215 * @example
216 * ```typespec
217 * @returnsDoc("Returns doc")
218 * op get(): Pet | NotFound;
219 * ```
220 */
221export type ReturnsDocDecorator = (
222 context: DecoratorContext,
223 target: Operation,
224 doc: string,
225) => DecoratorValidatorCallbacks | void;
226
227/**
228 * Attach a documentation string to describe the error return types of an operation.
229 * If an operation returns a union of success and errors it only describes the errors. See `@returnsDoc` for success documentation.
230 *
231 * @param doc Documentation string
232 * @example
233 * ```typespec
234 * @errorsDoc("Errors doc")
235 * op get(): Pet | NotFound;
236 * ```
237 */
238export type ErrorsDocDecorator = (
239 context: DecoratorContext,
240 target: Operation,
241 doc: string,
242) => DecoratorValidatorCallbacks | void;
243
244/**
245 * Mark this namespace as describing a service and configure service properties.
246 *
247 * @param options Optional configuration for the service.
248 * @example
249 * ```typespec
250 * @service
251 * namespace PetStore;
252 * ```
253 * @example Setting service title
254 * ```typespec
255 * @service(#{title: "Pet store"})
256 * namespace PetStore;
257 * ```
258 */
259export type ServiceDecorator = (
260 context: DecoratorContext,
261 target: Namespace,
262 options?: ServiceOptions,
263) => DecoratorValidatorCallbacks | void;
264
265/**
266 * Specify that this model is an error type. Operations return error types when the operation has failed.
267 *
268 * @example
269 * ```typespec
270 * @error
271 * model PetStoreError {
272 * code: string;
273 * message: string;
274 * }
275 * ```
276 */
277export type ErrorDecorator = (
278 context: DecoratorContext,
279 target: Model,
280) => DecoratorValidatorCallbacks | void;
281
282/**
283 * Specify a known data format hint for this string type. For example `uuid`, `uri`, etc.
284 * This differs from the `@pattern` decorator which is meant to specify a regular expression while `@format` accepts a known format name.
285 * The format names are open ended and are left to emitter to interpret.
286 *
287 * @param format format name.
288 * @example
289 * ```typespec
290 * @format("uuid")
291 * scalar uuid extends string;
292 * ```
293 */
294export type FormatDecorator = (
295 context: DecoratorContext,
296 target: Scalar | ModelProperty,
297 format: string,
298) => DecoratorValidatorCallbacks | void;
299
300/**
301 * Specify the the pattern this string should respect using simple regular expression syntax.
302 * The following syntax is allowed: alternations (`|`), quantifiers (`?`, `*`, `+`, and `{ }`), wildcard (`.`), and grouping parentheses.
303 * Advanced features like look-around, capture groups, and references are not supported.
304 *
305 * This decorator may optionally provide a custom validation _message_. Emitters may choose to use the message to provide
306 * context when pattern validation fails. For the sake of consistency, the message should be a phrase that describes in
307 * plain language what sort of content the pattern attempts to validate. For example, a complex regular expression that
308 * validates a GUID string might have a message like "Must be a valid GUID."
309 *
310 * @param pattern Regular expression.
311 * @param validationMessage Optional validation message that may provide context when validation fails.
312 * @example
313 * ```typespec
314 * @pattern("[a-z]+", "Must be a string consisting of only lower case letters and of at least one character.")
315 * scalar LowerAlpha extends string;
316 * ```
317 */
318export type PatternDecorator = (
319 context: DecoratorContext,
320 target: Scalar | ModelProperty,
321 pattern: string,
322 validationMessage?: string,
323) => DecoratorValidatorCallbacks | void;
324
325/**
326 * Specify the minimum length this string type should be.
327 *
328 * @param value Minimum length
329 * @example
330 * ```typespec
331 * @minLength(2)
332 * scalar Username extends string;
333 * ```
334 */
335export type MinLengthDecorator = (
336 context: DecoratorContext,
337 target: Scalar | ModelProperty,
338 value: Numeric,
339) => DecoratorValidatorCallbacks | void;
340
341/**
342 * Specify the maximum length this string type should be.
343 *
344 * @param value Maximum length
345 * @example
346 * ```typespec
347 * @maxLength(20)
348 * scalar Username extends string;
349 * ```
350 */
351export type MaxLengthDecorator = (
352 context: DecoratorContext,
353 target: Scalar | ModelProperty,
354 value: Numeric,
355) => DecoratorValidatorCallbacks | void;
356
357/**
358 * Specify the minimum number of items this array should have.
359 *
360 * @param value Minimum number
361 * @example
362 * ```typespec
363 * @minItems(1)
364 * model Endpoints is string[];
365 * ```
366 */
367export type MinItemsDecorator = (
368 context: DecoratorContext,
369 target: Type | ModelProperty,
370 value: Numeric,
371) => DecoratorValidatorCallbacks | void;
372
373/**
374 * Specify the maximum number of items this array should have.
375 *
376 * @param value Maximum number
377 * @example
378 * ```typespec
379 * @maxItems(5)
380 * model Endpoints is string[];
381 * ```
382 */
383export type MaxItemsDecorator = (
384 context: DecoratorContext,
385 target: Type | ModelProperty,
386 value: Numeric,
387) => DecoratorValidatorCallbacks | void;
388
389/**
390 * Specify the minimum value this numeric type should be.
391 *
392 * @param value Minimum value
393 * @example
394 * ```typespec
395 * @minValue(18)
396 * scalar Age is int32;
397 * ```
398 */
399export type MinValueDecorator = (
400 context: DecoratorContext,
401 target: Scalar | ModelProperty,
402 value: Numeric | ScalarValue | ScalarValue | ScalarValue | ScalarValue | ScalarValue,
403) => DecoratorValidatorCallbacks | void;
404
405/**
406 * Specify the maximum value this numeric type should be.
407 *
408 * @param value Maximum value
409 * @example
410 * ```typespec
411 * @maxValue(200)
412 * scalar Age is int32;
413 * ```
414 */
415export type MaxValueDecorator = (
416 context: DecoratorContext,
417 target: Scalar | ModelProperty,
418 value: Numeric | ScalarValue | ScalarValue | ScalarValue | ScalarValue | ScalarValue,
419) => DecoratorValidatorCallbacks | void;
420
421/**
422 * Specify the minimum value this numeric type should be, exclusive of the given
423 * value.
424 *
425 * @param value Minimum value
426 * @example
427 * ```typespec
428 * @minValueExclusive(0)
429 * scalar distance is float64;
430 * ```
431 */
432export type MinValueExclusiveDecorator = (
433 context: DecoratorContext,
434 target: Scalar | ModelProperty,
435 value: Numeric | ScalarValue | ScalarValue | ScalarValue | ScalarValue | ScalarValue,
436) => DecoratorValidatorCallbacks | void;
437
438/**
439 * Specify the maximum value this numeric type should be, exclusive of the given
440 * value.
441 *
442 * @param value Maximum value
443 * @example
444 * ```typespec
445 * @maxValueExclusive(50)
446 * scalar distance is float64;
447 * ```
448 */
449export type MaxValueExclusiveDecorator = (
450 context: DecoratorContext,
451 target: Scalar | ModelProperty,
452 value: Numeric | ScalarValue | ScalarValue | ScalarValue | ScalarValue | ScalarValue,
453) => DecoratorValidatorCallbacks | void;
454
455/**
456 * Mark this value as a secret value that should be treated carefully to avoid exposure
457 *
458 * @example
459 * ```typespec
460 * @secret
461 * scalar Password is string;
462 * ```
463 */
464export type SecretDecorator = (
465 context: DecoratorContext,
466 target: Scalar | ModelProperty | Model | Union | Enum,
467) => DecoratorValidatorCallbacks | void;
468
469/**
470 * Attaches a tag to an operation, interface, or namespace. Multiple `@tag` decorators can be specified to attach multiple tags to a TypeSpec element.
471 *
472 * @param tag Tag value
473 */
474export type TagDecorator = (
475 context: DecoratorContext,
476 target: Namespace | Interface | Operation,
477 tag: string,
478) => DecoratorValidatorCallbacks | void;
479
480/**
481 * Specifies how a templated type should name their instances.
482 *
483 * @param name name the template instance should take
484 * @param formatArgs Model with key value used to interpolate the name
485 * @example
486 * ```typespec
487 * @friendlyName("{name}List", T)
488 * model List<Item> {
489 * value: Item[];
490 * nextLink: string;
491 * }
492 * ```
493 */
494export type FriendlyNameDecorator = (
495 context: DecoratorContext,
496 target: Type,
497 name: string,
498 formatArgs?: Type,
499) => DecoratorValidatorCallbacks | void;
500
501/**
502 * Mark a model property as the key to identify instances of that type
503 *
504 * @param altName Name of the property. If not specified, the decorated property name is used.
505 * @example
506 * ```typespec
507 * model Pet {
508 * @key id: string;
509 * }
510 * ```
511 */
512export type KeyDecorator = (
513 context: DecoratorContext,
514 target: ModelProperty,
515 altName?: string,
516) => DecoratorValidatorCallbacks | void;
517
518/**
519 * Specify this operation is an overload of the given operation.
520 *
521 * @param overloadbase Base operation that should be a union of all overloads
522 * @example
523 * ```typespec
524 * op upload(data: string | bytes, @header contentType: "text/plain" | "application/octet-stream"): void;
525 * @overload(upload)
526 * op uploadString(data: string, @header contentType: "text/plain" ): void;
527 * @overload(upload)
528 * op uploadBytes(data: bytes, @header contentType: "application/octet-stream"): void;
529 * ```
530 */
531export type OverloadDecorator = (
532 context: DecoratorContext,
533 target: Operation,
534 overloadbase: Operation,
535) => DecoratorValidatorCallbacks | void;
536
537/**
538 * Provide an alternative name for this type when serialized to the given mime type.
539 *
540 * @param mimeType Mime type this should apply to. The mime type should be a known mime type as described here https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types without any suffix (e.g. `+json`)
541 * @param name Alternative name
542 * @example
543 * ```typespec
544 * model Certificate {
545 * @encodedName("application/json", "exp")
546 * @encodedName("application/xml", "expiry")
547 * expireAt: int32;
548 * }
549 * ```
550 * @example Invalid values
551 *
552 * ```typespec
553 * @encodedName("application/merge-patch+json", "exp")
554 * ^ error cannot use subtype
555 * ```
556 */
557export type EncodedNameDecorator = (
558 context: DecoratorContext,
559 target: Type,
560 mimeType: string,
561 name: string,
562) => DecoratorValidatorCallbacks | void;
563
564/**
565 * Specify that this union is discriminated.
566 *
567 * @param options Options to configure the serialization of the discriminated union.
568 * @example
569 * ```typespec
570 * @discriminated
571 * union Pet{ cat: Cat, dog: Dog }
572 *
573 * model Cat { name: string, meow: boolean }
574 * model Dog { name: string, bark: boolean }
575 * ```
576 * Serialized as:
577 * ```json
578 * {
579 * "kind": "cat",
580 * "value": {
581 * "name": "Whiskers",
582 * "meow": true
583 * }
584 * },
585 * {
586 * "kind": "dog",
587 * "value": {
588 * "name": "Rex",
589 * "bark": false
590 * }
591 * }
592 * ```
593 * @example Custom property names
594 *
595 * ```typespec
596 * @discriminated(#{discriminatorPropertyName: "dataKind", envelopePropertyName: "data"})
597 * union Pet{ cat: Cat, dog: Dog }
598 *
599 * model Cat { name: string, meow: boolean }
600 * model Dog { name: string, bark: boolean }
601 * ```
602 * Serialized as:
603 * ```json
604 * {
605 * "dataKind": "cat",
606 * "data": {
607 * "name": "Whiskers",
608 * "meow": true
609 * }
610 * },
611 * {
612 * "dataKind": "dog",
613 * "data": {
614 * "name": "Rex",
615 * "bark": false
616 * }
617 * }
618 * ```
619 */
620export type DiscriminatedDecorator = (
621 context: DecoratorContext,
622 target: Union,
623 options?: DiscriminatedOptions,
624) => DecoratorValidatorCallbacks | void;
625
626/**
627 * Specify the property to be used to discriminate this type.
628 *
629 * @param propertyName The property name to use for discrimination
630 * @example
631 * ```typespec
632 * @discriminator("kind")
633 * model Pet{ kind: string }
634 *
635 * model Cat extends Pet {kind: "cat", meow: boolean}
636 * model Dog extends Pet {kind: "dog", bark: boolean}
637 * ```
638 */
639export type DiscriminatorDecorator = (
640 context: DecoratorContext,
641 target: Model,
642 propertyName: string,
643) => DecoratorValidatorCallbacks | void;
644
645/**
646 * Provide an example value for a data type.
647 *
648 * @param example Example value.
649 * @param options Optional metadata for the example.
650 * @example
651 * ```tsp
652 * @example(#{name: "Fluffy", age: 2})
653 * model Pet {
654 * name: string;
655 * age: int32;
656 * }
657 * ```
658 */
659export type ExampleDecorator = (
660 context: DecoratorContext,
661 target: Model | Enum | Scalar | Union | ModelProperty | UnionVariant,
662 example: unknown,
663 options?: ExampleOptions,
664) => DecoratorValidatorCallbacks | void;
665
666/**
667 * Provide example values for an operation's parameters and corresponding return type.
668 *
669 * @param example Example value.
670 * @param options Optional metadata for the example.
671 * @example
672 * ```tsp
673 * @opExample(#{parameters: #{name: "Fluffy", age: 2}, returnType: #{name: "Fluffy", age: 2, id: "abc"})
674 * op createPet(pet: Pet): Pet;
675 * ```
676 */
677export type OpExampleDecorator = (
678 context: DecoratorContext,
679 target: Operation,
680 example: OperationExample,
681 options?: ExampleOptions,
682) => DecoratorValidatorCallbacks | void;
683
684/**
685 * Mark this operation as a `list` operation that returns a paginated list of items.
686 */
687export type ListDecorator = (
688 context: DecoratorContext,
689 target: Operation,
690) => DecoratorValidatorCallbacks | void;
691
692/**
693 * Pagination property defining the number of items to skip.
694 *
695 * @example
696 * ```tsp
697 * model Page<T> {
698 * @pageItems items: T[];
699 * }
700 * @list op listPets(@offset skip: int32, @pageSize pageSize: int8): Page<Pet>;
701 * ```
702 */
703export type OffsetDecorator = (
704 context: DecoratorContext,
705 target: ModelProperty,
706) => DecoratorValidatorCallbacks | void;
707
708/**
709 * Pagination property defining the page index.
710 *
711 * @example
712 * ```tsp
713 * model Page<T> {
714 * @pageItems items: T[];
715 * }
716 * @list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;
717 * ```
718 */
719export type PageIndexDecorator = (
720 context: DecoratorContext,
721 target: ModelProperty,
722) => DecoratorValidatorCallbacks | void;
723
724/**
725 * Specify the pagination parameter that controls the maximum number of items to include in a page.
726 *
727 * @example
728 * ```tsp
729 * model Page<T> {
730 * @pageItems items: T[];
731 * }
732 * @list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;
733 * ```
734 */
735export type PageSizeDecorator = (
736 context: DecoratorContext,
737 target: ModelProperty,
738) => DecoratorValidatorCallbacks | void;
739
740/**
741 * Specify the the property that contains the array of page items.
742 *
743 * @example
744 * ```tsp
745 * model Page<T> {
746 * @pageItems items: T[];
747 * }
748 * @list op listPets(@pageIndex page: int32, @pageSize pageSize: int8): Page<Pet>;
749 * ```
750 */
751export type PageItemsDecorator = (
752 context: DecoratorContext,
753 target: ModelProperty,
754) => DecoratorValidatorCallbacks | void;
755
756/**
757 * Pagination property defining the token to get to the next page.
758 * It MUST be specified both on the request parameter and the response.
759 *
760 * @example
761 * ```tsp
762 * model Page<T> {
763 * @pageItems items: T[];
764 * @continuationToken continuationToken: string;
765 * }
766 * @list op listPets(@continuationToken continuationToken: string): Page<Pet>;
767 * ```
768 */
769export type ContinuationTokenDecorator = (
770 context: DecoratorContext,
771 target: ModelProperty,
772) => DecoratorValidatorCallbacks | void;
773
774/**
775 * Pagination property defining a link to the next page.
776 *
777 * It is expected that navigating to the link will return the same set of responses as the operation that returned the current page.
778 *
779 * @example
780 * ```tsp
781 * model Page<T> {
782 * @pageItems items: T[];
783 * @nextLink next: url;
784 * @prevLink prev: url;
785 * @firstLink first: url;
786 * @lastLink last: url;
787 * }
788 * @list op listPets(): Page<Pet>;
789 * ```
790 */
791export type NextLinkDecorator = (
792 context: DecoratorContext,
793 target: ModelProperty,
794) => DecoratorValidatorCallbacks | void;
795
796/**
797 * Pagination property defining a link to the previous page.
798 *
799 * It is expected that navigating to the link will return the same set of responses as the operation that returned the current page.
800 *
801 * @example
802 * ```tsp
803 * model Page<T> {
804 * @pageItems items: T[];
805 * @nextLink next: url;
806 * @prevLink prev: url;
807 * @firstLink first: url;
808 * @lastLink last: url;
809 * }
810 * @list op listPets(): Page<Pet>;
811 * ```
812 */
813export type PrevLinkDecorator = (
814 context: DecoratorContext,
815 target: ModelProperty,
816) => DecoratorValidatorCallbacks | void;
817
818/**
819 * Pagination property defining a link to the first page.
820 *
821 * It is expected that navigating to the link will return the same set of responses as the operation that returned the current page.
822 *
823 * @example
824 * ```tsp
825 * model Page<T> {
826 * @pageItems items: T[];
827 * @nextLink next: url;
828 * @prevLink prev: url;
829 * @firstLink first: url;
830 * @lastLink last: url;
831 * }
832 * @list op listPets(): Page<Pet>;
833 * ```
834 */
835export type FirstLinkDecorator = (
836 context: DecoratorContext,
837 target: ModelProperty,
838) => DecoratorValidatorCallbacks | void;
839
840/**
841 * Pagination property defining a link to the last page.
842 *
843 * It is expected that navigating to the link will return the same set of responses as the operation that returned the current page.
844 *
845 * @example
846 * ```tsp
847 * model Page<T> {
848 * @pageItems items: T[];
849 * @nextLink next: url;
850 * @prevLink prev: url;
851 * @firstLink first: url;
852 * @lastLink last: url;
853 * }
854 * @list op listPets(): Page<Pet>;
855 * ```
856 */
857export type LastLinkDecorator = (
858 context: DecoratorContext,
859 target: ModelProperty,
860) => DecoratorValidatorCallbacks | void;
861
862/**
863 * A debugging decorator used to inspect a type.
864 *
865 * @param text Custom text to log
866 */
867export type InspectTypeDecorator = (
868 context: DecoratorContext,
869 target: Type,
870 text: string,
871) => DecoratorValidatorCallbacks | void;
872
873/**
874 * A debugging decorator used to inspect a type name.
875 *
876 * @param text Custom text to log
877 */
878export type InspectTypeNameDecorator = (
879 context: DecoratorContext,
880 target: Type,
881 text: string,
882) => DecoratorValidatorCallbacks | void;
883
884/**
885 * Sets the visibility modifiers that are active on a property, indicating that it is only considered to be present
886 * (or "visible") in contexts that select for the given modifiers.
887 *
888 * A property without any visibility settings applied for any visibility class (e.g. `Lifecycle`) is considered to have
889 * the default visibility settings for that class.
890 *
891 * If visibility for the property has already been set for a visibility class (for example, using `@invisible` or
892 * `@removeVisibility`), this decorator will **add** the specified visibility modifiers to the property.
893 *
894 * See: [Visibility](https://typespec.io/docs/language-basics/visibility)
895 *
896 * The `@typespec/http` library uses `Lifecycle` visibility to determine which properties are included in the request or
897 * response bodies of HTTP operations. By default, it uses the following visibility settings:
898 *
899 * - For the return type of operations, properties are included if they have `Lifecycle.Read` visibility.
900 * - For POST operation parameters, properties are included if they have `Lifecycle.Create` visibility.
901 * - For PUT operation parameters, properties are included if they have `Lifecycle.Create` or `Lifecycle.Update` visibility.
902 * - For PATCH operation parameters, properties are included if they have `Lifecycle.Update` visibility.
903 * - For DELETE operation parameters, properties are included if they have `Lifecycle.Delete` visibility.
904 * - For GET or HEAD operation parameters, properties are included if they have `Lifecycle.Query` visibility.
905 *
906 * By default, properties have all five Lifecycle visibility modifiers enabled, so a property is visible in all contexts
907 * by default.
908 *
909 * The default settings may be overridden using the `@returnTypeVisibility` and `@parameterVisibility` decorators.
910 *
911 * See also: [Automatic visibility](https://typespec.io/docs/libraries/http/operations#automatic-visibility)
912 *
913 * @param visibilities List of visibilities which apply to this property.
914 * @example
915 * ```typespec
916 * model Dog {
917 * // The service will generate an ID, so you don't need to send it.
918 * @visibility(Lifecycle.Read)
919 * id: int32;
920 *
921 * // The service will store this secret name, but won't ever return it.
922 * @visibility(Lifecycle.Create, Lifecycle.Update)
923 * secretName: string;
924 *
925 * // The regular name has all vi
926 * name: string;
927 * }
928 * ```
929 */
930export type VisibilityDecorator = (
931 context: DecoratorContext,
932 target: ModelProperty,
933 ...visibilities: EnumValue[]
934) => DecoratorValidatorCallbacks | void;
935
936/**
937 * Indicates that a property is not visible in the given visibility class.
938 *
939 * This decorator removes all active visibility modifiers from the property within
940 * the given visibility class, making it invisible to any context that selects for
941 * visibility modifiers within that class.
942 *
943 * @param visibilityClass The visibility class to make the property invisible within.
944 * @example
945 * ```typespec
946 * model Example {
947 * @invisible(Lifecycle)
948 * hidden_property: string;
949 * }
950 * ```
951 */
952export type InvisibleDecorator = (
953 context: DecoratorContext,
954 target: ModelProperty,
955 visibilityClass: Enum,
956) => DecoratorValidatorCallbacks | void;
957
958/**
959 * Removes visibility modifiers from a property.
960 *
961 * If the visibility modifiers for a visibility class have not been initialized,
962 * this decorator will use the default visibility modifiers for the visibility
963 * class as the default modifier set.
964 *
965 * @param target The property to remove visibility from.
966 * @param visibilities The visibility modifiers to remove from the target property.
967 * @example
968 * ```typespec
969 * model Example {
970 * // This property will have all Lifecycle visibilities except the Read
971 * // visibility, since it is removed.
972 * @removeVisibility(Lifecycle.Read)
973 * secret_property: string;
974 * }
975 * ```
976 */
977export type RemoveVisibilityDecorator = (
978 context: DecoratorContext,
979 target: ModelProperty,
980 ...visibilities: EnumValue[]
981) => DecoratorValidatorCallbacks | void;
982
983/**
984 * Removes properties that do not have at least one of the given visibility modifiers
985 * active.
986 *
987 * If no visibility modifiers are supplied, this decorator has no effect.
988 *
989 * See also: [Automatic visibility](https://typespec.io/docs/libraries/http/operations#automatic-visibility)
990 *
991 * When using an emitter that applies visibility automatically, it is generally
992 * not necessary to use this decorator.
993 *
994 * @param visibilities List of visibilities that apply to this property.
995 * @example
996 * ```typespec
997 * model Dog {
998 * @visibility(Lifecycle.Read)
999 * id: int32;
1000 *
1001 * @visibility(Lifecycle.Create, Lifecycle.Update)
1002 * secretName: string;
1003 *
1004 * name: string;
1005 * }
1006 *
1007 * // The spread operator will copy all the properties of Dog into DogRead,
1008 * // and @withVisibility will then remove those that are not visible with
1009 * // create or update visibility.
1010 * //
1011 * // In this case, the id property is removed, and the name and secretName
1012 * // properties are kept.
1013 * @withVisibility(Lifecycle.Create, Lifecycle.Update)
1014 * model DogCreateOrUpdate {
1015 * ...Dog;
1016 * }
1017 *
1018 * // In this case the id and name properties are kept and the secretName property
1019 * // is removed.
1020 * @withVisibility(Lifecycle.Read)
1021 * model DogRead {
1022 * ...Dog;
1023 * }
1024 * ```
1025 */
1026export type WithVisibilityDecorator = (
1027 context: DecoratorContext,
1028 target: Model,
1029 ...visibilities: EnumValue[]
1030) => DecoratorValidatorCallbacks | void;
1031
1032/**
1033 * Declares the visibility constraint of the parameters of a given operation.
1034 *
1035 * A parameter or property nested within a parameter will be visible if it has _any_ of the visibilities
1036 * in the list.
1037 *
1038 * It is invalid to call this decorator with no visibility modifiers.
1039 *
1040 * @param visibilities List of visibility modifiers that apply to the parameters of this operation.
1041 */
1042export type ParameterVisibilityDecorator = (
1043 context: DecoratorContext,
1044 target: Operation,
1045 ...visibilities: EnumValue[]
1046) => DecoratorValidatorCallbacks | void;
1047
1048/**
1049 * Declares the visibility constraint of the return type of a given operation.
1050 *
1051 * A property within the return type of the operation will be visible if it has _any_ of the visibilities
1052 * in the list.
1053 *
1054 * It is invalid to call this decorator with no visibility modifiers.
1055 *
1056 * @param visibilities List of visibility modifiers that apply to the return type of this operation.
1057 */
1058export type ReturnTypeVisibilityDecorator = (
1059 context: DecoratorContext,
1060 target: Operation,
1061 ...visibilities: EnumValue[]
1062) => DecoratorValidatorCallbacks | void;
1063
1064/**
1065 * Declares the default visibility modifiers for a visibility class.
1066 *
1067 * The default modifiers are used when a property does not have any visibility decorators
1068 * applied to it.
1069 *
1070 * The modifiers passed to this decorator _MUST_ be members of the target Enum.
1071 *
1072 * @param visibilities the list of modifiers to use as the default visibility modifiers.
1073 */
1074export type DefaultVisibilityDecorator = (
1075 context: DecoratorContext,
1076 target: Enum,
1077 ...visibilities: EnumValue[]
1078) => DecoratorValidatorCallbacks | void;
1079
1080/**
1081 * Applies the given visibility filter to the properties of the target model.
1082 *
1083 * This transformation is recursive, so it will also apply the filter to any nested
1084 * or referenced models that are the types of any properties in the `target`.
1085 *
1086 * If a `nameTemplate` is provided, newly-created type instances will be named according
1087 * to the template. See the `@friendlyName` decorator for more information on the template
1088 * syntax. The transformed type is provided as the argument to the template.
1089 *
1090 * @param target The model to apply the visibility filter to.
1091 * @param filter The visibility filter to apply to the properties of the target model.
1092 * @param nameTemplate The name template to use when renaming new model instances.
1093 * @example
1094 * ```typespec
1095 * model Dog {
1096 * @visibility(Lifecycle.Read)
1097 * id: int32;
1098 *
1099 * name: string;
1100 * }
1101 *
1102 * @withVisibilityFilter(#{ all: #[Lifecycle.Read] })
1103 * model DogRead {
1104 * ...Dog
1105 * }
1106 * ```
1107 */
1108export type WithVisibilityFilterDecorator = (
1109 context: DecoratorContext,
1110 target: Model,
1111 filter: VisibilityFilter,
1112 nameTemplate?: string,
1113) => DecoratorValidatorCallbacks | void;
1114
1115/**
1116 * Transforms the `target` model to include only properties that are visible during the
1117 * "Update" lifecycle phase.
1118 *
1119 * Any nested models of optional properties will be transformed into the "CreateOrUpdate"
1120 * lifecycle phase instead of the "Update" lifecycle phase, so that nested models may be
1121 * fully updated.
1122 *
1123 * If a `nameTemplate` is provided, newly-created type instances will be named according
1124 * to the template. See the `@friendlyName` decorator for more information on the template
1125 * syntax. The transformed type is provided as the argument to the template.
1126 *
1127 * @param target The model to apply the transformation to.
1128 * @param nameTemplate The name template to use when renaming new model instances.
1129 * @example
1130 * ```typespec
1131 * model Dog {
1132 * @visibility(Lifecycle.Read)
1133 * id: int32;
1134 *
1135 * @visibility(Lifecycle.Create, Lifecycle.Update)
1136 * secretName: string;
1137 *
1138 * name: string;
1139 * }
1140 *
1141 * @withLifecycleUpdate
1142 * model DogUpdate {
1143 * ...Dog
1144 * }
1145 * ```
1146 */
1147export type WithLifecycleUpdateDecorator = (
1148 context: DecoratorContext,
1149 target: Model,
1150 nameTemplate?: string,
1151) => DecoratorValidatorCallbacks | void;
1152
1153export type TypeSpecDecorators = {
1154 mediaTypeHint: MediaTypeHintDecorator;
1155 encode: EncodeDecorator;
1156 doc: DocDecorator;
1157 withOptionalProperties: WithOptionalPropertiesDecorator;
1158 withUpdateableProperties: WithUpdateablePropertiesDecorator;
1159 withoutOmittedProperties: WithoutOmittedPropertiesDecorator;
1160 withPickedProperties: WithPickedPropertiesDecorator;
1161 withoutDefaultValues: WithoutDefaultValuesDecorator;
1162 withDefaultKeyVisibility: WithDefaultKeyVisibilityDecorator;
1163 summary: SummaryDecorator;
1164 returnsDoc: ReturnsDocDecorator;
1165 errorsDoc: ErrorsDocDecorator;
1166 service: ServiceDecorator;
1167 error: ErrorDecorator;
1168 format: FormatDecorator;
1169 pattern: PatternDecorator;
1170 minLength: MinLengthDecorator;
1171 maxLength: MaxLengthDecorator;
1172 minItems: MinItemsDecorator;
1173 maxItems: MaxItemsDecorator;
1174 minValue: MinValueDecorator;
1175 maxValue: MaxValueDecorator;
1176 minValueExclusive: MinValueExclusiveDecorator;
1177 maxValueExclusive: MaxValueExclusiveDecorator;
1178 secret: SecretDecorator;
1179 tag: TagDecorator;
1180 friendlyName: FriendlyNameDecorator;
1181 key: KeyDecorator;
1182 overload: OverloadDecorator;
1183 encodedName: EncodedNameDecorator;
1184 discriminated: DiscriminatedDecorator;
1185 discriminator: DiscriminatorDecorator;
1186 example: ExampleDecorator;
1187 opExample: OpExampleDecorator;
1188 list: ListDecorator;
1189 offset: OffsetDecorator;
1190 pageIndex: PageIndexDecorator;
1191 pageSize: PageSizeDecorator;
1192 pageItems: PageItemsDecorator;
1193 continuationToken: ContinuationTokenDecorator;
1194 nextLink: NextLinkDecorator;
1195 prevLink: PrevLinkDecorator;
1196 firstLink: FirstLinkDecorator;
1197 lastLink: LastLinkDecorator;
1198 inspectType: InspectTypeDecorator;
1199 inspectTypeName: InspectTypeNameDecorator;
1200 visibility: VisibilityDecorator;
1201 invisible: InvisibleDecorator;
1202 removeVisibility: RemoveVisibilityDecorator;
1203 withVisibility: WithVisibilityDecorator;
1204 parameterVisibility: ParameterVisibilityDecorator;
1205 returnTypeVisibility: ReturnTypeVisibilityDecorator;
1206 defaultVisibility: DefaultVisibilityDecorator;
1207 withVisibilityFilter: WithVisibilityFilterDecorator;
1208 withLifecycleUpdate: WithLifecycleUpdateDecorator;
1209};
1210
1211export type ApplyVisibilityFilterFunctionImplementation = (
1212 context: FunctionContext,
1213 input: Model,
1214 filter: VisibilityFilter,
1215 nameTemplate?: string,
1216) => Model;
1217
1218export type ApplyLifecycleUpdateFunctionImplementation = (
1219 context: FunctionContext,
1220 input: Model,
1221 nameTemplate?: string,
1222) => Model;
1223
1224export type TypeSpecFunctions = {
1225 applyVisibilityFilter: ApplyVisibilityFilterFunctionImplementation;
1226 applyLifecycleUpdate: ApplyLifecycleUpdateFunctionImplementation;
1227};
1228