updated observable types and usage

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicmind/domainjs",
-  "version": "0.0.1-rc-073024-4",
+  "version": "0.0.1-rc-073024-4-a",
   "description": "A domain-driven design framework for scalable systems.",
   "keywords": [],
   "author": {

src/Aggregate.ts

@@ -41,11 +41,11 @@ import {
 } from '@/Entity'
 
 import {
-  Topics,
+  Observable,
   ObservableTopics,
 } from '@/Topic'
 
-export abstract class Aggregate<E extends Entity, T extends Topics = Topics> extends ObservableTopics<T> {
+export abstract class Aggregate<E extends Entity, T extends ObservableTopics = ObservableTopics> extends Observable<T> {
   protected root: E
 
   constructor(root: E) {

src/Event.ts

@@ -42,63 +42,72 @@ import {
 import {
   Observable,
   ObservableTopics,
-} from '@cosmicmind/patternjs'
+} from '@/Topic'
 
 /**
- * Represents an Event.
+ * Represents an event.
  *
- * @example
- * const event: Event = {
- *   name: 'John Doe',
- *   age: 25
- * }
+ * @typedef {Record<string, unknown>} Event
  */
 export type Event = Record<string, unknown>
 
 /**
  * Represents a collection of event topics.
  *
- * @extends {ObservableTopics}
+ * @typedef {Object} EventTopics
+ * @extends ObservableTopics
  *
- * @property {Event} [K] - The event topic.
+ * An EventTopics object is an extension of the ObservableTopics interface,
+ * which defines a collection of event topics. Each topic is accessible as
+ * a property of the EventTopics object, using the topic name as the property
+ * key. The value of each property is an Event object, representing the specific
+ * event topic.
+ *
+ * @property {Event} topicName - The event object representing the specific topic.
+ * @readonly
  */
 export type EventTopics = ObservableTopics & {
   readonly [K: string]: Event
 }
 
 /**
- * An observable class for handling events of specific types.
+ * Represents an observable for events.
  *
- * @template T The event topic type.
+ * @typeparam T - The type of event topics.
  */
 export class EventObservable<T extends EventTopics> extends Observable<T> {}
 
 /**
- * Represents the lifecycle hooks for an event property.
+ * Represents the lifecycle configuration for an event property.
  *
- * @template E - The type of the event.
- * @template V - The type of the property value.
+ * @template E - The type of event this property belongs to.
+ * @template V - The type of value this property takes.
  */
 export type EventPropertyLifecycle<E extends Event, V> = {
   required?: boolean
   validator?(value: V, event: E): boolean | never
 }
 
 /**
- * Represents a map that defines the lifecycle of event properties.
- *
- * @template E - The type of the event.
+ * Represents a map of event properties and their associated lifecycles.
+ * @template E - The type of event.
  */
 export type EventPropertyLifecycleMap<E extends Event> = {
   [K in keyof E]?: EventPropertyLifecycle<E, E[K]>
 }
 
+/**
+ * Custom error class for event-related errors.
+ *
+ * @class EventError
+ * @extends FoundationError
+ */
 export class EventError extends FoundationError {}
 
 /**
- * Represents the lifecycle methods for an event.
+ * Represents the lifecycle of an event.
  *
- * @template E - The type of event.
+ * @template E - The type of the event.
  */
 export type EventLifecycle<E extends Event> = {
   created?(event: E): void
@@ -107,21 +116,21 @@ export type EventLifecycle<E extends Event> = {
 }
 
 /**
- * Defines an event with an optional event lifecycle handler.
+ * Defines an event handler function.
  *
- * @template E The type of the event.
- * @param {EventLifecycle<E>} [handler={}] The optional event lifecycle handler.
- * @returns {(event: E) => E} A function that creates an event with the given lifecycle handler.
+ * @param {EventLifecycle<E>} [handler={}] - The event lifecycle handler object.
+ * @returns {(event: E) => E} - The event handler function.
+ * @template E - The type of event.
  */
 export const defineEvent = <E extends Event>(handler: EventLifecycle<E> = {}): (event: E) => E =>
   (event: E): E => makeEvent(event, handler)
 
 /**
- * Creates a proxy event handler that prevents the modification of event properties.
+ * Creates a proxy handler for event objects that disallows modification of event properties.
  *
- * @template E - The event type.
+ * @template E - The type of the event object.
  * @param {EventLifecycle<E>} handler - The event lifecycle handler.
- * @returns {ProxyHandler<E>} - The proxy event handler.
+ * @returns {ProxyHandler<E>} - The proxy handler for the event object.
  */
 function makeEventHandler<E extends Event>(handler: EventLifecycle<E>): ProxyHandler<E> {
   return {
@@ -132,28 +141,27 @@ function makeEventHandler<E extends Event>(handler: EventLifecycle<E>): ProxyHan
 }
 
 /**
- * Throws an EventError with a specified event and invokes the error handler.
- *
- * @template E - The type of Event.
- * @param {string} message - The error message.
- * @param {EventLifecycle<E>} handler - The event lifecycle handler.
- * @throws {EventError} - The EventError instance.
- * @return {never} - This method never returns.
+ * Throws an EventError and invokes the error handler.
+ * @template E - The type of event.
+ * @param {string} event - The event name.
+ * @param {EventLifecycle<E>} handler - The event handler.
+ * @throws {EventError} - The error that is thrown.
+ * @returns {never} - This method never returns as it always throws an error.
  */
-function throwError<E extends Event>(message: string, handler: EventLifecycle<E>): never {
-  const error = new EventError(message)
+function throwError<E extends Event>(event: string, handler: EventLifecycle<E>): never {
+  const error = new EventError(event)
   handler.error?.(error)
   throw error
 }
 
 /**
- * Creates an event of type `E`.
+ * Creates a new event object and applies lifecycle handlers and validators to its properties.
  *
- * @template E - The type of the event to create.
- * @param {E} target - The target object to create the event from.
- * @param {EventLifecycle<E>} [handler={}] - The lifecycle handler for the event.
- * @returns {E} - The created event object.
- * @throws {EventError} - If the target object is invalid.
+ * @template E - The type of the event object.
+ * @param {E} target - The target event object.
+ * @param {EventLifecycle<E>} [handler={}] - An optional object containing lifecycle handlers and validators.
+ * @throws {EventError} - Throws an error if the target event object is invalid.
+ * @returns {E | never} - The created event object with applied lifecycle handlers and validators.
  */
 function makeEvent<E extends Event>(target: E, handler: EventLifecycle<E> = {}): E | never {
   if (guard<E>(target)) {

src/Message.ts

@@ -42,39 +42,33 @@ import {
 import {
   Observable,
   ObservableTopics,
-} from '@cosmicmind/patternjs'
+} from '@/Topic'
 
 /**
- * Represents an Message.
- *
- * @example
- * const message: Message = {
- *   name: 'John Doe',
- *   age: 25
- * }
+ * Represents a generic message.
  */
 export type Message = Record<string, unknown>
 
 /**
  * Represents a collection of message topics.
  *
- * @extends {ObservableTopics}
- *
- * @property {Message} [K] - The message topic.
+ * @typedef {Object} MessageTopics
+ * @extends ObservableTopics
+ * @property {Message} [K] - The topic name mapped to its corresponding message.
  */
 export type MessageTopics = ObservableTopics & {
   readonly [K: string]: Message
 }
 
 /**
- * An observable class for handling messages of specific types.
+ * Represents an Observable that emits messages of a specific topic.
  *
- * @template T The message topic type.
+ * @template T - The type of the message topic.
  */
 export class MessageObservable<T extends MessageTopics> extends Observable<T> {}
 
 /**
- * Represents the lifecycle hooks for an message property.
+ * Type definition for the lifecycle of a message property.
  *
  * @template E - The type of the message.
  * @template V - The type of the property value.
@@ -85,20 +79,24 @@ export type MessagePropertyLifecycle<E extends Message, V> = {
 }
 
 /**
- * Represents a map that defines the lifecycle of message properties.
+ * Represents a map of property lifecycles for a message class.
  *
- * @template E - The type of the message.
+ * @template E - The message class type.
  */
 export type MessagePropertyLifecycleMap<E extends Message> = {
   [K in keyof E]?: MessagePropertyLifecycle<E, E[K]>
 }
 
+/**
+ * Error class for message-related errors.
+ *
+ * @extends {FoundationError}
+ */
 export class MessageError extends FoundationError {}
 
 /**
- * Represents the lifecycle methods for an message.
- *
- * @template E - The type of message.
+ * Represents the lifecycle events for a message.
+ * @template E The type of the message.
  */
 export type MessageLifecycle<E extends Message> = {
   created?(message: E): void
@@ -107,21 +105,20 @@ export type MessageLifecycle<E extends Message> = {
 }
 
 /**
- * Defines an message with an optional message lifecycle handler.
- *
- * @template E The type of the message.
- * @param {MessageLifecycle<E>} [handler={}] The optional message lifecycle handler.
- * @returns {(message: E) => E} A function that creates an message with the given lifecycle handler.
+ * Define message function.
+ * @template E - Type of the message.
+ * @param {MessageLifecycle<E>} [handler={}] - Message lifecycle handler.
+ * @returns {(message: E) => E} - A function that creates and processes the message.
  */
 export const defineMessage = <E extends Message>(handler: MessageLifecycle<E> = {}): (message: E) => E =>
   (message: E): E => makeMessage(message, handler)
 
 /**
- * Creates a proxy message handler that prmessages the modification of message properties.
+ * Creates a proxy handler to be used as a message handler.
  *
- * @template E - The message type.
+ * @template E - The type of the message object.
  * @param {MessageLifecycle<E>} handler - The message lifecycle handler.
- * @returns {ProxyHandler<E>} - The proxy message handler.
+ * @returns {ProxyHandler<E>} - The proxy handler for the message.
  */
 function makeMessageHandler<E extends Message>(handler: MessageLifecycle<E>): ProxyHandler<E> {
   return {
@@ -132,13 +129,13 @@ function makeMessageHandler<E extends Message>(handler: MessageLifecycle<E>): Pr
 }
 
 /**
- * Throws an MessageError with a specified message and invokes the error handler.
+ * Throws an error with the provided message and calls the error handler.
+ * This method does not return normally.
  *
- * @template E - The type of Message.
+ * @template E - The type of the message.
  * @param {string} message - The error message.
- * @param {MessageLifecycle<E>} handler - The message lifecycle handler.
- * @throws {MessageError} - The MessageError instance.
- * @return {never} - This method never returns.
+ * @param {MessageLifecycle<E>} handler - The error handler to call.
+ * @throws {MessageError} - The thrown error.
  */
 function throwError<E extends Message>(message: string, handler: MessageLifecycle<E>): never {
   const error = new MessageError(message)
@@ -147,13 +144,13 @@ function throwError<E extends Message>(message: string, handler: MessageLifecycl
 }
 
 /**
- * Creates an message of type `E`.
+ * Creates a message object and applies lifecycle methods and validations.
  *
- * @template E - The type of the message to create.
- * @param {E} target - The target object to create the message from.
- * @param {MessageLifecycle<E>} [handler={}] - The lifecycle handler for the message.
- * @returns {E} - The created message object.
- * @throws {MessageError} - If the target object is invalid.
+ * @template E - Type of the message object.
+ * @param {E} target - The message object to be created.
+ * @param {MessageLifecycle<E>} handler - The lifecycle methods and validators for the message object. (Optional)
+ * @returns {E | never} - The created message object.
+ * @throws {MessageError} - If the target is invalid.
  */
 function makeMessage<E extends Message>(target: E, handler: MessageLifecycle<E> = {}): E | never {
   if (guard<E>(target)) {

src/Topic.ts

@@ -39,6 +39,6 @@ import {
   ObservableTopics as OT,
 } from '@cosmicmind/patternjs'
 
-export type Topics = OT
+export type ObservableTopics = OT
 
-export class ObservableTopics<T extends Topics> extends O<T> {}
+export class Observable<T extends ObservableTopics> extends O<T> {}