URL Utilities

/**
 * Parse a URL string using specified parser
 * @param str - The URL string to parse
 * @param parser - Parser type: 'simple' or 'full' (default: 'full')
 * @returns Parsed URL object
 */
function parse(str, parser);

const jsonld = require('jsonld');

// Full URL parsing (default)
const fullParsed = jsonld.url.parse('https://user:pass@example.org:8080/path/to/resource?query=value#fragment');
// Result: {
//   href: 'https://user:pass@example.org:8080/path/to/resource?query=value#fragment',
//   protocol: 'https:',
//   scheme: 'https',
//   authority: 'user:pass@example.org:8080',
//   auth: 'user:pass',
//   user: 'user',
//   password: 'pass',
//   hostname: 'example.org',
//   port: '8080',
//   path: '/path/to/resource',
//   directory: '/path/to/',
//   file: 'resource',
//   query: 'query=value',
//   fragment: 'fragment'
// }

// Simple URL parsing
const simpleParsed = jsonld.url.parse('https://example.org/path?query#fragment', 'simple');
// Result: {
//   href: 'https://example.org/path?query#fragment',
//   scheme: 'https',
//   authority: 'example.org',
//   path: '/path',
//   query: 'query',
//   fragment: 'fragment'
// }

// Parse relative URLs
const relativeParsed = jsonld.url.parse('/path/to/resource');
// Result: { path: '/path/to/resource', ... }

/**
 * Available URL parsers with their configurations
 */
const parsers;

// Access parser configurations
const simpleParser = jsonld.url.parsers.simple;
console.log('Simple parser keys:', simpleParser.keys);
// Output: ['href', 'scheme', 'authority', 'path', 'query', 'fragment']

const fullParser = jsonld.url.parsers.full;
console.log('Full parser keys:', fullParser.keys);
// Output: ['href', 'protocol', 'scheme', 'authority', 'auth', 'user', 'password', 
//          'hostname', 'port', 'path', 'directory', 'file', 'query', 'fragment']

// Use parser regex directly
const customMatch = fullParser.regex.exec('https://example.org/path');

/**
 * Prepends a base IRI to a relative IRI
 * @param base - The base IRI
 * @param iri - The IRI to resolve (may be relative)
 * @returns Absolute IRI
 */
function prependBase(base, iri);

// Resolve relative IRI against base
const resolved = jsonld.url.prependBase('https://example.org/path/', 'resource.jsonld');
// Result: 'https://example.org/path/resource.jsonld'

// Resolve relative path
const resolved2 = jsonld.url.prependBase('https://example.org/docs/', '../contexts/schema.jsonld');
// Result: 'https://example.org/contexts/schema.jsonld'

// Absolute IRI remains unchanged
const resolved3 = jsonld.url.prependBase('https://example.org/', 'https://schema.org/Person');
// Result: 'https://schema.org/Person'

// Handle fragment identifiers
const resolved4 = jsonld.url.prependBase('https://example.org/doc', '#section1');
// Result: 'https://example.org/doc#section1'

/**
 * Removes a base IRI from an IRI, making it relative if possible
 * @param base - The base IRI to remove
 * @param iri - The absolute IRI
 * @returns Relative IRI if possible, otherwise the original IRI
 */
function removeBase(base, iri);

// Make IRI relative to base
const relative = jsonld.url.removeBase('https://example.org/docs/', 'https://example.org/docs/schema.jsonld');
// Result: 'schema.jsonld'

// Remove base from path
const relative2 = jsonld.url.removeBase('https://example.org/', 'https://example.org/contexts/person.jsonld');
// Result: 'contexts/person.jsonld'

// Different domain - no change
const relative3 = jsonld.url.removeBase('https://example.org/', 'https://schema.org/Person');
// Result: 'https://schema.org/Person' (unchanged)

// Fragment handling
const relative4 = jsonld.url.removeBase('https://example.org/doc', 'https://example.org/doc#section1');
// Result: '#section1'

/**
 * Removes dot segments from a URL path
 * @param path - The path to normalize
 * @returns Normalized path with dot segments removed
 */
function removeDotSegments(path);

// Remove single dot segments
const normalized1 = jsonld.url.removeDotSegments('/a/b/c/./../../g');
// Result: '/a/g'

