@typespec/http 0.59.0-dev.1 → 0.59.0-dev.10

package/dist/src/uri-template.js

@@ -0,0 +1,41 @@
+const operators = ["+", "#", ".", "/", ";", "?", "&"];
+const uriTemplateRegex = /\{([^{}]+)\}|([^{}]+)/g;
+const expressionRegex = /([^:*]*)(?::(\d+)|(\*))?/;
+/**
+ * Parse a URI template according to [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3)
+ */
+export function parseUriTemplate(template) {
+    const parameters = [];
+    const segments = [];
+    const matches = template.matchAll(uriTemplateRegex);
+    for (let [_, expression, literal] of matches) {
+        if (expression) {
+            let operator;
+            if (operators.includes(expression[0])) {
+                operator = expression[0];
+                expression = expression.slice(1);
+            }
+            const items = expression.split(",");
+            for (const item of items) {
+                const match = item.match(expressionRegex);
+                const name = match[1];
+                const parameter = {
+                    name: name,
+                    operator,
+                    modifier: match[3]
+                        ? { type: "explode" }
+                        : match[2]
+                            ? { type: "prefix", value: Number(match[2]) }
+                            : undefined,
+                };
+                parameters.push(parameter);
+                segments.push(parameter);
+            }
+        }
+        else {
+            segments.push(literal);
+        }
+    }
+    return { segments, parameters };
+}
+//# sourceMappingURL=uri-template.js.map

package/dist/src/uri-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri-template.js","sourceRoot":"","sources":["../../src/uri-template.ts"],"names":[],"mappings":"AAAA,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAU,CAAC;AAc/D,MAAM,gBAAgB,GAAG,wBAAwB,CAAC;AAClD,MAAM,eAAe,GAAG,0BAA0B,CAAC;AAEnD;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,UAAU,GAA2B,EAAE,CAAC;IAC9C,MAAM,QAAQ,GAAsC,EAAE,CAAC;IACvD,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IACpD,KAAK,IAAI,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,IAAI,OAAO,EAAE,CAAC;QAC7C,IAAI,UAAU,EAAE,CAAC;YACf,IAAI,QAA8B,CAAC;YACnC,IAAI,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAQ,CAAC,EAAE,CAAC;gBAC7C,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAQ,CAAC;gBAChC,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACnC,CAAC;YAED,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACpC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,CAAE,CAAC;gBAC3C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBACtB,MAAM,SAAS,GAAyB;oBACtC,IAAI,EAAE,IAAI;oBACV,QAAQ;oBACR,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;wBAChB,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE;wBACrB,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;4BACR,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE;4BAC7C,CAAC,CAAC,SAAS;iBAChB,CAAC;gBACF,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBAC3B,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AAClC,CAAC"}

package/lib/decorators.tsp

@@ -48,8 +48,21 @@ model QueryOptions {
    */
   name?: string;
 
+  /**
+   * If true send each value in the array/object as a separate query parameter.
+   * Equivalent of adding `*` in the path parameter as per [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3)
+   *
+   *  | Style  | Explode | Uri Template   | Primitive value id = 5 | Array id = [3, 4, 5]    | Object id = {"role": "admin", "firstName": "Alex"} |
+   *  | ------ | ------- | -------------- | ---------------------- | ----------------------- | -------------------------------------------------- |
+   *  | simple | false   | `/users{?id}`  | `/users?id=5`          | `/users?id=3,4,5`       | `/users?id=role,admin,firstName,Alex`              |
+   *  | simple | true    | `/users{?id*}` | `/users?id=5`          | `/users?id=3&id=4&id=5` | `/users?role=admin&firstName=Alex`                 |
+   *
+   */
+  explode?: boolean;
+
   /**
    * Determines the format of the array if type array is used.
+   * **DEPRECATED**: use explode: true instead of `multi` or `@encode`
    */
   format?: "multi" | "csv" | "ssv" | "tsv" | "simple" | "form" | "pipes";
 }
