@typespec/http 0.41.0

package/lib/http-decorators.tsp

@@ -0,0 +1,206 @@
+namespace TypeSpec.Http;
+
+using TypeSpec.Reflection;
+
+/**
+ * Header options.
+ */
+model HeaderOptions {
+  /**
+   * Name of the header when sent over http.
+   */
+  name?: string;
+  /**
+   * Determines the format of the array if type array is used.
+   */
+  format?: "csv";
+}
+
+/**
+ * Specify this property is to be sent or received as an http header.
+ *
+ * @param headerNameOrOptions Optional name of the header when sent over http or header options.
+ *
+ * @example
+ *
+ * ```typespec
+ * op read(@header accept: string): {@header("E-Tag") eTag: string};
+ * op create(@header({name: "X-Color", format: "csv"}) colors: string[]): void;
+ * ```
+ */
+extern dec header(target: ModelProperty, headerNameOrOptions?: string | HeaderOptions);
+
+/**
+ * Query parameter options.
+ */
+model QueryOptions {
+  /**
+   * Name of the query when included in the url.
+   */
+  name?: string;
+  /**
+   * Determines the format of the array if type array is used.
+   */
+  format?: "multi" | "csv";
+}
+
+/**
+ * Specify this property is to be sent as a query parameter.
+ *
+ * @param queryNameOrOptions Optional name of the query when included in the url or query parameter options.
+ *
+ * @example
+ *
+ * ```typespec
+ * op read(@query select: string, @query("order-by") orderBy: string): void;
+ * op list(@query({name: "id", format: "multi"}) ids: string[]): void;
+ * ```
+ */
+extern dec query(target: ModelProperty, queryNameOrOptions?: string | QueryOptions);
+
+/**
+ * Explicitly specify that this property is to be interpolated as a path parameter.
+ *
+ * @param paramName Optional name of the parameter in the url template.
+ *
+ * @example
+ *
+ * ```typespec
+ * @route("/read/{explicit}/things/{implicit}")
+ * op read(@path explicit: string, implicit: string): void;
+ * ```
+ */
+extern dec path(target: ModelProperty, paramName?: string);
+
+/**
+ * Explicitly specify that this property is to be set as the body
+ *
+ * @example
+ *
+ * ```typespec
+ * op upload(@body image: bytes): void;
+ * op download(): {@body image: bytes};
+ * ```
+ */
+extern dec body(target: ModelProperty);
+
+/**
+ * Specify the status code for this response. Property type must be a status code integer or a union of status code integer.
+ *
+ * @example
+ *
+ * ```typespec
+ * op read(): {@statusCode: 200, @body pet: Pet}
+ * op create(): {@statusCode: 201 | 202}
+ * ```
+ */
+extern dec statusCode(target: ModelProperty);
+
+/**
+ * Specify the http verb for the target operation to be `GET`.
+ *
+ * @example
+ *
+ * ```typespec
+ * @get op read(): string
+ * ```
+ */
+extern dec get(target: Operation);
+
+/**
+ * Specify the http verb for the target operation to be `PUT`.
+ *
+ * @example
+ *
+ * ```typespec
+ * @put op set(pet: Pet): void
+ * ```
+ */
+extern dec put(target: Operation);
+
+/**
+ * Specify the http verb for the target operation to be `POST`.
+ *
+ * @example
+ *
+ * ```typespec
+ * @post op create(pet: Pet): void
+ * ```
+ */
+extern dec post(target: Operation);
+
+/**
+ * Specify the http verb for the target operation to be `PATCH`.
+ *
+ * @example
+ *
+ * ```typespec
+ * @patch op update(pet: Pet): void
+ * ```
+ */
+extern dec patch(target: Operation);
+
+/**
+ * Specify the http verb for the target operation to be `DELETE`.
+ *
+ * @example
+ *
+ * ```typespec
+ * @delete op set(petId: string): void
+ * ```
+ */
+extern dec delete(target: Operation);
+
+/**
+ * Specify the http verb for the target operation to be `HEAD`.
+ * @example
+ *
+ * ```typespec
+ * @head op ping(petId: string): void
+ * ```
+ */
+extern dec head(target: Operation);
+
+/**
+ * Specify the endpoint for this service.
+ *  @param url Server endpoint
+ *  @param url 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
+ *
+ * ```typespec
+ * @server("https://{region}.foo.com", "Regional endpoint", {
+ *   @doc("Region name")
+ *   region?: string = "westus",
+ * })
+ * ```
+ *
+ */
+extern dec server(target: Namespace, url: string, description: string, parameters?: object);
+
+/**
+ * Specify this service authentication. See the [documentation in the Http library][https://microsoft.github.io/typespec/standard-library/rest/authentication] for full details.
+ *
+ * @param auth Authentication configuration. Can be a single security scheme, a union(either option is valid authentication) or a tuple(Must use all authentication together)
+ * @example
+ *
+ * ```typespec
+ * @service
+ * @useAuth(BasicAuth)
+ * namespace PetStore;
+ * ```
+ */
+extern dec useAuth(target: Namespace, auth: object | Union | object[]);
+
+/**
+ * Specify if inapplicable metadata should be included in the payload for the given entity.
+ */
+extern dec includeInapplicableMetadataInPayload(target: unknown, value: boolean);

