RDFa Streaming Parser

Common errors

• TypeError: RdfaParser is not a constructor

  cause Attempting to invoke the module's default export as a constructor when `RdfaParser` is a named export, or incorrectly requiring the module.
  fix For CommonJS, use `const { RdfaParser } = require('rdfa-streaming-parser');` or `const RdfaParser = require('rdfa-streaming-parser').RdfaParser;`. For ESM, use `import { RdfaParser } from 'rdfa-streaming-parser';`.

• Error: Missing base IRI and content type.

  cause The `RdfaParser` was initialized without sufficient context (like a `baseIRI` or `contentType`) to correctly resolve relative IRIs or understand the RDFa profile of the input.
  fix Provide a `baseIRI` and/or `contentType` (e.g., `'text/html'`) in the `RdfaParser` constructor options. Example: `new RdfaParser({ baseIRI: 'https://example.com/', contentType: 'text/html' });`.

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ES Module `import` syntax in a file that is treated as a CommonJS module (e.g., a `.js` file without `"type": "module"` in `package.json`, or a `.cjs` file).
  fix Either configure your project to use ES Modules (by adding `"type": "module"` to `package.json` and using `.js` files, or renaming to `.mjs`), or use CommonJS `require` syntax: `const { RdfaParser } = require('rdfa-streaming-parser');`.

Warnings

• breaking Major version 3 introduces changes that might require updates to existing codebases, especially regarding how errors are handled or specific configuration options are interpreted. Users upgrading from v1 or v2 should consult the official changelog or release notes for precise breaking changes.
  Fix: Review the official changelog for `rdfa-streaming-parser` between your current version and `3.x` and update your code accordingly. Pay close attention to error handling and constructor options.
• gotcha The `RdfaParser` often requires a `baseIRI` and/or `contentType` option in its constructor for accurate parsing. Omitting these can lead to incorrect IRI resolution for relative paths or misinterpretation of the RDFa profile.
  Fix: Always provide at least a `baseIRI` (e.g., `https://example.com/`) and/or `contentType` (e.g., `'text/html'`) when initializing `RdfaParser` to ensure proper parsing context.
• gotcha While the library explicitly supports CommonJS `require`, modern Node.js development, especially when integrating with other ESM-first libraries, generally prefers native ES Modules `import` syntax for consistency and better tooling support.
  Fix: Consider migrating CommonJS `require('rdfa-streaming-parser').RdfaParser` statements to `import { RdfaParser } from 'rdfa-streaming-parser';` for alignment with current JavaScript best practices.
• gotcha The parser emits RDFJS-compliant quads. Ensure that any downstream application components consuming these quads are compatible with the RDFJS data model specification, particularly concerning `DataFactory` implementations and term representations.
  Fix: Verify compatibility with the RDFJS specification for any RDF processing libraries you are using. If needed, you can pass a custom `dataFactory` to the `RdfaParser` constructor to ensure consistency.

Install

• npm install rdfa-streaming-parser npm
• yarn add rdfa-streaming-parser yarn
• pnpm add rdfa-streaming-parser pnpm

Imports

• RdfaParser
  wrong:

  import RdfaParser from 'rdfa-streaming-parser';

  correct:

  import { RdfaParser } from 'rdfa-streaming-parser';

  RdfaParser is a named export. While CommonJS require is still supported, native ESM import is preferred in modern applications.
• RdfaParser
  wrong:

  const RdfaParser = require('rdfa-streaming-parser');

  correct:

  const { RdfaParser } = require('rdfa-streaming-parser');

  For CommonJS, RdfaParser is a named export. Directly requiring the package gives the module object, not the class constructor.
• RdfaParser

  import type { RdfaParser } from 'rdfa-streaming-parser';

  For type-only imports in TypeScript, using `import type` is recommended for explicit intent and cleaner bundles.

Quickstart

This quickstart demonstrates how to parse an RDFa document from a file stream using `RdfaParser`, log the extracted RDFJS quads, and gracefully handle completion or errors. A temporary HTML file is created and then cleaned up.

import { RdfaParser } from 'rdfa-streaming-parser';
import * as fs from 'fs'; // Node.js built-in module

async function parseRdfaFile(filePath: string, baseIri: string, contentType: string) {
  const myParser = new RdfaParser({ baseIRI: baseIri, contentType: contentType });

  console.log(`Parsing RDFa from ${filePath}...`);

  return new Promise<void>((resolve, reject) => {
    fs.createReadStream(filePath)
      .pipe(myParser)
      .on('data', (quad) => {
        console.log(`Parsed quad: ${quad.subject.value} ${quad.predicate.value} ${quad.object.value} .`);
      })
      .on('error', (error) => {
        console.error('An error occurred during parsing:', error);
        reject(error);
      })
      .on('end', () => {
        console.log('All triples were parsed successfully!');
        resolve();
      });
  });
}

// Example usage:
const dummyHtmlContent = `<!DOCTYPE html>
<html>
<head prefix="foaf: http://xmlns.com/foaf/0.1/">
  <title>Example Document</title>
  <link rel="foaf:primaryTopic foaf:maker" href="https://www.rubensworks.net/#me" />
</head>
<body>
  <h1>Hello RDFa</h1>
  <p>This is an <span property="foaf:name">RDFa Example</span>.</p>
</body>
</html>`;

const tempFilePath = 'temp_rdfa_doc.html';
fs.writeFileSync(tempFilePath, dummyHtmlContent);

parseRdfaFile(tempFilePath, 'https://example.org/doc#', 'text/html')
  .finally(() => {
    fs.unlinkSync(tempFilePath); // Clean up the temporary file
  });