@nxgt/typespec 0.9.1 → 0.10.0

package/README.md

@@ -18,7 +18,7 @@ bun add -d @nxgt/typespec @typespec/compiler @typespec/http @typespec/openapi @t
 
 `@typespec/compiler`, `@typespec/http` and `@typespec/openapi` 1.16 or later
 are peer dependencies,
-and `typescript` 6 too, as for every `@nxgt` package. `@typespec/openapi3`
+and `typescript` 6 or 7 too, as for every `@nxgt` package. `@typespec/openapi3`
 compiles the spec, and `@nxgt/openapi-codegen` generates the code from it.
 The generator's CLI, `nxgt-openapi`, runs on [Bun](https://bun.sh): it needs
 `bun` on the PATH, even when called through `npx` or an npm script.
@@ -291,15 +291,34 @@ model Post {
 
 | Name | Emitted as | Generated | drizzle |
 | --- | --- | --- | --- |
-| `uuid` | the schema `Uuid`, `format: uuid` | `Uuid`, `z.guid()` | `id()` |
-| `email` | the schema `Email`, `format: email` | `Email`, `z.email()` | |
+| `uuid` | the schema `UUID`, `format: uuid`, a pattern for versions 1–8 | `UUID`, `z.guid().regex(…)` | `id()` |
+| `email` | `emailAddress`, the schema `EmailAddress`, `format: email` | `EmailAddress`, `z.string().regex(…)` | |
 | `...Timestamps` | `createdAt`, `updatedAt`, read-only | left out of `Create<T>` and updates | `timestamps()` |
 | `...SoftDelete` | `deletedAt: utcDateTime \| null`, read-only | | `softDelete()` |
 | `...Versioned` | `version: integer`, read and update | kept in `MergePatchUpdate<T>` | `version()` |
 | `...Actors<Id = uuid>` | `createdBy`, `updatedBy`, `deletedBy`, `Id \| null`, read-only | | `actors()` |
 
-TypeSpec's own `url` is the address of a page, `format: uri`, generated as
-`z.url()`. More in [Scalars and columns](docs/guide/columns.md).
+Every scalar of [`@nxgt/graphql-scalars`](https://www.npmjs.com/package/@nxgt/graphql-scalars)
+is declared too, as a camelCase scalar (`latitude`, `currency`, `positiveInt`,
+`httpUrl`, `ipV4`, `isoDuration`):
+
+```tsp
+model Place {
+  location: { latitude: latitude; longitude: longitude };
+  currency: currency;
+  openedOn: date;
+  homepage?: httpUrl;
+  seats: positiveInt;
+}
+```
+
+Each is an OpenAPI component named as in GraphQL (`Latitude`, `URL`), with a
+`format`, a pattern or bounds approximating the rule, and `x-nxgt-scalar`
+naming it. The exact rules (checksums, ISO and IANA lists) are outside the
+pattern. TypeSpec's own `url` takes any scheme; `httpUrl` takes `http:` and
+`https:`. Every scalar by category, in
+[Scalars](docs/guide/scalars.md); the ids, the addresses and the columns, in
+[Scalars and columns](docs/guide/columns.md).
 
 ### Headers
 
@@ -503,8 +522,18 @@ In the ruleset `@nxgt/typespec/recommended`; each is a warning, and named
 
 | Name | What it is |
 | --- | --- |
-| `uuid` | a string, `format: uuid`; the schema `Uuid` |
-| `email` | a string, `format: email`; the schema `Email` |
+| `uuid` | an RFC 9562 UUID, `format: uuid` and a pattern; the schema `UUID` |
+| `email` | an alias of `emailAddress`, `format: email` and a pattern; the schema `EmailAddress` |
+| `guid`, `uuidV4`, `uuidV7` | a UUID of any shape, of version 4, of version 7; `GUID`, `UUIDv4`, `UUIDv7` |
+| `ulid`, `cuid2`, `nanoId`, `ksuid`, `xid`, `objectId`, `isbn`, `semVer` | identifiers by shape: `ULID`, `Cuid2`, `NanoID`, `KSUID`, `XID`, `ObjectID`, `ISBN`, `SemVer` |
+| `base64`, `base64Url`, `hexadecimal`, `jwt`, `sha256`, `sha512` | encodings and digests; `base64` has the format `byte` and is generated as `z.base64()` |
+| `nonEmptyString`, `emoji` | a string with a visible character; one emoji |
+| `positiveInt`, `nonNegativeInt`, `negativeInt`, `nonPositiveInt`, `safeInt`, `port`, `positiveFloat`, `nonNegativeFloat`, `negativeFloat`, `nonPositiveFloat`, `bigInt`, `long` | the numbers: `int32` bounds, JavaScript's safe integers, TCP ports, floats by sign, and 64-bit (`long`, `format: int64`) or larger (`bigInt`) integers as strings |
+| `date`, `dateTime`, `time`, `localDateTime`, `localTime`, `isoDuration`, `utcOffset`, `timeZone`, `timestamp` | dates, times and durations as RFC 3339 and ISO 8601 write them |
+| `latitude`, `longitude` | decimal degrees, as numbers |
+| `hexColorCode`, `rgb`, `rgba`, `hsl`, `hsla` | CSS colors |
+| `emailAddress`, `hostname`, `httpUrl`, `ipV4`, `ipV6`, `ip`, `cidrV4`, `cidrV6`, `mac`, `phoneNumber` | addresses; `httpUrl` is named so because `url` is TypeSpec's |
+| `countryCode`, `locale`, `currency`, `iban` | ISO and BCP 47 codes, by shape |
 | `Timestamps` | `createdAt`, `updatedAt: utcDateTime`, read-only |
 | `SoftDelete` | `deletedAt: utcDateTime \| null`, read-only |
 | `Versioned` | `version: integer`, read and update |
@@ -600,8 +629,8 @@ envelope and the rate limit's headers.
   `3.1.0/openapi.yaml` and `3.2.0/openapi.yaml`: point the generator's input
   at one of them.
 - **The library's schema names are global.** `BadRequestBody` …
-  `InternalServerErrorBody`, `ValidationIssue`, `ValidationTarget`, `Uuid`,
-  `Email`, and each `<Item>Page` and `<Item>CursorPage` are emitted under
+  `InternalServerErrorBody`, `ValidationIssue`, `ValidationTarget`, the scalars' components
+  (`UUID`, `EmailAddress`, `Latitude`, …), and each `<Item>Page` and `<Item>CursorPage` are emitted under
   those names, without a namespace, once the spec uses them. A model of the
   same name in your spec then fails with `duplicate-type-name`
   ([troubleshooting](docs/troubleshooting.md)).
@@ -616,6 +645,8 @@ envelope and the rate limit's headers.
   what a handler answers;
 - [Authentication](docs/guide/auth.md): `JanusAuth`, and the guards'
   replies without a body;
+- [Scalars](docs/guide/scalars.md): every scalar of `@nxgt/graphql-scalars`
+  by category, with what each takes and what its pattern leaves out;
 - [Scalars and columns](docs/guide/columns.md): `uuid`, `email`, and the
   columns `@nxgt/drizzle` stamps;
 - [Headers](docs/guide/headers.md): `Idempotency-Key`, the rate limit and

package/docs/README.md

@@ -8,6 +8,7 @@ The [package README](../README.md) is the short version.
 | [Error replies](guide/errors.md) | declaring what an operation answers when it fails |
 | [Pagination](guide/pagination.md) | listing a collection a page at a time |
 | [Authentication](guide/auth.md) | protecting an operation with a `@nxgt/janus` session |
+| [Scalars](guide/scalars.md) | typing a latitude, a currency, an IP address or a port, and knowing what each pattern leaves out |
 | [Scalars and columns](guide/columns.md) | typing ids and addresses, and the columns a row carries |
 | [Headers](guide/headers.md) | making a write idempotent, or declaring a rate limit |
 | [Sorting](guide/sorting.md) | letting a client filter and sort a list |

package/docs/guide/columns.md

@@ -1,8 +1,9 @@
 # Scalars and columns
 
-Two scalars for the strings every API has, and the columns
+Scalars for the ids and addresses every API has, and the columns
 [`@nxgt/drizzle`](https://www.npmjs.com/package/@nxgt/drizzle) stamps a row
-with, as models to spread.
+with, as models to spread. The other scalars, by category, are in
+[Scalars](scalars.md).
 
 ## Scalars
 
@@ -18,7 +19,7 @@ namespace Blog;
 model Author {
   @visibility(Lifecycle.Read) id: uuid;
   email: email;
-  site?: url;
+  site?: httpUrl;
 }
 
 @route("/authors/{authorId}")
@@ -27,12 +28,25 @@ model Author {
 
 | Scalar | Emitted as | Generated | Refused |
 | --- | --- | --- | --- |
-| `uuid` | `$ref` to the schema `Uuid`: `type: string`, `format: uuid` | `type Uuid = string`, `zUuid = z.guid()` | `42`, in a path, a query or a body |
-| `email` | `$ref` to the schema `Email`: `format: email` | `type Email = string`, `zEmail = z.email()` | `not an address` |
-| `url` | TypeSpec's own: `format: uri`, inline | `z.url()` | `not a url` |
-
-`z.guid()` checks the shape of a UUID, as JSON Schema's `uuid` does, not
-the version and variant bits `z.uuid()` also checks.
+| `uuid` | `$ref` to the schema `UUID`: `type: string`, `format: uuid`, a pattern, `x-nxgt-scalar: UUID` | `type UUID = string`, `zUUID = z.guid().regex(…)` | `42`, a UUID with no hyphens or of version 9, in a path, a query or a body |
+| `email` | an alias of `emailAddress`: `$ref` to the schema `EmailAddress`, `format: email`, a pattern, `x-nxgt-scalar: EmailAddress` | `type EmailAddress = string`, `zEmailAddress = z.string().regex(…)` | `not an address`, `ada@localhost` |
+| `httpUrl` | `$ref` to the schema `URL`: `format: uri`, a pattern for `http:` and `https:`, `x-nxgt-scalar: URL` | `type URL = string`, `zURL = z.string().regex(…)` | `not a url`, `javascript:alert(1)` |
+
+TypeSpec's own `url` takes any scheme, inline, as `z.url()`; `httpUrl` is
+the `http:` and `https:` page address. `httpUrl` and `email` are generated as
+`z.string().regex(…)`: the pattern is the rule, as the generator leaves out
+`z.url()`, which trims its input, and `z.email()`, which refuses
+`ada@x.xn--p1ai`, an internationalised top-level domain `email` accepts.
+
+`uuid` takes an RFC 9562 UUID, any version 1 to 8 with the RFC variant, or
+the nil or the max UUID, in any case, as `@nxgt/graphql-scalars`' `UUID`
+does: the pattern adds those checks to the shape `z.guid()` checks. `uuidV4`,
+`uuidV7` and `guid` (any 8-4-4-4-12 hexadecimal) are the narrower and the
+looser ones. `email` is `emailAddress`, under the name it had first.
+
+The schema names changed in 0.10.0: `Uuid` and `Email` became `UUID` and
+`EmailAddress`, and a UUID of no known version is refused. A spec that needs
+the old shape-only id writes `guid`.
 
 ## Columns
 
@@ -112,6 +126,6 @@ without it is not checked against the version.
 
 ## Names
 
-`Uuid` and `Email` are schemas of their own, and their names are global: a
-model named `Email` in a spec that also uses `email` collides with it
+`UUID` and `EmailAddress` are schemas of their own, and their names are global: a
+model named `EmailAddress` in a spec that also uses `email` collides with it
 ([troubleshooting](../troubleshooting.md)).

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,14 @@ Nothing in progress.
 
 ## Shipped
 
+### 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

@@ -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/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;