o-dataset-pack

An RDFJS dataset that alerts upon the update of a node

Usage no npm install needed!

<script type="module">
  import oDatasetPack from 'https://cdn.skypack.dev/o-dataset-pack';
</script>

README

O Dataset Pack

A library of RDFJS Datasets that have many uses including subscribing to node changes and making transactions on a dataset.

This library follows the RDFJS spec for a Dataset.

Installation

npm install o-dataset-pack

Simple Examples

ExtendedDataset

import { createDataset } from "o-dataset-pack";
import { quad, namedNode } from "@rdfjs/data-model";
const dataset = createDataset();
dataset.add(
  quad(
    namedNode("http://example.org/cartoons#Zuko"),
    namedNode("http://www.w3.org/1999/02/22-rdf-syntax-ns#type"),
    namedNode("http://example.org/cartoons#Firebender")
  )
);
/*
Prints:
<http://example.org/cartoons#Zuko> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://example.org/cartoons#Firebender> .
*/
console.log(dataset.toString());

SubscribableDataset

import { createSubscribableDataset, DatasetChanges } from "o-dataset-pack";
import { Dataset } from "@rdfjs/types";
import { quad, namedNode, literal } from "@rdfjs/data-model";

const subscribableDataset = createSubscribableDataset([
  quad(
    namedNode("http://example.org/cartoons#Zuko"),
    namedNode("http://www.w3.org/1999/02/22-rdf-syntax-ns#type"),
    namedNode("http://example.org/cartoons#Firebender")
  ),
]);
subscribableDataset.on(
  namedNode("http://example.org/cartoons#Zuko"),
  (currentQuads: Dataset, changes: DatasetChanges) => {
    console.log(currentQuads.toString());
    console.log("--------");
    console.log(changes.added?.toString());
  }
);
/*
Prints:
<http://example.org/cartoons#Zuko> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://example.org/cartoons#Firebender> .
<http://example.org/cartoons#Zuko> <http://example.org/cartoons#name> "Zuko" .
--------
<http://example.org/cartoons#Zuko> <http://example.org/cartoons#name> "Zuko" .
*/
subscribableDataset.add(
  quad(
    namedNode("http://example.org/cartoons#Zuko"),
    namedNode("http://example.org/cartoons#name"),
    literal("Zuko")
  )
);

Loading from Serialized Data

import { serializedToDataset, serializedToSubscribableDataset } from "o-dataset-pack";

async function run(): Promise<void> {
  // Create an ExtendedDataset using Turtle
  const turtleData = `
    @prefix : <#>.
    @prefix elem: <http://purl.org/dc/elements/1.1/>.
    @prefix card: </profile/card#>.
    
    :this
        elem:author card:me.
  `;
  const turtleDataset = await serializedToDataset(turtleData, {
    baseIRI:
      "https://jackson.solidcommunity.net/IndividualChats/jackson.solidcommunity.net/index.ttl#",
    // NOTE: the "format" field isn't required because Turtle is the default parser
  });

  // Create a SubcribableDataset using JSON-LD
  const jsonLdData = [
    {
      "@id":
        "https://jackson.solidcommunity.net/IndividualChats/jackson.solidcommunity.net/index.ttl#this",
      "http://purl.org/dc/elements/1.1/author": [
        {
          "@id": "https://jackson.solidcommunity.net/profile/card#me",
        },
      ],
    },
    {
      "@id": "https://jackson.solidcommunity.net/profile/card#me",
    },
  ];
  const jsonLdDataset = await serializedToSubscribableDataset(
    JSON.stringify(jsonLdData),
    {
      baseIRI:
        "https://jackson.solidcommunity.net/IndividualChats/jackson.solidcommunity.net/index.ttl#",
      format: "application/json-ld",
    }
  );
  // Returns true because the input data describes the same triple.
  console.log(turtleDataset.equals(jsonLdDataset));
}
run();

API

See the full API docs.

ExtendedDataset

The extended dataset implements all the additional methods of the RDFJS dataset spec.

Usage:

import { createDataset } from "o-dataset-pack";
import { quad, namedNode, literal } from "@rdfjs/data-model";
// Required for advanced features:
import { dataset as initializeDatasetCore } from "@rdfjs/dataset";
import { ExtendedDatasetFactory } from "o-dataset-pack";
import { Dataset, Quad, DatasetCoreFactory, DatasetCore } from "rdf-js";

/**
 * Create a dataset with default settings
 */
const defaultDataset = createDataset();

/**
 * Create a dataset with default settings and initialized values
 */
const initializedQuads = [
  quad(
    namedNode("http://example.org/cartoons#Tom"),
    namedNode("http://www.w3.org/1999/02/22-rdf-syntax-ns#type"),
    namedNode("http://example.org/cartoons#Cat")
  ),
  quad(
    namedNode("http://example.org/cartoons#Tom"),
    namedNode("http://example.org/cartoons#name"),
    literal("Tom")
  ),
];
const defaultDataset2 = createDataset(initializedQuads);

/**
 * (Advanced Feature) Create a dataset by injecting a chosen datasetCore and datasetCoreFactory
 */
const datasetFactory: DatasetCoreFactory = {
  dataset: (quads?: Dataset<Quad> | Quad[]): DatasetCore => {
    return initializeDatasetCore(
      Array.isArray(quads) ? quads : quads?.toArray()
    );
  },
};
const extendedDatasetFactory = new ExtendedDatasetFactory(datasetFactory);
const customDataset = extendedDatasetFactory.dataset(initializedQuads);

/**
 * Do all the methods of the RDFJS Dataset interface. For a full list of methods, go to
 * https://rdf.js.org/dataset-spec/#data-interfaces
 */
defaultDataset.add(
  quad(
    namedNode("http://example.org/cartoons#Miuki"),
    namedNode("http://www.w3.org/1999/02/22-rdf-syntax-ns#type"),
    namedNode("http://example.org/cartoons#Cat")
  )
);
const combinedDataset = defaultDataset.union(defaultDataset2);
const differenceDataset = combinedDataset.difference(customDataset);
// Prints true because "defaultDataset2" and "customDataset" have equal values
// combinedDataset = defaultDataset ∪ defaultDataset2
// differenceDatasset = defaultDataset \ customDataset
// Therefore differenceDataset == defaultDataset
console.log(differenceDataset.equals(defaultDataset));

SubscribableDataset

import { createSubscribableDataset, DatasetChanges } from "o-dataset-pack";
import { quad, namedNode, literal } from "@rdfjs/data-model";
import { Dataset } from "@rdfjs/types";

// Create an empty subscribable dataset
const subscribableDataset = createSubscribableDataset();
// Add some initial quads
subscribableDataset.addAll([
  quad(
    namedNode("http://example.org/cartoons#Zuko"),
    namedNode("http://www.w3.org/1999/02/22-rdf-syntax-ns#type"),
    namedNode("http://example.org/cartoons#Firebender"),
    namedNode("http://example.org/cartoons")
  ),
  quad(
    namedNode("http://example.org/cartoons#Zuko"),
    namedNode("http://example.org/cartoons#name"),
    literal("Zuko"),
    namedNode("http://example.org/cartoons")
  ),
]);
// Set up listeners
// Listener that will trigger whenever a quad containing the named
// node "http://example.org/cartoons#Zuko" is added or removed.
subscribableDataset.on(
  namedNode("http://example.org/cartoons#Zuko"),
  (zukoQuads: Dataset, changes: DatasetChanges) => {
    console.log("ZUKO NODE CHANGED ============");
    console.log(zukoQuads.toString());
    console.log("Added Quads:");
    console.log(changes.added?.toString());
    console.log("Removed Quads:");
    console.log(changes.removed?.toString());
    console.log("\n\n");
  }
);
// Listener that will trigger whenever a quad containing the named
// node "http://example.org/cartoons" is added or removed. This is
// useful for keeping track of the cartoons graph.
subscribableDataset.on(
  namedNode("http://example.org/cartoons"),
  (cartoonGraphQuads: Dataset, changes: DatasetChanges) => {
    console.log("CARTOON GRAPH CHANGED ============");
    console.log(cartoonGraphQuads.toString());
    console.log("Added Quads:");
    console.log(changes.added?.toString());
    console.log("Removed Quads:");
    console.log(changes.removed?.toString());
    console.log("\n\n");
  }
);

