calendar/packages/features/flags/DECORATOR_IMPLEMENTATION_PLAN.md

Memoize/Unmemoize Decorator Implementation Plan

Overview

This plan outlines the implementation of @Memoize and @Unmemoize decorators to replace the current CachedXXRepository + PrismaXXRepository + RedisXXRepository pattern (9 classes per 3 entities) with a more declarative approach.

Current State

The current implementation uses three layers per entity:

• PrismaUserFeatureRepository - Database access
• RedisUserFeatureRepository - Cache operations (get/set/invalidate)
• CachedUserFeatureRepository - Orchestrates cache-aside pattern

This results in 9 repository classes for 3 entities (Feature, TeamFeature, UserFeature), with repetitive cache-aside logic in each CachedXXRepository.

Target State

A single repository class per entity with decorators handling caching:

class UserFeatureRepository {
  @Memoize({ key: (userId, featureId) => `features:user:${userId}:${featureId}`, schema: userFeaturesSchema })
  async findByUserIdAndFeatureId(userId: number, featureId: FeatureId): Promise<UserFeatures | null> {
    return this.prisma.userFeatures.findUnique({ where: { userId_featureId: { userId, featureId } } });
  }

  @Unmemoize({ keys: (userId, featureId) => [`features:user:${userId}:${featureId}`] })
  async upsert(userId: number, featureId: FeatureId, enabled: boolean, assignedBy: string): Promise<UserFeatures> {
    return this.prisma.userFeatures.upsert({ ... });
  }
}

Implementation Steps

Step 1: Enable Decorators in tsconfig (if needed)

The packages/features/tsconfig.json extends @calcom/tsconfig/react-library.json. We need to add experimentalDecorators: true to enable legacy decorators.

Note: Many packages already have experimentalDecorators: true (apps/web, apps/api/v2, packages/trpc, etc.), so this is consistent with the codebase.

Step 2: Create Decorator Infrastructure

Create new files in packages/features/cache/:

1. packages/features/cache/decorators/Memoize.ts

   • Decorator that wraps methods with cache-aside logic
   • Accepts configuration: key, ttl, schema (Zod)
   • Uses IRedisService for cache operations
   • Validates cached data with Zod schema before returning

2. packages/features/cache/decorators/Unmemoize.ts

   • Decorator that invalidates cache keys after method execution
   • Accepts configuration: keys (function returning array of cache keys)
   • Invalidates specified keys after the wrapped method completes

3. packages/features/cache/decorators/index.ts

   • Re-exports both decorators

4. packages/features/cache/decorators/types.ts

   • Shared types for decorator configuration

Step 3: Implement @Memoize Decorator

interface MemoizeConfig<TArgs extends unknown[]> {
  key: (...args: TArgs) => string;
  ttl?: number;
  schema?: ZodSchema;
}

function Memoize<TArgs extends unknown[]>(config: MemoizeConfig<TArgs>) {
  return function <T extends { redis: IRedisService }>(
    target: (this: T, ...args: TArgs) => Promise<unknown>,
    context: ClassMethodDecoratorContext
  ) {
    return async function (this: T, ...args: TArgs) {
      const cacheKey = config.key(...args);
      const cached = await this.redis.get<unknown>(cacheKey);
      
      if (cached !== null) {
        if (config.schema) {
          const parsed = config.schema.safeParse(cached);
          if (parsed.success) return parsed.data;
        } else {
          return cached;
        }
      }
      
      const result = await target.call(this, ...args);
      if (result !== null) {
        await this.redis.set(cacheKey, result, { ttl: config.ttl ?? DEFAULT_TTL });
      }
      return result;
    };
  };
}

Step 4: Implement @Unmemoize Decorator

interface UnmemoizeConfig<TArgs extends unknown[]> {
  keys: (...args: TArgs) => string[];
}

function Unmemoize<TArgs extends unknown[]>(config: UnmemoizeConfig<TArgs>) {
  return function <T extends { redis: IRedisService }>(
    target: (this: T, ...args: TArgs) => Promise<unknown>,
    context: ClassMethodDecoratorContext
  ) {
    return async function (this: T, ...args: TArgs) {
      const result = await target.call(this, ...args);
      const keysToInvalidate = config.keys(...args);
      await Promise.all(keysToInvalidate.map((key) => this.redis.del(key)));
      return result;
    };
  };
}

Step 5: Refactor UserFeatureRepository

Create a new unified UserFeatureRepository that uses decorators:

export class UserFeatureRepository implements IUserFeatureRepository {
  constructor(
    private prisma: PrismaClient,
    private redis: IRedisService
  ) {}

  async findByUserId(userId: number): Promise<UserFeatures[]> {
    return this.prisma.userFeatures.findMany({ where: { userId } });
  }

