You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
281 lines
11 KiB
281 lines
11 KiB
# @ldo/connected
|
|
|
|
@ldo/connected provides tools for LDO to connect to a remote datasource. It requires plugins for that datasource.
|
|
|
|
## Installation
|
|
|
|
Navigate into your project's root folder and run the following command:
|
|
```
|
|
cd my_project/
|
|
npx run @ldo/cli init
|
|
```
|
|
|
|
Now install the @ldo/solid library
|
|
|
|
```
|
|
npm i @ldo/connected
|
|
```
|
|
|
|
You may also install a connected plugin, for example `@ldo/connected-solid` and `@ldo/connected-nextgraph`.
|
|
|
|
```
|
|
npm i @ldo/connected-nextgraph
|
|
```
|
|
|
|
<details>
|
|
<summary>
|
|
Manual Installation
|
|
</summary>
|
|
|
|
If you already have generated ShapeTypes, you may install the `@ldo/ldo` and `@ldo/solid` libraries independently.
|
|
|
|
```
|
|
npm i @ldo/ldo @ldo/solid
|
|
```
|
|
</details>
|
|
|
|
## Simple Examples
|
|
|
|
Below is a simple example of @ldo/solid. Assume that a ShapeType was previously generated and placed at `./.ldo/foafProfile.shapeTypes`. Also assume we have a shape type for social media at `./.ldo/socialMediaPost.shapeTypes`
|
|
|
|
```typescript
|
|
import {
|
|
changeData,
|
|
commitData,
|
|
createConnectedLdoDataset
|
|
} from "@ldo/connected";
|
|
import { solidConnectedPlugin } from "@ldo/connected-solid";
|
|
import { nextGraphConnectedPlugin } from "@ldo/connected-nextgraph";
|
|
|
|
|
|
// Shape Types
|
|
import { FoafProfileShapeType } from "./.ldo/foafProfile.shapeTypes.js";
|
|
import { SocialMediaPostShapeType } from "./.ldo/socialMediaPost.shapeTypes.js";
|
|
|
|
// These are tools for Solid and NextGraph outside of the LDO ecosystem
|
|
import { fetch, getDefaultSession } from "@inrupt/solid-client-authn-browser";
|
|
import ng from "nextgraph";
|
|
|
|
async function main() {
|
|
/**
|
|
* ===========================================================================
|
|
* SETTING UP A CONNECTED LDO DATASTORE WITH 2 PLUGINS
|
|
* ===========================================================================
|
|
*/
|
|
const connectedLdoDataset = createConnectedLdoDataset([
|
|
solidConncetedPlugin,
|
|
nextGraphConnectedPlugin
|
|
]);
|
|
// Set context to be able to make authenticated requests
|
|
connectedLdoDataset.setContext("solid", { fetch });
|
|
const session = await ng.session_in_memory_start(
|
|
openedWallet.V0.wallet_id,
|
|
openedWallet.V0.personal_site
|
|
);
|
|
connectedLdoDataset.setContext("nextGraph", { sessionId: session.sessionId });
|
|
|
|
/**
|
|
* ===========================================================================
|
|
* READING DATA FROM REMOTE
|
|
* ===========================================================================
|
|
*/
|
|
|
|
// We can get a Solid resource by including a Solid-Compatible URL
|
|
const solidResource = solidLdoDataset.getResource(
|
|
"https://pod.example.com/profile.ttl"
|
|
);
|
|
// Similarly, we can get a NextGraph resource by including a
|
|
// NextGraph-Compatible URL
|
|
const nextGraphResource = solidLdoDataset.getResource(
|
|
"did:ng:o:W6GCQRfQkNTLtSS_2-QhKPJPkhEtLVh-B5lzpWMjGNEA:v:h8ViqyhCYMS2I6IKwPrY6UZi4ougUm1gpM4QnxlmNMQA"
|
|
);
|
|
// Optionally, you can provide the name of the specific plugin you want to use
|
|
const anotherSolidResource = solidLdoDataset.getResource("", "solid");
|
|
|
|
|
|
// This resource is currently unfetched
|
|
console.log(solidResource.isUnfetched()); // Logs true
|
|
console.log(nextGraphResource.isUnfetched()); // Logs true
|
|
|
|
// So let's fetch it! Running the `read` command will make a request to get
|
|
// the WebId.
|
|
const solidReadResult = await solidResource.read();
|
|
const ngReadResult = await nextGraphREsource.read();
|
|
|
|
// @ldo/connected will never throw an error. Instead, it will return errors.
|
|
// This design decision was made to force you to handle any errors. It may
|
|
// seem a bit annoying at first, but it will result in more resiliant code.
|
|
// You can easily follow intellisense tooltips to see what kinds of errors
|
|
// each action can throw.
|
|
if (solidReadResult.isError) {
|
|
switch (solidReadResult.type) {
|
|
case "serverError":
|
|
console.error("The solid server had an error:", solidReadResult.message);
|
|
return;
|
|
case "noncompliantPodError":
|
|
console.error("The Pod responded in a way not compliant with the spec");
|
|
return;
|
|
default:
|
|
console.error("Some other error was detected:", solidReadResult.message);
|
|
}
|
|
}
|
|
|
|
// When fetching a data resource, read triples will automatically be added to
|
|
// the solidLdoDataset. You can access them using Linked Data Objects. In
|
|
// the following example we're using a Profile Linked Data Object that was
|
|
// generated with the init step.
|
|
const profile = connectedLdoDataset
|
|
.usingType(FoafProfileShapeType)
|
|
.fromSubject("https://pod.example.com/profile#me");
|
|
|
|
// Now you can read "profile" like any JSON.
|
|
console.log(profile.name);
|
|
|
|
/**
|
|
* ===========================================================================
|
|
* MODIFYING DATA
|
|
* ===========================================================================
|
|
*/
|
|
|
|
// When we want to modify data the first step is to use the `changeData`
|
|
// function. We pass in an object that we want to change (in this case,
|
|
// "profile") as well an a list of any resources to which we want those
|
|
// changes to be applied (in this case, just the webIdResource). This gives
|
|
// us a new variable (conventionally named with a c for "changed") that we can
|
|
// write changes to.
|
|
const cProfile = changeData(profile, solidResource);
|
|
|
|
// We can make changes just like it's regular JSON
|
|
cProfile.name = "Captain Cool Dude";
|
|
|
|
// Committing data is as easy as running the "commitData" function.
|
|
const commitResult = await commitData(cProfile);
|
|
|
|
// Remember to check for and handle errors! We'll keep it short this time.
|
|
if (commitResult.isError) throw commitResult;
|
|
|
|
/**
|
|
* ===========================================================================
|
|
* CREATING NEW RESOURCES
|
|
* ===========================================================================
|
|
*/
|
|
|
|
// Let's create some social media posts to be stored on the Solid Pod and in
|
|
// NextGraph! We can create new resources using the "createResource" method.
|
|
const newSolidResource = await connectedLdoDataset.createResource("solid");
|
|
const newNgResource = await connectedLdoDataset.createResource("nextGraph");
|
|
|
|
// For Solid, you can also create resources at a predefined location
|
|
const postContainer = connectedLdoDataset
|
|
.getResource("https://pod.example.com/socialPosts/");
|
|
const createPostContainerResult =
|
|
await solidSocialPostsContainer.createIfAbsent();
|
|
if (createPostContainerResult.isError) throw createPostContainerResult;
|
|
const postResourceResult =
|
|
await postContainer.createChildAndOverwrite("post1.ttl");
|
|
if (postResourceResult.isError) throw postResourceResult;
|
|
const postResource = postResourceResult.resource;
|
|
|
|
// We can also create binary resources with things like images
|
|
const imageResourceResult = await postContainer.uploadChildAndOverwrite(
|
|
// name of the binary
|
|
"image1.svg",
|
|
// A blob for the binary
|
|
new Blob([`<svg><circle r="9" /></svg>`]),
|
|
// mime type of the binary
|
|
"image/svg+xml",
|
|
);
|
|
if (imageResourceResult.isError) throw imageResourceResult;
|
|
const imageResource = imageResourceResult.resource;
|
|
|
|
/**
|
|
* ===========================================================================
|
|
* CREATING NEW DATA
|
|
* ===========================================================================
|
|
*/
|
|
|
|
// We create data in a similar way to the way we modify data. We can use the
|
|
// "createData" method.
|
|
const cPost = solidLdoDataset.createData(
|
|
// An LDO ShapeType saying that this is a social media psot
|
|
SocialMediaPostShapeType,
|
|
// The URI of the post (in this case we'll make it the same as the resource)
|
|
postResource.uri,
|
|
// The resource we should write it to
|
|
postResource,
|
|
);
|
|
|
|
// We can add new data
|
|
cPost.text = "Check out this bad svg:";
|
|
cPost.image = { "@id": imageResource.uri };
|
|
|
|
// And now we commit data
|
|
const newDataResult = await commitData(cPost);
|
|
if (newDataResult.isError) throw newDataResult;
|
|
|
|
/**
|
|
* ===========================================================================
|
|
* DELETING RESOURCES
|
|
* ===========================================================================
|
|
*/
|
|
|
|
// Deleting resources can be done with a single method call. In this case,
|
|
// the container will be deleted along with all its contained resources
|
|
const deleteResult = await postContainer.delete();
|
|
if (deleteResult.isError) throw deleteResult;
|
|
}
|
|
main();
|
|
```
|
|
|
|
## API Details
|
|
|
|
ConnectedLdoDataset
|
|
|
|
- [createConnectedLdoDataset](https://ldo.js.org/latest/api/connected/functions/createConnectedLdoDataset/)
|
|
- [ConnectedLdoDataset](https://ldo.js.org/latest/api/connected/classes/ConnectedLdoDataset/)
|
|
- [ConnectedLdoTransactionDataset](https://ldo.js.org/latest/api/connected/classes/ConnectedLdoTransactionDataset/)
|
|
- [IConnectedLdoDataset](https://ldo.js.org/latest/api/connected/interfaces/IConnectedLdoDataset/)
|
|
|
|
ConnectedPlugins
|
|
|
|
- [ConnectedPlugin](https://ldo.js.org/latest/api/connected/interfaces/ConnectedPlugin/)
|
|
|
|
Resources (Manage batching requests)
|
|
|
|
- [Resource](https://ldo.js.org/latest/api/connected/interfaces/Resource/)
|
|
|
|
Data Functions
|
|
|
|
- [changeData](https://ldo.js.org/latest/api/connected/functions/changeData/)
|
|
- [commitData](https://ldo.js.org/latest/api/connected/functions/commitData/)
|
|
|
|
SuccessResult
|
|
|
|
- [SuccessResult](https://ldo.js.org/latest/api/connected/classes/SuccessResult/)
|
|
- [AbsentReadSuccess](https://ldo.js.org/latest/api/connected/classes/AbsentReadSuccess/)
|
|
- [AggregateSuccess](https://ldo.js.org/latest/api/connected/classes/AggregateSuccess/)
|
|
- [IgnoredInvalidUpdateSuccess](https://ldo.js.org/latest/api/connected/classes/IgnoredInvalidUpdateSuccess/)
|
|
- [ReadSuccess](https://ldo.js.org/latest/api/connected/classes/ReadSuccess/)
|
|
- [ResourceSuccess](https://ldo.js.org/latest/api/connected/classes/ResourceSuccess/)
|
|
- [Unfetched](https://ldo.js.org/latest/api/connected/classes/Unfetched/)
|
|
- [UpdateDefaultGraphSuccess](https://ldo.js.org/latest/api/connected/classes/UpdateDefaultGraphSuccess/)
|
|
- [UpdateSuccess](https://ldo.js.org/latest/api/connected/classes/UpdateSuccess/)å
|
|
|
|
ErrorResult
|
|
|
|
- [ErrorResult](https://ldo.js.org/latest/api/connected/classes/ErrorResult/)
|
|
- [AggregateError](https://ldo.js.org/latest/api/connected/classes/AggregateError/)
|
|
- [DisconnectedAttemptingReconnectError](https://ldo.js.org/latest/api/connected/classes/DisconnectedAttemptingReconnectError/)
|
|
- [InvalidUriError](https://ldo.js.org/latest/api/connected/classes/InvalidUriError/)
|
|
- [ResourceError](https://ldo.js.org/latest/api/connected/classes/ResourceError/)
|
|
- [UnexpectedResourceError](https://ldo.js.org/latest/api/connected/classes/UnexpectedResourceError/)
|
|
- [UnsupportedNotificationError](https://ldo.js.org/latest/api/connected/classes/UnsupportedNotificationError/)
|
|
|
|
## Sponsorship
|
|
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/).
|
|
|
|
[<img src="https://nlnet.nl/logo/banner.png" alt="nlnet foundation logo" width="300" />](https://nlnet.nl/)
|
|
[<img src="https://nlnet.nl/image/logos/NGI0Entrust_tag.svg" alt="NGI Zero Entrust Logo" width="300" />](https://nlnet.nl/)
|
|
|
|
## Liscense
|
|
MIT
|
|
|