@unrdf/hooks 5.0.1 → 26.4.2

package/examples/basic.mjs

@@ -0,0 +1,113 @@
+/**
+ * @unrdf/hooks - Basic Example
+ *
+ * Demonstrates basic usage of the Knowledge Hooks package.
+ */
+
+import { createStore, dataFactory } from '@unrdf/oxigraph';
+import {
+  defineHook,
+  createHookRegistry,
+  registerHook,
+  executeHooksByTrigger,
+  builtinHooks,
+} from '../src/index.mjs';
+
+const { namedNode, literal, quad  } = dataFactory;
+
+console.log('=== @unrdf/hooks Basic Example ===\n');
+
+// 1. Define a custom validation hook
+const validateEmailProperty = defineHook({
+  name: 'validate-email-property',
+  trigger: 'before-add',
+  validate: (quad) => {
+    if (quad.predicate.value === 'http://schema.org/email') {
+      if (quad.object.termType !== 'Literal') {
+        return false;
+      }
+      const email = quad.object.value;
+      return email.includes('@') && email.includes('.');
+    }
+    return true;
+  },
+  metadata: {
+    description: 'Validates email format for schema:email properties',
+  },
+});
+
+console.log('1. Defined custom email validation hook');
+
+// 2. Create registry and register hooks
+const registry = createHookRegistry();
+registerHook(registry, validateEmailProperty);
+registerHook(registry, builtinHooks.validatePredicateIRI);
+
+console.log('2. Registered hooks in registry\n');
+
+// 3. Create test quads
+const validQuad = quad(
+  namedNode('http://example.org/person1'),
+  namedNode('http://schema.org/email'),
+  literal('user@example.com')
+);
+
+const invalidQuad = quad(
+  namedNode('http://example.org/person2'),
+  namedNode('http://schema.org/email'),
+  literal('invalid-email')
+);
+
+// 4. Execute hooks on quads
+console.log('3. Executing hooks on valid email quad:');
+const result1 = executeHooksByTrigger(
+  [validateEmailProperty, builtinHooks.validatePredicateIRI],
+  'before-add',
+  validQuad
+);
+console.log(`   Valid: ${result1.valid}`);
+console.log(`   Hooks executed: ${result1.results.length}\n`);
+
+console.log('4. Executing hooks on invalid email quad:');
+const result2 = executeHooksByTrigger(
+  [validateEmailProperty, builtinHooks.validatePredicateIRI],
+  'before-add',
+  invalidQuad
+);
+console.log(`   Valid: ${result2.valid}`);
+console.log(`   Error: ${result2.error}\n`);
+
+// 5. Demonstrate transformation hook
+const normalizeEmail = defineHook({
+  name: 'normalize-email',
+  trigger: 'before-add',
+  transform: (quad) => {
+    if (quad.predicate.value === 'http://schema.org/email' &&
+        quad.object.termType === 'Literal') {
+      return dataFactory.quad(
+        quad.subject,
+        quad.predicate,
+        literal(quad.object.value.toLowerCase()),
+        quad.graph
+      );
+    }
+    return quad;
+  },
+});
+
+console.log('5. Applying transformation hook:');
+const upperEmail = quad(
+  namedNode('http://example.org/person3'),
+  namedNode('http://schema.org/email'),
+  literal('USER@EXAMPLE.COM')
+);
+
+const result3 = executeHooksByTrigger(
+  [normalizeEmail],
+  'before-add',
+  upperEmail
+);
+console.log(`   Original: ${upperEmail.object.value}`);
+console.log(`   Transformed: ${result3.quad.object.value}\n`);
+
+console.log('=== Example Complete ===');

package/examples/hook-chains/README.md

