URL.ts

export interface UrlOptions {
  /** Allowed protocols. Defaults to ['https:', 'http:'] */
  protocols?: string[];
  /** Require the URL to have a pathname beyond '/' */
  requirePath?: boolean;
}

export class Url {
  readonly value: string;
  readonly protocol: string;
  readonly hostname: string;
  readonly pathname: string;
  readonly search: string;
  readonly hash: string;

  private static readonly DEFAULT_PROTOCOLS = ['https:', 'http:'];

  constructor(value: unknown, options: UrlOptions = {}) {
    if (typeof value !== 'string') {
      throw new TypeError(`Url: expected string, got ${typeof value}`);
    }

    const raw = value.trim();
    let parsed: URL;

    try {
      parsed = new URL(raw);
    } catch {
      throw new TypeError(`Url: invalid URL "${value}"`);
    }

    const allowed = (options.protocols ?? Url.DEFAULT_PROTOCOLS).map(p =>
      p.endsWith(':') ? p : `${p}:`
    );

    if (!allowed.includes(parsed.protocol)) {
      throw new TypeError(
        `Url: protocol "${parsed.protocol}" not allowed. Expected one of: ${allowed.join(', ')}`
      );
    }

    if (options.requirePath && (parsed.pathname === '/' || parsed.pathname === '')) {
      throw new TypeError(`Url: URL must include a path beyond "/"`);
    }

    this.value    = parsed.href;
    this.protocol = parsed.protocol;
    this.hostname = parsed.hostname;
    this.pathname = parsed.pathname;
    this.search   = parsed.search;
    this.hash     = parsed.hash;
  }

  get isHttps(): boolean {
    return this.protocol === 'https:';
  }

  toString(): string {
    return this.value;
  }

  toJSON(): string {
    return this.value;
  }

  equals(other: Url): boolean {
    return this.value === other.value;
  }

  static isValid(value: unknown, options?: UrlOptions): boolean {
    try {
      new Url(value as string, options);
      return true;
    } catch {
      return false;
    }
  }
}