@nxgt/typespec 0.11.0 → 0.13.0

package/docs/guide/operation-ids.md

@@ -116,7 +116,7 @@ tells a cache, a proxy or a retry that the request is safe. An operation
 | Verb | Sent with |
 | --- | --- |
 | `list`, `read`, `find`, `count`, `get` | `GET` or `HEAD` |
-| `search`, `query` | `GET` or `POST`, for criteria too large for a query string |
+| `search`, `query` | `GET`, `POST`, or a `POST` marked [`@queryMethod`](#a-query-in-openapi-32), for criteria too large for a query string |
 | `create`, `createMany` | `POST` |
 | `update`, `updateMany` | `PUT` or `PATCH` |
 | `patch` | `PATCH` |
@@ -171,10 +171,67 @@ Not checked:
   whatever it says;
 - an operation `@operationIds` does not name.
 
-`QUERY`, the HTTP method for a safe request with a body, is not one of
-`search` and `query`'s methods yet: `@typespec/http` 1.16 declares only
-`GET`, `PUT`, `POST`, `PATCH`, `DELETE` and `HEAD`
-([roadmap](../roadmap.md#later)).
+## A QUERY in OpenAPI 3.2
+
+`QUERY` is the HTTP method for a safe request with a body, and
+`@typespec/http` 1.17 declares only `GET`, `PUT`, `POST`, `PATCH`, `DELETE`
+and `HEAD`. `@queryMethod` marks a `@post` as the `QUERY` it stands for:
+
+```tsp
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+@service
+@operationIds
+namespace Shop;
+
+model UserCriteria {
+  names: string[];
+}
+
+@route("/users")
+interface Users {
+  @post @queryMethod @route("/search")
+  search(@body criteria: UserCriteria): string[]; // searchUsers
+}
+```
+
+With the emitter `@nxgt/typespec` and OpenAPI 3.2 the document gets a real
+`QUERY`, the only version that has one:
+
+```yaml
+/users/search:
+  query:
+    operationId: searchUsers
+```
+
+Anything else is an error, not a `POST` with a mark: an older version in
+`openapi-versions` (or none, which defaults to 3.0) is `query-method-needs-openapi-3.2`, and the plain
+`@typespec/openapi3` emitter is `query-method-needs-nxgt-emitter`
+([troubleshooting](../troubleshooting.md)). `@nxgt/openapi-codegen`
+generates `method: 'query'` from it
+([TypeSpec](https://github.com/softistx/nxgt-http/blob/develop/packages/openapi-codegen/docs/guide/typespec.md)).
+The emitter and what a real `QUERY` needs are in [The emitter](emitter.md).
+When `@typespec/http` declares `QUERY`, the decorator is what changes, not
+your spec ([roadmap](../roadmap.md#later)).
+
+| Case | Result |
+| --- | --- |
+| `search` or `query` marked | no warning: a `QUERY` is one of their methods |
+| `findById`, `create` or another verb marked | `verb-method-mismatch`, with the method `QUERY`: `findById is sent with QUERY, where its verb find is sent with GET or HEAD` |
+| a name that is not a verb, marked | nothing to check |
+| marked and not a `@post` | the error `query-method-not-post` |
+
+```text
+error @nxgt/typespec/query-method-not-post: list is marked @queryMethod and sent with GET: @queryMethod marks a @post, which @nxgt/typespec writes as a QUERY in OpenAPI 3.2. Make it a @post.
+```
+
+A search that answers an array also meets the linter's `list-returns-page`;
+return a `Page<Item>`, as `search` above could
+(`Page<User> | BadRequest`).
 
 ## The resource
 

package/docs/roadmap.md

@@ -16,16 +16,35 @@ Nothing in progress.
 
 ## Later
 
-- **`QUERY` for `search` and `query`.** The HTTP `QUERY` method, a safe
-  request with a body, joins `GET` and `POST` as a method of `search` and
-  `query` once `@typespec/http` declares it. `@nxgt/openapi-codegen`
-  already reads an OpenAPI 3.2 `query` operation.
+- **A `QUERY` without a mark.** A real `QUERY` is done: the emitter
+  `@nxgt/typespec` writes a `@queryMethod` as a `query` operation in OpenAPI
+  3.2. What is left is a native `@query`-like verb, once `@typespec/http`
+  declares `QUERY`, so a spec stops needing `@post @queryMethod` and does not
+  otherwise change.
 - **`ETag` and conditional requests.** `ETag`, with `If-None-Match` and
   `If-Match`, once the `@nxgt/*` packages send one the same way. The
   optimistic lock is the body's `version` today (`Versioned`).
 
 ## Shipped
 
+### 0.13.0
+
+- **The emitter `@nxgt/typespec`.** `emit: ["@nxgt/typespec"]` runs
+  `@typespec/openapi3` with the same options and files, and in an OpenAPI 3.2
+  document writes each `@queryMethod` as a real `query` operation, which
+  `@nxgt/openapi-codegen` generates as `method: 'query'` and
+  `@nxgt/openapi-hono` serves. A marked operation with an older version, or
+  with plain `@typespec/openapi3`, is an error. `@typespec/openapi3` is an optional peer, and the
+  `tsp init` template emits with the new emitter.
+
+### 0.12.0
+
+- **`@queryMethod`, a `QUERY` sent as a `POST`.** The decorator marks a
+  `@post` with `x-nxgt-method: query`, which `@nxgt/openapi-codegen` reads,
+  and `search` and `query` accept it: a safe request with a body, with every
+  server, proxy and `fetch`. On anything but a `@post` it is the error
+  `query-method-not-post`.
+
 ### 0.11.0
 
 - **Request body aliases.** `CreateRequest<T>`, `UpdateRequest<T>` and

package/docs/troubleshooting.md

@@ -293,6 +293,104 @@ Or silence that one operation with a reason:
 @post @route("/find") findById(@body id: uuid): User;
 ```
 
+## `list is marked @queryMethod and sent with GET: @queryMethod marks a @post, which @nxgt/typespec writes as a QUERY in OpenAPI 3.2. Make it a @post.`
+
+**When:** an error, `query-method-not-post`: an operation marked
+`@queryMethod` is sent with a method other than `POST`. The method may be
+implicit, `@get` or none.
+
+```tsp
+@route("/users")
+interface Users {
+  @get @queryMethod list(): string[];
+}
+```
+
+**Why:** `@queryMethod` stands for a `QUERY` that `@typespec/http` cannot
+declare, so the spec writes a `@post` and the emitter writes the `QUERY`
+([The emitter](guide/emitter.md)); on a `GET`, a `PUT` or a `DELETE` it has
+nothing to stand for.
+
+**Fix:** make it a `@post`, with the criteria in the body:
+
+```tsp
+@post @queryMethod @route("/search") search(@body names: string[]): string[];
+```
+
+Or drop `@queryMethod`: a `GET` needs no mark. More, in
+[Operation ids](guide/operation-ids.md#a-query-in-openapi-32).
+
+## `search is marked @queryMethod: only OpenAPI 3.2 has a QUERY operation, and openapi-versions asks for 3.1.0. Emit 3.2 only, or take off @queryMethod.`
+
+**When:** `tsp compile` with the emitter `@nxgt/typespec`; the error
+`query-method-needs-openapi-3.2` on each marked operation. Nothing is emitted.
+
+**Why:** OpenAPI 3.1 and older have no `QUERY` operation, and the emitter
+does not turn the operation into a `POST`. `openapi-versions` holds a version
+below 3.2, or is unset, which means 3.0.0; the message names the first such
+version.
+
+**Fix:** emit 3.2 only, or take off `@queryMethod` and use a plain `@post`
+or `@get`:
+
+```yaml
+options:
+  '@nxgt/typespec':
+    openapi-versions: ['3.2.0']
+```
+
+An `openapi-versions` with 3.2 beside an older version fails the same way:
+list only 3.2. More, in [The emitter](guide/emitter.md).
+
+## `search is marked @queryMethod: emit with @nxgt/typespec, which writes it as a QUERY; @typespec/openapi3 would write a POST.`
+
+**When:** `tsp compile` with `@typespec/openapi3` in `emit`; the error
+`query-method-needs-nxgt-emitter` on each marked operation. Since 0.13.0; in
+0.12.0 this compiled to a `post` with `x-nxgt-method: query`.
+
+**Why:** only the emitter `@nxgt/typespec` writes a `@queryMethod` as a
+`QUERY`.
+
+**Fix:** emit with it, and ask for 3.2:
+
+```yaml
+emit:
+  - '@nxgt/typespec'
+options:
+  '@nxgt/typespec':
+    openapi-versions: ['3.2.0']
+```
+
+## `The emitter @nxgt/typespec runs @typespec/openapi3, which is not installed: add it beside @nxgt/typespec.`
+
+**When:** `tsp compile` with `@nxgt/typespec` in `emit`; the error
+`openapi3-missing`. Nothing is emitted.
+
+**Why:** `@typespec/openapi3` is an optional peer of `@nxgt/typespec`, loaded
+only when the spec is emitted, so installing the library does not install it.
+
+**Fix:**
+
+```sh
+bun add -d @typespec/openapi3
+```
+
+## `findById is sent with QUERY, where its verb find is sent with GET or HEAD`
+
+**When:** a warning, `verb-method-mismatch`: an operation named after one of
+the library's verbs other than `search` and `query` is marked `@queryMethod`.
+
+**Why:** a marked `POST` is checked as the `QUERY` it is, and only `search`
+and `query` are sent with `QUERY`.
+
+**Fix:** name it `search` or `query`, a name that is not a verb, or take off
+`@queryMethod` and give the verb its own method, as in the entry on
+[`findById is sent with POST`](#findbyid-is-sent-with-post-where-its-verb-find-is-sent-with-get-or-head).
+
+```tsp
+@post @queryMethod @route("/search") searchByName(@body names: string[]): User[]; // searchUserByName
+```
+
 ## `declares a reply without a body and one with a body of status …`
 
 **When:** an operation declares, for one status, a reply without a body and
@@ -600,7 +698,9 @@ using OpenAPI;
 
 **When:** you generate from what `tsp compile` emitted.
 
-**Why:** `@typespec/openapi3` emits OpenAPI 3.0 by default.
+**Why:** `@typespec/openapi3`, and so `@nxgt/typespec` which runs it, emits
+OpenAPI 3.0 by default.
 
 **Fix:** in `tspconfig.yaml`, set `openapi-versions: ['3.1.0']` or
-`['3.2.0']` under the `@typespec/openapi3` options.
+`['3.2.0']` under the options of the emitter you use, `@nxgt/typespec`
+or `@typespec/openapi3`.

package/lib/main.tsp

@@ -10,3 +10,4 @@ import "./columns.tsp";
 import "./headers.tsp";
 import "./sorting.tsp";
 import "./requests.tsp";
+import "./query-method.tsp";

package/lib/query-method.tsp

@@ -0,0 +1,26 @@
+import "@typespec/openapi";
+
+using TypeSpec.Reflection;
+
+namespace Nxgt;
+
+/**
+ * Marks a `POST` as a `QUERY`: a safe request, which changes nothing on the
+ * server, with its criteria in the body. It is sent as a `POST`, which every
+ * server, proxy and `fetch` accepts, and the OpenAPI document says what it is
+ * with `x-nxgt-method: query`: `@nxgt/openapi-codegen` reads it. Once
+ * `@typespec/http` declares `QUERY`, this is the decorator that changes, not
+ * the spec. Only on a `POST`: anything else is the error
+ * `query-method-not-post`. `@operationIds` checks its verb as a `QUERY`'s:
+ * `search` and `query` take one.
+ *
+ * @example
+ * ```typespec
+ * @route("/users")
+ * interface Users {
+ *   @post @queryMethod @route("/search")
+ *   search(@body criteria: UserCriteria): User[];   // searchUsers
+ * }
+ * ```
+ */
+extern dec queryMethod(target: Operation);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/typespec",
-	"version": "0.11.0",
+	"version": "0.13.0",
 	"license": "MIT",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -45,20 +45,29 @@
 			"src/index.ts"
 		]
 	},
+	"dependencies": {
+		"yaml": "^2.9.0"
+	},
 	"peerDependencies": {
 		"@typespec/compiler": "^1.16.0",
 		"@typespec/http": "^1.16.0",
 		"@typespec/openapi": "^1.16.0",
-		"typescript": "^6.0.3 || ^7.0.0"
+		"typescript": "^6.0.3 || ^7.0.0",
+		"@typespec/openapi3": "^1.16.0"
+	},
+	"peerDependenciesMeta": {
+		"@typespec/openapi3": {
+			"optional": true
+		}
 	},
 	"devDependencies": {
-		"@nxgt/openapi-codegen": "^0.8.0",
+		"@nxgt/openapi-codegen": "^0.9.1",
 		"@nxgt/openapi-hono": "^0.3.2",
 		"@types/bun": "^1.4.0",
-		"@typespec/compiler": "1.16.0",
-		"@typespec/http": "1.16.0",
-		"@typespec/openapi": "1.16.0",
-		"@typespec/openapi3": "1.16.0",
+		"@typespec/compiler": "1.17.0",
+		"@typespec/http": "1.17.0",
+		"@typespec/openapi": "1.17.0",
+		"@typespec/openapi3": "1.17.0",
 		"hono": "^4.13.4",
 		"zod": "^4.5.4"
 	}

package/templates/scaffolding.json

@@ -6,6 +6,7 @@
 		"libraries": [
 			"@typespec/http",
 			"@typespec/openapi",
+			"@typespec/openapi3",
 			"@nxgt/typespec",
 			"@nxgt/openapi-codegen"
 		],
@@ -15,9 +16,9 @@
 			}
 		},
 		"emitters": {
-			"@typespec/openapi3": {
+			"@nxgt/typespec": {
 				"selected": true,
-				"label": "OpenAPI 3.1 document",
+				"label": "OpenAPI 3.1 document (@typespec/openapi3; in 3.2, a @queryMethod is a QUERY)",
 				"options": {
 					"emitter-output-dir": "{project-root}/openapi",
 					"openapi-versions": ["3.1.0"],