tshex-cli 1.0.25 → 1.0.26

package/docs/generated-file-reference.md

@@ -9,12 +9,26 @@ The root contains the main entry points of the generated library.
 
 | File | Responsibility |
 | --- | --- |
-| `index.d.ts` | Declares root-level shared types such as `Generic<T>`. |
 | `main.ts` | Starts as a placeholder for the main implementation and root exports. |
 
-`index.d.ts` is the place for root-level type declarations. `main.ts` is the
-place for the main runtime entry point when the library starts exposing shared
-runtime components.
+`main.ts` is the place for the main runtime entry point when the library
+starts exposing shared runtime components.
+
+#### Types Files
+
+The `types/` directory contains root-level ambient type declarations.
+
+| File | Responsibility |
+| --- | --- |
+| `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/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`.
 
 #### Shared Domain Files
 
@@ -39,13 +53,29 @@ cases and integrations.
 | --- | --- |
 | `shared/application/validations.ts` | Declares the `Validatable` contract. |
 | `shared/application/services.ts` | Declares the `Service` base class for use cases. |
-| `shared/application/http.ts` | Declares framework-agnostic HTTP contracts. |
 | `shared/application/loggers.ts` | Declares shared log levels and the `Logger` contract. |
 | `shared/application/events.ts` | Declares `Event`, `EventHandler`, and `EventDispatcher`. |
 
 These files do not implement frameworks or transports. They define the stable
 contracts that adapters and services can share.
 
+#### Shared HTTP Files
+
+The `shared/application/http` directory groups the framework-agnostic HTTP
+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/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.
+
 #### Shared Data Files
 
 The generated template also includes a small set of data-access abstractions.

package/docs/library-structure.md

@@ -15,15 +15,34 @@ The root contains the entry points of the generated library.
 
 ```mermaid
 flowchart TD
-    root["Library root"] --> index["index.d.ts"]
+    root["Library root"] --> types["types/"]
     root --> main["main.ts"]
     root --> shared["shared/"]
     root --> users["users/"]
 ```
 
-`index.d.ts` defines root-level types. `main.ts` starts as a placeholder for
-main runtime exports. The rest of the structure lives under `shared/` and one
-or more context directories.
+`types/` groups the root-level type declarations. `main.ts` starts as a
+placeholder for main runtime exports. The rest of the structure lives under
+`shared/` and one or more context directories.
+
+#### Types
+
+The `types/` directory contains ambient type declarations shared by the whole
+library.
+
+```mermaid
+flowchart TD
+    types["types/"] --> typesObjects["objects.d.ts"]
+    types --> json["json.d.ts"]
+    types --> cldr["cldr.d.ts"]
+    types --> iana["iana.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
+database.
 
 #### Shared
 

package/docs/library-types.md

@@ -7,10 +7,10 @@ data but does not need a more specific shape yet.
 
 #### Root Declaration
 
-The root declaration lives in `index.d.ts`.
+The root declaration lives in `types/objects.d.ts`.
 
-```ts title="index.d.ts"
-type Generic<T = unknown> = Record<string, T>
+```ts title="types/objects.d.ts"
+export type Generic<T = unknown> = Record<string, T>
 ```
 
 This alias expands to `Record<string, T>`. When no type argument is provided,
@@ -21,6 +21,8 @@ the values use `unknown`.
 In the following example we use `Generic<string>` for a set of plain filters.
 
 ```ts
+import { type Generic } from './types/objects.js'
+
 const filters: Generic<string> = {
     status: 'active',
     sort: 'email',
@@ -35,6 +37,8 @@ value shape for the whole object.
 Now consider the same pattern without providing a type argument.
 
 ```ts
