@jalik/hal

@jalik/hal

H.A.L. (Hypertext Application Language) TypeScript declarations and functions.

Features

• Create HAL resources
• Create HAL paginated resources
• Consume HAL embedded data
• TypeScript declarations ♥

Installing

npm i -P @jalik/hal

yarn add @jalik/hal

Creating an HAL resource

import { createHalResource } from '@jalik/hal'

const user = {
  username: 'admin'
}

const roles = [
  { name: 'administrator' }
]

// we can add links to roles (optional)
const rolesResources = roles.map((role) => createHalResource(role, undefined, {
  self: { href: `http://localhost/roles/${role.name}` }
}))

const embedded = {
  roles: rolesResources
}

const links = {
  self: { href: 'http://localhost/users/admin' }
}

const resource = createHalResource(user, embedded, links)

Creating an HAL paged resource

import { createHalPagedResource } from '@jalik/hal'

const users = [
  { username: 'admin' },
  { username: 'john' }
]

// we can add links to users (optional)
const usersResources = users.map((user) => createHalResource(user, undefined, {
  self: { href: `http://localhost/users/${user.username}` }
}))

const embedded = {
  users: usersResources
}

const page = {
  number: 3,
  size: 2,
  totalElements: 10,
  totalPages: 5
}

const links = {
  first: 'http://localhost/users?p=1',
  prev: 'http://localhost/users?p=2',
  self: 'http://localhost/users?p=3',
  next: 'http://localhost/users?p=4',
  last: 'http://localhost/users?p=5',
}

const resource = createHalPagedResource(embedded, page, links)

Getting the HAL embedded values

import { getHalEmbedded } from '@jalik/hal'

const doc = {
  username: 'admin',
  _embedded: {
    roles: [
      { name: 'administrator' },
      { name: 'member' }
    ]
  }
}

const embedded = getHalEmbedded(doc)
// embedded = { roles[] }

Getting the HAL links

import { getHalLinks } from '@jalik/hal'

const doc = {
  username: 'admin',
  _links: {
    self: { href: 'http://localhost/users/admin' }
  }
}

const links = getHalLinks(doc)
// links = { self }

Getting the HAL page information

import { getHalPage } from '@jalik/hal'

const doc = {
  _embedded: { users: [] },
  page: {
    number: 1,
    size: 0,
    totalElements: 0,
    totalPages: 1
  }
}

const page = getHalPage(doc)
// page = { number, size, totalElements, totalPages }

Changelog

History of releases is in the changelog on GitHub.

License

The code is released under the MIT License.

Changelog

v1.0.1 (2025-01-09)

• fix: do not require embedded type when using HalResource type
• chore(deps): upgrade dependencies