Merge pull request #466 from hypermedia-app/triple-to-another

feat: converting triple to other patterns

Author: tpluscode

.changeset/famous-games-change.md

@@ -0,0 +1,6 @@
+---
+"@hydrofoil/shape-to-query": minor
+"@hydrofoil/sparql-processor": minor
+---
+
+The query processor methods now allow returning arrays, which may break extending classes

.changeset/lucky-buckets-smoke.md

@@ -0,0 +1,5 @@
+---
+"@hydrofoil/sparql-processor": patch
+---
+
+Allow transforming triple to another type of pattern

packages/processor/index.ts

@@ -2,7 +2,13 @@ import type sparqljs from 'sparqljs'
 import { match, P } from 'ts-pattern'
 import type { DataFactory, DefaultGraph, Quad_Predicate } from '@rdfjs/types' // eslint-disable-line camelcase
 
-type Term = sparqljs.IriTerm | sparqljs.BlankTerm | sparqljs.LiteralTerm | sparqljs.Variable | sparqljs.QuadTerm | DefaultGraph
+type Term =
+  sparqljs.IriTerm
+  | sparqljs.BlankTerm
+  | sparqljs.LiteralTerm
+  | sparqljs.Variable
+  | sparqljs.QuadTerm
+  | DefaultGraph
 
 export interface Processor {
   process<Q extends sparqljs.SparqlQuery>(query: Q): Q
@@ -136,11 +142,18 @@ export default abstract class ProcessorImpl<F extends DataFactory = DataFactory>
 
   processQuads(quads: sparqljs.Quads): sparqljs.Quads {
     return match(quads)
-      .with({ type: 'bgp' }, bgp => this.processBgp(bgp))
+      .with({ type: 'bgp' }, bgp => {
+        const processed = this.processBgp(bgp)
+        const maybeBgp = Array.isArray(processed) ? processed[0] : processed
+        if (maybeBgp.type !== 'bgp') {
+          throw new Error('Quads must be transformed to a single bgp pattern')
+        }
+        return maybeBgp
+      })
       .with({ type: 'graph' }, (graph): sparqljs.GraphQuads => ({
         type: 'graph',
         name: this.processTerm(graph.name),
-        triples: graph.triples.map(triple => this.processTriple(triple)),
+        triples: graph.triples.map<sparqljs.Triple>(triple => this.processTripleStrict(triple)),
       }))
       .exhaustive()
   }
@@ -174,15 +187,15 @@ export default abstract class ProcessorImpl<F extends DataFactory = DataFactory>
     return {
       queryType: 'CONSTRUCT',
       ...this.processBaseQuery(query),
-      template: query.template?.map(triple => this.processTriple(triple)),
+      template: query.template?.map(triple => this.processTripleStrict(triple)),
     }
   }
 
   processPatterns(where: sparqljs.Pattern[]): sparqljs.Pattern[] {
-    return where.map((pattern) => this.processPattern(pattern)).filter(Boolean)
+    return where.flatMap((pattern) => this.processPattern(pattern)).filter(Boolean)
   }
 
