Heracles.ts

Reference implementation of a Hydra client in TypeScript.

Getting started

First you’ll need to add the Heracles.ts module to your project:

npm install @hydra-cg/heracles.ts --save

Once added, you’re ready to use the client in your code. To obtain an instance of the client just use this snippet:

import HydraClientFactory from "@hydra-cg/heracles.ts";

let hydraClient = HydraClientFactory.configure().withDefaults().andCreate();

Once the instance is obtained, you’re free to use the client, i.e.:

const resource = await hydraClient.getResource("http://some.domain/api");
for (const link of resource.hypermedia.links) {
  // do something with the link.
}

For more example, please refer to the cookbook.

Programmer’s reference is available at docs.

Hydra client factory options

There are some additional options you can use while creating a client instance. The most interesting one will be probably which resource relations should be treated as links and exposed in the links property.

These options (methods to be called on the HydraClientFactory instance) would be:

• .withAllLinks() - treats all related resources as links
• .withAllHttpLinks() - similar as above, but only HTTP(S) URLs will be considered
• .withSameRootLinks() - only URLs from the same root of the requested resource will be considered
• .withStrictLinks() - this is the default - only links exposed as hydra:link will be considered

It is also possible to use custom extensions to the client, adding i.e. support to other than built-in JSON-LD serializations of the RDF. This can be achieved either by calling:

• .with(component: IHypermediaProcessor) - accepts a custom implementation of the IHypermediaProcessor interface
• .withFactory(method: HypermediaProcessorFactory) - accepts a parameterles factory method that will provide the instance as required

Example usage with custom parameters:

import HydraClientFactory from "@hydra-cg/heracles.ts";

let hydraClient = HydraClientFactory
  .configure()
  .withDefaults()
  .withAllLinks()
  .andCreate();

Index

Enumerations

• CrawlingDirection
• Level
• LinksPolicy

Classes

• BodyResourceBoundIriTemplateExpansionStrategy
• CompoundGraphTransformer
• EntryPointCorrectingGraphTransformer
• FilterableCollection
• FilterableCollectionIterator
• FlatteningGraphTransformer
• HydraClient
• HydraClientFactory
• HypermediaContainer
• IndirectTypingProvider
• JsonLdHypermediaProcessor
• LinksCollection
• MappingsBuilder
• MappingsCollection
• OperationsCollection
• PartialCollectionCrawler
• ProcessingState
• PropertyMapping
• ResourceFilterableCollection
• StaticOntologyProvider
• TemplatedLink
• TemplatedOperation
• TemplatedResource
• TypesCollection

Interfaces

• IApiDocumentation
• IClass
• ICollection
• ICrawlingOptions
• IDictionary
• IGraphTransformer
• IHeaders
• IHydraClient
• IHydraResource
• IHypermediaContainer
• IHypermediaProcessingOptions
• IHypermediaProcessor
• IIndirectTypingProvider
• IIriTemplate
• IIriTemplateExpansionStrategy
• IIriTemplateMapping
• ILink
• IOntologyProvider
• IOperation
• IPartialCollectionIterator
• IPartialCollectionView
• IPointingResource
• IProperty
• IPropertyMapping
• IResource
• IState
• ISupportedProperty
• ITemplatedLink
• ITemplatedOperation
• ITemplatedResource
• IWebResource

Type aliases

• HeaderMatcher
• HttpCallFacility
• HypermediaProcessorFactory
• InstanceFactory
• Literal
• MappingBuilder
• MappingsProcessor
• Notification

Variables

• dependentTypes
• empty
• factories
• hydraLinks
• hydraNamespace
• hydraOntology
• jsonLdContext
• link
• literals
• mappings
• rdfNamespace
• rdfsNamespace
• templatedLink

Functions

• addTo
• apiDocumentation
• collection
• convertToResource
• createStateFrom
• discoverCollectionsFrom
• getPart
• getTargetOf
• internalLinksExtractor
• isBlank
• isHydraIndependent
• isLink
• linksAndOperations
• linksExtractor
• onLinkMaterialized
• onTemplateMaterialized
• partialCollectionIteratorFactory
• rdfSchema
• templatedOperationsExtractor
• tryCreateOperationFrom
• tryGetPredicateLinkType
• tryGetResourceLinkType
• update

Object literals

• JsonLdHelper
• hydra
• rdf
• rdfs

---

Type aliases

HeaderMatcher

Ƭ HeaderMatcher: function

Defined in JsonLd/JsonLdHypermediaProcessor.ts:22