+import { type Generic } from './types/objects.js'
+
 const metadata: Generic = {
     retries: 2,
     cached: true,
@@ -64,6 +68,44 @@ generic record.
 > `Generic<T>` is intentionally small. It should support loose object contracts,
 > not replace explicit domain or application types.
 
+#### JSON Values
+
+The generated root also declares a small family of types that describe plain,
+serializable JSON data. They live in `types/json.d.ts`.
+
+```ts title="types/json.d.ts"
+export type JsonPrimitive = string | number | boolean | null
+
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray
+
+export type JsonArray = readonly JsonValue[]
+
+export type JsonObject = {
+    readonly [key: string]: JsonValue
+}
+```
+
+`JsonPrimitive` covers the scalar values allowed in JSON. `JsonValue` extends
+that with nested objects and arrays, so it recursively describes any value that
+survives a round trip through `JSON.stringify()`/`JSON.parse()`. `JsonObject`
+and `JsonArray` name the two composite shapes so other declarations can refer
+to them directly instead of repeating the union.
+
+```ts
+import { type JsonValue } from './types/json.js'
+
+function toLogPayload(value: JsonValue): string {
+    return JSON.stringify(value)
+}
+```
+
+Use `JsonValue` and `JsonObject` when a contract must guarantee its data is
+plain and serializable, such as request payloads, stored metadata, or wire
+formats. Prefer `Generic<T>` instead when the value type is not required to be
+JSON-safe. `shared/application/http/json-api.ts` and
+`shared/application/http/json-web-token.ts` build on these types to describe
+JSON:API documents and JOSE/JWT structures.
+
 #### Next Step
 
 For the rest of the generated shared abstractions, continue with the pages in

package/docs/shared/application/http.md

@@ -1,94 +1,64 @@
 ### HTTP
 
-The HTTP contracts define a transport-facing boundary without coupling the
-generated structure to a specific framework.
+The HTTP contracts define a framework-agnostic, transport-facing boundary.
 They are used when an adapter needs to describe requests, responses, handlers,
 or middleware in a consistent way.
 
-The generated template keeps `HttpRequest` and `HttpResponse` empty on purpose.
-Each project can extend them with the fields required by its own transport.
+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.
 
-#### Response Body
+The concern is split across four files under `shared/application/http/`:
 
-`HttpResponseBody` is responsible for standardizing the shape of the response
-payload.
+1. `http.ts` for the request/response boundary contracts and `HttpError`;
+2. `json-api.ts` for a type-only JSON:API v1.1 specification;
+3. `json-web-token.ts` for a type-only JOSE/JWT specification;
+4. `opengraph.ts` for a type-only Open Graph and social metadata specification.
 
-```ts title="shared/application/http.ts"
-export interface HttpResponseBody {
-    readonly data: Record<string, unknown> | null
-    readonly errors: string[] | null
-    readonly links: Record<string, URL> | null
-}
-```
-
-This structure makes successful data, error messages, and related links
-explicit without forcing a specific router or server implementation.
+Only `http.ts` contains runtime code. The other three files describe
+compile-time structure for widely used formats so adapters do not have to
+redefine them; they do not implement parsing, validation, or serialization.
 
 #### Request Handler
 
 `HttpRequestHandler` is responsible for processing a request and returning a
 response.
 
-```ts title="shared/application/http.ts"
+```ts title="shared/application/http/http.ts"
 export interface HttpRequestHandler {
-    handle(request: HttpRequest): HttpResponse | Promise<HttpResponse>
+    handle(request: Request): Response | Promise<Response>
 }
 ```
 
-In the following example we define adapter-specific request and response types,
-then implement a handler.
+In the following example we implement a handler using the standard `Request`
+and `Response` objects.
 
 ```ts title="users/adapters/get-user-handler.ts"
-import {
-    HttpRequest,
-    HttpRequestHandler,
-    HttpResponse,
-    HttpResponseBody,
-} from '../../shared/application/http.js'
-
-interface UserHttpRequest extends HttpRequest {
-    readonly params: {
-        id: string
-    }
-}
-
-interface UserHttpResponse extends HttpResponse {
-    readonly status: number
-    readonly body: HttpResponseBody
-}
+import { HttpRequestHandler } from '../../shared/application/http/http.js'
 
 export class GetUserHandler implements HttpRequestHandler {
-    public handle(request: HttpRequest): HttpResponse {
-        const typedRequest = request as UserHttpRequest
-
-        return {
-            status: 200,
-            body: {
-                data: {
-                    id: typedRequest.params.id,
-                },
-                errors: null,
-                links: null,
-            },
-        } as UserHttpResponse
+    public handle(request: Request): Response {
+        const id = new URL(request.url).pathname.split('/').at(-1)
+
+        return Response.json({ data: { id } }, { status: 200 })
     }
 }
 ```
 
-The generated `HttpRequest` and `HttpResponse` interfaces stay empty, so the
-adapter declares the transport-specific fields locally. This keeps the shared
-contract small and portable.
+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 `json-api.ts`.
 
 #### Middleware
 
 `HttpMiddleware` is responsible for running logic before or around the handler.
 
-```ts title="shared/application/http.ts"
+```ts title="shared/application/http/http.ts"
 export interface HttpMiddleware {
     process(
-        request: HttpRequest,
+        request: Request,
         handler: HttpRequestHandler,
-    ): HttpResponse | Promise<HttpResponse>
+    ): Response | Promise<Response>
 }
 ```
 
@@ -97,29 +67,69 @@ Now that the handler exists, middleware can wrap it.
 ```ts title="users/adapters/request-logger.ts"
 import {
     HttpMiddleware,
-    HttpRequest,
     HttpRequestHandler,
-    HttpResponse,
-} from '../../shared/application/http.js'
+} from '../../shared/application/http/http.js'
 
 export class RequestLoggerMiddleware implements HttpMiddleware {
     public async process(
-        request: HttpRequest,
+        request: Request,
         handler: HttpRequestHandler,
-    ): Promise<HttpResponse> {
+    ): Promise<Response> {
         void request
         return handler.handle(request)
     }
 }
 ```
 
-This middleware does not mutate the request or response. It only shows where
+This middleware passes the request through unchanged, showing where
 cross-cutting behavior belongs in the generated HTTP abstraction.
 
-> **Warning**
-> Do not treat the shared HTTP contracts as a full framework abstraction. They
-> only define the minimum boundary for adapters. Routing, serialization, and
-> status code policies remain the responsibility of the concrete transport.
+#### HTTP Errors
+
+`HttpError` is responsible for carrying an HTTP status code alongside a
+matching message.
+
+```ts title="shared/application/http/http.ts"
+export class HttpError extends Error {
+    public static readonly messages: { [code: number]: string } = Object.freeze({
+        400: 'Bad Request',
+        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 to its reason
+phrase. A caller can throw `new HttpError(404)` to get the standard message for
+free, or pass an explicit `message` to override it. Codes outside the map fall
+back to `'Unknown Error'`.
+
+```ts title="users/adapters/get-user-handler.ts"
+import { HttpError } from '../../shared/application/http/http.js'
+
+function assertFound<T>(value: T | null): T {
+    if (value === null) {
+        throw new HttpError(404)
+    }
+
+    return value
+}
+```
+
+> **Note**
+> The shared HTTP contracts define the minimum boundary for adapters. Routing,
+> serialization, and status code policies beyond `HttpError` are the
+> responsibility of the concrete transport.
 
 #### Example Flow
 
@@ -132,3 +142,142 @@ flowchart LR
 
 This flow keeps the transport boundary explicit while leaving framework choices
 to the adapter layer.
+
+#### 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.
+
+The main building blocks are:
+
+- `JsonApiResourceObject` / `JsonApiResourceIdentifier` for resources and
+  resource linkage, generic over the resource `type`, `attributes`, and
+  `relationships`;
+- `JsonApiRelationship`, `JsonApiToOneRelationship`, and
+  `JsonApiToManyRelationship` for relationship objects;
+- `JsonApiError` for the top-level error object;
+- `JsonApiDocument` (and its narrower aliases such as
+  `JsonApiSingleResourceDocument` and `JsonApiResourceCollectionDocument`) for
+  the top-level document, discriminated between a data document, an error
+  document, and a meta-only document;
+- `JsonApiAtomicOperationsDocument` / `JsonApiAtomicResultsDocument` for the
+  Atomic Operations extension request and response bodies.
+
+```ts title="users/adapters/get-user-handler.ts"
+import { HttpRequestHandler } from '../../shared/application/http/http.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 })
+    }
+}
+```
+
+> **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.
+
+#### JSON Web Tokens
+
+`json-web-token.ts` declares a type-only implementation of the JOSE and JWT
+family of RFCs (JWS, JWE, JWK, JWT, and related extensions such as DPoP and
+selective disclosure). It lets an adapter describe tokens and keys precisely
+without depending on a specific JOSE library's own types.
+
+The main building blocks are:
+
+- branded wire-format primitives such as `Base64Url`, `NumericDate`, and
+  `CompactJwt`;
+- `JsonWebKey` / `JsonWebKeySet` for keys, covering EC, RSA, `oct`, OKP, and
+  ML-DSA (`AKP`) key types;
+- `JwsHeader` / `JweHeader` for protected header parameters, and
+  `JwsJsonSerialization` / `JweJsonSerialization` for the JSON serializations;
+- `JwtClaims` (built on `IanaRegisteredJwtClaims`) for decoded payloads, plus
+  ready-made profiles such as `OpenIdConnectIdTokenClaims`,
+  `OAuth2JwtAccessTokenClaims`, `DpopProofClaims`, and `SdJwtClaims`;
+- service contracts an adapter can implement against a concrete JOSE
+  library: `JwtDecoder`, `JwsSigner`, `JwsVerifier`, `JweEncrypter`,
+  `JweDecrypter`, `JwkThumbprinter`, and `JwksResolver`, plus
+  `JwtValidationResult` for the outcome of validating a token against a
+  `JwtValidationPolicy`.
+
+```ts title="users/adapters/verify-access-token.ts"
+import {
+    JwsVerifier,
+    OAuth2JwtAccessTokenClaims,
+    CompactJws,
+    JsonWebKey,
+} from '../../shared/application/http/json-web-token.js'
+
+export function verifyAccessToken(
+    verifier: JwsVerifier,
+    token: CompactJws,
+    key: JsonWebKey,
+) {
+    return verifier.verify<OAuth2JwtAccessTokenClaims>(token, key)
+}
+```
+
+> **Hint**
+> This module has no runtime implementation. Pair it with a concrete JOSE
+> library (for signing, encryption, or verification) and use these types to
+> annotate its inputs and outputs.
+
+#### Open Graph
+
+`opengraph.ts` declares a type-only implementation of the
+[Open Graph protocol](https://ogp.me/), the Twitter Card meta tags, and
+Facebook's compatibility extensions. It is used when an adapter needs to build
+or read the social-sharing metadata of a page.
+
+The main building blocks are:
+
+- `OpenGraphMetadata`, a union of every standard Open Graph object type
+  (`OpenGraphWebsite`, `OpenGraphArticle`, `OpenGraphBook`, `OpenGraphProfile`,
+  the `music.*` and `video.*` types, `OpenGraphPaymentLink`, and
+  `OpenGraphCustomObject` for CURIE-style custom types);
+- `OpenGraphMetaTag` and `TwitterMetaTag`, the flat `property`/`content` and
+  `name`/`content` tag representations closer to the actual `<meta>` markup;
+- `SocialMetadataDocument`, an aggregate of Open Graph, Twitter, Facebook, and
+  standard head metadata for a single page, and `RawSocialMetadataDocument`
+  for its rendered, tag-list form.
+
+```ts title="users/adapters/user-profile-metadata.ts"
+import { OpenGraphProfile } from '../../shared/application/http/opengraph.js'
+
+export function buildProfileMetadata(username: string): OpenGraphProfile {
+    return {
+        type: 'profile',
+        title: username,
+        url: `https://example.com/users/${username}`,
+        images: [{ url: `https://example.com/users/${username}/avatar.png` }],
+        username,
+    }
+}
+```
+
+> **Hint**
+> This module has no runtime implementation, including no HTML rendering. Use
+> `OpenGraphMetadata` to build the data and a separate template or renderer to
+> emit the `<meta>` tags described by `OpenGraphMetaTag`/`TwitterMetaTag`.

package/docs/shared/application/loggers.md

@@ -28,22 +28,57 @@ any adapter to use a particular logger implementation.
 `Logger` is responsible for receiving log data from the application layer.
 
 ```ts title="shared/application/loggers.ts"
