tshex-cli 1.0.20 → 1.0.21

package/README.md

@@ -146,23 +146,23 @@ From this point on, the guide is split into dedicated documents under `docs/`.
 
 ### General
 
-- [Library structure](./docs/library-structure.md)
-- [Library types](./docs/library-types.md)
-- [Context ports](./docs/context-ports.md)
-- [Generated file reference](./docs/generated-file-reference.md)
+- [Library structure](https://github.com/virtualitems/tshex-cli/blob/main/docs/library-structure.md)
+- [Library 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)
 
 ### Shared application
 
-- [shared/application/data](./docs/shared/application/data.md)
-- [shared/application/events.ts](./docs/shared/application/events.md)
-- [shared/application/http.ts](./docs/shared/application/http.md)
-- [shared/application/loggers.ts](./docs/shared/application/loggers.md)
-- [shared/application/services.ts](./docs/shared/application/services.md)
-- [shared/application/validations.ts](./docs/shared/application/validations.md)
+- [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/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)
 
 ### Shared domain
 
-- [shared/domain/aggregates.ts](./docs/shared/domain/aggregates.md)
-- [shared/domain/entities.ts](./docs/shared/domain/entities.md)
-- [shared/domain/errors.ts](./docs/shared/domain/errors.md)
-- [shared/domain/value-objects.ts](./docs/shared/domain/value-objects.md)
+- [shared/domain/aggregates.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/domain/aggregates.md)
+- [shared/domain/entities.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/domain/entities.md)
+- [shared/domain/errors.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/domain/errors.md)
+- [shared/domain/value-objects.ts](https://github.com/virtualitems/tshex-cli/blob/main/docs/shared/domain/value-objects.md)

package/docs/context-ports.md

@@ -0,0 +1,165 @@
+### Context Ports
+
+Context ports define the communication available at a context boundary.
+They describe what data enters the context, what data leaves it, and which
+operation another system can invoke.
+
+Ports are used to keep communication contracts explicit. An adapter imports a
+port, implements that contract, and translates the external interaction into an
+application process.
+
+> **Hint**
+> The generated `example-ports.ts` file is only a placeholder. Replace it when
+> the first real interaction of the context becomes clear.
+
+#### Root Port File
+
+The generated context starts with a single root file for ports.
+
+```ts title="users/example-ports.ts"
+export function example(): void {
+    // ...
+}
+```
+
+This placeholder does not define a real contract yet. Its purpose is to mark
+the context root as the place where boundary-facing types and interfaces live.
+
+#### First Contract
+
+In the following example we replace the placeholder with a minimal contract for
+creating a user.
+
+```ts title="users/example-ports.ts"
+export type CreateUserRequest = {
+    user: {
+        id: string
+        email: string
+        active: boolean | null
+    }
+}
+
+export type CreateUserResponse = {
+    user: {
+        id: string
+        email: string
+        active: boolean | null
+    }
+}
+
+export interface CreateUserPort {
+    create(request: CreateUserRequest): Promise<CreateUserResponse>
+}
+```
+
+`CreateUserRequest` defines the incoming payload. `CreateUserResponse` defines
+the outgoing payload. `CreateUserPort` exposes the operation available at the
+boundary.
+
+This contract says nothing about HTTP, queues, or databases. It only declares
+the shape of the communication.
+
+#### Adapter Implementation
+
+Now that the port exists, an adapter can implement it and delegate the work to
+an application service.
+
+```ts title="users/adapters/create-user.ts"
+import type {
+    CreateUserPort,
+    CreateUserRequest,
+    CreateUserResponse,
+} from '../example-ports.js'
+
+type CreateUserService = {
+    execute(data: {
+        id: string
+        email: string
+        active: boolean | null
+    }): Promise<CreateUserResponse>
+}
+
+export class CreateUserAdapter implements CreateUserPort {
+    public constructor(
+        private readonly service: CreateUserService,
+    ) {}
+
+    public async create(
+        request: CreateUserRequest,
+    ): Promise<CreateUserResponse> {
+        return this.service.execute({
+            id: request.user.id,
+            email: request.user.email,
+            active: request.user.active,
+        })
+    }
+}
+```
+
+The adapter implements `CreateUserPort`, so it must provide `create()`. Inside
+that method it translates the root-level request into the input expected by the
+application service.
+
+This is the normal flow of the generated structure:
+
+```text
+external system -> adapter -> application -> domain
+```
+
+The port belongs to the boundary. The adapter materializes the boundary. The
+application process executes the use case.
+
+#### Multiple Port Files
+
+As the context grows, you can keep several contracts at the context root.
+
+```ts title="users/list-users.ts"
+export type ListUsersRequest = {
+    active: boolean | null
+}
+
+export type ListUsersResponse = {
+    users: Array<{
+        id: string
+        email: string
+        active: boolean | null
+    }>
+}
+
+export interface ListUsersPort {
+    list(request: ListUsersRequest): Promise<ListUsersResponse>
+}
+```
+
+An adapter can then import the contract from the file that owns it.
+
+This arrangement is useful when one context exposes several independent forms
+of communication. A single file works well for a small context. Separate files
+become easier to maintain when responsibilities start to diverge.
+
+> **Warning**
+> A port should define communication, not domain behavior. Avoid moving entity
+> rules, repository logic, or infrastructure details into the port file.
+
+#### Example Layout
+
+The following structure keeps ports at the root while the implementation lives
+in the generated folders.
+
+```text
+users/
+├── example-ports.ts
+├── list-users.ts
+├── adapters/
+├── application/
+└── domain/
+```
+
+This layout keeps the context boundary visible from the top level. It also
+reduces coupling between adapters because they all import the same contracts.
+
+#### Next Step
+
+After defining a port, implement the corresponding adapter and connect it to an
+application service. The surrounding structure is described in
+`library-structure.md`.

package/docs/generated-file-reference.md

@@ -0,0 +1,88 @@
+### Generated File Reference
+
+This reference describes the files generated by the library template.
+Use it to identify where a concern belongs before adding new code.
+
+#### Root Files
+
+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.
+
+#### Shared Domain Files
+
+The `shared/domain` directory contains foundations for domain modeling.
+
+| File | Responsibility |
+| --- | --- |
+| `shared/domain/value-objects.ts` | Declares `ValueObject<T>` and provides `Email` and `NullableBoolean`. |
+| `shared/domain/entities.ts` | Declares the `Entity` base class. |
+| `shared/domain/aggregates.ts` | Declares the `Aggregate` base class. |
+| `shared/domain/errors.ts` | Declares `ValueError`. |
+
+These files contain reusable domain concepts whose meaning can be shared across
+contexts. They are discussed in more detail in `shared/domain/*.md`.
+
+#### Shared Application Files
+
+The `shared/application` directory contains contracts used to coordinate use
+cases and integrations.
+
+| File | Responsibility |
+| --- | --- |
+| `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 Data Files
+
+The generated template also includes a small set of data-access abstractions.
+
+| File | Responsibility |
+| --- | --- |
+| `shared/application/data/drivers.ts` | Declares `DriverAdapter`, the connection contract with a data source. |
+| `shared/application/data/managers.ts` | Declares `DataManager`, `DatasetManager`, and plain-record operations. |
+| `shared/application/data/repositories.ts` | Declares `Repository`, which transforms raw records into domain representations. |
+
+These contracts belong to the application layer because they define how the
+application coordinates data access without forcing a specific driver.
+
+#### Context Files
+
+Each generated context starts with a root port file and three directories.
+
+| Path | Responsibility |
+| --- | --- |
+| `users/example-ports.ts` | Placeholder root file for context ports. |
+| `users/domain/` | Domain capabilities and rules for the context. |
+| `users/application/` | Processes that use domain capabilities to fulfill system purposes. |
+| `users/adapters/` | Integrations that implement ports and connect the context to external systems. |
+
+The `users/` path is an example context name. Your project can generate one or
+more contexts with the same internal layout.
+
+#### How To Use This Reference
+
+Use the following sequence when deciding where new code belongs.
+
+1. Put reusable domain concepts in `shared/domain`.
+2. Put reusable application contracts in `shared/application`.
+3. Put context-specific rules in `<context>/domain`.
+4. Put use cases in `<context>/application`.
+5. Put boundary implementations in `<context>/adapters`.
+6. Put boundary contracts at the context root.
+
+This reference explains placement. The architectural rationale is described in
+`library-structure.md`.

package/docs/library-structure.md

@@ -0,0 +1,163 @@
+### Library Structure
+
+The library structure organizes generated code into root files, shared
+capabilities, and one or more contexts.
+Each level has a distinct responsibility so that domain rules, use cases, and
+integrations do not collapse into the same place.
+
+This structure is used to keep the implementation centered on capabilities.
+Shared code holds common abstractions. Contexts hold application-specific
+language, rules, and operations.
+
+#### Root
+
+The root contains the entry points of the generated library.
+
+```text
+index.d.ts
+main.ts
+shared/
+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.
+
+#### Shared
+
+The `shared` directory contains concepts that can be reused by multiple
+contexts.
+
+```text
+shared/
+├── application/
+└── domain/
+```
+
+`shared/domain` contains modeling foundations such as value objects, entities,
+aggregates, and errors. `shared/application` contains contracts for services,
+validations, events, logging, HTTP boundaries, and data access.
+
+Move code to `shared` only when its meaning belongs to more than one context.
+Until then, keep it close to the context that owns the rule.
+
+#### Contexts
+
+A context groups the vocabulary, rules, and operations of one application
+capability.
+
+```text
+users/
+billing/
+inventory/
+sales/
+```
+
+Each context can evolve independently while still reusing the abstractions from
+`shared`. This separation reduces accidental coupling between unrelated parts of
+the system.
+
+#### Context Layout
+
+Every generated context starts with the same internal structure.
+
+```text
+users/
+├── example-ports.ts
+├── adapters/
+├── application/
+└── domain/
+```
+
+`example-ports.ts` is the root communication surface of the context.
+`domain/` contains capabilities and rules. `application/` contains processes.
+`adapters/` contains boundary implementations.
+
+#### Domain
+
+The domain layer contains the context's capabilities.
+
+This layer models concepts that carry business meaning: value objects, entities,
+aggregates, and the rules that make them valid. The domain should not depend on
+transport concerns or infrastructure details.
+
+Typical domain responsibilities include validating an email address, identifying
+an entity, changing the state of an order, or grouping related entities into a
+single unit.
+
+#### Application
+
+The application layer contains processes that use domain capabilities to
+fulfill a system purpose.
+
+A service in this layer coordinates collaborators. It can validate input,
+construct domain objects, read or write data through abstractions, publish an
+event, and log the result.
+
+The application layer is responsible for orchestration, not for owning the
+business rules themselves.
+
+#### Adapters
+
+The adapters layer contains the integrations that connect a context to other
+systems.
+
+An adapter can expose an HTTP handler, consume a message, call a remote API,
+implement a data driver, or connect to an event bus. Its role is to translate
+external input or output into the contracts expected by the application layer.
+
+#### Ports
+
+Ports define the communication available at the context boundary.
+
+They live at the context root because they describe how the context is used
+from the outside. An adapter imports a port, implements it, and delegates the
+work to an application process.
+
+The generated template starts with `example-ports.ts`, but a larger context may
+split ports across several files. The detailed guidance for that layout lives in
+`context-ports.md`.
+
+#### Dependency Direction
+
+The normal dependency direction is the following:
+
+```text
+adapter -> port
+adapter -> application
+application -> domain
+```
+
+This direction keeps the core model isolated from transport and infrastructure
+details. The deeper a layer is, the less it should know about the outside.
+
+> **Warning**
+> Avoid importing adapter-specific concerns into the domain layer. Once a domain
+> object depends on HTTP, database, or framework details, the context boundary
+> becomes harder to change.
+
+#### Example Flow
+
+The following diagram shows the runtime flow of a typical operation.
+
+```text
+External system
+      |
+      v
+Port + adapter
+      |
+      v
+Application service
+      |
+      v
+Domain capability
+```
+
+The adapter receives the input, the application service coordinates the use
+case, and the domain provides the rules and behavior required by that use case.
+
+#### Next Step
+
+Use this structure as the default layout for new code. When you need to inspect
+the purpose of a generated file, consult `generated-file-reference.md`.

package/docs/library-types.md

@@ -0,0 +1,70 @@
+### 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 `index.d.ts`.
+
+```ts title="index.d.ts"
+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
+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
+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.
+
+#### Next Step
+
+For the rest of the generated shared abstractions, continue with the pages in
+`shared/application` and `shared/domain`.