@jumentix/cli-init 0.0.0

package/templates/backend/src/modules/Users/composition/composeUserDeadLetterReplay.ts

@@ -0,0 +1,116 @@
+import {
+  DeadLetterQueue,
+  DeadLetterReplayWorker,
+  KeyValueDeadLetterStore,
+  type DeadLetterReplayHandler,
+  type DeadLetterRecord
+} from '@jumentix/dead-letter-queue';
+import type { IKeyValueStorageClient } from '@src/infra/persistence/KeyValueStorage/IKeyValueStorageClient';
+import type { UserService } from '@src/modules/Users/service/UserService';
+
+/**
+ * JUM-53 — replay the writes the mutex refused, through the same service.
+ *
+ * Replaying through `UserService` rather than the repository is deliberate: the
+ * service re-acquires the mutex, so a record whose lock has not cleared is
+ * refused again and stays queued. A repository-level replay would write past
+ * the lock, which is the corruption the mutex exists to prevent.
+ */
+
+/** The service methods that can refuse a write for a lock, by operation name. */
+type AggregatePayload = {
+  documentId?: string;
+  phoneId?: string;
+  emailId?: string;
+  data?: unknown;
+};
+
+/**
+ * The service reports failure in `response.error` and does not throw.
+ *
+ * That is the false green in this design: a replay of a still-locked record
+ * would return a response, the handler would return normally, and the queue
+ * would mark it `succeeded` — losing the write while reporting that it landed.
+ * Every handler goes through here.
+ */
+async function orThrow(
+  operation: () => Promise<{ error?: unknown }>
+): Promise<void> {
+  const response = await operation();
+  if (response?.error) {
+    const error = response.error as Error;
+    throw error instanceof Error ? error : new Error(String(error));
+  }
+}
+
+export function userReplayHandlers(
+  userService: UserService
+): Record<string, DeadLetterReplayHandler> {
+  const service = userService as unknown as Record<
+    string, (...args: unknown[]) => Promise<{ error?: unknown }>
+  >;
+  const of = (record: DeadLetterRecord) => (record.payload ?? {}) as AggregatePayload;
+
+  /** `payload` is the whole argument: `update`, `updatePassword`, `create*`. */
+  const whole = (method: string): DeadLetterReplayHandler => (
+    (record) => orThrow(() => service[method](record.resourceId, record.payload))
+  );
+
+  /** `payload` names a child and carries its data: `update{Document,Phone,Email}`. */
+  const child = (method: string, key: keyof AggregatePayload): DeadLetterReplayHandler => (
+    (record) => orThrow(() => service[method](record.resourceId, of(record)[key], of(record).data))
+  );
+
+  /** `payload` names a child only: `delete{Document,Phone,Email}`. */
+  const target = (method: string, key: keyof AggregatePayload): DeadLetterReplayHandler => (
+    (record) => orThrow(() => service[method](record.resourceId, of(record)[key]))
+  );
+
+  return {
+    update: whole('update'),
+    delete: (record) => orThrow(() => service.delete(record.resourceId)),
+    updatePassword: whole('updatePassword'),
+    createDocument: whole('createDocument'),
+    updateDocument: child('updateDocument', 'documentId'),
+    deleteDocument: target('deleteDocument', 'documentId'),
+    createPhone: whole('createPhone'),
+    updatePhone: child('updatePhone', 'phoneId'),
+    deletePhone: target('deletePhone', 'phoneId'),
+    createEmail: whole('createEmail'),
+    updateEmail: child('updateEmail', 'emailId'),
+    deleteEmail: target('deleteEmail', 'emailId')
+  };
+}
+
+/**
+ * The queue, backed by the same store the mutex uses.
+ *
+ * Without a key-value client there is no shared store, and a process-local
+ * queue would be lost on restart while looking like durability. Returning
+ * `undefined` keeps the service on its previous behaviour instead.
+ */
+export function composeUserDeadLetterQueue(
+  keyValueStorageClient?: IKeyValueStorageClient
+): DeadLetterQueue | undefined {
+  if (!keyValueStorageClient) return undefined;
+  return new DeadLetterQueue({
+    store: new KeyValueDeadLetterStore(keyValueStorageClient as never)
+  });
+}
+
+export function composeUserDeadLetterWorker(
+  queue: DeadLetterQueue | undefined,
+  userService: UserService,
+  intervalMs?: number
+): DeadLetterReplayWorker | undefined {
+  if (!queue) return undefined;
+  return new DeadLetterReplayWorker({
+    queue,
+    handlers: userReplayHandlers(userService),
+    ...(intervalMs ? { intervalMs } : {}),
+    onError: (error) => {
+      // eslint-disable-next-line no-console
+      console.error('[dead-letter] replay drain failed', error);
+    }
+  });
+}