Type declaration

▸(headers: Headers): boolean

Parameters:

Name	Type
headers	Headers

Returns: boolean

---

HttpCallFacility

Ƭ HttpCallFacility: function

Defined in HydraClientFactory.ts:16

Type declaration

▸(url: string, options?: RequestInit): Promise<Response>

Parameters:

Name	Type
url	string
Optional options	RequestInit

Returns: Promise<Response>

---

HypermediaProcessorFactory

Ƭ HypermediaProcessorFactory: function

Defined in HydraClientFactory.ts:17

Type declaration

▸(): IHypermediaProcessor

Returns: IHypermediaProcessor

---

InstanceFactory

Ƭ InstanceFactory: function

Defined in JsonLd/factories.ts:8

Type declaration

▸(resource: IResource, client: IHydraClient, processingState: ProcessingState): IResource

Parameters:

Name	Type
resource	IResource
client	IHydraClient
processingState	ProcessingState

Returns: IResource

---

Literal

Ƭ Literal: string | boolean | number

Defined in JsonLd/IPropertyMapping.ts:3

---

MappingBuilder

Ƭ MappingBuilder: function

Defined in DataModel/ITemplatedResource.ts:4

Type declaration

▸(MappingsBuilder: any): void

Parameters:

Name	Type
MappingsBuilder	any

Returns: void

---

MappingsProcessor

Ƭ MappingsProcessor: function

Defined in JsonLd/IPropertyMapping.ts:4

Type declaration

▸(items: any[], processingState: ProcessingState): any

Parameters:

Name	Type
items	any[]
processingState	ProcessingState

Returns: any

---

Notification

Ƭ Notification: function

Defined in JsonLd/ProcessingState.ts:8

Type declaration

▸(processingState: ProcessingState, resource: IResource): void

Parameters:

Name	Type
processingState	ProcessingState
resource	IResource

Returns: void

---

Variables

<Const> dependentTypes

● dependentTypes: string[] = [hydra.IriTemplateMapping, hydra.PartialCollectionView]

Defined in JsonLd/JsonLdHypermediaProcessor.ts:26

---

<Const> empty

● empty: any[] = []

Defined in DataModel/Collections/FilterableCollection.ts:4

---

<Const> factories

● factories: IDictionary<InstanceFactory>

Defined in JsonLd/factories.ts:15

Provides factory methods for strongly typed resources.

const:

type: {IDictionary}

---

<Const> hydraLinks

● hydraLinks: object

Defined in JsonLd/linksExtractor.ts:14

Type declaration

---

<Const> hydraNamespace

● hydraNamespace: “http://www.w3.org/ns/hydra/core#” = “http://www.w3.org/ns/hydra/core#”

Defined in namespaces.ts:5

Defines a Hydra Core Vocabulary namespace IRI.

constant: {string}

---

<Const> hydraOntology

● hydraOntology: any = require(“./JsonLd/hydra.json”)

Defined in HydraClientFactory.ts:14

---

<Const> jsonLdContext

● jsonLdContext: “http://www.w3.org/ns/json-ld#context” = “http://www.w3.org/ns/json-ld#context”

Defined in JsonLd/JsonLdHypermediaProcessor.ts:21

---

<Const> link

● link: TypesCollection = new TypesCollection([hydra.Link])

Defined in DataModel/TemplatedLink.ts:11 Defined in JsonLd/collection.ts:9

---

<Const> literals

● literals: string[] = [“string”, “number”, “boolean”]

Defined in JsonLd/JsonLdHypermediaProcessor.ts:24

---

<Const> mappings

● mappings: IDictionary<IPropertyMapping>

Defined in JsonLd/mappings.ts:16

Provides simple property mappings to be used when creating resources.

const:

type: {IDictionary}

---

<Const> rdfNamespace

● rdfNamespace: “http://www.w3.org/1999/02/22-rdf-syntax-ns#” = “http://www.w3.org/1999/02/22-rdf-syntax-ns#”

Defined in namespaces.ts:80

Defines RDF namespace IRI.

constant:

---

<Const> rdfsNamespace

● rdfsNamespace: “http://www.w3.org/2000/01/rdf-schema#” = “http://www.w3.org/2000/01/rdf-schema#”

Defined in namespaces.ts:97

Defines RDFS namespace IRI.

constant:

---

<Const> templatedLink

● templatedLink: string[] = [hydra.TemplatedLink]

Defined in DataModel/TemplatedLink.ts:10

---

Functions

