@typespec/compiler 0.41.0

package/lib/decorators.tsp

@@ -0,0 +1,420 @@
+import "../dist/lib/decorators.js";
+
+using TypeSpec.Reflection;
+
+namespace TypeSpec;
+
+/**
+ * Typically a short, single-line description.
+ * @param summary Summary string.
+ *
+ * @example
+ * ```typespec
+ * @summary("This is a pet")
+ * model Pet {}
+ * ```
+ */
+extern dec summary(target: unknown, summary: string);
+
+/**
+ * Attach a documentation string.
+ * @param doc Documentation string
+ * @param formatArgs Record with key value pair that can be interpolated in the doc.
+ *
+ * @example
+ * ```typespec
+ * @doc("Represent a Pet available in the PetStore")
+ * model Pet {}
+ * ```
+ */
+extern dec doc(target: unknown, doc: string, formatArgs?: object);
+
+/**
+ * Mark this type as deprecated
+ * @param message Deprecation message.
+ *
+ * @example
+ *
+ * ```typespec
+ * @deprecated("Use ActionV2")
+ * op Action<T>(): T;
+ * ```
+ */
+extern dec deprecated(target: unknown, message: string);
+
+/**
+ * Service options.
+ */
+model ServiceOptions {
+  /**
+   * Title of the service.
+   */
+  title?: string;
+  /**
+   * Version of the service.
+   */
+  version?: string;
+}
+
+/**
+ * Mark this namespace as describing a service and configure service properties.
+ * @param options Optional configuration for the service.
+ *
+ * @example
+ * ```typespec
+ * @service
+ * namespace PetStore;
+ * ```
+ *
+ * @example Setting service title
+ * ```typespec
+ * @service({title: "Pet store"})
+ * namespace PetStore;
+ * ```
+ *
+ * @example Setting service version
+ * ```typespec
+ * @service({version: "1.0"})
+ * namespace PetStore;
+ * ```
+ */
+extern dec service(target: Namespace, options?: ServiceOptions);
+
+/**
+ * Specify that this model is an error type. Operations return error types when the operation has failed.
+ *
+ * @example
+ * ```typespec
+ * @error
+ * model PetStoreError {
+ *   code: string;
+ *   message: string;
+ * }
+ * ```
+ */
+extern dec error(target: object);
+
+/**
+ * Specify a known data format hint for this string type. For example `uuid`, `uri`, etc.
+ * This differ from the @pattern decorator that is meant to specify a regular expression while @format takes in a known format name.
+ * The format names are open ended and are left to emitter to interpret.
+ *
+ * @param format format name.
+ *
+ * @example
+ * ```typespec
+ * @format("uuid")
+ * scalar uuid extends string;
+ * ```
+ */
+extern dec format(target: string | bytes | ModelProperty, format: string);
+
+/**
+ * Specify the the pattern this string should respect using simple regular expression syntax.
+ * The following syntax is allowed: alternations (`|`), quantifiers (`?`, `*`, `+`, and `{ }`), wildcard (`.`), and grouping parentheses.
+ * Advanced features like look-around, capture groups, and references are not supported.
+ *
+ * @param pattern Regular expression.
+ *
+ * @example
+ * ```typespec
+ * @pattern("[a-z]+")
+ * scalar LowerAlpha extends string;
+ * ```
+ */
+extern dec pattern(target: string | bytes | ModelProperty, pattern: string);
+
+/**
+ * Specify the minimum length this string type should be.
+ * @param value Minimum length
+ *
+ * @example
+ * ```typespec
+ * @minLength(2)
+ * scalar Username extends string;
+ * ```
+ */
+extern dec minLength(target: string | ModelProperty, value: integer);
+
+/**
+ * Specify the maximum length this string type should be.
+ * @param value Maximum length
+ *
+ * @example
+ * ```typespec
+ * @maxLength(20)
+ * scalar Username extends string;
+ * ```
+ */
+extern dec maxLength(target: string | ModelProperty, value: integer);
+
+/**
+ * Specify the minimum number of items this array should have.
+ * @param value Minimum number
+ *
+ * @example
+ * ```typespec
+ * @minItems(1)
+ * model Endpoints is string[];
+ * ```
+ */
+extern dec minItems(target: unknown[] | ModelProperty, value: integer);
+
+/**
+ * Specify the maximum number of items this array should have.
+ * @param value Maximum number
+ *
+ * @example
+ * ```typespec
+ * @maxItems(5)
+ * model Endpoints is string[];
+ * ```
+ */
+extern dec maxItems(target: unknown[] | ModelProperty, value: integer);
+
+/**
+ * Specify the minimum value this numeric type should be.
+ * @param value Minimum value
+ *
+ * @example
+ * ```typespec
+ * @minValue(18)
+ * scalar Age is int32;
+ * ```
+ */
+extern dec minValue(target: numeric | ModelProperty, value: numeric);
+
+/**
+ * Specify the maximum value this numeric type should be.
+ * @param value Maximum value
+ *
+ * @example
+ * ```typespec
+ * @maxValue(200)
+ * scalar Age is int32;
+ * ```
+ */
+extern dec maxValue(target: numeric | ModelProperty, value: numeric);
+
+/**
+ * Specify the minimum value this numeric type should be, exclusive of the given
+ * value.
+ * @param value Minimum value
+ *
+ * @example
+ * ```typespec
+ * @minValueExclusive(0)
+ * scalar distance is float64;
+ * ```
+ */
+extern dec minValueExclusive(target: numeric | ModelProperty, value: numeric);
+
+/**
+ * Specify the maximum value this numeric type should be, exclusive of the given
+ * value.
+ * @param value Maximum value
+ *
+ * @example
+ * ```typespec
+ * @maxValueExclusive(50)
+ * scalar distance is float64;
+ * ```
+ */
+extern dec maxValueExclusive(target: numeric | ModelProperty, value: numeric);
+
+/**
+ * Mark this string as a secret value that should be treated carefully to avoid exposure
+ *
+ * @example
+ * ```typespec
+ * @secret
+ * scalar Password is string;
+ * ```
+ */
+extern dec secret(target: string | ModelProperty);
+
+/**
+ * Attaches a tag to an operation, interface, or namespace. Multiple `@tag` decorators can be specified to attach multiple tags to a TypeSpec element.
+ * @param tag Tag value
+ */
+extern dec tag(target: Namespace | Interface | Operation, tag: string);
+
+/**
+ * Specifies how a templated type should name their instances.
+ * @param name name the template instance should take
+ * @formatArgs Model with key value used to interpolate the name
+ *
+ * @example
+ * ```typespec
+ * @friendlyName("{name}List", T)
+ * model List<T> {
+ *   value: T[];
+ *   nextLink: string;
+ * }
+ * ```
+ */
+extern dec friendlyName(target: unknown, name: string, formatArgs?: unknown);
+
+/**
+ * Provide a set of known values to a string type.
+ * @param values Known values enum.
+ *
+ * @example
+ * ```typespec
+ * @knownValues(KnownErrorCode)
+ * scalar ErrorCode extends string;
+ *
+ * enum KnownErrorCode {
+ *   NotFound,
+ *   Invalid,
+ * }
+ * ```
+ */
+extern dec knownValues(target: string | numeric | ModelProperty, values: Enum);
+
+/**
+ * Mark a model property as the key to identify instances of that type
+ *
+ * @example
+ * ```typespec
+ * model Pet {
+ *   @key id: string;
+ * }
+ * ```
+ */
+extern dec key(target: ModelProperty, altName?: string);
+
+/**
+ * Specify this operation is an overload of the given operation.
+ * @param overloadbase Base operation that should be a union of all overloads
+ *
+ * @example
+ * ```typespec
+ * op upload(data: string | bytes, @header contentType: "text/plain" | "application/octet-stream"): void;
+ * @overload(upload)
+ * op uploadString(data: string, @header contentType: "text/plain" ): void;
+ * @overload(upload)
+ * op uploadBytes(data: bytes, @header contentType: "application/octet-stream"): void;
+ * ```
+ */
+extern dec overload(target: Operation, overloadbase: Operation);
+
+/**
+ * Provide an alternative name for this type.
+ * @param targetName Projection target
+ * @param projectedName Alternative name
+ *
+ * @example
+ * ```typespec
+ * model Certificate {
+ *   @projectedName("json", "exp")
+ *   expireAt: int32;
+ * }
+ * ```
+ */
+extern dec projectedName(target: unknown, targetName: string, projectedName: string);
+
+/**
+ * Specify the property to be used to discriminate this type.
+ *
+ * @example
+ *
+ * ```typespec
+ * @discriminator("kind")
+ * union Pet{ cat: Cat, dog: Dog }
+ *
+ * model Cat {kind: "cat", meow: boolean}
+ * model Dog {kind: "dog", bark: boolean}
+ * ```
+ *
+ * ```typespec
+ * @discriminator("kind")
+ * model Pet{ kind: string }
+ *
+ * model Cat extends Pet {kind: "cat", meow: boolean}
+ * model Dog extends Pet  {kind: "dog", bark: boolean}
+ * ```
+ */
+extern dec discriminator(target: object | Union, propertyName: string);
+
+/**
+ * Indicates that a property is only considered to be present or applicable ("visible") with
+ * the in the given named contexts ("visibilities"). When a property has no visibilities applied
+ * to it, it is implicitly visible always.
+ *
+ * As far as the TypeSpec core library is concerned, visibilities are open-ended and can be arbitrary
+ * strings, but  the following visibilities are well-known to standard libraries and should be used
+ * with standard emitters that interpret them as follows:
+ *
+ * - "read": output of any operation.
+ * - "create": input to operations that create an entity..
+ * - "query": input to operations that read data.
+ * - "update": input to operations that update data.
+ * - "delete": input to operations that delete data.
+ *
+ * See also: [Automatic visibility](https://microsoft.github.io/typespec/standard-library/rest/operations#automatic-visibility)
+ *
+ * @example
+ *
+ * ```typespec
+ * model Dog {
+ *   // the service will generate an ID, so you don't need to send it.
+ *   @visibility("read") id: int32;
+ *   // the service will store this secret name, but won't ever return it
+ *   @visibility("create", "update") secretName: string;
+ *   // the regular name is always present
+ *   name: string;
+ * }
+ * ```
+ */
+extern dec visibility(target: ModelProperty, ...visibilities: string[]);
+
+/**
+ * Removes properties that are not considered to be present or applicable
+ * ("visible") in the given named contexts ("visibilities"). Can be used
+ * together with spread to effectively spread only visible properties into
+ * a new model.
+ *
+ * See also: [Automatic visibility](https://microsoft.github.io/typespec/standard-library/rest/operations#automatic-visibility)
+ *
+ * When using an emitter that applies visibility automatically, it is generally
+ * not necessary to use this decorator.
+ *
+ * @example
+ * ```typespec
+ * model Dog {
+ *   @visibility("read") id: int32;
+ *   @visibility("create", "update") secretName: string;
+ *   name: string;
+ * }
+ *
+ * // The spread operator will copy all the properties of Dog into DogRead,
+ * // and @withVisibility will then remove those that are not visible with
+ * // create or update visibility.
+ * //
+ * // In this case, the id property is removed, and the name and secretName
+ * // properties are kept.
+ * @withVisibility("create", "update")
+ * model DogCreateOrUpdate {
+ *   ...Dog;
+ * }
+ *
+ * // In this case the id and name properties are kept and the secretName property
+ * // is removed.
+ * @withVisibility("read")
+ * model DogRead {
+ *   ...Dog;
+ * }
+ * ```
+ */
+extern dec withVisibility(target: object, ...visibilities: string[]);
+extern dec withDefaultKeyVisibility(target: object, visibility: unknown);
+extern dec withUpdateableProperties(target: object);
+extern dec withoutDefaultValues(target: object);
+extern dec withoutOmittedProperties(target: object, omit: string | Union);
+
+//---------------------------------------------------------------------------
+// Debugging
+//---------------------------------------------------------------------------
+extern dec inspectType(target: unknown, text: string);
+extern dec inspectTypeName(target: unknown, text: string);

