@typespec/compiler 0.44.0-dev.2 → 0.44.0-dev.20

package/lib/decorators.tsp

@@ -92,11 +92,11 @@ extern dec service(target: Namespace, options?: ServiceOptions);
  * }
  * ```
  */
-extern dec error(target: object);
+extern dec error(target: Model);
 
 /**
  * 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.
+ * This differs from the `@pattern` decorator which is meant to specify a regular expression while `@format` accepts a known format name.
  * The format names are open ended and are left to emitter to interpret.
  *
  * @param format format name.
@@ -242,7 +242,7 @@ 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
+ * @param formatArgs Model with key value used to interpolate the name
  *
  * @example
  * ```typespec
@@ -274,6 +274,7 @@ extern dec knownValues(target: string | numeric | ModelProperty, values: Enum);
 
 /**
  * Mark a model property as the key to identify instances of that type
+ * @param altName Name of the property. If not specified, the decorated property name is used.
  *
  * @example
  * ```typespec
@@ -316,6 +317,7 @@ extern dec projectedName(target: unknown, targetName: string, projectedName: str
 
 /**
  * Specify the property to be used to discriminate this type.
+ * @param propertyName The property name to use for discrimination
  *
  * @example
  *
@@ -335,7 +337,80 @@ extern dec projectedName(target: unknown, targetName: string, projectedName: str
  * model Dog extends Pet  {kind: "dog", bark: boolean}
  * ```
  */
-extern dec discriminator(target: object | Union, propertyName: string);
+extern dec discriminator(target: Model | Union, propertyName: string);
+
+/**
+ * Known encoding to use on utcDateTime or offsetDateTime
+ */
+enum DateTimeKnownEncoding {
+  /**
+   * RFC 3339 standard. https://www.ietf.org/rfc/rfc3339.txt
+   * Encode to string.
+   */
+  rfc3339: "rfc3339",
+  /**
+   * RFC 7231 standard. https://www.ietf.org/rfc/rfc7231.txt
+   * Encode to string.
+   */
+  rfc7231: "rfc7231",
+  /**
+   * Encode to integer
+   */
+  unixTimestamp: "unixTimestamp",
+}
+
+/**
+ * Known encoding to use on duration
+ */
+enum DurationKnownEncoding {
+  /**
+   * ISO8601 duration
+   */
+  ISO8601: "ISO8601",
+  /**
+   * Encode to integer or float
+   */
+  seconds: "seconds",
+}
+
+/**
+ * Known encoding to use on bytes
+ */
+enum BytesKnownEncoding {
+  /**
+   * ISO8601 duration
+   */
+  ISO8601: "ISO8601",
+  /**
+   * Encode to integer or float
+   */
+  seconds: "seconds",
+}
+
+/**
+ * Specify how to encode the target type.
+ * @param encoding Known name of an encoding.
+ * @param encodedAs What target type is this being encoded as. Default to string.
+ *
+ * @example offsetDateTime encoded with rfc7231
+ *
+ * ```tsp
+ * @encode("rfc7231")
+ * scalar myDateTime extends offsetDateTime;
+ * ```
+ *
+ * @example utcDateTime encoded with unixTimestamp
+ *
+ * ```tsp
+ * @encode("unixTimestamp", int32)
+ * scalar myDateTime extends unixTimestamp;
+ * ```
+ */
+extern dec encode(
+  target: Scalar | ModelProperty,
+  encoding: string | EnumMember,
+  encodedAs?: string | numeric
+);
 
 /**
  * Indicates that a property is only considered to be present or applicable ("visible") with
@@ -352,7 +427,9 @@ extern dec discriminator(target: object | Union, propertyName: string);
  * - "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)
+ * See also: [Automatic visibility](https://microsoft.github.io/typespec/standard-library/http/operations#automatic-visibility)
+ *
+ * @param visibilities List of visibilities which apply to this property.
  *
  * @example
  *
@@ -375,11 +452,13 @@ extern dec visibility(target: ModelProperty, ...visibilities: string[]);
  * 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)
+ * See also: [Automatic visibility](https://microsoft.github.io/typespec/standard-library/http/operations#automatic-visibility)
  *
  * When using an emitter that applies visibility automatically, it is generally
  * not necessary to use this decorator.
  *
+ * @param visibilities List of visibilities which apply to this property.
+ *
  * @example
  * ```typespec
  * model Dog {
@@ -407,14 +486,43 @@ extern dec visibility(target: ModelProperty, ...visibilities: string[]);
  * }
  * ```
  */
-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);
+extern dec withVisibility(target: Model, ...visibilities: string[]);
+
+/**
+ * Set the visibility of key properties in a model if not already set.
+ *
+ * @param visibility The desired default visibility value. If a key property already has a `visibility` decorator then the default visibility is not applied.
+ */
+extern dec withDefaultKeyVisibility(target: Model, visibility: unknown);
+
+/**
+ * Returns the model with non-updateable properties removed.
+ */
+extern dec withUpdateableProperties(target: Model);
+
+/**
+ * Returns the model with any default values removed.
+ */
+extern dec withoutDefaultValues(target: Model);
+
+/**
+ * Returns the model with the given properties omitted.
+ * @param omit List of properties to omit
+ */
+extern dec withoutOmittedProperties(target: Model, omit: string | Union);
 
 //---------------------------------------------------------------------------
 // Debugging
 //---------------------------------------------------------------------------
