tshex-cli 1.0.18 → 1.0.20

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "tshex-cli",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "author": "https://github.com/virtualitems/",
+  "license": "MIT",
   "description": "Typescript Hexagonal Architecture CLI",
   "type": "module",
   "main": "./build/main.js",

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

@@ -0,0 +1,15 @@
+import { DataManager } from './managers.js'
+
+/**
+ * @description Declares the connection contract with a data source driver.
+ * It connects to the source, returns an enabled data manager, and disconnects when the work is done.
+ * This declaration belongs to the application layer as a contract,
+ * while its concrete implementation belongs to the adapters layer.
+ */
+export abstract class DriverAdapter<M extends DataManager = DataManager> {
+    [property: string]: unknown
+
+    public abstract connect(...args: unknown[]): Promise<M>
+
+    public abstract disconnect(): Promise<unknown>
+} //:: class

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

@@ -0,0 +1,81 @@
+/**
+ * @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
+
+/**
+ * @description Extends a data manager with set operations over data collections.
+ */
+export abstract class DatasetManager<T = Record<string, unknown>> extends DataManager<T> {
+    [property: string]: unknown
+
+    public abstract union(other: Array<T>): Promise<Array<T>>
+
+    public abstract intersection(other: Array<T>): Promise<Array<T>>
+
+    public abstract difference(other: Array<T>): Promise<Array<T>>
+
+    public abstract symmetricDifference(other: Array<T>): Promise<Array<T>>
+
+    public abstract complement(other: Array<T>): Promise<Array<T>>
+} //:: class

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

@@ -0,0 +1,29 @@
+import { type DataManager } from './managers.js'
+import { type DriverAdapter } from './drivers.js'
+
+/**
+ * @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>
+> {
+    [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)
+    }
+
+    protected abstract transform(data: DataShape): EntityShape
+} //:: class

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

@@ -1,121 +1,35 @@
-// Libraries
-
-// Same Layer
-
-// Lower Layers
-
-// Types
-
-// Constants
-
 /**
- * @description
+ * @description Represents something that occurred in the application.
+ * It carries the event time and its plain details.
  */
 export abstract class Event {
     [property: string]: unknown
 
-    // public ATTRIBUTES
-
-    // protected ATTRIBUTES
-
-    // private ATTRIBUTES
-
-    // public static ATTRIBUTES
-
-    // protected static ATTRIBUTES
-
-    // private static ATTRIBUTES
-
-    // Constructor, Getters, Setters
-
     public constructor(
         public readonly timestamp: number = Date.now(),
         public readonly details: Record<string, unknown> = {}
     ) {}
-
-    // public METHODS
-
-    // protected METHODS
-
-    // private METHODS
-
-    // public static METHODS
-
-    // protected static METHODS
-
-    // private static METHODS
 } //:: class
 
 /**
- * @description
+ * @description Represents a reaction to an application event.
  */
 export abstract class EventHandler {
     [property: string]: unknown
 
-    // public ATTRIBUTES
-
-    // protected ATTRIBUTES
-
-    // private ATTRIBUTES
-
-    // public static ATTRIBUTES
-
-    // protected static ATTRIBUTES
-
-    // private static ATTRIBUTES
-
-    // Constructor, Getters, Setters
-
-    // public METHODS
-
     public abstract handle(event: Event): Promise<void>
-
-    // protected METHODS
-
-    // private METHODS
-
-    // public static METHODS
-
-    // protected static METHODS
-
-    // private static METHODS
 } //:: class
 
 /**
- * @description
+ * @description Declares the interaction contract with an event bus.
+ * It subscribes handlers, removes subscriptions, and dispatches events.
  */
 export abstract class EventDispatcher {
     [property: string]: unknown
 
-    // public ATTRIBUTES
-
-    // protected ATTRIBUTES
-
-    // private ATTRIBUTES
-
-    // public static ATTRIBUTES
-
-    // protected static ATTRIBUTES
-
-    // private static ATTRIBUTES
-
-    // Constructor, Getters, Setters
-
-    // public METHODS
-
     public abstract subscribe(key: unknown, handler: EventHandler): void
 
     public abstract unsubscribe(key: unknown, handler: EventHandler): void
 
     public abstract dispatch(event: Event): void
-
-    // protected METHODS
-
-    // private METHODS
-
-    // public static METHODS
-
-    // protected static METHODS
-
-    // private static METHODS
 } //:: class

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

