tshex-cli 1.0.27 → 1.0.29

package/docs/types/json.md

@@ -0,0 +1,82 @@
+### JSON
+
+The generated root also declares a small family of types that describe plain,
+serializable JSON data.
+They are used when a contract must guarantee that a value survives a round
+trip through `JSON.stringify()` / `JSON.parse()`.
+
+#### Declaration
+
+These types 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 JSON-safe
+value. `JsonObject` and `JsonArray` name the two composite shapes so other
+declarations can refer to them directly instead of repeating the union.
+
+#### Implementation Options
+
+A `JsonValue` is always one of four shapes. Each one is a distinct option a
+consumer must be ready to handle.
+
+| Shape | Type | Example |
+| --- | --- | --- |
+| Primitive | `JsonPrimitive` | `'active'`, `42`, `true`, `null` |
+| Object | `JsonObject` | `{ id: '1', active: true }` |
+| Array | `JsonArray` | `[1, 2, 3]`, `[{ id: '1' }]` |
+| Nested composite | `JsonValue` | `{ tags: ['a', 'b'], meta: { retries: 2 } }` |
+
+```ts
+import { type JsonValue } from './types/json.js'
+
+const primitive: JsonValue = 'ada@example.com'
+const object: JsonValue = { id: '1', active: true }
+const array: JsonValue = [1, 2, 3]
+const nested: JsonValue = { tags: ['a', 'b'], meta: { retries: 2 } }
+```
+
+All four are valid `JsonValue` values because the type is a recursive union;
+there is no separate constructor or runtime check to opt into a shape.
+
+#### Basic Usage
+
+```ts
+import { type JsonValue } from './types/json.js'
+
+function toLogPayload(value: JsonValue): string {
+    return JSON.stringify(value)
+}
+```
+
+Because `JsonValue` excludes functions, `undefined`, symbols, and other
+non-serializable values, `toLogPayload()` can call `JSON.stringify()` without
+guarding against values that would silently disappear or throw.
+
+#### JsonObject Versus Generic
+
+Use `JsonObject`/`JsonValue` when a contract must guarantee its data is plain
+and serializable, such as request payloads, stored metadata, or wire formats.
+Prefer `types/objects.md`'s `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; see `shared/application/http/json-api.md`
+and `shared/application/http/json-web-token.md`.
+
+> **Hint**
+> These declarations only provide compile-time structure. They do not validate
+> that a runtime value is actually JSON-safe; a value typed as `JsonValue` can
+> still contain a `Date` or a class instance if it was cast into the type.

package/docs/types/locales.md

@@ -0,0 +1,77 @@
+### Locales
+
+`Locale` is a literal string union of every locale identifier available in
+Unicode CLDR.
+It is used when a contract needs to accept only valid locale tags instead of
+an open `string`.
+
+#### Declaration
+
+`Locale` lives in `types/locales.d.ts` and is generated from Unicode CLDR
+48.2.1.
+
+```ts title="types/locales.d.ts"
+export type Locale =
+    | 'aa'
+    | 'af'
+    | 'am'
+    | 'ar'
+    | 'ar-EG'
+    | 'de'
+    | 'de-AT'
+    | 'en'
+    | 'en-GB'
+    | 'en-US'
+    | 'es'
+    | 'es-419'
+    | 'fr'
+    | 'ja'
+    | 'zh-Hans'
+    // ...every other CLDR locale identifier
+```
+
+The generated file lists every language identifier and every regional variant
+registered by CLDR, from bare language tags such as `'en'` to script- and
+region-qualified tags such as `'zh-Hant-HK'` or `'ca-ES-valencia'`.
+
+#### Basic Usage
+
+```ts
+import { type Locale } from './types/locales.js'
+
+function formatCount(value: number, locale: Locale): string {
+    return new Intl.NumberFormat(locale).format(value)
+}
+
+formatCount(1200, 'en-US')
+formatCount(1200, 'es-419')
+```
+
+Because `Locale` only accepts identifiers CLDR actually defines, a typo such
+as `'en-USA'` fails at compile time instead of silently reaching
+`Intl.NumberFormat`.
+
+#### Accepting Multiple Locales
+
+`Intl` APIs commonly accept a locale or a list of locales in priority order.
+`Locale[]` expresses that same option without widening to `string[]`.
+
+```ts
+import { type Locale } from './types/locales.js'
+
+const preferredLocales: Locale[] = ['fr-CA', 'fr', 'en']
+```
+
+The runtime resolves the first supported locale from the list; `Locale[]`
+only guarantees that every candidate is a real CLDR identifier.
+
+#### Where It Is Used
+
+`shared/application/loggers.ts` uses `Locale[]` for `Logger.datetimeLocales`,
+the locale list passed to `Date.prototype.toLocaleString()` when formatting a
+log timestamp. See `shared/application/loggers.md`.
+
+> **Hint**
+> `Locale` is a compile-time contract only. It does not validate that the
+> runtime's ICU data actually supports every listed locale; `Intl` APIs fall
+> back to a default when a requested locale is unsupported at runtime.

