@nxgt/typespec 0.9.2 → 0.11.0

package/docs/guide/scalars.md

@@ -0,0 +1,288 @@
+# Scalars
+
+The scalars of [`@nxgt/graphql-scalars`](https://www.npmjs.com/package/@nxgt/graphql-scalars)
+as TypeSpec scalars, so a spec types a latitude, a currency or an IPv4 address
+once and every generator and validator downstream agrees on it.
+
+```tsp
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+@service(#{ title: "Places" })
+namespace Places;
+
+model Place {
+  name: string;
+  location: {
+    latitude: latitude;
+    longitude: longitude;
+  };
+  currency: currency;
+  openedOn: date;
+  homepage?: httpUrl;
+  contact?: emailAddress;
+  seats: positiveInt;
+}
+
+@route("/places") @post op createPlace(@body place: Place): Place;
+```
+
+Each property becomes a `$ref` to a component named as the GraphQL scalar:
+
+```yaml
+components:
+  schemas:
+    Currency:
+      type: string
+      pattern: ^[A-Z]{3}$
+      format: currency
+      description: |-
+        An ISO 4217 currency code, uppercase: `EUR`, `USD`. ...
+      x-nxgt-scalar: Currency
+    Latitude:
+      type: number
+      format: double
+      minimum: -90
+      maximum: 90
+      x-nxgt-scalar: Latitude
+    PositiveInt:
+      type: integer
+      format: int32
+      minimum: 1
+      maximum: 2147483647
+      x-nxgt-scalar: PositiveInt
+```
+
+## What a scalar emits
+
+| Emitted | Value |
+| --- | --- |
+| The component | The GraphQL name (`@friendlyName`): `Latitude`, `CIDRv4`, `EmailAddress`. It is global: a model of that name in your spec collides with it. |
+| `format` | JSON Schema's when one exists (`date`, `date-time`, `duration`, `email`, `hostname`, `ipv4`, `ipv6`, `uri`, `uuid`), otherwise the kebab-case name (`iban`, `local-time`, `cidr-v4`); `base64` has OpenAPI's `byte`. The numbers keep the format TypeSpec writes from the base type. |
+| `pattern`, `minimum`, `maximum` | The closest the GraphQL rule goes in a pattern or in bounds. |
+| `x-nxgt-scalar` | The GraphQL name, so a generator can tell the rule from the shape. |
+| `description` | The rule in words, and what the pattern leaves out. |
+
+A generator that knows nothing of `x-nxgt-scalar` still validates the pattern
+and the bounds. A later `@nxgt/openapi-codegen` release will map it to the exact
+Zod schema from `@nxgt/zod` ([roadmap](../roadmap.md)); until then, what a
+scalar leaves out is not checked.
+
+## Names
+
+The identifiers are camelCase: `ipV4`, `cidrV6`, `uuidV7`, `hexColorCode`. The
+component keeps the GraphQL spelling.
+
+- `url` and `duration` are TypeSpec built-ins, and a scalar of that name makes
+  `url` ambiguous under `using Nxgt`. They are `httpUrl` and `isoDuration`.
+- `JSON`, `JSONObject` and `Void` are not declared: write TypeSpec's own
+  `unknown`, `Record<unknown>` and `void`.
+- A declaration of yours named like a scalar shadows it. In a spec with an
+  operation `locale`, write `Nxgt.locale`.
+
+```tsp
+@get op locale(): string;                 // yours
+model Page { language: Nxgt.locale; }    // the scalar
+```
+
+## Identifiers
+
+`uuid`, with the id columns, is also in [Scalars and columns](columns.md).
+
+| Scalar | Component | Format | Takes | Left out of the pattern |
+| --- | --- | --- | --- | --- |
+| `uuid` | `UUID` | `uuid` | `550e8400-e29b-41d4-a716-446655440000`, the nil and the max UUID | |
+| `uuidV4` | `UUIDv4` | `uuid` | `123e4567-e89b-42d3-a456-426614174000` | |
+| `uuidV7` | `UUIDv7` | `uuid` | `017f22e2-79b0-7cc3-98c4-dc0c0c07398f` | |
+| `guid` | `GUID` | `uuid` | any 8-4-4-4-12 hexadecimal, `123e4567-e89b-12d3-c456-426614174000` | no version, no variant |
+| `ulid` | `ULID` | `ulid` | `01ARZ3NDEKTSV4RRFFQ69G5FAV`: 26 Crockford base32 characters, the first 0 to 7, any case | |
+| `cuid2` | `Cuid2` | `cuid2` | `tz4a98xxat96iws9zmbrgj3a`, `ab`: a lowercase letter, then lowercase letters and digits, 2 to 32 characters | |
+| `nanoId` | `NanoID` | `nano-id` | `V1StGXR8_Z5jdHi6B-myT`: 21 characters of `A-Za-z0-9_-`; a custom length is refused | |
+| `ksuid` | `KSUID` | `ksuid` | `0ujtsYcgvSTl8PAuAdqWYSMnLOv`: 27 base62 characters, up to `aWgEPTl1tmebfsQzFP4bxwgy80V` | |
+| `xid` | `XID` | `xid` | `9m4e2mr0ui3e8a215n4g`: 20 lowercase base32hex characters, the last `0` or `g` | |
+| `objectId` | `ObjectID` | `object-id` | `507f1f77bcf86cd799439011`: 24 hexadecimal digits, any case | |
+| `isbn` | `ISBN` | `isbn` | `0306406152`, `080442957X`, `9780306406157`: digits only, no hyphen | the check digit (`9780306406158` passes) |
+| `semVer` | `SemVer` | `sem-ver` | `1.2.3`, `1.0.0-rc.1+build.5`: no `v` prefix, no leading zero | |
+
+`uuid` refuses a UUID of no known version (`...-91d4-...`); `guid` is the shape
+only. Case is kept as sent.
+
+## Encodings
+
+| Scalar | Component | Format | Takes | Left out of the pattern |
+| --- | --- | --- | --- | --- |
+| `base64` | `Base64` | `byte` | `aGk=`, `a+b/`, `""`: RFC 4648 with padding, in its one canonical spelling (`YR==` is refused) | |
+| `base64Url` | `Base64URL` | `base64-url` | `aGk`, `a-b_`: `-` and `_`, no padding, canonical | |
+| `hexadecimal` | `Hexadecimal` | `hexadecimal` | `deadBEEF`, `abc`: one or more digits, any case, no `0x` | |
+| `jwt` | `JWT` | `jwt` | three base64url parts joined by `.`, `eyJhbGci….eyJzdWIi….dozjgNry…` | that each part is canonical and the first two are JSON objects, `alg: none`, the signature |
+| `sha256` | `SHA256` | `sha256` | 64 hexadecimal digits, any case | |
+| `sha512` | `SHA512` | `sha512` | 128 hexadecimal digits, any case | |
+
+`base64` carries the OpenAPI format `byte`, which the generator turns into
+`z.base64()` in front of the pattern (`zBase64 = z.base64().regex(…)`); the
+others are `z.string().regex(…)`. A `jwt` is a shape, not a verification: check
+the token's signature in your code.
+
+## Strings
+
+| Scalar | Component | Format | Takes | Left out of the pattern |
+| --- | --- | --- | --- | --- |
+| `nonEmptyString` | `NonEmptyString` | `non-empty-string` | `a`, ` a `: at least one non-white-space character (ECMAScript `\s`); kept as sent, not trimmed; `""`, `"   "` and a lone no-break space are refused | |
+| `emoji` | `Emoji` | `emoji` | `😀`, `👍🏽`, `👨‍👩‍👧`, `🇫🇷`, `1️⃣`: exactly one emoji | tag sequences (the flags of England, Scotland, Wales), segmentation into user-perceived characters, so two emoji in a row may pass |
+
+The `emoji` pattern uses Unicode property escapes and needs the `u` flag;
+the generated Zod regex has it.
+
+## Numbers
+
+Numbers are JSON numbers, except `BigInt` and `Long`, which are decimal strings
+because a JSON number loses precision past 2^53.
+
+| Scalar | Component | Format | Takes | Left out of the pattern |
+| --- | --- | --- | --- | --- |
+| `positiveInt` | `PositiveInt` | `int32` | `1` to `2147483647` | `-0` |
+| `nonNegativeInt` | `NonNegativeInt` | `int32` | `0` to `2147483647` | `-0` |
+| `negativeInt` | `NegativeInt` | `int32` | `-2147483648` to `-1` | `-0` |
+| `nonPositiveInt` | `NonPositiveInt` | `int32` | `-2147483648` to `0` | `-0` |
+| `safeInt` | `SafeInt` | `int64` | the integers JavaScript holds exactly, `-9007199254740991` to `9007199254740991` | `-0` |
+| `port` | `Port` | `int32` | `0` to `65535` | `-0` |
+| `positiveFloat` | `PositiveFloat` | `double` | `0.5`, above 0 | |
+| `nonNegativeFloat` | `NonNegativeFloat` | `double` | `0`, `1.5` | |
+| `negativeFloat` | `NegativeFloat` | `double` | `-0.5`, below 0 | |
+| `nonPositiveFloat` | `NonPositiveFloat` | `double` | `0`, `-1.5` | |
+| `bigInt` | `BigInt` | `big-int` | `"123456789012345678901234567890"`: no leading zero, no `+`, no `-0` | |
+| `long` | `Long` | `int64` | `"9223372036854775807"`, the signed 64-bit range | |
+
+`long` is a string with `format: int64`, the OpenAPI idiom for an int64 sent as
+a string; `timestamp` and `safeInt` are JSON numbers with the same format.
+
+An integer scalar accepts `-0`, which GraphQL refuses and no JSON Schema can
+express.
+
+## Date and time
+
+| Scalar | Component | Format | Takes | Left out of the pattern |
+| --- | --- | --- | --- | --- |
+| `date` | `Date` | `date` | `2024-02-29` (an impossible day is refused) | |
+| `dateTime` | `DateTime` | `date-time` | `2024-03-10T12:00:00+02:00`: an offset is required, `-00:00` refused | the range 0000 to 9999 in UTC, the leap second |
+| `time` | `Time` | `time` | `10:15:30Z`, `10:15:30.5+02:00` | |
+| `localDateTime` | `LocalDateTime` | `local-date-time` | `2024-03-10T10:15`, `2024-03-10T10:15:30`: no offset | |
+| `localTime` | `LocalTime` | `local-time` | `10:15`, `10:15:30.5`: no offset | |
+| `isoDuration` | `Duration` | `duration` | `P1Y2M3DT4H5M6S`, `PT0.5S`, `P2W`: weeks alone, no sign | |
+| `utcOffset` | `UtcOffset` | `utc-offset` | `+05:30`, from `-12:00` to `+14:00`; `-00:00` refused | |
+| `timeZone` | `TimeZone` | `time-zone` | `Europe/Paris`, `UTC` | the list of IANA names |
+| `timestamp` | `Timestamp` | `int64` | milliseconds since the epoch, `1710065730000`, within ±8640000000000000 | |
+
+A well-shaped unknown time zone name (`Mars/Olympus`) passes
+([Known gaps](#known-gaps)).
+
+## Geo
+
+| Scalar | Component | Format | Takes | Left out of the pattern |
+| --- | --- | --- | --- | --- |
+| `latitude` | `Latitude` | `double` | `48.8566`, from -90 to 90 | |
+| `longitude` | `Longitude` | `double` | `2.3522`, from -180 to 180 | |
+
+Both are numbers, never strings.
+
+## Colors
+
+CSS color syntax, in the comma form, one space after each comma.
+
+| Scalar | Component | Format | Takes | Left out of the pattern |
+| --- | --- | --- | --- | --- |
+| `hexColorCode` | `HexColorCode` | `hex-color-code` | `#f00`, `#f008`, `#ff0000`, `#ff000080`, any case | |
+| `rgb` | `RGB` | `rgb` | `rgb(255, 0, 0)`; no percentage, no leading zero | |
+| `rgba` | `RGBA` | `rgba` | `rgba(255, 0, 0, 0.5)`: the alpha is `0`, `1` or a fraction with a leading `0` and no trailing zero | |
+| `hsl` | `HSL` | `hsl` | `hsl(120, 100%, 50%)`: hue 0 to 359, no unit | |
+| `hsla` | `HSLA` | `hsla` | `hsla(120, 100%, 50%, 0.5)` | |
+
+`rgb(255,0,0)`, `rgb(255 0 0)` and `RGB(255, 0, 0)` are refused.
+
+## Network
+
+| Scalar | Component | Format | Takes | Left out of the pattern |
+| --- | --- | --- | --- | --- |
+| `emailAddress` (alias `email`) | `EmailAddress` | `email` | `ada@example.com`, `a.b+c@sub.example.org`: no quoted local part, at least two labels | whether the domain exists |
+| `hostname` | `Hostname` | `hostname` | `api.example.com`, `localhost`, `xn--bcher-kva.example`; not `1.2.3.4`, not Unicode | nothing is resolved |
+| `httpUrl` | `URL` | `uri` | `https://example.com/a?b=c`, `http://localhost:3000`, `https://[2001:db8::1]/`; no other scheme, no user info | |
+| `ipV4` | `IPv4` | `ipv4` | `192.168.0.1`: no leading zero | |
+| `ipV6` | `IPv6` | `ipv6` | `2001:db8::1`, `::1`, `::ffff:192.0.2.1`, any case; no zone | |
+| `ip` | `IP` | `ip` | either of the two | |
+| `cidrV4` | `CIDRv4` | `cidr-v4` | `10.0.0.0/8`, `0.0.0.0/0` | that the address starts its block |
+| `cidrV6` | `CIDRv6` | `cidr-v6` | `2001:db8::/32`, `::/0` | that the address starts its block |
+| `mac` | `MAC` | `mac` | `00:1a:2b:3c:4d:5e`; not the hyphen or dotted form | |
+| `phoneNumber` | `PhoneNumber` | `phone-number` | `+33612345678`: E.164, 7 to 15 digits, no separator | whether the number exists |
+
+`httpUrl` is for a page's address; it is generated as
+`zURL = z.string().regex(…)`: the pattern is the rule, and keeps to `http:`
+and `https:` (`javascript:alert(1)` is refused). The generator leaves out
+`z.url()` for it, which trims its input. TypeSpec's own `url` takes any
+scheme and is generated as a bare `z.url()`.
+
+## Locale
+
+| Scalar | Component | Format | Takes | Left out of the pattern |
+| --- | --- | --- | --- | --- |
+| `countryCode` | `CountryCode` | `country-code` | `FR`, `US`: ISO 3166-1 alpha-2, uppercase | the list of assigned codes (`ZZ` passes) |
+| `locale` | `Locale` | `locale` | `fr`, `fr-FR`, `zh-Hant-TW`, `en-US-u-ca-buddhist`: BCP 47 in canonical case, up to 255 characters | the IANA registry, the order of extensions |
+
+## Finance
+
+| Scalar | Component | Format | Takes | Left out of the pattern |
+| --- | --- | --- | --- | --- |
+| `currency` | `Currency` | `currency` | `EUR`, `USD`: ISO 4217, uppercase | the list of codes (`ZZZ` passes) |
+| `iban` | `IBAN` | `iban` | `FR1420041010050500013M02606`: uppercase, no spaces | the mod 97 checksum, the country and its length |
+
+## Values
+
+`JSON`, `JSONObject` and `Void` are not scalars here. Write `unknown`,
+`Record<unknown>` and `void`.
+
+## In a route
+
+The scalars work anywhere a type does: a path, a query, a header, a body.
+
+```tsp
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+@service(#{ title: "Inventory" })
+namespace Inventory;
+
+model Host {
+  @visibility(Lifecycle.Read) id: uuid;
+  name: hostname;
+  address: ip;
+  network: cidrV4;
+  port: port;
+}
+
+@route("/hosts")
+interface Hosts {
+  @get list(@query ipPrefix?: cidrV4): Host[];
+  @get @route("{hostId}") read(@path hostId: uuid): Host;
+}
+```
+
+A request that breaks a pattern or a bound is answered `400` by the generated
+validator, the same as any other schema.
+
+## Known gaps
+
+The pattern is an approximation. Three things a consumer meets:
+
+- An integer scalar accepts `-0`.
+- A scalar that depends on a list (`countryCode`, `currency`, `timeZone`, the
+  `iban` checksum, the `locale` registry) accepts a well-shaped unknown value
+  until the generator maps `x-nxgt-scalar` to `@nxgt/zod`.
+- A declaration named like a scalar shadows it: write `Nxgt.locale`.
+
+See also [Scalars and columns](columns.md) for `uuid`, `email` and the columns,
+and the [troubleshooting](../troubleshooting.md) page.

package/docs/roadmap.md

@@ -8,6 +8,12 @@ generated by `@nxgt/openapi-codegen` in CI before it ships.
 
 Nothing in progress.
 
+## Next
+
+- **Exact scalar rules in the generated code.** `@nxgt/openapi-codegen` maps
+  `x-nxgt-scalar` to the exact Zod schema from `@nxgt/zod`: the checksums,
+  the ISO and IANA lists and the `Intl` rules the patterns leave out.
+
 ## Later
 
 - **`QUERY` for `search` and `query`.** The HTTP `QUERY` method, a safe
@@ -20,6 +26,22 @@ Nothing in progress.
 
 ## Shipped
 
+### 0.11.0
+
+- **Request body aliases.** `CreateRequest<T>`, `UpdateRequest<T>` and
+  `PatchRequest<T>` are TypeSpec's `Create`, `Update` and `MergePatchUpdate`
+  named `Create<T>Request`, `Update<T>Request` and `Patch<T>Request`, so the
+  generated types and schemas share one convention. `Create<T>` and
+  `MergePatchUpdate<T>` stay usable.
+
+### 0.10.0
+
+- **Every scalar of `@nxgt/graphql-scalars`.** The scalars, under the same
+  names, as camelCase TypeSpec scalars: each emits a component named as in
+  GraphQL, a format, a pattern or bounds approximating the rule, and
+  `x-nxgt-scalar`. `uuid` and `email` take the GraphQL rules; the components
+  `Uuid` and `Email` are now `UUID` and `EmailAddress`.
+
 ### 0.9.0
 
 - **A `tsp init` template.** `tsp init` with the package's template

package/docs/troubleshooting.md

@@ -13,7 +13,7 @@ one name with `name_collision`.
 optional, and the generator adds its own 400 beside it.
 
 ```tsp
-@patch updatePost(@path postId: string, @body post: MergePatchUpdate<Post>): Post | BadRequest;
+@patch patchPost(@path postId: string, @body post: PatchRequest<Post>): Post | BadRequest;
 ```
 
 ## `Couldn't resolve import "@nxgt/typespec"`
@@ -92,8 +92,9 @@ In GitHub Actions, add `oven-sh/setup-bun@v2` before the step.
 
 **When:** `tsp compile` runs on a spec that declares its own model named like
 one of the library's: `BadRequestBody` … `InternalServerErrorBody`,
-`ValidationIssue`, `ValidationTarget`, `Uuid` or `Email` when the spec uses
-`uuid` or `email`, or the page of one of its models,
+`ValidationIssue`, `ValidationTarget`, `UUID` or `EmailAddress` when the spec
+uses `uuid` or `email` (or any other scalar, under its GraphQL name: `Latitude`,
+`Currency`), or the page of one of its models,
 such as `PostPage` beside `Page<Post>`, or `CommentCursorPage` beside
 `CursorPage<Comment>`.
 
@@ -489,6 +490,97 @@ linter:
     '@nxgt/typespec/error-body-shape': 'the legacy routes answer their own errors'
 ```
 
+## `@typespec/openapi3/invalid-model-property: 'Operation' cannot be specified as a model property.`
+
+**When:** `tsp compile` runs on a spec that has `using Nxgt` and declares, in
+its own namespace, something named like a scalar (`locale`, `date`, `time`,
+`port`, `hostname`…) and also uses the scalar of that name.
+
+```tsp
+using Nxgt;
+
+@get op locale(): string;
+model Page { language: locale; }
+```
+
+```text
+error @typespec/openapi3/invalid-model-property: 'Operation' cannot be specified as a model property.
+```
+
+**Why:** a declaration of the spec's own namespace shadows what `using Nxgt`
+brings in, without a word. With an operation the name resolves to the
+operation, and the emitter refuses it. With a model, `model date { … }` and
+`day: date`, the property silently gets the model, a `$ref` to `date` where
+`Date` was meant.
+
+**Fix:** write the scalar with its namespace, or rename your declaration:
+
+```tsp
+model Page { language: Nxgt.locale; }
+```
+
+## `` A value the GraphQL scalar refuses is accepted: `ZZ`, `ZZZ`, `Mars/Olympus`, a bad IBAN checksum ``
+
+**When:** a request carries a value that `@nxgt/graphql-scalars` refuses but
+the generated validator accepts and answers `2xx`: a country code that is not
+assigned (`ZZ`), a currency (`ZZZ`), an IBAN with a wrong checksum, an ISBN
+with a wrong check digit, a time zone (`Mars/Olympus`) or a locale that is not
+in the registry, a JWT whose segments are not a token, an `Emoji` that is not
+one.
+
+**Why:** the scalar's pattern checks the shape. A list (`countryCode`,
+`currency`, `timeZone`, `locale`) or a checksum (`iban`, ISBN) does not fit in
+a pattern. `x-nxgt-scalar` names the exact rule, but `@nxgt/openapi-codegen`
+does not map it to the `@nxgt/zod` schema yet ([roadmap](roadmap.md)).
+
+**Fix:** until it does, check the value in the handler against the exact
+rule, the list or the checksum, from `@nxgt/zod` or your own table, and answer
+`400` as the generated validator does:
+
+```ts
+if (!knownCountries.has(body.country)) {
+	return c.json({ status: 400, message: 'Unknown country code' }, 400);
+}
+```
+
+## `An integer scalar accepts -0`
+
+**When:** a body carries `-0` for `positiveInt`, `nonNegativeInt`, `port`,
+`safeInt` and the other integer scalars, and the validator lets it through
+where `@nxgt/graphql-scalars` refuses it.
+
+**Why:** `-0` is a JSON number equal to `0`, which no JSON Schema keyword can
+tell from `0`. For `nonNegativeInt`, `nonPositiveInt`, `port`, the bound holds,
+so the value passes (`positiveInt` and `negativeInt` refuse it by their bound).
+
+**Fix:** normalise in the handler when the sign matters:
+
+```ts
+const quantity = Object.is(body.quantity, -0) ? 0 : body.quantity;
+```
+
+## `UUID`, `EmailAddress`: generated `Uuid` and `Email` are gone, and an id is answered 400
+
+**When:** after upgrading to 0.10.0, the generated code no longer exports
+`Uuid`, `zUuid`, `Email` or `zEmail` (`Module has no exported member 'Uuid'`),
+or a request whose id was accepted before is answered `400`.
+
+**Why:** the schemas follow `@nxgt/graphql-scalars`' names, `UUID` and
+`EmailAddress`, and `uuid` takes its rule: an RFC 9562 version 1 to 8 with the
+RFC variant, or the nil or max UUID. An id of no known version
+(`…-91d4-…`) is refused.
+
+**Fix:** rename the imports. For an id that is a shape only, write `guid`
+instead of `uuid`:
+
+```ts
+import { type UUID, zUUID, type EmailAddress, zEmailAddress } from './generated';
+```
+
+```tsp
+model Legacy { id: guid; }
+```
+
 ## `Unknown decorator @operationId`
 
 **When:** a spec writes `@operationId` next to `@operationIds`.

package/lib/main.tsp

@@ -9,3 +9,4 @@ import "./scalars.tsp";
 import "./columns.tsp";
 import "./headers.tsp";
 import "./sorting.tsp";
+import "./requests.tsp";

package/lib/requests.tsp

@@ -0,0 +1,36 @@
+import "@typespec/http";
+
+using Http;
+
+namespace Nxgt;
+
+/**
+ * The body of a create: the properties of `T` visible on create, named
+ * `Create<T>Request` (`CreatePostRequest`). A nested model filtered the same
+ * way is named alike (`CreateAddressRequest`); one left whole keeps its name.
+ */
+alias CreateRequest<T extends Reflection.Model> = Create<
+  T,
+  "Create{name}Request"
+>;
+
+/**
+ * The body of a full update, as a `PUT` replaces the resource: the properties
+ * of `T` visible on update, each as optional as `T` declares it, named
+ * `Update<T>Request` (`UpdatePostRequest`).
+ */
+alias UpdateRequest<T extends Reflection.Model> = Update<
+  T,
+  "Update{name}Request"
+>;
+
+/**
+ * The body of a partial update, as a JSON Merge Patch
+ * (`application/merge-patch+json`): the properties of `T` visible on update,
+ * all optional, a nullable one sent as `null` to clear it, named
+ * `Patch<T>Request` (`PatchPostRequest`).
+ */
+alias PatchRequest<T extends Reflection.Model> = MergePatchUpdate<
+  T,
+  "Patch{name}Request"
+>;

package/lib/scalars/color/hex-color-code.tsp

@@ -0,0 +1,17 @@
+import "@typespec/openapi";
+
+using TypeSpec.OpenAPI;
+
+namespace Nxgt;
+
+/**
+ * A CSS hex color: `#` then 3, 4, 6 or 8 hexadecimal digits, in any case, kept
+ * as sent: `#ff0000`. The 4 and 8 digit forms carry an alpha.
+ *
+ * Specified by https://www.w3.org/TR/css-color-4/#hex-notation.
+ */
+@friendlyName("HexColorCode")
+@format("hex-color-code")
+@pattern("^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$")
+@extension("x-nxgt-scalar", "HexColorCode")
+scalar hexColorCode extends string;

package/lib/scalars/color/hsl.tsp

@@ -0,0 +1,18 @@
+import "@typespec/openapi";
+
+using TypeSpec.OpenAPI;
+
+namespace Nxgt;
+
+/**
+ * A CSS `hsl()` color in the comma syntax: `hsl(120, 100%, 50%)`. A hue from 0
+ * to 359 with no unit (360 is written 0), then saturation and lightness as
+ * integer percentages from 0% to 100%.
+ *
+ * Specified by https://www.w3.org/TR/css-color-4/#the-hsl-notation.
+ */
+@friendlyName("HSL")
+@format("hsl")
+@pattern("^hsl\\((?:3[0-5]\\d|[12]\\d\\d|[1-9]?\\d), (?:100|[1-9]?\\d)%, (?:100|[1-9]?\\d)%\\)$")
+@extension("x-nxgt-scalar", "HSL")
+scalar hsl extends string;

package/lib/scalars/color/hsla.tsp

@@ -0,0 +1,18 @@
+import "@typespec/openapi";
+
+using TypeSpec.OpenAPI;
+
+namespace Nxgt;
+
+/**
+ * A CSS `hsla()` color in the comma syntax: `hsla(120, 100%, 50%, 0.5)`. As
+ * `hsl` plus an alpha: `0`, `1`, or a fraction with no trailing zero and a
+ * leading `0`.
+ *
+ * Specified by https://www.w3.org/TR/css-color-4/#the-hsl-notation.
+ */
+@friendlyName("HSLA")
+@format("hsla")
+@pattern("^hsla\\((?:3[0-5]\\d|[12]\\d\\d|[1-9]?\\d), (?:100|[1-9]?\\d)%, (?:100|[1-9]?\\d)%, (?:0|1|0\\.\\d*[1-9])\\)$")
+@extension("x-nxgt-scalar", "HSLA")
+scalar hsla extends string;

package/lib/scalars/color/rgb.tsp

@@ -0,0 +1,18 @@
+import "@typespec/openapi";
+
+using TypeSpec.OpenAPI;
+
+namespace Nxgt;
+
+/**
+ * A CSS `rgb()` color in the comma syntax: `rgb(255, 0, 0)`. Three integers
+ * from 0 to 255, no leading zero, no percentage, a `, ` between them, the
+ * function name in lower case.
+ *
+ * Specified by https://www.w3.org/TR/css-color-4/#rgb-functions.
+ */
+@friendlyName("RGB")
+@format("rgb")
+@pattern("^rgb\\((?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d), (?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d), (?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)\\)$")
+@extension("x-nxgt-scalar", "RGB")
+scalar rgb extends string;

package/lib/scalars/color/rgba.tsp

@@ -0,0 +1,18 @@
+import "@typespec/openapi";
+
+using TypeSpec.OpenAPI;
+
+namespace Nxgt;
+
+/**
+ * A CSS `rgba()` color in the comma syntax: `rgba(255, 0, 0, 0.5)`. As `rgb`
+ * plus an alpha: `0`, `1`, or a fraction with no trailing zero and a leading
+ * `0`.
+ *
+ * Specified by https://www.w3.org/TR/css-color-4/#rgb-functions.
+ */
+@friendlyName("RGBA")
+@format("rgba")
+@pattern("^rgba\\((?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d), (?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d), (?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d), (?:0|1|0\\.\\d*[1-9])\\)$")
+@extension("x-nxgt-scalar", "RGBA")
+scalar rgba extends string;

package/lib/scalars/color.tsp

@@ -0,0 +1,6 @@
+// The color scalars, one file each under ./color/.
+import "./color/hex-color-code.tsp";
+import "./color/hsl.tsp";
+import "./color/hsla.tsp";
+import "./color/rgb.tsp";
+import "./color/rgba.tsp";

package/lib/scalars/date-time/date-time.tsp

@@ -0,0 +1,19 @@
+import "@typespec/openapi";
+
+using TypeSpec.OpenAPI;
+
+namespace Nxgt;
+
+/**
+ * An RFC 3339 date-time with its offset, `Z` or `±hh:mm`, kept as sent: `2024-03-10T12:00:00+02:00`.
+ * A time with no offset names no instant and is refused, and so is the offset `-00:00`:
+ * write `Z` or `+00:00`. An impossible day is refused. The range 0000 to 9999 in UTC is
+ * not in the pattern, nor is the leap second.
+ *
+ * Specified by https://www.rfc-editor.org/rfc/rfc3339.
+ */
+@friendlyName("DateTime")
+@format("date-time")
+@pattern("^(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8]))|(?:\\d\\d(?:0[48]|[2468][048]|[13579][26])|(?:[02468][048]|[13579][26])00)-02-29)T(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)(?:Z|\\+(?:[01]\\d|2[0-3]):[0-5]\\d|-(?!00:00)(?:[01]\\d|2[0-3]):[0-5]\\d)$")
+@extension("x-nxgt-scalar", "DateTime")
+scalar dateTime extends string;

package/lib/scalars/date-time/date.tsp

@@ -0,0 +1,17 @@
+import "@typespec/openapi";
+
+using TypeSpec.OpenAPI;
+
+namespace Nxgt;
+
+/**
+ * A calendar date, `YYYY-MM-DD`, with no time and no time zone: `2024-02-29`. An impossible
+ * day, such as `2023-02-29`, is refused.
+ *
+ * Specified by https://www.rfc-editor.org/rfc/rfc3339#section-5.6.
+ */
+@friendlyName("Date")
+@format("date")
+@pattern("^(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8]))|(?:\\d\\d(?:0[48]|[2468][048]|[13579][26])|(?:[02468][048]|[13579][26])00)-02-29)$")
+@extension("x-nxgt-scalar", "Date")
+scalar date extends string;

package/lib/scalars/date-time/iso-duration.tsp

@@ -0,0 +1,17 @@
+import "@typespec/openapi";
+
+using TypeSpec.OpenAPI;
+
+namespace Nxgt;
+
+/**
+ * An ISO 8601 duration, kept as sent and not normalised: `P1DT2H`. Weeks are not mixed with
+ * other units, and there is no sign. Named `isoDuration` because `duration` is TypeSpec's own.
+ *
+ * Specified by https://www.iso.org/iso-8601-date-and-time-format.html.
+ */
+@friendlyName("Duration")
+@format("duration")
+@pattern("^P(?:\\d+W|(?!.*W)(?=\\d|T\\d)(?:\\d+Y)?(?:\\d+M)?(?:\\d+D)?(?:T(?=\\d)(?:\\d+H)?(?:\\d+M)?(?:\\d+(?:[.,]\\d+)?S)?)?)$")
+@extension("x-nxgt-scalar", "Duration")
+scalar isoDuration extends string;

package/lib/scalars/date-time/local-date-time.tsp

@@ -0,0 +1,15 @@
+import "@typespec/openapi";
+
+using TypeSpec.OpenAPI;
+
+namespace Nxgt;
+
+/**
+ * A date and a time on the wall clock, with no offset, not even `Z`: `2024-03-10T10:15:30`.
+ * The seconds are optional. An impossible day is refused.
+ */
+@friendlyName("LocalDateTime")
+@format("local-date-time")
+@pattern("^(?:\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8]))|(?:\\d\\d(?:0[48]|[2468][048]|[13579][26])|(?:[02468][048]|[13579][26])00)-02-29)T(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?$")
+@extension("x-nxgt-scalar", "LocalDateTime")
+scalar localDateTime extends string;