feat: new @typespec/rest-api library with standard REST terminology

packages/rest-api/generated-defs/TypeSpec.RestApi.ts

@@ -0,0 +1,155 @@
+import type {
+  DecoratorContext,
+  DecoratorValidatorCallbacks,
+  Model,
+  Operation,
+} from "@typespec/compiler";
+
+/**
+ * Mark a model as a REST resource. A resource represents an entity that can be
+ * identified by a unique key and managed through standard CRUD operations.
+ *
+ * @param collectionName The URL path segment used for the resource collection (e.g., "users", "orders").
+ */
+export type ResourceDecorator = (
+  context: DecoratorContext,
+  target: Model,
+  collectionName: string,
+) => DecoratorValidatorCallbacks | void;
+
+/**
+ * Establish a parent-child relationship between resources, creating nested URL paths.
+ * For example, marking `Comment` with `@parentResource(Post)` produces paths like
+ * `/posts/{postId}/comments/{commentId}`.
+ *
+ * @param parent The parent resource model type.
+ */
+export type ParentResourceDecorator = (
+  context: DecoratorContext,
+  target: Model,
+  parent: Model,
+) => DecoratorValidatorCallbacks | void;
+
+/**
+ * Mark an operation as reading a single resource instance (HTTP GET on a resource).
+ * The operation will be mapped to `GET /<collection>/{id}`.
+ *
+ * @param resourceType The resource model type this operation reads.
+ */
+export type ReadsDecorator = (
+  context: DecoratorContext,
+  target: Operation,
+  resourceType: Model,
+) => DecoratorValidatorCallbacks | void;
+
+/**
+ * Mark an operation as creating a new resource in a collection (HTTP POST).
+ * The operation will be mapped to `POST /<collection>`.
+ *
+ * @param resourceType The resource model type this operation creates.
+ */
+export type CreatesDecorator = (
+  context: DecoratorContext,
+  target: Operation,
+  resourceType: Model,
+) => DecoratorValidatorCallbacks | void;
+
+/**
+ * Mark an operation as creating or replacing a resource (HTTP PUT).
+ * The operation will be mapped to `PUT /<collection>/{id}`.
+ *
+ * @param resourceType The resource model type this operation creates or replaces.
+ */
+export type CreatesOrReplacesDecorator = (
+  context: DecoratorContext,
+  target: Operation,
+  resourceType: Model,
+) => DecoratorValidatorCallbacks | void;
+
+/**
+ * Mark an operation as updating a resource (HTTP PATCH).
+ * The operation will be mapped to `PATCH /<collection>/{id}`.
+ *
+ * @param resourceType The resource model type this operation updates.
+ */
+export type UpdatesDecorator = (
+  context: DecoratorContext,
+  target: Operation,
+  resourceType: Model,
+) => DecoratorValidatorCallbacks | void;
+
+/**
+ * Mark an operation as deleting a resource (HTTP DELETE).
+ * The operation will be mapped to `DELETE /<collection>/{id}`.
+ *
+ * @param resourceType The resource model type this operation deletes.
+ */
+export type DeletesDecorator = (
+  context: DecoratorContext,
+  target: Operation,
+  resourceType: Model,
+) => DecoratorValidatorCallbacks | void;
+
+/**
+ * Mark an operation as listing resources from a collection (HTTP GET on a collection).
+ * The operation will be mapped to `GET /<collection>`.
+ *
+ * @param resourceType The resource model type this operation lists.
+ */
+export type ListsDecorator = (
+  context: DecoratorContext,
+  target: Operation,
+  resourceType: Model,
+) => DecoratorValidatorCallbacks | void;
+
+/**
+ * Define a custom action on a resource instance.
+ * Creates an endpoint like `POST /<collection>/{id}/<actionName>`.
+ *
+ * @param name The URL path segment for the action. If not provided, the operation name is used.
+ */
+export type ActionDecorator = (
+  context: DecoratorContext,
+  target: Operation,
+  name?: string,
+) => DecoratorValidatorCallbacks | void;
+
+/**
+ * Define a custom action on a resource collection.
+ * Creates an endpoint like `POST /<collection>/<actionName>`.
+ *
+ * @param resourceType The resource model type this action operates on.
+ * @param name The URL path segment for the action. If not provided, the operation name is used.
+ */
+export type CollectionActionDecorator = (
+  context: DecoratorContext,
+  target: Operation,
+  resourceType: Model,
+  name?: string,
+) => DecoratorValidatorCallbacks | void;
+
+/**
+ * Copy the resource key parameters onto a model.
+ * Used internally by `KeysOf` and `ParentKeysOf` templates.
+ *
+ * @param filter If "parent", only copies parent resource keys.
+ */
+export type CopyResourceKeyParametersDecorator = (
+  context: DecoratorContext,
+  target: Model,
+  filter?: string,
+) => DecoratorValidatorCallbacks | void;
+
+export type TypeSpecRestApiDecorators = {
+  resource: ResourceDecorator;
+  parentResource: ParentResourceDecorator;
+  reads: ReadsDecorator;
+  creates: CreatesDecorator;
+  createsOrReplaces: CreatesOrReplacesDecorator;
+  updates: UpdatesDecorator;
+  deletes: DeletesDecorator;
+  lists: ListsDecorator;
+  action: ActionDecorator;
+  collectionAction: CollectionActionDecorator;
+  copyResourceKeyParameters: CopyResourceKeyParametersDecorator;
+};

