Document Loading

/**
 * Default document loader for external documents
 * @type {DocumentLoader}
 */
let documentLoader;

const jsonld = require('jsonld');

// Get current document loader
const currentLoader = jsonld.documentLoader;

// Set custom document loader
jsonld.documentLoader = async (url, options) => {
  // Custom loading logic
  const response = await fetch(url);
  const document = await response.json();
  return {
    contextUrl: null,
    document: document,
    documentUrl: url
  };
};

/**
 * Gets remote JSON-LD document using document loader
 * @param url - The URL to fetch
 * @param options - Optional configuration object
 * @returns Promise resolving to retrieved remote document
 */
function get(url, options);

// Basic document retrieval
const remoteDoc = await jsonld.get('http://example.org/context.jsonld');
console.log(remoteDoc.document); // The loaded document
console.log(remoteDoc.documentUrl); // Final URL after redirects

// Get with custom loader for this call
const customLoader = async (url) => {
  // Custom logic
  return {
    contextUrl: null,
    document: {/* document content */},
    documentUrl: url
  };
};

const doc = await jsonld.get('http://example.org/doc', {
  documentLoader: customLoader
});

/**
 * Sets default document loader to built-in type
 * @param type - Document loader type ('node' or 'xhr')
 * @param ...params - Additional parameters for the loader
 */
function useDocumentLoader(type, ...params);

// Use Node.js document loader (default in Node.js environment)
jsonld.useDocumentLoader('node');

// Use XHR document loader (for browser environments)
jsonld.useDocumentLoader('xhr');

// Use Node.js loader with custom options
jsonld.useDocumentLoader('node', {
  headers: {
    'User-Agent': 'MyApp/1.0'
  }
});

/**
 * Registry of available document loaders
 */
const documentLoaders;

// Get Node.js document loader factory
const nodeLoader = jsonld.documentLoaders.node;

// Create custom Node.js loader instance
const customNodeLoader = nodeLoader({
  headers: {
    'User-Agent': 'MyJsonLdApp/1.0',
    'Accept': 'application/ld+json, application/json'
  }
});

// Use the custom loader
jsonld.documentLoader = customNodeLoader;

// Pre-loaded contexts cache example
const CONTEXTS = {
  "http://schema.org": {
    "@context": {
      "name": "http://schema.org/name",
      "Person": "http://schema.org/Person"
    }
  },
  "http://example.org/context": {
    "@context": {
      "title": "http://purl.org/dc/terms/title"
    }
  }
};

// Custom loader with fallback to built-in loader
const nodeDocumentLoader = jsonld.documentLoaders.node();

const customLoader = async (url, options) => {
  // Check cache first
  if (url in CONTEXTS) {
    return {
      contextUrl: null,
      document: CONTEXTS[url],
      documentUrl: url
    };
  }
  
  // Fall back to default loader
  return nodeDocumentLoader(url, options);
};

jsonld.documentLoader = customLoader;

// Authentication example
const authenticatedLoader = async (url, options) => {
  const response = await fetch(url, {
    headers: {
      'Authorization': 'Bearer ' + getAuthToken(),
      'Accept': 'application/ld+json, application/json'
    }
  });
  
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }
  
  const document = await response.json();
  return {
    contextUrl: null,
    document: document,
    documentUrl: response.url
  };
};

// Rate limiting example
class RateLimitedLoader {
  constructor(baseLoader, requestsPerSecond = 10) {
    this.baseLoader = baseLoader;
    this.interval = 1000 / requestsPerSecond;
    this.lastRequest = 0;
  }
  
  async load(url, options) {
    const now = Date.now();
    const timeSinceLastRequest = now - this.lastRequest;
    
    if (timeSinceLastRequest < this.interval) {
      await new Promise(resolve => 
        setTimeout(resolve, this.interval - timeSinceLastRequest)
      );
    }
    
    this.lastRequest = Date.now();
    return this.baseLoader(url, options);
  }
}

const rateLimitedLoader = new RateLimitedLoader(
  jsonld.documentLoaders.node(), 
  5 // 5 requests per second
);

jsonld.documentLoader = (url, options) => rateLimitedLoader.load(url, options);

/**
 * Document loader function type
 */
type DocumentLoader = (url: string, options?: any) => Promise<RemoteDocument>;

/**
 * Remote document structure returned by document loaders
 */
interface RemoteDocument {
  /**
   * Context URL from HTTP Link header (optional)
   */
  contextUrl?: string;
  
  /**
   * The actual document that was loaded
   */
  document: any;
  
  /**
   * The actual document URL after redirects
   */
  documentUrl: string;
}

/**
 * Document loader factory function type
 */
type DocumentLoaderFactory = (options?: any) => DocumentLoader;

/**
 * Document loaders registry interface
 */
interface DocumentLoaders {
  /**
   * Node.js HTTP/HTTPS document loader factory
   */
  node: DocumentLoaderFactory;
  
  /**
   * Browser XMLHttpRequest document loader factory
   */
  xhr: DocumentLoaderFactory;
}

/**
 * Node.js document loader options
 */
interface NodeDocumentLoaderOptions {
  /**
   * HTTP headers to include in requests
   */
  headers?: Record<string, string>;
  
  /**
   * Maximum number of redirects to follow
   */
  maxRedirects?: number;
  
  /**
   * Request timeout in milliseconds
   */
  timeout?: number;
  
  /**
   * HTTPS agent options
   */
  httpsAgent?: any;
  
  /**
   * HTTP agent options
   */
  httpAgent?: any;
}

/**
 * XHR document loader options
 */
interface XhrDocumentLoaderOptions {
  /**
   * HTTP headers to include in requests
   */
  headers?: Record<string, string>;
  
  /**
   * Request timeout in milliseconds
   */
  timeout?: number;
  
  /**
   * Whether to include credentials in cross-origin requests
   */
  withCredentials?: boolean;
}