api.md

September 25, 2020 · View on GitHub

Classes

SolidAPI
SolidFileClient ⇐ SolidApi: Class for working with files on Solid Pods

Typedefs

WriteOptions : object

ReadFolderOptions : object

SolidApiOptions : object

Links : object

Item : object

FolderData : object

fetch ⇒ Promise.<Response>

(optionally authenticated) fetch method similar to window.fetch

zipOptions : object

.acl write parameters

unzipOptions : object

.acl write parameters

SolidFileClientOptions : object

SolidAPI

Kind: global class

SolidAPI
- new SolidAPI(fetch, [options])
- .fetch(url, [options]) ⇒ Promise.<Response>
- .get(url, [options]) ⇒ Promise.<Response>
- .delete(url, [options]) ⇒ Promise.<Response>
- .post(url, [options]) ⇒ Promise.<Response>
- .put(url, [options]) ⇒ Promise.<Response>
- .patch(url, [options]) ⇒ Promise.<Response>
- .head(url, [options]) ⇒ Promise.<Response>
- .options(url, [options]) ⇒ Promise.<Response>
- .itemExists(url) ⇒ Promise.<boolean>
- .postItem(url, content, contentType, link, [options]) ⇒ Promise.<Response>
- .createFolder(url, [options]) ⇒ Promise.<Response>
- .postFile(url, content, [options]) ⇒ Promise.<Response>
- .createFile(url, content, [options]) ⇒ Promise.<Response>
- .putFile(url, content, [options]) ⇒ Promise.<Response>
- .patchFile(url, patchContent, patchContentType) ⇒ Promise.<Response>
- .readFolder(url, [options]) ⇒ Promise.<FolderData>
- .getItemLinks(url, [options]) ⇒ Promise.<Links>
- .copyFile(from, to, [options]) ⇒ Promise.<Response>
- .copyMetaFileForItem(oldTargetFile, newTargetFile, [options]) ⇒ Promise.<(Response|undefined)>
- .copyAclFileForItem(oldTargetFile, newTargetFile, [options]) ⇒ Promise.<Response>
- .copyLinksForItem(oldTargetFile, newTargetFile, [options]) ⇒ Promise.<Array.<Response>>
- .copyFolder(from, to, [options]) ⇒ Promise.<Array.<Response>>
- .copy(from, to, [options]) ⇒ Promise.<Array.<Response>>
- .deleteFolderContents(url) ⇒ Promise.<Array.<Response>>
- .deleteFolderRecursively(url) ⇒ Promise.<Array.<Response>>
- .move(from, to, [copyOptions]) ⇒ Promise.<Array.<Response>>
- .rename(url, newName, [moveOptions]) ⇒ Promise.<Array.<Response>>

new SolidAPI(fetch, [options])

Provide API methods which use the passed fetch method constructor adds :

this.rdf methods from RdfQuery
this.acl methods from AclParser

Param	Type
fetch	`fetch`
[options]	`SolidApiOptions`

solidAPI.fetch(url, [options]) ⇒ `Promise.<Response>`

Fetch a resource with the passed fetch method

Kind: instance method of SolidAPI
Returns: Promise.<Response> - resolves if response.ok is true, else rejects the response

Param	Type
url	`string`
[options]	`RequestInit`

solidAPI.get(url, [options]) ⇒ `Promise.<Response>`

Send get request

Kind: instance method of SolidAPI

Param	Type
url	`string`
[options]	`RequestInit`

solidAPI.delete(url, [options]) ⇒ `Promise.<Response>`

Send delete request

Kind: instance method of SolidAPI

Param	Type
url	`string`
[options]	`RequestInit`

solidAPI.post(url, [options]) ⇒ `Promise.<Response>`

Send post request

Kind: instance method of SolidAPI

Param	Type
url	`string`
[options]	`RequestInit`

solidAPI.put(url, [options]) ⇒ `Promise.<Response>`

Send put request

Kind: instance method of SolidAPI

Param	Type
url	`string`
[options]	`RequestInit`

solidAPI.patch(url, [options]) ⇒ `Promise.<Response>`

Send patch request

Kind: instance method of SolidAPI

Param	Type
url	`string`
[options]	`RequestInit`

solidAPI.head(url, [options]) ⇒ `Promise.<Response>`

Send head request

Kind: instance method of SolidAPI

Param	Type
url	`string`
[options]	`RequestInit`

solidAPI.options(url, [options]) ⇒ `Promise.<Response>`

Send options request

Kind: instance method of SolidAPI

Param	Type
url	`string`
[options]	`RequestInit`

