/**
 * Namespace capability for plugin identification.
 *
 * Each plugin must claim a unique namespace to identify itself.
 * Namespaces are used for config scoping and event namespacing.
 *
 * @example
 * ```typescript
 * const namespace = new Namespace();
 * namespace.ns('analytics.tracking');
 * console.log(namespace.name); // 'analytics.tracking'
 * ```
 */

export class Namespace {
  /**
   * The plugin's namespace.
   * Set via the `ns()` method, can only be set once.
   */
  name: string = '';

  /**
   * Set the plugin's namespace.
   *
   * Can only be called once per instance. Attempting to set it again throws an error.
   *
   * @param namespace - Dot-notation namespace (e.g., 'analytics.tracking')
   * @throws Error if namespace is already set
   *
   * @example
   * ```typescript
   * const ns = new Namespace();
   * ns.ns('my.plugin'); // Success
   * ns.ns('other.plugin'); // Throws Error
   * ```
   */
  ns(namespace: string): void {
    if (this.name) {
      throw new Error(
        `Namespace already set to "${this.name}". Cannot reassign to "${namespace}".`
      );
    }
    this.name = namespace;
  }
}