@inrupt/solid-client / resource/solidDataset

Module: resource/solidDataset#

Type Aliases#

ParseOptions#

Ƭ ParseOptions: Object

Custom parsers to load [[SolidDataset]]s serialised in different RDF formats.

Provide your own parsers by providing an object on the parsers property with the supported content type as the key, and the parser as a value. For documentation on how to provide a parser, see [[Parser]].

Type declaration#

Name	Type
`parsers`	`Record`<`ContentType`, `Parser`>

Defined in#

src/resource/solidDataset.ts:153

Parser#

Ƭ Parser: Object

A Parser takes a string and generates Quads.

By providing an object conforming to the Parser interface, you can handle RDF serialisations other than text/turtle, which @inrupt/solid-client supports by default. This can be useful to retrieve RDF data from sources other than a Solid Pod.

A Parser has the following properties:

onQuad: Registers the callback with which parsed Quads can be provided to @inrupt/solid-client.
onError: Registers the callback with which @inrupt/solid-client can be notified of errors parsing the input.
onComplete: Registers the callback with which @inrupt/solid-client can be notified that parsing is complete.
parse: Accepts the serialised input string and an object containing the input Resource’s metadata. The input metadata can be read using functions like [[getSourceUrl]] and [[getContentType]].

For example, the following defines a parser that reads an RDFa serialisation using the rdfa-streaming-parser library:

import { RdfaParser } from "rdfa-streaming-parser";

// ...

const getRdfaParser = () => {
  const onQuadCallbacks = [];
  const onCompleteCallbacks = [];
  const onErrorCallbacks = [];

  return {
    onQuad: (callback) => onQuadCallbacks.push(callback),
    onError: (callback) => onErrorCallbacks.push(callback),
    onComplete: (callback) => onCompleteCallbacks.push(callback),
    parse: async (source, resourceInfo) => {
      const parser = new RdfaParser({
        baseIRI: getSourceUrl(resourceInfo),
        contentType: getContentType(resourceInfo) ?? "text/html",
      });
      parser.on("data", (quad) => {
        onQuadCallbacks.forEach((callback) => callback(quad));
      });
      parser.on("error", (error) => {
        onErrorCallbacks.forEach((callback) => callback(error));
      });
      parser.write(source);
      parser.end();
      onCompleteCallbacks.forEach((callback) => callback());
    },
  };
};

Type declaration#

Name	Type
`onComplete`	(`onCompleteCallback`: () => `void`) => `void`
`onError`	(`onErrorCallback`: (`error`: `unknown`) => `void`) => `void`
`onQuad`	(`onQuadCallback`: (`quad`: `Quad`) => `void`) => `void`
`parse`	(`source`: `string`, `resourceInfo`: `WithServerResourceInfo`) => `void`

Defined in#

src/resource/solidDataset.ts:139

Functions#

changeLogAsMarkdown#

▸ changeLogAsMarkdown(solidDataset): string

Gets a human-readable representation of the local changes to a Resource to aid debugging.

Note that changes to the exact format of the return value are not considered a breaking change; it is intended to aid in debugging, not as a serialisation method that can be reliably parsed.

Parameters#

Name	Type	Description
`solidDataset`	`Readonly`<{}> & { `internal_changeLog`: { `additions`: `Quad`[] ; `deletions`: `Quad`[] } }	The Resource of which to get a human-readable representation of the changes applied to it locally.

Returns#

string

Since

0.3.0

Defined in#

src/resource/solidDataset.ts:884

createContainerAt#

▸ createContainerAt(url, options?): Promise<SolidDataset & WithServerResourceInfo>

Create a Container at the given URL. Some content may optionally be specified, e.g. to add metadata describing the container.

Throws an error if creating the Container failed, e.g. because the current user does not have permissions to, or because the Container already exists.

Note that a Solid server will automatically create the necessary Containers when storing a Resource; i.e. there is no need to call this function if it is immediately followed by [[saveSolidDatasetAt]] or [[overwriteFile]].

Parameters#

Name	Type	Description
`url`	`string` \| `Url`	URL of the empty Container that is to be created.
`options`	`Object`	Optional parameter `options.fetch`: An alternative `fetch` function to make the HTTP request, compatible with the browser-native fetch API.
`options.fetch?`	(`input`: `RequestInfo` \| `URL`, `init?`: `RequestInit`) => `Promise`<`Response`>	MDN Reference
`options.initialContent?`	`Readonly`<{}>	-

Returns#

Promise<SolidDataset & WithServerResourceInfo>

Since

0.2.0

Defined in#

src/resource/solidDataset.ts:451

createContainerInContainer#

▸ createContainerInContainer(containerUrl, options?): Promise<SolidDataset & WithResourceInfo>

Create an empty Container inside the Container at the given URL.

Throws an error if creating the Container failed, e.g. because the current user does not have permissions to.

The Container in which to create the new Container should itself already exist.