// Remove double dot segments
const normalized2 = jsonld.url.removeDotSegments('/a/b/c/../d/e/../f');
// Result: '/a/b/d/f'

// Handle leading dots
const normalized3 = jsonld.url.removeDotSegments('../../../g');
// Result: 'g'

// Complex path normalization
const normalized4 = jsonld.url.removeDotSegments('/a/b/./c/../d/./e/../../f/g');
// Result: '/a/f/g'

/**
 * Checks if a URL is absolute
 * @param v - The URL to check  
 * @returns true if URL is absolute
 */
function isAbsolute(v);

/**
 * Checks if a URL is relative
 * @param v - The URL to check
 * @returns true if URL is relative
 */
function isRelative(v);

// Check absolute URLs
const isAbs1 = jsonld.url.isAbsolute('https://example.org/path');
// Result: true

const isAbs2 = jsonld.url.isAbsolute('/path/to/resource');
// Result: false

const isAbs3 = jsonld.url.isAbsolute('mailto:user@example.org');
// Result: true

// Check relative URLs
const isRel1 = jsonld.url.isRelative('./resource.jsonld');
// Result: true

const isRel2 = jsonld.url.isRelative('../contexts/schema.jsonld');
// Result: true

const isRel3 = jsonld.url.isRelative('https://example.org/');
// Result: false

// URL processing pipeline for JSON-LD contexts
const processContextUrl = (baseUrl, contextRef) => {
  console.log('Base URL:', baseUrl);
  console.log('Context reference:', contextRef);
  
  // Check if context reference is absolute
  if (jsonld.url.isAbsolute(contextRef)) {
    console.log('Context is absolute URL');
    return contextRef;
  }
  
  // Resolve relative context against base
  const resolvedUrl = jsonld.url.prependBase(baseUrl, contextRef);
  console.log('Resolved URL:', resolvedUrl);
  
  // Parse the resolved URL
  const parsed = jsonld.url.parse(resolvedUrl);
  console.log('Parsed components:', {
    scheme: parsed.scheme,
    hostname: parsed.hostname,
    path: parsed.path,
    query: parsed.query,
    fragment: parsed.fragment
  });
  
  // Normalize the path
  if (parsed.path) {
    const normalizedPath = jsonld.url.removeDotSegments(parsed.path);
    console.log('Normalized path:', normalizedPath);
  }
  
  return resolvedUrl;
};

// Example usage
const baseUrl = 'https://example.org/documents/person.jsonld';
const contextRef = '../contexts/schema.jsonld';
const finalUrl = processContextUrl(baseUrl, contextRef);
// Result: 'https://example.org/contexts/schema.jsonld'

// URL manipulation for JSON-LD compaction
const makeRelativeIfPossible = (baseUrl, targetUrl) => {
  if (jsonld.url.isAbsolute(targetUrl)) {
    // Try to make it relative
    const relative = jsonld.url.removeBase(baseUrl, targetUrl);
    
    // Check if it's actually relative now
    if (jsonld.url.isRelative(relative)) {
      console.log(`Made relative: ${targetUrl} -> ${relative}`);
      return relative;
    }
  }
  
  return targetUrl;
};

/**
 * Simple URL parser result
 */
interface SimpleUrlParts {
  href: string;
  scheme: string | null;
  authority: string | null;
  path: string;
  query: string | null;
  fragment: string | null;
}

/**
 * Full URL parser result
 */
interface FullUrlParts extends SimpleUrlParts {
  protocol: string | null;
  auth: string | null;
  user: string | null;
  password: string | null;
  hostname: string | null;
  port: string | null;
  directory: string | null;
  file: string | null;
}

/**
 * URL parser configuration
 */
interface UrlParser {
  keys: string[];
  regex: RegExp;
}

/**
 * Available URL parsers
 */
interface UrlParsers {
  simple: UrlParser;
  full: UrlParser;
}

/**
 * URL utilities interface
 */
interface UrlUtilities {
  parse(str: string, parser?: 'simple' | 'full'): SimpleUrlParts | FullUrlParts;
  prependBase(base: string, iri: string): string;
  removeBase(base: string, iri: string): string;
  removeDotSegments(path: string): string;
  isAbsolute(v: string): boolean;
  isRelative(v: string): boolean;
  parsers: UrlParsers;
}