package/lib/http.tsp

@@ -0,0 +1,57 @@
+import "../dist/src/index.js";
+import "./http-decorators.tsp";
+import "./auth.tsp";
+
+namespace TypeSpec.Http;
+
+using Private;
+
+model Response<Status> {
+  @doc("The status code.")
+  @statusCode
+  statusCode: Status;
+}
+
+/**
+ * Defines a model with a single property of the given type, marked with `@body`.
+ *
+ * This can be useful in situations where you cannot use a bare T as the body
+ * and it is awkward to add a property.
+ */
+model Body<T> {
+  @body
+  body: T;
+}
+
+model LocationHeader {
+  @doc("The Location header contains the URL where the status of the long running operation can be checked.")
+  @header
+  location: string;
+}
+
+// Don't put @doc on these, change `getStatusCodeDescription` implementation
+// to update the default descriptions for these status codes. This ensures
+// that we get consistent emit between different ways to spell the same
+// responses in TypeSpec.
+model OkResponse is Response<200>;
+model CreatedResponse is Response<201>;
+model AcceptedResponse is Response<202>;
+model NoContentResponse is Response<204>;
+model MovedResponse is Response<301> {
+  ...LocationHeader;
+}
+model NotModifiedResponse is Response<304>;
+model BadRequestResponse is Response<400>;
+model UnauthorizedResponse is Response<401>;
+model ForbiddenResponse is Response<403>;
+model NotFoundResponse is Response<404>;
+model ConflictResponse is Response<409>;
+
+/**
+ * Produces a new model with the same properties as T, but with `@query`,
+ *`@header`, `@body`, and `@path` decorators removed from all properties.
+ */
+@plainData
+model PlainData<T> {
+  ...T;
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@typespec/http",
+  "version": "0.41.0",
+  "author": "Microsoft Corporation",
+  "description": "TypeSpec HTTP protocol binding",
+  "homepage": "https://github.com/Microsoft/typespec",
+  "readme": "https://github.com/Microsoft/typespec/blob/master/README.md",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Microsoft/typespec.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Microsoft/typespec/issues"
+  },
+  "keywords": [
+    "typespec"
+  ],
+  "type": "module",
+  "main": "dist/src/index.js",
+  "tspMain": "lib/http.tsp",
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./testing": "./dist/src/testing/index.js"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/src/index.d.ts"
+      ],
+      "testing": [
+        "./dist/src/testing/index.d.ts"
+      ]
+    }
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "lib/*.tsp",
+    "dist/**",
+    "!dist/test/**"
+  ],
+  "peerDependencies": {
+    "@typespec/compiler": "~0.41.0"
+  },
+  "devDependencies": {
+    "@types/mocha": "~10.0.0",
+    "@types/node": "~18.11.9",
+    "@typespec/compiler": "~0.41.0",
+    "@typespec/eslint-config-typespec": "~0.6.0",
+    "@typespec/library-linter": "~0.41.0",
+    "@typespec/eslint-plugin": "~0.41.0",
+    "eslint": "^8.12.0",
+    "mocha": "~10.1.0",
+    "mocha-junit-reporter": "~2.2.0",
+    "mocha-multi-reporters": "~1.5.1",
+    "c8": "~7.12.0",
+    "rimraf": "~3.0.2",
+    "typescript": "~4.9.3"
+  },
+  "scripts": {
+    "clean": "rimraf ./dist ./temp",
+    "build": "tsc -p . && npm run lint-typespec-library",
+    "watch": "tsc -p . --watch",
+    "lint-typespec-library": "tsp compile . --warn-as-error --import @typespec/library-linter --no-emit",
+    "test": "mocha",
+    "test-official": "c8 mocha --forbid-only --reporter mocha-multi-reporters",
+    "lint": "eslint . --ext .ts --max-warnings=0",
+    "lint:fix": "eslint . --fix --ext .ts"
+  }
+}