Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
get
✓ import { get } from 'barnard59-http'
✗ const { get } = require('barnard59-http')
barnard59-http functions are primarily used as pipeline steps in RDF definitions, but can be imported programmatically. The library is ESM-first.
post
✓ import { post } from 'barnard59-http'
✗ const { post } = require('barnard59-http')
Used for HTTP POST requests within a pipeline. ESM import is standard; CommonJS `require` might fail due to the package's module type.
request
✓ import { request } from 'barnard59-http'
✗ import request from 'barnard59-http'
Provides a generic HTTP request step, allowing full control over method, headers, and body. It is a named export, not a default export.
Demonstrates defining an RDF pipeline in Turtle (.ttl) to fetch JSON data via an `http:get` step and process it with a custom TypeScript step. It showcases integration within the Barnard59 ecosystem and execution via the `barnard59` CLI.
/* pipeline.ttl */
@prefix pipeline: <https://pipeline.described.at/> .
@prefix p: <http://barnard59.com/pipeline/> .
@prefix http: <http://barnard59.com/http/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
<http://example.org/pipeline/fetchData> a p:Pipeline ;
rdfs:label "Fetch JSON data from an API" ;
pipeline:runs (
[ a http:get ;
http:url "https://jsonplaceholder.typicode.com/todos/1"^^xsd:anyURI ;
rdfs:label "Fetch Todo 1"
]
[ a p:map ;
rdfs:label "Parse JSON and extract title" ;
pipeline:handle <node:./transform.js#parseJsonAndExtractTitle>
]
[ a p:catch ;
rdfs:label "Handle Errors"
pipeline:handle <node:./transform.js#logError>
]
) .
/* transform.ts */
import { Context, Stream } from '@barnard59/core';
export function parseJsonAndExtractTitle(this: Context, chunk: Stream) {
const content = chunk.toString(); // Assuming the HTTP response is a string
try {
const json = JSON.parse(content);
return this.env.rdf.literal(json.title || 'No Title');
} catch (error) {
console.error('Failed to parse JSON or extract title:', error);
return this.env.rdf.literal('Error processing data');
}
}
export function logError(this: Context, error: Error) {
console.error('Pipeline error caught:', error.message);
return this.env.rdf.literal(`Error: ${error.message}`);
}
/* Usage with barnard59 CLI: */
// npm install -g barnard59
// npm install barnard59-http @barnard59/core @zazuko/env
// barnard59 run pipeline.ttl --pipeline http://example.org/pipeline/fetchData
barnard59 --version
Debug
Known issues
breakingOlder versions of barnard59 and its related packages might have strict peer dependency requirements for rdf-js. Upgrading individual barnard59-* packages without ensuring compatibility across the entire ecosystem can lead to runtime errors due to differing rdf-js interface expectations.fixAlways update barnard59 packages within the same major version range when possible. Refer to the main barnard59 monorepo changelog for cross-package compatibility notes. Ensure your project's rdf-js dependencies align with the barnard59 ecosystem's expectations.
affects: All versions, especially major/minor updates.
gotchaBarnard59 is designed for streaming data. While barnard59-http operations inherently support streams, certain pipeline designs or custom steps that collect entire datasets into memory can negate streaming benefits and lead to out-of-memory errors for large inputs.fixDesign custom pipeline steps to be stream-aware, processing data chunk-by-chunk. Avoid operations like `toArray()` on large streams within custom handlers unless strictly necessary and memory usage is controlled.
affects: All versions
gotchaSince barnard59 and its modular packages like barnard59-http have transitioned to an ESM-first approach, using CommonJS `require()` syntax can lead to `ERR_UNKNOWN_FILE_EXTENSION` or `Cannot find module` errors, particularly in Node.js environments configured for CJS.fixEnsure your project uses ES Modules (e.g., `"type": "module"` in package.json or `.mjs` file extensions) and uses `import` statements. If a pure CommonJS environment is required, consider using dynamic `import()` or transpilation.
affects: >=2.x
gotchaHTTP requests made via barnard59-http steps are subject to network failures, incorrect URLs, or API authentication issues, leading to pipeline halts or unexpected data. Error handling within the pipeline definition is crucial.fixImplement `pipeline:catch` steps in your RDF pipeline definitions to gracefully handle HTTP errors. Utilize `http:retry` for transient network issues or `http:timeout` for long-running requests where applicable.
affects: All versions
Errors
Common errors & fixes
ERR_UNKNOWN_FILE_EXTENSION: Unknown file extension ".ttl" for .../pipeline.ttl
The Node.js runtime is trying to interpret the .ttl (Turtle) pipeline definition file as a JavaScript module, which it cannot do by default in an ESM context.
fixEnsure you are running the pipeline using the `barnard59` CLI (e.g., `barnard59 run pipeline.ttl`) or programmatically loading the RDF graph, not directly trying to `import` or `require` the `.ttl` file as a JS module.
Error: HttpError: 404 Not Found (or similar 4xx/5xx status code)
The HTTP request made by a barnard59-http step (e.g., `http:get`) received an error status code from the target server, indicating a client-side (4xx) or server-side (5xx) issue.
fixVerify the `http:url` in your pipeline definition is correct and accessible. Check the target API's documentation for expected endpoints and parameters. Implement `pipeline:catch` steps to handle these errors gracefully and potentially retry failed requests.
TypeError: Invalid RDF/JS object provided to operation
A custom JavaScript step or another pipeline operation received an RDF/JS object (e.g., Quad, Term, Dataset) that does not conform to the expected RDF/JS specification or the specific version used by barnard59.
fixCheck the `rdf-js` version used by your `barnard59` installation and ensure any custom code or external RDF/JS libraries are compatible. Inspect the input to the problematic step to ensure it's a valid RDF/JS object.
Audit
Dependencies
barnard59-corerequiredProvides the core pipeline execution logic and base steps that barnard59-http integrates with.
@zazuko/envrequiredProvides an RDF/JS environment for common RDF operations and factories, often wrapped by barnard59-env.