@rytass/bpm-core-nestjs-module 0.1.2 → 0.1.3

package/src/lib/identity/identity.module.ts

@@ -0,0 +1,96 @@
+import {
+  DynamicModule,
+  InjectionToken,
+  Module,
+  Provider,
+} from '@nestjs/common';
+import { ModuleMetadata } from '@nestjs/common/interfaces';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { IdentityQueries } from './identity.queries';
+import { IdentityService } from './identity.service';
+import { MemberMetadataCacheEntity } from './member-metadata-cache.entity';
+import { BPMMemberResolver } from './member-resolver.interface';
+import {
+  BPM_IDENTITY_OPTIONS,
+  BPMRootIdentityOptions,
+  resolveBPMIdentityOptions,
+} from './identity-options';
+
+export interface IdentityModuleOptions extends BPMRootIdentityOptions {
+  readonly imports?: ModuleMetadata['imports'];
+  readonly memberResolverProvider: Provider<BPMMemberResolver>;
+}
+
+export interface IdentityModuleAsyncOptions extends Pick<
+  ModuleMetadata,
+  'imports'
+> {
+  readonly inject?: readonly InjectionToken[];
+  readonly memberResolverProvider: Provider<BPMMemberResolver>;
+  readonly useFactory: (
+    ...args: readonly unknown[]
+  ) => BPMRootIdentityOptions | Promise<BPMRootIdentityOptions>;
+}
+
+@Module({})
+export class IdentityModule {
+  static forRoot(options: IdentityModuleOptions): DynamicModule {
+    const resolverProviders = createMemberResolverProviders(options);
+
+    return {
+      exports: [IdentityService],
+      imports: [
+        ...(options.imports ?? []),
+        TypeOrmModule.forFeature([MemberMetadataCacheEntity]),
+      ],
+      module: IdentityModule,
+      providers: [
+        IdentityQueries,
+        IdentityService,
+        ...resolverProviders,
+        createIdentityOptionsProvider(options),
+      ],
+    };
+  }
+
+  static forRootAsync(options: IdentityModuleAsyncOptions): DynamicModule {
+    const resolverProviders = createMemberResolverProviders(options);
+
+    return {
+      exports: [IdentityService],
+      imports: [
+        ...(options.imports ?? []),
+        TypeOrmModule.forFeature([MemberMetadataCacheEntity]),
+      ],
+      module: IdentityModule,
+      providers: [
+        IdentityQueries,
+        IdentityService,
+        ...resolverProviders,
+        {
+          inject: [...(options.inject ?? [])],
+          provide: BPM_IDENTITY_OPTIONS,
+          useFactory: async (
+            ...args: readonly unknown[]
+          ): Promise<ReturnType<typeof resolveBPMIdentityOptions>> =>
+            resolveBPMIdentityOptions(await options.useFactory(...args)),
+        },
+      ],
+    };
+  }
+}
+
+function createMemberResolverProviders(
+  options: IdentityModuleOptions,
+): readonly Provider[] {
+  return [options.memberResolverProvider];
+}
+
+function createIdentityOptionsProvider(
+  options: BPMRootIdentityOptions = {},
+): Provider {
+  return {
+    provide: BPM_IDENTITY_OPTIONS,
+    useValue: resolveBPMIdentityOptions(options),
+  };
+}

package/src/lib/identity/identity.queries.ts

