@unrdf/knowledge-engine 5.0.1 → 26.4.2

package/src/utils/ring-buffer.mjs

@@ -1,282 +0,0 @@
-/**
- * @file ring-buffer.mjs
- * @description TRIZ #10 Prior Action - Ring buffer for efficient streaming operations
- * Pre-allocates fixed memory to avoid array reallocation overhead during high-throughput streaming
- */
-
-/**
- * @typedef {Object} RingBufferOptions
- * @property {number} [maxSize=100] - Maximum number of items in buffer
- */
-
-/**
- * High-performance circular buffer for streaming data
- * O(1) push operations with automatic wraparound, avoiding array slice/shift overhead
- *
- * @template T
- * @example
- * const buffer = new RingBuffer(100);
- * buffer.push({ event: 'added', timestamp: Date.now() });
- * const events = buffer.toArray(); // Returns items in insertion order
- */
-export class RingBuffer {
-  /**
-   * @param {number} [maxSize=100] - Maximum buffer capacity
-   */
-  constructor(maxSize = 100) {
-    /** @type {Array<T|undefined>} */
-    this.buffer = new Array(maxSize);
-    /** @type {number} - Index where next item will be written */
-    this.head = 0;
-    /** @type {number} - Index of oldest item */
-    this.tail = 0;
-    /** @type {number} - Current number of items */
-    this.size = 0;
-    /** @type {number} - Maximum capacity */
-    this.maxSize = maxSize;
-  }
-
-  /**
-   * Add item to buffer, overwriting oldest if full
-   * @param {T} item - Item to add
-   * @returns {T|undefined} - Overwritten item if buffer was full, undefined otherwise
-   */
-  push(item) {
-    /** @type {T|undefined} */
-    let overwritten;
-
-    if (this.size === this.maxSize) {
-      // Buffer full - overwrite oldest item
-      overwritten = this.buffer[this.tail];
-      this.tail = (this.tail + 1) % this.maxSize;
-    } else {
-      this.size++;
-    }
-
-    this.buffer[this.head] = item;
-    this.head = (this.head + 1) % this.maxSize;
-
-    return overwritten;
-  }
-
-  /**
-   * Remove and return oldest item from buffer
-   * @returns {T|undefined} - Oldest item or undefined if empty
-   */
-  shift() {
-    if (this.size === 0) {
-      return undefined;
-    }
-
-    const item = this.buffer[this.tail];
-    this.buffer[this.tail] = undefined; // Allow GC
-    this.tail = (this.tail + 1) % this.maxSize;
-    this.size--;
-
-    return item;
-  }
-
-  /**
-   * Get item at index (0 = oldest)
-   * @param {number} index - Index from oldest item
-   * @returns {T|undefined} - Item at index or undefined
-   */
-  get(index) {
-    if (index < 0 || index >= this.size) {
-      return undefined;
-    }
-    const actualIndex = (this.tail + index) % this.maxSize;
-    return this.buffer[actualIndex];
-  }
-
-  /**
-   * Get most recent item without removing
-   * @returns {T|undefined} - Most recent item or undefined if empty
-   */
-  peek() {
-    if (this.size === 0) {
-      return undefined;
-    }
-    const lastIndex = (this.head - 1 + this.maxSize) % this.maxSize;
-    return this.buffer[lastIndex];
-  }
-
-  /**
-   * Get oldest item without removing
-   * @returns {T|undefined} - Oldest item or undefined if empty
-   */
-  peekOldest() {
-    if (this.size === 0) {
-      return undefined;
-    }
-    return this.buffer[this.tail];
-  }
-
-  /**
-   * Convert buffer to array in insertion order (oldest first)
-   * @returns {Array<T>} - Array of items
-   */
-  toArray() {
-    if (this.size === 0) {
-      return [];
-    }
-
-    /** @type {Array<T>} */
-    const result = new Array(this.size);
-
-    for (let i = 0; i < this.size; i++) {
-      const index = (this.tail + i) % this.maxSize;
-      result[i] = /** @type {T} */ (this.buffer[index]);
-    }
-
-    return result;
-  }
-
-  /**
-   * Clear all items from buffer
-   */
-  clear() {
-    // Clear references for GC
-    for (let i = 0; i < this.maxSize; i++) {
-      this.buffer[i] = undefined;
-    }
-    this.head = 0;
-    this.tail = 0;
-    this.size = 0;
-  }
-
-  /**
-   * Check if buffer is empty
-   * @returns {boolean}
-   */
-  isEmpty() {
-    return this.size === 0;
-  }
-
-  /**
-   * Check if buffer is full
-   * @returns {boolean}
-   */
-  isFull() {
-    return this.size === this.maxSize;
-  }
-
-  /**
-   * Get current number of items
-   * @returns {number}
-   */
-  get length() {
-    return this.size;
-  }
-
-  /**
-   * Get maximum capacity
-   * @returns {number}
-   */
-  get capacity() {
-    return this.maxSize;
-  }
-
-  /**
-   * Get available space
-   * @returns {number}
-   */
-  get available() {
-    return this.maxSize - this.size;
-  }
-
-  /**
-   * Iterate over items (oldest to newest)
-   * @yields {T}
-   */
-  *[Symbol.iterator]() {
-    for (let i = 0; i < this.size; i++) {
-      const index = (this.tail + i) % this.maxSize;
-      yield /** @type {T} */ (this.buffer[index]);
-    }
-  }
-
-  /**
-   * Apply function to each item
-   * @param {(item: T, index: number) => void} fn - Function to apply
-   */
-  forEach(fn) {
-    for (let i = 0; i < this.size; i++) {
-      const index = (this.tail + i) % this.maxSize;
-      fn(/** @type {T} */ (this.buffer[index]), i);
-    }
-  }
-
-  /**
-   * Filter items and return new array
-   * @param {(item: T, index: number) => boolean} predicate - Filter function
-   * @returns {Array<T>}
-   */
-  filter(predicate) {
-    /** @type {Array<T>} */
-    const result = [];
-    for (let i = 0; i < this.size; i++) {
-      const index = (this.tail + i) % this.maxSize;
-      const item = /** @type {T} */ (this.buffer[index]);
-      if (predicate(item, i)) {
-        result.push(item);
-      }
-    }
-    return result;
-  }
-
-  /**
-   * Find first item matching predicate
-   * @param {(item: T, index: number) => boolean} predicate - Search function
-   * @returns {T|undefined}
-   */
-  find(predicate) {
-    for (let i = 0; i < this.size; i++) {
-      const index = (this.tail + i) % this.maxSize;
-      const item = /** @type {T} */ (this.buffer[index]);
-      if (predicate(item, i)) {
-        return item;
-      }
-    }
-    return undefined;
-  }
-
-  /**
-   * Get last N items (most recent)
-   * @param {number} n - Number of items
-   * @returns {Array<T>}
-   */
-  last(n) {
-    const count = Math.min(n, this.size);
-    /** @type {Array<T>} */
-    const result = new Array(count);
-    const startOffset = this.size - count;
-
-    for (let i = 0; i < count; i++) {
-      const index = (this.tail + startOffset + i) % this.maxSize;
-      result[i] = /** @type {T} */ (this.buffer[index]);
-    }
-
-    return result;
-  }
-
-  /**
-   * Get first N items (oldest)
-   * @param {number} n - Number of items
-   * @returns {Array<T>}
-   */
-  first(n) {
-    const count = Math.min(n, this.size);
-    /** @type {Array<T>} */
-    const result = new Array(count);
-
-    for (let i = 0; i < count; i++) {
-      const index = (this.tail + i) % this.maxSize;
-      result[i] = /** @type {T} */ (this.buffer[index]);
-    }
-
-    return result;
-  }
-}
-
-export default RingBuffer;