package/docs/types/objects.md

@@ -0,0 +1,70 @@
+### Objects
+
+The generated root declares `Generic<T>`, 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.
+
+#### Declaration
+
+`Generic<T>` 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`.
+
+#### With A Type Argument
+
+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.
+
+#### Without A 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. It is also the base shape
+> used by `types/json.md` when a value only needs to be JSON-safe.

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.27",
+  "version": "1.0.29",
   "author": "https://github.com/virtualitems/",
   "license": "MIT",
   "description": "Typescript Hexagonal Architecture CLI",
@@ -41,15 +41,14 @@
   "bin": {
     "tshex": "./build/main.js"
   },
+  "scripts": {
+    "build": "deno run --allow-all npm:esbuild --bundle --minify --platform=node --external:commander --format=esm --outfile=./build/main.js ./source/main.ts",
+    "test": "deno test --allow-all tests/"
+  },
   "dependencies": {
-    "commander": "^12.1.0"
+    "commander": "^15.0.0"
   },
   "devDependencies": {
-    "@fission-ai/openspec": "^1.6.0",
-    "@types/node": "^22.5.4",
-    "typescript": "^5.4.5"
-  },
-  "scripts": {
-    "build": "tsc"
+    "@types/node": "^18"
   }
 }

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/source/main.ts

@@ -9,12 +9,12 @@ import { program } from 'commander'
 import fs from 'node:fs'
 import path from 'node:path'
 import readline from 'node:readline/promises'
-import { stdin as input, stdout as output } from 'node:process'
+import { stdin, stdout } from 'node:process'
 
 // FUNCTIONS
 
 function readPackageJson() {
-    const filePath = path.join(import.meta.dirname, '..', 'package.json')
+    const filePath = path.join(import.meta.dirname!, '..', 'package.json')
     const fileContents = fs.readFileSync(filePath, 'utf-8')
     return JSON.parse(fileContents)
 }
@@ -77,19 +77,35 @@ function executeCreateTests(
                 continue
             }
 
-            if (ignoredSourceDir !== undefined && sourcePath.startsWith(ignoredSourceDir)) {
+            if (
+                ignoredSourceDir !== undefined &&
+                sourcePath.startsWith(ignoredSourceDir)
+            ) {
                 continue
             }
 
-            if (fs.existsSync(destinationPath) && fs.statSync(destinationPath).isDirectory() === false) {
+            if (
+                fs.existsSync(destinationPath) &&
+                fs.statSync(destinationPath).isDirectory() === false
+            ) {
                 continue
             }
 
-            executeCreateTests(sourcePath, destinationPath, fileContents, ignoredSourceDir, rootSourceDir)
+            executeCreateTests(
+                sourcePath,
+                destinationPath,
+                fileContents,
+                ignoredSourceDir,
+                rootSourceDir
+            )
             continue
         }
 
-        if (entry.isFile() && entry.name.endsWith('.ts') && fs.existsSync(destinationPath) === false) {
+        if (
+            entry.isFile() &&
+            entry.name.endsWith('.ts') &&
+            fs.existsSync(destinationPath) === false
+        ) {
             fs.writeFileSync(destinationPath, fileContents)
         }
     }
@@ -104,10 +120,12 @@ async function ensureTestsDirectory(testsRootDir: string) {
         return
     }
 
-    const rl = readline.createInterface({ input, output })
+    const rl = readline.createInterface({ input: stdin, output: stdout })
 
     try {
-        const answer = await rl.question(`Tests directory does not exist at ${testsRootDir}. Create it? (y/N) `)
+        const answer = await rl.question(
+            `Tests directory does not exist at ${testsRootDir}. Create it? (y/N) `
+        )
 
         if (answer.trim().toLowerCase() !== 'y') {
             return false
@@ -121,7 +139,7 @@ async function ensureTestsDirectory(testsRootDir: string) {
 }
 
 async function main(program: typeof import('commander').program) {
-    const templatesDir = path.join(import.meta.dirname, '..', 'templates')
+    const templatesDir = path.join(import.meta.dirname!, '..', 'templates')
 
     const options = program.opts()
 
@@ -182,7 +200,9 @@ async function main(program: typeof import('commander').program) {
         const testsDir = path.join(testsRootDir, path.basename(sourceDir))
 
         if (testsDir === sourceDir) {
-            program.error('Tests destination directory cannot be the same as the source directory')
+            program.error(
+                'Tests destination directory cannot be the same as the source directory'
+            )
         }
 
         executeCreateTests(sourceDir, testsDir, testsTemplateContents, testsRootDir)
@@ -198,7 +218,10 @@ program
     .option('-P, --project <name>', "creates a new project with it's shared directory")
     .option('-C, --context <name>', 'creates a new context')
     .option('-R, --react', 'creates a React context with --context')
-    .option('-T, --tests <path>', 'creates a .ts tests structure from an existing directory')
+    .option(
+        '-T, --tests <path>',
+        'creates a .ts tests structure from an existing directory'
+    )
     .option('--dir <path>', 'sets the directory to create the new item')
     .parse(process.argv)
 

package/templates/ctx/example-ports.ts

@@ -1,4 +1,5 @@
 // Ports are exports from the context root level
+// you can delete this file and create your own ports file in the context root level
 
 export function example(): void {
     // ...

package/templates/lib/shared/application/data/capabilities.ts

@@ -0,0 +1,56 @@
+type Generic = Record<string, unknown>
+
+export interface Listable {
+    all(): Generic | Promise<Generic[]>
+}
+
+/**
+ * @description Declares a filtering operation over plain source records.
+ */
+export interface Filterable {
+    filter(selector: unknown): Generic | Promise<Generic[]>
+}
+
+/**
+ * @description Declares a sorting operation over plain source records.
+ */
+export interface Sortable {
+    sort(selector: unknown): Generic | Promise<Generic[]>
+}
+
+/**
+ * @description Declares a creation operation for plain source records.
+ */
+export interface Creatable {
+    create(data: unknown): unknown
+}
+
+/**
+ * @description Declares an update operation that selects source records and applies new plain data.
+ */
+export interface Updatable {
+    update(selector: unknown, data: unknown): unknown
+}
+
+/**
+ * @description Declares a deletion operation over source records selected by plain criteria.
+ */
+export interface Deletable {
+    delete(selector: unknown): unknown
+}
+
+/**
+ * @description Declares an aggregation operation over source records.
+ */
+export interface Aggregatable {
+    aggregate(selector: unknown): unknown
+}
+
+/**
+ * @description Declares operations for selecting or preloading relationships from a data source.
+ */
+export interface Relatable {
+    selectRelated(...args: unknown[]): unknown
+
+    prefetchRelated(...args: unknown[]): unknown
+}

package/templates/lib/shared/application/data/managers.ts

@@ -1,66 +1,9 @@
-/**
- * @description Declares a filtering operation over plain source records.
- */
-export interface Filterable<S = Record<string, unknown>> {
-    filter(selector: S): Promise<Array<S>>
-}
-
-/**
- * @description Declares a sorting operation over plain source records.
- */
-export interface Sortable<S = Record<string, unknown>> {
-    sort(selector: S): Promise<Array<S>>
-}
-
-/**
- * @description Declares a creation operation for plain source records.
- */
-export interface Creatable<D = Record<string, unknown>> {
-    create(data: D): Promise<unknown>
-}
-
-/**
- * @description Declares an update operation that selects source records and applies new plain data.
- */
-export interface Updatable<S = Record<string, unknown>, D = Record<string, unknown>> {
-    update(selector: S, data: D): Promise<unknown>
-}
-
-/**
- * @description Declares a deletion operation over source records selected by plain criteria.
- */
-export interface Deletable<S = Record<string, unknown>> {
-    delete(selector: S): Promise<unknown>
-}
-
-/**
- * @description Declares an aggregation operation over source records.
- */
-export interface Aggregatable<S = Record<string, unknown>> {
-    aggregate(selector: S): Promise<S>
-}
-
-/**
- * @description Declares operations for selecting or preloading relationships from a data source.
- */
-export interface Relatable {
-    selectRelated(...args: unknown[]): unknown
-
-    prefetchRelated(...args: unknown[]): unknown
-}
-
 /**
  * @description Operates on a data source using plain objects and arrays.
  * It exposes the raw data without transforming it.
  */
 export abstract class DataManager<T = Record<string, unknown>> {
     [property: string]: unknown
-
-    public none(): Array<T> {
-        return []
-    }
-
-    public abstract all(): Promise<Array<T>>
 } //:: class
 
 /**

package/templates/lib/shared/application/data/repositories.ts

@@ -1,29 +1,18 @@
 import { type DataManager } from './managers.js'
 import { type DriverAdapter } from './drivers.js'
 
+type Generic = Record<string, unknown>
+
 /**
  * @description Acts as an intermediary between plain source data and domain objects.
  * It transforms records into domain representations and can translate them back when needed.
  */
-export abstract class Repository<
-    DataShape extends Record<string, unknown> = Record<string, unknown>,
-    EntityShape extends Record<string, unknown> = Record<string, unknown>
-> {
+export abstract class Repository<RawDataShape = Generic, EntityShape = Generic> {
     [property: string]: unknown
 
-    public constructor(public readonly driver: DriverAdapter<DataManager<DataShape>>) {}
-
-    public async all(): Promise<Array<EntityShape>> {
-        const connection = await this.driver.connect()
-        const raw = await connection.all()
-        const entities = this.transformList(raw)
-        await this.driver.disconnect()
-        return entities
-    }
-
-    protected transformList(data: Array<DataShape>): Array<EntityShape> {
-        return data.map(this.transform)
-    }
+    public constructor(
+        public readonly driver: DriverAdapter<DataManager<RawDataShape>>
+    ) {}
 
-    protected abstract transform(data: DataShape): EntityShape
+    protected abstract transform(data: RawDataShape): EntityShape
 } //:: class