tshex-cli 1.0.27 → 1.0.28

package/docs/generated-file-reference.md

@@ -22,13 +22,14 @@ The `types/` directory contains root-level ambient type declarations.
 | --- | --- |
 | `types/objects.d.ts` | Declares root-level shared types such as `Generic<T>`. |
 | `types/json.d.ts` | Declares `JsonValue` and the other plain, serializable JSON shapes. |
-| `types/cldr.d.ts` | Declares the `Locale` union from Unicode CLDR. |
-| `types/iana.d.ts` | Declares the `TimeZone` union from the IANA time zone database. |
+| `types/locales.d.ts` | Declares the `Locale` union from Unicode CLDR. |
+| `types/timezones.d.ts` | Declares the `TimeZone` union from the IANA time zone database. |
 
 `types/objects.d.ts` and `types/json.d.ts` are the place for general-purpose
-root-level type declarations. `types/cldr.d.ts` and `types/iana.d.ts` are
-generated reference types consumed by other shared contracts, such as
-`shared/application/loggers.ts`.
+root-level type declarations. `types/locales.d.ts` and `types/timezones.d.ts`
+are generated reference types consumed by other shared contracts, such as
+`shared/application/loggers.ts`. Each file is documented in its own page under
+`types/*.md`.
 
 #### Shared Domain Files
 
@@ -66,15 +67,17 @@ boundary and the type-only specifications for common web content formats.
 
 | File | Responsibility |
 | --- | --- |
-| `shared/application/http/http.ts` | Declares `HttpRequestHandler`, `HttpMiddleware`, and `HttpError`. |
+| `shared/application/http/handlers.ts` | Declares `HttpRequestHandler` and `HttpMiddleware`. |
+| `shared/application/http/errors.ts` | Declares `HttpError`. |
 | `shared/application/http/json-api.ts` | Type-only JSON:API v1.1 document, resource, and Atomic Operations declarations. |
 | `shared/application/http/json-web-token.ts` | Type-only JOSE/JWT declarations (JWK, JWS, JWE, JWT claims). |
 | `shared/application/http/opengraph.ts` | Type-only Open Graph, Twitter Card, and social metadata declarations. |
 
-`http.ts` is the only file in this directory with runtime code. `json-api.ts`,
-`json-web-token.ts`, and `opengraph.ts` contain compile-time structure only;
-they describe the shape of external formats without implementing parsing,
-validation, or serialization.
+`handlers.ts` and `errors.ts` are the only files in this directory with
+runtime code. `json-api.ts`, `json-web-token.ts`, and `opengraph.ts` contain
+compile-time structure only; they describe the shape of external formats
+without implementing parsing, validation, or serialization. Each file is
+documented in its own page under `shared/application/http/*.md`.
 
 #### Shared Data Files
 

package/docs/library-structure.md

@@ -34,14 +34,14 @@ library.
 flowchart TD
     types["types/"] --> typesObjects["objects.d.ts"]
     types --> json["json.d.ts"]
