API Reference

Create A Store

Create a new interface to a graph by calling SolidState(options).

Options

{
  graph: 'string',
  session: {optional}
}

Example

import SolidState from 'solidstate-kv'

const db = SolidState({
  graph: 'test-graph'
})

User Provided Store

SolidState can sync it’s local data to a user-provided data store via the Solid Protocol.

Provide a Session object to the init options that has, at least, a webID string and a fetch function that can make requests against provided webID.

A straight-forward way to create this session object is with the Solid Client Authentication Library from Inrupt, as demonstrated in the Pocket Change sample project. This can also be done without libraries if you’re feeling brave.

If you’ve provided a Session object, SolidState will create the graph in the user-provided store at <webid>/<graph>. It will sync the currents state of the local store to this graph, and replicate any changes made locally upstream to this graph.

SolidState will not pro-actively live sync from this upstream store. It will download the store and sync it to it’s local state on initialization. To subscribe to changes live as they happen, use a Sync Server (tk).

Options

{
  session: {
    fetch: fn(),
    webID: String
  },
  graph: `sample-graph`
}

Example

import SolidState from 'solidstate-kv'
import {
  EVENTS,
  getDefaultSession
} from '@inrupt/solid-client-authn-browser'

let session = getDefaultSession()

session.events.on(EVENTS.SESSION_RESTORED, (url) => {
  let db = SetupDB({
    session: session,
    graph: `sample-graph`
  })
})

Entities

Entities are stored as flat objects, that is sets of key:value pairs. Values can be of any given type. Nested objects are created by managing relationships between entities.

Entities have two special keys: @id and @type.

The @id key is used to uniquely identify the entity.

The @type key is used to classify or attach a schema to the entity.

Post Data

Create a new entity with db.post. This will return a copy of the document. Note that we have a new property, @id. This is a generated UUID, but you can also provide your own, so long as it’s unique to this entity.

Example

let ref = await db.post({
  "@type": "Food",
  "name": "Hummus",
  "vegetarian": true,
  "number": 10,
  "ingredient": [
    "Garbanzo Beans",
    "Lemon"
  ]
})

Returns

// ref
{
  "@type": "Food",
  "name": "Hummus",
  "vegetarian": true,
  "number": 10,
  "ingredient": [
    "Garbanzo Beans",
    "Lemon"
  ],
  "@id": "uuid:5974d4a4-4b44-4c2d-a9f5-fbccc8da2760"
}

Get Data

Get a single item by @id with db.get()

Example

let ref = await db.post({
  "@id": "chickpeas",
  "@type": "Ingredient",
  "name": "Chickpeas"
})
let checkpeas = await db.get("chickpeas")

Returns

// ref
{
  "@id": "chickpeas",
  "@type": "Ingredient",
  "name": "Chickpeas"
}

Get All

Get all items in the graph with db.getAll()

Example

let items = await db.getAll()

Returns

// items
[{
  "@id": "chickpeas",
  "@type": "Ingredient",
  "name": "Chickpeas"
},{
  "@id": "lemon",
  "@type": "Ingredient",
  "name": "Lemon"
}]

Put Data

Update an Entity with the db.put() function, passing the Entities @id as the first parameter, and the new keys as the second.

Example

let ref = await db.put("chickpeas", {
  "name": "Garbanzo Beans"
})

Returns

{
  "@id": "chickpeas",
  "@type": "Ingredient",
  "name": "Garbanzo Beans"
}

Patch Data

Add to the existing value of an Entity with db.patch().

Note: If the original value was a single scalar, the new value will be an Array. This can be tricky and also confusing.

Example

await db.post({
  "@id": "hummus",
  "@type": "Food",
  "name": "Hummus",
  "vegetarian": true,
  "number": 10,
  "ingredient": [
    "Garbanzo Beans",
    "Lemon"
  ]
})

let ref = await db.patch('hummus', {
  "ingredient": "Olive Oil"
})

Returns

// ref
{
  "@id": "hummus",
  "@type": "Food",
  "name": "Hummus",
  "vegetarian": true,
  "number": 10,
  "ingredient": [
    "Garbanzo Beans",
    "Lemon",
    "Olive Oil"
  ]
}

Delete Data

Delete a key/value off an Entity with db.delete(id, data).

Delete the entire entity with db.delete(id).

Example

await db.post({
  "@id": "hummus",
  "@type": "Food",
  "name": "Hummus",
  "vegetarian": true,
  "number": 10,
  "ingredient": [
    "Garbanzo Beans",
    "Lemon"
  ]
})
let ref = await db.patch('hummus', {
  "ingredient": "Olive Oil"
})

Returns

// ref
{
  "@id": "hummus",
  "@type": "Food",
  "name": "Hummus",
  "vegetarian": true,
  "number": 10,
  "ingredient": [
    "Garbanzo Beans",
    "Lemon"
  ]
}