@comunica/utils-bindings-factory

Comunica Bindings Factory

This package provides a factory for Bindings objects, which allow variables to be mapped to RDF terms. This package implements the RDF/JS BindingsFactory and Bindings interfaces.

Internally, it makes use of immutable to make sure that operations such as set and delete reuse internal memory when possible.

This module is part of the Comunica framework, and should only be used by developers that want to build their own query engine.

Click here if you just want to query with Comunica.

Install

$ yarn add @comunica/utils-bindings-factory

Usage

import * as RDF from '@rdfjs/types';
import { DataFactory } from '@comunica/utils-data-factory';
import { BindingsFactory } from '@comunica/utils-bindings-factory';

const DF = new DataFactory();
const BF = new BindingsFactory(DF);

const bindings1: RDF.Bindings = BF.bindings([
  [ DF.variable('var1'), DF.literal('abc') ],
  [ DF.variable('var2'), DF.literal('def') ],
]);

const bindings2: RDF.Bindings = BF.fromRecord({
  var1: DF.literal('abc'),
  var2: DF.literal('def'),
});

Factory methods

Factory instances can be used as follows.

Creating new bindings

Bindings can either be created by passing key-value pairs, or in record-form:

const bindings1: RDF.Bindings = BF.bindings([
  [ DF.variable('var1'), DF.literal('abc') ],
  [ DF.variable('var2'), DF.literal('def') ],
]);

const bindings2: RDF.Bindings = BF.fromRecord({
  var1: DF.literal('abc'),
  var2: DF.literal('def'),
});

Cloning bindings

Bindings can be cloned as follows:

const clonedBindings = BF.fromBindings(otherBindings);

Bindings methods

The following methods are exposed on bindings created by the factory.

Since all bindings are immutable, the original bindings instances will never be changed.

Bindings.has()

The has() method is used to check if a value exists for the given variable. The variable can either be supplied as a string (without ? prefix), or as an RDF/JS variable.

if (bindings.has('var1')) {
  console.log('Has var1!');
}
if (bindings.has(DF.variable('var2'))) {
  console.log('Has var2!');
}

Bindings.get()

The get() method is used to read the bound value of variable. The variable can either be supplied as a string (without ? prefix), or as an RDF/JS variable.

const term1: RDF.Term | undefined = bindings.get('var1');
const term2: RDF.Term | undefined = bindings.get(DF.variable('var2'));

Bindings.set()

The set() method is used to create a copy of the current bindings object, with the addition of a new variable binding. The variable can either be supplied as a string (without ? prefix), or as an RDF/JS variable.

const newBindings = bindings
  .set('var1', DF.namedNode('ex:term1'))
  .set(DF.variable('var2'), DF.namedNode('ex:term2'));

Bindings.delete()

The delete() method is used to create a copy of the current bindings object, with the removal of a variable binding. The variable can either be supplied as a string (without ? prefix), or as an RDF/JS variable.

const newBindings = bindings
  .delete('var1')
  .delete(DF.variable('var2'));

Bindings.keys()

The keys() method returns an iterable over all the RDF/JS variable keys that have a value in this bindings object.

for (const variable of bindings.keys()) {
  console.log(variable);
}

Bindings.values()

The values() method returns an iterable over all the RDF/JS term values that have a key in this bindings object.

for (const term of bindings.values()) {
  console.log(term);
}

Bindings.forEach()

The forEach() method iterates over all entries in this bindings object and invokes the callback with the RDF/JS term value and RDF/JS variable key of each entry.

bindings.forEach((value, key) => {
  console.log(key);
  console.log(value);
})

Bindings.size

The size field returns the number of key-value entries in the bindings object.

console.log(bindings.size);

Entry iteration

Each bindings object is an Iterable over its key-value entries, where each entry is a tuple of type [RDF.Variable, RDF.Term].

// Iterate over all entries
for (const [ key, value ] of bindings) {
  console.log(key);
  console.log(value);
}

// Save the entries in an array
const entries = [ ...bindings ];

Bindings.equals

The equals() method checks if the entries of this bindings object equal the entries in another bindings object.

bindings1.equals(bindings2);

Bindings.filter

The filter() method creates a new bindings object by filtering entries using a callback. The callback is applied on each entry. Returning true indicates that this entry must be contained in the resulting bindings object.

const filteredBindings = bindings.filter((value, key) => {
  return key.value !== 'abc';
});

Bindings.map

The map() method creates a new bindings object by mapping entries using a callback. The callback is applied on each entry in which the original value is replaced by the returned value.

const mappedBindings = bindings.map((value, key) => {
  return DF.namedNode(value.value + '_modified');
});

Bindings.merge

The merge() method merges the entries of this bindings object with all entries of another bindings object. If a merge conflict occurs (this and other have an equal variable with unequal value), then undefined is returned.

const mergedBindings = bindings1.merge(bindings2);

Bindings.mergeWith

The mergeWith() method merges this bindings object with another where merge conflicts can be resolved using a callback function. The callback function that is invoked when a merge conflict occurs, for which the returned value is considered the merged value.

const mergedBindings = bindings1.mergeWith((self, other, key) => {
  return DF.namedNode(self.value + other.value);
}, bindings2);

Bindings.toString

The toString() method returns a compact string representation of the bindings object, which can be useful for debugging.

console.log(bindings.toString());

/*
Can output in the form of:
{
  "a": "ex:a",
  "b": "ex:b",
  "c": "ex:c"
}
 */