@@ -12,7 +12,6 @@ export interface HttpResponse {}
  * @description
  */
 export interface HttpResponseBody {
-    [property: string]: unknown
     readonly data: Record<string, unknown> | null
     readonly errors: string[] | null
     readonly links: Record<string, URL> | null

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

@@ -9,7 +9,8 @@ export const ERROR = 40
 export const CRITICAL = 50
 
 /**
- * @description
+ * @description Declares the logging contract used by the application layer.
+ * Adapters implement this abstraction to send logs to external systems.
  */
 export abstract class Logger {
     [property: string]: unknown

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

@@ -1,43 +1,7 @@
-// Libraries
-
-// Same Layer
-
-// Lower Layers
-
-// Types
-
-// Constants
-
 /**
- * @description
- * function arguments are Entity
+ * @description Represents an application use case.
+ * A service coordinates domain capabilities and collaborators to complete a process that fulfills a system purpose.
  */
 export abstract class Service {
     [property: string]: unknown
-
-    // public ATTRIBUTES
-
-    // protected ATTRIBUTES
-
-    // private ATTRIBUTES
-
-    // public static ATTRIBUTES
-
-    // protected static ATTRIBUTES
-
-    // private static ATTRIBUTES
-
-    // Constructor, Getters, Setters
-
-    // public METHODS
-
-    // protected METHODS
-
-    // private METHODS
-
-    // public static METHODS
-
-    // protected static METHODS
-
-    // private static METHODS
 } //:: class

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

@@ -2,9 +2,5 @@
  * @description
  */
 export interface Validatable {
-    [property: string]: unknown
-
     isValid(): boolean
-
-    validate(): unknown
 }

package/templates/lib/shared/domain/aggregates.ts

@@ -1,44 +1,7 @@
-// Libraries
-
-// Same Layer
-
-// Lower Layers
-
-// Types
-
-// Constants
-
 /**
- * @description An Aggregate is a class that contains business logic that doesn't belong to any entity.
- * It is used to perform operations that don't fit into an entity or involve multiple entities.
- * Normally, method arguments are entities.
+ * @description Represents a logical unit that groups multiple entities.
+ * Its operations depend on the identities and collaboration of the entities that compose that unit.
  */
 export abstract class Aggregate {
     [property: string]: unknown
-
-    // public ATTRIBUTES
-
-    // protected ATTRIBUTES
-
-    // private ATTRIBUTES
-
-    // public static ATTRIBUTES
-
-    // protected static ATTRIBUTES
-
-    // private static ATTRIBUTES
-
-    // Constructor, Getters, Setters
-
-    // public METHODS
-
-    // protected METHODS
-
-    // private METHODS
-
-    // public static METHODS
-
-    // protected static METHODS
-
-    // private static METHODS
 } //:: class

package/templates/lib/shared/domain/entities.ts

@@ -1,46 +1,17 @@
-// Libraries
-
-// Same Layer
-
-// Lower Layers
-
-// Types
-
-// Constants
-
 /**
- * @description An Entity is a class that represents a domain concept or element.
+ * @description Represents a domain concept with its own identity.
+ * Two instances describe the same element when they share that identity.
  */
 export abstract class Entity {
     [property: string]: unknown
 
-    // public ATTRIBUTES
-
-    // protected ATTRIBUTES
-
-    // private ATTRIBUTES
-
-    // public static ATTRIBUTES
-
-    // protected static ATTRIBUTES
-
-    // private static ATTRIBUTES
-
-    // Constructor, Getters, Setters
-
-    // public METHODS
-
     public abstract equals(other: Entity): boolean
 
-    public abstract toJSON(): Record<string, unknown>
-
-    // protected METHODS
-
-    // private METHODS
-
-    // public static METHODS
-
-    // protected static METHODS
+    public toJSON(): Record<string, unknown> {
+        return this
+    }
 
-    // private static METHODS
+    public toString(): string {
+        return String(this.constructor.name)
+    }
 } //:: class

package/templates/lib/shared/domain/errors.ts

@@ -1,46 +1,10 @@
-// Libraries
-
-// Same Layer
-
-// Lower Layers
-
-// Types
-
-// Constants
-
 /**
- * @description
+ * @description Represents a received value that does not satisfy the rule expected by a domain concept.
  */
 export class ValueError extends Error {
     [property: string]: unknown
 
-    // public ATTRIBUTES
-
-    // protected ATTRIBUTES
-
-    // private ATTRIBUTES
-
-    // public static ATTRIBUTES
-
-    // protected static ATTRIBUTES
-
-    // private static ATTRIBUTES
-
-    // Constructor, Getters, Setters
-
     public constructor(received: string, expected: string) {
         super(`Invalid value ${received} for ${expected}.`)
     }
-
-    // public METHODS
-
-    // protected METHODS
-
-    // private METHODS
-
-    // public static METHODS
-
-    // protected static METHODS
-
-    // private static METHODS
 } //:: class

package/templates/lib/shared/domain/value-objects.ts

@@ -1,15 +1,5 @@
-// Libraries
-
-// Same Layer
-
 import { ValueError } from './errors.js'
 
-// Lower Layers
-
-// Types
-
-// Constants
-
 /**
  * @see https://emailregex.com/
  */
@@ -17,40 +7,23 @@ const VALID_EMAIL_REGEX =
     /^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/
 
 /**
- * @description
+ * @description Represents a domain concept whose identity is determined by its value.
+ * It centralizes the rules, semantics, and behavior that belong to that value.
  */
 export abstract class ValueObject<T = unknown> {
     [property: string]: unknown
 
-    // public ATTRIBUTES
-
     public abstract readonly value: T
 
-    // protected ATTRIBUTES
-
-    // private ATTRIBUTES
-
-    // public static ATTRIBUTES
-
-    // protected static ATTRIBUTES
-
-    // private static ATTRIBUTES
-
-    // Constructor, Getters, Setters
-
-    // public METHODS
-
     public toString(): string {
         return String(this.value)
     }
 
-    public abstract equals(other: ValueObject<T> | null | undefined): boolean
-
-    // protected METHODS
-
-    // private METHODS
+    public toJSON(): T {
+        return this.value
+    }
 
-    // public static METHODS
+    public abstract equals(other: ValueObject<T> | null | undefined): boolean
 
     public static isValid(value: unknown): boolean {
         return (
@@ -59,41 +32,22 @@ export abstract class ValueObject<T = unknown> {
             Object.is(value, NaN) === false
         )
     }
-
-    // protected static METHODS
-
-    // private static METHODS
 } //:: class
 
 /**
- * @description
+ * @description Models a Boolean state that can be true, false, or null.
+ * It adds explicit behavior for the indeterminate state.
  */
 export class NullableBoolean extends ValueObject<boolean | null> {
     [property: string]: unknown
 
-    // public ATTRIBUTES
-
     public override readonly value: boolean | null
 
-    // protected ATTRIBUTES
-
-    // private ATTRIBUTES
-
-    // public static ATTRIBUTES
-
-    // protected static ATTRIBUTES
-
-    // private static ATTRIBUTES
-
-    // Constructor, Getters, Setters
-
     protected constructor(value: boolean | null) {
         super()
         this.value = value
     }
 
-    // public METHODS
-
     public override equals(other: NullableBoolean | null | undefined): boolean {
         if (other === null || other === undefined) return false
         return this.value === other.value
@@ -103,43 +57,19 @@ export class NullableBoolean extends ValueObject<boolean | null> {
         return this.value === null
     }
 
-    // protected METHODS
-
-    // private METHODS
-
-    // public static METHODS
-
     public static from(value: boolean | null): NullableBoolean {
         return new this(value)
     }
-
-    // protected static METHODS
-
-    // private static METHODS
 } //:: class
 
 /**
- * @description
+ * @description Represents an email address as a value object with validation and email-specific operations.
  */
 export class Email extends ValueObject<string> {
     [property: string]: unknown
 
-    // public ATTRIBUTES
-
     public override readonly value: string
 
-    // protected ATTRIBUTES
-
-    // private ATTRIBUTES
-
-    // public static ATTRIBUTES
-
-    // protected static ATTRIBUTES
-
-    // private static ATTRIBUTES
-
-    // Constructor, Getters, Setters
-
     protected constructor(value: string) {
         super()
         this.value = value
@@ -157,8 +87,6 @@ export class Email extends ValueObject<string> {
         return this.domain?.split('.').pop()
     }
 
-    // public METHODS
-
     public override equals(other: Email | null | undefined): boolean {
         if (other === null || other === undefined) {
             return false
@@ -167,12 +95,6 @@ export class Email extends ValueObject<string> {
         return this.value === other.value
     }
 
-    // protected METHODS
-
-    // private METHODS
-
-    // public static METHODS
-
     public static override isValid(value: unknown): boolean {
         if (super.isValid(value) === false) return false
 
@@ -187,8 +109,4 @@ export class Email extends ValueObject<string> {
 
         return new this(value)
     }
-
-    // protected static METHODS
-
-    // private static METHODS
 } //:: class