@@ -0,0 +1,263 @@
+# Hook Chains Example
+
+This example demonstrates how to use **@unrdf/hooks** for creating sequential hook chains that validate and transform RDF quads through multiple stages.
+
+## Features
+
+- **Sequential Execution**: Hooks execute in defined order
+- **Progressive Transformation**: Quads transform through pipeline stages
+- **Early Termination**: Chain stops on first validation failure
+- **Result Aggregation**: Complete execution history and results
+- **Composable Patterns**: Mix and match hooks for different pipelines
+
+## Installation
+
+```bash
+pnpm install
+```
+
+## Usage
+
+Run the example:
+
+```bash
+pnpm start
+```
+
+Run tests:
+
+```bash
+pnpm test
+```
+
+## Example Output
+
+```
+🔗 Hook Chains Example
+
+============================================================
+
+🧹 Data Cleaning Chain
+────────────────────────────────────────────────────────────
+Input:   Alice   Smith
+       "  Alice   Smith  "
+Status: ✅ SUCCESS
+Steps: 3/3 passed
+Output: Alice Smith
+        "Alice Smith"
+
+Chain execution:
+  1. ✅ 🔄 trim-literals
+  2. ✅ 🔄 normalize-whitespace
+  3. ✅    validate-literal-length
+
+🔍 Quality Assurance Chain
+────────────────────────────────────────────────────────────
+Input: Literal with 1500 characters
+Status: ❌ FAILED
+Steps: 3/4 passed
+Failed at: validate-literal-length
+Reason: validation failed
+
+Chain execution (early termination):
+  1. ✅ standard-validation
+  2. ✅ validate-iris
+  3. ✅ validate-iri-format
+  4. ❌ validate-literal-length
+
+⚙️  Complete Processing Chain
+────────────────────────────────────────────────────────────
+Input:
+  Object: "  Chuck  "
+  Graph: DefaultGraph
+
+Status: ✅ SUCCESS
+Steps: 5/5 passed
+
+Output:
+  Object: "Chuck"
+  Graph: NamedNode
+  Graph IRI: http://example.org/provenance/1733288888888
+
+Chain execution:
+  1. ✅    validate-iris
+  2. ✅ 🔄 normalize-whitespace
+      └─ Transformation applied
+  3. ✅    validate-literal-length
+  4. ✅ 🔄 add-provenance
+      └─ Transformation applied
+  5. ✅    final-validation
+
+============================================================
+✨ Hook Chains Example Complete
+```
+
+## Hook Chain Patterns
+
+### 1. Data Cleaning Chain
+
+Clean and normalize messy data:
+
+```javascript
+const dataCleaningChain = [
+  builtinHooks.trimLiterals,       // Remove leading/trailing whitespace
+  normalizeWhitespace,              // Collapse multiple spaces
+  validateLiteralLength,            // Ensure valid length
+];
+
+const result = executeHookChain(dataCleaningChain, store, quad);
+```
+
+### 2. Quality Assurance Chain
+
+Comprehensive validation pipeline:
+
+```javascript
+const qualityAssuranceChain = [
+  builtinHooks.standardValidation,  // RDF structure
+  validateIRIs,                      // IRI well-formedness
+  builtinHooks.validateIRIFormat,   // URL validation
+  validateLiteralLength,             // Length constraints
+];
+
+const result = executeHookChain(qualityAssuranceChain, store, quad);
+```
+
+### 3. Complete Processing Chain
+
+Full pipeline with validation and transformation:
+
+```javascript
+const completeProcessingChain = [
+  validateIRIs,                      // 1. Validate structure
+  normalizeWhitespace,               // 2. Clean data
+  validateLiteralLength,             // 3. Check constraints
+  addProvenance,                     // 4. Add metadata
+  finalValidation,                   // 5. Final checks
+];
+
+const result = executeHookChain(completeProcessingChain, store, quad);
+```
+
+## Custom Hooks
+
+### Validation Hook
+
+```javascript
+const validateIRIs = defineHook({
+  name: 'validate-iris',
+  trigger: 'before-add',
+  validate: quad => {
+    const validateIRI = term => {
+      if (term.termType !== 'NamedNode') return true;
+      try {
+        new URL(term.value);
+        return true;
+      } catch {
+        return false;
+      }
+    };
+
+    return validateIRI(quad.subject) &&
+           validateIRI(quad.predicate) &&
+           validateIRI(quad.object);
+  },
+});
+```
+
+### Transformation Hook
+
+```javascript
+const normalizeWhitespace = defineHook({
+  name: 'normalize-whitespace',
+  trigger: 'before-add',
+  transform: quad => {
+    if (quad.object.termType !== 'Literal') {
+      return quad;
+    }
+
+    const normalized = quad.object.value
+      .trim()
+      .replace(/\s+/g, ' ');
+
+    return DataFactory.quad(
+      quad.subject,
+      quad.predicate,
+      DataFactory.literal(
+        normalized,
+        quad.object.language || quad.object.datatype
+      ),
+      quad.graph
+    );
+  },
+});
+```
+
+## Chain Execution
+
+### Success Case
+
+```javascript
+const result = executeHookChain(chain, store, quad);
+
+if (result.success) {
+  console.log('All hooks passed!');
+  console.log('Transformed quad:', result.quad);
+  console.log('Steps executed:', result.results.length);
+}
+```
+
+### Failure Case (Early Termination)
+
+```javascript
+const result = executeHookChain(chain, store, invalidQuad);
+
+if (!result.success) {
+  const failedHook = result.results.find(r => !r.passed);
+  console.log('Failed at:', failedHook.hookName);
+  console.log('Reason:', failedHook.reason);
+  console.log('Steps before failure:', result.results.length);
+}
+```
+
+### Tracking Transformations
+
+```javascript
+const result = executeHookChain(chain, store, quad);
+
+result.results.forEach((r, i) => {
+  console.log(`Step ${i + 1}: ${r.hookName}`);
+  if (r.transformed) {
+    console.log('  → Transformation applied');
+  }
+  if (!r.passed) {
+    console.log('  → Validation failed:', r.reason);
+  }
+});
+```
+
+## Testing
+
+The example includes comprehensive tests:
+
+- Individual hook behavior
+- Chain execution order
+- Early termination on failures
+- Progressive transformations
+- Result aggregation
+
+Run tests with:
+
+```bash
+pnpm test
+```
+
+## Learn More
+
+- [@unrdf/hooks Documentation](../../README.md)
+- [Policy Hooks Example](../policy-hooks/)
+- [UNRDF Core](../../../core/)
+
+## License
+
+MIT

