refactor

core/shared/application/AsyncUseCase.ts

@@ -1,3 +1,30 @@
+/**
+ * Async Use Case interface for queries.
+ *
+ * Queries do not change system state and return data directly.
+ * The output is most often a Result<T, E> where T is the data and E is a domain error code,
+ * to handle business rejections explicitly. Use cases do not throw errors; they use error codes in Result.
+ *
+ * Example:
+ * ```typescript
+ * export type YourUseCaseError =
+ *   | 'SPONSOR_NOT_FOUND'
+ *   | 'PRICING_NOT_CONFIGURED'
+ *   | 'APPLICATIONS_CLOSED'
+ *   | 'NO_SLOTS_AVAILABLE'
+ *   | 'DUPLICATE_PENDING_REQUEST'
+ *   | 'OFFER_BELOW_MINIMUM';
+ *
+ * export class ApplyForSponsorshipUseCase implements AsyncUseCase<Input, Result<SuccessDTO, YourUseCaseError>> {
+ *   async execute(input: Input): Promise<Result<SuccessDTO, YourUseCaseError>> {
+ *     // implementation
+ *   }
+ * }
+ * ```
+ *
+ * @template Input - The input type for the use case
+ * @template Output - The output type returned by the use case, often Result<T, DomainErrorCode>
+ */
 export interface AsyncUseCase<Input, Output> {
   execute(input: Input): Promise<Output>;
 }