+import { type TimeZone } from '../../types/iana.js'
+import { type Locale } from '../../types/cldr.js'
+
 export abstract class Logger {
-	public abstract debug(data: unknown): void
+    [property: string]: unknown
 
-	public abstract info(data: unknown): void
+    public name: string = 'main'
 
-	public abstract warning(data: unknown): void
+    public level: number = 0
 
-	public abstract error(data: unknown): void
+    public datetimeLocales: Locale[] = ['en-GB']
 
-	public abstract critical(data: unknown): void
-}
+    public datetimeFormatOptions: Intl.DateTimeFormatOptions & { timeZone: TimeZone } = {
+        timeZone: 'UTC',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        fractionalSecondDigits: 3,
+        hourCycle: 'h23'
+    }
+
+    public abstract debug(data: unknown): void
+
+    public abstract info(data: unknown): void
+
+    public abstract warning(data: unknown): void
+
+    public abstract error(data: unknown): void
+
+    public abstract critical(data: unknown): void
+
+    protected getCurrentDatetime(): string {
+        return new Date().toLocaleString(this.datetimeLocales, this.datetimeFormatOptions)
+    }
+} //:: class
 ```
 
 The contract is intentionally small. It defines the actions the application can
 request, while the adapter decides how those actions are persisted or displayed.
 
+`name` and `level` identify the logger instance and its minimum severity, so an
+adapter can decide which logs to emit or route. `datetimeLocales` and
+`datetimeFormatOptions` control how `getCurrentDatetime()` formats the current
+moment, using the `Locale` type from `types/cldr.d.ts` and the `TimeZone` type
+from `types/iana.d.ts`. Adapters can use `getCurrentDatetime()` to timestamp
+log entries consistently, regardless of the runtime environment's own locale
+or timezone.
+
 #### First Adapter
 
 In the following example we implement a console-based logger.
@@ -51,43 +86,32 @@ In the following example we implement a console-based logger.
 ```ts title="users/adapters/console-logger.ts"
 import { Logger } from '../../shared/application/loggers.js'
 
