Merge pull request #62 from commitd/stuarthendren/issue60

feat(rdf): adds label decorators and rdf procesing options

Author: stuarthendren

packages/graph-rdf/src/RdfGraph.test.ts

@@ -30,7 +30,7 @@ it('Create from ttl string', () => {
 })
 
 it('Create from ttl string using prefixes', () => {
-  const contentModel = buildGraph(sample, { usePrefix: true })
+  const contentModel = buildGraph(sample, { usePrefixId: true })
   expect(Object.keys(contentModel.nodes)).toHaveLength(16)
   expect(Object.keys(contentModel.edges)).toHaveLength(13)
 
@@ -51,7 +51,7 @@ it('Create from ttl string using prefixes', () => {
 
 it('Can process literals to rdf literal string', () => {
   const contentModel = buildGraph(sample, {
-    usePrefix: true,
+    usePrefixId: true,
     literals: LiteralOption.AS_STRING,
   })
   const node = contentModel.getNode('txn:123') as ModelNode
@@ -65,7 +65,7 @@ it('Can process literals to rdf literal string', () => {
 
 it('Can process literals to value only', () => {
   const contentModel = buildGraph(sample, {
-    usePrefix: true,
+    usePrefixId: true,
     literals: LiteralOption.VALUE_ONLY,
   })
   const node = contentModel.getNode('txn:123') as ModelNode
@@ -77,7 +77,7 @@ it('Can process literals to value only', () => {
 
 it('Can parse simple example by adding missing prefixes', () => {
   const contentModel = buildGraph(small, {
-    usePrefix: true,
+    usePrefixId: true,
     additionalPrefixes: {
       owl: 'http://www.w3.org/2002/07/owl#',
       xsd: 'http://www.w3.org/2001/XMLSchema#',
@@ -143,7 +143,7 @@ it('Decorates by default', () => {
 
 it('Decorates by default', () => {
   const contentModel = buildGraph(decorated, {
-    usePrefix: true,
+    usePrefixId: true,
     decorate: false,
     literals: LiteralOption.VALUE_ONLY,
   })

packages/graph-rdf/src/RdfGraph.ts

@@ -1,4 +1,4 @@
-import { ContentModel, ModelEdge, ModelNode } from '@committed/graph'
+import { ContentModel, ModelEdge, ModelItem, ModelNode } from '@committed/graph'
 import {
   DataFactory,
   Literal,
@@ -69,26 +69,39 @@ export enum LiteralOption {
 }
 
 export enum RdfFormat {
-  /** Suports a permissive superset of Turtle, TriG, N-Triple and N-Quad */
+  /** Supports a permissive superset of Turtle, TriG, N-Triple and N-Quad */
   Turtle = 'turtle',
   /** Supports N3 format */
   N3 = 'N3',
 }
 
 export interface RdfOptions {
-  usePrefix: boolean
+  /** use the prefix in the node ids */
+  usePrefixId: boolean
+  /** Define how literals are converted to be used in the graph */
   literals: LiteralOption
+  /** Declare the serialization format of the RDF */
   format: RdfFormat
+  /** Transfer declarations from the http://ont.committed.io/graph/decorator namespace to decoration properties of the graph */
   decorate: boolean
+  /** Declare the attribute to use as the label */
   label?: string
+  /** Declare the property to use as the node type */
   type?: string
+  /** Declare the base IRI of the graph */
   baseIRI?: string
+  /** Declare a blank node prefix to be used */
   blankNodePrefix?: string
+  /** Add additional prefixes to the used */
   additionalPrefixes?: Record<string, string>
+  /** Node processor to apply to nodes after conversion */
+  nodeProcessor?: (node: ModelNode) => ModelNode
+  /** Edge processor to apply to edges after conversion */
+  edgeProcessor?: (edge: ModelEdge) => ModelEdge
 }
 
 export const DEFAULT_RDF_OPTIONS: RdfOptions = {
-  usePrefix: false,
+  usePrefixId: false,
   literals: LiteralOption.AS_OBJECT,
   format: RdfFormat.Turtle,
   label: rdfsLabel.value,
@@ -97,7 +110,10 @@ export const DEFAULT_RDF_OPTIONS: RdfOptions = {
 }
 
 interface GraphBuilderOptions
-  extends Pick<RdfOptions, 'usePrefix' | 'literals' | 'decorate'> {
+  extends Pick<
+    RdfOptions,
+    'usePrefixId' | 'literals' | 'decorate' | 'nodeProcessor' | 'edgeProcessor'
+  > {
   prefixes: Record<string, string>
   label?: NamedNode
   type?: NamedNode
@@ -120,9 +136,29 @@ class GraphBuilder {
     this.triples.forEach((t) => this.addTriple(t))
     this.attributes.forEach((t) => this.addAttribute(t))
 
+    this.processNodes()
+    this.processEdges()
     return ContentModel.fromRaw({ nodes: this.nodes, edges: this.edges })
   }
 
+  private processNodes() {
+    const nodeProcessor = this.options.nodeProcessor
+    if (nodeProcessor !== undefined) {
+      Object.keys(this.nodes).forEach((key) => {
+        this.nodes[key] = nodeProcessor(this.nodes[key])
+      })
+    }
+  }
+
+  private processEdges() {
+    const edgeProcessor = this.options.edgeProcessor
+    if (edgeProcessor !== undefined) {
+      Object.keys(this.edges).forEach((key) => {
+        this.edges[key] = edgeProcessor(this.edges[key])
+      })
+    }
+  }
+
   private addTriple(t: Triple): void {
     if (t.object.termType === 'Literal') {
       this.attributes.push(t)
@@ -213,7 +249,7 @@ class GraphBuilder {
   }
 
   toPrefixedId(id: string): string {
-    if (this.options.usePrefix) {
+    if (this.options.usePrefixId) {
       const match = Object.keys(this.options.prefixes).find((prefix) =>
         id.startsWith(prefix)
       )
@@ -300,7 +336,7 @@ export function buildGraph(
   )
 
   const builderOptions = {
-    label: label !== undefined ? DataFactory.namedNode(label) : undefined,
+    label: typeof label === 'string' ? DataFactory.namedNode(label) : undefined,
     type: type !== undefined ? DataFactory.namedNode(type) : undefined,
     prefixes,
     ...rest,

packages/graph-rdf/src/index.ts

@@ -1 +1,2 @@
 export * as Rdf from './RdfGraph'
+export * as RdfUtil from './utils'

packages/graph-rdf/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './labels'
+export * from './processors'

packages/graph-rdf/src/utils/labels.test.ts

@@ -0,0 +1,32 @@
+import { labelWithPrefix, labelWithFragment } from './labels'
+
+it('Can label by prefixed id', () => {
+  const decorator = labelWithPrefix({
+    'https://example.org/data/': 'data',
+    'https://example.org/demo#': 'demo',
+  })
+
+  expect(
+    decorator({ id: 'https://example.org/data/test', attributes: {} }).label
+  ).toBe('data:test')
+  expect(
+    decorator({ id: 'https://example.org/demo#TEST', attributes: {} }).label
+  ).toBe('demo:TEST')
+  expect(
+    decorator({ id: 'https://example.org/other', attributes: {} }).label
+  ).toBe('https://example.org/other')
+})
+
+it('Can label by id fragment', () => {
+  const decorator = labelWithFragment()
+
+  expect(
+    decorator({ id: 'https://example.org/data/test', attributes: {} }).label
+  ).toBe('test')
+  expect(
+    decorator({ id: 'https://example.org/demo#TEST', attributes: {} }).label
+  ).toBe('TEST')
+  expect(
+    decorator({ id: 'https://example.org/other', attributes: {} }).label
+  ).toBe('other')
+})

packages/graph-rdf/src/utils/labels.ts

@@ -0,0 +1,55 @@
+import { ModelItem } from '@committed/graph'
+
+const labelNodeBy =
+  <T extends ModelItem>(mapping: (item: T) => string) =>
+  (item: T) => ({ label: mapping(item) })
+
+const idTo = (mapping: (id: string) => string) => (item: ModelItem) =>
+  mapping(item.id)
+
+export const prefixedId =
+  (prefixes: Record<string, string>) =>
+  (id: string): string => {
+    const match = Object.keys(prefixes).find((prefix) => id.startsWith(prefix))
+    if (match !== undefined) {
+      const prefix = prefixes[match]
+      return `${prefix}:${id.substr(match.length)}`
+    }
+    return id
+  }
+
+export const fragmentId = (id: string): string => {
+  try {
+    const url = new URL(id)
+    const hash = url.hash
+    if (hash) {
+      return hash.substr(1)
+    }
+    const path = url.pathname
+    return path.substring(path.lastIndexOf('/') + 1)
+  } catch (e) {
+    return id
+  }
+}
+
+/**
+ *
+ * Creates a decorator to map ids to labels with RDF style prefixes using the provided prefixes.
+ *
+ * @param prefixes map of prefix to full URI
+ * @returns item decorator
+ */
+export const labelWithPrefix = <T extends ModelItem>(
+  prefixes: Record<string, string>
+): ((item: T) => { label: string }) =>
+  labelNodeBy<T>(idTo(prefixedId(prefixes)))
+
+/**
+ *
+ * Creates a decorator to map ids to labels using the fragment of the URL or last path part
+ *
+ * @returns item decorator
+ */
+export const labelWithFragment = <T extends ModelItem>(): ((item: T) => {
+  label: string
+}) => labelNodeBy<T>(idTo(fragmentId))

packages/graph-rdf/src/utils/processors.test.ts

@@ -0,0 +1,80 @@
+import { ModelEdge, ModelNode } from '@committed/graph'
+import { cleanProcessor } from './processors'
+
+it('Can label by fragment id', () => {
+  expect(
+    cleanProcessor<ModelNode>({
+      id: 'https://example.org/data/test',
+      attributes: {},
+    }).label
+  ).toBe('test')
+  expect(
+    cleanProcessor<ModelNode>({
+      id: 'https://example.org/demo#TEST',
+      attributes: {},
+    }).label
+  ).toBe('TEST')
+  expect(cleanProcessor<ModelNode>({ id: 'test', attributes: {} }).label).toBe(
+    'test'
+  )
+  expect(
+    cleanProcessor<ModelNode>({ id: 'test', label: 'label', attributes: {} })
+      .label
+  ).toBe('label')
+})
+
+it('Can clean attribute labels', () => {
+  expect(
+    cleanProcessor<ModelNode>({
+      id: 'https://example.org/data/test',
+      attributes: { 'https://example.org/data/test': 'test' },
+    }).attributes
+  ).toStrictEqual({ test: 'test' })
+  expect(
+    cleanProcessor<ModelNode>({
+      id: 'https://example.org/demo#TEST',
+      attributes: {
+        'https://example.org/demo#TEST': 'TEST',
+      },
+    }).attributes
+  ).toStrictEqual({ TEST: 'TEST' })
+  expect(
+    cleanProcessor<ModelNode>({ id: 'test', attributes: { test: 'test' } })
+      .attributes
+  ).toStrictEqual({ test: 'test' })
+})
+
+it('Can process type', () => {
+  expect(
+    cleanProcessor<ModelNode>({
+      id: 'https://example.org/demo#TEST',
+      attributes: { type: 'https://example.org/demo#TEST' },
+    }).attributes
+  ).toStrictEqual({ type: 'TEST' })
+})
+
+it('Can rewite label if equal id or matches edge predicate format', () => {
+  expect(
+    cleanProcessor<ModelNode>({
+      id: 'https://example.org/data/test',
+      label: 'https://example.org/data/test',
+      attributes: {},
+    }).label
+  ).toBe('test')
+  expect(
+    cleanProcessor<ModelEdge>({
+      id: 'https://example.org/demo#source|https://example.org/demo#TEST|https://example.org/demo#target',
+      source: 'https://example.org/demo#source',
+      target: 'https://example.org/demo#target',
+      label: 'https://example.org/demo#TEST',
+      attributes: {},
+    }).label
+  ).toBe('TEST')
+  expect(cleanProcessor<ModelNode>({ id: 'test', attributes: {} }).label).toBe(
+    'test'
+  )
+  expect(
+    cleanProcessor<ModelNode>({ id: 'test', label: 'label', attributes: {} })
+      .label
+  ).toBe('label')
+})

packages/graph-rdf/src/utils/processors.ts

@@ -0,0 +1,29 @@
+import { ModelAttributeSet, ModelEdge, ModelNode } from '@committed/graph'
+import { fragmentId } from './labels'
+
+/**
+ *
+ * @param item Opinionated function to process rdf nodes and edges for a cleaner presentation in the graph
+ * @returns
+ */
+export const cleanProcessor = <T extends ModelNode | ModelEdge>(item: T): T => {
+  if (typeof item.label === 'string' && item.id.includes(`|${item.label}|`)) {
+    item.label = fragmentId(item.label)
+  }
+
+  if (item.label === undefined || item.label === item.id) {
+    item.label = fragmentId(item.id)
+  }
+
+  if (typeof item.attributes.type === 'string') {
+    item.attributes.type = fragmentId(item.attributes.type)
+  }
+
+  const attributes: ModelAttributeSet = {}
+  Object.keys(item.attributes).forEach((key) => {
+    attributes[fragmentId(key)] = item.attributes[key]
+  })
+  item.attributes = attributes
+
+  return item
+}