terminusdb 12.0.2

package/lib/valueHash.js_old

@@ -0,0 +1,581 @@
+/* eslint-disable no-plusplus */
+/* eslint-disable no-continue */
+/* eslint-disable no-restricted-syntax */
+/**
+ * @file ValueHash - Client-side ValueHash computation for TerminusDB documents
+ * @license Apache Version 2
+ *
+ * This module provides functions to compute ValueHash IDs for TerminusDB documents
+ * on the client side, matching the server's algorithm exactly.
+ *
+ * The ValueHash algorithm:
+ * 1. Extract all path-value pairs from the document
+ * 2. Format them in Prolog's ~q (quoted) format
+ * 3. Compute SHA256 hash of the formatted string
+ * 4. Append hash to the base IRI (e.g., "Type/" -> "Type/<hash>")
+ */
+
+const crypto = require('node:crypto');
+
+/**
+ * Standard XSD type mappings for value elaboration
+ */
+const XSD_TYPES = {
+  string: 'http://www.w3.org/2001/XMLSchema#string',
+  integer: 'http://www.w3.org/2001/XMLSchema#integer',
+  decimal: 'http://www.w3.org/2001/XMLSchema#decimal',
+  double: 'http://www.w3.org/2001/XMLSchema#double',
+  float: 'http://www.w3.org/2001/XMLSchema#float',
+  boolean: 'http://www.w3.org/2001/XMLSchema#boolean',
+  date: 'http://www.w3.org/2001/XMLSchema#date',
+  dateTime: 'http://www.w3.org/2001/XMLSchema#dateTime',
+  time: 'http://www.w3.org/2001/XMLSchema#time',
+  gYear: 'http://www.w3.org/2001/XMLSchema#gYear',
+  gMonth: 'http://www.w3.org/2001/XMLSchema#gMonth',
+  gDay: 'http://www.w3.org/2001/XMLSchema#gDay',
+  gYearMonth: 'http://www.w3.org/2001/XMLSchema#gYearMonth',
+  gMonthDay: 'http://www.w3.org/2001/XMLSchema#gMonthDay',
+  duration: 'http://www.w3.org/2001/XMLSchema#duration',
+  anyURI: 'http://www.w3.org/2001/XMLSchema#anyURI',
+  base64Binary: 'http://www.w3.org/2001/XMLSchema#base64Binary',
+  hexBinary: 'http://www.w3.org/2001/XMLSchema#hexBinary',
+  long: 'http://www.w3.org/2001/XMLSchema#long',
+  short: 'http://www.w3.org/2001/XMLSchema#short',
+  byte: 'http://www.w3.org/2001/XMLSchema#byte',
+  unsignedLong: 'http://www.w3.org/2001/XMLSchema#unsignedLong',
+  unsignedInt: 'http://www.w3.org/2001/XMLSchema#unsignedInt',
+  unsignedShort: 'http://www.w3.org/2001/XMLSchema#unsignedShort',
+  unsignedByte: 'http://www.w3.org/2001/XMLSchema#unsignedByte',
+  positiveInteger: 'http://www.w3.org/2001/XMLSchema#positiveInteger',
+  negativeInteger: 'http://www.w3.org/2001/XMLSchema#negativeInteger',
+  nonPositiveInteger: 'http://www.w3.org/2001/XMLSchema#nonPositiveInteger',
+  nonNegativeInteger: 'http://www.w3.org/2001/XMLSchema#nonNegativeInteger',
+};
+
+/**
+ * Default context prefixes
+ */
+const DEFAULT_CONTEXT = {
+  '@base': 'terminusdb:///data/',
+  '@schema': 'terminusdb:///schema#',
+};
+
+/**
+ * Expand a prefixed IRI using the context
+ * @param {string} iri - The IRI to expand (may be prefixed like "xsd:string")
+ * @param {object} context - The context object with prefix mappings
+ * @returns {string} The expanded IRI
+ */
+function expandIRI(iri, context) {
+  if (!iri || typeof iri !== 'string') return iri;
+
+  // Already expanded
+  if (iri.startsWith('http://') || iri.startsWith('https://') || iri.startsWith('terminusdb:')) {
+    return iri;
+  }
+
+  // Handle xsd: prefix specially
+  if (iri.startsWith('xsd:')) {
+    const localPart = iri.substring(4);
+    return XSD_TYPES[localPart] || `http://www.w3.org/2001/XMLSchema#${localPart}`;
+  }
+
+  // Handle prefixed IRIs
+  const colonIndex = iri.indexOf(':');
+  if (colonIndex > 0) {
+    const prefix = iri.substring(0, colonIndex);
+    const localPart = iri.substring(colonIndex + 1);
+    if (context[prefix]) {
+      return context[prefix] + localPart;
+    }
+  }
+
+  // Use schema prefix for type names
+  const schemaBase = context['@schema'] || DEFAULT_CONTEXT['@schema'];
+  return schemaBase + iri;
+}
+
+/**
+ * Get the base IRI for a type
+ * @param {string} type - The type name
+ * @param {object} context - The context object
+ * @returns {string} The base IRI for document IDs of this type
+ */
+function getTypeBase(type, context) {
+  const base = context['@base'] || DEFAULT_CONTEXT['@base'];
+  // Extract just the type name without namespace
+  let typeName = type;
+  if (type.includes('#')) {
+    typeName = type.split('#').pop();
+  } else if (type.includes('/')) {
+    typeName = type.split('/').pop();
+  }
+  return `${base}${typeName}/`;
+}
+
+/**
+ * Infer XSD type from JavaScript value
+ * @param {any} value - The value to infer type for
+ * @returns {string} The XSD type IRI
+ */
+function inferXsdType(value) {
+  if (typeof value === 'string') {
+    return XSD_TYPES.string;
+  }
+  if (typeof value === 'number') {
+    if (Number.isInteger(value)) {
+      return XSD_TYPES.integer;
+    }
+    return XSD_TYPES.decimal;
+  }
+  if (typeof value === 'boolean') {
+    return XSD_TYPES.boolean;
+  }
+  return XSD_TYPES.string;
+}
+
+/**
+ * Format a string for Prolog quoted output (escape special characters)
+ * @param {string} str - The string to format
+ * @returns {string} The formatted string
+ */
+function formatPrologString(str) {
+  // In Prolog ~q format, strings are double-quoted and special chars are escaped
+  let result = str;
+  // Escape backslashes first
+  result = result.replace(/\\/g, '\\\\');
+  // Escape double quotes
+  result = result.replace(/"/g, '\\"');
+  return `"${result}"`;
+}
+
+/**
+ * Format an atom for Prolog quoted output
+ * Atoms containing special characters or starting with uppercase need quoting
+ * @param {string} atom - The atom to format
+ * @returns {string} The formatted atom
+ */
+function formatPrologAtom(atom) {
+  // In Prolog, atoms are single-quoted if they contain special characters
+  // or start with uppercase, etc.
+  // For URIs and special names, we always quote
+  if (typeof atom !== 'string') {
+    return String(atom);
+  }
+
+  // Escape single quotes within the atom
+  const escaped = atom.replace(/'/g, "\\'");
+  return `'${escaped}'`;
+}
+
+/**
+ * Format a typed value in Prolog format: (value^^type)
+ * For strings: ("value"^^'type')
+ * For numbers: (42^^'type')
+ * For booleans: (true^^'type')
+ * @param {any} value - The value
+ * @param {string} type - The XSD type IRI
+ * @returns {string} The formatted typed value
+ */
+function formatTypedValue(value, type) {
+  let formattedValue;
+
+  // Numbers are NOT quoted in Prolog
+  if (typeof value === 'number') {
+    formattedValue = String(value);
+  } else if (typeof value === 'boolean') {
+    formattedValue = value ? 'true' : 'false';
+  } else {
+    // Strings are double-quoted
+    formattedValue = formatPrologString(String(value));
+  }
+
+  const formattedType = formatPrologAtom(type);
+  return `(${formattedValue}^^${formattedType})`;
+}
+
+/**
+ * Format a path (list of keys) in Prolog format: [key1,key2,...]
+ * @param {Array} path - The path as array of keys
+ * @returns {string} The formatted path
+ */
+function formatPrologPath(path) {
+  const formattedElements = path.map((element) => {
+    if (typeof element === 'number') {
+      return String(element);
+    }
+    return formatPrologAtom(element);
+  });
+  return `[${formattedElements.join(',')}]`;
+}
+
+/**
+ * Format a path-value pair in Prolog format: [path]-value
+ * @param {Array} path - The path
+ * @param {any} value - The value (already formatted)
+ * @returns {string} The formatted pair
+ */
+function formatPathValuePair(path, value) {
+  return `${formatPrologPath(path)}-${value}`;
+}
+
+/**
+ * Extract all path-value pairs from an elaborated document
+ * This matches TerminusDB's get_all_path_values/2 predicate
+ *
+ * @param {object} doc - The elaborated document
+ * @param {Array} currentPath - The current path (for recursion)
+ * @returns {Array} Array of [path, formattedValue] pairs
+ */
+function extractPathValues(doc, currentPath = []) {
+  const pathValues = [];
+
+  if (doc === null || doc === undefined) {
+    return pathValues;
+  }
+
+  if (typeof doc !== 'object') {
+    // Primitive value - should not happen at top level
+    return pathValues;
+  }
+
+  // Get all keys and sort them for deterministic ordering
+  const keys = Object.keys(doc).filter((k) => k !== '@id').sort();
+
+  for (const key of keys) {
+    const value = doc[key];
+    const newPath = [...currentPath, key];
+
+    if (key === '@type') {
+      // Type is an atom value
+      if (typeof value === 'string') {
+        pathValues.push([newPath, formatPrologAtom(value)]);
+      }
+    } else if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      // Nested object - check @container FIRST (containers also have @type and @value)
+      if (value['@container'] !== undefined) {
+        // Container type (list, set, array)
+        // For containers, get_value extracts each element's value directly
+        // The path is just the field name (no @value, no indices)
+        if (value['@value'] !== undefined) {
+          const containerValue = value['@value'];
+          if (Array.isArray(containerValue)) {
+            if (containerValue.length === 0) {
+              // Empty container - emit empty list
+              pathValues.push([newPath, '[]']);
+            } else {
+              // Sort elements for deterministic ordering
+              const sortedElements = [...containerValue].sort((a, b) => {
+                const aStr = JSON.stringify(a);
+                const bStr = JSON.stringify(b);
+                return aStr.localeCompare(bStr);
+              });
+              // Emit each element's value with just the field path
+              sortedElements.forEach((element) => {
+                if (element['@value'] !== undefined && element['@type'] !== undefined) {
+                  // Typed literal - emit directly
+                  pathValues.push([newPath, formatTypedValue(element['@value'], element['@type'])]);
+                } else if (element['@type'] === '@id' && element['@id'] !== undefined) {
+                  // Document link
+                  pathValues.push([newPath, formatPrologString(element['@id'])]);
+                } else if (typeof element === 'object' && element !== null) {
+                  // Subdocument - this would need recursive handling
+                  // But for simple cases, subdocs in sets might have their own @id
+                  const subPaths = extractPathValues(element, newPath);
+                  pathValues.push(...subPaths);
+                }
+              });
+            }
+          }
+        }
+      } else if (value['@type'] === '@id' && value['@id'] !== undefined) {
+        // Document link - value is just the IRI string (double-quoted)
+        pathValues.push([newPath, formatPrologString(value['@id'])]);
+      } else if (value['@value'] !== undefined && value['@type'] !== undefined) {
+        // Typed literal like {"@value": "foo", "@type": "xsd:string"}
+        pathValues.push([newPath, formatTypedValue(value['@value'], value['@type'])]);
+      } else {
+        // Regular nested object (subdocument)
+        const subPaths = extractPathValues(value, newPath);
+        pathValues.push(...subPaths);
+      }
+    } else if (Array.isArray(value)) {
+      // Array/Set - sort for deterministic ordering
+      if (value.length === 0) {
+        pathValues.push([newPath, '[]']);
+      } else {
+        const sortedElements = [...value].sort((a, b) => {
+          const aStr = JSON.stringify(a);
+          const bStr = JSON.stringify(b);
+          return aStr.localeCompare(bStr);
+        });
+        for (let i = 0; i < sortedElements.length; i++) {
+          const element = sortedElements[i];
+          const elementPath = [...newPath, i];
+          if (typeof element === 'object' && element !== null) {
+            // Check if it's a typed literal (has @value and @type)
+            if (element['@value'] !== undefined && element['@type'] !== undefined) {
+              // Typed literal - emit directly without recursing
+              pathValues.push([elementPath, formatTypedValue(element['@value'], element['@type'])]);
+            } else {
+              // Complex object - recurse
+              const subPaths = extractPathValues(element, elementPath);
+              pathValues.push(...subPaths);
+            }
+          } else {
+            // Primitive in array
+            const type = inferXsdType(element);
+            pathValues.push([elementPath, formatTypedValue(element, type)]);
+          }
+        }
+      }
+    } else {
+      // Primitive value - create typed literal
+      const type = inferXsdType(value);
+      pathValues.push([newPath, formatTypedValue(value, type)]);
+    }
+  }
+
+  return pathValues;
+}
+
+/**
+ * Check if a string value is a document link (IRI reference)
+ * @param {string} value - The value to check
+ * @param {object} context - The context with @base
+ * @returns {boolean} True if value is a document link
+ */
+function isDocumentLink(value, context) {
+  const base = context['@base'] || 'terminusdb:///data/';
+  // Check if value starts with the base IRI (it's a document reference)
+  return value.startsWith(base) || value.startsWith('http://') || value.startsWith('https://');
+}
+
+/**
+ * Elaborate a document by expanding IRIs and adding type information
+ * This is a simplified version that works for ValueHash computation
+ *
+ * @param {object} doc - The document to elaborate
+ * @param {object} context - The context with prefix mappings
+ * @param {object} schema - Optional schema information for type inference
+ * @returns {object} The elaborated document
+ */
+function elaborateDocument(doc, context, schema = null) {
+  if (doc === null || doc === undefined) {
+    return doc;
+  }
+
+  if (typeof doc !== 'object') {
+    return doc;
+  }
+
+  if (Array.isArray(doc)) {
+    return doc.map((item) => elaborateDocument(item, context, schema));
+  }
+
+  const elaborated = {};
+
+  // Expand @type first
+  if (doc['@type']) {
+    elaborated['@type'] = expandIRI(doc['@type'], context);
+  }
+
+  // Process other fields
+  for (const [key, value] of Object.entries(doc)) {
+    if (key === '@type' || key === '@id') {
+      continue;
+    }
+
+    // Expand the key to full IRI
+    const expandedKey = key.startsWith('@') ? key : expandIRI(key, context);
+
+    if (value === null || value === undefined) {
+      continue;
+    }
+
+    if (typeof value === 'object' && !Array.isArray(value)) {
+      if (value['@type'] && value['@value'] !== undefined) {
+        // Already a typed value
+        elaborated[expandedKey] = {
+          '@type': expandIRI(value['@type'], context),
+          '@value': value['@value'],
+        };
+      } else {
+        // Subdocument - recursively elaborate
+        elaborated[expandedKey] = elaborateDocument(value, context, schema);
+      }
+    } else if (Array.isArray(value)) {
+      // Array of values - create container structure
+      const elaboratedItems = value.map((item) => {
+        if (typeof item === 'object' && item !== null) {
+          return elaborateDocument(item, context, schema);
+        }
+        // Wrap primitive in typed literal
+        return {
+          '@type': inferXsdType(item),
+          '@value': item,
+        };
+      });
+
+      // Infer element type from first item (or use generic)
+      let elementType = XSD_TYPES.string;
+      if (elaboratedItems.length > 0) {
+        const firstItem = elaboratedItems[0];
+        if (firstItem['@type']) {
+          elementType = firstItem['@type'];
+        }
+      }
+
+      // Create container structure
+      elaborated[expandedKey] = {
+        '@container': '@set', // Default to set; could be refined with schema
+        '@type': elementType,
+        '@value': elaboratedItems,
+      };
+    } else if (typeof value === 'string' && isDocumentLink(value, context)) {
+      // Document link - wrap as @id reference
+      elaborated[expandedKey] = {
+        '@type': '@id',
+        '@id': value,
+      };
+    } else {
+      // Primitive value - wrap in typed literal
+      elaborated[expandedKey] = {
+        '@type': inferXsdType(value),
+        '@value': value,
+      };
+    }
+  }
+
+  return elaborated;
+}
+
+/**
+ * Compute the ValueHash for a document
+ *
+ * @param {object} doc - The document to hash
+ * @param {object} [options] - Options for hash computation
+ * @param {object} [options.context] - The context with prefix mappings
+ * @param {object} [options.schema] - Optional schema information
+ * @returns {string} The computed ValueHash (SHA256 hex string)
+ */
+function computeValueHash(doc, options = {}) {
+  const context = options.context || DEFAULT_CONTEXT;
+
+  // Elaborate the document
+  const elaborated = elaborateDocument(doc, context, options.schema);
+
+  // Extract path-values
+  const pathValues = extractPathValues(elaborated);
+
+  // Sort path-values for deterministic ordering (by path first, then value)
+  pathValues.sort((a, b) => {
+    const pathA = JSON.stringify(a[0]);
+    const pathB = JSON.stringify(b[0]);
+    if (pathA !== pathB) {
+      return pathA.localeCompare(pathB);
+    }
+    return String(a[1]).localeCompare(String(b[1]));
+  });
+
+  // Format as Prolog list of pairs
+  const formattedPairs = pathValues.map(([path, value]) => formatPathValuePair(path, value));
+  const prologList = `[${formattedPairs.join(',')}]`;
+
+  // Debug: log the Prolog list being hashed
+  // if (options.debug) {
+  //   console.log('Prolog list being hashed:', prologList);
+  // }
+
+  // Compute SHA256 hash
+  const hash = crypto.createHash('sha256').update(prologList).digest('hex');
+
+  return hash;
+}
+
+/**
+ * Generate the full @id for a document using ValueHash
+ *
+ * @param {object} doc - The document to generate ID for
+ * @param {object} [options] - Options for ID generation
+ * @param {object} [options.context] - The context with prefix mappings
+ * @param {object} [options.schema] - Optional schema information
+ * @returns {string} The full document @id with ValueHash
+ */
+function generateValueHashId(doc, options = {}) {
+  const context = options.context || DEFAULT_CONTEXT;
+
+  if (!doc['@type']) {
+    throw new Error('Document must have @type for ValueHash computation');
+  }
+
+  const expandedType = expandIRI(doc['@type'], context);
+  const base = getTypeBase(expandedType, context);
+  const hash = computeValueHash(doc, options);
+
+  return base + hash;
+}
+
+/**
+ * Set the @id of a document using ValueHash, recursively processing subdocuments
+ *
+ * @param {object} doc - The document to set ID for
+ * @param {object} [options] - Options for ID generation
+ * @param {object} [options.context] - The context with prefix mappings
+ * @param {object} [options.schema] - Optional schema information
+ * @returns {object} The document with @id set (and subdocuments processed)
+ */
+function setValueHashId(doc, options = {}) {
+  if (doc === null || doc === undefined || typeof doc !== 'object') {
+    return doc;
+  }
+
+  if (Array.isArray(doc)) {
+    return doc.map((item) => setValueHashId(item, options));
+  }
+
+  // Create a copy to avoid mutating the original
+  const result = { ...doc };
+
+  // Process subdocuments first (depth-first)
+  for (const [key, value] of Object.entries(result)) {
+    if (key.startsWith('@')) {
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      result[key] = value.map((item) => {
+        if (typeof item === 'object' && item !== null && item['@type']) {
+          return setValueHashId(item, options);
+        }
+        return item;
+      });
+    } else if (typeof value === 'object' && value !== null && value['@type']) {
+      result[key] = setValueHashId(value, options);
+    }
+  }
+
+  // Now compute and set the ID for this document
+  if (result['@type']) {
+    result['@id'] = generateValueHashId(result, options);
+  }
+
+  return result;
+}
+
+module.exports = {
+  computeValueHash,
+  generateValueHashId,
+  setValueHashId,
+  elaborateDocument,
+  extractPathValues,
+  expandIRI,
+  getTypeBase,
+  formatPrologAtom,
+  formatPrologString,
+  formatTypedValue,
+  formatPrologPath,
+  formatPathValuePair,
+  XSD_TYPES,
+  DEFAULT_CONTEXT,
+};