@typespec/rest 0.41.0

package/lib/resource.tsp

@@ -0,0 +1,280 @@
+import "@typespec/http";
+import "../dist/src/index.js";
+import "../dist/src/internal-decorators.js";
+
+namespace TypeSpec.Rest.Resource;
+
+using TypeSpec.Http;
+
+@doc("The default error response for resource operations.")
+model ResourceError {
+  @doc("The error code.")
+  code: int32;
+
+  @doc("The error message.")
+  message: string;
+}
+
+@doc("Dynamically gathers keys of the model type T.")
+@copyResourceKeyParameters
+@friendlyName("{name}Key", T)
+model KeysOf<T> {}
+
+@doc("Dynamically gathers parent keys of the model type T.")
+@copyResourceKeyParameters("parent")
+@friendlyName("{name}ParentKey", T)
+model ParentKeysOf<T> {}
+
+@doc("Represents operation parameters for resource TResource.")
+model ResourceParameters<TResource extends object> {
+  ...KeysOf<TResource>;
+}
+
+@doc("Represents collection operation parameters for resource TResource.")
+model ResourceCollectionParameters<TResource extends object> {
+  ...ParentKeysOf<TResource>;
+}
+
+/**
+ * Represent the resource GET operation.
+ * @template TResource The resource model.
+ * @template TError The error response.
+ */
+@Private.validateHasKey(TResource)
+@Private.validateIsError(TError)
+interface ResourceRead<TResource extends object, TError> {
+  @autoRoute
+  @doc("Gets an instance of the resource.")
+  @readsResource(TResource)
+  get(...ResourceParameters<TResource>): TResource | TError;
+}
+
+@doc("Resource create operation completed successfully.")
+model ResourceCreatedResponse<T> {
+  ...CreatedResponse;
+  @body body: T;
+}
+
+interface ResourceCreateOrReplace<TResource extends object, TError> {
+  @autoRoute
+  @doc("Creates or replaces a instance of the resource.")
+  @createsOrReplacesResource(TResource)
+  createOrReplace(
+    ...ResourceParameters<TResource>,
+    @body resource: ResourceCreateModel<TResource>
+  ): TResource | ResourceCreatedResponse<TResource> | TError;
+}
+
+@friendlyName("{name}Update", TResource)
+model ResourceCreateOrUpdateModel<TResource extends object>
+  is OptionalProperties<UpdateableProperties<DefaultKeyVisibility<TResource, "read">>>;
+
+interface ResourceCreateOrUpdate<TResource extends object, TError> {
+  @autoRoute
+  @doc("Creates or update a instance of the resource.")
+  @createsOrUpdatesResource(TResource)
+  createOrUpdate(
+    ...ResourceParameters<TResource>,
+    @body resource: ResourceCreateOrUpdateModel<TResource>
+  ): TResource | ResourceCreatedResponse<TResource> | TError;
+}
+
+@friendlyName("{name}Create", TResource)
+model ResourceCreateModel<TResource extends object>
+  is UpdateableProperties<DefaultKeyVisibility<TResource, "read">>;
+
+interface ResourceCreate<TResource extends object, TError> {
+  @autoRoute
+  @doc("Creates a new instance of the resource.")
+  @createsResource(TResource)
+  create(
+    ...ResourceCollectionParameters<TResource>,
+    @body resource: ResourceCreateModel<TResource>
+  ): TResource | ResourceCreatedResponse<TResource> | TError;
+}
+
+@Private.validateHasKey(TResource)
+@Private.validateIsError(TError)
+interface ResourceUpdate<TResource extends object, TError> {
+  @autoRoute
+  @doc("Updates an existing instance of the resource.")
+  @updatesResource(TResource)
+  update(
+    ...ResourceParameters<TResource>,
+    @body properties: ResourceCreateOrUpdateModel<TResource>
+  ): TResource | TError;
+}
+
+@doc("Resource deleted successfully.")
+model ResourceDeletedResponse {
+  @doc("The status code.")
+  @statusCode
+  _: 200;
+}
+
+@Private.validateHasKey(TResource)
+@Private.validateIsError(TError)
+interface ResourceDelete<TResource extends object, TError> {
+  @autoRoute
+  @doc("Deletes an existing instance of the resource.")
+  @deletesResource(TResource)
+  delete(...ResourceParameters<TResource>): ResourceDeletedResponse | TError;
+}
+
+/**
+ * Structure for a paging response using `value` and `nextLink` to represent pagination.
+ * This only provides the model structure and not actual pagination support.
+ * See https://github.com/microsoft/typespec/issues/705 for general paging support.
+ */
+@doc("Paged response of {name} items", T)
+@friendlyName("{name}CollectionWithNextLink", T)
+model CollectionWithNextLink<T extends object> {
+  @doc("The items on this page")
+  value: T[];
+
+  @doc("The link to the next page of items")
+  nextLink?: ResourceLocation<T>;
+}
+
+interface ResourceList<TResource extends object, TError> {
+  @autoRoute
+  @doc("Lists all instances of the resource.")
+  @listsResource(TResource)
+  list(...ResourceCollectionParameters<TResource>): CollectionWithNextLink<TResource> | TError;
+}
+
+@Private.validateHasKey(TResource)
+@Private.validateIsError(TError)
+interface ResourceInstanceOperations<TResource extends object, TError>
+  extends ResourceRead<TResource, TError>,
+    ResourceUpdate<TResource, TError>,
+    ResourceDelete<TResource, TError> {}
+
+@Private.validateHasKey(TResource)
+@Private.validateIsError(TError)
+interface ResourceCollectionOperations<TResource extends object, TError>
+  extends ResourceCreate<TResource, TError>,
+    ResourceList<TResource, TError> {}
+
+@Private.validateHasKey(TResource)
+@Private.validateIsError(TError)
+interface ResourceOperations<TResource extends object, TError>
+  extends ResourceInstanceOperations<TResource, TError>,
+    ResourceCollectionOperations<TResource, TError> {}
+
+@Private.validateHasKey(TResource)
+@Private.validateIsError(TError)
+interface SingletonResourceRead<TSingleton extends object, TResource extends object, TError> {
+  @autoRoute
+  @doc("Gets the singleton resource.")
+  @segmentOf(TSingleton)
+  @readsResource(TSingleton)
+  Get(...ResourceParameters<TResource>): TSingleton | TError;
+}
+
+@Private.validateHasKey(TResource)
+@Private.validateIsError(TError)
+interface SingletonResourceUpdate<TSingleton extends object, TResource extends object, TError> {
+  @autoRoute
+  @doc("Updates the singleton resource.")
+  @segmentOf(TSingleton)
+  @updatesResource(TSingleton)
+  Update(
+    ...ResourceParameters<TResource>,
+
+    @body
+    properties: ResourceCreateOrUpdateModel<TSingleton>
+  ): TSingleton | TError;
+}
+
+interface SingletonResourceOperations<TSingleton extends object, TResource extends object, TError>
+  extends SingletonResourceRead<TSingleton, TResource, TError>,
+    SingletonResourceUpdate<TSingleton, TResource, TError> {}
+
+@Private.validateHasKey(TResource)
+@Private.validateIsError(TError)
+interface ExtensionResourceRead<TExtension extends object, TResource extends object, TError> {
+  @autoRoute
+  @doc("Gets an instance of the extension resource.")
+  @readsResource(TExtension)
+  Get(...ResourceParameters<TResource>, ...ResourceParameters<TExtension>): TExtension | TError;
+}
+
+interface ExtensionResourceCreateOrUpdate<
+  TExtension extends object,
+  TResource extends object,
+  TError
+> {
+  @autoRoute
+  @doc("Creates or update a instance of the extension resource.")
+  @createsOrUpdatesResource(TExtension)
+  CreateOrUpdate(
+    ...ResourceParameters<TResource>,
+    ...ResourceParameters<TExtension>,
+    @body resource: ResourceCreateOrUpdateModel<TExtension>
+  ): TExtension | ResourceCreatedResponse<TExtension> | TError;
+}
+
+interface ExtensionResourceCreate<TExtension extends object, TResource extends object, TError> {
+  @autoRoute
+  @doc("Creates a new instance of the extension resource.")
+  @createsResource(TExtension)
+  Create(
+    ...ResourceParameters<TResource>,
+    @body resource: ResourceCreateModel<TExtension>
+  ): TExtension | ResourceCreatedResponse<TExtension> | TError;
+}
+
+interface ExtensionResourceUpdate<TExtension extends object, TResource extends object, TError> {
+  @autoRoute
+  @doc("Updates an existing instance of the extension resource.")
+  @updatesResource(TExtension)
+  Update(
+    ...ResourceParameters<TResource>,
+    ...ResourceParameters<TExtension>,
+
+    @body
+    properties: ResourceCreateOrUpdateModel<TExtension>
+  ): TExtension | TError;
+}
+
+interface ExtensionResourceDelete<TExtension extends object, TResource extends object, TError> {
+  @autoRoute
+  @doc("Deletes an existing instance of the extension resource.")
+  @deletesResource(TExtension)
+  Delete(
+    ...ResourceParameters<TResource>,
+    ...ResourceParameters<TExtension>
+  ): ResourceDeletedResponse | TError;
+}
+
+interface ExtensionResourceList<TExtension extends object, TResource extends object, TError> {
+  @autoRoute
+  @doc("Lists all instances of the extension resource.")
+  @listsResource(TExtension)
+  List(
+    ...ResourceParameters<TResource>,
+    ...ResourceCollectionParameters<TExtension>
+  ): CollectionWithNextLink<TExtension> | TError;
+}
+
+interface ExtensionResourceInstanceOperations<
+  TExtension extends object,
+  TResource extends object,
+  TError
+>
+  extends ExtensionResourceRead<TExtension, TResource, TError>,
+    ExtensionResourceUpdate<TExtension, TResource, TError>,
+    ExtensionResourceDelete<TExtension, TResource, TError> {}
+
+interface ExtensionResourceCollectionOperations<
+  TExtension extends object,
+  TResource extends object,
+  TError
+>
+  extends ExtensionResourceCreate<TExtension, TResource, TError>,
+    ExtensionResourceList<TExtension, TResource, TError> {}
+
+interface ExtensionResourceOperations<TExtension extends object, TResource extends object, TError>
+  extends ExtensionResourceInstanceOperations<TExtension, TResource, TError>,
+    ExtensionResourceCollectionOperations<TExtension, TResource, TError> {}

