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-8410

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

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