addTo

▸ addTo(collection: ICollection[], hashList: string[], item: ICollection): void

Defined in DataModel/HypermediaContainer.ts:12

Parameters:

Name	Type
collection	ICollection[]
hashList	string[]
item	ICollection

Returns: void

---

apiDocumentation

▸ apiDocumentation(mappings: IDictionary<IPropertyMapping>): IDictionary<IPropertyMapping>

Defined in JsonLd/apiDocumentation.ts:8

Parameters:

Name	Type
mappings	IDictionary<IPropertyMapping>

Returns: IDictionary<IPropertyMapping>

---

collection

▸ collection(mappings: IDictionary<IPropertyMapping>): IDictionary<IPropertyMapping>

Defined in JsonLd/collection.ts:20

Parameters:

Name	Type
mappings	IDictionary<IPropertyMapping>

Returns: IDictionary<IPropertyMapping>

---

convertToResource

▸ convertToResource(item: any, processingState: ProcessingState): IResource

Defined in JsonLd/collection.ts:11

Parameters:

Name	Type
item	any
processingState	ProcessingState

Returns: IResource

---

createStateFrom

▸ createStateFrom(iri: string, links: LinksCollection): IState

Defined in JsonLd/partialCollectionIteratorFactory.ts:18

Parameters:

Name	Type
iri	string
links	LinksCollection

Returns: IState

---

discoverCollectionsFrom

▸ discoverCollectionsFrom(hypermedia: Iterable<IResource>): ICollection[]

Defined in DataModel/HypermediaContainer.ts:19

Parameters:

Name	Type
hypermedia	Iterable<IResource>

Returns: ICollection[]

---

getPart

▸ getPart(state: IState, link: ILink, client: IHydraClient, collectionIri: string): Promise<Iterable<IResource»

Defined in JsonLd/partialCollectionIteratorFactory.ts:31

Parameters:

Name	Type
state	IState
link	ILink
client	IHydraClient
collectionIri	string

Returns: Promise<Iterable<IResource»

---

getTargetOf

▸ getTargetOf(link: ILink): string

Defined in JsonLd/partialCollectionIteratorFactory.ts:43

Parameters:

Name	Type
link	ILink

Returns: string

---

internalLinksExtractor

▸ internalLinksExtractor(resources: any[], processingState: ProcessingState): ILink[]

Defined in JsonLd/linksExtractor.ts:66

Parameters:

Name	Type
resources	any[]
processingState	ProcessingState

Returns: ILink[]

---

isBlank

▸ isBlank(resource: object): boolean

Defined in JsonLd/JsonLdHypermediaProcessor.ts:28

Parameters:

Name	Type
resource	object

Returns: boolean

---

isHydraIndependent

▸ isHydraIndependent(resource: object): boolean

Defined in JsonLd/JsonLdHypermediaProcessor.ts:32

Parameters:

Name	Type
resource	object

Returns: boolean

---

isLink

▸ isLink(type: any): boolean

Defined in JsonLd/linksExtractor.ts:23

Parameters:

Name	Type
type	any

Returns: boolean

---

linksAndOperations

▸ linksAndOperations(mappings: IDictionary<IPropertyMapping>): IDictionary<IPropertyMapping>

Defined in JsonLd/linksAndOperations.ts:9

Parameters:

Name	Type
mappings	IDictionary<IPropertyMapping>

Returns: IDictionary<IPropertyMapping>

---

<Const> linksExtractor

▸ linksExtractor(resources: any, processingState: any): LinksCollection

Defined in JsonLd/linksExtractor.ts:107

Parameters:

Name	Type
resources	any
processingState	any

Returns: LinksCollection

---

onLinkMaterialized

▸ onLinkMaterialized(processingState: ProcessingState, link: ILink, templateIri: string, operations: IOperation[]): void

Defined in JsonLd/templatedOperationsExtractor.ts:19

Parameters:

Name	Type
processingState	ProcessingState
link	ILink
templateIri	string
operations	IOperation[]

Returns: void

---

onTemplateMaterialized

▸ onTemplateMaterialized(processingState: ProcessingState, template: IIriTemplate, linkIri: string, operations: IOperation[]): void

Defined in JsonLd/templatedOperationsExtractor.ts:10

Parameters:

Name	Type
processingState	ProcessingState
template	IIriTemplate
linkIri	string
operations	IOperation[]

Returns: void

---

partialCollectionIteratorFactory

▸ partialCollectionIteratorFactory(resource: IResource, client: IHydraClient, processingState: ProcessingState): IResource

