Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

alcaeus

wikibus1kMIT3.0.2TypeScript support: included

Hydra Core hypermedia-aware client library

ajax, hydra, semanticweb, hypermedia, rdf, json-ld

readme

Alcaeus npm version Code coverage

Hydra Core library for JavaScript

Alcaeus (pronounced AL-SEE-UHS) is a Node.js/browser library for consuming Hydra APIs.

Alcaeus is the birth name of Heracles. The demigod who defeated Hydra.

Installation

Use npm or yarn:

npm i alcaeus

Requirements

Alcaues v3 is implemented only as ES Modules. It will work in recent versions on node and modern browsers.

Usage

Since v3 Alcaeus is configured using an RDF/JS Environment factory. This decouples the library from any specific RDF/JS implementation.

It is recommended to use the implementation provided by @zazuko/env which allows to easily reuse extend existing environments.

import create from 'alcaeus'
import Environment from '@zazuko/env/Environment.js'
import rdf from '@zazuko/env'

const env = new Environment(create(), { parent: rdf })

const { response, representation } = await env.hydra.loadResource('http://example.com/resource');
const rootResource = representation.root;

// contains supported classes, operations, etc.
const apiDocs = Hydra.apiDocumentations[0];

const id = rootResource.id; 

To learn more, head to http://alcaeus.hydra.how.

License

MIT

changelog

Changelog

3.0.2

Patch Changes

  • 7cfdaaa: Updated @rdfjs/types, @tpluscode/rdf-ns-builders, @tpluscode/rdfine, @rdfine/hydra
  • Updated dependencies [7cfdaaa]
  • Updated dependencies [7cfdaaa]

3.0.1

Patch Changes

  • bde6d93: Export type for alcaeus factory

3.0.0

Major Changes

  • f48a8a4: Convert to ESM-only. Other changes include:

    1. isomorphic-fetch and isomorhpic-form-data are removed as dependencies. They should be loaded by consumers if necessary
    2. Removed ./web and ./node modules. Instead, consumers must use alcaeus in conjunction with an RDF/JS environment
    3. Extracted packages alcaeus-model and alcaeus-core

Patch Changes

3.0.0-esm.1

Patch Changes

3.0.0-esm.0

Major Changes

  • f48a8a4: Convert to ESM-only. Other changes include:

    1. isomorphic-fetch and isomorhpic-form-data are removed as dependencies. They should be loaded by consumers if necessary
    2. Removed ./web and ./node modules. Instead, consumers must use alcaeus in conjunction with an RDF/JS environment
    3. Extracted packages alcaeus-model and alcaeus-core

Patch Changes

2.3.3

Patch Changes

  • d1d2e9e: Previously retrieved resource representation will be used when response has equal etag header

2.3.2

Patch Changes

  • 6793756: RequestInit default were not applied when invoking operations

2.3.1

Patch Changes

  • eabfc12: Also support function to initialize fetch RequestInit

2.3.0

Minor Changes

  • 1529482: Allow setting all of fetch RequestInit both globally, as well as on a per-request basis

2.2.4

Patch Changes

  • f883d78: Invalid base URL error would have been thrown when performing request of a relative URL

2.2.3

Patch Changes

  • 63139d0: Update @tpluscode/rdf-ns-builders to v2

2.2.2

Patch Changes

  • 61e9e74: Update @types/parse-link-header to v2

2.2.1

Patch Changes

  • 2b5ee86: Make factories exported by alcaeus/node and alcaeus/web generic

    This alleviates a breaking change inadvertently introduced in v2.2, which was to make DatasetCore the default dataset type for the client. Since it provides less methods than the previous default rdf-dataset-indexed, users may want to provide a different factory, such as rdf-ext.

    import { create } from "alcaeus/web"; // or 'alcaeus/node'
    import $rdf from "rdf-ext";
    
    // client's type will be inferred as HydraClient<DatasetExt>
    const client = create({
      datasetFactory: $rdf.dataset,
    });

2.2.0

Minor Changes

  • a5b52c5: Removed dependencies rdf-dataset-indexed, rdf-transform-triple-to-quad. Replaced with @rdfjs/dataset and rdf-dataset-ext

Patch Changes

  • f23f1e0: Operation body was ignored when headers were not provided
  • 512bcdf: Update RDF/JS formats packages

2.1.3

Patch Changes

  • 996243b: build(deps): bump parse-link-header from 1.0.1 to 2.0.0

2.1.2

Patch Changes

  • e0f34dc: ResourceRepresentation#get would not return resources which are only object of a triple

2.1.1

Patch Changes

  • 1318431: Builds would fail with "Could not find a declaration file for module 'parse-link-header'"

2.1.0