package/lib/lib.tsp

@@ -0,0 +1,158 @@
+namespace TypeSpec;
+
+/**
+ * Represent a byte array
+ */
+scalar bytes;
+
+/**
+ * A numeric type
+ */
+scalar numeric;
+
+/**
+ * A whole number
+ */
+scalar integer extends numeric;
+
+/**
+ * A number with decimal value
+ */
+scalar float extends numeric;
+
+/**
+ * A 64-bit integer. (`-9,223,372,036,854,775,808` to `9,223,372,036,854,775,807`)
+ */
+scalar int64 extends integer;
+
+/**
+ * A 32-bit integer. (`-2,147,483,648` to `2,147,483,647`)
+ */
+scalar int32 extends int64;
+
+/**
+ * A 16-bit integer. (`-32,768` to `32,767`)
+ */
+scalar int16 extends int32;
+
+/**
+ * A 8-bit integer. (`-128` to `127`)
+ */
+scalar int8 extends int16;
+
+/**
+ * A 64-bit unsigned integer (`0` to `18,446,744,073,709,551,615`)
+ */
+scalar uint64 extends integer;
+
+/**
+ * A 32-bit unsigned integer (`0` to `4,294,967,295`)
+ */
+scalar uint32 extends uint64;
+
+/**
+ * A 16-bit unsigned integer (`0` to `65,535`)
+ */
+scalar uint16 extends uint32;
+
+/**
+ * A 8-bit unsigned integer (`0` to `255`)
+ */
+scalar uint8 extends uint16;
+
+/**
+ * An integer that can be serialized to JSON (`−9007199254740991 (−(2^53 − 1))` to `9007199254740991 (2^53 − 1)` )
+ */
+scalar safeint extends int64;
+
+/**
+ * A 32 bit floating point number. (`±1.5 x 10^−45` to `±3.4 x 10^38`)
+ */
+scalar float64 extends float;
+
+/**
+ * A 32 bit floating point number. (`±5.0 × 10^−324` to `±1.7 × 10^308`)
+ */
+scalar float32 extends float64;
+
+/**
+ * A sequence of textual characters.
+ */
+scalar string;
+
+/**
+ * A date on a calendar without a time zone, e.g. "April 10th"
+ */
+scalar plainDate;
+
+/**
+ * A time on a clock without a time zone, e.g. "3:00 am"
+ */
+scalar plainTime;
+
+/**
+ * A date and time in a particular time zone, e.g. "April 10th at 3:00am in PST"
+ */
+scalar zonedDateTime;
+
+/**
+ * A duration/time period. e.g 5s, 10h
+ */
+scalar duration;
+
+/**
+ * Boolean with `true` and `false` values.
+ */
+scalar boolean;
+
+/**
+ * Represent any structured model.(With properties)
+ */
+model object {}
+
+/**
+ * Array model type, equivalent to `T[]`
+ */
+@indexer(integer, T)
+model Array<T> {}
+
+/**
+ * Model with string properties where all the properties have type `T`
+ */
+@indexer(string, T)
+model Record<T> {}
+
+/**
+ * Represent a URI string as described by https://url.spec.whatwg.org/#relative-url-string.
+ */
+@format("url")
+scalar url extends string;
+
+@doc("The template for adding optional properties.")
+@withOptionalProperties
+model OptionalProperties<T> {
+  ...T;
+}
+
+@doc("The template for adding updateable properties.")
+@withUpdateableProperties
+model UpdateableProperties<T> {
+  ...T;
+}
+
+@doc("The template for omitting properties.")
+@withoutOmittedProperties(TKeys)
+model OmitProperties<T, TKeys extends string> {
+  ...T;
+}
+
+@withoutDefaultValues
+model OmitDefaults<T> {
+  ...T;
+}
+
+@doc("The template for setting the default visibility of key properties.")
+@withDefaultKeyVisibility(Visibility)
+model DefaultKeyVisibility<T, Visibility extends string> {
+  ...T;
+}

