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

# Bun
bun 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;