-  processPattern(pattern: sparqljs.Pattern): sparqljs.Pattern {
+  processPattern(pattern: sparqljs.Pattern): sparqljs.Pattern | sparqljs.Pattern[] {
     return match(pattern)
       .with({ type: 'bgp' }, (bgp) => this.processBgp(bgp))
       .with({ type: 'values' }, values => this.processValues(values))
@@ -291,14 +304,31 @@ export default abstract class ProcessorImpl<F extends DataFactory = DataFactory>
     return this.factory.literal(literal.value, langOrDt)
   }
 
-  processBgp(bgp: sparqljs.BgpPattern): sparqljs.BgpPattern {
-    return {
-      ...bgp,
-      triples: bgp.triples.map(triple => this.processTriple(triple)),
-    }
+  processBgp({ triples }: sparqljs.BgpPattern): sparqljs.Pattern | sparqljs.Pattern[] {
+    let currentBgp: sparqljs.BgpPattern | undefined
+
+    return triples.reduce((patterns: sparqljs.Pattern[], triple) => {
+      const result = this.processTriple(triple)
+      const processedTriples = Array.isArray(result) ? result : [result]
+
+      return processedTriples.reduce((patterns: sparqljs.Pattern[], processedTriple) => {
+        if ('subject' in processedTriple) {
+          if (!currentBgp) {
+            currentBgp = { type: 'bgp', triples: [processedTriple] }
+            return [...patterns, currentBgp]
+          }
+
+          currentBgp.triples.push(processedTriple)
+          return patterns
+        }
+
+        currentBgp = undefined
+        return [...patterns, processedTriple]
+      }, patterns)
+    }, [])
   }
 
-  processTriple(triple: sparqljs.Triple): sparqljs.Triple {
+  processTriple(triple: sparqljs.Triple): sparqljs.Triple | sparqljs.Triple[] | sparqljs.Pattern | sparqljs.Pattern[] {
     return {
       subject: this.processTerm(triple.subject),
       predicate: match(triple.predicate)
@@ -308,6 +338,14 @@ export default abstract class ProcessorImpl<F extends DataFactory = DataFactory>
     }
   }
 
+  private processTripleStrict(triple: sparqljs.Triple): sparqljs.Triple {
+    const processed = this.processTriple(triple)
+    if (!('subject' in processed)) {
+      throw new Error('Triple must be transformed to another triple')
+    }
+    return processed
+  }
+
   processPropertyPath(path: sparqljs.PropertyPath): sparqljs.PropertyPath {
     if (path.pathType === '!') {
       return this.processNegatedPropertySet(path)
@@ -337,7 +375,7 @@ export default abstract class ProcessorImpl<F extends DataFactory = DataFactory>
     }
   }
 
-  processGroup(group: sparqljs.GroupPattern) : sparqljs.Pattern {
+  processGroup(group: sparqljs.GroupPattern): sparqljs.Pattern {
     return {
       ...group,
       patterns: this.processPatterns(group.patterns),
@@ -373,7 +411,7 @@ export default abstract class ProcessorImpl<F extends DataFactory = DataFactory>
       .with({ type: 'functionCall' }, functionCall => this.processFunctionCall(functionCall))
       .with({ type: 'aggregate' }, aggregate => aggregate)
       .when(Array.isArray, (tuple: sparqljs.Expression[]) => tuple.map(expression => this.processExpression(expression)))
-      .with({ equals: P.instanceOf(Function) }, term => this.processTerm(term))
+      .with({ termType: P.string }, term => this.processTerm(term))
       .exhaustive()
   }
 
@@ -392,7 +430,16 @@ export default abstract class ProcessorImpl<F extends DataFactory = DataFactory>
       ...operation,
       args: operation.args.map(arg =>
         match(arg)
-          .when(isPattern, operation => this.processPattern(operation))
+          .when(isPattern, operation => {
+            const processed = this.processPattern(operation)
+            if (Array.isArray(processed)) {
+              if (processed.length > 1) {
+                throw new Error('Operation argument cannot be transformed to an array')
+              }
+              return processed[0]
+            }
+            return processed
+          })
           .otherwise(() => this.processExpression(arg as sparqljs.Expression)),
       ),
     }

packages/processor/test/index.test.ts

@@ -3,6 +3,7 @@ import path from 'node:path'
 import rdf from '@zazuko/env/web.js'
 import { glob } from 'glob'
 import { expect } from 'chai'
+import type { FilterPattern, Triple } from 'sparqljs'
 import QueryProcessor from '../index.js'
 import { loadQuery, stringifyQuery } from './lib/query.js'
 
@@ -15,7 +16,8 @@ describe('@hydrofoil/sparql-processor', function () {
         const name = path.basename(file)
 
         it(`does not modify the query (${name})`, function () {
-          const processor = new (class extends QueryProcessor {})(rdf)
+          const processor = new (class extends QueryProcessor {
+          })(rdf)
 
           const processed = processor.process(loadQuery(name))
 
@@ -24,5 +26,63 @@ describe('@hydrofoil/sparql-processor', function () {
         })
       })
     })
+
+    context('replacing triples with other patterns', function () {
+      context('magic property', function () {
+        class FullTextSearchProcessor extends QueryProcessor {
+          override processTriple(triple: Triple) {
+            if ('termType' in triple.predicate && triple.predicate.value === 'http://example.org/fullTextSearch') {
+              return <FilterPattern>{
+                type: 'filter',
+                expression: {
+                  type: 'operation',
+                  operator: 'regex',
+                  args: [
+                    triple.subject,
+                    triple.object,
+                  ],
+                },
+              }
+            }
+            return super.processTriple(triple)
+          }
+        }
+
+        it('replaces triples with fullTextSearch predicate', function () {
+          const processor = new FullTextSearchProcessor(rdf)
+
+          const query = loadQuery('triple-patterns/magic-property.rq')
+          const processed = processor.process(query)
+
+          expect(stringifyQuery(processed))
+            .to.deep.equal(stringifyQuery(loadQuery('triple-patterns/magic-property.expected.rq')))
+        })
+      })
+
+      context('multiple resulting patterns', function () {
+        class FullTextSearchProcessor extends QueryProcessor {
+          override processTriple(triple: Triple) {
+            if ('type' in triple.predicate && triple.predicate.pathType === '/') {
+              return triple.predicate.items.map((predicate, index, array): Triple => {
+                const subject = index === 0 ? triple.subject : this.factory.variable(`v${index - 1}`)
+                const object = index === array.length - 1 ? triple.object : this.factory.variable(`v${index}`)
+                return { subject, predicate, object }
+              })
+            }
+            return super.processTriple(triple)
+          }
+        }
+
+        it('replaces one triples with multiple', function () {
+          const processor = new FullTextSearchProcessor(rdf)
+
+          const query = loadQuery('triple-patterns/sequence.rq')
+          const processed = processor.process(query)
+
+          expect(stringifyQuery(processed))
+            .to.deep.equal(stringifyQuery(loadQuery('triple-patterns/sequence.expected.rq')))
+        })
+      })
+    })
   })
 })