package/templates/backend/src/modules/Users/composition/composeUsersAuthServices.ts

@@ -0,0 +1,145 @@
+import type { IDatabaseClient } from '@src/infra/persistence/port/IDatabaseClient';
+import type { IPasswordCryptoService } from '@src/infra/security/IPasswordCryptoService';
+import type { IMutexService } from '@src/infra/mutex/port/IMutexService';
+import type { IJwtService } from '@src/infra/jwt/IJwtService';
+import type { IKeyValueStorageClient } from '@src/infra/persistence/KeyValueStorage/IKeyValueStorageClient';
+import type { IEventBus, IMessageMediator } from '@src/modules/port';
+import { InMemorySecurityAuditRepository } from '@src/infra/audit';
+import { CacheService } from '@src/infra/cache';
+
+import { UserDataRepository } from '@src/modules/Users/adapters/out/persistence/UserDataRepository';
+import { OrganizationDataRepository } from '@src/modules/Users/adapters/out/persistence/OrganizationDataRepository';
+import { UserService } from '@src/modules/Users/service/UserService';
+import { OrganizationService } from '@src/modules/Users/service/OrganizationService';
+import { UserProviderLocal } from '@src/modules/Users/service/UserProviderLocal';
+import { AuthService } from '@src/modules/Users/service/AuthService';
+import { UserUseCases } from '@src/modules/Users/application/use-cases/UserUseCases';
+import { OrganizationUseCases } from '@src/modules/Users/application/use-cases/OrganizationUseCases';
+import { AuthUseCases } from '@src/modules/Users/application/use-cases/AuthUseCases';
+import type { IUserUseCases } from '@src/modules/Users/application/ports/IUserUseCases';
+import type { IOrganizationUseCases } from '@src/modules/Users/application/ports/IOrganizationUseCases';
+import type { IAuthUseCases } from '@src/modules/Users/application/ports/IAuthUseCases';
+import type { IUserEventListeners } from '@src/modules/Users/events/contracts/IUserEventListeners';
+import { registerUserEventListeners } from '@src/modules/Users/events/listeners/registerUserEventListeners';
+import { registerUserMessageHandlers } from '@src/modules/Users/events/listeners/registerUserMessageHandlers';
+import type { IUserProvider } from '@src/modules/Users/service/ports/IUserProvider';
+import type { IAuthService } from '@src/modules/Users/service/ports/IAuthService';
+import type { DeadLetterQueue, DeadLetterReplayWorker } from '@jumentix/dead-letter-queue';
+import {
+  composeUserDeadLetterQueue,
+  composeUserDeadLetterWorker
+} from '@src/modules/Users/composition/composeUserDeadLetterReplay';
+
+interface IUsersAuthCompositionConfig {
+  databaseClient: IDatabaseClient;
+  passwordCryptoService: IPasswordCryptoService;
+  mutexService: IMutexService;
+  jwtService: IJwtService;
+  keyValueStorageClient?: IKeyValueStorageClient;
+  eventBus?: IEventBus;
+  messageMediator?: IMessageMediator;
+  userEventListeners?: IUserEventListeners;
+  deadLetterIntervalMs?: number;
+}
+
+interface IUsersAuthComposition {
+  dataRepository: UserDataRepository;
+  organizationDataRepository: OrganizationDataRepository;
+  userService: UserService;
+  organizationService: OrganizationService;
+  userProvider: IUserProvider;
+  authService: IAuthService;
+  userUseCases: IUserUseCases;
+  organizationUseCases: IOrganizationUseCases;
+  authUseCases: IAuthUseCases;
+  deadLetterQueue?: DeadLetterQueue;
+  deadLetterWorker?: DeadLetterReplayWorker;
+}
+
+export const composeUsersAuthServices = (
+  config: IUsersAuthCompositionConfig
+): IUsersAuthComposition => {
+  const {
+    databaseClient,
+    passwordCryptoService,
+    mutexService,
+    jwtService,
+    keyValueStorageClient,
+    eventBus,
+    messageMediator,
+    userEventListeners,
+    deadLetterIntervalMs
+  } = config;
+  const integrationBus = messageMediator ?? eventBus;
+  const cacheService = keyValueStorageClient
+    ? CacheService.compile({ keyValueStorageClient })
+    : undefined;
+
+  const dataRepository = UserDataRepository.compile({
+    databaseClient
+  });
+  const organizationDataRepository = OrganizationDataRepository.compile({
+    databaseClient
+  });
+  // JUM-53. Built before the service because the service takes it, and only
+  // when there is a shared store: a process-local queue would be lost on
+  // restart while looking like durability.
+  const deadLetterQueue = composeUserDeadLetterQueue(keyValueStorageClient);
+  const userService = UserService.compile({
+    dataRepository,
+    organizationDataRepository,
+    services: {
+      passwordCryptoService,
+      mutexService,
+      eventBus: integrationBus,
+      cacheService,
+      deadLetterQueue
+    }
+  });
+  // Returned rather than started here. Composition builds; a background timer
+  // is the runtime's to start and, more importantly, to stop.
+  const deadLetterWorker = composeUserDeadLetterWorker(
+    deadLetterQueue,
+    userService,
+    deadLetterIntervalMs
+  );
+  const organizationService = OrganizationService.compile({
+    dataRepository: organizationDataRepository,
+    services: {
+      cacheService
+    }
+  });
+  const userProvider = UserProviderLocal.compile(userService);
+  const authService = AuthService.compile(
+    userProvider,
+    passwordCryptoService,
+    jwtService,
+    keyValueStorageClient,
+    integrationBus,
+    InMemorySecurityAuditRepository.compile()
+  );
+  const userUseCases = UserUseCases.compile(userService);
+  const organizationUseCases = OrganizationUseCases.compile(organizationService);
+  const authUseCases = AuthUseCases.compile(authService, mutexService);
+
+  if (integrationBus) {
+    registerUserEventListeners(integrationBus, userEventListeners);
+  }
+  if (messageMediator) {
+    registerUserMessageHandlers(messageMediator, authService);
+  }
+
+  return {
+    dataRepository,
+    organizationDataRepository,
+    userService,
+    organizationService,
+    userProvider,
+    authService,
+    userUseCases,
+    organizationUseCases,
+    authUseCases,
+    deadLetterQueue,
+    deadLetterWorker
+  };
+};

