feat(woql): Add vars_unique() for generating unique variable names fixes #261

Implements a new WOQL.vars_unique() function that creates variables with
guaranteed unique names using an incrementing counter. This solves the problem
where vars() generates generic variables that can collide across scopes.

## Implementation:

**VarUnique Constructor (woqlDoc.js):**
- Global counter for unique variable generation
- Appends incrementing counter to base name (e.g., 'x' -> 'x_1', 'x_2')
- Stores baseName, name, and counter properties
- Generates proper JSON with unique variable names

**WOQL.vars_unique() Function (woql.js):**
- Maps input names to VarUnique instances
- Works identically to vars() but with uniqueness guarantee
- Useful with select() to firewall local variables from other scopes

**Convert Function Update:**
- Handles VarUnique instances like Var instances
- Ensures proper JSON serialization

## Benefits:

✅ **Guaranteed Uniqueness:** Variables are unique across all scopes, even with same input names
✅ **Scope Isolation:** Works with select() to prevent variable collision
✅ **Backward Compatible:** Original vars() unchanged and works exactly as before
✅ **Well Documented:** Comprehensive JSDoc with usage examples

## Testing:

**6 New Comprehensive Tests:**
1. ✅ Creates VarUnique instances
2. ✅ Unique names within single call
3. ✅ Unique names across multiple calls
4. ✅ Incrementing counter validation
5. ✅ Correct JSON generation
6. ✅ Original vars() unchanged

**All 156 tests passing**

## Usage Examples:

```javascript
// Basic usage
const [a, b, c] = WOQL.vars_unique('a', 'b', 'c')
// Creates: a_1, b_2, c_3

// Guaranteed uniqueness even with same names
const [x1] = WOQL.vars_unique('x')  // x_4
const [x2] = WOQL.vars_unique('x')  // x_5

// Scope isolation with select()
const [localVar] = WOQL.vars_unique('x')
WOQL.select(localVar, WOQL.triple(localVar, 'rdf:type', 'Person'))
// localVar is unique and won't conflict with other 'x' variables
```

Author: hoijnet

lib/query/woqlDoc.js

