# web-annotation-utils

TypeScript types and utility functions for handling Web Annotations.

A Web Annotation, as defined by the [Web Annotation Data Model][] is basically a JSON object with a target (what the note is ‘about’) and a body (the note ‘content’); along with optional metadata (creator, date, motivation, etc.). This module provides a TypeScript type declaration for Web Annotations.

Besides the type definition, it provides convenience functions for dealing with Web Annotations, such as getting the URL(s) of pages an annotation targets, or the plain text content the annotation body. It aims to provide some basic tools to get started writing interoperable annotation tools without having to deal with the intricacies of the data model.

[Web Annotation Data Model]: https://www.w3.org/TR/annotation-model/

## Usage

Install, using npm or equivalent:

```
npm install git+https://code.treora.com/gerben/web-annotation-utils#latest
```

Usage example:

```
import type { WebAnnotation } from 'web-annotation-utils';
import { completeAnnotationStub, getTargetUrls } from 'web-annotation-utils';

const webAnnotation: WebAnnotation = completeAnnotationStub({
  "bodyValue": "interesting.",
  "target": [
    "http://example.org/page1",
    {
      "source": "http://example.org/page2",
      "selector": {
        "type": "TextQuoteSelector",
        "exact": "bla bla bla",
      }
    }
  ]
});

const targetUrls = getTargetUrls(webAnnotation.target);
// [ 'http://example.org/page1', 'http://example.org/page2' ]
```


## Types

See [WebAnnotation.ts](./WebAnnotation.ts).

<!-- TSDOC_START -->

## :toolbox: Functions

- [asArray](#gear-asarray)
- [asSingleValue](#gear-assinglevalue)
- [findTargetsInDocument](#gear-findtargetsindocument)
- [findTargetInDocument](#gear-findtargetindocument)
- [completeAnnotationStub](#gear-completeannotationstub)
- [getSingleCreatorName](#gear-getsinglecreatorname)
- [targetsUrl](#gear-targetsurl)
- [getTargetUrls](#gear-gettargeturls)
- [getTargetUrl](#gear-gettargeturl)
- [getTargetQuotes](#gear-gettargetquotes)
- [getTargetQuote](#gear-gettargetquote)

### :gear: asArray

| Function | Type |
| ---------- | ---------- |
| `asArray` | `<T>(value: ZeroOrMore<T>) => T[]` |

### :gear: asSingleValue

| Function | Type |
| ---------- | ---------- |
| `asSingleValue` | `<T>(value: ZeroOrMore<T>) => T` |

### :gear: findTargetsInDocument

Find the Elements and/or Ranges in the document the annotation targets, if
any.

This supports the following selector types:
- CssSelector
- TextQuoteSelector
- TextPositionSelector
- RangeSelector

| Function | Type |
| ---------- | ---------- |
| `findTargetsInDocument` | `(target: OneOrMore<Target>, document?: Document) => Promise<DomMatch[]>` |

### :gear: findTargetInDocument

Find the Elements and/or Ranges in the document the annotation targets, if
any, given a single target.

This supports the following selector types:
- CssSelector
- TextQuoteSelector
- TextPositionSelector
- RangeSelector

| Function | Type |
| ---------- | ---------- |
| `findTargetInDocument` | `(target: Target, document?: Document) => Promise<DomMatch[]>` |

### :gear: completeAnnotationStub

Turn a partial annotation into a ‘well-formed’ WebAnnotation.

It sets the following properties, if absent in the given stub:
- `@context` as required
- `type` as required, to `'Annotation'`
- `created` as recommended (to the current time)
- `target` to `'about:invalid'`

| Function | Type |
| ---------- | ---------- |
| `completeAnnotationStub` | `(annotationStub: Partial<WebAnnotation>) => WebAnnotation` |

### :gear: getSingleCreatorName

Get the name of the creator. If there are multiple, returns the first.
Assumes the creator is a nested Agent object: if the creator a string
(presumably the URL of an Agent node), `undefined` is returned.

| Function | Type |
| ---------- | ---------- |
| `getSingleCreatorName` | `(annotationOrBody: WebAnnotation or BodyObject) => string` |

### :gear: targetsUrl

Check whether the annotation likely targets the given URL.

The word “likely” is used because, in its comparison, this ignores the URL
scheme, fragment and query parameters.

Note that, strictly speaking, a URL should be treated as an opaque string.
In practice, it may however be useful to consider URLs as ‘likely equivalent’
in order to apply annotations targeting one URL to the document with the
very similar URL. Apply with caution: Especially a different query may,
depending on the website at hand, result in very different documents.

| Function | Type |
| ---------- | ---------- |
| `targetsUrl` | `(target: OneOrMore<Target>, url: string) => boolean` |

### :gear: getTargetUrls

Get the URLs of the resources that the annotation targets, for all its
targets.

| Function | Type |
| ---------- | ---------- |
| `getTargetUrls` | `(target: OneOrMore<Target>) => string[]` |

### :gear: getTargetUrl

Get the URL of the resource that the annotation targets, for a single
target.

| Function | Type |
| ---------- | ---------- |
| `getTargetUrl` | `(target: Target) => string` |

### :gear: getTargetQuotes

Get the exact quotes that the annotation targets using a TextQuoteSelector,
if any.

| Function | Type |
| ---------- | ---------- |
| `getTargetQuotes` | `(target: OneOrMore<Target>) => string[]` |

### :gear: getTargetQuote

Get the exact quote that a single target of an annotation targets using a
TextQuoteSelector, if any.

| Function | Type |
| ---------- | ---------- |
| `getTargetQuote` | `(target: Target) => string` |



<!-- TSDOC_END -->


## Licence

This is free and unencumbered software released into the public domain.