package/templates/backend/src/modules/Users/domain/Entity/IOrganization.ts

@@ -0,0 +1,17 @@
+import {
+  AddressValueObject,
+  EmailValueObject,
+  PhoneValueObject
+} from '@src/modules/ddd/valueObjects';
+
+export interface IOrganization {
+  id: string;
+  createdAt: Date;
+  updatedAt: Date;
+  deletedAt?: Date | string | null;
+  name: string;
+  address: AddressValueObject[];
+  phone: PhoneValueObject[];
+  email: EmailValueObject[];
+  users: string[];
+}

package/templates/backend/src/modules/Users/domain/Entity/IUser.ts

@@ -0,0 +1,22 @@
+import {
+  EmailValueObject,
+  DocumentValueObject,
+  PhoneValueObject
+} from '@src/modules/ddd/valueObjects';
+
+export interface IUser {
+  id: string;
+  createdAt: Date;
+  updatedAt: Date;
+  deletedAt?: Date | string | null;
+  firstName: string;
+  lastName: string;
+  avatar: string;
+  username: string;
+  password: string;
+  organization?: string;
+  emails: EmailValueObject[];
+  documents?: DocumentValueObject[];
+  phones?: PhoneValueObject[];
+  roles: string[];
+}

package/templates/backend/src/modules/Users/domain/Model/Organization.ts