This function is primarily useful if the current user does not have access to change existing files in a Container, but is allowed to add new files; in other words, they have Append, but not Write access to a Container. This is useful in situations where someone wants to allow others to, for example, send notifications to their Pod, but not to view or delete existing notifications. You can pass a suggestion for the new Resource’s name, but the server may decide to give it another name — for example, if a Resource with that name already exists inside the given Container. If the user does have access to write directly to a given location, [[createContainerAt]] will do the job just fine, and does not require the parent Container to exist in advance.

Parameters#

Name	Type	Description
`containerUrl`	`string` \| `Url`	URL of the Container in which the empty Container is to be created.
`options?`	`SaveInContainerOptions`	Optional parameter `options.fetch`: An alternative `fetch` function to make the HTTP request, compatible with the browser-native fetch API.`options.slugSuggestion` accepts a string for your new Container’s name.

Returns#

Promise<SolidDataset & WithResourceInfo>

A promise that resolves to a SolidDataset with ResourceInfo if successful, and that rejects otherwise.

Since

0.2.0

Defined in#

src/resource/solidDataset.ts:653

createSolidDataset#

▸ createSolidDataset(): SolidDataset

Initialise a new [[SolidDataset]] in memory.

Returns#

SolidDataset

An empty [[SolidDataset]].

Defined in#

src/resource/solidDataset.ts:71

deleteContainer#

▸ deleteContainer(container, options?): Promise<void>

Deletes the Container at a given URL.

Parameters#

Name	Type	Description
`container`	`string` \| `Url` \| `WithResourceInfo`	The URL of the Container to delete or the Container Dataset itself (if it has ResourceInfo).
`options?`	`Object`	-
`options.fetch?`	(`input`: `RequestInfo` \| `URL`, `init?`: `RequestInit`) => `Promise`<`Response`>	MDN Reference

Returns#

Promise<void>

Since

0.6.0

Defined in#

src/resource/solidDataset.ts:718

deleteSolidDataset#

▸ deleteSolidDataset(solidDataset, options?): Promise<void>

Deletes the SolidDataset at a given URL.

If operating on a container, the container must be empty otherwise a 409 CONFLICT will be raised.

Parameters#

Name	Type	Description
`solidDataset`	`string` \| `Url` \| `WithResourceInfo`	The URL of the SolidDataset to delete or the SolidDataset itself (if it has ResourceInfo).
`options?`	`Object`	-
`options.fetch?`	(`input`: `RequestInfo` \| `URL`, `init?`: `RequestInit`) => `Promise`<`Response`>	MDN Reference

Returns#

Promise<void>

Since

0.6.0

Defined in#

src/resource/solidDataset.ts:416

getContainedResourceUrlAll#

▸ getContainedResourceUrlAll(solidDataset): UrlString[]

Given a [[SolidDataset]] representing a Container (see [[isContainer]]), fetch the URLs of all contained resources that respect slash semantics (see validateContainedResourceAll). If the solidDataset given is not a container, or is missing resourceInfo, throw an error.

Parameters#

Name	Type	Description
`solidDataset`	`Readonly`<{}> & `WithResourceInfo`	The container from which to fetch all contained Resource URLs.

Returns#

UrlString[]

A list of URLs, each of which points to a contained Resource of the given SolidDataset.

Since

1.3.0

Defined in#

src/resource/solidDataset.ts:770

getSolidDataset#

▸ getSolidDataset(url, options?): Promise<SolidDataset & WithServerResourceInfo>

Fetch a SolidDataset from the given URL. Currently requires the SolidDataset to be available as Turtle.

Note that the URL of a container ends with a trailing slash “/”. If it is missing, some libraries will add it automatically, which may result in additional round-trips, possibly including authentication errors (more information).

Parameters#

Name	Type	Description
`url`	`string` \| `Url`	URL to fetch a [[SolidDataset]] from.
`options?`	`Partial`<{ `fetch`: (`input`: `RequestInfo` \| `URL`, `init?`: `RequestInit`) => `Promise`<`Response`> } & `ParseOptions`>	Optional parameter `options.fetch`: An alternative `fetch` function to make the HTTP request, compatible with the browser-native fetch API.

Returns#

Promise<SolidDataset & WithServerResourceInfo>

Promise resolving to a [[SolidDataset]] containing the data at the given Resource, or rejecting if fetching it failed.

Defined in#

src/resource/solidDataset.ts:239

saveSolidDatasetAt#

▸ saveSolidDatasetAt<Dataset>(url, solidDataset, options?): Promise<Dataset & WithServerResourceInfo & WithChangeLog>

Given a SolidDataset, store it in a Solid Pod (overwriting the existing data at the given URL).

A SolidDataset keeps track of the data changes compared to the data in the Pod; i.e., the changelog tracks both the old value and new values of the property being modified. This function applies the changes to the current SolidDataset. If the old value specified in the changelog does not correspond to the value currently in the Pod, this function will throw an error (common issues are listed in the documentation).