solidAPI.itemExists(url) ⇒ `Promise.<boolean>`

Check if item exists. Return false if status is 404. If status is 403 (or any other "bad" status) reject.

Kind: instance method of SolidAPI

Param	Type
url	`string`

solidAPI.postItem(url, content, contentType, link, [options]) ⇒ `Promise.<Response>`

Create an item at target url. Per default it will create the parent folder if it doesn't exist.

Kind: instance method of SolidAPI

Param	Type	Description
url	`string`
content	`Blob` \| `string`
contentType	`string`
link	`string`	header for Container/Resource, see LINK in apiUtils
[options]	`WriteOptions`	only uses createPath option

solidAPI.createFolder(url, [options]) ⇒ `Promise.<Response>`

Create a folder if it doesn't exist. Per default it will resolve when the folder already existed

Kind: instance method of SolidAPI
Returns: Promise.<Response> - Response of HEAD request if it already existed, else of creation request

Param	Type
url	`string`
[options]	`WriteOptions`

solidAPI.postFile(url, content, [options]) ⇒ `Promise.<Response>`

Create a new file.

Kind: instance method of SolidAPI

Param	Type
url	`string`
content	`Blob` \| `String`
[options]	`WriteOptions`

solidAPI.createFile(url, content, [options]) ⇒ `Promise.<Response>`

Create a new file. Per default it will overwrite existing files

Kind: instance method of SolidAPI

Param	Type
url	`string`
content	`Blob` \| `String`
[options]	`WriteOptions`

solidAPI.putFile(url, content, [options]) ⇒ `Promise.<Response>`

Create a file using PUT Per default it will overwrite existing files

Kind: instance method of SolidAPI

Param	Type
url	`string`
content	`Blob` \| `String`
[options]	`WriteOptions`

solidAPI.patchFile(url, patchContent, patchContentType) ⇒ `Promise.<Response>`

Update a file using PATCH

Kind: instance method of SolidAPI

Param	Type	Description
url	`string`	parsable by N3.js
patchContent	`String`
patchContentType	`string`

Properties

Name	Type	Description
'text/n3'	`patchContentType`	or 'application/sparql-update'

solidAPI.readFolder(url, [options]) ⇒ `Promise.<FolderData>`

Fetch and parse a folder

Kind: instance method of SolidAPI

Param	Type
url	`string`
[options]	`ReadFolderOptions`

solidAPI.getItemLinks(url, [options]) ⇒ `Promise.<Links>`

Get acl and meta links of an item

Kind: instance method of SolidAPI

Param	Type	Description
url	`string`
[options]	`object`	- specify if links should be checked for existence or not - may select acl or meta only

solidAPI.copyFile(from, to, [options]) ⇒ `Promise.<Response>`

Copy a file. Per default overwrite existing files and copy links too.

Kind: instance method of SolidAPI
Returns: Promise.<Response> - - Response from the new file created

Param	Type	Description
from	`string`	Url where the file currently is
to	`string`	Url where it should be copied to
[options]	`WriteOptions`

solidAPI.copyMetaFileForItem(oldTargetFile, newTargetFile, [options]) ⇒ `Promise.<(Response|undefined)>`

Copy a meta file

Kind: instance method of SolidAPI
Returns: Promise.<(Response|undefined)> - creation response

Param	Type
oldTargetFile	`string`
newTargetFile	`string`
[options]	`WriteOptions`

solidAPI.copyAclFileForItem(oldTargetFile, newTargetFile, [options]) ⇒ `Promise.<Response>`

Copy an ACL file

Kind: instance method of SolidAPI
Returns: Promise.<Response> - creation response

Param	Type	Description
oldTargetFile	`string`	Url of the file the acl file targets (e.g. file.ttl for file.ttl.acl)
newTargetFile	`string`	Url of the new file targeted (e.g. new-file.ttl for new-file.ttl.acl)
[options]	`WriteOptions`

solidAPI.copyLinksForItem(oldTargetFile, newTargetFile, [options]) ⇒ `Promise.<Array.<Response>>`

Copy links for an item. Use withAcl and withMeta options to specify which links to copy Does not throw if the links don't exist.

Kind: instance method of SolidAPI
Returns: Promise.<Array.<Response>> - creation responses

Param	Type	Description
oldTargetFile	`string`	Url of the file the acl file targets (e.g. file.ttl for file.ttl.acl)
newTargetFile	`string`	Url of the new file targeted (e.g. new-file.ttl for new-file.ttl.acl)
[options]	`WriteOptions`

solidAPI.copyFolder(from, to, [options]) ⇒ `Promise.<Array.<Response>>`

