From ef8000e9172726469c50e47e122d4fbf46840862 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Philippe=20H=C3=B6ij?= <philippe@hoij.net>
Date: Mon, 27 Apr 2026 05:46:03 +0200
Subject: [PATCH 1/2] Add upsert and merge_repeats behaviour to client

---
 lib/typedef.js | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/lib/typedef.js b/lib/typedef.js
index 190da8c..c0c318b 100644
--- a/lib/typedef.js
+++ b/lib/typedef.js
@@ -38,6 +38,10 @@ const { ACTIONS } = Utils.ACTIONS;
  *@property {boolean} [full_replace] - default is false, If true, all existing documents are deleted
  before inserting the posted documents. This allows the full replacement of the contents of a
  database. This is especially useful for replacing the schema.
+ *@property {boolean} [overwrite] - default is false, If true, existing documents with the same
+ ID will be overwritten instead of causing an error. This enables upsert behavior.
+ *@property {boolean} [merge_repeats] - default is false, If true, duplicate document IDs
+ in the same request are silently accepted instead of causing an error.
  */
 
 /**
@@ -49,6 +53,8 @@ const { ACTIONS } = Utils.ACTIONS;
  a new document if it doesn't exist.
  *@property {GraphType} [graph_type] - default is instance, instance|schema Used to switch between
  getting documents from the instance or the schema graph.
+ *@property {boolean} [merge_repeats] - default is false, If true, duplicate document IDs
+ in the same request are silently accepted instead of causing an error.
  */
 
 /**

From 5ef94bff1170e6f927a089593950ba7b57b68c13 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Philippe=20H=C3=B6ij?= <philippe@hoij.net>
Date: Mon, 27 Apr 2026 21:17:44 +0200
Subject: [PATCH 2/2] Significant documentation update for classes

---
 lib/query/woqlQuery.js | 425 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 412 insertions(+), 13 deletions(-)

diff --git a/lib/query/woqlQuery.js b/lib/query/woqlQuery.js
index 33b2526..31f150b 100644
--- a/lib/query/woqlQuery.js
+++ b/lib/query/woqlQuery.js
@@ -191,6 +191,13 @@ class WOQLQuery extends WOQLCore {
  * @param {string} IRI -  The document id  or a variable to read
  * @param {string} output - Variable which will be bound to the document.
  * @return {WOQLQuery} WOQLQuery
+ * @example
+ * let [person] = vars("Person")
+ * const query = WOQL.read_document(
+ *      "Person/0b4feda109d9d13c9da809090b342ad9e4d8185545ce05f7cd20b97fe458f547",
+ *     person
+ * );
+ * const res =  await client.query(query);
  */
 WOQLQuery.prototype.read_document = function (IRI, output) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -206,6 +213,10 @@ WOQLQuery.prototype.read_document = function (IRI, output) {
  * have a class specified key.
  * @param {string} [IRI] - An optional identifier specifying the document location.
  * @return {WOQLQuery} WOQLQuery
+ * @example
+ * const res = await client.query(
+ *    WOQL.insert_document(WOQL.doc({ "@type" : "Person", "label": "John" }))
+ * )
  */
 
 WOQLQuery.prototype.insert_document = function (docjson, IRI) {
@@ -274,6 +285,9 @@ WOQLQuery.prototype.wrapCursorWithAnd = function () {
  * @param {string}  refPath  - path to specific reference Id or commit Id
  * @param {WOQLQuery} [subquery] - subquery for the specific commit point
  * @returns {WOQLQuery}
+ * @example
+ * let [a, b, c] = vars("a", "b", "c")
+ * WOQL.using("userName/dbName/local/commit|branch/commitID|branchname").triple(a, b, c)
  */
 
 WOQLQuery.prototype.using = function (refPath, subquery) {
@@ -306,6 +320,9 @@ WOQLQuery.prototype.comment = function (comment, subquery) {
  * Filters the query so that only the variables included in [V1...Vn] are returned in the bindings
  * @param {...string|...Var} varNames - only these variables are returned
  * @returns {WOQLQuery}
+ * @example
+ * let [a, b, c] = vars("a", "b", "c")
+ * WOQL.select(a, triple(a, b, c))
  */
 
 WOQLQuery.prototype.select = function (...varNames) {
@@ -432,6 +449,14 @@ WOQLQuery.prototype.distinct = function (...varNames) {
 * Logical conjunction of the contained queries - all queries must match or the entire clause fails
 * @param {...WOQLQuery} subqueries - A list of one or more woql queries to execute as a conjunction
 * @returns {WOQLQuery} - A WOQLQuery object containing the conjunction of queries
+* @example
+* //find triples that are of type scm:Journey, and have
+* //a start_station Start, and that start_station is labeled Start_Label
+* let [Journey, Start, Start_Label] = vars("Journey", "Start", "Start_Label")
+* WOQL.and(
+*      WOQL.triple(Journey, "rdf:type", "@schema:Journey"),
+*      WOQL.triple(Journey, "start_station", Start),
+*      WOQL.triple(Start, "label", Start_Label))
 */
 
 WOQLQuery.prototype.and = function (...subqueries) {
@@ -467,6 +492,12 @@ WOQLQuery.prototype.and = function (...subqueries) {
  * @param {...WOQLQuery} subqueries - A list of one or more woql queries
  * to execute as alternatives
  * @returns {WOQLQuery} - A WOQLQuery object containing the logical Or of the subqueries
+ * @example
+ * let [Subject] = vars("Subject")
+ * or(
+ *   triple(Subject, 'label', "A"),
+ *   triple(Subject, "label", "a")
+ *  )
  */
 
 WOQLQuery.prototype.or = function (...subqueries) {
@@ -510,6 +541,10 @@ WOQLQuery.prototype.from = function (graphRef, query) {
  * @param {typedef.GraphRef} graphRef- A valid graph resource identifier string
  * @param {WOQLQuery} [subquery] - The query which will be written into the graph
  * @returns {WOQLQuery} A WOQLQuery which will be written into the graph in question
+ * @example
+ * //Subq is an argument or a chained query
+ * using("admin/minecraft").into("instance/main").add_triple("a", "rdf:type", "@schema:X")
+ * //writes a single tripe (doc:a, rdf:type, scm:X) into the main instance graph
  */
 
 WOQLQuery.prototype.into = function (graphRef, subquery) {
@@ -532,6 +567,9 @@ WOQLQuery.prototype.into = function (graphRef, subquery) {
  * @param {string|Var} predicate - The IRI of a property or a variable
  * @param {string|Var} object - The IRI of a node or a variable, or a literal
  * @returns {WOQLQuery}
+ * @example
+ * triple("v:subject", "v:predicate", "v:object");
+ * // Matches when the variables are set, and queries variables that are not set
  */
 
 WOQLQuery.prototype.triple = function (subject, predicate, object) {
@@ -555,6 +593,15 @@ WOQLQuery.prototype.triple = function (subject, predicate, object) {
  * @param {object} low - The inclusive lower bound as a typed value, e.g. literal(10, "integer")
  * @param {object} high - The exclusive upper bound as a typed value, e.g. literal(100, "integer")
  * @returns {WOQLQuery}
+ * @example
+ * triple_slice(
+ *   "v:subject",
+ *   "v:predicate",
+ *   "v:object",
+ *   literal(10, "integer"),
+ *   literal(100, "integer")
+ * );
+ * // Queries the range of values with very high performance thanks to succinct data structures
  */
 WOQLQuery.prototype.triple_slice = function (subject, predicate, object, low, high) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -577,6 +624,16 @@ WOQLQuery.prototype.triple_slice = function (subject, predicate, object, low, hi
  * @param {object} high - The exclusive upper bound as a typed value
  * @param {typedef.GraphRef} graphRef - A valid graph resource identifier string
  * @returns {WOQLQuery}
+ * @example
+ * quad_slice(
+ *   "v:subject",
+ *   "v:predicate",
+ *   "v:object",
+ *   literal(10, "integer"),
+ *   literal(100, "integer"),
+ *   "v:graph"
+ * );
+ * // Queries the range of values with very high performance thanks to succinct data structures
  */
 WOQLQuery.prototype.quad_slice = function (subject, predicate, object, low, high, graphRef) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -597,6 +654,16 @@ WOQLQuery.prototype.quad_slice = function (subject, predicate, object, low, high
  * @param {object} low - The inclusive lower bound as a typed value
  * @param {object} high - The exclusive upper bound as a typed value
  * @returns {WOQLQuery}
+ * @example
+ * triple_slice_rev(
+ *   "v:subject",
+ *   "v:predicate",
+ *   "v:object",
+ *   literal(10, "integer"),
+ *   literal(100, "integer")
+ * );
+ * // Queries the range of values with very high performance thanks to succinct data structures,
+ * and retrieves in reverse order
  */
 WOQLQuery.prototype.triple_slice_rev = function (subject, predicate, object, low, high) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -619,6 +686,16 @@ WOQLQuery.prototype.triple_slice_rev = function (subject, predicate, object, low
  * @param {object} high - The exclusive upper bound as a typed value
  * @param {typedef.GraphRef} graphRef - A valid graph resource identifier string
  * @returns {WOQLQuery}
+ * @example
+ * quad_slice_rev(
+ *   "v:subject",
+ *   "v:predicate",
+ *   "v:object",
+ *   literal(10, "integer"),
+ *   literal(100, "integer"),
+ *   "v:graph"
+ * );
+ * // Queries the range of values with very high performance thanks to succinct data structures
  */
 WOQLQuery.prototype.quad_slice_rev = function (subject, predicate, object, low, high, graphRef) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -638,6 +715,9 @@ WOQLQuery.prototype.quad_slice_rev = function (subject, predicate, object, low,
  * @param {string|Var} object - The current object value or a variable
  * @param {object|Var} next - The next object value or a variable
  * @returns {WOQLQuery}
+ * @example
+ * triple_next("v:subject", "v:predicate", "v:object", "v:next");
+ * // This is very helpful for navigating the stored triples fast
  */
 WOQLQuery.prototype.triple_next = function (subject, predicate, object, next) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -657,6 +737,9 @@ WOQLQuery.prototype.triple_next = function (subject, predicate, object, next) {
  * @param {object|Var} next - The next object value or a variable
  * @param {typedef.GraphRef} graphRef - A valid graph resource identifier string
  * @returns {WOQLQuery}
+ * @example
+ * quad_next("v:subject", "v:predicate", "v:object", "v:next", "v:graph");
+ * // This is very helpful for navigating the stored triples fast in a graph
  */
 WOQLQuery.prototype.quad_next = function (subject, predicate, object, next, graphRef) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -676,6 +759,9 @@ WOQLQuery.prototype.quad_next = function (subject, predicate, object, next, grap
  * @param {string|Var} object - The current object value or a variable
  * @param {object|Var} previous - The previous object value or a variable
  * @returns {WOQLQuery}
+ * @example
+ * triple_previous("v:subject", "v:predicate", "v:object", "v:previous");
+ * // This is very helpful for navigating the stored triples backwards
  */
 WOQLQuery.prototype.triple_previous = function (subject, predicate, object, previous) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -695,6 +781,9 @@ WOQLQuery.prototype.triple_previous = function (subject, predicate, object, prev
  * @param {object|Var} previous - The previous object value or a variable
  * @param {typedef.GraphRef} graphRef - A valid graph resource identifier string
  * @returns {WOQLQuery}
+ * @example
+ * quad_previous("v:subject", "v:predicate", "v:object", "v:previous", "v:graph");
+ * // This is very helpful for navigating the stored triples backwards in a graph
  */
 WOQLQuery.prototype.quad_previous = function (subject, predicate, object, previous, graphRef) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -712,6 +801,9 @@ WOQLQuery.prototype.quad_previous = function (subject, predicate, object, previo
  * @param {string|Var} predicate - The IRI of a property or a variable
  * @param {string|Var} object - The IRI of a node or a variable, or a literal
  * @returns {WOQLQuery}
+ * @example
+ * added_triple("v:subject", "v:predicate", "v:object");
+ * // This helps to find which triples were added to the currently stored layer
  */
 
 WOQLQuery.prototype.added_triple = function (subject, predicate, object) {
@@ -727,11 +819,14 @@ WOQLQuery.prototype.added_triple = function (subject, predicate, object) {
 
 /**
  * Creates a triple pattern matching rule for the triple [S, P, O] (Subject, Predicate,
- * Object) added in the current commit
+ * Object) removed in the current commit
  * @param {string|Var} subject - The IRI of a triple’s subject or a variable
  * @param {string|Var} predicate - The IRI of a property or a variable
  * @param {string|Var} object - The IRI of a node or a variable, or a literal
  * @returns {WOQLQuery}
+ * @example
+ * removed_triple("v:subject", "v:predicate", "v:object");
+ * // This helps to find which triples were removed from the currently stored layer
  */
 
 WOQLQuery.prototype.removed_triple = function (subject, predicate, object) {
@@ -785,6 +880,9 @@ WOQLQuery.prototype.value = function (subject, predicate, objValue) {
  * @param {string|Var} object - The IRI of a node or a variable, or a literal
  * @param {typedef.GraphRef} graphRef - A valid graph resource identifier string
  * @returns {WOQLQuery}
+ * @example
+ * quad("v:subject", "v:predicate", "v:object", "v:graph");
+ * // This helps to find triples in a specific graph (such as the "schema" graph)
  */
 
 WOQLQuery.prototype.quad = function (subject, predicate, object, graphRef) {
@@ -806,6 +904,9 @@ WOQLQuery.prototype.quad = function (subject, predicate, object, graphRef) {
  * @param {string|Var} object - The IRI of a node or a variable, or a literal
  * @param {typedef.GraphRef} graphRef- A valid graph resource identifier string
  * @returns {WOQLQuery}
+ * @example
+ * added_quad("v:subject", "v:predicate", "v:object", "v:graph");
+ * // This helps to find which quads were added to the currently stored layer
  */
 
 WOQLQuery.prototype.added_quad = function (subject, predicate, object, graphRef) {
@@ -827,6 +928,9 @@ WOQLQuery.prototype.added_quad = function (subject, predicate, object, graphRef)
  * @param {string|Var} object - The IRI of a node or a variable, or a literal
  * @param {typedef.GraphRef} graphRef- A valid graph resource identifier string
  * @returns {WOQLQuery}
+ * @example
+ * removed_quad("v:subject", "v:predicate", "v:object", "v:graph");
+ * // This helps to find which quads were removed from the currently stored layer
  */
 
 WOQLQuery.prototype.removed_quad = function (subject, predicate, object, graphRef) {
@@ -844,7 +948,10 @@ WOQLQuery.prototype.removed_quad = function (subject, predicate, object, graphRe
  * Returns true if ClassA subsumes ClassB, according to the current DB schema
  * @param {string} classA - ClassA
  * @param {string} classB - ClassB
- * @returns {boolean} WOQLQuery
+ * @returns {WOQLQuery} WOQLQuery
+ * @example
+ * sub("v:classA", "v:classB");
+ * // This helps to find if classA subsumes classB (classA is more specific than class B)
  */
 WOQLQuery.prototype.sub = function (classA, classB) {
   if (!classA || !classB) return this.parameterError('Subsumption takes two parameters, both URIs');
@@ -862,6 +969,9 @@ WOQLQuery.prototype.subsumption = WOQLQuery.prototype.sub;
  * @param {string|number|boolean|array|Var} varName - literal, variable, array, or id
  * @param {string|number|boolean|array|Var} varValue - literal, variable, array, or id
  * @returns {WOQLQuery}
+ * @example
+ * eq("v:varName", "v:varValue");
+ * // This helps to match if varName is equal to varValue
  */
 WOQLQuery.prototype.eq = function (varName, varValue) {
   // if (a && a === 'args') return ['left', 'right']
@@ -876,13 +986,17 @@ WOQLQuery.prototype.eq = function (varName, varValue) {
 WOQLQuery.prototype.equals = WOQLQuery.prototype.eq;
 
 /**
- * Substring
+ * Substring of string
  * @param {string|Var} string - String or variable
  * @param {number|Var} before - integer or variable (characters from start to begin)
  * @param {number|Var} [length] - integer or variable (length of substring)
  * @param {number|Var} [after] - integer or variable (number of characters after substring)
  * @param {string|Var} [subString] - String or variable
  * @returns {WOQLQuery}
+ * @example
+ * let [after, result] = vars("after", "result")
+ * substr("joe", 1, 2, after, result)
+ * //result is "oe", after is 2
  */
 WOQLQuery.prototype.substr = function (string, before, length, after, subString) {
   // if (String && String === 'args')
@@ -920,6 +1034,8 @@ WOQLQuery.prototype.substring = WOQLQuery.prototype.substr;
  * @param {Vars | array<Var>} asvars - an array of AsVar variable mappings (see as for format below)
  * @param {WOQLQuery} queryResource - an external resource (remote, file, post) to query
  * @returns {WOQLQuery} A WOQLQuery which contains the get expression
+ * get(as("Name", "v:name").as("Label", "v:label")).post("file.csv",{"type":"csv"}, "post")
+ * // map the column Name to variable name, Label>label, from the attached csv file "file.csv"
  */
 WOQLQuery.prototype.get = function (asvars, queryResource) {
   this.cursor['@type'] = 'Get';
@@ -971,6 +1087,9 @@ WOQLQuery.prototype.put = function (varsToExp, query, fileResource) {
 /**
  * @param {...(array|string|Var)} varList variable number of arguments
  * @returns WOQLQuery
+ * @example
+ * get(as("Name", "v:name").as("Label", "v:label")).post("file.csv",{"type":"csv"}, "post")
+ * // map the column Name to variable name, Label>label, from the attached csv file "file.csv"
  */
 WOQLQuery.prototype.as = function (...varList) {
   // if (varList && varList[0] == 'args')
@@ -1032,12 +1151,15 @@ WOQLQuery.prototype.remote = function (remoteObj, formatObj) {
 };
 
 /**
- * Identifies a resource as a local path on the client, to be sent to the server through a
+ * Identifies a resource attached to the POST request or
+ * a local path on the client, to be sent to the server through a
  * HTTP POST request, with the format defined through the options
  * @param {string} url - The Path on the server at which the file resource can be accessed
  * @param {typedef.DataFormatObj} [formatObj] - imput options, optional
  * @param {string} [source] - It defines the source of the file, it can be 'url','post'
  * @returns {WOQLQuery} A WOQLQuery which contains the Post resource identifier
+ * get(as("Name", "v:name").as("Label", "v:label")).post("file.csv",{"type":"csv"}, "post")
+ * // map the column Name to variable name, Label>label, from the attached csv file "file.csv"
  */
 
 WOQLQuery.prototype.post = function (url, formatObj, source = 'post') {
@@ -1057,6 +1179,8 @@ WOQLQuery.prototype.post = function (url, formatObj, source = 'post') {
  * @param {string|Var} predicate - The IRI of a property or a variable
  * @param {string|Var} object - The IRI of a node or a variable, or a literal
  * @returns {WOQLQuery} - A WOQLQuery which contains the Triple Deletion statement
+ * @example
+ * delete_triple("john", "age", 42)
  */
 
 WOQLQuery.prototype.delete_triple = function (subject, predicate, object) {
@@ -1072,6 +1196,8 @@ WOQLQuery.prototype.delete_triple = function (subject, predicate, object) {
  * @param {string|Var} predicate - The IRI of a property or a variable
  * @param {string|Var} object - The IRI of a node or a variable, or a literal
  * @returns {WOQLQuery}
+ * @example
+ * add_triple("john", "age", 42)
  */
 
 WOQLQuery.prototype.add_triple = function (subject, predicate, object) {
@@ -1088,6 +1214,8 @@ WOQLQuery.prototype.add_triple = function (subject, predicate, object) {
  * @param {string|Var} object - The IRI of a node or a variable, or a literal
  * @param {typedef.GraphRef} graphRef - A valid graph resource identifier string
  * @returns {WOQLQuery} - A WOQLQuery which contains the Delete Quad Statement
+ * @example remove the class Person from the schema graph
+ * WOQL.delete_quad("Person", "rdf:type", "sys:Class", "schema")
  */
 WOQLQuery.prototype.delete_quad = function (subject, predicate, object, graphRef) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -1110,6 +1238,8 @@ WOQLQuery.prototype.delete_quad = function (subject, predicate, object, graphRef
  * @param {string|Var} object - The IRI of a node or a variable, or a literal
  * @param {typedef.GraphRef} graphRef - A valid graph resource identifier string
  * @returns {WOQLQuery}
+ * @example
+ * add_quad("john", "age", 42, "schema")
  */
 
 WOQLQuery.prototype.add_quad = function (subject, predicate, object, graphRef) {
@@ -1128,6 +1258,10 @@ WOQLQuery.prototype.add_quad = function (subject, predicate, object, graphRef) {
  * @param {string|Var} resultVarName - A string or variable
  * containing the trimmed version of the string
  * @returns {WOQLQuery} A WOQLQuery which contains the Trim pattern matching expression
+ * @example
+ * let [trimmed] = vars("trimmed")
+ * trim("hello   ", trimmed)
+ * //trimmed contains "hello"
  */
 
 WOQLQuery.prototype.trim = function (inputStr, resultVarName) {
@@ -1140,9 +1274,15 @@ WOQLQuery.prototype.trim = function (inputStr, resultVarName) {
 
 /**
  * Evaluates the passed arithmetic expression and generates or matches the result value
- * @param {object| WOQLQuery | string} arithExp - query or JSON-LD representing the query
- * @param {string|Var} resultVarName - output variable
- * @returns {WOQLQuery}
+ * @param {object| WOQLQuery | string} arithExp - A WOQL query containing a valid WOQL Arithmetic
+ * Expression, which is evaluated by the function
+ * @param {string|number|Var} resultVarName - Either a variable, in which the result of the
+ * expression will be stored, or a numeric literal which will be used as a test of result of
+ * the evaluated expression
+ * @returns {WOQLQuery} A WOQLQuery which contains the Arithmetic function
+ * @example
+ * let [result] = vars("result")
+ * eval(plus(2, minus(3, 1)), result)
  */
 
 WOQLQuery.prototype.eval = function (arithExp, resultVarName) {
@@ -1155,11 +1295,15 @@ WOQLQuery.prototype.eval = function (arithExp, resultVarName) {
 
 /**
  * Evaluates the passed arithmetic expression and generates or matches the result value.
- * Alias for eval() to support both naming conventions in fluent/chained style.
- * @param {object|WOQLQuery|string} arithExp - A WOQL query containing a valid arithmetic expression
- * @param {string|number|Var} resultVarName - Either a variable to store the result, or a numeric
- * literal to test against the evaluated expression
- * @returns {WOQLQuery}
+ * @param {object|WOQLQuery|string} arithExp - A WOQL query containing a valid WOQL Arithmetic
+ * Expression, which is evaluated by the function
+ * @param {string|number|Var} resultVarName - Either a variable, in which the result of the
+ * expression will be stored, or a numeric literal which will be used as a test of result of
+ * the evaluated expression
+ * @returns {WOQLQuery} A WOQLQuery which contains the Arithmetic function
+ * @example
+ * let [result] = vars("result")
+ * evaluate(plus(2, minus(3, 1)), result)
  */
 
 WOQLQuery.prototype.evaluate = function (arithExp, resultVarName) {
@@ -1170,6 +1314,9 @@ WOQLQuery.prototype.evaluate = function (arithExp, resultVarName) {
  * Adds the numbers together
  * @param {...(string|number|Var)} args - a variable or numeric containing the values to add
  * @returns {WOQLQuery} A WOQLQuery which contains the addition expression
+ * @example
+ * let [result] = vars("result")
+ * evaluate(plus(2, plus(3, 1)), result)
  */
 
 WOQLQuery.prototype.plus = function (...args) {
@@ -1191,6 +1338,9 @@ WOQLQuery.prototype.plus = function (...args) {
  * @param {...(string|number|Var)} args - variable or numeric containing the value that will be
  * subtracted from
  * @returns {WOQLQuery} A WOQLQuery which contains the subtraction expression
+ * @example
+ * let [result] = vars("result")
+ * evaluate(minus(2.1, plus(0.2, 1)), result)
  */
 WOQLQuery.prototype.minus = function (...args) {
   // if (args && args[0] === 'args') return ['first', 'right']
@@ -1210,6 +1360,10 @@ WOQLQuery.prototype.minus = function (...args) {
  * Multiplies numbers N1...Nn together
  * @param {...(string|number|Var)} args - a variable or numeric containing the value
  * @returns {WOQLQuery} A WOQLQuery which contains the multiplication expression
+ * @example
+ * let [result] = vars("result")
+ * evaluate(times(10, minus(2.1, plus(0.2, 1))), result)
+ * //result contains 9.000000000000002
  */
 WOQLQuery.prototype.times = function (...args) {
   // if (args && args[0] === 'args') return ['first', 'right']
@@ -1228,6 +1382,10 @@ WOQLQuery.prototype.times = function (...args) {
  * Divides numbers N1...Nn by each other left, to right precedence
  * @param {...(string|number|Var )} args - numbers to tbe divided
  * @returns {WOQLQuery} A WOQLQuery which contains the division expression
+ * @example
+ * let [result] = vars("result")
+ * evaluate(divide(times(10, minus(2.1, plus(0.2, 1))), 10), result)
+ * //result contains 0.9000000000000001
  */
 WOQLQuery.prototype.divide = function (...args) {
   // if (args && args[0] === 'args') return ['left', 'right']
@@ -1246,6 +1404,10 @@ WOQLQuery.prototype.divide = function (...args) {
  * Division - integer division - args are divided left to right
  * @param {...(string|number|Var)} args - numbers for division
  * @returns {WOQLQuery} A WOQLQuery which contains the division expression
+ * @example
+ * let [result] = vars("result")
+ * evaluate(div(10, 3), result)
+ * //result contains 3
  */
 
 WOQLQuery.prototype.div = function (...args) {
@@ -1267,6 +1429,10 @@ WOQLQuery.prototype.div = function (...args) {
  * raised to the power of the second number
  * @param {number} expNum -  a variable or numeric containing the exponent
  * @returns {WOQLQuery} A WOQLQuery which contains the exponent expression
+ * @example
+ * let [result] = vars("result")
+ * evaluate(exp(3, 2), result)
+ * //result contains 9
  */
 WOQLQuery.prototype.exp = function (varNum, expNum) {
   // if (a && a === 'args') return ['left', 'right']
@@ -1281,6 +1447,10 @@ WOQLQuery.prototype.exp = function (varNum, expNum) {
  * Generates the nearest lower integer to the passed number
  * @param {string|number|Var} varNum - Variable or numeric containing the number to be floored
  * @returns {WOQLQuery} A WOQLQuery which contains the floor expression
+ * @example
+ * let [result] = vars("result")
+ * evaluate(divide(floor(times(10, minus(2.1, plus(0.2, 1)))), 10), result)
+ * //result contains 0.9 - floating point error removed
  */
 WOQLQuery.prototype.floor = function (varNum) {
   // if (a && a === 'args') return ['argument']
@@ -1295,6 +1465,9 @@ WOQLQuery.prototype.floor = function (varNum) {
  * @param {string|Var} instanceIRI - A string IRI or a variable that identify the class instance
  * @param {string|Var} classId - A Class IRI or a variable
  * @returns {WOQLQuery} A WOQLQuery object containing the type test
+ * @example
+ * let [subject] = vars("subject")
+ * isa(subject, "Person")
  */
 WOQLQuery.prototype.isa = function (instanceIRI, classId) {
   // if (a && a === 'args') return ['element', 'of_type']
@@ -1312,6 +1485,10 @@ WOQLQuery.prototype.isa = function (instanceIRI, classId) {
  * representing the other string to be compared
  * @param {number|string|Var} distance - variable representing the distance between the variables
  * @returns {WOQLQuery} A WOQLQuery which contains the Like pattern matching expression
+ * @example
+ * let [dist] = vars('dist')
+ * like("hello", "hallo", dist)
+ * //dist contains 0.7265420560747664
  */
 WOQLQuery.prototype.like = function (stringA, stringB, distance) {
   // if (a && a === 'args')
@@ -1332,6 +1509,13 @@ WOQLQuery.prototype.like = function (stringA, stringB, distance) {
  * the number to be compared
  * @param {string|number|Var} varNum02 - a variable or numeric containing the second comporator
  * @returns {WOQLQuery} A WOQLQuery which contains the comparison expression
+ * @example
+ * let [result, number] = vars("result", "number")
+ * and(
+ *   eq(number, 1.1),
+ *   less(number, 1.2).eq(result, literal(true, "boolean"))
+ * )
+ * //result contains true
  */
 WOQLQuery.prototype.less = function (varNum01, varNum02) {
   if (typeof varNum01 === 'undefined' || typeof varNum02 === 'undefined') return this.parameterError('Less takes two parameters');
@@ -1347,6 +1531,13 @@ WOQLQuery.prototype.less = function (varNum01, varNum02) {
  * @param {string|number|Var} varNum01 - a variable or numeric containing the number to be compared
  * @param {string|number|Var} varNum02 - a variable or numeric containing the second comporator
  * @returns {WOQLQuery} A WOQLQuery which contains the comparison expression
+ * @example
+ * let [result, number] = vars("result", "number")
+ * and(
+ *   eq(number, 1.2)
+ *   greater(number, 1.1).eq(result, literal(true, "boolean")),
+ * )
+ * //result contains true
  */
 WOQLQuery.prototype.greater = function (varNum01, varNum02) {
   if (typeof varNum01 === 'undefined' || typeof varNum02 === 'undefined') return this.parameterError('Greater takes two parameters');
@@ -1362,6 +1553,12 @@ WOQLQuery.prototype.greater = function (varNum01, varNum02) {
  * @param {string|number|Var} left - The greater value
  * @param {string|number|Var} right - The lesser value
  * @returns {WOQLQuery}
+ * @example
+ * let [result, number] = vars("result", "number")
+ * and(
+ *   eq(number, 1.2),
+ *   gt(number, 1.1).eq(result, literal(true, "boolean"))
+ * )
  */
 WOQLQuery.prototype.gt = WOQLQuery.prototype.greater;
 
@@ -1370,6 +1567,12 @@ WOQLQuery.prototype.gt = WOQLQuery.prototype.greater;
  * @param {string|number|Var} left - The lesser value
  * @param {string|number|Var} right - The greater value
  * @returns {WOQLQuery}
+ * @example
+ * let [result, number] = vars("result", "number")
+ * and(
+ *   eq(number, 1.1),
+ *   lt(number, 1.2).eq(result, literal(true, "boolean"))
+ * )
  */
 WOQLQuery.prototype.lt = WOQLQuery.prototype.less;
 
@@ -1378,6 +1581,12 @@ WOQLQuery.prototype.lt = WOQLQuery.prototype.less;
  * @param {string|number|Var} left - The greater or equal value
  * @param {string|number|Var} right - The lesser or equal value
  * @returns {WOQLQuery}
+ * @example
+ * let [result, number] = vars("result", "number")
+ * and(
+ *   eq(number, 1.2),
+ *   gte(number, 1.1).eq(result, literal(true, "boolean"))
+ * )
  */
 WOQLQuery.prototype.gte = function (left, right) {
   if (typeof left === 'undefined' || typeof right === 'undefined') return this.parameterError('Gte takes two parameters');
@@ -1393,6 +1602,12 @@ WOQLQuery.prototype.gte = function (left, right) {
  * @param {string|number|Var} left - The lesser or equal value
  * @param {string|number|Var} right - The greater or equal value
  * @returns {WOQLQuery}
+ * @example
+ * let [result, number] = vars("result", "number")
+ * and(
+ *   eq(number, 1.1),
+ *   lte(number, 1.2).eq(result, literal(true, "boolean"))
+ * )
  */
 WOQLQuery.prototype.lte = function (left, right) {
   if (typeof left === 'undefined' || typeof right === 'undefined') return this.parameterError('Lte takes two parameters');
@@ -1410,6 +1625,12 @@ WOQLQuery.prototype.lte = function (left, right) {
  * @param {string|number|Var} start - The inclusive lower bound
  * @param {string|number|Var} end - The exclusive upper bound
  * @returns {WOQLQuery}
+ * @example
+ * let [result, number] = vars("result", "number")
+ * and(
+ *   eq(number, 1.1),
+ *   in_range(number, 1.0, 2.0).eq(result, literal(true, "boolean"))
+ * )
  */
 WOQLQuery.prototype.in_range = function (value, start, end) {
   if (typeof value === 'undefined' || typeof start === 'undefined' || typeof end === 'undefined') return this.parameterError('InRange takes three parameters');
@@ -1424,12 +1645,19 @@ WOQLQuery.prototype.in_range = function (value, start, end) {
 /**
  * Generates a sequence of values in the half-open range [start, end).
  * When value is unbound, produces each value via backtracking.
+ * Can also be used for matching
  * @param {string|number|Var} value - The generated sequence value (or variable)
  * @param {string|number|Var} start - The inclusive start of the sequence
  * @param {string|number|Var} end - The exclusive end of the sequence
  * @param {string|number|Var} [step] - Optional increment per step
  * @param {string|number|Var} [count] - Optional total count
  * @returns {WOQLQuery}
+ * @example
+ * let [result] = vars("result")
+ * and(
+ *   sequence(number, 1.0, 2.0, 0.1).eq(result, literal(true, "boolean"))
+ * )
+ * // solutions where number as 1.0, 1.1, ... , 1.9 get generated
  */
 WOQLQuery.prototype.sequence = function (value, start, end, step, count) {
   if (typeof value === 'undefined' || typeof start === 'undefined' || typeof end === 'undefined') return this.parameterError('Sequence takes at least three parameters');
@@ -1452,6 +1680,10 @@ WOQLQuery.prototype.sequence = function (value, start, end, step, count) {
  * @param {string|object|Var} yearMonth - A gYearMonth value or variable
  * @param {string|object|Var} date - The resulting xsd:date (or variable)
  * @returns {WOQLQuery}
+ * @example
+ * month_start_date("2025-01", "v:date");
+ * // "v:..." indicates date is a variable
+ * // date returns 2025-01-01
  */
 WOQLQuery.prototype.month_start_date = function (yearMonth, date) {
   if (typeof yearMonth === 'undefined' || typeof date === 'undefined') return this.parameterError('MonthStartDate takes two parameters');
@@ -1467,6 +1699,10 @@ WOQLQuery.prototype.month_start_date = function (yearMonth, date) {
  * @param {string|object|Var} yearMonth - A gYearMonth value or variable
  * @param {string|object|Var} date - The resulting xsd:date (or variable)
  * @returns {WOQLQuery}
+ * @example
+ * // "v:..." indicates date is a variable
+ * month_end_date(literal("2000-02","xsd:gYearMonth"),"v:date")
+ * // date returns 2000-02-29
  */
 WOQLQuery.prototype.month_end_date = function (yearMonth, date) {
   if (typeof yearMonth === 'undefined' || typeof date === 'undefined') return this.parameterError('MonthEndDate takes two parameters');
@@ -1483,6 +1719,7 @@ WOQLQuery.prototype.month_end_date = function (yearMonth, date) {
  * @param {string|object|Var} start - The inclusive start date
  * @param {string|object|Var} end - The exclusive end date
  * @returns {WOQLQuery}
+ * month_start_dates("v:date", literal("2000-01-01", "xsd:date"), literal("2001-01-01", "xsd:date"))
  */
 WOQLQuery.prototype.month_start_dates = function (date, start, end) {
   if (typeof date === 'undefined' || typeof start === 'undefined' || typeof end === 'undefined') return this.parameterError('MonthStartDates takes three parameters');
@@ -1500,6 +1737,8 @@ WOQLQuery.prototype.month_start_dates = function (date, start, end) {
  * @param {string|object|Var} start - The inclusive start date
  * @param {string|object|Var} end - The exclusive end date
  * @returns {WOQLQuery}
+ * month_end_dates("v:date", literal("2000-01-01", "xsd:date"), literal("2001-01-01", "xsd:date"))
+ * // 2000-01-31, 2000-02-29, ... ,  2000-12-31
  */
 WOQLQuery.prototype.month_end_dates = function (date, start, end) {
   if (typeof date === 'undefined' || typeof start === 'undefined' || typeof end === 'undefined') return this.parameterError('MonthEndDates takes three parameters');
@@ -1520,6 +1759,8 @@ WOQLQuery.prototype.month_end_dates = function (date, start, end) {
  * @param {string|number|object|Var} yStart - Inclusive start of interval Y
  * @param {string|number|object|Var} yEnd - Exclusive end of interval Y
  * @returns {WOQLQuery}
+ * interval_relation("v:rel", "2000-01-01", "2001-01-01", "2000-06-01", "2000-12-31")
+ * // "contains"
  */
 WOQLQuery.prototype.interval_relation = function (relation, xStart, xEnd, yStart, yEnd) {
   if (typeof relation === 'undefined' || typeof xStart === 'undefined' || typeof xEnd === 'undefined' || typeof yStart === 'undefined' || typeof yEnd === 'undefined') return this.parameterError('IntervalRelation takes five parameters');
@@ -1540,6 +1781,12 @@ WOQLQuery.prototype.interval_relation = function (relation, xStart, xEnd, yStart
  * @param {string|object|Var} x - First xdd:dateTimeInterval value
  * @param {string|object|Var} y - Second xdd:dateTimeInterval value
  * @returns {WOQLQuery}
+ * interval_relation_typed(
+ *   "v:rel",
+ *   literal("2000-01-01T00:00:00/2001-01-01T00:00:00","xdd:dateTimeInterval"),
+ *   literal("2000-06-01T00:00:00/2000-12-31T23:59:59", "xdd:dateTimeInterval")
+ * )
+ * // "contains"
  */
 WOQLQuery.prototype.interval_relation_typed = function (relation, x, y) {
   if (typeof relation === 'undefined' || typeof x === 'undefined' || typeof y === 'undefined') return this.parameterError('IntervalRelationTyped takes three parameters');
@@ -1557,6 +1804,8 @@ WOQLQuery.prototype.interval_relation_typed = function (relation, x, y) {
  * @param {Array|object|Var} list - The list of values
  * @param {string|object|Var} result - Variable or value for the minimum
  * @returns {WOQLQuery}
+ * range_min([1, 2, 3], "v:min")
+ * // "1"
  */
 WOQLQuery.prototype.range_min = function (list, result) {
   if (typeof list === 'undefined' || typeof result === 'undefined') return this.parameterError('RangeMin takes two parameters');
@@ -1573,6 +1822,8 @@ WOQLQuery.prototype.range_min = function (list, result) {
  * @param {Array|object|Var} list - The list of values
  * @param {string|object|Var} result - Variable or value for the maximum
  * @returns {WOQLQuery}
+ * range_max([1, 2, 3], "v:max")
+ * // "3"
  */
 WOQLQuery.prototype.range_max = function (list, result) {
   if (typeof list === 'undefined' || typeof result === 'undefined') return this.parameterError('RangeMax takes two parameters');
@@ -1589,6 +1840,8 @@ WOQLQuery.prototype.range_max = function (list, result) {
  * @param {string|object|Var} end - Exclusive end date
  * @param {string|object|Var} interval - The interval value
  * @returns {WOQLQuery}
+ * interval(literal("2000-01-01", "xsd:date"), literal("2001-01-01", "xsd:date"), "v:interval")
+ * // "2000-01-01/2001-01-01"
  */
 WOQLQuery.prototype.interval = function (start, end, interval) {
   if (typeof start === 'undefined' || typeof end === 'undefined'
@@ -1609,6 +1862,12 @@ WOQLQuery.prototype.interval = function (start, end, interval) {
  * @param {string|object|Var} duration - The xsd:duration between start and end
  * @param {string|object|Var} interval - The xdd:dateTimeInterval value
  * @returns {WOQLQuery}
+ * interval_start_duration(
+ *   literal("2000-01-01", "xsd:date"),
+ *   literal("P1Y", "xsd:duration"),
+ *   "v:interval"
+ * )
+ * // "2000-01-01/2001-01-01"
  */
 WOQLQuery.prototype.interval_start_duration = function (start, duration, interval) {
   if (typeof start === 'undefined' || typeof duration === 'undefined'
@@ -1629,6 +1888,12 @@ WOQLQuery.prototype.interval_start_duration = function (start, duration, interva
  * @param {string|object|Var} end - Exclusive end date or dateTime
  * @param {string|object|Var} interval - The xdd:dateTimeInterval value
  * @returns {WOQLQuery}
+ * interval_duration_end(
+ *   literal("P1Y", "xsd:duration"),
+ *   literal("2001-01-01", "xsd:date"),
+ *   "v:interval"
+ * )
+ * // "P1Y/2001-01-01"
  */
 WOQLQuery.prototype.interval_duration_end = function (duration, end, interval) {
   if (typeof duration === 'undefined' || typeof end === 'undefined'
@@ -1648,6 +1913,8 @@ WOQLQuery.prototype.interval_duration_end = function (duration, end, interval) {
  * @param {string|object|Var} date - The input date
  * @param {string|object|Var} next - The next calendar day
  * @returns {WOQLQuery}
+ * day_after(literal("2000-02-28", "xsd:date"), "v:next")
+ * // "2000-02-29"
  */
 WOQLQuery.prototype.day_after = function (date, next) {
   if (typeof date === 'undefined' || typeof next === 'undefined') {
@@ -1665,6 +1932,8 @@ WOQLQuery.prototype.day_after = function (date, next) {
  * @param {string|object|Var} date - The input date
  * @param {string|object|Var} previous - The previous calendar day
  * @returns {WOQLQuery}
+ * day_before(literal("2000-03-01", "xsd:date"), "v:previous")
+ * // "2000-02-29"
  */
 WOQLQuery.prototype.day_before = function (date, previous) {
   if (typeof date === 'undefined' || typeof previous === 'undefined') {
@@ -1683,6 +1952,8 @@ WOQLQuery.prototype.day_before = function (date, previous) {
  * @param {string|object|Var} date - The input date or dateTime
  * @param {string|number|Var} weekday - The ISO weekday number (1=Monday, 7=Sunday)
  * @returns {WOQLQuery}
+ * weekday(literal("2000-02-29", "xsd:date"), "v:weekday")
+ * // 2
  */
 WOQLQuery.prototype.weekday = function (date, weekday) {
   if (typeof date === 'undefined' || typeof weekday === 'undefined') return this.parameterError('Weekday takes two parameters');
@@ -1699,6 +1970,8 @@ WOQLQuery.prototype.weekday = function (date, weekday) {
  * @param {string|object|Var} date - The input date or dateTime
  * @param {string|number|Var} weekday - The US weekday number (1=Sunday, 7=Saturday)
  * @returns {WOQLQuery}
+ * weekday_sunday_start(literal("2000-02-29", "xsd:date"), "v:weekday")
+ * // 3
  */
 WOQLQuery.prototype.weekday_sunday_start = function (date, weekday) {
   if (typeof date === 'undefined' || typeof weekday === 'undefined') return this.parameterError('WeekdaySundayStart takes two parameters');
@@ -1716,6 +1989,8 @@ WOQLQuery.prototype.weekday_sunday_start = function (date, weekday) {
  * @param {string|number|Var} year - The ISO week-numbering year
  * @param {string|number|Var} week - The ISO week number (1-53)
  * @returns {WOQLQuery}
+ * iso_week(literal("2000-02-29", "xsd:date"), "v:year", "v:week")
+ * // 2000, 9
  */
 WOQLQuery.prototype.iso_week = function (date, year, week) {
   if (typeof date === 'undefined' || typeof year === 'undefined' || typeof week === 'undefined') return this.parameterError('IsoWeek takes three parameters');
@@ -1735,6 +2010,8 @@ WOQLQuery.prototype.iso_week = function (date, year, week) {
  * @param {string|object|Var} end - The end date or dateTime
  * @param {string|object|Var} duration - The xsd:duration between start and end
  * @returns {WOQLQuery}
+ * date_duration(literal("2000-01-31", "xsd:date"), literal("2000-02-29", "xsd:date"), "v:duration")
+ * // "P29D"
  */
 WOQLQuery.prototype.date_duration = function (start, end, duration) {
   if (start === undefined || end === undefined || duration === undefined) return this.parameterError('DateDuration takes three parameters');
@@ -1750,6 +2027,11 @@ WOQLQuery.prototype.date_duration = function (start, end, duration) {
  * Specifies that the Subquery is optional - if it does not match the query will not fail
  * @param {WOQLQuery} [subquery] - A subquery which will be optionally matched
  * @returns {WOQLQuery} A WOQLQuery object containing the optional sub Query
+ * @example
+ * let [subject] = vars("subject")
+ * opt(triple(subject, 'label', "A"))
+ * //Subq is an argument or a chained query
+ * opt().triple(subject, 'label', "A")
  */
 WOQLQuery.prototype.opt = function (subquery) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -1769,6 +2051,9 @@ WOQLQuery.prototype.optional = WOQLQuery.prototype.opt;
  * unique hash will be generated
  * @param {string|Var} resultVarName - Variable in which the unique ID is stored
  * @returns {WOQLQuery} A WOQLQuery object containing the unique ID generating function
+ * @example
+ * let [newid] = vars("newid")
+ * unique("doc:Person", ["John", "Smith"], newid)
  */
 WOQLQuery.prototype.unique = function (prefix, inputVarList, resultVarName) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -1785,6 +2070,10 @@ WOQLQuery.prototype.unique = function (prefix, inputVarList, resultVarName) {
  * @param {string} prefix
  * @param {string |array}  inputVarList the variable input list for generate the id
  * @param {string} outputVar  the output variable name
+ * @returns {WOQLQuery} A WOQLQuery object containing the ID generating function
+ * @example
+ * let [newid] = vars("newid")
+ * idgen("doc:Person", ["John", "Smith"], newid)
  */
 
 WOQLQuery.prototype.idgen = function (prefix, inputVarList, outputVar) {
@@ -1805,7 +2094,9 @@ WOQLQuery.prototype.idgenerator = WOQLQuery.prototype.idgen;
  * @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
- * idgen_random("Person/", "v:person_id")
+ * @example
+ * let [newid] = vars("newid")
+ * idgen_random("Person/", newid)
  */
 WOQLQuery.prototype.idgen_random = function (prefix, outputVar) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -1826,6 +2117,10 @@ WOQLQuery.prototype.random_idgen = WOQLQuery.prototype.idgen_random;
  * @param {string|Var} inputVarName - string or variable representing the uncapitalized string
  * @param {string|Var} resultVarName -  variable that stores the capitalized string output
  * @returns {WOQLQuery} A WOQLQuery which contains the Upper case pattern matching expression
+ * @example
+ * let [allcaps] = vars("allcaps")
+ * upper("aBCe", allcaps)
+ * //upper contains "ABCE"
  */
 WOQLQuery.prototype.upper = function (inputVarName, resultVarName) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -1840,6 +2135,10 @@ WOQLQuery.prototype.upper = function (inputVarName, resultVarName) {
  * @param {string|Var} inputVarName -  string or variable representing the non-lowercased string
  * @param {string|Var} resultVarName - variable that stores the lowercased string output
  * @returns {WOQLQuery} A WOQLQuery which contains the Lower case pattern matching expression
+ * @example
+ * let [lower] = var("l")
+ * lower("aBCe", lower)
+ * //lower contains "abce"
  */
 
 WOQLQuery.prototype.lower = function (inputVarName, resultVarName) {
@@ -1859,6 +2158,10 @@ WOQLQuery.prototype.lower = function (inputVarName, resultVarName) {
  * the output string
  * @param {string|Var} resultVarName - stores output
  * @returns {WOQLQuery} A WOQLQuery which contains the Pad pattern matching expression
+ * @example
+ * let [fixed] = vars("fixed length")
+ * pad("joe", " ", 8, fixed)
+ * //fixed contains "joe     "
  */
 
 WOQLQuery.prototype.pad = function (inputVarName, pad, len, resultVarName) {
@@ -1878,6 +2181,9 @@ WOQLQuery.prototype.pad = function (inputVarName, pad, len, resultVarName) {
  * to use as a separator
  * @param {string|Var} resultVarName - variable that stores output list
  * @returns {WOQLQuery} A WOQLQuery which contains the Split pattern matching expression
+ * @example
+ * let [words] = vars("words")
+ * split("joe has a hat", " ", words)
  */
 
 WOQLQuery.prototype.split = function (inputVarName, separator, resultVarName) {
@@ -1895,6 +2201,9 @@ WOQLQuery.prototype.split = function (inputVarName, separator, resultVarName) {
  * @param {string|array|Var} list - List ([string, literal] or string*) Either a variable
  * representing a list or a list of variables or literals
  * @returns {WOQLQuery} A WOQLQuery which contains the List inclusion pattern matching expression
+ * @example
+ * let [name] = vars("name")
+ * member(name, ["john", "joe", "frank"])
  */
 WOQLQuery.prototype.member = function (element, list) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -1910,6 +2219,9 @@ WOQLQuery.prototype.member = function (element, list) {
  * @param {string|Var|array} listB - Second list or variable
  * @param {string|Var} result - Variable to store the result
  * @returns {WOQLQuery} A WOQLQuery which contains the SetDifference expression
+ * @example
+ * let [result] = vars("result")
+ * set_difference(["a", "b", "c"], ["b", "d"], result)  // result = ["a", "c"]
  */
 WOQLQuery.prototype.set_difference = function (listA, listB, result) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -1926,6 +2238,9 @@ WOQLQuery.prototype.set_difference = function (listA, listB, result) {
  * @param {string|Var|array} listB - Second list or variable
  * @param {string|Var} result - Variable to store the result
  * @returns {WOQLQuery} A WOQLQuery which contains the SetIntersection expression
+ * @example
+ * let [result] = vars("result")
+ * set_intersection(["a", "b", "c"], ["b", "c", "d"], result)  // result = ["b", "c"]
  */
 WOQLQuery.prototype.set_intersection = function (listA, listB, result) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -1942,6 +2257,9 @@ WOQLQuery.prototype.set_intersection = function (listA, listB, result) {
  * @param {string|Var|array} listB - Second list or variable
  * @param {string|Var} result - Variable to store the result
  * @returns {WOQLQuery} A WOQLQuery which contains the SetUnion expression
+ * @example
+ * let [result] = vars("result")
+ * set_union(["a", "b"], ["b", "c"], result)  // result = ["a", "b", "c"]
  */
 WOQLQuery.prototype.set_union = function (listA, listB, result) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -1957,6 +2275,8 @@ WOQLQuery.prototype.set_union = function (listA, listB, result) {
  * @param {string|Var|any} element - Element to check
  * @param {string|Var|array} set - Set (list) to check membership in
  * @returns {WOQLQuery} A WOQLQuery which contains the SetMember expression
+ * @example
+ * set_member("b", ["a", "b", "c"])  // succeeds if "b" is in the set
  */
 WOQLQuery.prototype.set_member = function (element, set) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -1971,6 +2291,9 @@ WOQLQuery.prototype.set_member = function (element, set) {
  * @param {string|Var|array} list - Input list or variable
  * @param {string|Var} set - Variable to store the resulting set
  * @returns {WOQLQuery} A WOQLQuery which contains the ListToSet expression
+ * @example
+ * let [result] = vars("result")
+ * list_to_set(["a", "b", "a", "c", "b"], result)  // result = ["a", "b", "c"]
  */
 WOQLQuery.prototype.list_to_set = function (list, set) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -1986,6 +2309,9 @@ WOQLQuery.prototype.list_to_set = function (list, set) {
  * strings - variables can be embedded in the string if they do not contain spaces
  * @param {string|Var}  resultVarName - A variable or string containing the output string
  * @returns {WOQLQuery} A WOQLQuery which contains the Concatenation pattern matching expression
+ * @example
+ * let [first_name, last_name, full_name] = vars("first_name", "last_name", "full_name")
+ * concat([first_name, " ", last_name], full_name)
  */
 
 WOQLQuery.prototype.concat = function (varList, resultVarName) {
@@ -2026,6 +2352,9 @@ WOQLQuery.prototype.concatenate = WOQLQuery.prototype.concat;
  * to put in between the joined strings in input
  * @param {string|Var} resultVarName - A variable or string containing the output string
  * @returns {WOQLQuery} A WOQLQuery which contains the Join pattern matching expression
+ * @example
+ * let [sentence] = vars("sentence")
+ * join(["joe", "has", "a", "hat", " ", sentence)
  */
 WOQLQuery.prototype.join = function (varList, glue, resultVarName) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -2043,6 +2372,9 @@ WOQLQuery.prototype.join = function (varList, glue, resultVarName) {
  * list of variables or numeric literals
  * @param {string|Var} total - the variable name with the sum result of the values in List
  * @returns {WOQLQuery} - A WOQLQuery which contains the Sum expression
+ * @example
+ * let [total] = vars("total")
+ * sum([2, 3, 4, 5], total)
  */
 WOQLQuery.prototype.sum = function (subquery, total) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -2060,6 +2392,9 @@ WOQLQuery.prototype.sum = function (subquery, total) {
  * or a chained query
  * @returns {WOQLQuery} A WOQLQuery whose results will be returned starting from
  * the specified offset
+ * @example
+ * let [a, b, c] = vars("a", "b", "c")
+ * start(100).triple(a, b, c)
  */
 
 WOQLQuery.prototype.start = function (start, subquery) {
@@ -2077,6 +2412,11 @@ WOQLQuery.prototype.start = function (start, subquery) {
  * @param {WOQLQuery} [subquery] - A subquery whose results will be limited
  * @returns {WOQLQuery} A WOQLQuery whose results will be returned starting from
  * the specified offset
+ * @example
+ * let [a, b, c] = vars("a", "b", "c")
+ * limit(100).triple(a, b, c)
+ * //subquery is an argument or a chained query
+ * limit(100,triple(a, b, c))
  */
 
 WOQLQuery.prototype.limit = function (limit, subquery) {
@@ -2097,6 +2437,10 @@ WOQLQuery.prototype.limit = function (limit, subquery) {
  * or a list of strings or variables
  * @returns {WOQLQuery} A WOQLQuery which contains the Regular Expression pattern
  * matching expression
+ * @example
+ * let [All, Sub] = vars("All", "Sub")
+ * WOQL.re("h(.).*", "hello", [All, Sub])
+ * //e contains 'e', llo contains 'llo'
  */
 
 WOQLQuery.prototype.re = function (pattern, inputVarName, resultVarList) {
@@ -2117,6 +2461,9 @@ WOQLQuery.prototype.regexp = WOQLQuery.prototype.re;
  * @param {string|Var} resultVarName -  A variable in which the length of the list is stored or
  * the length of the list as a non-negative integer
  * @returns {WOQLQuery} A WOQLQuery which contains the Length pattern matching expression
+ * @example
+ * let [count] = vars("count")
+ * length(["john", "joe", "frank"], count)
  */
 WOQLQuery.prototype.length = function (inputVarList, resultVarName) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -2141,6 +2488,7 @@ WOQLQuery.prototype.length = function (inputVarList, resultVarName) {
  * @param {number|string|Var} start - The start index (0-based, supports negative indices)
  * @param {number|string|Var} [end] - The end index (exclusive, optional - defaults to list length)
  * @returns {WOQLQuery} A WOQLQuery which contains the Slice pattern matching expression
+ * @example
  * let [result] = vars("result")
  * slice(["a", "b", "c", "d"], result, 1, 3)  // result = ["b", "c"]
  * slice(["a", "b", "c", "d"], result, -2)    // result = ["c", "d"]
@@ -2172,6 +2520,9 @@ WOQLQuery.prototype.slice = function (inputList, resultVarName, start, end) {
  * will fail to match
  * @param {string | WOQLQuery} [subquery] -  A subquery which will be negated
  * @returns {WOQLQuery} A WOQLQuery object containing the negated sub Query
+ * @example
+ * let [subject, label] = vars("subject", "label")
+ * not().triple(subject, 'label', label)
  */
 WOQLQuery.prototype.not = function (subquery) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -2183,6 +2534,10 @@ WOQLQuery.prototype.not = function (subquery) {
  * Results in one solution of the subqueries
  * @param {string| WOQLQuery } [subquery] - WOQL Query objects
  * @returns {WOQLQuery} A WOQLQuery object containing the once sub Query
+ * sequence("v:number", 1, 10, 1)
+ * // returns 9 generated solutions, 1..9
+ * once(sequence("v:number", 1, 10, 1))
+ * // returns only first generated solution, 1
  */
 WOQLQuery.prototype.once = function (subquery) {
   // if (query && query === 'args') return ['query']
@@ -2207,6 +2562,9 @@ WOQLQuery.prototype.immediately = function (query) {
  * @param {string|number|Var} countVarName - variable or integer count
  * @param {WOQLQuery} [subquery]
  * @returns {WOQLQuery} A WOQLQuery object containing the count sub Query
+ * @example
+ * let [count, Person] = vars("count", "Person")
+ * WOQL.count(count).triple(Person, "rdf:type", "@schema:Person")
  */
 WOQLQuery.prototype.count = function (countVarName, subquery) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -2222,6 +2580,9 @@ WOQLQuery.prototype.count = function (countVarName, subquery) {
  * @param {string|Var} varType - Either a variable or a basic datatype (xsd / xdd)
  * @param {string|Var} resultVarName - save the return variable
  * @returns {WOQLQuery} A WOQLQuery which contains the casting expression
+ * @example
+ * let [time] = vars("time")
+ * cast("22/3/98", "xsd:dateTime", time)
  */
 
 WOQLQuery.prototype.typecast = function (varName, varType, resultVarName) {
@@ -2242,6 +2603,9 @@ WOQLQuery.prototype.cast = WOQLQuery.prototype.typecast;
  * each optionally followed by either “asc” or “desc” to represent order as a list, by default
  * it will sort the variable in ascending order
  * @returns  {WOQLQuery} A WOQLQuery which contains the ordering expression
+ * @example
+ * let [A, B, C] = vars("A", "B", "C")
+ * WOQL.order_by(A, [B, "asc"], [C, "desc"]).triple(A, B, C);
  */
 WOQLQuery.prototype.order_by = function (...orderedVarlist) {
   // if (orderedVarlist && orderedVarlist[0] === 'args')
@@ -2296,6 +2660,14 @@ WOQLQuery.prototype.order_by = function (...orderedVarlist) {
  * @param {string|Var} output - output variable name
  * @param {WOQLQuery} [groupquery] - The query whose results will be grouped
  * @returns {WOQLQuery} A WOQLQuery which contains the grouping expression
+ * @example
+ * //subquery is an argument or a chained query
+ * let [age, last_name, first_name, age_group, person] = vars("age", "last name", "first name",
+ * "age group", "person")
+ * group_by(age, [last_name, first_name], age_group)
+ *   .triple(person, "first_name", first_name)
+ *   .triple(person, "last_name", last_name)
+ *   .triple(person, "age", age)
  */
 
 WOQLQuery.prototype.group_by = function (gvarlist, groupedvar, output, groupquery) {
@@ -2324,6 +2696,11 @@ WOQLQuery.prototype.group_by = function (gvarlist, groupedvar, output, groupquer
  * @param {string|Var} into - Variable that will be bound to the collected list
  * @param {WOQLQuery} [subquery] - The query whose solutions will be collected
  * @returns {WOQLQuery} A WOQLQuery which contains the collect expression
+ * collect(["number"], "v:numbers",
+ *   sequence("v:number", 1, 10, 1),
+ *   // sequence generates 9 indepedent solutions, 1..9 ()
+ * )
+ * // numbers variable now has the list of numbers
  */
 WOQLQuery.prototype.collect = function (template, into, subquery) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -2337,6 +2714,8 @@ WOQLQuery.prototype.collect = function (template, into, subquery) {
 /**
  * A function that always matches, always returns true
  * @returns {WOQLQuery} A WOQLQuery object containing the true value that will match any pattern
+ * @example
+ * when(true()).triple("a", "b", "c")
  */
 WOQLQuery.prototype.true = function () {
   this.cursor['@type'] = 'True';
@@ -2354,6 +2733,9 @@ WOQLQuery.prototype.true = function () {
  * @param {string|Var} [resultVarName] - A variable in which the actual paths
  * traversed will be stored
  * @returns {WOQLQuery} - A WOQLQuery which contains the path regular expression matching expression
+ * @example
+ * let [person, grand_uncle, lineage] = vars("person", "grand uncle", "lineage")
+ * path(person, "((father|mother) {2,2}), brother)", grand_uncle, lineage)
  */
 
 WOQLQuery.prototype.path = function (subject, pattern, object, resultVarName) {
@@ -2375,6 +2757,11 @@ WOQLQuery.prototype.path = function (subject, pattern, object, resultVarName) {
  * @param {string|Var} field - The field from which the document which is being accessed.
  * @param {string|Var} value - The value for the document and field.
  * @returns {WOQLQuery} A WOQLQuery which contains the a dot Statement
+ * @example
+ * and(
+ *   eq("v:doc", new doc({"@type": "Person", "name": "John Doe"})),
+ *   dot("v:doc", "name", "v:name")
+ * )
  */
 
 WOQLQuery.prototype.dot = function (document, field, value) {
@@ -2391,6 +2778,11 @@ WOQLQuery.prototype.dot = function (document, field, value) {
  * @param {string|Var} resourceId - A valid resource identifier string (can refer to any graph /
  * branch / commit / db)
  * @param {string|Var} resultVarName - The variable name
+ * @returns {WOQLQuery} A WOQLQuery which contains the size expression
+ * @example
+ * let [varSize] = vars("varSize")
+ * size("admin/minecraft/local/branch/main/instance/main", varSize)
+ * //returns the number of bytes in the main instance graph on the main branch
  */
 
 WOQLQuery.prototype.size = function (resourceId, resultVarName) {
@@ -2409,6 +2801,10 @@ WOQLQuery.prototype.size = function (resourceId, resultVarName) {
  * @param {string|number|Var} tripleCount - An integer literal with the size in bytes or a
  * variable containing that integer
  * @returns {WOQLQuery} A WOQLQuery which contains the size expression
+ * @example
+ * let [count] = vars("count")
+ * triple_count("admin/minecraft/local/_commits", count)
+ * //returns the number of triples in the local commit graph
  */
 WOQLQuery.prototype.triple_count = function (resourceId, TripleCount) {
   if (this.cursor['@type']) this.wrapCursorWithAnd();
@@ -2423,6 +2819,9 @@ WOQLQuery.prototype.triple_count = function (resourceId, TripleCount) {
  * @param {string|Var} elementId - the id of a schema graph element
  * @param {string|Var} elementType - the element type
  * @returns {WOQLQuery} A WOQLQuery object containing the type_of pattern matching rule
+ * @example
+ * type_of(literal("string", "xsd:string"), "v:elementType")
+ * // elementType is "xsd:string"
  */
 
 WOQLQuery.prototype.type_of = function (elementId, elementType) {