// Modify the dataset
/*
Prints:
CARTOON GRAPH CHANGED ============
<http://example.org/cartoons#Zuko> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://example.org/cartoons#Firebender> <http://example.org/cartoons> .
<http://example.org/cartoons#Zuko> <http://example.org/cartoons#name> "Zuko" <http://example.org/cartoons> .
<http://example.org/cartoons#Katara> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://example.org/cartoons#Waterbender> <http://example.org/cartoons> .
<http://example.org/cartoons#Katara> <http://example.org/cartoons#name> "Katara" <http://example.org/cartoons> .

Added Quads:
<http://example.org/cartoons#Katara> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://example.org/cartoons#Waterbender> <http://example.org/cartoons> .
<http://example.org/cartoons#Katara> <http://example.org/cartoons#name> "Katara" <http://example.org/cartoons> .

Removed Quads:
undefined
 */
subscribableDataset.addAll([
  quad(
    namedNode("http://example.org/cartoons#Katara"),
    namedNode("http://www.w3.org/1999/02/22-rdf-syntax-ns#type"),
    namedNode("http://example.org/cartoons#Waterbender"),
    namedNode("http://example.org/cartoons")
  ),
  quad(
    namedNode("http://example.org/cartoons#Katara"),
    namedNode("http://example.org/cartoons#name"),
    literal("Katara"),
    namedNode("http://example.org/cartoons")
  ),
]);

/*
Prints:
ZUKO NODE CHANGED ============
<http://example.org/cartoons#Zuko> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://example.org/cartoons#Firebender> <http://example.org/cartoons> .
<http://example.org/cartoons#Zuko> <http://example.org/cartoons#name> "Zuko" <http://example.org/cartoons> .
<http://example.org/cartoons#Zuko> <http://example.org/cartoons#hasEnemy> <http://example.org/cartoons#Katara> <http://example.org/cartoons> .
<http://example.org/cartoons#Katara> <http://example.org/cartoons#hasEnemy> <http://example.org/cartoons#Zuko> <http://example.org/cartoons> .

Added Quads:
<http://example.org/cartoons#Katara> <http://example.org/cartoons#hasEnemy> <http://example.org/cartoons#Zuko> <http://example.org/cartoons> .
<http://example.org/cartoons#Zuko> <http://example.org/cartoons#hasEnemy> <http://example.org/cartoons#Katara> <http://example.org/cartoons> .

Removed Quads:
undefined


CARTOON GRAPH CHANGED ============
<http://example.org/cartoons#Zuko> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://example.org/cartoons#Firebender> <http://example.org/cartoons> .
<http://example.org/cartoons#Zuko> <http://example.org/cartoons#name> "Zuko" <http://example.org/cartoons> .
<http://example.org/cartoons#Zuko> <http://example.org/cartoons#hasEnemy> <http://example.org/cartoons#Katara> <http://example.org/cartoons> .
<http://example.org/cartoons#Katara> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://example.org/cartoons#Waterbender> <http://example.org/cartoons> .
<http://example.org/cartoons#Katara> <http://example.org/cartoons#name> "Katara" <http://example.org/cartoons> .
<http://example.org/cartoons#Katara> <http://example.org/cartoons#hasEnemy> <http://example.org/cartoons#Zuko> <http://example.org/cartoons> .

Added Quads:
<http://example.org/cartoons#Katara> <http://example.org/cartoons#hasEnemy> <http://example.org/cartoons#Zuko> <http://example.org/cartoons> .
<http://example.org/cartoons#Zuko> <http://example.org/cartoons#hasEnemy> <http://example.org/cartoons#Katara> <http://example.org/cartoons> .

Removed Quads:
undefined
*/
subscribableDataset.addAll([
  quad(
    namedNode("http://example.org/cartoons#Katara"),
    namedNode("http://example.org/cartoons#hasEnemy"),
    namedNode("http://example.org/cartoons#Zuko"),
    namedNode("http://example.org/cartoons")
  ),
  quad(
    namedNode("http://example.org/cartoons#Zuko"),
    namedNode("http://example.org/cartoons#hasEnemy"),
    namedNode("http://example.org/cartoons#Katara"),
    namedNode("http://example.org/cartoons")
  ),
]);