@@ -0,0 +1,61 @@
+import { Args, Int, Query, Resolver } from '@nestjs/graphql';
+import { BPMAdminOnly, BPMAuthenticated } from '../bpm-auth';
+import { IdentityService } from './identity.service';
+import { MemberMetadataCacheEntity } from './member-metadata-cache.entity';
+import {
+  MemberProfileObject,
+  toMemberProfileObject,
+} from './member-profile.object';
+
+@Resolver()
+@BPMAuthenticated()
+export class IdentityQueries {
+  constructor(private readonly identityService: IdentityService) {}
+
+  @Query(() => MemberProfileObject)
+  async member(
+    @Args('memberId', { type: () => String }) memberId: string,
+  ): Promise<MemberProfileObject> {
+    const metadata = await this.identityService.resolveMember(memberId);
+
+    return toMemberProfileObject(metadata);
+  }
+
+  @Query(() => [MemberProfileObject])
+  async members(
+    @Args('memberIds', { type: () => [String] }) memberIds: readonly string[],
+  ): Promise<readonly MemberProfileObject[]> {
+    const metadataList = await this.identityService.resolveMembers(memberIds);
+
+    return metadataList.map(toMemberProfileObject);
+  }
+
+  @Query(() => [MemberMetadataCacheEntity])
+  @BPMAdminOnly()
+  async cachedMembers(): Promise<readonly MemberMetadataCacheEntity[]> {
+    return this.identityService.listCachedMembers();
+  }
+
+  @Query(() => [MemberProfileObject])
+  async searchMembers(
+    @Args('searchText', { type: () => String }) searchText: string,
+    @Args('page', { nullable: true, type: () => Int }) page?: number | null,
+    @Args('pageSize', { nullable: true, type: () => Int })
+    pageSize?: number | null,
+  ): Promise<readonly MemberProfileObject[]> {
+    const metadataList = await this.identityService.searchMembers(searchText, {
+      page: page ?? undefined,
+      pageSize: pageSize ?? undefined,
+    });
+
+    return metadataList.map(toMemberProfileObject);
+  }
+
+  @Query(() => Int)
+  async memberCount(
+    @Args('searchText', { nullable: true, type: () => String })
+    searchText?: string | null,
+  ): Promise<number> {
+    return this.identityService.countMembers(searchText ?? '');
+  }
+}

package/src/lib/identity/identity.service.spec.ts

@@ -0,0 +1,105 @@
+import { Repository } from 'typeorm';
+import { MemberMetadata } from '@rytass/bpm-core-shared';
+import { IdentityService } from './identity.service';
+import { MemberMetadataCacheEntity } from './member-metadata-cache.entity';
+import { MemberResolver } from './member-resolver.interface';
+
+describe('IdentityService', () => {
+  it('returns fresh cache entries without calling resolver', async (): Promise<void> => {
+    const cachedMetadata: MemberMetadata = {
+      customFields: {},
+      email: 'cached@example.internal',
+      memberId: 'member-1',
+      name: 'Cached Member',
+    };
+    const cacheRepository = {
+      findOne: jest.fn<Promise<MemberMetadataCacheEntity | null>, []>(() =>
+        Promise.resolve({
+          expiresAt: new Date(Date.now() + 60_000),
+          fetchedAt: new Date(),
+          id: 'cache-1',
+          memberId: 'member-1',
+          metadata: cachedMetadata,
+        }),
+      ),
+      save: jest.fn(),
+    } as unknown as Repository<MemberMetadataCacheEntity>;
+    const resolver: MemberResolver = {
+      resolve: jest.fn(),
+      resolveMany: jest.fn(),
+    };
+    const service = new IdentityService(cacheRepository, resolver);
+
+    await expect(service.resolveMember('member-1')).resolves.toEqual(
+      cachedMetadata,
+    );
+    expect(resolver.resolve).not.toHaveBeenCalled();
+  });
+
+  it('paginates member search results while keeping a full count', async (): Promise<void> => {
+    const members: readonly MemberMetadata[] = [
+      readMemberMetadata('member-1'),
+      readMemberMetadata('member-2'),
+      readMemberMetadata('member-3'),
+    ];
+    const cacheRepository = {
+      find: jest.fn(),
+      findOne: jest.fn(),
+      save: jest.fn(),
+    } as unknown as Repository<MemberMetadataCacheEntity>;
+    const resolver: MemberResolver = {
+      resolve: jest.fn(),
+      resolveMany: jest.fn(),
+      search: jest.fn<Promise<readonly MemberMetadata[]>, [string]>(() =>
+        Promise.resolve(members),
+      ),
+    };
+    const service = new IdentityService(cacheRepository, resolver);
+
+    await expect(
+      service.searchMembers('', { page: 2, pageSize: 2 }),
+    ).resolves.toEqual([members[2]]);
+    await expect(service.countMembers('')).resolves.toBe(3);
+  });
+
+  it('uses configured member metadata cache TTL for refreshed members', async (): Promise<void> => {
+    const cacheRepository = {
+      findOne: jest.fn<Promise<MemberMetadataCacheEntity | null>, []>(() =>
+        Promise.resolve(null),
+      ),
+      save: jest.fn(
+        (
+          entity: MemberMetadataCacheEntity,
+        ): Promise<MemberMetadataCacheEntity> => Promise.resolve(entity),
+      ),
+    } as unknown as Repository<MemberMetadataCacheEntity> & {
+      readonly save: jest.Mock;
+    };
+    const resolver: MemberResolver = {
+      resolve: jest.fn<Promise<MemberMetadata>, [string]>((memberId) =>
+        Promise.resolve(readMemberMetadata(memberId)),
+      ),
+      resolveMany: jest.fn(),
+    };
+    const service = new IdentityService(cacheRepository, resolver, {
+      memberMetadataCacheTtlMs: 1_000,
+    });
+
+    await service.resolveMember('member-1');
+
+    const savedEntity = cacheRepository.save.mock
+      .calls[0]?.[0] as MemberMetadataCacheEntity;
+    expect(
+      savedEntity.expiresAt.getTime() - savedEntity.fetchedAt.getTime(),
+    ).toBe(1_000);
+  });
+});
+
+function readMemberMetadata(memberId: string): MemberMetadata {
+  return {
+    customFields: {},
+    email: `${memberId}@example.internal`,
+    memberId,
+    name: memberId,
+  };
+}

