{"id":16307,"library":"barnard59-http","title":"HTTP Protocol for Barnard59 Linked Data Pipelines","description":"barnard59-http provides a set of HTTP protocol operations (such as GET, POST, PUT, DELETE) that function as 'steps' within Barnard59 Linked Data pipelines. Barnard59 is an Extract, Transform, Load (ETL) toolkit primarily designed for working with RDF and Linked Data, where pipelines are declaratively defined using RDF graphs (e.g., in Turtle or JSON-LD format) and executed by the `barnard59` CLI or programmatic API. This package extends the core Barnard59 functionality, enabling pipelines to interact with external HTTP resources. The current stable version is 2.1.0, and it is part of an actively maintained monorepo, with frequent patch and minor releases across its constituent packages. Key differentiators include its deep integration with RDF/Linked Data principles, its streaming architecture for handling large datasets, and the flexibility to embed custom JavaScript logic directly into RDF-defined pipelines.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"git://github.com/zazuko/barnard59","tags":["javascript","typescript"],"install":[{"cmd":"npm install barnard59-http","lang":"bash","label":"npm"},{"cmd":"yarn add barnard59-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add barnard59-http","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the core pipeline execution logic and base steps that barnard59-http integrates with.","package":"barnard59-core","optional":false},{"reason":"Provides an RDF/JS environment for common RDF operations and factories, often wrapped by barnard59-env.","package":"@zazuko/env","optional":false}],"imports":[{"note":"barnard59-http functions are primarily used as pipeline steps in RDF definitions, but can be imported programmatically. The library is ESM-first.","wrong":"const { get } = require('barnard59-http')","symbol":"get","correct":"import { get } from 'barnard59-http'"},{"note":"Used for HTTP POST requests within a pipeline. ESM import is standard; CommonJS `require` might fail due to the package's module type.","wrong":"const { post } = require('barnard59-http')","symbol":"post","correct":"import { post } from 'barnard59-http'"},{"note":"Provides a generic HTTP request step, allowing full control over method, headers, and body. It is a named export, not a default export.","wrong":"import request from 'barnard59-http'","symbol":"request","correct":"import { request } from 'barnard59-http'"}],"quickstart":{"code":"/* pipeline.ttl */\n@prefix pipeline: .\n@prefix p: .\n@prefix http: .\n@prefix rdfs: .\n@prefix xsd: .\n\n a p:Pipeline ;\n rdfs:label \"Fetch JSON data from an API\" ;\n pipeline:runs (\n [ a http:get ;\n http:url \"https://jsonplaceholder.typicode.com/todos/1\"^^xsd:anyURI ;\n rdfs:label \"Fetch Todo 1\"\n ]\n [ a p:map ;\n rdfs:label \"Parse JSON and extract title\" ;\n pipeline:handle \n ]\n [ a p:catch ;\n rdfs:label \"Handle Errors\"\n pipeline:handle \n ]\n ) .\n\n/* transform.ts */\nimport { Context, Stream } from '@barnard59/core';\n\nexport function parseJsonAndExtractTitle(this: Context, chunk: Stream) {\n const content = chunk.toString(); // Assuming the HTTP response is a string\n try {\n const json = JSON.parse(content);\n return this.env.rdf.literal(json.title || 'No Title');\n } catch (error) {\n console.error('Failed to parse JSON or extract title:', error);\n return this.env.rdf.literal('Error processing data');\n }\n}\n\nexport function logError(this: Context, error: Error) {\n console.error('Pipeline error caught:', error.message);\n return this.env.rdf.literal(`Error: ${error.message}`);\n}\n\n/* Usage with barnard59 CLI: */\n// npm install -g barnard59\n// npm install barnard59-http @barnard59/core @zazuko/env\n// barnard59 run pipeline.ttl --pipeline http://example.org/pipeline/fetchData","lang":"typescript","description":"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."},"warnings":[{"fix":"Always 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.","message":"Older 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.","severity":"breaking","affected_versions":"All versions, especially major/minor updates."},{"fix":"Design 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.","message":"Barnard59 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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.","message":"Since 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.","severity":"gotcha","affected_versions":">=2.x"},{"fix":"Implement `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.","message":"HTTP 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure 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.","cause":"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.","error":"ERR_UNKNOWN_FILE_EXTENSION: Unknown file extension \".ttl\" for .../pipeline.ttl"},{"fix":"Verify 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.","cause":"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.","error":"Error: HttpError: 404 Not Found (or similar 4xx/5xx status code)"},{"fix":"Check 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.","cause":"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.","error":"TypeError: Invalid RDF/JS object provided to operation"}],"ecosystem":"npm"}