LDO (Linked Data Objects) is a library that lets you easily manipulate RDF as if it were a standard TypeScript object that follows a [ShEx](https://shex.io) shape you define.
`@ldo/ldo` is the primary interface for accessing Linked Data Objects given raw RDF.
For a full tutorial of using LDO to build React Solid applications, see [this tutorial](https://medium.com/@JacksonMorgan/building-solid-apps-with-ldo-6127a5a1979c).
## Guide
## Setup
A full walkthrough for using the `@ldo/ldo` library can be found in the [For RDF Usage Guide](https://ldo.js.org/raw_rdf/).
### Automatic Setup
To setup LDO, `cd` into your typescript project and run `npx @ldo/cli init`.
## Installation
```bash
cd my-typescript-project
npx @ldo/cli init
```
### Manual Setup
The following is handled by the __automatic setup__:
Install the LDO dependencies.
```bash
npm install @ldo/ldo
npm install @ldo/cli --save-dev
```
### Automatic Installation
Create a folder to store your ShEx shapes:
```bash
mkdir shapes
Navigate into your project's root folder and run the following command:
```
Create a script to build ShEx shapes and convert them into Linked Data Objects. You can put this script in `package.json`
LDO uses [ShEx](https://shex.io) as a schema for the RDF data in your project. To add a ShEx schema to your project, simply create a file ending in `.shex` to the `shapes` folder.
For more information on writing ShEx schemas see the [ShEx Primer](http://shex.io/shex-primer/index.html).
Below is a simple example of LDO in a real use-case (changing the name on a Solid Pod)
Below is a simple example of LDO in a real use-case (changing the name on a Solid Pod). Assume that a ShapeType was previously generated and placed at `./.ldo/foafProfile.shapeTypes`.
```typescript
import { parseRdf, startTransaction, toSparqlUpdate, toTurtle } from "ldo";
import { FoafProfileShapeType } from "./ldo/foafProfile.shapeTypes";
import { FoafProfileShapeType } from "./.ldo/foafProfile.shapeTypes";
async function run() {
const rawTurtle = `
@ -161,200 +108,49 @@ async function run() {
run();
```
## Getting an LDO Dataset
An LDO Dataset is a kind of [RDF JS Dataset](https://rdf.js.org/dataset-spec/) that can create linked data objects.
Once you have an LdoDataset we can get a Linked Data Object. A linked data object feels just like a JavaScript object literal, but when you make modifications to it, it will affect the underlying LdoDataset.
Getting a LdoDataset
Thie first step is defining which Shape Type you want to retrieve from the dataset. We can use the generated shape types and the `usingType()` method for this.
`fromSubject` lets you define a an `entryNode`, the place of entry for the graph. The object returned by `jsonldDatasetProxy` will represent the given node. This parameter accepts both `namedNode`s and `blankNode`s. `fromSubject` takes a generic type representing the typescript type of the given subject.
`fromJson` will take any regular Json, add the information to the dataset, and return a Jsonld Dataset Proxy representing the given data.
Other Helper Functions
```typescript
const person2 = ldoDataset
.usingType(FoafProfileShapeType)
.fromJson({
"@id": "http://example.com/Person2",
fn: ["Jane Doe"],
});
```
## Getting and Setting Data on a Linked Data Object
Once you've created a Linked Data Object, you can get and set data as if it were a normal TypeScript Object. For specific details, see the documentation at [JSONLD Dataset Proxy](https://github.com/o-development/jsonld-dataset-proxy/blob/master/Readme.md).
```typescript
import { LinkedDataObject } from "ldo";
import { FoafProfileFactory } from "./ldo/foafProfile.ldoFactory.ts";
import { FoafProfile } from "./ldo/foafProfile.typings";
`serialize(linkedDataObject, options)` provides general serialization based on provided options:
- `foramt` (optional): The format to serialize to. The following are acceptable formats: `Turtle`, `TriG`, `N-Triples`, `N-Quads`, `N3`, `Notation3`.
- `prefixes`: The prefixes for those serializations that use prefixes.
## Transactions
Sometimes, you want to keep track of changes you make for the object. This is where transactions come in handy.
To start a transaction, use the `startTransaction(linkedDataObject)` function. From then on, all transactions will be tracked, but not added to the original ldoDataset. You can view the changes using the `transactionChanges(linkedDataObject)` or `toSparqlUpdate(linkedDataObject)` methods. When you're done with the transaction, you can run the `commitTransaction(linkedDataObject)` method to add the changes to the original ldoDataset.
This project was made possible by a grant from NGI Zero Entrust via nlnet. Learn more on the [NLnet project page](https://nlnet.nl/project/SolidUsableApps/).
jaxoncreed
2 years ago