package/src/lib/identity/identity.service.ts

@@ -0,0 +1,200 @@
+import { Inject, Injectable, Optional } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { In, Repository } from 'typeorm';
+import { MemberMetadata } from '@rytass/bpm-core-shared';
+import {
+  BPM_IDENTITY_OPTIONS,
+  BPMResolvedIdentityOptions,
+  DEFAULT_BPM_IDENTITY_OPTIONS,
+} from './identity-options';
+import { MemberMetadataCacheEntity } from './member-metadata-cache.entity';
+import { MEMBER_RESOLVER, MemberResolver } from './member-resolver.interface';
+
+const DEFAULT_MEMBER_PAGE = 1;
+const DEFAULT_MEMBER_PAGE_SIZE = 10;
+const MAX_MEMBER_PAGE_SIZE = 100;
+
+interface SearchMembersOptions {
+  readonly page?: number;
+  readonly pageSize?: number;
+}
+
+const normalizePage = (page?: number): number =>
+  Number.isInteger(page) && page !== undefined && page > 0
+    ? page
+    : DEFAULT_MEMBER_PAGE;
+
+const normalizePageSize = (pageSize?: number): number => {
+  if (!Number.isInteger(pageSize) || pageSize === undefined || pageSize <= 0) {
+    return DEFAULT_MEMBER_PAGE_SIZE;
+  }
+
+  return Math.min(pageSize, MAX_MEMBER_PAGE_SIZE);
+};
+
+const paginateMembers = (
+  members: readonly MemberMetadata[],
+  options: SearchMembersOptions,
+): readonly MemberMetadata[] => {
+  const page = normalizePage(options.page);
+  const pageSize = normalizePageSize(options.pageSize);
+  const offset = (page - 1) * pageSize;
+
+  return members.slice(offset, offset + pageSize);
+};
+
+@Injectable()
+export class IdentityService {
+  constructor(
+    @InjectRepository(MemberMetadataCacheEntity)
+    private readonly cacheRepository: Repository<MemberMetadataCacheEntity>,
+    @Inject(MEMBER_RESOLVER)
+    private readonly memberResolver: MemberResolver,
+    @Optional()
+    @Inject(BPM_IDENTITY_OPTIONS)
+    private readonly identityOptions: BPMResolvedIdentityOptions = DEFAULT_BPM_IDENTITY_OPTIONS,
+  ) {}
+
+  async resolveMember(memberId: string): Promise<MemberMetadata> {
+    const now = new Date();
+    const cached = await this.cacheRepository.findOne({ where: { memberId } });
+
+    if (cached && cached.expiresAt > now) {
+      return cached.metadata;
+    }
+
+    const metadata = await this.memberResolver.resolve(memberId);
+    const fetchedAt = now;
+    const expiresAt = new Date(
+      now.getTime() + this.identityOptions.memberMetadataCacheTtlMs,
+    );
+
+    const cacheEntity = cached ?? new MemberMetadataCacheEntity();
+    cacheEntity.fetchedAt = fetchedAt;
+    cacheEntity.expiresAt = expiresAt;
+    cacheEntity.memberId = memberId;
+    cacheEntity.metadata = metadata;
+
+    await this.cacheRepository.save(cacheEntity);
+
+    return metadata;
+  }
+
+  async resolveMembers(
+    memberIds: readonly string[],
+  ): Promise<readonly MemberMetadata[]> {
+    const uniqueMemberIds = [...new Set(memberIds)].filter(
+      (memberId) => memberId.length > 0,
+    );
+
+    if (uniqueMemberIds.length === 0) {
+      return [];
+    }
+
+    const now = new Date();
+    const cachedRows = await this.cacheRepository.find({
+      where: { memberId: In([...uniqueMemberIds]) },
+    });
+    const cacheEntityByMemberId = new Map(
+      cachedRows.map((row): readonly [string, MemberMetadataCacheEntity] => [
+        row.memberId,
+        row,
+      ]),
+    );
+    const metadataByMemberId = new Map<string, MemberMetadata>();
+    const staleMemberIds: string[] = [];
+
+    for (const memberId of uniqueMemberIds) {
+      const cached = cacheEntityByMemberId.get(memberId);
+
+      if (cached && cached.expiresAt > now) {
+        metadataByMemberId.set(memberId, cached.metadata);
+      } else {
+        staleMemberIds.push(memberId);
+      }
+    }
+
+    if (staleMemberIds.length > 0) {
+      const resolvedMap =
+        await this.memberResolver.resolveMany(staleMemberIds);
+      const expiresAt = new Date(
+        now.getTime() + this.identityOptions.memberMetadataCacheTtlMs,
+      );
+      const entitiesToSave: MemberMetadataCacheEntity[] = [];
+
+      for (const memberId of staleMemberIds) {
+        const metadata = resolvedMap.get(memberId);
+
+        if (!metadata) {
+          continue;
+        }
+
+        const cacheEntity =
+          cacheEntityByMemberId.get(memberId) ??
+          new MemberMetadataCacheEntity();
+
+        cacheEntity.memberId = memberId;
+        cacheEntity.metadata = metadata;
+        cacheEntity.fetchedAt = now;
+        cacheEntity.expiresAt = expiresAt;
+
+        entitiesToSave.push(cacheEntity);
+        metadataByMemberId.set(memberId, metadata);
+      }
+
+      if (entitiesToSave.length > 0) {
+        await this.cacheRepository.save(entitiesToSave);
+      }
+    }
+
+    return memberIds
+      .map((memberId) => metadataByMemberId.get(memberId))
+      .filter((metadata): metadata is MemberMetadata => Boolean(metadata));
+  }
+
+  async listCachedMembers(): Promise<readonly MemberMetadataCacheEntity[]> {
+    return this.cacheRepository.find({ order: { memberId: 'ASC' } });
+  }
+
+  async countMembers(searchText: string): Promise<number> {
+    const members = await this.searchAllMembers(searchText);
+
+    return members.length;
+  }
+
+  async searchMembers(
+    searchText: string,
+    options: SearchMembersOptions = {},
+  ): Promise<readonly MemberMetadata[]> {
+    const members = await this.searchAllMembers(searchText);
+
+    if (options.page === undefined && options.pageSize === undefined) {
+      return members;
+    }
+
+    return paginateMembers(members, options);
+  }
+
+  private async searchAllMembers(
+    searchText: string,
+  ): Promise<readonly MemberMetadata[]> {
+    if (this.memberResolver.search) {
+      return this.memberResolver.search(searchText);
+    }
+
+    const normalizedSearchText = searchText.trim().toLocaleLowerCase();
+    const cachedMembers = await this.listCachedMembers();
+
+    return cachedMembers
+      .map((member) => member.metadata)
+      .filter((metadata) => {
+        if (!normalizedSearchText) {
+          return true;
+        }
+
+        return [metadata.email, metadata.memberId, metadata.name].some(
+          (value) => value.toLocaleLowerCase().includes(normalizedSearchText),
+        );
+      });
+  }
+}

