@devleaf-labs/jarspec-client v1.0.3
Jarspec JS/TS Client
What is Jarspec?
The JSON API Response Specification (jarspec) is a new specification provided to lay a foundation for how JSON responses from RESTful API servers should be formatted.
You can read more about Jarspec here...
What is the Jarspec client
The Jarspec client (for TS/JS) extends off of the Javascript Fetch API with powerful type features when using with an API which returns a jarspec response. Please note this library will not work with anything other than Jarspec responses by design, as a 502 error/type error will be thrown if the data returned does not match jarspec conventions.
Getting Started
You can install the jarspec client using the following commands:
# NPM
npm i @devleaf-labs/jarspec-client
# Yarn
yarn add @devleaf-labs/jarspec-client
And then use in your code as follows:
// Using Javascript
const jarspec = require('@devleaf-labs/jarspec-client');
jarspec.jarspecRequest('https://localhost:3000')
.then(response => {
console.log(response); // jarspec success response
})
.catch(err => {
console.log(err); // jarspec error response
});
// Using Typescript
import { jarspecRequest } from '@devleaf-labs/jarspec-client';
jarspecRequest<unknown>('https://localhost:3000')
.then((res: JarspecSuccessResponse) => {
console.log(res); // jarspec success response
console.log(res.data); // unknown[]|null
})
.catch((err: JarspecErrorResponse) => {
console.log(err); // jarspec error response.
});
You can type out an expected data value using jarspecRequest<T>()
where T is the format you expect your data returned in. The library will inteligently convert T
into T[]
as part of the JarspecSuccessResponse|JarspecErrorResponse
interface.
API
jarspecRequest
jarspecRequest(input: RequestInfo, init?: RequestInit) => Promise<JarspecSuccessResponse|JarspecErrorResponse>
The parameters supplied to the jarspecRequest
method are the same that would be applied to the Javascript Fetch API.
JarspecSuccessResponse
interface JarspecSuccessResponse<T = any> {
status: 'ok';
code: 200;
data: T[]|null;
id?: string;
timestamp: string;
version: '1.0.0';
}
JarspecErrorResponse
interface JarspecSuccessResponse<T = any> {
status: gRPCStatus;
code: HTTPStatus;
message: string;
data: T[]|null;
id?: string;
timestamp: string;
version: '1.0.0';
}
gRPCStatus
type gRPCStatus =
'ok'|
'invalid-argument'|
'failed-precondition'|
'out-of-range'|
'unauthenticated'|
'permission-denied'|
'not-found'|
'aborted'|
'already-exists'|
'resource-exhausted'|
'cancelled'|
'data-loss'|
'unknown'|
'internal'|
'not-implemented'|
'na'|
'unavailable'|
'deadline-exceeded';
HTTPStatus
type HTTPStatus =
200|
400|
401|
403|
404|
409|
429|
499|
500|
501|
502|
503|
504;