// If there are many operation you want to do at once, use transactions.
// An update will not be triggered until the transaction is committed.
const transactionalDataset = subscribableDataset.startTransaction();
// Delete all triples with a "hasEnemy" predicate
transactionalDataset.deleteMatches(
  undefined,
  namedNode("http://example.org/cartoons#hasEnemy"),
  undefined,
  undefined
);
// Add "hasFrient" predicate
transactionalDataset.addAll([
  quad(
    namedNode("http://example.org/cartoons#Katara"),
    namedNode("http://example.org/cartoons#hasFriend"),
    namedNode("http://example.org/cartoons#Zuko"),
    namedNode("http://example.org/cartoons")
  ),
  quad(
    namedNode("http://example.org/cartoons#Zuko"),
    namedNode("http://example.org/cartoons#hasFriend"),
    namedNode("http://example.org/cartoons#Katara"),
    namedNode("http://example.org/cartoons")
  ),
]);
/*
Prints:
ZUKO NODE CHANGED ============
<http://example.org/cartoons#Zuko> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://example.org/cartoons#Firebender> <http://example.org/cartoons> .
<http://example.org/cartoons#Zuko> <http://example.org/cartoons#name> "Zuko" <http://example.org/cartoons> .
<http://example.org/cartoons#Zuko> <http://example.org/cartoons#hasFriend> <http://example.org/cartoons#Katara> <http://example.org/cartoons> .
<http://example.org/cartoons#Katara> <http://example.org/cartoons#hasFriend> <http://example.org/cartoons#Zuko> <http://example.org/cartoons> .

Added Quads:
<http://example.org/cartoons#Katara> <http://example.org/cartoons#hasFriend> <http://example.org/cartoons#Zuko> <http://example.org/cartoons> .
<http://example.org/cartoons#Zuko> <http://example.org/cartoons#hasFriend> <http://example.org/cartoons#Katara> <http://example.org/cartoons> .

Removed Quads:
<http://example.org/cartoons#Katara> <http://example.org/cartoons#hasEnemy> <http://example.org/cartoons#Zuko> <http://example.org/cartoons> .
<http://example.org/cartoons#Zuko> <http://example.org/cartoons#hasEnemy> <http://example.org/cartoons#Katara> <http://example.org/cartoons> .


CARTOON GRAPH CHANGED ============
<http://example.org/cartoons#Zuko> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://example.org/cartoons#Firebender> <http://example.org/cartoons> .
<http://example.org/cartoons#Zuko> <http://example.org/cartoons#name> "Zuko" <http://example.org/cartoons> .
<http://example.org/cartoons#Zuko> <http://example.org/cartoons#hasFriend> <http://example.org/cartoons#Katara> <http://example.org/cartoons> .
<http://example.org/cartoons#Katara> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://example.org/cartoons#Waterbender> <http://example.org/cartoons> .
<http://example.org/cartoons#Katara> <http://example.org/cartoons#name> "Katara" <http://example.org/cartoons> .
<http://example.org/cartoons#Katara> <http://example.org/cartoons#hasFriend> <http://example.org/cartoons#Zuko> <http://example.org/cartoons> .

Added Quads:
<http://example.org/cartoons#Katara> <http://example.org/cartoons#hasFriend> <http://example.org/cartoons#Zuko> <http://example.org/cartoons> .
<http://example.org/cartoons#Zuko> <http://example.org/cartoons#hasFriend> <http://example.org/cartoons#Katara> <http://example.org/cartoons> .

Removed Quads:
<http://example.org/cartoons#Katara> <http://example.org/cartoons#hasEnemy> <http://example.org/cartoons#Zuko> <http://example.org/cartoons> .
<http://example.org/cartoons#Zuko> <http://example.org/cartoons#hasEnemy> <http://example.org/cartoons#Katara> <http://example.org/cartoons> .
*/
transactionalDataset.commit();

License

MIT