Defined in JsonLd/partialCollectionIteratorFactory.ts:47

Parameters:

Name	Type
resource	IResource
client	IHydraClient
processingState	ProcessingState

Returns: IResource

---

rdfSchema

▸ rdfSchema(mappings: IDictionary<IPropertyMapping>): IDictionary<IPropertyMapping>

Defined in JsonLd/rdfSchema.ts:8

Parameters:

Name	Type
mappings	IDictionary<IPropertyMapping>

Returns: IDictionary<IPropertyMapping>

---

<Const> templatedOperationsExtractor

▸ templatedOperationsExtractor(operations: IOperation[], processingState: ProcessingState): OperationsCollection

Defined in JsonLd/templatedOperationsExtractor.ts:46

Parameters:

Name	Type
operations	IOperation[]
processingState	ProcessingState

Returns: OperationsCollection

---

tryCreateOperationFrom

▸ tryCreateOperationFrom(processingState: ProcessingState, link: ILink, template: IIriTemplate, operations: IOperation[]): void

Defined in JsonLd/templatedOperationsExtractor.ts:28

Parameters:

Name	Type
processingState	ProcessingState
link	ILink
template	IIriTemplate
operations	IOperation[]

Returns: void

---

tryGetPredicateLinkType

▸ tryGetPredicateLinkType(predicate: string, processingState: ProcessingState): string

Defined in JsonLd/linksExtractor.ts:27

Parameters:

Name	Type
predicate	string
processingState	ProcessingState

Returns: string

---

tryGetResourceLinkType

▸ tryGetResourceLinkType(iri: string, type: string[], processingState: ProcessingState): string

Defined in JsonLd/linksExtractor.ts:39

Parameters:

Name	Type
iri	string
type	string[]
processingState	ProcessingState

Returns: string

---

update

▸ update(state: IState, iri: string, links: LinksCollection): IState

Defined in JsonLd/partialCollectionIteratorFactory.ts:22

Parameters:

Name	Type
state	IState
iri	string
links	LinksCollection

Returns: IState

---

Object literals

<Const> JsonLdHelper

JsonLdHelper: object

Defined in JsonLd/JsonLdHelper.ts:3

validKeys

▸ validKeys(instance: object, nonHydra?: boolean): Iterable<string>

Defined in JsonLd/JsonLdHelper.ts:4

Parameters:

Name	Type	Default value
instance	object	-
Default value nonHydra	boolean	false

Returns: Iterable<string>

---

---

<Let> hydra

hydra: object

Defined in namespaces.ts:11

Defines Hydra Core Vocabulary terms.

constant:

ApiDocumentation

● ApiDocumentation: string = hydraNamespace + “ApiDocumentation”

Defined in namespaces.ts:20

---

BasicRepresentation

● BasicRepresentation: string = hydraNamespace + “BasicRepresentation”

Defined in namespaces.ts:28

---

Class

● Class: string = hydraNamespace + “Class”

Defined in namespaces.ts:50

---

Collection

● Collection: string = hydraNamespace + “Collection”

Defined in namespaces.ts:41

---

IriTemplate

● IriTemplate: string = hydraNamespace + “IriTemplate”

Defined in namespaces.ts:29

---

IriTemplateMapping

● IriTemplateMapping: string = hydraNamespace + “IriTemplateMapping”

Defined in namespaces.ts:30

---

Link

● Link: string = hydraNamespace + “Link”

Defined in namespaces.ts:31

---

Operation

● Operation: string = hydraNamespace + “Operation”

Defined in namespaces.ts:60

---

PartialCollectionView

● PartialCollectionView: string = hydraNamespace + “PartialCollectionView”

Defined in namespaces.ts:42

---

Resource

● Resource: string = hydraNamespace + “Resource”

Defined in namespaces.ts:65

---

Status

● Status: string = hydraNamespace + “Status”

Defined in namespaces.ts:61

---

SupportedProperty

● SupportedProperty: string = hydraNamespace + “SupportedProperty”

Defined in namespaces.ts:51

---

TemplatedLink

● TemplatedLink: string = hydraNamespace + “TemplatedLink”

Defined in namespaces.ts:32

---

VariableRepresentation

● VariableRepresentation: string = hydraNamespace + “VariableRepresentation”

Defined in namespaces.ts:33

---

apiDocumentation

● apiDocumentation: string = hydraNamespace + “apiDocumentation”

Defined in namespaces.ts:14

---

collection