package/lib/main.tsp

@@ -0,0 +1,4 @@
+import "./lib.tsp";
+import "./decorators.tsp";
+import "./reflection.tsp";
+import "./projected-names.tsp";

package/lib/projected-names.tsp

@@ -0,0 +1,94 @@
+// Set of projections consuming the @projectedName decorator
+#suppress "projections-are-experimental"
+projection op#target {
+  to(targetName) {
+    if hasProjectedName(self, targetName) {
+      self::rename(getProjectedName(self, targetName));
+    };
+  }
+  from(targetName) {
+    if hasProjectedName(self, targetName) {
+      self::rename(self::projectionBase::name);
+    };
+  }
+}
+
+#suppress "projections-are-experimental"
+projection interface#target {
+  to(targetName) {
+    if hasProjectedName(self, targetName) {
+      self::rename(getProjectedName(self, targetName));
+    };
+  }
+  from(targetName) {
+    if hasProjectedName(self, targetName) {
+      self::rename(self::projectionBase::name);
+    };
+  }
+}
+
+#suppress "projections-are-experimental"
+projection model#target {
+  to(targetName) {
+    if hasProjectedName(self, targetName) {
+      self::rename(getProjectedName(self, targetName));
+    };
+
+    self::properties::forEach((p) => {
+      if hasProjectedName(p, targetName) {
+        self::renameProperty(p::name, getProjectedName(p, targetName));
+      };
+    });
+  }
+  from(targetName) {
+    if hasProjectedName(self, targetName) {
+      self::rename(self::projectionBase::name);
+    };
+
+    self::projectionBase::properties::forEach((p) => {
+      if hasProjectedName(p, targetName) {
+        self::renameProperty(getProjectedName(p, targetName), p::name);
+      };
+    });
+  }
+}
+
+#suppress "projections-are-experimental"
+projection enum#target {
+  to(targetName) {
+    if hasProjectedName(self, targetName) {
+      self::rename(getProjectedName(self, targetName));
+    };
+
+    self::members::forEach((p) => {
+      if hasProjectedName(p, targetName) {
+        self::renameMember(p::name, getProjectedName(p, targetName));
+      };
+    });
+  }
+  from(targetName) {
+    if hasProjectedName(self, targetName) {
+      self::rename(self::projectionBase::name);
+    };
+
+    self::projectionBase::members::forEach((p) => {
+      if hasProjectedName(p, targetName) {
+        self::renameMember(getProjectedName(p, targetName), p::name);
+      };
+    });
+  }
+}
+
+#suppress "projections-are-experimental"
+projection union#target {
+  to(targetName) {
+    if hasProjectedName(self, targetName) {
+      self::rename(getProjectedName(self, targetName));
+    };
+  }
+  from(targetName) {
+    if hasProjectedName(self, targetName) {
+      self::rename(self::projectionBase::name);
+    };
+  }
+}

package/lib/reflection.tsp

@@ -0,0 +1,10 @@
+namespace TypeSpec.Reflection;
+
+model ModelProperty {}
+model Interface {}
+model Enum {}
+model EnumMember {}
+model Namespace {}
+model Operation {}
+model Union {}
+model UnionVariant {}