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/fix-8095

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

1158lines · modecode

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