Merge pull request #347 from hoijnet/woql/random-id-gen

Adding random id generation to WOQL JS

Author: hoijnet

integration_tests/woql_random_idgen.test.ts

@@ -0,0 +1,195 @@
+//@ts-check
+import { describe, expect, test, beforeAll, afterAll } from "@jest/globals";
+import { WOQLClient, WOQL } from "../index.js";
+import { DbDetails } from "../dist/typescript/lib/typedef.js";
+
+let client: WOQLClient;
+
+beforeAll(() => {
+  client = new WOQLClient("http://127.0.0.1:6363", {
+    user: "admin",
+    organization: "admin",
+    key: process.env.TDB_ADMIN_PASS ?? "root"
+  });
+});
+
+const testDb = "db__test_woql_random_idgen";
+
+describe("WOQL Random ID Generation", () => {
+  test("Setup: Create database and schema", async () => {
+    const dbObj: DbDetails = {
+      label: testDb,
+      comment: "Test database for random ID generation",
+      schema: true
+    };
+    const result = await client.createDatabase(testDb, dbObj);
+    expect(result["@type"]).toEqual("api:DbCreateResponse");
+
+    const schema = [
+      {
+        "@type": "Class",
+        "@id": "Person",
+        "@key": { "@type": "Random" },
+        name: "xsd:string"
+      }
+    ];
+
+    await client.addDocument(schema, { graph_type: "schema" });
+  });
+
+  test("Generate random ID using WOQL", async () => {
+    const query = WOQL.random_idgen("Person/", "v:person_id");
+
+    const result = await client.query(query);
+    expect(result?.bindings).toBeDefined();
+    expect(result?.bindings?.length).toBeGreaterThan(0);
+
+    // Server returns bindings without the 'v:' prefix
+    const binding = result?.bindings?.[0];
+    const personId = binding["person_id"] || binding["v:person_id"];
+    expect(personId).toBeDefined();
+    expect(personId).toContain("Person/");
+
+    // Should have a 16-character random suffix
+    const suffix = personId.split("Person/")[1];
+    expect(suffix.length).toBe(16);
+  });
+
+  test("Generate multiple unique IDs", async () => {
+    const query = WOQL.and(
+      WOQL.random_idgen("Person/", "v:id1"),
+      WOQL.random_idgen("Person/", "v:id2"),
+      WOQL.random_idgen("Person/", "v:id3")
+    );
+
+    const result = await client.query(query);
+    expect(result?.bindings).toBeDefined();
+    expect(result?.bindings?.length).toBe(1);
+
+    const binding = result?.bindings?.[0];
+    const id1 = binding["id1"] || binding["v:id1"];
+    const id2 = binding["id2"] || binding["v:id2"];
+    const id3 = binding["id3"] || binding["v:id3"];
+
+    // All IDs should be different
+    expect(id1).not.toEqual(id2);
+    expect(id1).not.toEqual(id3);
+    expect(id2).not.toEqual(id3);
+
+    // All should start with prefix
+    expect(id1).toContain("Person/");
+    expect(id2).toContain("Person/");
+    expect(id3).toContain("Person/");
+  });
+
+  test("Use random ID to create document", async () => {
+    //Generate random ID
+    const query = WOQL.random_idgen("Person/", "v:new_person");
+
+    const result = await client.query(query);
+    expect(result?.bindings).toBeDefined();
+
+    const binding = result?.bindings?.[0];
+    const personId = binding["new_person"] || binding["v:new_person"];
+    expect(personId).toBeDefined();
+    expect(personId).toContain("Person/");
+
+    // Create the document using the generated ID
+    const doc = {
+      "@type": "Person",
+      "@id": personId,
+      name: "Alice"
+    };
+
+    await client.addDocument(doc);
+
+    // Verify the document was created
+    const retrieved: any = await client.getDocument({ id: personId });
+    expect(retrieved["@id"]).toEqual(personId);
+    expect(retrieved.name).toEqual("Alice");
+  });
+
+  test("Generate different IDs on repeated query execution", async () => {
+    const query = WOQL.random_idgen("Data/", "v:id");
+    const ids = new Set<string>();
+
+    for (let i = 0; i < 10; i++) {
+      const result = await client.query(query);
+      const binding = result?.bindings?.[0];
+      const id = binding["id"] || binding["v:id"];
+      ids.add(id);
+    }
+
+    // All 10 executions should produce unique IDs
+    expect(ids.size).toBe(10);
+  });
+
+  test("Mix WOQL builder with raw JSON-LD", async () => {
+    // Test mixing WOQL builder syntax with raw JSON-LD
+    // This verifies the pattern documented in woql-json-ld-queries guide
+    const query1 = WOQL.and(
+      WOQL.random_idgen("Test/", "v:test_id"),
+      {
+        "@type": "LexicalKey",
+        base: {
+          "@type": "DataValue",
+          data: {
+            "@type": "xsd:string",
+            "@value": "Display/"
+          }
+        },
+        key_list: [],
+        uri: {
+          "@type": "NodeValue",
+          variable: "out"
+        }
+      } as any
+    );
+
+    const result1 = await client.query(query1);
+    const binding1 = result1?.bindings?.[0];
+    
+    // Verify random_idgen result
+    const id1 = binding1["test_id"] || binding1["v:test_id"];
+    expect(id1).toBeDefined();
+    expect(id1).toContain("Test/");
+    
+    // Verify the ID has correct 16-character suffix
+    const suffix = id1.split("Test/")[1];
+    expect(suffix.length).toBe(16);
+    
+    // Verify LexicalKey result (empty key_list generates just the base)
+    const out = binding1["out"] || binding1["v:out"];
+    expect(out).toBeDefined();
+    expect(out).toContain("Display/");
+  });
+
+  test("Both random_idgen and idgen_random aliases work", async () => {
+    // Test random_idgen alias
+    const query1 = WOQL.random_idgen("Test/", "v:test_id");
+    const result1 = await client.query(query1);
+    const binding1 = result1?.bindings?.[0];
+    const id1 = binding1["test_id"] || binding1["v:test_id"];
+    expect(id1).toBeDefined();
+    expect(id1).toContain("Test/");
+
+    // Test idgen_random alias (should produce same structure)
+    const query2 = WOQL.idgen_random("Test/", "v:test_id");
+    const result2 = await client.query(query2);
+    const binding2 = result2?.bindings?.[0];
+    const id2 = binding2["test_id"] || binding2["v:test_id"];
+    expect(id2).toBeDefined();
+    expect(id2).toContain("Test/");
+
+    // Both queries should produce the same JSON structure (same variable name)
+    expect(query1.json()).toEqual(query2.json());
+  });
+
+  afterAll(async () => {
+    try {
+      await client.deleteDatabase(testDb);
+    } catch (e) {
+      // Ignore errors
+    }
+  });
+});