Copy a folder and all contents. Per default existing folders will be deleted before copying and links will be copied.

Kind: instance method of SolidAPI
Returns: Promise.<Array.<Response>> - Resolves with an array of creation responses. The first one will be the folder specified by "to". The others will be creation responses from the contents in arbitrary order.

Param	Type
from	`string`
to	`string`
[options]	`WriteOptions`

solidAPI.copy(from, to, [options]) ⇒ `Promise.<Array.<Response>>`

Copy a file (url ending with file name) or folder (url ending with "/"). Per default existing folders will be deleted before copying and links will be copied.

Kind: instance method of SolidAPI
Returns: Promise.<Array.<Response>> - Resolves with an array of creation responses. The first one will be the folder specified by "to". If it is a folder, the others will be creation responses from the contents in arbitrary order.

Param	Type
from	`string`
to	`string`
[options]	`WriteOptions`

solidAPI.deleteFolderContents(url) ⇒ `Promise.<Array.<Response>>`

Delete all folders and files inside a folder

Kind: instance method of SolidAPI
Returns: Promise.<Array.<Response>> - Resolves with a response for each deletion request

Param	Type
url	`string`

solidAPI.deleteFolderRecursively(url) ⇒ `Promise.<Array.<Response>>`

Delete a folder, its contents and links recursively

Kind: instance method of SolidAPI
Returns: Promise.<Array.<Response>> - Resolves with an array of deletion responses. The first one will be the folder specified by "url". The others will be the deletion responses from the contents in arbitrary order

Param	Type
url	`string`

solidAPI.move(from, to, [copyOptions]) ⇒ `Promise.<Array.<Response>>`

Move a file (url ending with file name) or folder (url ending with "/"). Shortcut for copying and deleting items

Kind: instance method of SolidAPI
Returns: Promise.<Array.<Response>> - Responses of the copying

Param	Type
from	`string`
to	`string`
[copyOptions]	`WriteOptions`

solidAPI.rename(url, newName, [moveOptions]) ⇒ `Promise.<Array.<Response>>`

Rename a file (url ending with file name) or folder (url ending with "/"). Shortcut for moving items within the same directory

Kind: instance method of SolidAPI
Returns: Promise.<Array.<Response>> - Response of the newly created items

Param	Type
url	`string`
newName	`string`
[moveOptions]	`RequestOptions`

SolidFileClient ⇐ `SolidApi`

Class for working with files on Solid Pods

Kind: global class
Extends: SolidApi

SolidFileClient ⇐ SolidApi
- new SolidFileClient(auth, [options])
- .readFile(url, [request]) ⇒ Promise.<(string|Blob|Response)>
- .readHead(url, options) ⇒ string
- .deleteFile(url) ⇒ Promise.<Response>
- .deleteFolder(url) ⇒ Promise.<Array.<Response>>
- .aclUrlParser(url) ⇒ object
- .getFolderItemList(path) ⇒ Promise.<Array.<Item>>
- .createZipArchive(resource, archiveUrl, options) ⇒ promise.<response>
- .getAsZip()
- .addItemsToZip()
- .zipItemLinks(zip, itemLinks, itemName)
- .extractZipArchive(zip, destination, options) ⇒
- .uploadExtractedZipArchive(zip, destination, curFolder, responses, options) ⇒ promise
- ._uploadLinkFile()

new SolidFileClient(auth, [options])

Param	Type	Description
auth	`SolidAuthClient`	An auth client, for instance solid-auth-client or solid-auth-cli
[options]	`SolidFileClientOptions`

solidFileClient.readFile(url, [request]) ⇒ `Promise.<(string|Blob|Response)>`

Fetch an item and return content as text,json,or blob as needed

Kind: instance method of SolidFileClient

Param	Type
url	`string`
[request]	`RequestInit`

solidFileClient.readHead(url, options) ⇒ `string`

read Head as string

Kind: instance method of SolidFileClient
Returns: string - headStr

Param	Type
url	`string`
options	`object`

solidFileClient.deleteFile(url) ⇒ `Promise.<Response>`

delete file

Kind: instance method of SolidFileClient
Returns: Promise.<Response> - response of the file deletion

Param	Type
url	`string`

solidFileClient.deleteFolder(url) ⇒ `Promise.<Array.<Response>>`

Delete a folder, its contents and links recursively

Kind: instance method of SolidFileClient
Returns: Promise.<Array.<Response>> - Resolves with an array of deletion responses. The first one will be the folder specified by "url". The others will be the deletion responses from the contents in arbitrary order

Param	Type
url	`string`

solidFileClient.aclUrlParser(url) ⇒ `object`