-type ExternalService = {
-    debug(data: unknown): void
-    info(data: unknown): void
-    warning(data: unknown): void
-    error(data: unknown): void
-    critical(data: unknown): void
-}
-
 export class ConsoleLogger extends Logger {
-    constructor(protected readonly externalService: ExternalService) {
-        super()
-    }
-
 	public debug(data: unknown): void {
-		this.externalService.debug(data)
+		console.debug(this.getCurrentDatetime(), this.name, data)
 	}
 
 	public info(data: unknown): void {
-		this.externalService.info(data)
+		console.info(this.getCurrentDatetime(), this.name, data)
 	}
 
 	public warning(data: unknown): void {
-		this.externalService.warning(data)
+		console.warn(this.getCurrentDatetime(), this.name, data)
 	}
 
 	public error(data: unknown): void {
-		this.externalService.error(data)
+		console.error(this.getCurrentDatetime(), this.name, data)
 	}
 
 	public critical(data: unknown): void {
-		this.externalService.critical(data)
+		console.error(this.getCurrentDatetime(), this.name, data)
 	}
 }
 ```
 
 This adapter satisfies the generated contract without changing the application
-layer.
+layer. It reuses `getCurrentDatetime()` to prefix every entry with a
+consistently formatted timestamp.
 
 #### Service Integration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tshex-cli",
-  "version": "1.0.25",
+  "version": "1.0.26",
   "author": "https://github.com/virtualitems/",
   "license": "MIT",
   "description": "Typescript Hexagonal Architecture CLI",