package/src/validate.mjs

@@ -1,319 +0,0 @@
-/**
- * @file SHACL validation.
- * @module validate
- */
-
-import { createStore } from '@unrdf/oxigraph';
-import rdf from 'rdf-ext';
-import SHACLValidator from 'rdf-validate-shacl';
-import { trace, SpanStatusCode } from '@opentelemetry/api';
-
-const tracer = trace.getTracer('unrdf');
-
-/**
- * Validate a store against SHACL shapes.
- * @param {Store} store - The store containing data to validate
- * @param {Store|string} shapes - The store or Turtle string containing SHACL shapes
- * @param {Object} [options] - Validation options
- * @param {boolean} [options.strict] - Enable strict validation mode
- * @param {boolean} [options.includeDetails] - Include detailed validation results
- * @returns {{conforms: boolean, results: Array<object>}} Validation report
- *
- * @throws {Error} If validation fails
- *
- * @example
- * const dataStore = new Store();
- * // ... add data quads to store
- *
- * const shapesTtl = `
- *   @prefix sh: <http://www.w3.org/ns/shacl#> .
- *   @prefix ex: <http://example.org/> .
- *   ex:PersonShape a sh:NodeShape ;
- *     sh:targetClass ex:Person ;
- *     sh:property [
- *       sh:path ex:name ;
- *       sh:minCount 1 ;
- *       sh:maxCount 1
- *     ] .
- * `;
- *
- * const report = validateShacl(dataStore, shapesTtl);
- * console.log('Conforms:', report.conforms);
- * console.log('Results:', report.results);
- */
-export function validateShacl(store, shapes, options = {}) {
-  if (!store || typeof store.getQuads !== 'function') {
-    throw new TypeError('validateShacl: store must be a valid Store instance');
-  }
-  if (!shapes) {
-    throw new TypeError('validateShacl: shapes must be provided');
-  }
-
-  return tracer.startActiveSpan('validate.shacl', span => {
-    try {
-      const shapesType = typeof shapes === 'string' ? 'turtle' : 'store';
-      span.setAttributes({
-        'validate.shapes_type': shapesType,
-        'validate.data_size': store.size,
-        'validate.include_details': options.includeDetails || false,
-      });
-
-      // Parse Turtle shapes if provided as string
-      let shapesStore;
-      if (typeof shapes === 'string') {
-        shapesStore = createStore();
-        shapesStore.load(shapes, { format: 'text/turtle' });
-      } else {
-        shapesStore = shapes;
-      }
-
-      if (!shapesStore || typeof shapesStore.getQuads !== 'function') {
-        throw new TypeError('validateShacl: shapes must be a valid Store or Turtle string');
-      }
-
-      span.setAttribute('validate.shapes_size', shapesStore.size);
-
-      const validator = new SHACLValidator(rdf.dataset(shapesStore.getQuads()));
-      const report = validator.validate(rdf.dataset(store.getQuads()));
-
-      const results = (report.results || []).map(r => ({
-        message: r.message?.[0]?.value || null,
-        path: r.path?.value || null,
-        focusNode: r.focusNode?.value || null,
-        severity: r.severity?.value || null,
-        sourceConstraint: r.sourceConstraint?.value || null,
-        sourceConstraintComponent: r.sourceConstraintComponent?.value || null,
-        sourceShape: r.sourceShape?.value || null,
-        value: r.value?.value || null,
-        ...(options.includeDetails && {
-          detail: r.detail || null,
-          resultPath: r.resultPath?.value || null,
-          resultSeverity: r.resultSeverity?.value || null,
-        }),
-      }));
-
-      const errorCount = results.filter(
-        r => r.severity === 'http://www.w3.org/ns/shacl#Violation'
-      ).length;
-      const warningCount = results.filter(
-        r => r.severity === 'http://www.w3.org/ns/shacl#Warning'
-      ).length;
-
-      span.setAttributes({
-        'validate.conforms': report.conforms,
-        'validate.total_results': results.length,
-        'validate.error_count': errorCount,
-        'validate.warning_count': warningCount,
-      });
-
-      span.setStatus({ code: SpanStatusCode.OK });
-
-      const validationResult = {
-        conforms: report.conforms,
-        results,
-        ...(options.includeDetails && {
-          totalResults: results.length,
-          errorCount: errorCount,
-          warningCount: warningCount,
-          infoCount: results.filter(r => r.severity === 'http://www.w3.org/ns/shacl#Info').length,
-        }),
-      };
-
-      span.end();
-      return validationResult;
-    } catch (error) {
-      span.recordException(error);
-      span.setStatus({
-        code: SpanStatusCode.ERROR,
-        message: error.message,
-      });
-      span.end();
-      throw new Error(`SHACL validation failed: ${error.message}`);
-    }
-  });
-}
-
-/**
- * Validate a store against multiple SHACL shape sets.
- * @param {Store} store - The store containing data to validate
- * @param {Array<Store|string>} shapesList - Array of stores or Turtle strings containing SHACL shapes
- * @param {Object} [options] - Validation options
- * @returns {{conforms: boolean, results: Array<object>, shapeResults: Array<object>}} Combined validation report
- *
- * @throws {Error} If validation fails
- *
- * @example
- * const shapesList = [
- *   personShapesTtl,
- *   organizationShapesTtl,
- *   contactShapesTtl
- * ];
- *
- * const report = validateShaclMultiple(store, shapesList);
- * console.log('Overall conforms:', report.conforms);
- * console.log('Shape-specific results:', report.shapeResults);
- */
-export function validateShaclMultiple(store, shapesList, options = {}) {
-  if (!store || typeof store.getQuads !== 'function') {
-    throw new TypeError('validateShaclMultiple: store must be a valid Store instance');
-  }
-  if (!Array.isArray(shapesList) || shapesList.length === 0) {
-    throw new TypeError('validateShaclMultiple: shapesList must be a non-empty array');
-  }
-
-  try {
-    const shapeResults = [];
-    let allResults = [];
-    let overallConforms = true;
-
-    for (let i = 0; i < shapesList.length; i++) {
-      const shapes = shapesList[i];
-      const report = validateShacl(store, shapes, options);
-
-      shapeResults.push({
-        index: i,
-        shapes: typeof shapes === 'string' ? 'Turtle string' : 'Store',
-        conforms: report.conforms,
-        resultCount: report.results.length,
-        results: report.results,
-      });
-
-      allResults = allResults.concat(report.results);
-      if (!report.conforms) {
-        overallConforms = false;
-      }
-    }
-
-    return {
-      conforms: overallConforms,
-      results: allResults,
-      shapeResults,
-      totalShapes: shapesList.length,
-      totalResults: allResults.length,
-    };
-  } catch (error) {
-    throw new Error(`Multiple SHACL validation failed: ${error.message}`);
-  }
-}
-
-/**
- * Create a SHACL validation report in a structured format.
- * @param {Object} validationResult - Result from validateShacl
- * @param {Object} [options] - Formatting options
- * @param {boolean} [options.includeSummary] - Include summary statistics
- * @param {boolean} [options.groupBySeverity] - Group results by severity
- * @returns {Object} Formatted validation report
- *
- * @example
- * const report = validateShacl(store, shapes);
- * const formatted = formatValidationReport(report, {
- *   includeSummary: true,
- *   groupBySeverity: true
- * });
- */
-export function formatValidationReport(validationResult, options = {}) {
-  if (!validationResult || typeof validationResult !== 'object') {
-    throw new TypeError('formatValidationReport: validationResult must be an object');
-  }
-
-  const { results = [], conforms } = validationResult;
-  const { includeSummary = false, groupBySeverity = false } = options;
-
-  let formatted = {
-    conforms,
-    resultCount: results.length,
-  };
-
-  if (includeSummary) {
-    const severityCounts = results.reduce((acc, result) => {
-      const severity = result.severity || 'unknown';
-      acc[severity] = (acc[severity] || 0) + 1;
-      return acc;
-    }, {});
-
-    formatted.summary = {
-      totalResults: results.length,
-      severityCounts,
-      hasErrors: severityCounts['http://www.w3.org/ns/shacl#Violation'] > 0,
-      hasWarnings: severityCounts['http://www.w3.org/ns/shacl#Warning'] > 0,
-      hasInfo: severityCounts['http://www.w3.org/ns/shacl#Info'] > 0,
-    };
-  }
-
-  if (groupBySeverity) {
-    formatted.resultsBySeverity = results.reduce((acc, result) => {
-      const severity = result.severity || 'unknown';
-      if (!acc[severity]) {
-        acc[severity] = [];
-      }
-      acc[severity].push(result);
-      return acc;
-    }, {});
-  } else {
-    formatted.results = results;
-  }
-
-  return formatted;
-}
-
-/**
- * Check if a validation result contains any errors.
- * @param {Object} validationResult - Result from validateShacl
- * @returns {boolean} True if there are any validation errors
- *
- * @example
- * const report = validateShacl(store, shapes);
- * if (hasValidationErrors(report)) {
- *   console.log('Validation failed with errors');
- * }
- */
-export function hasValidationErrors(validationResult) {
-  if (!validationResult || typeof validationResult !== 'object') {
-    return false;
-  }
-
-  const { results = [] } = validationResult;
-  return results.some(result => result.severity === 'http://www.w3.org/ns/shacl#Violation');
-}
-
-/**
- * Get validation errors from a validation result.
- * @param {Object} validationResult - Result from validateShacl
- * @returns {Array<Object>} Array of validation error objects
- *
- * @example
- * const report = validateShacl(store, shapes);
- * const errors = getValidationErrors(report);
- * errors.forEach(error => {
- *   console.log(`Error: ${error.message} at ${error.focusNode}`);
- * });
- */
-export function getValidationErrors(validationResult) {
-  if (!validationResult || typeof validationResult !== 'object') {
-    return [];
-  }
-
-  const { results = [] } = validationResult;
-  return results.filter(result => result.severity === 'http://www.w3.org/ns/shacl#Violation');
-}
-
-/**
- * Get validation warnings from a validation result.
- * @param {Object} validationResult - Result from validateShacl
- * @returns {Array<Object>} Array of validation warning objects
- *
- * @example
- * const report = validateShacl(store, shapes);
- * const warnings = getValidationWarnings(report);
- * warnings.forEach(warning => {
- *   console.log(`Warning: ${warning.message} at ${warning.focusNode}`);
- * });
- */
-export function getValidationWarnings(validationResult) {
-  if (!validationResult || typeof validationResult !== 'object') {
-    return [];
-  }
-
-  const { results = [] } = validationResult;
-  return results.filter(result => result.severity === 'http://www.w3.org/ns/shacl#Warning');
-}