ACL content url parser

Kind: instance method of SolidFileClient
Returns: object - an acl object from url.acl

Param	Type
url	`string`

solidFileClient.getFolderItemList(path) ⇒ `Promise.<Array.<Item>>`

Wrap API response for retrieving folder item list

Kind: instance method of SolidFileClient

Param	Type
path	`String`

solidFileClient.createZipArchive(resource, archiveUrl, options) ⇒ `promise.<response>`

Request API to upload the items as zip archive zip file contains a blob (or a string if async blob is not supported like in jest tests)

Kind: instance method of SolidFileClient
Returns: promise.<response> - res => { const success = await res.text() })>}

Param	Type	Description
resource	`string`	path (file or folder)
archiveUrl	`string`	.zip file url
options	`object`

Param	Type
zip	`object`
itemLinks	`Array`
itemName	`string`

solidFileClient.extractZipArchive(zip, destination, options) ⇒

Wrap API response for extracting a zip archive unzip file is expecting a blob content (except if async blob is not supported like in jest tests)

Kind: instance method of SolidFileClient
Returns: {promise<{ err: [], info: []}>)

Param	Type	Description
zip	`string`	file
destination	`string`	folder
options	`object`

Properties

Name	Type
...unzipOptions	`options`

solidFileClient.uploadExtractedZipArchive(zip, destination, curFolder, responses, options) ⇒ `promise`

Recursively upload all files and folders with links from an extracted zip archive

Kind: instance method of SolidFileClient

Param	Type	Description
zip	`object`
destination	`string`	url
curFolder	`string`
responses	`Array`
options	`object`

solidFileClient._uploadLinkFile()

Check that link content is valid and create link

Kind: instance method of SolidFileClient

WriteOptions : `object`

Kind: global typedef
Properties

Name	Type	Default	Description
[createPath]	`boolean`	`true`	create parent containers if they don't exist
[withAcl]	`boolean`	`true`	also copy acl files
[agent]	`AGENT`	`"no_modify"`	specify how to handle existing .acl
[withMeta]	`boolean`	`true`	also copy meta files
[merge]	`MERGE`	`"replace"`	specify how to handle existing files/folders

ReadFolderOptions : `object`

Kind: global typedef
Properties

Name	Type	Default
[links]	`LINKS`	`"exclude"`

SolidApiOptions : `object`

Kind: global typedef
Properties

Name	Type	Default	Description
[enableLogging]	`boolean` \| `string`	`false`	set to true to output all logging to the console or e.g. solid-file-client:fetch for partial logs

Links : `object`

Kind: global typedef
Properties

Name	Type
[acl]	`string`
[meta]	`string`

Item : `object`

Kind: global typedef
Properties

Name	Type
url	`string`
name	`string`
parent	`string`
itemType	`"Container"` \| `"Resource"`
[links]	`Links`

FolderData : `object`

Kind: global typedef
Properties

Name	Type
url	`string`
name	`string`
parent	`string`
links	`Links`
type	`"folder"`
folders	`Array.<Item>`
files	`Array.<Item>`

fetch ⇒ `Promise.<Response>`

(optionally authenticated) fetch method similar to window.fetch

Kind: global typedef

Param	Type
url	`string`
[options]	`RequestInit`

zipOptions : `object`

.acl write parameters

Kind: global typedef
Properties

Name	Type	Default	Description
[createPath]	`boolean`	`true`	create parent containers if they don't exist
[links]	`LINKS`	`"include"`
[withAcl]	`boolean`	`true`	also copy acl files
[withMeta]	`boolean`	`true`	also copy meta files

unzipOptions : `object`

.acl write parameters

Kind: global typedef
Properties

Name	Type	Default	Description
[createPath]	`boolean`	`true`	create parent containers if they don't exist
[links]	`LINKS`	`"include"`
[withAcl]	`boolean`	`true`	also copy acl files
[withMeta]	`boolean`	`true`	also copy meta files
[merge]	`MERGE`	`"replace"`	specify how to handle existing files/folders - .acl content validation parameters
[aclMode]	`aclMode`	`"Control"`	specify the minimal existing mode to validate ACL document
[aclAuth]	`aclAuth`	`"must"`	should be "must" (actually NSS accepts "may" = absence of acl:Authorization)
[aclDefault]	`aclDefault`	`"must"`	specify if acl:default is needed to validate ACL document

SolidFileClientOptions : `object`

Kind: global typedef
Properties

Name	Type	Default	Description
[enableLogging]	`boolean` \| `string`	`false`	true for all logging or e.g. solid-file-client:fetch for partial logs