+
+/**
+ * A debugging decorator used to inspect a type.
+ * @param text Custom text to log
+ */
 extern dec inspectType(target: unknown, text: string);
+
+/**
+ * A debugging decorator used to inspect a type name.
+ * @param text Custom text to log
+ */
 extern dec inspectTypeName(target: unknown, text: string);

package/lib/lib.tsp

@@ -117,45 +117,69 @@ model object {}
 
 /**
  * Array model type, equivalent to `T[]`
+ * @template T The type of the array elements
  */
 @indexer(integer, T)
 model Array<T> {}
 
 /**
  * Model with string properties where all the properties have type `T`
+ * @template T The type of the properties
  */
 @indexer(string, T)
 model Record<T> {}
 
 /**
- * Represent a URI string as described by https://url.spec.whatwg.org/#relative-url-string.
+ * Represent a URL string as described by https://url.spec.whatwg.org/
  */
 @format("url")
 scalar url extends string;
 
+/**
+ * Represents a collection of optional properties.
+ * @template T An object whose spread properties are all optional.
+ */
 @doc("The template for adding optional properties.")
 @withOptionalProperties
 model OptionalProperties<T> {
   ...T;
 }
 
+/**
+ * Represents a collection of updateable properties.
+ * @template T An object whose spread properties are all updateable.
+ */
 @doc("The template for adding updateable properties.")
 @withUpdateableProperties
 model UpdateableProperties<T> {
   ...T;
 }
 
+/**
+ * Represents a collection of omitted properties.
+ * @template T An object whose properties are spread.
+ * @template TKeys The property keys to omit.
+ */
 @doc("The template for omitting properties.")
 @withoutOmittedProperties(TKeys)
 model OmitProperties<T, TKeys extends string> {
   ...T;
 }
 
+/**
+ * Represents a collection of properties with default values omitted.
+ * @template T An object whose spread property defaults are all omitted.
+ */
 @withoutDefaultValues
 model OmitDefaults<T> {
   ...T;
 }
 
+/**
+ * Applies a visiblity setting to a collection of properties.
+ * @template T An object whose properties are spread.
+ * @template Visibility The visibility to apply to all properties.
+ */
 @doc("The template for setting the default visibility of key properties.")
 @withDefaultKeyVisibility(Visibility)
 model DefaultKeyVisibility<T, Visibility extends string> {

package/lib/reflection.tsp

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typespec/compiler",
-  "version": "0.44.0-dev.2",
+  "version": "0.44.0-dev.20",
   "description": "TypeSpec Compiler Preview",
   "author": "Microsoft Corporation",
   "license": "MIT",
@@ -56,48 +56,47 @@
     "!dist/test/**"
   ],
   "dependencies": {
-    "@babel/code-frame": "~7.18.6",
-    "ajv": "~8.11.2",
+    "@babel/code-frame": "~7.21.4",
+    "ajv": "~8.12.0",
     "picocolors": "~1.0.0",
     "globby": "~13.1.1",
     "js-yaml": "~4.1.0",
-    "mkdirp": "~1.0.4",
+    "mkdirp": "~2.1.6",
     "mustache": "~4.2.0",
-    "prettier": "~2.8.1",
+    "prettier": "~2.8.7",
     "node-fetch": "3.2.8",
     "prompts": "~2.4.1",
-    "vscode-languageserver": "~8.0.2",
+    "vscode-languageserver": "~8.1.0",
     "vscode-languageserver-textdocument": "~1.0.1",
-    "yargs": "~17.6.2",
+    "yargs": "~17.7.1",
     "node-watch": "~0.7.1",
     "change-case": "~4.1.2"
   },
   "devDependencies": {
     "@types/babel__code-frame": "~7.0.3",
     "@types/js-yaml": "~4.0.1",
-    "@types/mkdirp": "~1.0.1",
     "@types/mocha": "~10.0.0",
     "@types/mustache": "~4.2.1",
     "@types/node": "~18.11.9",
     "@types/prettier": "2.6.0",
-    "@types/prompts": "~2.4.1",
-    "@types/yargs": "~17.0.2",
+    "@types/prompts": "~2.4.3",
+    "@types/yargs": "~17.0.24",
     "@typespec/eslint-config-typespec": ">=0.6.0",
     "@typespec/internal-build-utils": ">=0.4.0",
-    "eslint": "^8.12.0",
+    "eslint": "^8.36.0",
     "grammarkdown": "~3.2.0",
-    "mocha": "~10.1.0",
+    "mocha": "~10.2.0",
     "mocha-junit-reporter": "~2.2.0",
     "mocha-multi-reporters": "~1.5.1",
-    "c8": "~7.12.0",
+    "c8": "~7.13.0",
     "prettier-plugin-organize-imports": "~3.2.0",
     "source-map-support": "~0.5.19",
-    "rimraf": "~3.0.2",
+    "rimraf": "~5.0.0",
     "tmlanguage-generator": ">=0.4.0",
-    "typescript": "~4.9.3",
-    "vscode-oniguruma": "~1.6.1",
-    "vscode-textmate": "~8.0.0",
-    "sinon": "~15.0.1",
+    "typescript": "~5.0.2",
+    "vscode-oniguruma": "~1.7.0",
+    "vscode-textmate": "~9.0.0",
+    "sinon": "~15.0.3",
     "@types/sinon": "~10.0.13"
   },
   "peerDependencies": {},