lib/query/woqlQuery.js

@@ -1175,6 +1175,29 @@ WOQLQuery.prototype.idgen = function (prefix, inputVarList, outputVar) {
 
 WOQLQuery.prototype.idgenerator = WOQLQuery.prototype.idgen;
 
+/**
+ * Generates a random ID with a specified prefix
+ * Uses cryptographically secure random base64 encoding to generate unique identifiers
+ * @param {string} prefix - prefix for the generated ID
+ * @param {string} outputVar - variable that stores the generated ID
+ * @returns {WOQLQuery} A WOQLQuery which contains the random ID generation pattern
+ * @example
+ * idgen_random("Person/", "v:person_id")
+ */
+WOQLQuery.prototype.idgen_random = function (prefix, outputVar) {
+  if (this.cursor['@type']) this.wrapCursorWithAnd();
+  this.cursor['@type'] = 'RandomKey';
+  this.cursor.base = this.cleanDataValue(prefix, 'xsd:string');
+  this.cursor.uri = this.cleanNodeValue(outputVar);
+  return this;
+};
+
+/**
+ * Backward-compatible alias for idgen_random
+ * @deprecated Use idgen_random instead
+ */
+WOQLQuery.prototype.random_idgen = WOQLQuery.prototype.idgen_random;
+
 /**
  * Changes a string to upper-case
  * @param {string|Var} inputVarName - string or variable representing the uncapitalized string

lib/woql.js

@@ -752,6 +752,30 @@ WOQL.idgenerator = function (prefix, inputVarList, resultVarName) {
   return new WOQLQuery().idgen(prefix, inputVarList, resultVarName);
 };
 
+/**
+ * Generates a random ID with a specified prefix
+ * @param {string} prefix - prefix for the generated ID
+ * @param {string} resultVarName - variable that stores the generated ID
+ * @returns {WOQLQuery} A WOQLQuery object containing the random ID generation function
+ * @example
+ * let [newid] = vars("newid")
+ * idgen_random("Person/", newid)
+ */
+WOQL.idgen_random = function (prefix, resultVarName) {
+  return new WOQLQuery().idgen_random(prefix, resultVarName);
+};
+
+/**
+ * Backward-compatible alias for idgen_random
+ * @deprecated Use idgen_random instead
+ * @param {string} prefix - prefix for the generated ID
+ * @param {string} resultVarName - variable that stores the generated ID
+ * @returns {WOQLQuery} A WOQLQuery object containing the random ID generation function
+ */
+WOQL.random_idgen = function (prefix, resultVarName) {
+  return new WOQLQuery().idgen_random(prefix, resultVarName);
+};
+
 /**
  *
  * Changes a string to upper-case

test/woql.spec.js

@@ -4,6 +4,7 @@ const WOQL = require('../lib/woql');
 const { Var, VarUnique, Vars } = require('../lib/query/woqlDoc');
 
 const idGenJson = require('./woqlJson/woqlIdgenJson');
+const randomKeyJson = require('./woqlJson/woqlRandomKeyJson');
 const woqlStarJson = require('./woqlJson/woqlStarJson');
 const woqlInsertJson = require('./woqlJson/woqlInsertJson');
 const woqlDoctypeJson = require('./woqlJson/woqlDoctypeJson');
@@ -285,6 +286,12 @@ describe('woql queries', () => {
     expect(woqlObject.json()).to.eql(idGenJson);
   });
 
+  it('check the idgen_random method', () => {
+    const woqlObject = WOQL.idgen_random('Person/', 'v:Person_ID');
+
+    expect(woqlObject.json()).to.eql(randomKeyJson);
+  });
+
   it('check the typecast method', () => {
     const woqlObject = WOQL.typecast('v:Duration', 'xsd:integer', 'v:Duration_Cast');
 

test/woqlJson/woqlRandomKeyJson.js

@@ -0,0 +1,11 @@
+module.exports = {
+  '@type': 'RandomKey',
+  base: {
+    '@type': 'DataValue',
+    data: { '@type': 'xsd:string', '@value': 'Person/' },
+  },
+  uri: {
+    '@type': 'NodeValue',
+    variable: 'Person_ID',
+  },
+};