treora/selector-state-frags

Converter between the JSON and the URI+Fragment representation of Selectors and States

Selector State Fragments

Converts between Web Annotation Selectors and States as Fragment Identifiers and Web Annotation Data Model Selectors and States (or SpecificResources containing those).

Install

npm install selector-state-frags

…or equivalent.

Use

Convert between fragment identifier and Selector or State object:

// for fragment identifiers of the form `selector(…)`
const { selector } = parse(fragmentIdentifier)

// for fragment identifiers of the form `state(…)`
const { state } = parse(fragmentIdentifier)

const fragmentIdentifier = stringify(selectorOrState)

A SpecificResource is simply treated as a pair of { source, selector }, or { source, state }. To convert between this object and a URI with the Selector/State as its fragment identifier:

const specificResource = uriToSpecificResource(uri)

const uri = specificResourceToUri(specificResource)

With uriToSpecificResource, if the given URI contains any other type of fragment identifier (neither selector nor state), it will be converted to its equivalent FragmentSelector:

uriToSpecificResource('https://example.com/page#section4')
// {
//     source: 'https://example.com/page',
//     selector: {
//         type: 'FragmentSelector',
//         value: 'section4',
//     }
// }

With specificResourceToUri, note that if the SpecificResource contains both a Selector and a State, only the Selector will be put in the fragment identifier.

Example

const selector = {
  "type": "TextPositionSelector",
  "start": 412,
  "end": 795
}
stringify(selector) === 'selector(type=TextPositionSelector,start=412,end=795)'
// And `parse('selector(…)')` would do the reverse conversion.

const specificResource = {
    "source": "http://example.org/ebook1",
    "selector": {
      "type": "TextPositionSelector",
      "start": 412,
      "end": 795
    }
}
specificResourceToUri(specificResource) === 'http://example.org/ebook1#selector(type=TextPositionSelector,start=412,end=795)'
// And uriToSpecificResource('http://…') would do the reverse conversion.

License

Apache License 2.0