tshex-cli 1.0.27 → 1.0.29

package/build/main.js

@@ -1,159 +1,2 @@
 #!/usr/bin/env node
-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';
-function readPackageJson() {
-    const filePath = path.join(import.meta.dirname, '..', 'package.json');
-    const fileContents = fs.readFileSync(filePath, 'utf-8');
-    return JSON.parse(fileContents);
-}
-function executeCreateProject(templatesDir, projectDir) {
-    try {
-        fs.cpSync(path.join(templatesDir, 'lib'), projectDir, {
-            recursive: true,
-            filter: (src) => src.endsWith('.gitkeep') === false
-        });
-        console.log('Project created successfully');
-    }
-    catch (err) {
-        console.error(err);
-    }
-}
-function executeCreateContext(templatesDir, contextDir) {
-    try {
-        fs.cpSync(path.join(templatesDir, 'ctx'), contextDir, {
-            recursive: true,
-            filter: (src) => src.endsWith('.gitkeep') === false
-        });
-        console.log('Context created successfully');
-    }
-    catch (err) {
-        console.error(err);
-    }
-}
-function executeCreateReactContext(templatesDir, contextDir) {
-    try {
-        fs.cpSync(path.join(templatesDir, 'ctx-react'), contextDir, {
-            recursive: true,
-            filter: (src) => src.endsWith('.gitkeep') === false
-        });
-        console.log('React context created successfully');
-    }
-    catch (err) {
-        console.error(err);
-    }
-}
-function executeCreateTests(sourceDir, destinationDir, fileContents, ignoredSourceDir, rootSourceDir = sourceDir) {
-    const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
-    if (fs.existsSync(destinationDir) === false) {
-        fs.mkdirSync(destinationDir, { recursive: true });
-    }
-    for (const entry of entries) {
-        const sourcePath = path.join(sourceDir, entry.name);
-        const destinationPath = path.join(destinationDir, entry.name);
-        if (entry.isDirectory()) {
-            if (entry.name === 'shared' && sourceDir === rootSourceDir) {
-                continue;
-            }
-            if (ignoredSourceDir !== undefined && sourcePath.startsWith(ignoredSourceDir)) {
-                continue;
-            }
-            if (fs.existsSync(destinationPath) && fs.statSync(destinationPath).isDirectory() === false) {
-                continue;
-            }
-            executeCreateTests(sourcePath, destinationPath, fileContents, ignoredSourceDir, rootSourceDir);
-            continue;
-        }
-        if (entry.isFile() && entry.name.endsWith('.ts') && fs.existsSync(destinationPath) === false) {
-            fs.writeFileSync(destinationPath, fileContents);
-        }
-    }
-}
-async function ensureTestsDirectory(testsRootDir) {
-    if (fs.existsSync(testsRootDir)) {
-        if (fs.statSync(testsRootDir).isDirectory() === false) {
-            throw new Error(`Tests path exists but is not a directory: ${testsRootDir}`);
-        }
-        return;
-    }
-    const rl = readline.createInterface({ input, output });
-    try {
-        const answer = await rl.question(`Tests directory does not exist at ${testsRootDir}. Create it? (y/N) `);
-        if (answer.trim().toLowerCase() !== 'y') {
-            return false;
-        }
-    }
-    finally {
-        rl.close();
-    }
-    fs.mkdirSync(testsRootDir, { recursive: true });
-    return true;
-}
-async function main(program) {
-    const templatesDir = path.join(import.meta.dirname, '..', 'templates');
-    const options = program.opts();
-    let targetDir = path.resolve(options.dir ?? process.cwd());
-    if (Object.keys(options).length === 0) {
-        program.help();
-    }
-    if (fs.existsSync(targetDir) === false) {
-        fs.mkdirSync(targetDir, { recursive: true });
-    }
-    if (options.project !== undefined) {
-        targetDir = path.join(targetDir, options.project);
-        executeCreateProject(templatesDir, targetDir);
-    }
-    if (options.react === true && options.context === undefined) {
-        program.error('Option --react requires --context <name>');
-    }
-    if (options.context !== undefined) {
-        targetDir = path.join(targetDir, options.context);
-        if (options.react === true) {
-            executeCreateReactContext(templatesDir, targetDir);
-        }
-        else {
-            executeCreateContext(templatesDir, targetDir);
-        }
-    }
-    if (options.tests !== undefined) {
-        const sourceDir = path.resolve(options.tests);
-        const testsTemplateFile = path.join(templatesDir, 'tests', 'content.ts');
-        if (fs.existsSync(sourceDir) === false) {
-            program.error(`Tests source directory does not exist: ${sourceDir}`);
-        }
-        if (fs.statSync(sourceDir).isDirectory() === false) {
-            program.error(`Tests source path is not a directory: ${sourceDir}`);
-        }
-        if (fs.existsSync(testsTemplateFile) === false) {
-            program.error(`Tests template file does not exist: ${testsTemplateFile}`);
-        }
-        const testsTemplateContents = fs.readFileSync(testsTemplateFile, 'utf-8');
-        const testsRootDir = path.join(targetDir, 'tests');
-        const testsDirectoryCreated = await ensureTestsDirectory(testsRootDir);
-        if (testsDirectoryCreated === false) {
-            program.error('Tests directory creation cancelled');
-        }
-        const testsDir = path.join(testsRootDir, path.basename(sourceDir));
-        if (testsDir === sourceDir) {
-            program.error('Tests destination directory cannot be the same as the source directory');
-        }
-        executeCreateTests(sourceDir, testsDir, testsTemplateContents, testsRootDir);
-        console.log('Tests structure created successfully');
-    }
-}
-const packageJson = readPackageJson();
-program
-    .name('tshex')
-    .version(packageJson.version)
-    .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('--dir <path>', 'sets the directory to create the new item')
-    .parse(process.argv);
-void main(program).catch((err) => {
-    const message = err instanceof Error ? err.message : String(err);
-    program.error(message);
-});
+import{program as l}from"commander";import r from"node:fs";import n from"node:path";import p from"node:readline/promises";import{stdin as m,stdout as x}from"node:process";function h(){let e=n.join(import.meta.dirname,"..","package.json"),s=r.readFileSync(e,"utf-8");return JSON.parse(s)}function g(e,s){try{r.cpSync(n.join(e,"lib"),s,{recursive:!0,filter:t=>t.endsWith(".gitkeep")===!1}),console.log("Project created successfully")}catch(t){console.error(t)}}function j(e,s){try{r.cpSync(n.join(e,"ctx"),s,{recursive:!0,filter:t=>t.endsWith(".gitkeep")===!1}),console.log("Context created successfully")}catch(t){console.error(t)}}function S(e,s){try{r.cpSync(n.join(e,"ctx-react"),s,{recursive:!0,filter:t=>t.endsWith(".gitkeep")===!1}),console.log("React context created successfully")}catch(t){console.error(t)}}function d(e,s,t,i,c=e){let u=r.readdirSync(e,{withFileTypes:!0});r.existsSync(s)===!1&&r.mkdirSync(s,{recursive:!0});for(let o of u){let a=n.join(e,o.name),f=n.join(s,o.name);if(o.isDirectory()){if(o.name==="shared"&&e===c||i!==void 0&&a.startsWith(i)||r.existsSync(f)&&r.statSync(f).isDirectory()===!1)continue;d(a,f,t,i,c);continue}o.isFile()&&o.name.endsWith(".ts")&&r.existsSync(f)===!1&&r.writeFileSync(f,t)}}async function w(e){if(r.existsSync(e)){if(r.statSync(e).isDirectory()===!1)throw new Error(`Tests path exists but is not a directory: ${e}`);return}let s=p.createInterface({input:m,output:x});try{if((await s.question(`Tests directory does not exist at ${e}. Create it? (y/N) `)).trim().toLowerCase()!=="y")return!1}finally{s.close()}return r.mkdirSync(e,{recursive:!0}),!0}async function T(e){let s=n.join(import.meta.dirname,"..","templates"),t=e.opts(),i=n.resolve(t.dir??process.cwd());if(Object.keys(t).length===0&&e.help(),r.existsSync(i)===!1&&r.mkdirSync(i,{recursive:!0}),t.project!==void 0&&(i=n.join(i,t.project),g(s,i)),t.react===!0&&t.context===void 0&&e.error("Option --react requires --context <name>"),t.context!==void 0&&(i=n.join(i,t.context),t.react===!0?S(s,i):j(s,i)),t.tests!==void 0){let c=n.resolve(t.tests),u=n.join(s,"tests","content.ts");r.existsSync(c)===!1&&e.error(`Tests source directory does not exist: ${c}`),r.statSync(c).isDirectory()===!1&&e.error(`Tests source path is not a directory: ${c}`),r.existsSync(u)===!1&&e.error(`Tests template file does not exist: ${u}`);let o=r.readFileSync(u,"utf-8"),a=n.join(i,"tests");await w(a)===!1&&e.error("Tests directory creation cancelled");let y=n.join(a,n.basename(c));y===c&&e.error("Tests destination directory cannot be the same as the source directory"),d(c,y,o,a),console.log("Tests structure created successfully")}}var v=h();l.name("tshex").version(v.version).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("--dir <path>","sets the directory to create the new item").parse(process.argv);T(l).catch(e=>{let s=e instanceof Error?e.message:String(e);l.error(s)});

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/data.md

@@ -49,7 +49,7 @@ The base class provides `none()` as an explicit empty result and requires
 contracts such as `Filterable`, `Creatable`, and `Updatable`, plus the
 `DatasetManager` extension for set operations.
 
-#### First Implementation
+#### Implementation
 
 In the following example we implement an in-memory manager and its driver.
 
@@ -92,6 +92,18 @@ export class MemoryUsersDriver extends DriverAdapter<MemoryUsersManager> {
 raw records. The application layer can use both without knowing whether the
 source is memory, SQL, or an HTTP-backed adapter.
 
+Put all your complex data operations in `DataManager`. `Repository` should only handle the transformation of raw records into domain representations. For example, if you need to relate users to their posts, implement that in a manager:
+
+```ts
+class ComplexUsersManager extends DataManager<EnrichedUserRecord> {
+    ...
+
+    public async findAllAndRelate(): Promise<Array<EnrichedUserRecord>> {
+        ...
+    }
+}
+```
+
 #### Repository
 
 `Repository` is responsible for transforming raw records into domain-oriented

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.