Resolve function and general housekeeping (#30)

Author: dillonredding

.github/workflows/npm-publish.yaml

@@ -13,7 +13,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: 16
+          node-version: 18
           registry-url: https://registry.npmjs.org/
       - name: Set version from tag
         run: npm version ${{ github.event.release.tag_name }} --no-git-tag-version

.nvmrc

@@ -0,0 +1 @@
+v18

CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0]
+
+### Added
+
+- `resolve` function for resolving a `SubEntity`
+- [Development section in the README](./README.md#development)
+
+### Changed
+
+- Project is now built with Node 18
+
+### Removed
+
+- Contribution guidelines and code of conduct, which now live [here](https://github.com/siren-js/.github/tree/main/profile)
+
 ## [0.7.0] - 2023-04-20
 
 > **NOTE:** This release includes breaking changes from [v0.6.0](#060---2023-03-06).

CODE_OF_CONDUCT.md

@@ -4,7 +4,7 @@
 [![Build Workflow](https://img.shields.io/github/actions/workflow/status/siren-js/client/build.yaml?style=flat-square)]()
 [![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
 [![License](https://img.shields.io/github/license/siren-js/client?style=flat-square)](LICENSE)
-[![Contributing](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat-square)](CONTRIBUTING.md)
+[![Contributing](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat-square)](https://github.com/siren-js/.github/blob/main/profile/CONTRIBUTING.md)
 
 [Siren](https://github.com/kevinswiber/siren) API client library for JavaScript
 
@@ -23,6 +23,7 @@ Siren is a very powerful hypermedia format that enables a server and its clients
 - [Background](#background)
 - [Install](#install)
 - [Usage](#usage)
+- [Development](#development)
 - [API](#api)
 - [Maintainer](#maintainer)
 - [Contributing](#contributing)
@@ -77,6 +78,39 @@ if (editAction != null) {
 }
 ```
 
+## Development
+
+```sh
+# setup Node.js
+$ nvm use
+
+# test with Jest
+$ npm test
+# run tests in watch mode
+$ npm run test:watch
+# run tests with coverage
+$ npm run test:cov
+
+# compile TypeScript code
+$ npm run compile
+
+# lint with ESLint
+$ npm run lint
+# automatically fix lint issues where possible
+$ npm run lint:fix
+
+# format files with Prettier
+$ npm run format
+# check files for proper formatting
+$ npm run format:check
+
+# build the library (compile, lint, format check)
+$ npm run build:lib
+
+# generate docs with TypeDoc
+$ npm run build:docs
+```
+
 ## API
 
 See our [docs](https://siren-js.github.io/client).
@@ -87,7 +121,7 @@ See our [docs](https://siren-js.github.io/client).
 
 ## Contributing
 
-See our [contribution guidelines](./CONTRIBUTING.md).
+See our [contribution guidelines](https://github.com/siren-js/.github/blob/main/profile/CONTRIBUTING.md).
 
 PRs accepted.
 

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 {
   "name": "@siren-js/client",
   "version": "0.0.0",
-  "description": "Client class for communicating with Siren APIs",
+  "description": "Siren API client library",
   "files": [
     "/dist"
   ],
@@ -27,6 +27,7 @@
   },
   "keywords": [
     "API",
+    "client",
     "HATEOAS",
     "hypermedia",
     "REST",

README.md

@@ -0,0 +1,37 @@
+import nock from 'nock';
+
+import { entity, siren } from '../test/stubs';
+import { EmbeddedEntity, EmbeddedLink } from './';
+import { resolve } from './resolve';
+
+describe('resolve', () => {
+  beforeEach(() => {
+    if (!nock.isActive()) {
+      nock.activate();
+    }
+  });
+
+  afterEach(() => {
+    nock.restore();
+  });
+
+  it('should return EmbeddedEntity', async () => {
+    const subEntity = new EmbeddedEntity();
+
+    const result = await resolve(subEntity);
+
+    expect(result).toBe(subEntity);
+  });
+
+  it('should follow and parse EmbeddedLink', async () => {
+    const url = 'https://api.example.com/foo';
+    const subEntity = new EmbeddedLink();
+    subEntity.href = url;
+    const scope = nock(url).get('').reply(200, siren);
+
+    const result = await resolve(subEntity);
+
+    expect(result).toStrictEqual(entity);
+    expect(scope.isDone()).toBe(true);
+  });
+});

_config.yml

@@ -0,0 +1,15 @@
+import { follow } from './follow';
+import { EmbeddedLink, Entity, SubEntity } from './models';
+import { parse } from './parse';
+
+/**
+ * Resolves a {@linkcode SubEntity} to an {@linkcode Entity}. An
+ * `EmbeddedEntity` is returned as is, while an {@linkcode EmbeddedLink} is
+ * {@linkcode follow | followed} and {@linkcode parse | parsed}.
+ */
+export async function resolve<T extends object = object>(subEntity: SubEntity): Promise<Entity<T>> {
+  if (subEntity instanceof EmbeddedLink) {
+    return follow(subEntity).then(parse) as Promise<Entity<T>>;
+  }
+  return Promise.resolve(subEntity as unknown as Entity<T>);
+}