package/lib/rest-decorators.tsp

@@ -0,0 +1,112 @@
+namespace TypeSpec.Rest;
+
+using TypeSpec.Reflection;
+
+/**
+ * This interface or operation should resolve its route automatically. To be used with resource types where the route segments area defined on the models.
+ *
+ * @example
+ *
+ * ```typespec
+ * @autoRoute
+ * interface Pets {
+ *   get(@segment("pets") @path id: string): void; //-> route: /pets/{id}
+ * }
+ * ```
+ */
+extern dec autoRoute(target: Interface | Operation);
+
+/**
+ * Defines the preceding path segment for a @path parameter in auto-generated routes.
+ *
+ * @param name Segment that will be inserted into the operation route before the path parameter's name field.
+ *
+ * @example
+ * @autoRoute
+ * interface Pets {
+ *   get(@segment("pets") @path id: string): void; //-> route: /pets/{id}
+ * }
+ */
+extern dec segment(target: object | ModelProperty | Operation, name: string);
+
+/**
+ * Returns the URL segment of a given model if it has `@segment` and `@key` decorator.
+ */
+extern dec segmentOf(target: Operation, type: object);
+
+/**
+ * Defines the separator string that is inserted before the action name in auto-generated routes for actions.
+ *
+ * @param seperator Seperator seperating the action segment from the rest of the url
+ */
+extern dec actionSeparator(target: object | ModelProperty | Operation, seperator: "/" | ":" | "/:");
+
+/**
+ * Mark this model as a resource type with a name.
+ *
+ * @param collectionName type's collection name
+ */
+extern dec resource(target: object, collectionName: string);
+
+/**
+ * Specify that this is a Read operation for a given resource.
+ *
+ * @param resource Resource marked with @resource
+ */
+extern dec readsResource(target: Operation, resourceType: object);
+
+/**
+ * Specify that this is a Create operation for a given resource.
+ *
+ * @param resource Resource marked with @resource
+ */
+extern dec createsResource(target: Operation, resourceType: object);
+
+/**
+ * Specify that this is a CreateOrReplace operation for a given resource.
+ *
+ * @param resource Resource marked with @resource
+ */
+extern dec createsOrReplacesResource(target: Operation, resourceType: object);
+
+/**
+ * Specify that this is a CreatesOrUpdate operation for a given resource.
+ *
+ * @param resource Resource marked with @resource
+ */
+extern dec createsOrUpdatesResource(target: Operation, resourceType: object);
+
+/**
+ * Specify that this is a Update operation for a given resource.
+ *
+ * @param resource Resource marked with @resource
+ */
+extern dec updatesResource(target: Operation, resourceType: object);
+
+/**
+ * Specify that this is a Delete operation for a given resource.
+ *
+ * @param resource Resource marked with @resource
+ */
+extern dec deletesResource(target: Operation, resourceType: object);
+
+/**
+ * Specify that this is a List operation for a given resource.
+ *
+ * @param resource Resource marked with @resource
+ */
+extern dec listsResource(target: Operation, resourceType: object);
+
+/**
+ * Specify this operation is an action. (Scopped to a resource item /pets/{petId}/my-action)
+ */
+extern dec action(target: Operation, name?: string);
+
+/**
+ * Specify this operation is a collection action. (Scopped to a resource, /pets/my-action)
+ */
+extern dec collectionAction(target: Operation, resourceType: object, name?: string);
+
+namespace Private {
+  extern dec resourceLocation(target: string, resourceType: object);
+}

package/lib/rest.tsp

@@ -0,0 +1,9 @@
+import "@typespec/http";
+import "./rest-decorators.tsp";
+import "./resource.tsp";
+
+namespace TypeSpec.Rest;
+
+@doc("The location of an instance of {name}", TResource)
+@Private.resourceLocation(TResource)
+scalar ResourceLocation<TResource extends object> extends url;

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@typespec/rest",
+  "version": "0.41.0",
+  "author": "Microsoft Corporation",
+  "description": "TypeSpec REST protocol binding",
+  "homepage": "https://microsoft.github.io/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/rest.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/http": "~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"
+  }
+}