packages/processor/test/queries/triple-patterns/magic-property.expected.rq

@@ -0,0 +1,8 @@
+PREFIX ex: <http://example.org/>
+PREFIX schema: <http://schema.org/>
+
+SELECT * {
+    ?s a schema:Person ; schema:name ?name .
+    FILTER(REGEX(?name, "John*"))
+    ?s schema:knows ex:JaneDoe .
+}

packages/processor/test/queries/triple-patterns/magic-property.rq

@@ -0,0 +1,8 @@
+PREFIX ex: <http://example.org/>
+PREFIX schema: <http://schema.org/>
+
+SELECT * {
+    ?s a schema:Person ; schema:name ?name .
+    ?name ex:fullTextSearch "John*" .
+    ?s schema:knows ex:JaneDoe .
+}

packages/processor/test/queries/triple-patterns/sequence.expected.rq

@@ -0,0 +1,9 @@
+PREFIX ex: <http://example.org/>
+PREFIX schema: <http://schema.org/>
+
+SELECT * {
+    ?s a schema:Person .
+    ?s schema:knows ?v0 .
+    ?v0 schema:knows ?friend  .
+    ?s schema:name ?name .
+}

packages/processor/test/queries/triple-patterns/sequence.rq

@@ -0,0 +1,8 @@
+PREFIX ex: <http://example.org/>
+PREFIX schema: <http://schema.org/>
+
+SELECT * {
+    ?s a schema:Person .
+    ?s schema:knows/schema:knows ?friend  .
+    ?s schema:name ?name .
+}

packages/shape-to-query/lib/optimizer/BlankNodeScopeFixer.ts

@@ -26,7 +26,7 @@ export class BlankNodeScopeFixer extends Processor<Environment<TermMapFactory |
   }
 
   processUnion(union: UnionPattern): Pattern {
-    const patterns = union.patterns.map(pattern => {
+    const patterns = union.patterns.flatMap(pattern => {
       this.incrementScope()
       return this.processPattern(pattern)
     })

packages/shape-to-query/lib/optimizer/UnionRepeatedPatternsRemover.ts

@@ -102,7 +102,7 @@ export class UnionRepeatedPatternsRemover extends Processor {
     return processed
   }
 
-  processBgp(bgp: BgpPattern): BgpPattern {
+  processBgp(bgp: BgpPattern) {
     if (this.union) {
       // remove repeated triples from the bgp
       bgp.triples = bgp.triples.filter(triple => {