Minor Changes

  • f6cf34c: Make it possible to override request headers from Resource#load method

2.0.3

Patch Changes

  • be5b886: Error response root node would not have been selected

2.0.2

Patch Changes

  • e4da204: Add root selector for application/problem+json bodies

2.0.1

Patch Changes

  • e46dffa: Parse JSON responses as JSON-LD when there is a context Link header

2.0.0

Major Changes

1.4.0

Minor Changes

  • ad302ea: apiDocumentation property should return actual dereferenced representations (fixes #259)

1.3.1

Patch Changes

  • 04b4959: rdf-literal must be default-imported, otherwise webpack fails to bundle alcaeus

1.3.0

Minor Changes

  • b2fd347: getProperties returned only resources (fixes #248)

    WARNING: this may be a BREAKING CHANGE for clients relying on the current, broken behaviour. To keep the current return value call .getProperties({ termTypes: ['NamedNode', 'BlankNode'] }). See the docs for details

  • 0537be7: Added generic type argument to operation invoke methods

Patch Changes

  • 5536a73: Unwanted any type when implementing ResourceCacheStrategy

1.2.1

Patch Changes

  • 91808a5: Typo in ApiDocumentation#loadEntrypoint method

1.2.0

Minor Changes

  • 9894812: Added support for hydra:memberAssertion

Patch Changes

  • a15434d: Iterating response and resource count would return same resource multiple times
  • 52beb52: Update isomorphic-fetch

1.1.4

Patch Changes

  • 8d0a898: Update RDF/JS types, rdfine and rdf-ns-builders

1.1.3

Patch Changes

  • ca9dc9e: Web: Do not capture the global fetch function

    The problem is that tools which monkey-patch the Window.fetch, such as Sentry, would not work with alcaeus if it captures the original fetch function before patching happens

1.1.2

Patch Changes

  • 42e1a8c: alcaeus/node incorrectly imported formats-common

1.1.1

Patch Changes

  • 48362a0: Empty representation cannot be retrieved back from ResourceStore

1.1.0

Minor Changes

  • 9f906d6: Pass request URI to defaultHeaders

1.0.1

Patch Changes

  • c212178: Fix typing of Class mixin

All notable changes to this project will be documented in this file. See standard-version for commit guidelines.

1.0.0 (2020-12-03)

Bug Fixes

  • performance: improve operation lookup (d8dfddc)

1.0.0-RC.4 (2020-10-24)

Bug Fixes

  • ensure body reader is opened only once (3dc9018)

1.0.0-RC.3 (2020-10-22)

Bug Fixes

  • do not consume body until parsing (5bfebf2)

1.0.0-RC.2 (2020-10-20)

Bug Fixes

  • relax generic params to allow any RdfResource (2d429f8)
  • standalone loadDocumentation did not work (392622b)

1.0.0-RC.1 (2020-10-13)

Bug Fixes

  • ensure types of CoreMixins are exported (dc1ea74)

1.0.0-RC.0 (2020-10-08)

Features

  • use @rdfine/hydra for most of API model (d26566b)
  • perf: add cache wrapper over ResourceFactory (497f268)
  • cache request headers added to subsequent requests (1344d7f)

Bug Fixes

  • do not add failed responses to store (1cbd4fd)
  • ensure type augmentations are picked up (0606b9b)
  • findOperations does not find by type name node (7f2ce91)
  • make load generic (f7e378a)
  • requested (or redirected) URI used as base to parse (02a4fd5)
  • perf: include operations more selectively by namespaces (07e7aab)

1.0.0-beta.18 (2020-09-22)

1.0.0-beta.17 (2020-09-22)

Bug Fixes

  • hydra:expects allows multiple objects and not only hydra:Class (e1486f0)

1.0.0-beta.16 (2020-09-18)

Bug Fixes

  • built-in Headers was still used in code (cab40e5)

1.0.0-beta.15 (2020-09-17)

Bug Fixes

  • only use built-in URL class (1a46f09)

1.0.0-beta.14 (2020-09-17)

Features

  • create separate entrypoints for node/web (a0efc1a)

1.0.0-beta.13 (2020-09-16)

Bug Fixes

  • readable-stream must be default-imported (c46c71a)

1.0.0-beta.12 (2020-09-16)

Bug Fixes

  • esm: remove typescript interfaces from imports in mjs build (17d6966)

1.0.0-beta.11 (2020-09-02)

Bug Fixes

  • declarations: avoid this outside of interface (b498527)

1.0.0-beta.10 (2020-09-02)

Bug Fixes

  • exports must begin with dot (76e802b)

1.0.0-beta.9 (2020-09-02)

1.0.0-beta.8 (2020-09-01)

Features

  • defaultHeaders should allow async function (d6f89b5)

1.0.0-beta.7 (2020-05-19)

Bug Fixes

  • revert modules deps to support commonjs (f679111)

1.0.0-beta.6 (2020-05-18)

Features

  • use esm of formats-common to have access to parsers by default (9baca32)

Bug Fixes

  • bogus headers were sent due to qubyte/fetch-ponyfill#248 (14e2247)

1.0.0-beta.5 (2020-05-04)

Bug Fixes

  • node: replace isomorphic-fetch with fetch-ponyfill (035ce44)

1.0.0-beta.4 (2020-04-30)

Features

  • added a resource store, changed how bodies are processed (94d46ba)

Bug Fixes

  • re-export HydraResponse from main module (c932dbb)

1.0.0-beta.3 (2020-04-25)

⚠ BREAKING CHANGES

  • root selectors are now simple functions, initialized through an array of [string, func]

Bug Fixes

  • getting links failed if any object was Literal (38ce61a)
  • selecting root only work for hydra:PartialCollectionView (18d637a)

1.0.0-beta.2 (2020-04-24)

1.0.0-beta.1 (2020-04-23)

Bug Fixes

  • add required transitive dependencies to package.json (57ab8ce)

1.0.0-beta.0 (2020-04-23)

1.0.0-alpha.16 (2020-04-22)

Features

  • template: resolve relative templates against immediate parent (68221d3)

Bug Fixes

  • templates: expanding template calls "abstract" method (7e889fd)

0.10.7 (2020-03-17)

Features

  • setting base URI to allow relative resource ids (275664d)

0.10.6 (2020-02-29)

Bug Fixes

  • alcaeus had an unlisted dependency (ed80788)

1.0.0-alpha.15 (2020-04-17)

Bug Fixes

  • improve how root is selected by checking graph connections (2d36689), closes #161
  • operation finder should not traverse graphs (049f74a)

1.0.0-alpha.14 (2020-04-17)

Features

  • node: add a cjs module exporting client with all parsers (59f8311)

Bug Fixes

  • initializing alcaeus with parsers (afd6e37)

1.0.0-alpha.13 (2020-04-15)

1.0.0-alpha.12 (2020-04-14)

Bug Fixes

  • operations are searched in the resource's graph only (25d3aba)

1.0.0-alpha.11 (2020-04-02)

⚠ BREAKING CHANGES

  • no separate commonjs build may require setting up esm

Features

  • only single es modules build (76382b6)

1.0.0-alpha.10 (2020-03-12)

1.0.0-alpha.9 (2020-02-04)

Bug Fixes

  • build: reduce bundle size by updating rdf-transform-to-quad (fa9cc01)

1.0.0-alpha.8 (2020-01-29)

⚠ BREAKING CHANGES

  • parsers have to be provided explicitly by the calling application
  • content type is mandatory on operations with body

  • remove dependency on JSON-LD parser and simplify rdf handling (4065aa3)

1.0.0-alpha.7 (2020-01-28)

1.0.0-alpha.6 (2020-01-27)

Features

  • make collection generic for nicer runtime typings (15483e3)

Bug Fixes

  • collection mixin was ot hooked up to factory (604de05)
  • required dependency string-to-stream missing (259bf16)

1.0.0-alpha.5 (2020-01-26)

Bug Fixes

  • add NamedNode to inout type foe load methods (d60a1b0)

1.0.0-alpha.4 (2020-01-23)

Bug Fixes

  • also export Operation from main (e1e8c44)
  • invoked operation does not return the representation object (2a8a214)

1.0.0-alpha.3 (2020-01-19)

Bug Fixes

  • change api documentation promise to return instances (a82bdcd)
  • remove deprecated code (5a07cff)
  • rename and reorganize interfaces (46c3d73)

1.0.0-alpha.2 (2020-01-17)

Bug Fixes

  • resource: getArray should only return resources (aa1f860)

1.0.0-alpha.1 (2020-01-17)

Features

  • load method to allow named node param (1e4cf66)

1.0.0-alpha.2 (2020-01-17)

Features

  • load method to allow named node param (74f37e7)

1.0.0-alpha.1 (2020-01-17)

Features

  • load method to allow named node param (dc165d7)

1.0.0-alpha.0 (2020-01-17)

0.10.5 (2019-12-07)

Bug Fixes

  • headers are not getting correctly applied (77f8fbb)

0.10.4 (2019-12-04)

Bug Fixes

  • missing import of FormData in node environment (4a5b378)

0.10.3 (2019-11-24)

Bug Fixes

  • form data should automatically set multipart content type (965bcc2)

0.10.2 (2019-11-21)

Features

  • added methods to find operations on resources, also recursively (fac47cc)

Bug Fixes

  • change return type annotation for getCollections (bded51e)
  • duplicate operation returned when supported by two resource types (#150) (20878f6)
  • findOperationsDeep did not apply default filter (88c5dbb)

0.10.0 (2019-10-31)

Bug Fixes

  • deps: make gitbook stuff dev dependencies (61a7840)

Build System

  • bump version to use on gitbook (5dd85f7)
  • ensure that import casing matches file names (f1006f8)

Features

  • explicitly add triples inferred from the manages block (7fc3178), closes #147
  • explicitly assert props and operations from subClassOf relation (8ab6cf5), closes #145

0.9.2 (2019-10-17)

Bug Fixes

  • wrap rdf:List resources in an Array object (d2e1b09)

Build System

  • deps: [security] bump eslint-utils from 1.3.1 to 1.4.2 (b53d877)

0.9.1 (2019-08-16)

Bug Fixes

  • headers do not get properly overridden when casing differs (7f3a62e)
  • warn about unsupported media type (661c966), closes #47

Tests

  • make sure header merging accepts arrays (93723f8)

0.9.0 (2019-08-15)

Features

  • set default headers for all api requests (e150767)
  • fetch: setting request headers on individual calls (9343d55)

0.8.1 (2019-08-12)

Bug Fixes

  • extend the return type of operation.target (724fcf2)
  • proper typing for implementation of mediaTypeProcessors (e465bc1)
  • wrong predicate used for SupportedProperty#writable (d293503)

Build System

  • deps: [security] bump tar from 2.2.1 to 2.2.2 (6f0e265)

0.8.0 (2019-08-11)

Bug Fixes

  • literals should be converted to native values (52877f0)

Build System

  • deps: [security] bump extend from 3.0.0 to 3.0.2 (de18658)
  • deps: [security] bump fstream from 1.0.10 to 1.0.12 (e5fbfd7)
  • deps: [security] bump https-proxy-agent from 2.0.0 to 2.2.2 (15c696c)
  • deps: [security] bump is-my-json-valid from 2.13.1 to 2.20.0 (cf45e33)
  • deps: [security] bump stringstream from 0.0.5 to 0.0.6 (e2d65b4)
  • deps: [security] bump tough-cookie from 2.3.1 to 2.3.4 (77e6662)

Features

  • expose a target property on IOperation (0cf8e56)

0.7.1 (2019-08-05)

Bug Fixes

  • problem building upstream project with strict compilation (189a47a)

Build System

  • deps: [security] bump brace-expansion from 1.1.6 to 1.1.11 (1f1b982)
  • deps: [security] bump http-proxy-agent from 2.0.0 to 2.1.0 (301999c)
  • deps: [security] bump sshpk from 1.9.2 to 1.16.1 (fc94742)
  • deps: [security] bump tar-fs from 1.15.3 to 1.16.3 (f32dc2b)

0.7.0 (2019-08-02)

Bug Fixes

  • canonical link selector should resolve relative links (46f3fd2)
  • reverse links not calculated for multiple triple objects (7678378)
  • typings: missing return value of IOperation#invoke (196e47f)

Features

  • add a method to quickly load resources (852f05c), closes #55
  • added indexer signature and bunch of type guards (121cffe), closes #116
  • create a root selector for 201 response with location (5f45323)

Tests

  • missing tests to boost coverage (c701b44)
  • test IriTemplateMapping properties (c8caac6)

0.6.3 (2019-06-27)

Bug Fixes

  • collections: type views as IResource (eb3f2f9), closes #83

Features

  • operations: publicly expose underlying supported operation (7ef5d35f)

Build System

0.6.2 (2019-05-23)

Bug Fixes

Features

0.6.1 (2019-05-23)

Bug Fixes

Documentation

0.6.0 (2019-05-19)

Features

BREAKING CHANGES

0.5.3 (2019-05-01)

Bug Fixes

0.5.2 (2019-05-01)

Bug Fixes

0.5.1 (2019-04-09)

Bug Fixes

0.5.0 (2019-03-26)

Bug Fixes

Chores

0.4.6 (2019-02-17)

Bug Fixes

0.4.5 (2019-01-24)

Bug Fixes

0.4.4 (2019-12-13)

Bug Fixes

Chores

Features

0.4.3 (2018-10-30)

Bug Fixes

Build System

0.4.2 (2018-07-21)

Chores

  • fix declaration generation and packaging (1ba5c7c)

0.4.1 (2018-06-19)

Bug Fixes

  • handle bool fals in _get (7743c50)

Build System

0.4.0 (2018-06-17)

Too much to manually back fill.