@@ -0,0 +1,280 @@
+/* eslint-disable no-underscore-dangle */
+import type { HasMany } from '@src/modules/port';
+import { BaseModel, hasMany } from '@src/modules/port';
+import type { EntityConstructor } from '@src/modules/port/relations';
+import { canNotBeEmpty, throwIfReadOnly } from '@src/shared/validators';
+import {
+  AddressValueObject,
+  EmailValueObject,
+  PhoneValueObject
+} from '@src/modules/ddd/valueObjects';
+import type { IOrganization } from '@src/modules/Users/domain/Entity/IOrganization';
+import type { IUser } from '@src/modules/Users/domain/Entity/IUser';
+import type { RequestCreateOrganization } from '@src/modules/Users/interface/dto/RequestCreateOrganization';
+
+interface OrganizationFactory extends RequestCreateOrganization {
+  id?: string;
+  createdAt?: Date | string;
+  updatedAt?: Date | string;
+  deletedAt?: Date | string | null;
+  readOnly?: boolean;
+}
+
+interface RequestUpdateAddress {
+  id: string;
+  email?: string;
+  type?: string;
+  isPrimary?: boolean;
+}
+
+type OrganizationPhonePayload = NonNullable<RequestCreateOrganization['phone']>[number];
+type OrganizationEmailPayload = NonNullable<RequestCreateOrganization['email']>[number];
+
+export class Organization extends BaseModel<IOrganization> implements IOrganization {
+  public static readonly dataEntitySchema = {
+    name: 'Organization',
+    fields: [
+      {
+        name: 'id',
+        type: 'string',
+        format: 'uuid',
+        required: true,
+        validations: ['pattern:^[0-9a-fA-F-]{36}$']
+      },
+      {
+        name: 'createdAt',
+        type: 'string',
+        format: 'date-time',
+        required: true,
+        validations: []
+      },
+      {
+        name: 'updatedAt',
+        type: 'string',
+        format: 'date-time',
+        required: true,
+        validations: []
+      },
+      {
+        name: 'name',
+        type: 'string',
+        required: true,
+        validations: ['minLength:1']
+      },
+      {
+        name: 'address',
+        type: 'array',
+        required: false,
+        validations: []
+      },
+      {
+        name: 'phone',
+        type: 'array',
+        required: false,
+        validations: []
+      },
+      {
+        name: 'email',
+        type: 'array',
+        required: false,
+        validations: []
+      },
+      {
+        name: 'users',
+        type: 'array',
+        required: false,
+        validations: []
+      },
+      {
+        name: 'deletedAt',
+        type: 'string',
+        format: 'date-time',
+        required: false,
+        validations: []
+      }
+    ]
+  } as const;
+
+  private _name: string = '';
+
+  private _address: AddressValueObject[] = [];
+
+  private _phone: PhoneValueObject[] = [];
+
+  private _email: EmailValueObject[] = [];
+
+  private _users: string[] = [];
+
+  public userEntities: HasMany<EntityConstructor<IUser>> = [];
+
+  private readonly _readOnly: boolean = false;
+
+  private _skipDomainValidation: boolean = true;
+
+  constructor(payload: OrganizationFactory) {
+    super({
+      id: payload.id,
+      createdAt: payload.createdAt,
+      updatedAt: payload.updatedAt,
+      deletedAt: payload.deletedAt
+    });
+    BaseModel.throwIfDataEntitySchemaIsNotOpenApi31Compliant(Organization.dataEntitySchema as any);
+    this.name = payload.name;
+    payload.address?.forEach((entry) => this.createAddress(entry));
+    payload.phone?.forEach((entry) => this.createPhone(entry));
+    payload.email?.forEach((entry) => this.createEmail(entry));
+    this._users = [...(payload.users || [])];
+    this._readOnly = payload.readOnly ?? false;
+    this._excludeOnSerialize = [
+      'createAddress',
+      'updateAddress',
+      'deleteAddress',
+      'createPhone',
+      'updatePhone',
+      'deletePhone',
+      'createEmail',
+      'updateEmail',
+      'deleteEmail'
+    ];
+    this._skipDomainValidation = false;
+    this.validateDomainState();
+  }
+
+  private validateDomainState(): void {
+    if (this._skipDomainValidation) return;
+    BaseModel.throwIfModelPayloadIsNotOpenApi31Compliant(
+      {
+        id: this.id,
+        createdAt: this.createdAt.toISOString(),
+        updatedAt: this.updatedAt.toISOString(),
+        name: this.name,
+        address: this.address.map((entry) => ({ ...entry })),
+        phone: this.phone.map((entry) => ({ ...entry })),
+        email: this.email.map((entry) => ({ ...entry })),
+        users: [...this.users]
+      },
+      Organization.dataEntitySchema as any
+    );
+  }
+
+  public get name(): string {
+    return this._name;
+  }
+
+  public set name(name: string) {
+    throwIfReadOnly('name', this._readOnly);
+    canNotBeEmpty('name', name);
+    this._name = name;
+    this.validateDomainState();
+  }
+
+  public get address(): AddressValueObject[] {
+    return [...this._address];
+  }
+
+  public createAddress(payload: Record<string, any>): boolean {
+    throwIfReadOnly('address', this._readOnly);
+    this._address.push(new AddressValueObject(payload));
+    this.validateDomainState();
+    return true;
+  }
+
+  public updateAddress(payload: RequestUpdateAddress): boolean {
+    throwIfReadOnly('address', this._readOnly);
+    for (let i = 0; i < this._address.length; i += 1) {
+      if (this._address[i].id === payload.id) {
+        this._address[i] = new AddressValueObject({ ...this._address[i], ...payload });
+        this.validateDomainState();
+        return true;
+      }
+    }
+    return false;
+  }
+
+  public deleteAddress(id: string): boolean {
+    throwIfReadOnly('address', this._readOnly);
+    for (let i = 0; i < this._address.length; i += 1) {
+      if (this._address[i].id === id) {
+        this._address.splice(i, 1);
+        this.validateDomainState();
+        return true;
+      }
+    }
+    return false;
+  }
+
+  public get phone(): PhoneValueObject[] {
+    return [...this._phone];
+  }
+
+  public createPhone(payload: OrganizationPhonePayload): boolean {
+    throwIfReadOnly('phone', this._readOnly);
+    this._phone.push(new PhoneValueObject(payload));
+    this.validateDomainState();
+    return true;
+  }
+
+  public updatePhone(payload: Partial<OrganizationPhonePayload> & { id: string }): boolean {
+    throwIfReadOnly('phone', this._readOnly);
+    for (let i = 0; i < this._phone.length; i += 1) {
+      if (this._phone[i].id === payload.id) {
+        this._phone[i] = new PhoneValueObject({ ...this._phone[i], ...payload });
+        this.validateDomainState();
+        return true;
+      }
+    }
+    return false;
+  }
+
+  public deletePhone(id: string): boolean {
+    throwIfReadOnly('phone', this._readOnly);
+    for (let i = 0; i < this._phone.length; i += 1) {
+      if (this._phone[i].id === id) {
+        this._phone.splice(i, 1);
+        this.validateDomainState();
+        return true;
+      }
+    }
+    return false;
+  }
+
+  public get email(): EmailValueObject[] {
+    return [...this._email];
+  }
+
+  public createEmail(payload: OrganizationEmailPayload): boolean {
+    throwIfReadOnly('email', this._readOnly);
+    this._email.push(new EmailValueObject(payload));
+    this.validateDomainState();
+    return true;
+  }
+
+  public updateEmail(payload: Partial<OrganizationEmailPayload> & { id: string }): boolean {
+    throwIfReadOnly('email', this._readOnly);
+    for (let i = 0; i < this._email.length; i += 1) {
+      if (this._email[i].id === payload.id) {
+        this._email[i] = new EmailValueObject({ ...this._email[i], ...payload });
+        this.validateDomainState();
+        return true;
+      }
+    }
+    return false;
+  }
+
+  public deleteEmail(id: string): boolean {
+    throwIfReadOnly('email', this._readOnly);
+    for (let i = 0; i < this._email.length; i += 1) {
+      if (this._email[i].id === id) {
+        this._email.splice(i, 1);
+        this.validateDomainState();
+        return true;
+      }
+    }
+    return false;
+  }
+
+  @hasMany('User')
+  public get users(): string[] {
+    return [...this._users];
+  }
+}