{"id":12875,"library":"barnard59-cube","title":"Barnard59 RDF Cube Operations","description":"barnard59-cube is a JavaScript package offering a suite of operations and command-line interfaces for managing RDF cubes within Barnard59 Linked Data pipelines. It provides functionalities like `toObservation` for creating cube observations aligned with the Cube Schema specification and `buildCubeShape` for deriving SHACL shapes from observation streams. The package also includes robust CLI commands for fetching, validating, and checking RDF cube metadata and observations against defined constraints using SPARQL endpoints. Currently at version 1.4.10, this package is part of the actively developed `barnard59` monorepo, benefiting from continuous updates that incorporate dependency upgrades and minor feature enhancements. Its key differentiator is the seamless integration of RDF cube lifecycle management into stream-based data processing workflows.","status":"active","version":"1.4.10","language":"javascript","source_language":"en","source_url":"git://github.com/zazuko/barnard59","tags":["javascript"],"install":[{"cmd":"npm install barnard59-cube","lang":"bash","label":"npm"},{"cmd":"yarn add barnard59-cube","lang":"bash","label":"yarn"},{"cmd":"pnpm add barnard59-cube","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides RDF serialization and parsing capabilities essential for handling cube data.","package":"barnard59-formats","optional":false},{"reason":"Core RDF data model utilities for processing RDF terms and datasets.","package":"barnard59-rdf","optional":false},{"reason":"Used for SHACL-based validation of cube shapes and metadata.","package":"barnard59-shacl","optional":false},{"reason":"Provides the RDF/JS environment used throughout Barnard59 packages.","package":"barnard59-env","optional":false}],"imports":[{"note":"ESM is the primary module system for current Barnard59 versions. Operations are typically named exports.","wrong":"const toObservation = require('barnard59-cube').toObservation;","symbol":"toObservation","correct":"import { toObservation } from 'barnard59-cube';"},{"note":"Import specific operations as named exports. Direct path imports might break with future refactoring.","wrong":"import buildCubeShape from 'barnard59-cube/lib/buildCubeShape';","symbol":"buildCubeShape","correct":"import { buildCubeShape } from 'barnard59-cube';"},{"note":"The 'cube' namespace primarily exposes CLI commands via the main `barnard59` executable, not directly importable functions for programmatic use in a typical JS module fashion.","symbol":"cube","correct":"barnard59 cube fetch-cube --help"}],"quickstart":{"code":"import { createRequire } from 'module';\nconst require = createRequire(import.meta.url);\nconst { spawn } = require('child_process');\n\nconst cubeUri = 'https://agriculture.ld.admin.ch/agroscope/PRIFm8t15/2';\nconst endpoint = 'https://int.lindas.admin.ch/query';\n\nconsole.log(`Fetching cube data for ${cubeUri} from ${endpoint}...`);\n\nconst child = spawn('barnard59', ['cube', 'fetch-cube', '--cube', cubeUri, '--endpoint', endpoint]);\n\nlet stdoutData = '';\nlet stderrData = '';\n\nchild.stdout.on('data', (data) => {\n  stdoutData += data.toString();\n});\n\nchild.stderr.on('data', (data) => {\n  stderrData += data.toString();\n});\n\nchild.on('close', (code) => {\n  if (code === 0) {\n    console.log('Cube data fetched successfully (truncated to first 500 chars):');\n    console.log(stdoutData.substring(0, 500) + (stdoutData.length > 500 ? '...' : ''));\n  } else {\n    console.error(`Error fetching cube data. Exit code: ${code}`);\n    console.error(`Stderr: ${stderrData}`);\n  }\n});\n\n// Example of programmatic use (assuming operations are exported):\n// import { toObservation, buildCubeShape } from 'barnard59-cube';\n// async function processCubeData() {\n//   // This would typically involve setting up a Barnard59 pipeline\n//   // For example: sourceStream.pipe(toObservation()).pipe(buildCubeShape()).pipe(sinkStream);\n//   console.log('\\nProgrammatic operations would go here, e.g., using toObservation or buildCubeShape.');\n//   console.log('Refer to Barnard59 pipeline documentation for detailed programmatic usage.');\n// }\n// processCubeData();","lang":"javascript","description":"Demonstrates how to use the `fetch-cube` CLI command to retrieve RDF cube data from a SPARQL endpoint, capturing its output."},"warnings":[{"fix":"Review any code that inspects or manipulates RDF literals, particularly comparisons or type checks, to account for implicit `xsd:string` datatypes on plain literals. Explicitly check for `rdf:langString` if language-tagged strings are expected.","message":"Updating `rdf-literal` to v2, a core dependency, changes how RDF literals are handled. RDF 1.1 specifies that all literals, including plain ones, are now considered typed (e.g., plain literals implicitly have `xsd:string`). Code that relied on distinguishing plain literals without a datatype from those explicitly typed as `xsd:string` may exhibit changed behavior.","severity":"breaking","affected_versions":">=1.4.10"},{"fix":"Consult the `rdfxml-streaming-parser` v3 changelog for specific breaking changes. Adjust parser configuration, error handling logic, or input RDF/XML documents if issues arise during parsing.","message":"The `rdfxml-streaming-parser` dependency was updated to v3. Major version bumps in parsers typically involve breaking changes in configuration options, error handling, or stricter adherence to specifications, which could affect how RDF/XML input is processed or validated.","severity":"breaking","affected_versions":">=1.4.10"},{"fix":"Examine the `@zazuko/env-node` v3 release notes for breaking changes related to RDF/JS factory usage or environment setup. Update code that directly interacts with the RDF/JS environment or creates RDF terms.","message":"The `@zazuko/env-node` dependency has been updated to v3. This environment provides the RDF/JS factories and utilities. A major version update might introduce breaking changes in the RDF/JS data model factories, default behaviors for creating terms/datasets, or how specific environment extensions operate.","severity":"breaking","affected_versions":">=1.2.7 (via `barnard59-env`)"},{"fix":"Review SHACL shapes and validation logic. If validation failures occur unexpectedly or report formats change, consult the `rdf-validate-shacl` 0.6 changelog for necessary adjustments.","message":"The `rdf-validate-shacl` dependency, used by `barnard59-shacl` (a dependency of barnard59-cube), has been updated to 0.6. This may introduce stricter SHACL validation rules, changes in how validation reports are generated, or require updates to SHACL shapes themselves to ensure compatibility.","severity":"breaking","affected_versions":">=1.4.10 (via `barnard59-shacl`)"},{"fix":"Design pipelines to process data chunk-by-chunk using back-pressure mechanisms. Utilize `pipeline.stream.pipe()` and `pipeline.stream.on()` events rather than buffering large amounts of data in JavaScript arrays.","message":"Barnard59 pipelines, including those within `barnard59-cube`, are inherently stream-based. For optimal performance and memory efficiency, avoid collecting entire streams into memory when processing large datasets, especially for operations like `buildCubeShape` which might process many observations before emitting a single result.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Specify the RDF format explicitly using the `--profileFormat` option. For example: `barnard59 cube check-metadata --profile https://example.org/my-profile.ttl --profileFormat 'text/turtle'`.","cause":"When using `check-metadata` with a remote `--profile` URL, the HTTP response header might lack a proper `Content-Type`, preventing the pipeline from identifying the RDF format.","error":"Pipeline failed because the profile remote address does not include a correct `content-type` header."},{"fix":"Check the stderr output for more specific error messages. Verify `--cube` and `--endpoint` URIs are correct and accessible. Ensure input RDF (if from stdin) is well-formed. Use `--help` for the specific command to review expected arguments.","cause":"Generic error from CLI commands, often indicating incorrect arguments, missing environment variables, network issues (for SPARQL endpoints), or malformed input RDF.","error":"Error: Command failed with exit code 1"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null}