@@ -40,6 +40,12 @@ 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
@@ -80,6 +86,30 @@ 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
+ */
+function VarUnique(name) {
+  uniqueVarCounter += 1;
+  this.name = `${name}_${uniqueVarCounter}`;
+  this.baseName = name;
+  this.counter = uniqueVarCounter;
+  this.json = function () {
+    return {
+      '@type': 'Value',
+      variable: this.name,
+    };
+  };
+}
+
 /**
  * @param {object} name
  * @returns {object}
@@ -105,4 +135,6 @@ function Vars(...args) {
   return varObj;
 }
 
-module.exports = { Vars, Var, Doc };
+module.exports = {
+  Vars, Var, VarUnique, Doc,
+};

lib/woql.js

@@ -4,7 +4,9 @@
 // I HAVE TO REVIEW THE Inheritance and the prototype chain
 const WOQLQuery = require('./query/woqlBuilder');
 const WOQLLibrary = require('./query/woqlLibrary');
-const { Vars, Var, Doc } = require('./query/woqlDoc');
+const {
+  Vars, Var, VarUnique, Doc,
+} = require('./query/woqlDoc');
 // eslint-disable-next-line no-unused-vars
 const typedef = require('./typedef');
 // eslint-disable-next-line no-unused-vars
@@ -1352,6 +1354,33 @@ WOQL.vars = function (...varNames) {
   return varNames.map((item) => new Var(item));
 };
 
+/**
+ * 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
+ *
+ * @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
+ */
+
+WOQL.vars_unique = function (...varNames) {
+  return varNames.map((item) => new VarUnique(item));
+};
+
 /**
  * Produces an encoded form of a document that can be used by a WOQL operation
  * such as `WOQL.insert_document`.

test/woql.spec.js

@@ -1,7 +1,7 @@
 const { expect } = require('chai');
 
 const WOQL = require('../lib/woql');
-const { Var, Vars } = require('../lib/query/woqlDoc');
+const { Var, VarUnique, Vars } = require('../lib/query/woqlDoc');
 
 const idGenJson = require('./woqlJson/woqlIdgenJson');
 const woqlStarJson = require('./woqlJson/woqlStarJson');
@@ -376,6 +376,96 @@ describe('woql queries', () => {
     expect(varsArr[0]).to.be.instanceof(Var);
   });
 
+  it('check the vars_unique method creates VarUnique instances', () => {
+    const varsArr = WOQL.vars_unique('A', 'B', 'C');
+
+    expect(varsArr[0]).to.be.instanceof(VarUnique);
+    expect(varsArr[1]).to.be.instanceof(VarUnique);
+    expect(varsArr[2]).to.be.instanceof(VarUnique);
+  });
+
+  it('check vars_unique creates unique variable names within a single call', () => {
+    const [a, b, c] = WOQL.vars_unique('A', 'B', 'C');
+
+    // Each variable should have a unique name
+    expect(a.name).to.not.equal(b.name);
+    expect(b.name).to.not.equal(c.name);
+    expect(a.name).to.not.equal(c.name);
+
+    // Each should contain the base name
+    expect(a.name).to.include('A');
+    expect(b.name).to.include('B');
+    expect(c.name).to.include('C');
+  });
+
+  it('check vars_unique creates unique variable names across multiple calls', () => {
+    const [a1] = WOQL.vars_unique('X');
+    const [a2] = WOQL.vars_unique('X');
+    const [a3] = WOQL.vars_unique('X');
+
+    // Variables with the same base name should still be unique
+    expect(a1.name).to.not.equal(a2.name);
+    expect(a2.name).to.not.equal(a3.name);
+    expect(a1.name).to.not.equal(a3.name);
+
+    // All should contain the base name 'X'
+    expect(a1.name).to.include('X');
+    expect(a2.name).to.include('X');
+    expect(a3.name).to.include('X');
+  });
+
+  it('check vars_unique appends incrementing counter', () => {
+    // Get the current counter value by creating a variable
+    const [v1] = WOQL.vars_unique('test');
+    const counter1 = v1.counter;
+
+    // Next variable should have counter + 1
+    const [v2] = WOQL.vars_unique('test');
+    expect(v2.counter).to.equal(counter1 + 1);
+
+    // And so on
+    const [v3] = WOQL.vars_unique('test');
+    expect(v3.counter).to.equal(counter1 + 2);
+  });
+
+  it('check vars_unique generates correct JSON with unique variable names', () => {
+    const [a, b] = WOQL.vars_unique('myvar', 'myvar');
+
+    const jsonA = a.json();
+    const jsonB = b.json();
+
+    expect(jsonA).to.have.property('@type', 'Value');
+    expect(jsonA).to.have.property('variable');
+    expect(jsonB).to.have.property('@type', 'Value');
+    expect(jsonB).to.have.property('variable');
+
+    // 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');
+  });
+
+  it('check vars still works exactly as before (no changes)', () => {
+    const [x, y, z] = WOQL.vars('X', 'Y', 'Z');
+
+    // Should create Var instances, not VarUnique
+    expect(x).to.be.instanceof(Var);
+    expect(x).to.not.be.instanceof(VarUnique);
+
+    // Names should be exactly as provided
+    expect(x.name).to.equal('X');
+    expect(y.name).to.equal('Y');
+    expect(z.name).to.equal('Z');
+
+    // Should not have counter property
+    expect(x).to.not.have.property('counter');
+
+    // Multiple calls with same names should produce identical variable names
+    const [x2] = WOQL.vars('X');
+    expect(x2.name).to.equal('X');
+    expect(x2.name).to.equal(x.name);
+  });
+
   it('check type_of(Var,Var)', () => {
     const TypeOf = WOQL.type_of('v:X', 'v:Y').json()
     expect(TypeOf).to.deep.eql({