@mariolazzari/quotable NPM

Quotable REST API client

This package is a TypeScript based wrapper around the public Quotable REST APIs

Quotable REST API client

Prerequisites

This package requires NodeJS (version 18 or later) and a node package manager (Npm, Yarn, Pnpm or Bun).

To make sure you have them available on your machine, try running the following command.

$ npm -v && node -v
v10.1.0
v18.18.0

Gettting started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Installation

BEFORE YOU INSTALL: please read the prerequisites.

Start with cloning this repo on your local machine:

$ git clone https://github.com/mariolazzari/quotable
$ cd quotable

To install and set up the library, run:

npm install @mariolazzari/quotable

Usage

Import package

import { Quotable } from "@mariolazzari/quotable"

Watch mode

npm test

Unit testing

npm test

Bulding new version

npm build

This task will create a distribution version of the project inside your local dist/ folder.

Quotable class

Quotable class content handles all the requests and the responses to Quotable REST APIs.

Constructor

In order to initialize Quotable client:

const quotable = new Quotable();

Methods

Quotable client includes the following methods:

getAuthors

Description

This asynchronous method handles GET /api/authors REST API.

Prototype

async getAuthors(params:AuthorRequest): Promise<Result<AuthorResponse>>

Sample code

const sortBy: SortBy<Author> = 'quoteCount';
const order: Order = 'desc';
const { success, data, error } = await quotable.getAuthors({ 
    sortBy,
    order,
});

getQuote

Description

This asynchronous method handles GET /api/quotes/:id REST API.

Prototype

async getQuote(id:string): Promise<Result<Quote>>

Sample code

const id = '2qpi1ZKL9Ko';
const { data, error, success } = await quotable.getQuote(id);

getQuotes

Description

This asynchronous method handles GET /api/quotes REST API.

Prototype

async getQuotes(params:ListQuoteRequest): Promise<Result<ListQuoteResponse>>

Sample code

const tags = 'love | happiness';
const { data, error, success } = await quotable.getQuotes({ tags });

getRandomQuotes

Description

This asynchronous method handles GET /api/quotes/random REST API.

Prototype

async getQuotes(params:RandomQuoteRequest): Promise<Result<Quote[]>>

Sample code

const tags = 'technology,famous-quotes';
const { success, data, error } = await quotable.getRandomQuotes({ tags });

getTags

Description

This asynchronous method handles GET /api/tags REST API.

Prototype

async getTags(params:TagRequest): Promise<Result<Tag[]>>

Sample code

const sortBy: SortBy<Tag> = 'name';
const { success, data, error } = await quotable.getTags({ sortBy });

Types

Author

type Author = {
  // A unique id for this author
  _id: string;
  // A brief, one paragraph bio of the author. Source: wiki API
  bio: string;
  // A one-line description of the author. Typically it is the person's primary
  // occupation or what they are know for.
  description: string;
  // The link to the author's wikipedia page or official website
  link: string;
  // The authors full name
  name: string;
  // A slug is a URL-friendly ID derived from the authors name. It can be used as
  slug: string;
  // The number of quotes by this author
  quoteCount: string;
};

AuthorRequest

type AuthorRequest = Partial<{
  slug: string;
  sortBy: SortBy<Author>;
  order: Order;
  limit: number;
  page: number;
}>;

AuthorResponse

type AuthorResponse = {
  // The number of results included in this response.
  count: number;
  // The total number of results matching this request.
  totalCount: number;
  // The current page number
  page: number;
  // The total number of pages matching this request
  totalPages: number;
  // The 1-based index of the last result included in this response. This shows the
  // current pagination offset.
  lastItemIndex: number | null;
  // The array of authors
  results: Author[];
};

ListQuoteRequest

type ListQuoteRequest = RandomQuoteParams &
  Partial<{
    sortBy: Sort<Quote>;
    order: Order;
    page: number;
  }>;

ListQuoteResponse

type ListQuoteResponse = {
  // The number of quotes returned in this response
  count: number;
  // The total number of quotes matching this query
  totalCount: number;
  // The current page number
  page: number;
  // The total number of pages matching this request
  totalPages: number;
  // The 1-based index of the last result included in the current response.
  lastItemIndex: number;
  // The array of quotes
  results: Quote[];
};

Order

type Order = 'asc' | 'desc' | 'default';

Quote

type Quote = {
  _id: string;
  // The quotation text
  content: string;
  // The full name of the author
  author: string;
  // The `slug` of the quote author
  authorSlug: string;
  // The length of quote (number of characters)
  length: number;
  // An array of tag names for this quote
  tags: string[];
};

RandomQuoteRequest

type RandomQuoteRequest = Partial<{
  limit: number;
  maxLength: number;
  minLength: number;
  tags: string;
  author: string;
}>;

RequestParams

type RequestParams =
  | ListQuoteRequest
  | RandomQuoteRequest
  | AuthorRequest
  | TagRequest;

Result

type Result<T> = {
  success: boolean;
  data?: T;
  error?: string;
};

SortBy

type Sort<T> = keyof T;

Tag

type Tag = {
  _id: string;
  name: string;
  dateAdded: string;
  dateModified: string;
  __v: number;
  quoteCount: number;
};

TagRequest

type TagRequest = Partial<{
  sortBy: SortBy<Tag>;
  order: Order;
}>;

Authors

Mario Lazzari - Initial work

@mariolazzari/quotable v0.0.4

Quotable REST API client

Gettting started

Installation

Usage

Quotable class

Constructor

Methods

getAuthors

getQuote

getQuotes

getRandomQuotes

getTags

Types

Author

AuthorRequest

AuthorResponse

ListQuoteRequest

ListQuoteResponse

Order

Quote

RandomQuoteRequest

RequestParams

Result

SortBy

Tag

TagRequest

Authors

Links