● collection: string = hydraNamespace + “collection”

Defined in namespaces.ts:35

---

description

● description: string = hydraNamespace + “description”

Defined in namespaces.ts:15

---

entrypoint

● entrypoint: string = hydraNamespace + “entrypoint”

Defined in namespaces.ts:16

---

expects

● expects: string = hydraNamespace + “expects”

Defined in namespaces.ts:53

---

expectsHeader

● expectsHeader: string = hydraNamespace + “expectsHeader”

Defined in namespaces.ts:54

---

first

● first: string = hydraNamespace + “first”

Defined in namespaces.ts:67

---

freetextQuery

● freetextQuery: string = hydraNamespace + “freetextQuery”

Defined in namespaces.ts:68

---

last

● last: string = hydraNamespace + “last”

Defined in namespaces.ts:69

---

mapping

● mapping: string = hydraNamespace + “mapping”

Defined in namespaces.ts:22

---

member

● member: string = hydraNamespace + “member”

Defined in namespaces.ts:36

---

method

● method: string = hydraNamespace + “method”

Defined in namespaces.ts:55

---

namespace

● namespace: string = hydraNamespace

Defined in namespaces.ts:12

---

next

● next: string = hydraNamespace + “next”

Defined in namespaces.ts:70

---

operation

● operation: string = hydraNamespace + “operation”

Defined in namespaces.ts:63

---

pageIndex

● pageIndex: string = hydraNamespace + “pageIndex”

Defined in namespaces.ts:37

---

pageReference

● pageReference: string = hydraNamespace + “pageReference”

Defined in namespaces.ts:38

---

possibleStatus

● possibleStatus: string = hydraNamespace + “possibleStatus”

Defined in namespaces.ts:56

---

previous

● previous: string = hydraNamespace + “previous”

Defined in namespaces.ts:71

---

property

● property: string = hydraNamespace + “property”

Defined in namespaces.ts:23

---

readable

● readable: string = hydraNamespace + “readable”

Defined in namespaces.ts:44

---

required

● required: string = hydraNamespace + “required”

Defined in namespaces.ts:45

---

returns

● returns: string = hydraNamespace + “returns”

Defined in namespaces.ts:57

---

returnsHeader

● returnsHeader: string = hydraNamespace + “returnsHeader”

Defined in namespaces.ts:58

---

search

● search: string = hydraNamespace + “search”

Defined in namespaces.ts:72

---

supportedClass

● supportedClass: string = hydraNamespace + “supportedClass”

Defined in namespaces.ts:17

---

supportedOperation

● supportedOperation: string = hydraNamespace + “supportedOperation”

Defined in namespaces.ts:46

---

supportedProperty

● supportedProperty: string = hydraNamespace + “supportedProperty”

Defined in namespaces.ts:47

---

template

● template: string = hydraNamespace + “template”

Defined in namespaces.ts:24

---

title

● title: string = hydraNamespace + “title”

Defined in namespaces.ts:18

---

totalItems

● totalItems: string = hydraNamespace + “totalItems”

Defined in namespaces.ts:39

---

variable

● variable: string = hydraNamespace + “variable”

Defined in namespaces.ts:25

---

variableRepresentation

● variableRepresentation: string = hydraNamespace + “variableRepresentation”

Defined in namespaces.ts:26

---

view

● view: string = hydraNamespace + “view”

Defined in namespaces.ts:73

---

writeable

● writeable: string = hydraNamespace + “writeable”

Defined in namespaces.ts:48

---

---

<Let> rdf

rdf: object

Defined in namespaces.ts:86

Defines useful RDF terms.

constant:

Property

● Property: string = rdfNamespace + “Property”

Defined in namespaces.ts:89

---

namespace

● namespace: string = rdfNamespace

Defined in namespaces.ts:87

---

type

● type: string = rdfNamespace + “type”

Defined in namespaces.ts:90

---

---

<Let> rdfs

rdfs: object

Defined in namespaces.ts:103

Defines useful RDFS terms.

constant:

comment

● comment: string = rdfsNamespace + “comment”

Defined in namespaces.ts:106

---

domain

● domain: string = rdfsNamespace + “domain”

Defined in namespaces.ts:107

---

label

● label: string = rdfsNamespace + “label”

Defined in namespaces.ts:108

---

namespace

● namespace: string = rdfsNamespace

Defined in namespaces.ts:104

---

range

● range: string = rdfsNamespace + “range”

Defined in namespaces.ts:109

---

---

This site is open source. Improve this page.