-    types --> cldr["cldr.d.ts"]
-    types --> iana["iana.d.ts"]
+    types --> locales["locales.d.ts"]
+    types --> timezones["timezones.d.ts"]
 ```
 
 `types/objects.d.ts` defines root-level types such as `Generic<T>`.
 `types/json.d.ts` defines `JsonValue` and the other plain, serializable JSON
-shapes. `types/cldr.d.ts` declares the `Locale` union from Unicode CLDR.
-`types/iana.d.ts` declares the `TimeZone` union from the IANA time zone
+shapes. `types/locales.d.ts` declares the `Locale` union from Unicode CLDR.
+`types/timezones.d.ts` declares the `TimeZone` union from the IANA time zone
 database.
 
 #### Shared

package/docs/shared/application/http/errors.md

@@ -0,0 +1,96 @@
+### HTTP Errors
+
+`HttpError` carries an HTTP status code alongside a matching message.
+It is used when a use case or adapter needs to signal a specific HTTP outcome
+without depending on a transport framework's own error type.
+
+#### Declaration
+
+```ts title="shared/application/http/errors.ts"
+export class HttpError extends Error {
+    public static readonly messages: { [code: number]: string } = Object.freeze({
+        400: 'Bad Request',
+        401: 'Unauthorized',
+        404: 'Not Found',
+        409: 'Conflict',
+        // ...remaining standard 4xx/5xx status codes
+        500: 'Internal Server Error',
+    })
+
+    public readonly code: number
+
+    constructor(code: number, message?: string) {
+        super(message ?? HttpError.messages[code] ?? 'Unknown Error')
+        this.code = code
+        this.name = 'HttpError'
+    }
+}
+```
+
+`HttpError.messages` maps every standard 4xx/5xx status code registered by the
+HTTP specification, from `400` to `511`, to its reason phrase.
+
+#### Implementation Options
+
+Constructing an `HttpError` supports three distinct outcomes, depending on
+what arguments are passed.
+
+**1. Known code, default message.** The message is looked up from
+`HttpError.messages`.
+
+```ts
+import { HttpError } from '../../shared/application/http/errors.js'
+
+const error = new HttpError(404)
+
+error.code // 404
+error.message // 'Not Found'
+```
+
+**2. Known code, explicit message.** The explicit message always takes
+precedence over the table.
+
+```ts
+import { HttpError } from '../../shared/application/http/errors.js'
+
+const error = new HttpError(409, 'Email is already registered')
+
+error.code // 409
+error.message // 'Email is already registered'
+```
+
+**3. Unrecognized code, no message.** Codes outside `HttpError.messages` fall
+back to `'Unknown Error'` instead of throwing.
+
+```ts
+import { HttpError } from '../../shared/application/http/errors.js'
+
+const error = new HttpError(499)
+
+error.code // 499
+error.message // 'Unknown Error'
+```
+
+#### Usage In A Handler
+
+```ts title="users/adapters/get-user-handler.ts"
+import { HttpError } from '../../shared/application/http/errors.js'
+
+function assertFound<T>(value: T | null): T {
+    if (value === null) {
+        throw new HttpError(404)
+    }
+
+    return value
+}
+```
+
+`assertFound()` throws the standard `404` message for free. The caller of the
+handler decides how a thrown `HttpError` is turned into a `Response`, since
+`errors.ts` only declares the error shape and not the response translation.
+
+> **Note**
+> `HttpError` only carries the status code and message. Serializing it into a
+> `Response` body, including it in a JSON:API error document (see
+> `shared/application/http/json-api.md`), and logging it are the
+> responsibility of the concrete adapter.

package/docs/shared/application/http/handlers.md

@@ -0,0 +1,102 @@
+### HTTP Handlers
+
+The handler contracts define a framework-agnostic, transport-facing boundary.
+They are used when an adapter needs to describe request processing and
+cross-cutting request logic in a consistent way, without depending on a
+specific server framework.
+
+The generated template relies on the standard `Request` and `Response` types
+from the Fetch API, so adapters work directly with the platform's own APIs.
+
+#### Request Handler
+
+`HttpRequestHandler` is responsible for processing a request and returning a
+response.
+
+```ts title="shared/application/http/handlers.ts"
+export interface HttpRequestHandler {
+    handle(request: Request): Response | Promise<Response>
+}
+```
+
+In the following example we implement a handler using the standard `Request`
+and `Response` objects.
+
+```ts title="users/adapters/get-user-handler.ts"
+import { HttpRequestHandler } from '../../shared/application/http/handlers.js'
+
+export class GetUserHandler implements HttpRequestHandler {
+    public handle(request: Request): Response {
+        const id = new URL(request.url).pathname.split('/').at(-1)
+
+        return Response.json({ data: { id } }, { status: 200 })
+    }
+}
+```
+
+Using the standard `Request` and `Response` types means the adapter relies on
+the platform's own APIs, such as `request.url`, `request.headers`, and
+`Response.json`. The shape of the JSON body itself, when the adapter follows
+JSON:API, is described by the document types in
+`shared/application/http/json-api.md`.
+
+`handle()` can be synchronous or asynchronous; both `Response` and
+`Promise<Response>` are valid return types, so an adapter that awaits a
+database call satisfies the same contract as one that returns immediately.
+
+#### Middleware
+
+`HttpMiddleware` is responsible for running logic before or around the
+handler.
+
+```ts title="shared/application/http/handlers.ts"
+export interface HttpMiddleware {
+    process(
+        request: Request,
+        handler: HttpRequestHandler,
+    ): Response | Promise<Response>
+}
+```
+
+Now that the handler exists, middleware can wrap it.
+
+```ts title="users/adapters/request-logger.ts"
+import {
+    HttpMiddleware,
+    HttpRequestHandler,
+} from '../../shared/application/http/handlers.js'
+
+export class RequestLoggerMiddleware implements HttpMiddleware {
+    public async process(
+        request: Request,
+        handler: HttpRequestHandler,
+    ): Promise<Response> {
+        void request
+        return handler.handle(request)
+    }
+}
+```
+
+This middleware passes the request through unchanged, showing where
+cross-cutting behavior belongs in the generated HTTP abstraction. A
+short-circuiting middleware, such as an authentication guard, follows the same
+shape but returns a `Response` (for example built from
+`shared/application/http/errors.md`'s `HttpError`) without calling
+`handler.handle()`.
+
+> **Note**
+> The handler contracts define the minimum boundary for adapters. Routing,
+> middleware chaining/composition, and status code policies beyond
+> `HttpError` are the responsibility of the concrete transport.
+
+#### Example Flow
+
+```mermaid
+flowchart LR
+    request[Request] --> middleware[Middleware]
+    middleware --> handler[Handler]
+    handler --> response["Response body"]
+```
+
+This flow keeps the transport boundary explicit while leaving framework
+choices to the adapter layer.

package/docs/shared/application/http/json-api.md

@@ -0,0 +1,235 @@
+### JSON:API
+
+`json-api.ts` declares a type-only implementation of the
+[JSON:API v1.1](https://jsonapi.org/format/) specification, including the
+[Atomic Operations extension](https://jsonapi.org/ext/atomic/). It gives an
+adapter a shared vocabulary for request and response bodies without forcing a
+particular server framework.
+
+This module has no runtime code. It only describes compile-time structure;
+rules that depend on runtime values, URI validity, document-wide uniqueness,
+full linkage, HTTP semantics, or member-name character validation still
+require explicit checks in the adapter.
+
+#### Resource Identifiers
+
+A resource is referenced in one of two ways, depending on whether the server
+has assigned it a permanent id yet.
+
+| Type | Option | Required members |
+| --- | --- | --- |
+| `JsonApiPersistedResourceIdentifier` | Server-assigned id | `type`, `id` |
+| `JsonApiLocalResourceIdentifier` | Client-assigned local id, not yet persisted | `type`, `lid` |
+
+`JsonApiResourceIdentifier` is the union of both.
+
+```ts
+import type { JsonApiResourceIdentifier } from '../../../shared/application/http/json-api.js'
+
+const persisted: JsonApiResourceIdentifier<'users'> = { type: 'users', id: '1' }
+const local: JsonApiResourceIdentifier<'users'> = { type: 'users', lid: 'tmp-1' }
+```
+
+Resource linkage (`JsonApiResourceLinkage`) is either a single identifier or
+`null` (`JsonApiToOneLinkage`), or an array of identifiers
+(`JsonApiToManyLinkage`).
+
+#### Resource Objects
+
+A resource object has the same persisted-versus-local split as its
+identifier.
+
+| Type | Option | `id` | `lid` |
+| --- | --- | --- | --- |
+| `JsonApiResourceObject` | Server-originated resource | required | optional |
+| `JsonApiNewResourceObject` | Client-originated resource without a server id | never | optional |
+
+`JsonApiCreateResourceObject` is the union accepted by create requests, since
+a client is allowed to submit a client-generated id.
+
+```ts title="users/adapters/get-user-handler.ts"
+import { HttpRequestHandler } from '../../shared/application/http/handlers.js'
+import {
+    JsonApiSingleResourceDocument,
+    JsonApiResourceObject,
+} from '../../shared/application/http/json-api.js'
+
+type UserAttributes = { email: string }
+type UserResource = JsonApiResourceObject<'users', UserAttributes>
+
+export class GetUserHandler implements HttpRequestHandler {
+    public handle(request: Request): Response {
+        const id = new URL(request.url).pathname.split('/').at(-1) ?? ''
+
+        const body: JsonApiSingleResourceDocument<UserResource> = {
+            data: {
+                type: 'users',
+                id,
+                attributes: { email: 'ada@example.com' },
+            },
+        }
+
+        return Response.json(body, { status: 200 })
+    }
+}
+```
+
+#### Relationships
+
+`JsonApiRelationship` requires at least one of `links`, `data`, or `meta`, per
+the base specification. Two narrower aliases fix the shape of `data`:
+
+| Type | `data` shape |
+| --- | --- |
+| `JsonApiToOneRelationship` | single identifier or `null` |
+| `JsonApiToManyRelationship` | array of identifiers |
+
+```ts
+import type {
+    JsonApiToOneRelationship,
+    JsonApiToManyRelationship,
+} from '../../../shared/application/http/json-api.js'
+
+const author: JsonApiToOneRelationship<{ type: 'authors' }> = {
+    data: { type: 'authors', id: '9' },
+}
+
+const comments: JsonApiToManyRelationship<{ type: 'comments' }> = {
+    data: [{ type: 'comments', id: '1' }, { type: 'comments', id: '2' }],
+}
+```
+
+#### Documents
+
+`JsonApiDocument` is a discriminated union over which top-level member is
+required. Exactly one of these three shapes is valid at a time:
+
+| Type | Required top-level member | Use |
+| --- | --- | --- |
+| `JsonApiDataDocument` | `data` | success responses returning resources |
+| `JsonApiErrorDocument` | `errors` (non-empty) | failure responses |
+| `JsonApiMetaDocument` | `meta` | responses with no primary data, such as a heartbeat |
+
+`JsonApiDataDocument` itself is narrowed by four ready-made aliases depending
+on what `data` contains:
+
+| Alias | `data` shape |
+| --- | --- |
+| `JsonApiSingleResourceDocument` | resource or `null` |
+| `JsonApiResourceCollectionDocument` | array of resources |
+| `JsonApiSingleIdentifierDocument` | identifier or `null` |
+| `JsonApiIdentifierCollectionDocument` | array of identifiers |
+| `JsonApiRelationshipDocument` | any resource linkage |
+
+```ts
+import type {
+    JsonApiErrorDocument,
+    JsonApiMetaDocument,
+} from '../../../shared/application/http/json-api.js'
+
+const notFound: JsonApiErrorDocument = {
+    errors: [{ status: '404', title: 'Not Found' }],
+}
+
+const heartbeat: JsonApiMetaDocument<{ status: string }> = {
+    meta: { status: 'ok' },
+}
+```
+
+#### Request Documents
+
+Three request-only document shapes fix `data` to exactly what each operation
+accepts:
+
+| Type | `data` shape | Use |
+| --- | --- | --- |
+| `JsonApiCreateDocument` | `JsonApiCreateResourceObject` | `POST` requests |
+| `JsonApiUpdateDocument` | `JsonApiResourceObject` | `PATCH` requests |
+| `JsonApiRelationshipUpdateDocument` | resource linkage | relationship endpoints |
+
+`JsonApiQueryParameters` describes the standard `include`, `sort`, `filter`,
+and `page` query members, plus the `fields[TYPE]`, `filter[FIELD]`, and
+`page[FIELD]` bracketed member-name patterns.
+
+#### Errors
+
+`JsonApiError` requires at least one of `id`, `links`, `status`, `code`,
+`title`, `detail`, `source`, or `meta`.
+
+```ts
+import type { JsonApiError } from '../../../shared/application/http/json-api.js'
+
+const validationError: JsonApiError = {
+    status: '422',
+    title: 'Invalid Attribute',
+    detail: 'email must be a valid address',
+    source: { pointer: '/data/attributes/email' },
+}
+```
+
+#### Atomic Operations Extension
+
+The Atomic Operations extension adds a request document that carries one or
+more operations, and a response document that carries their results. Every
+operation targets either a resource or a relationship, and every operation
+uses exactly one of three op codes. `JsonApiAtomicStrictOperation` is the
+union of the seven concrete shapes that combination produces:
+
+| Type | `op` | Target | `data` |
+| --- | --- | --- | --- |
+| `JsonApiAtomicAddResourceOperation` | `'add'` | resource (`ref` optional, `href` optional) | resource to create |
+| `JsonApiAtomicUpdateResourceOperation` | `'update'` | resource | resource to replace |
+| `JsonApiAtomicRemoveResourceOperation` | `'remove'` | resource (required) | none |
+| `JsonApiAtomicUpdateToOneRelationshipOperation` | `'update'` | relationship (required) | identifier or `null` |
+| `JsonApiAtomicAddToManyRelationshipOperation` | `'add'` | relationship (required) | identifier array |
+| `JsonApiAtomicUpdateToManyRelationshipOperation` | `'update'` | relationship (required) | identifier array |
+| `JsonApiAtomicRemoveFromManyRelationshipOperation` | `'remove'` | relationship (required) | identifier array |
+
+A target is expressed through `ref` (a `JsonApiAtomicResourceRef` or
+`JsonApiAtomicRelationshipRef`) or through `href`, never both at once
+(`JsonApiExclusive`).
+
+```ts title="users/adapters/atomic-operations-handler.ts"
+import {
+    JsonApiAtomicOperationsDocument,
+    JsonApiAtomicResultsDocument,
+    JsonApiAtomicStrictOperation,
+} from '../../shared/application/http/json-api.js'
+
+const request: JsonApiAtomicOperationsDocument<JsonApiAtomicStrictOperation> = {
+    'atomic:operations': [
+        { op: 'add', href: '/users', data: { type: 'users', attributes: { email: 'ada@example.com' } } },
+        { op: 'update', ref: { type: 'users', id: '1' }, data: { type: 'users', id: '1', attributes: { email: 'ada@lovelace.dev' } } },
+        { op: 'remove', ref: { type: 'users', id: '2' } },
+        { op: 'update', ref: { type: 'users', id: '1', relationship: 'team' }, data: { type: 'teams', id: '9' } },
+        { op: 'add', ref: { type: 'teams', id: '9', relationship: 'members' }, data: [{ type: 'users', id: '1' }] },
+    ],
+}
+
+const response: JsonApiAtomicResultsDocument = {
+    'atomic:results': [{ data: { type: 'users', id: '1' } }, {}, {}, {}, {}],
+}
+```
+
+`JsonApiAtomicRequestDocument` and `JsonApiAtomicResponseDocument` are the
+named aliases for the request and response side of the extension; the latter
+is a union of `JsonApiAtomicResultsDocument` and `JsonApiErrorDocument`, since
+a batch of operations can still fail as a whole.
+
+#### Extension And `@`-Members
+
+`JsonApiExtensionMembers` and `JsonApiAtMembers` compose extension-namespaced
+(`'ext:member'`) and meta (`'@member'`) properties through intersections, for
+custom or third-party JSON:API extensions beyond Atomic Operations.
+
+```ts
+import type { JsonApiExtensionMembers, JsonApiResourceObject } from '../../../shared/application/http/json-api.js'
+
+type VersionedResource = JsonApiResourceObject<'users'> &
+    JsonApiExtensionMembers<'version', { id: string }>
+```
+
+> **Hint**
+> These declarations only provide compile-time structure. Rules that depend on
+> runtime values, URI validity, document-wide uniqueness, or member-name
+> character validation still require explicit checks in the adapter.