package/src/lib/identity/member-base.adapter.spec.ts

@@ -0,0 +1,77 @@
+import {
+  BPMMemberBaseResolverAdapter,
+  createBPMAuthContextFromMemberBaseMember,
+} from './member-base.adapter';
+
+interface TestMemberBaseMember {
+  readonly email: string;
+  readonly id: string;
+  readonly name: string;
+  readonly permissions: readonly string[];
+  readonly roles: readonly string[];
+}
+
+describe('member-base adapter', () => {
+  it('creates BPM auth context from a host member-base member', (): void => {
+    const context = createBPMAuthContextFromMemberBaseMember(
+      createMember('member-001'),
+      {
+        readCustomFields: (member): Readonly<Record<string, unknown>> => ({
+          source: 'member-base',
+          tenantMemberId: member.id,
+        }),
+        readPermissions: (member): readonly string[] => member.permissions,
+        readRoles: (member): readonly string[] => member.roles,
+      },
+    );
+
+    expect(context).toEqual({
+      memberId: 'member-001',
+      metadata: {
+        source: 'member-base',
+        tenantMemberId: 'member-001',
+      },
+      permissions: ['bpm:approve'],
+      roles: ['approver'],
+    });
+  });
+
+  it('adapts member-base lookup and search to BPM member metadata', async (): Promise<void> => {
+    const members = [createMember('member-001'), createMember('member-002')];
+    const resolver = new BPMMemberBaseResolverAdapter<TestMemberBaseMember>({
+      resolveMember: (memberId): Promise<TestMemberBaseMember | null> =>
+        Promise.resolve(
+          members.find((member) => member.id === memberId) ?? null,
+        ),
+      searchMembers: (searchText): Promise<readonly TestMemberBaseMember[]> =>
+        Promise.resolve(
+          members.filter((member) => member.email.includes(searchText)),
+        ),
+    });
+
+    await expect(resolver.resolve('member-001')).resolves.toEqual({
+      customFields: {},
+      email: 'member-001@example.com',
+      memberId: 'member-001',
+      name: 'Member member-001',
+    });
+    await expect(resolver.search?.('member-002')).resolves.toEqual([
+      {
+        customFields: {},
+        email: 'member-002@example.com',
+        memberId: 'member-002',
+        name: 'Member member-002',
+      },
+    ]);
+  });
+});
+
+function createMember(id: string): TestMemberBaseMember {
+  return {
+    email: `${id}@example.com`,
+    id,
+    name: `Member ${id}`,
+    permissions: ['bpm:approve'],
+    roles: ['approver'],
+  };
+}