@@ -63,15 +76,42 @@ model QueryOptions {
  *
  * ```typespec
  * op read(@query select: string, @query("order-by") orderBy: string): void;
- * op list(@query({name: "id", format: "multi"}) ids: string[]): void;
+ * op list(@query(#{name: "id", explode: true}) ids: string[]): void;
  * ```
  */
-extern dec query(target: ModelProperty, queryNameOrOptions?: string | QueryOptions);
+extern dec query(target: ModelProperty, queryNameOrOptions?: valueof string | QueryOptions);
+
+model PathOptions {
+  /** Name of the parameter in the uri template. */
+  name?: string;
+
+  /**
+   * When interpolating this parameter in the case of array or object expand each value using the given style.
+   * Equivalent of adding `*` in the path parameter as per [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3)
+   */
+  explode?: boolean;
+
+  /**
+   * Different interpolating styles for the path parameter.
+   * - `simple`: No special encoding.
+   * - `label`: Using `.` separator.
+   * - `matrix`: `;` as separator.
+   * - `fragment`: `#` as separator.
+   * - `path`: `/` as separator.
+   */
+  style?: "simple" | "label" | "matrix" | "fragment" | "path";
+
+  /**
+   * When interpolating this parameter do not encode reserved characters.
+   * Equivalent of adding `+` in the path parameter as per [RFC-6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3)
+   */
+  allowReserved?: boolean;
+}
 
 /**
  * Explicitly specify that this property is to be interpolated as a path parameter.
  *
- * @param paramName Optional name of the parameter in the url template.
+ * @param paramNameOrOptions Optional name of the parameter in the uri template or options.
  *
  * @example
  *
@@ -80,7 +120,7 @@ extern dec query(target: ModelProperty, queryNameOrOptions?: string | QueryOptio
  * op read(@path explicit: string, implicit: string): void;
  * ```
  */
-extern dec path(target: ModelProperty, paramName?: valueof string);
+extern dec path(target: ModelProperty, paramNameOrOptions?: valueof string | PathOptions);
 
 /**
  * Explicitly specify that this property type will be exactly the HTTP body.
@@ -220,19 +260,21 @@ extern dec delete(target: Operation);
 extern dec head(target: Operation);
 
 /**
- * Specify the endpoint for this service.
+ * Specify an endpoint for this service. Multiple `@server` decorators can be used to specify multiple endpoints.
+ *
  *  @param url Server endpoint
  *  @param description Description of the endpoint
  *  @param parameters Optional set of parameters used to interpolate the url.
  *
  * @example
+ *
  * ```typespec
  * @service
  * @server("https://example.com", "Single server endpoint")
  * namespace PetStore;
  * ```
  *
- * @example parameterized
+ * @example Parameterized
  *
  * ```typespec
  * @server("https://{region}.foo.com", "Regional endpoint", {
@@ -241,6 +283,16 @@ extern dec head(target: Operation);
  * })
  * ```
  *
+ * @example Multiple
+ * ```typespec
+ * @service
+ * @server("https://example.com", "Standard endpoint")
+ * @server("https://{project}.private.example.com", "Private project endpoint", {
+ *   project: string;
+ * })
+ * namespace PetStore;
+ * ```
+ *
  */
 extern dec server(
   target: Namespace,
@@ -270,22 +322,28 @@ extern dec useAuth(target: Namespace | Interface | Operation, auth: {} | Union |
 extern dec includeInapplicableMetadataInPayload(target: unknown, value: valueof boolean);
 
 /**
- * Defines the relative route URI for the target operation
- *
- * The first argument should be a URI fragment that may contain one or more path parameter fields.
- * If the namespace or interface that contains the operation is also marked with a `@route` decorator,
- * it will be used as a prefix to the route URI of the operation.
+ * Defines the relative route URI template for the target operation as defined by [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3)
  *
  * `@route` can only be applied to operations, namespaces, and interfaces.
  *
- * @param path Relative route path. Cannot include query parameters.
- * @param options Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations.
+ * @param uriTemplate Uri template for this operation.
+ * @param options _DEPRECATED_ Set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations.
  *
- * @example
+ * @example Simple path parameter
  *
  * ```typespec
- * @route("/widgets")
- * op getWidget(@path id: string): Widget;
+ * @route("/widgets/{id}") op getWidget(@path id: string): Widget;
+ * ```
+ *
+ * @example Reserved characters
+ * ```typespec
+ * @route("/files{+path}") op getFile(@path path: string): bytes;
+ * ```
+ *
+ * @example Query parameter
+ * ```typespec
+ * @route("/files") op list(select?: string, filter?: string): Files[];
+ * @route("/files{?select,filter}") op listFullUriTemplate(select?: string, filter?: string): Files[];
  * ```
  */
 extern dec route(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typespec/http",
-  "version": "0.59.0-dev.1",
+  "version": "0.59.0-dev.10",
   "author": "Microsoft Corporation",
   "description": "TypeSpec HTTP protocol binding",
   "homepage": "https://github.com/microsoft/typespec",
@@ -45,12 +45,12 @@
     "@types/node": "~18.11.19",
     "@typespec/compiler": "~0.58.1 || >=0.59.0-dev <0.59.0",
     "@typespec/library-linter": "~0.58.0 || >=0.59.0-dev <0.59.0",
-    "@vitest/coverage-v8": "^1.6.0",
-    "@vitest/ui": "^1.6.0",
+    "@vitest/coverage-v8": "^2.0.4",
+    "@vitest/ui": "^2.0.4",
     "c8": "^10.1.2",
-    "rimraf": "~5.0.7",
-    "typescript": "~5.5.3",
-    "vitest": "^1.6.0",
+    "rimraf": "~6.0.1",
+    "typescript": "~5.5.4",
+    "vitest": "^2.0.4",
     "@typespec/tspd": "~0.46.0"
   },
   "dependencies": {},