<?php

declare(strict_types=1);

namespace KTXF\Cache;

/**
 * Cache Scope
 * 
 * Defines the scope/namespace level for cached entries:
 * - Global: Shared across all tenants and users (e.g., routes, modules)
 * - Tenant: Scoped to a specific tenant (e.g., config, sessions)
 * - User: Scoped to a specific user within a tenant (e.g., rate limits)
 */
enum CacheScope: string
{
    case Global = 'global';
    case Tenant = 'tenant';
    case User = 'user';

    /**
     * Build the cache path prefix for this scope
     * 
     * @param string|null $tenantId Tenant identifier (required for Tenant/User scope)
     * @param string|null $userId User identifier (required for User scope)
     * @return string Path prefix (e.g., "global", "tenant/{tid}", "user/{tid}/{uid}")
     */
    public function buildPrefix(?string $tenantId = null, ?string $userId = null): string
    {
        return match ($this) {
            self::Global => 'global',
            self::Tenant => $tenantId ? "tenant/{$tenantId}" : 'tenant/_unknown',
            self::User => $tenantId && $userId 
                ? "user/{$tenantId}/{$userId}" 
                : "user/_unknown/_unknown",
        };
    }

    /**
     * Validate that required identifiers are provided for this scope
     */
    public function validate(?string $tenantId, ?string $userId): bool
    {
        return match ($this) {
            self::Global => true,
            self::Tenant => $tenantId !== null,
            self::User => $tenantId !== null && $userId !== null,
        };
    }
}