The SolidDataset returned by this function will contain the data sent to the Pod, and a ChangeLog up-to-date with the saved data. Note that if the data on the server was modified in between the first fetch and saving it, the updated data will not be reflected in the returned SolidDataset. To make sure you have the latest data, call [[getSolidDataset]] again after saving the data.

The Solid server will create any intermediary Containers that do not exist yet, so they do not need to be created in advance. For example, if the target URL is https://example.pod/container/resource and https://example.pod/container/ does not exist yet, it will exist after this function resolves successfully.

Type parameters#

Name	Type
`Dataset`	extends `Readonly`<{}>

Parameters#

Name	Type	Description
`url`	`string` \| `Url`	URL to save `solidDataset` to.
`solidDataset`	`Dataset`	The [[SolidDataset]] to save.
`options?`	`Partial`<{ `fetch?`: (`input`: `RequestInfo` \| `URL`, `init?`: `RequestInit`) => `Promise`<`Response`> } & { `prefixes`: `Record`<`string`, `string`> }>	Optional parameter `options.fetch`: An alternative `fetch` function to make the HTTP request, compatible with the browser-native fetch API. `options.prefixes`: A prefix map to customize the serialization. Only applied on resource creation if the serialization allows it.

Returns#

Promise<Dataset & WithServerResourceInfo & WithChangeLog>

A Promise resolving to a [[SolidDataset]] containing the stored data, or rejecting if saving it failed.

Defined in#

src/resource/solidDataset.ts:359

saveSolidDatasetInContainer#

▸ saveSolidDatasetInContainer(containerUrl, solidDataset, options?): Promise<SolidDataset & WithResourceInfo>

Given a SolidDataset, store it in a Solid Pod in a new Resource inside a Container.

The Container at the given URL should already exist; if it does not, you can initialise it first using [[createContainerAt]], or directly save the SolidDataset at the desired location using [[saveSolidDatasetAt]].

This function is primarily useful if the current user does not have access to change existing files in a Container, but is allowed to add new files; in other words, they have Append, but not Write access to a Container. This is useful in situations where someone wants to allow others to, for example, send notifications to their Pod, but not to view or delete existing notifications. You can pass a suggestion for the new Resource’s name, but the server may decide to give it another name — for example, if a Resource with that name already exists inside the given Container. If the user does have access to write directly to a given location, [[saveSolidDatasetAt]] will do the job just fine, and does not require the parent Container to exist in advance.

Parameters#

Name	Type	Description
`containerUrl`	`string` \| `Url`	URL of the Container in which to create a new Resource.
`solidDataset`	`Readonly`<{}>	The [[SolidDataset]] to save to a new Resource in the given Container.
`options?`	`SaveInContainerOptions`	Optional parameter `options.fetch`: An alternative `fetch` function to make the HTTP request, compatible with the browser-native fetch API.

Returns#

Promise<SolidDataset & WithResourceInfo>

A Promise resolving to a [[SolidDataset]] containing the saved data. The Promise rejects if the save failed.

Defined in#

src/resource/solidDataset.ts:550

solidDatasetAsMarkdown#

▸ solidDatasetAsMarkdown(solidDataset): string

Gets a human-readable representation of the given SolidDataset to aid debugging.

Note that changes to the exact format of the return value are not considered a breaking change; it is intended to aid in debugging, not as a serialisation method that can be reliably parsed.

Parameters#

Name	Type	Description
`solidDataset`	`Readonly`<{}>	The [[SolidDataset]] to get a human-readable representation of.

Returns#

string

Since

0.3.0

Defined in#

src/resource/solidDataset.ts:848

validateContainedResourceAll#

▸ validateContainedResourceAll(solidDataset): Object

Given a SolidDataset representing a Container (see isContainer), verify that all its containment claims are valid. Containment of a resource is valid if it respects slash semantics.

For the example, given a container at https://example.org/container/:

The following resources are valid:
- https://example.org/container/resource
- https://example.org/container/subcontainer/
The following resources are invalid:
- https://example.org/container/resource/invalid (not a direct child resource)
- https://example.org/container2 (not a child resource)
- https://domain2.example.org/container/resource (not a direct child resource)

If a component claim is invalid, validateContainedResourceAll returns the invalid component’s URL as part of its return object.

Note: It is recommended that this function always be used before calling getContainedResourceUrlAll since getContainedResourceUrlAll does not return Resources for which containment is invalid. Using the function in conjunction with getContainedResourceUrlAll allows for the detection of unexpected behaviour from servers, including malicious containment triples that could appear. Because ESS conforms to the Solid Protocol, i.e., respects slash semantics for its containment triples, validateContainedResourceAll returns true for containers fetched from ESS.

Parameters#

Name	Type	Description
`solidDataset`	`Readonly`<{}> & `WithResourceInfo`	The container from which containment claims are validated.

Returns#

Object

A validation report, including the offending contained resources URL if any.

Name	Type
`invalidContainedResources`	`string`[]
`isValid`	`boolean`

Since

unreleased

Defined in#

src/resource/solidDataset.ts:817