Merge pull request #298 from zazuko/formats-types

build(formats): type declarations

.changeset/brave-papayas-obey.md

@@ -0,0 +1,5 @@
+---
+"barnard59-formats": patch
+---
+
+Added type declarations

.changeset/eighty-melons-boil.md

@@ -0,0 +1,5 @@
+---
+"barnard59-env": patch
+---
+
+Update `@zazuko/env-node`

.changeset/young-turkeys-sit.md

@@ -0,0 +1,5 @@
+---
+"barnard59-formats": patch
+---
+
+Ensures that the RDF/JS environment is used with parser streams

.github/workflows/ci.yaml

@@ -81,14 +81,20 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os:
-          - ubuntu-latest
-          - macos-latest
-          - windows-latest
-    runs-on: ${{ matrix.os }}
+        env:
+          - os: ubuntu-latest
+            node: 20
+          - os: macos-latest
+            node: 20
+          - os: windows-latest
+            node: 20.12.1 # Pinned, because of https://github.com/approvals/Approvals.NodeJS/issues/176
+    runs-on: ${{ matrix.env.os }}
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.env.node }}
+          cache: npm
       - run: npm ci
       - run: npx barnard59 run test/e2e/definitions/file-loader.ttl
       - run: npx barnard59 run test/e2e/definitions/foreach/with-handler.ttl
@@ -103,25 +109,31 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os:
-          - ubuntu-latest
-          - macos-latest
-          - windows-latest
-    runs-on: ${{ matrix.os }}
+        env:
+          - os: ubuntu-latest
+            node: 20
+          - os: macos-latest
+            node: 20
+          - os: windows-latest
+            node: 20.12.1 # Pinned, because of https://github.com/approvals/Approvals.NodeJS/issues/176
+    runs-on: ${{ matrix.env.os }}
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.env.node }}
+          cache: npm
       - run: npm ci
       - name: pack all
         run: npm pack -ws
       - run: npm install -g barnard59-*.tgz
-        if: matrix.os == 'ubuntu-latest' || matrix.os == 'macos-latest'
+        if: matrix.env.os == 'ubuntu-latest' || matrix.env.os == 'macos-latest'
       - run: cmd /c npm install -g (Get-ChildItem -Filter barnard59-*.tgz).FullName
-        if: matrix.os == 'windows-latest'
+        if: matrix.env.os == 'windows-latest'
       - run: which barnard59
       - run: barnard59 --help
       - run: barnard59 shacl validate --shapes test/support/pipeline-shapes.ttl < test/e2e/definitions/file-loader.ttl
-        if: matrix.os == 'ubuntu-latest' || matrix.os == 'macos-latest'
+        if: matrix.env.os == 'ubuntu-latest' || matrix.os == 'macos-latest'
       - run: barnard59 shacl validate --shapes test/support/pipeline-shapes.ttl < test/e2e/definitions/file-loader.ttl
-        if: matrix.os == 'windows-latest'
+        if: matrix.env.os == 'windows-latest'
         shell: cmd

package.json

@@ -28,7 +28,7 @@
     "mocha": "^10.2.0",
     "sinon-chai": "^3.7.0",
     "ts-node": "^10.9.2",
-    "typescript": "^5.3.2",
+    "typescript": "^5.4.5",
     "wsrun": "^5.2.4"
   },
   "lint-staged": {

packages/formats/csvw.js

@@ -3,13 +3,41 @@ import CsvwParser from 'rdf-parser-csvw'
 import tracer from './lib/tracer.js'
 import { toDataset } from './lib/stream.js'
 
+/**
+ * @typedef {{
+ *   metadata: import('@rdfjs/types').DatasetCore
+ *   timezone?: string
+ *   relaxColumnCount?: boolean
+ *   skipLinesWithError?: boolean
+ * }} Options
+ */
+
+/**
+ * @overload
+ * @param {Options} args
+ * @return {import('duplexify').Duplexify}
+ */
+
+/**
+ * @overload
+ * @param {import('@rdfjs/types').DatasetCore} metadata
+ * @return {import('duplexify').Duplexify}
+ */
+
+/**
+ * @this {import('barnard59-core').Context}
+ * @param {Options | import('@rdfjs/types').DatasetCore} args
+ */
 function parse(args) {
+  /**
+   * @type {import('@rdfjs/types').DatasetCore}
+   */
   let metadata
   let relaxColumnCount = false
   let skipLinesWithError = false
   let timezone = 'local'
 
-  if (args.metadata) {
+  if ('metadata' in args) {
     metadata = args.metadata
 
     if (typeof args.relaxColumnCount !== 'undefined') {

packages/formats/jsonld.js

@@ -6,20 +6,28 @@ import sinkToDuplex from '@rdfjs/sink-to-duplex'
 import { combine, jsonStringify } from 'barnard59-base'
 import tracer from './lib/tracer.js'
 
+/**
+ * @this {import('barnard59-core').Context}
+ * @param {Object} [options]
+ * @param {string | Record<string, string>} [options.localContext]
+ */
 function parse({ localContext } = {}) {
-  let documentLoader = null
+  /**
+   * @type {import('@rdfjs/parser-jsonld').DocumentLoader | undefined}
+   */
+  let documentLoader
 
   if (localContext) {
     if (typeof localContext === 'string') {
-      localContext = JSON.parse(localContext)
+      documentLoader = new FsDocumentLoader(JSON.parse(localContext))
+    } else {
+      documentLoader = new FsDocumentLoader(localContext)
     }
-
-    documentLoader = new FsDocumentLoader(localContext)
   }
 
   return tracer.startActiveSpan('jsonld:parse', span => {
     const stream = sinkToDuplex(new Parser({ factory: this.env, documentLoader }), { objectMode: true })
-    stream.on('error', err => {
+    stream.on('error', /** @type {any} */ err => {
       span.recordException(err)
       span.setStatus({ code: SpanStatusCode.ERROR, message: err.message })
       span.end()
@@ -29,10 +37,13 @@ function parse({ localContext } = {}) {
   })
 }
 
+/**
+ * @this {import('barnard59-core').Context}
+ */
 const parseObject = function () {
   return tracer.startActiveSpan('jsonld:parse.object', span => {
     const stream = combine([jsonStringify(), parse.call(this)], { objectMode: true })
-    stream.on('error', err => {
+    stream.on('error', (/** @type Error */ err) => {
       span.recordException(err)
       span.setStatus({ code: SpanStatusCode.ERROR, message: err.message })
       span.end()