Ensure variables are constructed correctly

Author: hoijnet

integration_tests/woql_arithmetic.test.ts

@@ -2,12 +2,13 @@
 import { describe, expect, test, beforeAll } from '@jest/globals';
 import { WOQLClient, WOQL } from '../index.js';
 import { DbDetails } from '../dist/typescript/lib/typedef.js';
-import { Vars } from '../lib/woql.js';
+import { vars, vars_unique, Vars, VarsUnique } from '../lib/woql.js';
 
 let client: WOQLClient //= new WOQLClient('http://127.0.0.1:6363');
 const db01 = 'db__test_woql_arithmetic';
 
 beforeAll(() => {
+  WOQL.vars_unique_reset_start(20);
   client = new WOQLClient("http://127.0.0.1:6363", { user: 'admin', organization: 'admin', key: process.env.TDB_ADMIN_PASS ?? 'root' })
   client.db(db01);
 });
@@ -22,11 +23,43 @@ describe('Tests for woql arithmetic', () => {
     expect(result["api:status"]).toEqual("api:success");
   });
 
+  test('Test simple arithmetic with Vars variables handling', async () => {
+    let v = Vars("result1", "result2");
+    const query = WOQL.limit(100).eval(WOQL.times(2, 3), v.result1);
+
+    const expectedJson = [{"result1": {"@type": "xsd:decimal", "@value": 6}}];
+    
+    const result = await client.query(query);
+    expect(result?.bindings).toStrictEqual(expectedJson);
+  });
+
+  test('Test simple arithmetic with VarsUnique variables handling', async () => {
+    let v = VarsUnique("result1", "result2");
+    const query = WOQL.limit(100).eval(WOQL.times(2, 3), v.result1);
+
+    // suffix is 21 because we reset it to 20 above
+    const expectedJson = [{"result1_21": {"@type": "xsd:decimal", "@value": 6}}];
+    
+    const result = await client.query(query);
+    expect(result?.bindings).toStrictEqual(expectedJson);
+  });
+
   test('Test simple arithmetic with vars variables handling', async () => {
-    let v = Vars("result");
-    const query = WOQL.limit(100).eval(WOQL.times(2, 3), v.result);
+    let [result1] = vars("result1");
+    const query = WOQL.limit(100).eval(WOQL.times(2, 3), result1);
 
-    const expectedJson = [{"result": {"@type": "xsd:decimal", "@value": 6}}];
+    const expectedJson = [{"result1": {"@type": "xsd:decimal", "@value": 6}}];
+    
+    const result = await client.query(query);
+    expect(result?.bindings).toStrictEqual(expectedJson);
+  });
+
+  test('Test simple arithmetic with vars_unique variables handling', async () => {
+    let [result3] = vars_unique("result3");
+    const query = WOQL.limit(100).eval(WOQL.times(2, 3), result3);
+
+    // suffix is 23 because we already used vars_unique from WOQL 2 times since we reset it to 20 above
+    const expectedJson = [{"result3_23": {"@type": "xsd:decimal", "@value": 6}}];
 
     const result = await client.query(query);
     expect(result?.bindings).toStrictEqual(expectedJson);

lib/query/woqlDoc.js

@@ -40,12 +40,6 @@ function convert(obj) {
       '@type': 'Value',
       variable: obj.name,
     };
-  // eslint-disable-next-line no-use-before-define
-  } if (obj instanceof VarUnique) {
-    return {
-      '@type': 'Value',
-      variable: obj.name,
-    };
   } if (typeof (obj) === 'object' && !Array.isArray(obj)) {
     const pairs = [];
     // eslint-disable-next-line no-restricted-syntax
@@ -73,7 +67,7 @@ function convert(obj) {
 }
 
 /**
- * @param {string} name
+ * @param {string} name The variable name
  * @returns
  */
 function Var(name) {
@@ -86,29 +80,33 @@ function Var(name) {
   };
 }
 
-/**
- * Global counter for generating unique variable names
- */
 let uniqueVarCounter = 0;
-
 /**
- * Creates a unique variable by appending an incrementing counter to the name.
- * This ensures variables are unique across all instantiations, even with the same input name.
- * @param {string} name - Base name for the variable
- * @returns {VarUnique} - A unique variable object
+ * @param {string} name The variable name
+ * @returns
  */
 function VarUnique(name) {
   uniqueVarCounter += 1;
-  this.name = `${name}_${uniqueVarCounter}`;
-  this.baseName = name;
-  this.counter = uniqueVarCounter;
+  const localName = `${name}_${uniqueVarCounter}`;
+  this.name = localName;
   this.json = function () {
     return {
       '@type': 'Value',
       variable: this.name,
     };
   };
 }
+// Inherit Var prototype chain for VarUnique to pass instanceof check for Var (same)
+VarUnique.prototype = Object.create(Var.prototype);
+VarUnique.prototype.constructor = VarUnique;
+
+/**
+ * Reset the unique variable counter to a specific value
+ * @param {number} start - starting value
+ */
+function SetVarsUniqueCounter(start) {
+  uniqueVarCounter = start;
+}
 
 /**
  * @param {object} name
@@ -126,7 +124,7 @@ function Doc(obj) {
 */
 function Vars(...args) {
   const varObj = {};
-  for (let i = 0, j = arguments.length; i < j; i += 1) {
+  for (let i = 0, j = args.length; i < j; i += 1) {
     const argumentName = args[i];
 
     // this[argumentName] = new Var(argumentName);
@@ -135,6 +133,21 @@ function Vars(...args) {
   return varObj;
 }
 
+/**
+* @param  {...string} varNames
+* @returns {object<Var>}
+*/
+function VarsUnique(...args) {
+  const varObj = {};
+  for (let i = 0, j = args.length; i < j; i += 1) {
+    const argumentName = args[i];
+
+    uniqueVarCounter += 1;
+    varObj[argumentName] = new Var(argumentName + (uniqueVarCounter ? `_${uniqueVarCounter}` : ''));
+  }
+  return varObj;
+}
+
 module.exports = {
-  Vars, Var, VarUnique, Doc,
+  Vars, VarsUnique, Var, VarUnique, Doc, SetVarsUniqueCounter,
 };

lib/woql.js

@@ -5,7 +5,10 @@
 const WOQLQuery = require('./query/woqlBuilder');
 const WOQLLibrary = require('./query/woqlLibrary');
 const {
-  Vars, Var, VarUnique, Doc,
+  Vars, Var, Doc,
+  VarsUnique,
+  VarUnique,
+  SetVarsUniqueCounter,
 } = require('./query/woqlDoc');
 // eslint-disable-next-line no-unused-vars
 const typedef = require('./typedef');
@@ -1359,32 +1362,29 @@ WOQL.vars = function (...varNames) {
 };
 
 /**
- * Generates unique javascript variables for use as WOQL variables within a query.
- * Each call to vars_unique() creates variables with unique names by appending an
- * incrementing counter, ensuring that variables are fully unique across all scopes.
- * This is particularly useful with select() to firewall local variables from other
- * scopes, even when requesting the same variable name multiple times.
- *
- * @param  {...string} varNames - Base names for the variables
- * @returns {array<VarUnique>} an array of unique javascript variables which can be
- * dereferenced using the array destructuring operation
- * @example
- * const [a, b, c] = WOQL.vars_unique("a", "b", "c")
- * // Creates variables like "a_1", "b_2", "c_3"
- * const [a2, b2] = WOQL.vars_unique("a", "b")
- * // Creates variables like "a_4", "b_5" - guaranteed unique even with same input names
- *
+ * 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
+ * array destructuring operation
  * @example
- * // Using with select() to create isolated scopes
- * const [localVar] = WOQL.vars_unique("x")
- * WOQL.select(localVar, WOQL.triple(localVar, "rdf:type", "Person"))
- * // localVar is "x_1" and won't conflict with any other "x" variables
+ * const [a, b, c] = WOQL.vars("a", "b", "c")
+ * //a, b, c are javascript variables that are unique WOQL variables
  */
 
 WOQL.vars_unique = function (...varNames) {
   return varNames.map((item) => new VarUnique(item));
 };
 
+/**
+ * Sets the unique variable counter to a specific value
+ * This is particularly useful together with select() for locally scoped variables
+ * @param  {number} start - starting value
+ */
+
+WOQL.vars_unique_reset_start = function (start) {
+  SetVarsUniqueCounter(start ?? 0);
+};
+
 /**
  * Produces an encoded form of a document that can be used by a WOQL operation
  * such as `WOQL.insert_document`.
@@ -1422,6 +1422,22 @@ WOQL.Vars = function (...varNames) {
   return new Vars(...varNames);
 };
 
+/**
+ *
+ * Produces variables with unique names by appending an incrementing counter to each variable name.
+ * This is particularly useful together with select() for locally scoped variables
+ *
+ * @param  {...string} varNames
+ * @returns {object<Var>}
+ * @example
+ * // Creates variables like "a_4", "b_5" - unique even with same input names
+ * const v = WOQL.VarsUnique('var01', 'var02', 'var03');
+ * triple(v.var01, v.var02, v.var03) // locally scoped
+ */
+WOQL.VarsUnique = function (...varNames) {
+  return new VarsUnique(...varNames);
+};
+
 /**
  *
  * query module

test/woql.spec.js

@@ -443,20 +443,25 @@ describe('woql queries', () => {
   });
 
   it('check vars_unique appends incrementing counter', () => {
+    WOQL.vars_unique_reset_start(0);
     // Get the current counter value by creating a variable
     const [v1] = WOQL.vars_unique('test');
-    const counter1 = v1.counter;
+    const counter1 = Number(v1.name.split('_')[1]);
 
     // Next variable should have counter + 1
     const [v2] = WOQL.vars_unique('test');
-    expect(v2.counter).to.equal(counter1 + 1);
+    const counter2 = Number(v2.name.split('_')[1]);
+    expect(counter2).to.equal(counter1 + 1);
+    expect(counter2).to.equal(2);
 
     // And so on
     const [v3] = WOQL.vars_unique('test');
-    expect(v3.counter).to.equal(counter1 + 2);
+    const counter3 = Number(v3.name.split('_')[1]);
+    expect(counter3).to.equal(counter1 + 2);
   });
 
   it('check vars_unique generates correct JSON with unique variable names', () => {
+    WOQL.vars_unique_reset_start(0);
     const [a, b] = WOQL.vars_unique('myvar', 'myvar');
 
     const jsonA = a.json();
@@ -469,10 +474,18 @@ describe('woql queries', () => {
 
     // Variable names in JSON should be different even with same base name
     expect(jsonA.variable).to.not.equal(jsonB.variable);
-    expect(jsonA.variable).to.include('myvar');
-    expect(jsonB.variable).to.include('myvar');
+    expect(jsonA.variable).to.equal('myvar_1');
+    expect(jsonB.variable).to.equal('myvar_2');
   });
 
+  it('checks that vars_unique and vars work the same way', () => {
+    const [a, b] = WOQL.vars_unique('myvar', 'myvar');
+    const [x, y] = WOQL.vars('myvar', 'myvar');
+
+    expect(a.name.split('_')[0]).to.equal(x.name);
+    expect(b.name.split('_')[0]).to.equal(y.name);
+  })
+
   it('check vars still works exactly as before (no changes)', () => {
     const [x, y, z] = WOQL.vars('X', 'Y', 'Z');