<?php

declare(strict_types=1);

/**
 * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
 * SPDX-License-Identifier: AGPL-3.0-or-later
 */

namespace KTXF\Resource\Identifier;

/**
 * A typed collection of resource identifiers with search and filter capabilities
 */
interface ResourceIdentifiersInterface extends \Countable, \IteratorAggregate {

	/** Add an identifier to the collection */
	public function add(ResourceIdentifierInterface $identifier): void;

	/** Get all identifiers */
	public function all(): array;

	/** Filter identifiers by depth level (1–4) */
	public function byDepth(int $depth): static;

	/** Filter identifiers by provider */
	public function byProvider(string $provider): static;

	/** Filter identifiers by service (requires depth >= 2) */
	public function byService(string $service): static;

	/** Filter identifiers by collection (requires depth >= 3) */
	public function byCollection(string $collection): static;

	/** Filter identifiers by entity (requires depth == 4) */
	public function byEntity(string $entity): static;

	/** Get unique provider names */
	public function providers(): array;

	/** Get unique service names */
	public function services(): array;

	/** Get unique collection names */
	public function collections(): array;

	/** Get unique entity names */
	public function entities(): array;

}