tshex-cli 1.0.26 → 1.0.28

package/docs/types/timezones.md

@@ -0,0 +1,75 @@
+### Time Zones
+
+`TimeZone` is a literal string union of every IANA time zone identifier.
+It is used when a contract needs to accept only valid time zone names instead
+of an open `string`.
+
+#### Declaration
+
+`TimeZone` lives in `types/timezones.d.ts` and is generated from the IANA time
+zone database.
+
+```ts title="types/timezones.d.ts"
+export type TimeZone =
+    | 'Africa/Cairo'
+    | 'America/Argentina/Buenos_Aires'
+    | 'America/Indiana/Indianapolis'
+    | 'America/New_York'
+    | 'Asia/Tokyo'
+    | 'Australia/Sydney'
+    | 'Europe/London'
+    | 'Europe/Paris'
+    | 'Pacific/Auckland'
+    | 'UTC'
+    // ...every other IANA time zone identifier
+```
+
+The generated file lists every canonical zone, including three-level entries
+such as `'America/Argentina/Buenos_Aires'` and `'America/Indiana/Knox'`, and
+ends with the fixed `'UTC'` identifier.
+
+#### Basic Usage
+
+```ts
+import { type TimeZone } from './types/timezones.js'
+
+function formatInZone(date: Date, timeZone: TimeZone): string {
+    return date.toLocaleString('en-GB', { timeZone })
+}
+
+formatInZone(new Date(), 'America/New_York')
+formatInZone(new Date(), 'UTC')
+```
+
+Because `TimeZone` only accepts identifiers the IANA database actually
+defines, a typo such as `'America/New York'` (with a space) fails at compile
+time instead of throwing a `RangeError` at runtime.
+
+#### Combining With `Intl.DateTimeFormatOptions`
+
+`TimeZone` is meant to replace the loosely typed `timeZone` member of
+`Intl.DateTimeFormatOptions`.
+
+```ts
+import { type TimeZone } from './types/timezones.js'
+
+const options: Intl.DateTimeFormatOptions & { timeZone: TimeZone } = {
+    timeZone: 'Europe/Madrid',
+    hour: '2-digit',
+    minute: '2-digit',
+}
+```
+
+The intersection keeps every other formatting option from
+`Intl.DateTimeFormatOptions` while narrowing `timeZone` to a real identifier.
+
+#### Where It Is Used
+
+`shared/application/loggers.ts` uses this same intersection for
+`Logger.datetimeFormatOptions`, defaulting `timeZone` to `'UTC'`. See
+`shared/application/loggers.md`.
+
+> **Hint**
+> `TimeZone` is a compile-time contract only. It does not validate that the
+> runtime's ICU data actually supports every listed zone, and it does not
+> account for future IANA database changes such as renamed or merged zones.

package/package.json

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

package/readme.md

@@ -82,7 +82,6 @@ The command creates this structure:
 
 ```text
 core/
-|-- index.d.ts
 |-- main.ts
 |-- shared/
 |   |-- application/
@@ -91,7 +90,12 @@ core/
 |   |   |   |-- managers.ts
 |   |   |   `-- repositories.ts
 |   |   |-- events.ts
-|   |   |-- http.ts
+|   |   |-- http/
+|   |   |   |-- errors.ts
+|   |   |   |-- handlers.ts
+|   |   |   |-- json-api.ts
+|   |   |   |-- json-web-token.ts
+|   |   |   `-- opengraph.ts
 |   |   |-- loggers.ts
 |   |   |-- services.ts
 |   |   `-- validations.ts