package/examples/hook-chains/node_modules/.bin/validate-hooks

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/Users/sac/unrdf/packages/hooks/examples/node_modules:/Users/sac/unrdf/packages/hooks/node_modules:/Users/sac/unrdf/packages/node_modules:/Users/sac/unrdf/node_modules:/Users/sac/node_modules:/Users/node_modules:/node_modules:/Users/sac/unrdf/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/Users/sac/unrdf/packages/hooks/examples/node_modules:/Users/sac/unrdf/packages/hooks/node_modules:/Users/sac/unrdf/packages/node_modules:/Users/sac/unrdf/node_modules:/Users/sac/node_modules:/Users/node_modules:/node_modules:/Users/sac/unrdf/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../@unrdf/hooks/examples/validate-hooks.mjs" "$@"
+else
+  exec node  "$basedir/../@unrdf/hooks/examples/validate-hooks.mjs" "$@"
+fi

package/examples/hook-chains/node_modules/.bin/vitest

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/Users/sac/unrdf/node_modules/.pnpm/vitest@4.0.15_@opentelemetry+api@1.9.0_@types+node@24.10.1_@vitest+ui@4.0.15_happy-dom@_4020ef6a5cc83a28d6954792bad1f77a/node_modules/vitest/node_modules:/Users/sac/unrdf/node_modules/.pnpm/vitest@4.0.15_@opentelemetry+api@1.9.0_@types+node@24.10.1_@vitest+ui@4.0.15_happy-dom@_4020ef6a5cc83a28d6954792bad1f77a/node_modules:/Users/sac/unrdf/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/Users/sac/unrdf/node_modules/.pnpm/vitest@4.0.15_@opentelemetry+api@1.9.0_@types+node@24.10.1_@vitest+ui@4.0.15_happy-dom@_4020ef6a5cc83a28d6954792bad1f77a/node_modules/vitest/node_modules:/Users/sac/unrdf/node_modules/.pnpm/vitest@4.0.15_@opentelemetry+api@1.9.0_@types+node@24.10.1_@vitest+ui@4.0.15_happy-dom@_4020ef6a5cc83a28d6954792bad1f77a/node_modules:/Users/sac/unrdf/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../vitest/vitest.mjs" "$@"
+else
+  exec node  "$basedir/../vitest/vitest.mjs" "$@"
+fi

package/examples/hook-chains/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -0,0 +1 @@
+{"version":"4.0.15","results":[[":test/example.test.mjs",{"duration":7.120207999999991,"failed":false}]]}

package/examples/hook-chains/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@unrdf/hooks-example-chains",
+  "version": "5.0.0",
+  "type": "module",
+  "description": "Hook Chains Example - Sequential hook execution and composition",
+  "private": true,
+  "scripts": {
+    "start": "node src/index.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@unrdf/core": "workspace:*",
+    "@unrdf/hooks": "workspace:*",
+    "n3": "^1.26.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.15"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}