  @Memoize({
    key: (userId: number, featureId: FeatureId) => `features:user:${userId}:${featureId}`,
    schema: userFeaturesSchema,
  })
  async findByUserIdAndFeatureId(userId: number, featureId: FeatureId): Promise<UserFeatures | null> {
    return this.prisma.userFeatures.findUnique({
      where: { userId_featureId: { userId, featureId } },
    });
  }

  @Memoize({
    key: (userId: number) => `features:user:autoOptIn:${userId}`,
    schema: booleanSchema,
  })
  async findAutoOptInByUserId(userId: number): Promise<boolean> {
    const user = await this.prisma.user.findUnique({
      where: { id: userId },
      select: { autoOptInFeatures: true },
    });
    return user?.autoOptInFeatures ?? false;
  }

  @Unmemoize({
    keys: (userId: number, featureId: FeatureId) => [`features:user:${userId}:${featureId}`],
  })
  async upsert(userId: number, featureId: FeatureId, enabled: boolean, assignedBy: string): Promise<UserFeatures> {
    return this.prisma.userFeatures.upsert({
      where: { userId_featureId: { userId, featureId } },
      create: { userId, featureId, enabled, assignedBy },
      update: { enabled, assignedBy },
    });
  }

  @Unmemoize({
    keys: (userId: number, featureId: FeatureId) => [`features:user:${userId}:${featureId}`],
  })
  async delete(userId: number, featureId: FeatureId): Promise<void> {
    await this.prisma.userFeatures.delete({
      where: { userId_featureId: { userId, featureId } },
    });
  }

  @Unmemoize({
    keys: (userId: number) => [`features:user:autoOptIn:${userId}`],
  })
  async updateAutoOptIn(userId: number, enabled: boolean): Promise<void> {
    await this.prisma.user.update({
      where: { id: userId },
      data: { autoOptInFeatures: enabled },
    });
  }

  // Methods without caching (complex queries)
  async checkIfUserBelongsToTeamWithFeature(userId: number, slug: string): Promise<boolean> {
    // ... existing implementation
  }

  async checkIfUserBelongsToTeamWithFeatureNonHierarchical(userId: number, slug: string): Promise<boolean> {
    // ... existing implementation
  }
}

Step 6: Update DI Configuration

Update the DI module to use the new unified repository:

// packages/features/flags/di/UserFeatureRepository.module.ts
const loadModule = bindModuleToClassOnToken({
  module: thisModule,
  moduleToken,
  token,
  classs: UserFeatureRepository,
  depsMap: {
    prisma: prismaModuleLoader,
    redis: redisModuleLoader,
  },
});

Step 7: Write Tests

Create comprehensive tests for the decorators:

1. packages/features/cache/decorators/__tests__/Memoize.test.ts

   • Test cache hit returns cached value
   • Test cache miss fetches from source and caches
   • Test Zod validation on cached data
   • Test null results are not cached
   • Test TTL is respected

2. packages/features/cache/decorators/__tests__/Unmemoize.test.ts

   • Test cache keys are invalidated after method execution
   • Test multiple keys can be invalidated
   • Test method result is returned correctly

File Structure

packages/features/
  cache/
    decorators/
      __tests__/
        Memoize.test.ts
        Unmemoize.test.ts
      Memoize.ts
      Unmemoize.ts
      types.ts
      index.ts
  flags/
    repositories/
      UserFeatureRepository.ts  (new unified repository)
      # Keep existing files for backward compatibility during migration
    di/
      UserFeatureRepository.module.ts  (new module)
      tokens.ts  (add new token)

Migration Strategy

1. Create the new decorator infrastructure alongside existing code
2. Create the new unified UserFeatureRepository with decorators
3. Add new DI module for the unified repository
4. Update consumers to use the new repository
5. Remove old CachedXXRepository, RedisXXRepository files after migration is complete

Benefits

1. Reduced boilerplate: 1 class instead of 3 per entity
2. Declarative caching: Cache behavior is visible at method level
3. Co-located logic: Caching and invalidation rules are next to the methods they affect
4. Type-safe: Full TypeScript support with proper typing
5. Testable: Decorators can be tested independently
6. Consistent: Same pattern for all repositories

Considerations

1. Decorator limitations: Legacy decorators (experimentalDecorators) are used since TC39 decorators have different semantics
2. Redis dependency: Repository classes must have redis: IRedisService property for decorators to work
3. Zod validation: Optional but recommended for cached data integrity
4. TTL: Default 5 minutes, configurable per method

Timeline

1. Step 1-2: Create decorator infrastructure (~30 min)
2. Step 3-4: Implement decorators (~30 min)
3. Step 5: Refactor UserFeatureRepository (~30 min)
4. Step 6: Update DI configuration (~15 min)
5. Step 7: Write tests (~45 min)
6. Type checks and lint (~15 min)
7. Create PR (~10 min)

Total estimated time: ~3 hours