@@ -100,6 +104,11 @@ core/
 |       |-- entities.ts
 |       |-- errors.ts
 |       `-- value-objects.ts
+|-- types/
+|   |-- json.d.ts
+|   |-- locales.d.ts
+|   |-- objects.d.ts
+|   `-- timezones.d.ts
 `-- users/
     |-- adapters/
     |-- application/
@@ -224,15 +233,25 @@ From this point on, the guide is split into dedicated documents under `docs/`.
 ### General
 
 - [Project structure](https://github.com/virtualitems/tshex-cli/blob/main/docs/library-structure.md)
-- [Project types](https://github.com/virtualitems/tshex-cli/blob/main/docs/library-types.md)
 - [Context ports](https://github.com/virtualitems/tshex-cli/blob/main/docs/context-ports.md)
 - [Generated file reference](https://github.com/virtualitems/tshex-cli/blob/main/docs/generated-file-reference.md)
 
+### Types
+
+- [types/objects.d.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/types/objects.md)
+- [types/json.d.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/types/json.md)
+- [types/locales.d.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/types/locales.md)
+- [types/timezones.d.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/types/timezones.md)
+
 ### Shared application
 
 - [shared/application/data](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/data.md)
 - [shared/application/events.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/events.md)
-- [shared/application/http.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/http.md)
+- [shared/application/http/errors.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/http/errors.md)
+- [shared/application/http/handlers.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/http/handlers.md)
+- [shared/application/http/json-api.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/http/json-api.md)
+- [shared/application/http/json-web-token.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/http/json-web-token.md)
+- [shared/application/http/opengraph.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/http/opengraph.md)
 - [shared/application/loggers.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/loggers.md)
 - [shared/application/services.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/services.md)
 - [shared/application/validations.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/application/validations.md)

package/templates/lib/shared/application/http/{http.ts → errors.ts}

@@ -1,17 +1,3 @@
-/**
- * @description Http request handler to process incoming requests and generate responses.
- */
-export interface HttpRequestHandler {
-    handle(request: Request): Response | Promise<Response>
-}
-
-/**
- * @description An HTTP middleware that pipes requests through handlers.
- */
-export interface HttpMiddleware {
-    process(request: Request, handler: HttpRequestHandler): Response | Promise<Response>
-}
-
 /**
  * @description HTTP error with a specific status code and message.
  */

package/templates/lib/shared/application/http/handlers.ts

@@ -0,0 +1,13 @@
+/**
+ * @description Http request handler to process incoming requests and generate responses.
+ */
+export interface HttpRequestHandler {
+    handle(request: Request): Response | Promise<Response>
+}
+
+/**
+ * @description An HTTP middleware that pipes requests through handlers.
+ */
+export interface HttpMiddleware {
+    process(request: Request, handler: HttpRequestHandler): Response | Promise<Response>
+}

package/templates/lib/shared/application/loggers.ts

@@ -1,5 +1,5 @@
-import { type TimeZone } from '../../types/iana'
-import { type Locale } from '../../types/cldr'
+import { type TimeZone } from '../../types/timezones'
+import { type Locale } from '../../types/locales'
 
 export const DEBUG = 10
 

package/docs/library-types.md

@@ -1,112 +0,0 @@
-### Library Types
-
-The generated root type `Generic<T>` represents a plain object whose keys are
-strings and whose values share the same type.
-It provides a small common building block for code that works with object-like
-data but does not need a more specific shape yet.
-
-#### Root Declaration
-
-The root declaration lives in `types/objects.d.ts`.
-
-```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,
-the values use `unknown`.
-
-#### Basic Usage
-
-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',
-}
-```
-
-`filters` can only store string values because the type argument fixes the
-value shape for the whole object.
-
-#### Default Type Argument
-
-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,
-}
-```
-
-In this case the values use `unknown`. This is useful when the object is plain
-and open-ended, but the caller must narrow each value before using it in a
-specific way.
-
-#### When To Use It
-
-Use `Generic<T>` when the code needs a simple object contract and the exact set
-of keys is not the main concern.
-
-Typical uses include:
-
-1. filter objects;
-2. metadata objects;
-3. plain configuration maps;
-4. transport-neutral dictionaries.
-
-When the object has a stable business meaning, prefer a named type instead of a
-generic record.
-
-> **Hint**
-> `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
-`shared/application` and `shared/domain`.

package/docs/shared/application/http.md

@@ -1,283 +0,0 @@
-### HTTP
-
-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 relies on the standard `Request` and `Response` types
-from the Fetch API, so adapters work directly with the platform's own APIs.
-
-The concern is split across four files under `shared/application/http/`:
-
-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.
-
-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/http.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/http.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 `json-api.ts`.
-
-#### Middleware
-
-`HttpMiddleware` is responsible for running logic before or around the handler.
-
-```ts title="shared/application/http/http.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/http.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.
-
-#### 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
-
-```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.
-
-#### 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`.