https://github.com/studiohyperdrive/hal-tools
https://github.com/studiohyperdrive/hal-tools
Last synced: 9 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/studiohyperdrive/hal-tools
- Owner: studiohyperdrive
- Created: 2020-12-16T11:13:13.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2023-06-29T10:56:47.000Z (almost 3 years ago)
- Last Synced: 2025-05-31T10:49:43.478Z (11 months ago)
- Language: TypeScript
- Size: 454 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Studio Hyperdrive HAL Toolset
## General
WARNING: This package has been renamed to [@studiohyperdrive/nodejs-hal-tools](https://www.npmjs.com/package/@studiohyperdrive/nodejs-hal-tools).
This repo contains a set of tools for working with HAL standards.
It is build with:
- node: `v12.20.0` ( ~ `lts/erbium`)
- npm: `6.14.8`
For a complete list of packages and version check out the `package.json` file.
## Use
### Install
You can install this package by doing:
``` bash
$ npm install @studiohyperdrive/nodejs-hal-tools
```
or if you use Yarn:
``` bash
$ yarn add @studiohyperdrive/nodejs-hal-tools
```
### In your code
In your code, you can use this package and it's interfaces like this:
```typescript
import { HALFormat } from '@studiohyperdrive/nodejs-hal-tools';
class DoSomething {
public async findAll(page: number, size: number): Promise> {
const [entities, totalElements] = await this.MyEntitiyRepository.findAndCount(
calculateTakeSkip(page, size),
);
const key = 'my-entities';
const path = `https://my-api.com/v1/api/${key}`;
return HALFormat({
path,
key,
entities,
page,
size,
totalElements,
});
}
}
```
This will transform your entities and count to a HAL formatted response which you can return to the client.
#### Parameters
- `path`: The path parameter is optional, if omitted, the _links section is not added
- `maxPages`: An optional parameter that limits the maximum number of pages returned. This can be useful in scenario's with lots of items, where querying with limit/offset can be time consuming. To prevent the user from navigating to e.g. page 599, you can limit that number using the `maxPages` parameter.
### What's in the package?
This package exposes the following functions:
- `calculateTotalPages`: This function will calculate the total amount of pages based on the pagesize & total amount of items.
- `calculatePagination`: This function will calculate and return all pagination properties.
- `calculateNextPage`: This function will calculate your next page or, when there is none, return your current page.
- `createHalLinks`: This function will create a set of links required by the HAL Format.
- `HALFormat`: This function is the main one which will use the above and your input to transform your input to a HAL-formatted object.
And the following interfaces:
- `IHALLink`: An interface for a single HAL link.
- `IHALLinks`: An interface for the `_links` property.
- `IHALEntities`: An interface for the `_embedded` property, takes in an optional `T`.
- `IHALPagination`: An interface for the `_page` property.
- `IHALFormat`: An interface for the HAL formatted object containing the above properties.
- `IHALFormatParams`: An interface for the arguments of the `HALFormat` function.
## Setup for contribution
### Clone and install dependencies
To setup this project, clone the repo and run `npm i` to install the dependencies.
### NPM
The available commands for building the project are:
| command | runs |
|--------------|-----------------------------------------------------------------------------------------------------------|
| build | This script runs tsc to compile and your code (target to the `dist` folder). |
| prepare | This script runs the `npm run build` command, it is a hook on the npm publish. |
The available commands for testing the project are:
| command | runs |
|--------------|-----------------------------------------------------------------------------------------------------------|
| lint | This script will run linting and fix what it can. |
| test | This script will run your Jest tests for the library and create a coverage report. |
| test | This script will run your Jest tests but with the `--watchAll` flag. It does not create a coverage report.|
## Publish
This project can be published to the npm registry. To do so follow these steps:
1. Run `npm version ` to create a new version and commit + tag it.
2. Open a Merge Request on Github.
3. Once your changes have been commited to the main-branch, you can publish to the repo.
4. Run `npm publish`.
## Team
This project has been created by:
- Denis Valcke: denis.valcke@studiohyperdrive.be
It is currently maintained by:
- Denis Valcke: denis.valcke@studiohyperdrive.be