build: type declarations

zazuko · May 16, 2024 · cd81cc1 · cd81cc1
1 parent 1df0b79
commit cd81cc1
Show file tree

Hide file tree

Showing 9 changed files with 103 additions and 7 deletions.
diff --git a/.changeset/brave-papayas-obey.md b/.changeset/brave-papayas-obey.md
@@ -0,0 +1,5 @@
+---
+"barnard59-formats": patch
+---
+
+Added type declarations
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/formats/csvw.js b/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') {

diff --git a/packages/formats/jsonld.js b/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 } = {}) {
+  /**
+   * @type {import('@rdfjs/parser-jsonld').DocumentLoader | null}
+   */
   let documentLoader = null
 
   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,6 +37,9 @@ 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 })

diff --git a/packages/formats/lib/stream.js b/packages/formats/lib/stream.js
@@ -1,5 +1,12 @@
+import { isReadableStream } from 'is-stream'
+
+/**
+ * @param {import('@rdfjs/environment/Environment.js').Environment<ReturnType<import('@zazuko/env/lib/DatasetFactory.js').default>>} rdf
+ * @param {(import('@rdfjs/types').Stream & import('stream').Readable) | import('@rdfjs/types').DatasetCore} streamOrDataset
+ * @return {Promise<import('@rdfjs/types').DatasetCore>}
+ */
 export function toDataset(rdf, streamOrDataset) {
-  if (!streamOrDataset.readable) {
+  if (!isReadableStream(streamOrDataset)) {
     return Promise.resolve(streamOrDataset)
   }
 

diff --git a/packages/formats/n3.js b/packages/formats/n3.js
@@ -1,6 +1,10 @@
 import Parser from '@rdfjs/parser-n3'
 import sinkToDuplex from '@rdfjs/sink-to-duplex'
 
+/**
+ * @this {import('barnard59-core').Context}
+ * @param {import('@rdfjs/parser-n3').ParserOptions} args
+ */
 function parse(args) {
   return sinkToDuplex(new Parser({ factory: this.env, ...args }), {
     readableObjectMode: true,

diff --git a/packages/formats/package.json b/packages/formats/package.json
@@ -30,11 +30,13 @@
     "@rdfjs/serializer-ntriples": "^2.0.0",
     "@rdfjs/sink-to-duplex": "^1.0.0",
     "barnard59-base": "^2.0.1",
+    "is-stream": "^3.0.0",
     "rdf-parser-csvw": "^0.15.0",
     "rdf-parser-csvw-xlsx": "^0.1.0",
     "rdfxml-streaming-parser": "^1.2.0"
   },
   "devDependencies": {
+    "@types/sax": "^1.2.7",
     "@zazuko/env-core": "^1.1.2",
     "barnard59-env": "^1.2.5",
     "chai": "^4.3.7"

diff --git a/packages/formats/rdf-xml.js b/packages/formats/rdf-xml.js
@@ -1,6 +1,9 @@
 import sinkToDuplex from '@rdfjs/sink-to-duplex'
 import { RdfXmlParser } from 'rdfxml-streaming-parser'
 
+/**
+ * @this {import('barnard59-core').Context}
+ */
 function parse() {
   return sinkToDuplex(new RdfXmlParser({
     dataFactory: this.env,

diff --git a/packages/formats/xlsx.js b/packages/formats/xlsx.js
@@ -3,11 +3,37 @@ import CsvwXlsxParser from 'rdf-parser-csvw-xlsx'
 import tracer from './lib/tracer.js'
 import { toDataset } from './lib/stream.js'
 
+/**
+ * @typedef {{
+ *  metadata: import('@rdfjs/types').DatasetCore
+ *  timezone?: string
+ * }} 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('rdf-js').DatasetCore}
+   */
   let metadata
   let timezone = 'local'
 
-  if (args.metadata) {
+  if ('metadata' in args) {
     metadata = args.metadata
 
     if (typeof args.timezone !== 'undefined') {