Make typescript typings stricter across

Author: hoijnet

lib/typedef.js

@@ -190,4 +190,24 @@ const { ACTIONS } = Utils.ACTIONS;
  * @property {string|Blob} data - Attached data, such as CSV contents
  */
 
+/**
+ * @typedef {Object} Frame - Represents a document frame, object frame, or property frame
+ * in the viewer system. Frames are used to describe the structure and properties of data
+ * being displayed or validated.
+ * @property {string} [subject] - Subject identifier
+ * @property {string} [property] - Property name
+ * @property {string} [type] - Type information (e.g., xsd:string, schema:Person)
+ * @property {*} [value] - Frame value
+ * @property {number} [depth] - Depth in frame hierarchy
+ * @property {string} [range] - Property range/type
+ * @property {string} [label] - Display label
+ * @property {Object} [parent] - Parent frame reference
+ * @property {Array} [children] - Child frames
+ * @property {string} [status] - Frame status: 'updated' | 'error' | 'new' | 'ok'
+ * @property {boolean} [literal] - Whether this represents a literal value
+ * @property {number} [index] - Index in parent collection
+ * @property {Object} [frame] - Nested frame data
+ * @property {string} [subjectClass] - Class of the subject
+ */
+
 module.exports = {};

lib/viewer/frameRule.js

@@ -8,6 +8,10 @@
 /* eslint-disable no-use-before-define */
 const TerminusRule = require('./terminusRule');
 
+/**
+ * @typedef {import('../typedef').Frame} Frame
+ */
+
 /**
  * @file Frame Rule
  * @license Apache Version 2
@@ -23,7 +27,7 @@ Object.setPrototypeOf(FrameRule.prototype, TerminusRule.TerminusRule.prototype);
 /**
  * Returns an array of rules that match the paased frame
  * @param {[FrameRule]} rules - array of rules to be tested
- * @param {Frame} frame - object frame, property frame or data from to be tested
+ * @param {Frame | object} frame - document frame, object frame, or property frame to be tested
  * @param {function} [onmatch] - optional function to be called with args (frame, rule)
  * on each match
  */

lib/viewer/tableConfig.js

@@ -124,8 +124,10 @@ WOQLTableConfig.prototype.prettyPrint = function () {
 };
 
 /**
- * @param {boolean} canfilter
- * @returns  WOQLTableConfig
+ * Gets or sets whether the table is filterable
+ * @param {boolean} [canfilter] - If provided, sets the filterable state
+ * @returns {boolean|WOQLTableConfig} - Returns the filterable state (boolean) when called
+ * without arguments, or returns this instance (WOQLTableConfig) for chaining when setting
  */
 
 WOQLTableConfig.prototype.filterable = function (canfilter) {

lib/viewer/terminusRule.js

@@ -20,7 +20,7 @@ TerminusRule.prototype.literal = function (tf) {
 };
 
 /**
- * @param {[TYPE_URLS]} list - parameters are types identified by prefixed URLS (xsd:string...)
+ * @param {...string} list - parameters are types identified by prefixed URLS (xsd:string...)
  */
 TerminusRule.prototype.type = function (...list) {
   if (typeof list === 'undefined' || list.length === 0) {

lib/viewer/woqlChooser.js

@@ -6,6 +6,10 @@ const WOQLChooserConfig = require('./chooserConfig');
 const UTILS = require('../utils');
 const { WOQLRule } = require('./woqlRule');
 
+/**
+ * @typedef {import('../woqlClient')} WOQLClient
+ */
+
 /**
  * Very simple implementation of a WOQL backed chooser
  * Makes a drop down from a WOQL query - configuration tells it which columns to use...

lib/viewer/woqlResult.js

@@ -8,6 +8,11 @@
 const UTILS = require('../utils');
 const WOQL = require('../woql');
 const WOQLQ = require('./woqlPaging');
+
+/**
+ * @typedef {import('../query/woqlCore')} WOQLQuery
+ */
+
 /**
  * @module WOQLResult
  * @license Apache Version 2

lib/viewer/woqlStream.js

@@ -1,5 +1,9 @@
 const WOQLStreamConfig = require('./streamConfig');
 
+/**
+ * @typedef {import('../woqlClient')} WOQLClient
+ */
+
 /**
  * @param {WOQLClient} client
  * @param {WOQLStreamConfig} config

lib/woql.js

@@ -522,6 +522,9 @@ WOQL.evaluate = function (arithExp, resultVarName) {
  * @example
  * let [result] = vars("result")
  * eval(plus(2, minus(3, 1)), result)
+ * @deprecated Use {@link evaluate} instead. The name 'eval' conflicts with JavaScript's
+ * built-in eval in strict mode.
+ * @internal
  */
 WOQL.eval = function (arithExp, resultVarName) {
   return new WOQLQuery().eval(arithExp, resultVarName);
@@ -1350,7 +1353,7 @@ WOQL.iri = function (val) {
 /**
  * Generates javascript variables for use as WOQL variables within a query
  * @param  {...string} varNames
- * @returns {array<Var>} an array of javascript variables which can be dereferenced using the
+ * @returns {Array<Var>} an array of javascript variables which can be dereferenced using the
  * array destructuring operation
  * @example
  * const [a, b, c] = WOQL.vars("a", "b", "c")
@@ -1364,7 +1367,7 @@ WOQL.vars = function (...varNames) {
 /**
  * Generates unique javascript variables for use as WOQL variables within a query
  * @param  {...string} varNames
- * @returns {array<Var>} an array of javascript variables which can be dereferenced using the
+ * @returns {Array<Var>} an array of javascript variables which can be dereferenced using the
  * array destructuring operation
  * @example
  * const [a, b, c] = WOQL.vars("a", "b", "c")

lib/woqlClient.js

@@ -14,6 +14,10 @@ const ConnectionConfig = require('./connectionConfig');
 const WOQL = require('./woql');
 const WOQLQuery = require('./query/woqlCore');
 
+/**
+ * @typedef {import('./typedef').NamedResourceData} NamedResourceData
+ */
+
 /**
  * @license Apache Version 2
  * @class

scripts/fix-eval-export.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+/**
+ * Post-process generated .d.ts files to fix the 'eval' export issue.
+ * The function 'eval' is a reserved keyword in strict mode, so we rename it
+ * in the type definitions while keeping the JavaScript implementation for backward compatibility.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const woqlDtsPath = path.join(__dirname, '../dist/typescript/lib/woql.d.ts');
+
+if (!fs.existsSync(woqlDtsPath)) {
+  console.error(`Error: ${woqlDtsPath} not found. Run 'npm run generate-types' first.`);
+  process.exit(1);
+}
+
+let content = fs.readFileSync(woqlDtsPath, 'utf8');
+
+// Remove the eval export line (it's deprecated, use evaluate instead)
+const evalExportRegex = /export declare function eval\([^)]*\): [^;]+;[\r\n]*/g;
+const originalLength = content.length;
+
+content = content.replace(evalExportRegex, '');
+
+if (content.length < originalLength) {
+  fs.writeFileSync(woqlDtsPath, content, 'utf8');
+  console.log('>> Removed eval export from woql.d.ts (use evaluate() instead)');
+} else {
+  console.log('>> No eval export found in woql.d.ts, no workaround needed');
+}