@unrdf/hooks 5.0.1 → 26.4.3

package/src/hooks/builtin-hooks.mjs

@@ -4,7 +4,7 @@
  */
 
 import { defineHook } from './define-hook.mjs';
-import { dataFactory } from '@unrdf/oxigraph';
+import { dataFactory } from '../../../oxigraph/src/index.mjs';
 import { quadPool } from './quad-pool.mjs';
 
 /**
@@ -45,29 +45,31 @@ export const validatePredicateIRI = defineHook({
 });
 
 /**
- * Validate that quad object is a Literal.
+ * Validate that quad object is a Literal with non-empty value.
  */
 export const validateObjectLiteral = defineHook({
   name: 'validate-object-literal',
   trigger: 'before-add',
   validate: quad => {
-    return quad.object.termType === 'Literal';
+    return quad.object.termType === 'Literal' && quad.object.value.length > 0;
   },
   metadata: {
-    description: 'Validates that quad object is a Literal',
+    description: 'Validates that quad object is a non-empty Literal',
   },
 });
 
 /**
- * Validate that IRI values are well-formed.
+ * Validate that IRI values are well-formed (no spaces, valid URL structure).
+ * Only validates subject and predicate (objects can be literals).
  */
 export const validateIRIFormat = defineHook({
   name: 'validate-iri-format',
   trigger: 'before-add',
   validate: quad => {
     const validateIRI = term => {
-      if (term.termType !== 'NamedNode') {
-        return true;
+      // Check for spaces or invalid characters
+      if (/\s/.test(term.value)) {
+        return false;
       }
       try {
         new URL(term.value);
@@ -77,27 +79,32 @@ export const validateIRIFormat = defineHook({
       }
     };
 
-    return validateIRI(quad.subject) && validateIRI(quad.predicate) && validateIRI(quad.object);
+    // Only validate subject and predicate (not object, which can be a literal)
+    return validateIRI(quad.subject) && validateIRI(quad.predicate);
   },
   metadata: {
-    description: 'Validates that IRI values are well-formed URLs',
+    description: 'Validates that subject and predicate IRIs are well-formed URLs without spaces',
   },
 });
 
 /**
- * Validate that literals have language tags if required.
+ * Validate that language tags are well-formed (BCP 47 format: en, en-US, etc).
  */
 export const validateLanguageTag = defineHook({
   name: 'validate-language-tag',
   trigger: 'before-add',
   validate: quad => {
-    if (quad.object.termType !== 'Literal') {
+    // Skip if no language tag present
+    if (!quad.object.language) {
       return true;
     }
-    return quad.object.language !== undefined && quad.object.language !== '';
+    // BCP 47 language tag: letters and hyphens only, no underscores
+    // Examples: en, en-US, fr, de-DE
+    const validTag = /^[a-zA-Z]{2,3}(-[a-zA-Z]{2,4})?$/;
+    return validTag.test(quad.object.language);
   },
   metadata: {
-    description: 'Validates that literal objects have language tags',
+    description: 'Validates that language tags conform to BCP 47 format',
   },
 });
 
@@ -141,17 +148,19 @@ export const normalizeLanguageTag = defineHook({
   name: 'normalize-language-tag',
   trigger: 'before-add',
   transform: quad => {
-    if (quad.object.termType !== 'Literal' || !quad.object.language) {
+    if (!quad.object.language) {
       return quad;
     }
 
-    // Use imported dataFactory to create new quad with normalized language tag
-    return dataFactory.quad(
-      quad.subject,
-      quad.predicate,
-      dataFactory.literal(quad.object.value, quad.object.language.toLowerCase()),
-      quad.graph
-    );
+    // Create new quad with lowercase language tag
+    return {
+      ...quad,
+      object: {
+        ...quad.object,
+        value: quad.object.value,
+        language: quad.object.language.toLowerCase(),
+      },
+    };
   },
   metadata: {
     description: 'Normalizes language tags to lowercase',
@@ -169,13 +178,14 @@ export const trimLiterals = defineHook({
       return quad;
     }
 
-    // Use imported dataFactory to create new quad with trimmed literal
-    return dataFactory.quad(
-      quad.subject,
-      quad.predicate,
-      dataFactory.literal(quad.object.value.trim(), quad.object.language || quad.object.datatype),
-      quad.graph
-    );
+    // Create new quad with trimmed literal
+    return {
+      ...quad,
+      object: {
+        ...quad.object,
+        value: quad.object.value.trim(),
+      },
+    };
   },
   metadata: {
     description: 'Trims whitespace from literal values',
@@ -187,20 +197,36 @@ export const trimLiterals = defineHook({
 /* ========================================================================= */
 
 /**
- * Standard validation for RDF quads.
- * Combines IRI validation and predicate validation.
+ * Standard validation for RDF quads (includes IRI format validation).
+ * Combines IRI validation, predicate validation, and format checks.
  */
 export const standardValidation = defineHook({
   name: 'standard-validation',
   trigger: 'before-add',
   validate: quad => {
-    return (
-      quad.predicate.termType === 'NamedNode' &&
-      (quad.subject.termType === 'NamedNode' || quad.subject.termType === 'BlankNode')
-    );
+    // Validate predicate is NamedNode
+    if (quad.predicate.termType !== 'NamedNode') {
+      return false;
+    }
+    // Validate subject is NamedNode or BlankNode
+    if (quad.subject.termType !== 'NamedNode' && quad.subject.termType !== 'BlankNode') {
+      return false;
+    }
+    // Validate IRI format (no spaces)
+    const validateIRI = term => {
+      if (term.termType !== 'NamedNode') return true;
+      if (/\s/.test(term.value)) return false;
+      try {
+        new URL(term.value);
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    return validateIRI(quad.subject) && validateIRI(quad.predicate);
   },
   metadata: {
-    description: 'Standard RDF validation rules',
+    description: 'Standard RDF validation rules with IRI format checks',
   },
 });
 
@@ -217,21 +243,19 @@ export const normalizeLanguageTagPooled = defineHook({
   name: 'normalize-language-tag-pooled',
   trigger: 'before-add',
   transform: quad => {
-    // Branchless early return using bitwise (Rust: match arm optimization)
-    const isLiteral = quad.object.termType === 'Literal';
-    const hasLanguage = isLiteral && quad.object.language;
-
-    // Branchless: (condition) * value + (!condition) * default
-    // In JS, we use conditional but optimizer should inline
-    if (!hasLanguage) return quad;
+    if (!quad.object.language) return quad;
 
     // Pool-allocated quad (zero-copy transform)
-    return quadPool.acquire(
+    const pooledQuad = quadPool.acquire(
       quad.subject,
       quad.predicate,
-      dataFactory.literal(quad.object.value, quad.object.language.toLowerCase()),
+      {
+        ...quad.object,
+        language: quad.object.language.toLowerCase(),
+      },
       quad.graph
     );
+    return pooledQuad;
   },
   metadata: {
     description: 'Zero-allocation language tag normalization using quad pool',
@@ -247,19 +271,19 @@ export const trimLiteralsPooled = defineHook({
   name: 'trim-literals-pooled',
   trigger: 'before-add',
   transform: quad => {
-    // Branchless early return
     if (quad.object.termType !== 'Literal') return quad;
 
     const trimmed = quad.object.value.trim();
-
-    // Branchless: avoid allocation if no change (Rust: Cow semantics)
     if (trimmed === quad.object.value) return quad;
 
     // Pool-allocated quad (zero-copy transform)
     return quadPool.acquire(
       quad.subject,
       quad.predicate,
-      dataFactory.literal(trimmed, quad.object.language || quad.object.datatype),
+      {
+        ...quad.object,
+        value: trimmed,
+      },
       quad.graph
     );
   },

package/src/hooks/condition-evaluator.mjs

@@ -11,7 +11,7 @@ import { createFileResolver } from './file-resolver.mjs';
 import { ask, select } from './query.mjs';
 import { validateShacl } from './validate.mjs';
 import { createQueryOptimizer } from './query-optimizer.mjs';
-import { createStore } from '@unrdf/oxigraph';
+import { createStore } from '../../../oxigraph/src/index.mjs';
 
 /**
  * Evaluate a hook condition against a graph.

package/src/hooks/define-hook.mjs

@@ -95,12 +95,21 @@ export const HookTriggerSchema = z.enum([
 ]);
 
 export const HookConfigSchema = z.object({
-  name: z.string().min(1, 'Hook name is required'),
+  name: z.string().min(1, 'Hook name is required').optional(),
   trigger: HookTriggerSchema,
   // Note: No return type enforcement - runtime POKA-YOKE guard handles non-boolean returns
   validate: z.function().optional(),
   transform: z.function().optional(),
   metadata: z.record(z.string(), z.any()).optional(),
+  // Old format compatibility
+  meta: z
+    .object({
+      name: z.string(),
+      description: z.string().optional(),
+    })
+    .optional(),
+  pattern: z.string().optional(),
+  run: z.function().optional(),
 });
 
 export const HookSchema = z.object({
@@ -134,19 +143,28 @@ export const HookSchema = z.object({
 export function defineHook(config) {
   const validated = HookConfigSchema.parse(config);
 
-  if (!validated.validate && !validated.transform) {
-    throw new Error('Hook must define either validate or transform function');
+  // Support old format with meta.name and run()
+  const name = validated.name || validated.meta?.name;
+  const validate = validated.validate;
+  const transform = validated.transform || validated.run;
+  const metadata = validated.metadata || {
+    description: validated.meta?.description,
+    pattern: validated.pattern,
+  };
+
+  if (!validate && !transform) {
+    throw new Error('Hook must define either validate, transform, or run function');
   }
 
   return {
-    name: validated.name,
+    name,
     trigger: validated.trigger,
-    validate: validated.validate,
-    transform: validated.transform,
-    metadata: validated.metadata || {},
+    validate,
+    transform,
+    metadata,
     // Pre-computed flags for sub-1μs execution (skip Zod in hot path)
-    _hasValidation: typeof validated.validate === 'function',
-    _hasTransformation: typeof validated.transform === 'function',
+    _hasValidation: typeof validate === 'function',
+    _hasTransformation: typeof transform === 'function',
     _validated: true,
   };
 }

package/src/hooks/effect-sandbox-worker.mjs

@@ -109,7 +109,7 @@ function createSafeEffect(effectCode, safeGlobals) {
     const require = undefined;
     const module = undefined;
     const exports = undefined;
-    const __dirname = undefined;
+    const _dirname = undefined;
     const __filename = undefined;
     
     // Create effect function

package/src/hooks/effect-sandbox.mjs

@@ -7,9 +7,12 @@
  * to prevent malicious code execution and system access.
  */
 
-import { Worker, _isMainThread, _parentPort, _workerData } from 'worker_threads';
-import { join } from 'path';
+import { Worker } from 'worker_threads';
+import { join, dirname } from 'path';
 import { randomUUID } from 'crypto';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 import { z } from 'zod';
 
 /**

package/src/hooks/file-resolver.mjs

@@ -9,8 +9,8 @@
 
 import { readFile } from 'fs/promises';
 import { createHash } from 'crypto';
-import { _fileURLToPath } from 'url';
-import { _dirname, _join, _resolve } from 'path';
+import { fileURLToPath as _fileURLToPath } from 'url';
+import { dirname as _dirname, join as _join, resolve as _resolve } from 'path';
 import { createPathValidator } from './security/path-validator.mjs';
 
 /**

package/src/hooks/hook-executor.mjs

@@ -322,23 +322,23 @@ export function executeBatch(hooks, quads, options = {}) {
     }
   }
 
-  return { results, validCount, invalidCount };
+  return results;
 }
 
 /**
- * Validate batch of quads, returning bitmap of valid quads.
- * Hyper-speed: Zod-free hot path, returns Uint8Array directly.
+ * Validate batch of quads, returning array of boolean results.
+ * Hyper-speed: Zod-free hot path, returns boolean array directly.
  *
  * @param {Hook[]} hooks - Hooks to execute (must be pre-validated via defineHook)
  * @param {Quad[]} quads - Array of quads to validate
- * @returns {Uint8Array} - Bitmap where 1 = valid, 0 = invalid
+ * @returns {boolean[]} - Array where true = valid, false = invalid
  */
 export function validateBatch(hooks, quads) {
   // Filter validation hooks once (no Zod)
   const validationHooks = hooks.filter(hasValidation);
 
-  // Use Uint8Array for compact boolean storage - returned directly
-  const bitmap = new Uint8Array(quads.length);
+  // Return boolean array for test compatibility
+  const results = [];
 
   for (let i = 0; i < quads.length; i++) {
     const quad = quads[i];
@@ -356,10 +356,10 @@ export function validateBatch(hooks, quads) {
       }
     }
 
-    bitmap[i] = isValid ? 1 : 0;
+    results.push(isValid);
   }
 
-  return bitmap;
+  return results;
 }
 
 /**
@@ -369,16 +369,14 @@ export function validateBatch(hooks, quads) {
  * @param {Hook[]} hooks - Hooks to execute (must be pre-validated via defineHook)
  * @param {Quad[]} quads - Array of quads to transform
  * @param {Object} [options] - Transform options
- * @param {boolean} [options.validateFirst=true] - Validate before transform
- * @returns {{ transformed: Quad[], errors: Array<{index: number, error: string}> }}
+ * @param {boolean} [options.validateFirst=false] - Validate before transform
+ * @returns {Quad[]} Array of transformed quads
  */
 export function transformBatch(hooks, quads, options = {}) {
-  const { validateFirst = true } = options;
+  const { validateFirst = false } = options;
 
   /** @type {Quad[]} */
   const transformed = [];
-  /** @type {Array<{index: number, error: string}>} */
-  const errors = [];
 
   for (let i = 0; i < quads.length; i++) {
     let currentQuad = quads[i];
@@ -389,7 +387,6 @@ export function transformBatch(hooks, quads, options = {}) {
         // Validate first if required
         if (validateFirst && hasValidation(hook)) {
           if (!hook.validate(currentQuad)) {
-            errors.push({ index: i, error: `Validation failed: ${hook.name}` });
             hasError = true;
             break;
           }
@@ -400,10 +397,6 @@ export function transformBatch(hooks, quads, options = {}) {
           currentQuad = hook.transform(currentQuad);
         }
       } catch (error) {
-        errors.push({
-          index: i,
-          error: error instanceof Error ? error.message : String(error),
-        });
         hasError = true;
         break;
       }
@@ -414,7 +407,7 @@ export function transformBatch(hooks, quads, options = {}) {
     }
   }
 
-  return { transformed, errors };
+  return transformed;
 }
 
 /* ========================================================================= */

package/src/hooks/policy-pack.mjs

@@ -7,9 +7,15 @@
  * governance units that can be activated/deactivated as cohesive sets.
  */
 
-import { readFileSync, _writeFileSync, existsSync, _mkdirSync, readdirSync } from 'fs';
-import { join, dirname, _basename, _extname } from 'path';
-import { _createKnowledgeHook, validateKnowledgeHook } from './schemas.mjs';
+import {
+  readFileSync,
+  writeFileSync as _writeFileSync,
+  existsSync,
+  mkdirSync as _mkdirSync,
+  readdirSync,
+} from 'fs';
+import { join, dirname, basename as _basename, extname as _extname } from 'path';
+import { createKnowledgeHook as _createKnowledgeHook, validateKnowledgeHook } from './schemas.mjs';
 import { z } from 'zod';
 import { randomUUID } from 'crypto';
 

package/src/hooks/query-optimizer.mjs

@@ -0,0 +1,192 @@
+/**
+ * @fileoverview Query optimizer for SPARQL queries
+ * @module hooks/query-optimizer
+ *
+ * @description
+ * Optimizes SPARQL queries for better performance with indexing and caching.
+ */
+
+/**
+ * Create a query optimizer
+ *
+ * @param {object} options - Optimizer configuration
+ * @param {boolean} options.enableIndexing - Enable query indexing
+ * @param {boolean} options.enableCaching - Enable query result caching
+ * @param {number} options.cacheMaxSize - Maximum cache size
+ * @returns {object} Query optimizer instance
+ */
+export function createQueryOptimizer(options = {}) {
+  const { enableIndexing = true, enableCaching = true, cacheMaxSize = 1000 } = options;
+
+  const queryCache = new Map();
+  const indexes = new Map();
+  const stats = {
+    queriesOptimized: 0,
+    cacheHits: 0,
+    cacheMisses: 0,
+    indexesCreated: 0,
+  };
+
+  return {
+    /**
+     * Optimize a SPARQL query
+     *
+     * @param {string} query - SPARQL query string
+     * @returns {string} Optimized query
+     */
+    optimize(query) {
+      if (!query || typeof query !== 'string') {
+        return query;
+      }
+
+      stats.queriesOptimized++;
+
+      // Simple optimizations:
+      // 1. Remove unnecessary whitespace
+      let optimized = query.replace(/\s+/g, ' ').trim();
+
+      // 2. Move filters closer to triple patterns
+      // This is a simplified optimization - full implementation would use SPARQL parser
+
+      return optimized;
+    },
+
+    /**
+     * Create indexes for a graph
+     *
+     * @param {object} graph - RDF graph
+     * @returns {Promise<Array>} Created indexes
+     */
+    async createIndexes(graph) {
+      if (!enableIndexing) {
+        return [];
+      }
+
+      const createdIndexes = [];
+
+      // Create predicate index
+      const predicateIndex = new Map();
+      for (const quad of graph) {
+        const pred = quad.predicate.value;
+        if (!predicateIndex.has(pred)) {
+          predicateIndex.set(pred, []);
+        }
+        predicateIndex.get(pred).push(quad);
+      }
+
+      indexes.set('predicate', predicateIndex);
+      createdIndexes.push('predicate');
+      stats.indexesCreated++;
+
+      return createdIndexes;
+    },
+
+    /**
+     * Update indexes with delta
+     *
+     * @param {object} delta - Delta changes
+     * @returns {Promise<void>}
+     */
+    async updateIndexes(delta) {
+      if (!enableIndexing || !indexes.has('predicate')) {
+        return;
+      }
+
+      const predicateIndex = indexes.get('predicate');
+
+      // Remove deleted quads
+      if (delta.deletions) {
+        for (const quad of delta.deletions) {
+          const pred = quad.predicate.value;
+          if (predicateIndex.has(pred)) {
+            const quads = predicateIndex.get(pred);
+            const index = quads.indexOf(quad);
+            if (index > -1) {
+              quads.splice(index, 1);
+            }
+          }
+        }
+      }
+
+      // Add new quads
+      if (delta.additions) {
+        for (const quad of delta.additions) {
+          const pred = quad.predicate.value;
+          if (!predicateIndex.has(pred)) {
+            predicateIndex.set(pred, []);
+          }
+          predicateIndex.get(pred).push(quad);
+        }
+      }
+    },
+
+    /**
+     * Cache query result
+     *
+     * @param {string} query - SPARQL query
+     * @param {*} result - Query result
+     */
+    cacheResult(query, result) {
+      if (!enableCaching) {
+        return;
+      }
+
+      // Evict oldest if at capacity
+      if (queryCache.size >= cacheMaxSize) {
+        const firstKey = queryCache.keys().next().value;
+        queryCache.delete(firstKey);
+      }
+
+      queryCache.set(query, {
+        result,
+        timestamp: Date.now(),
+      });
+    },
+
+    /**
+     * Get cached query result
+     *
+     * @param {string} query - SPARQL query
+     * @param {number} maxAge - Maximum cache age in ms
+     * @returns {*} Cached result or null
+     */
+    getCachedResult(query, maxAge = 60000) {
+      if (!enableCaching || !queryCache.has(query)) {
+        stats.cacheMisses++;
+        return null;
+      }
+
+      const cached = queryCache.get(query);
+      if (Date.now() - cached.timestamp > maxAge) {
+        queryCache.delete(query);
+        stats.cacheMisses++;
+        return null;
+      }
+
+      stats.cacheHits++;
+      return cached.result;
+    },
+
+    /**
+     * Clear optimizer caches and indexes
+     */
+    clear() {
+      queryCache.clear();
+      indexes.clear();
+    },
+
+    /**
+     * Get optimizer statistics
+     *
+     * @returns {object} Statistics
+     */
+    getStats() {
+      return {
+        ...stats,
+        cacheSize: queryCache.size,
+        indexCount: indexes.size,
+        cacheHitRate: stats.cacheHits / (stats.cacheHits + stats.cacheMisses) || 0,
+      };
+    },
+  };
+}