packages/rest-api/generated-defs/TypeSpec.RestApi.ts-test.ts

@@ -0,0 +1,10 @@
+// An error in the imports would mean that the decorator is not exported or
+// doesn't have the right name.
+
+import { $decorators } from "@typespec/rest-api";
+import type { TypeSpecRestApiDecorators } from "./TypeSpec.RestApi.js";
+
+/**
+ * An error here would mean that the exported decorator is not using the same signature. Make sure to have export const $decName: DecNameDecorator = (...) => ...
+ */
+const _: TypeSpecRestApiDecorators = $decorators["TypeSpec.RestApi"];

packages/rest-api/lib/decorators.tsp

@@ -0,0 +1,94 @@
+using TypeSpec.Http;
+using TypeSpec.Reflection;
+
+namespace TypeSpec.RestApi;
+
+/**
+ * Mark a model as a REST resource. A resource represents an entity that can be
+ * identified by a unique key and managed through standard CRUD operations.
+ *
+ * @param collectionName The URL path segment used for the resource collection (e.g., "users", "orders").
+ */
+extern dec resource(target: Model, collectionName: valueof string);
+
+/**
+ * Establish a parent-child relationship between resources, creating nested URL paths.
+ * For example, marking `Comment` with `@parentResource(Post)` produces paths like
+ * `/posts/{postId}/comments/{commentId}`.
+ *
+ * @param parent The parent resource model type.
+ */
+extern dec parentResource(target: Model, parent: Model);
+
+/**
+ * Mark an operation as reading a single resource instance (HTTP GET on a resource).
+ * The operation will be mapped to `GET /<collection>/{id}`.
+ *
+ * @param resourceType The resource model type this operation reads.
+ */
+extern dec reads(target: Operation, resourceType: Model);
+
+/**
+ * Mark an operation as creating a new resource in a collection (HTTP POST).
+ * The operation will be mapped to `POST /<collection>`.
+ *
+ * @param resourceType The resource model type this operation creates.
+ */
+extern dec creates(target: Operation, resourceType: Model);
+
+/**
+ * Mark an operation as creating or replacing a resource (HTTP PUT).
+ * The operation will be mapped to `PUT /<collection>/{id}`.
+ *
+ * @param resourceType The resource model type this operation creates or replaces.
+ */
+extern dec createsOrReplaces(target: Operation, resourceType: Model);
+
+/**
+ * Mark an operation as updating a resource (HTTP PATCH).
+ * The operation will be mapped to `PATCH /<collection>/{id}`.
+ *
+ * @param resourceType The resource model type this operation updates.
+ */
+extern dec updates(target: Operation, resourceType: Model);
+
+/**
+ * Mark an operation as deleting a resource (HTTP DELETE).
+ * The operation will be mapped to `DELETE /<collection>/{id}`.
+ *
+ * @param resourceType The resource model type this operation deletes.
+ */
+extern dec deletes(target: Operation, resourceType: Model);
+
+/**
+ * Mark an operation as listing resources from a collection (HTTP GET on a collection).
+ * The operation will be mapped to `GET /<collection>`.
+ *
+ * @param resourceType The resource model type this operation lists.
+ */
+extern dec lists(target: Operation, resourceType: Model);
+
+/**
+ * Define a custom action on a resource instance.
+ * Creates an endpoint like `POST /<collection>/{id}/<actionName>`.
+ *
+ * @param name The URL path segment for the action. If not provided, the operation name is used.
+ */
+extern dec action(target: Operation, name?: valueof string);
+
+/**
+ * Define a custom action on a resource collection.
+ * Creates an endpoint like `POST /<collection>/<actionName>`.
+ *
+ * @param resourceType The resource model type this action operates on.
+ * @param name The URL path segment for the action. If not provided, the operation name is used.
+ */
+extern dec collectionAction(target: Operation, resourceType: Model, name?: valueof string);
+
+/**
+ * Copy the resource key parameters onto a model.
+ * Used internally by `KeysOf` and `ParentKeysOf` templates.
+ *
+ * @param filter If "parent", only copies parent resource keys.
+ */
+extern dec copyResourceKeyParameters(target: Model, filter?: valueof string);

packages/rest-api/lib/main.tsp

@@ -0,0 +1,6 @@
+import "@typespec/http";
+import "./decorators.tsp";
+import "./resources.tsp";
+import "../dist/src/tsp-index.js";
+
+using TypeSpec.Http;