ts-apicalypse v0.4.2

ts-apicalypse

A Typescript client and request builder for Apicalypse.

If you are searching for a lib with IGDB types baked-in, check ts-igdb-client.

Why?

Long story short, node Apicalypse client is good if you are writing Javascript only code. But if you need strong type checking and inference, it's not enough. The patterns used inside the original client make it impossible to have strict typing or inference (e.g. when using fields queries). (see current DefinitelyTyped)

Usage

Consider the following type for the different usages:

type DEMO = {
  id: number,
  name: string,
  games: { id: number, name: string }[],
  collection: { id: number, name: string, demo: DEMO }
};

Simple request

import { request, fields, exclude, where } from 'ts-apicalypse';

const { data } = await request<DEMO>() // DEMO is the complete typing of the objects that can be returned by the endpoint
  .pipe(
    fields(['name']), // `fields` are type checked. Here valid fields would be 'id' | 'name' | 'games' | 'collection' |
                      // 'games.id' | 'games.name' | 'games.*' |
                      // 'collection.id' | 'collection.name' | 'collection.*'
                      // or even deeply nested one like 'collection.demo.name' or 'collection.demo.games.*', etc.
    where('created_at', '<',  now), // The prop, the operator and the value are type checked
  ).execute('https://...'); // Execute the query

// Infered type of `data` is:
type Data = {
  id: number,   // always returned
  name: string  // requested via fields
}

// another example using `exclude` operator
const { data } = await request<DEMO>()
  .pipe(
    fields('*'),      // All fields...
    exclude(['name']) // ... except name
  ).execute('https://...');

Request nested fields

import { request, fields, sort, limit, offset } from 'ts-apicalypse';

const { data } = await request<DEMO>()
    .pipe(
      fields(['name', 'games', 'collection.*']),
      sort('created_at', '<'), // sort, asc by default
      limit(10),  // pagination
      offset(10), // pagination
    ).execute('https://...')

// Infered type of `data` is:
type Data = {
  id: number,     // always returned
  name: string    // requested via fields
  games: number[] // requested via fields. No fields requested, so it's only an array of IDs
  collection: {   // requested via fields. All fields requested
    id: number,
    name: string,
    demo: number,
  }  
}

Request with complex conditions

import { request, fields, or, and, where, whereIn, WhereFlags, WhereInFlags } from 'ts-apicalypse';

const { data } = await request<DEMO>()
  .pipe(
    fields('*'),
    // demo of possible combinations 
    and(
      where('id', '>', 4),
      where('id', '>=', 4),
      where('id', '<', 4),
      where('id', '<=', 4),
      where('name', '=', 'zelda'),   // name is zelda (case sensitive)
      where('name', '~', 'zelda'),   // name is zelda (case insensitive)
      where('name', '!=', 'zelda'),  // name is not zelda
      where('name', '=', 'zelda', WhereFlags.STARTSWITH),  // name starts with zelda (also works with ~)
      where('name', '=', 'zelda', WhereFlags.ENDSWITH),    // name ends with zelda (also works with ~)
      where('name', '=', 'zelda', WhereFlags.CONTAINS),    // name contains zelda (also works with ~)
      where('name', '=', null),  // no name
      where('name', '!=', null), // name exists
      where('collection.demo.name', '=', 'zelda'), // nested types are also supported
      or(
        where('name', '=', 'zelda'),
        whereIn('name', ['mario', 'luigi']),
        whereIn('games', [1, 2], WhereInFlags.AND),   // Results whose games ids includes 1 and 2
        whereIn('games', [1, 2], WhereInFlags.OR),    // Results whose games ids includes 1 or 2
        whereIn('games', [1, 2], WhereInFlags.NAND),  // Results whose games ids does not contain both 1 and 2, but can be 1 or 2
        whereIn('games', [1, 2], WhereInFlags.NOR),   // Results whose games ids does not contain 1 or does not contain 2
        whereIn('games', [1, 2], WhereInFlags.EXACT), // Results whose exclusive games ids are 1 and 2
        whereIn('collection.demo.name', ['mario', 'luigi']), // nested types are also supported
      )
    )
  ).execute('https://...');

Count query

Most query will return requested fields as response data. But count actually return data differently:

import { request, fields, exclude } from 'ts-apicalypse';

const { data } = await request<DEMO, 'count'>() // Here the query is tagged as a "count" query
  .pipe() // you can have no operators, or specify some conditions
  .execute('https://.../count'); // some endpoint returning count data

// Infered type of `data` is:
type Data = {
  count: number
}

Multi-query request

One can query multiple endpoints at once with a multi query

import { request, multi, fields, isNamed } from 'ts-apicalypse';

const { data } = await multi(
  // `sub` must be used inside `multi` to alias the queries
  request<DEMO>().sub("endpoint1", "alias1").pipe(fields(['...'])),
  request<DEMO, 'count'>().sub("endpoint1", "alias2").pipe(fields(['...'])),
  request<DEMO>().sub("endpoint2", "alias3").pipe(fields(['...'])),
).execute('https://...');

// Infered type of `result` is:
type Result = ({
  name: 'alias1';
  result: {...}[]
} | {
  name: 'alias2';
  count: number;
} | {
  name: 'alias3';
  result: {...}[]
})[]

// you can then use `isNamed` type-guard to help you narrow those types
const result = data[0];
if (isNamed(result, 'alias1')) {
  result.result...
} else if (isNamed(result, 'alias2')) {
  result.count...
}