3

Screenshot / Code Snippet

animated example

Usage example:

import {
    CommonWrapperObject,
    Errors,
    Filters,
    Tag,
} from "@userscripters/stackexchange-api-types";

export const getTagsAPI = async (search: string): Promise<Tag[]> => {
    const filter: Filters.BuiltIn = "default";

    const uri = new URL(`https://api.stackexchange.com/2.3/tags`);
    uri.search = new URLSearchParams({
        site: location.hostname,
        inname: search.toLowerCase(),
        filter,
    }).toString();

    const res = await fetch(uri.toString());
    if (!res.ok) return [];

    const body = await res.json();

    const { items, error_name } = body as CommonWrapperObject<Tag>;

    const errorMap: Map<Errors.Name, string> = new Map([
        ["bad_parameter", "Invalid parameter"],
        ["access_denied", "The API refused access"],
    ]);

    console.log(errorMap.get(error_name));

    return items;
};

About

Stack Exchange API types is a type declaration package adding type definitions for objects exposed by Stack Exchange API for both client- and server-side consumption.

The package is automatically generated, so all currently available types should be present in the definitions - do let us know if we missed anything!

License

The package is licensed under the GPL-3.0-or-later license.

Download

The package is published as both an NPM package and a GitHub package. Can be installed via a package manager like NPM as usual:

npm install --save-dev @userscripters/stackexchange-api-types

If you opt to install it from the GitHub registry, please note that it only supports scoped packages, you will need a simple .npmrc file at your project root:

@userscripters:registry=https://npm.pkg.github.com

You will also need to be logged in to GitHub. An easy way to do so is to have a global .npmrc with your PAT (personal access token) set as an access token:

//npm.pkg.github.com/:_authToken=<your token here>

Platform

The type declarations are intended to be used with TypeScript/JavaScript projects targeting either browsers or server-side environments like Node.js.

Changelog

Version Changes
0.3.0 Deduplicated generated interfaces & exported types globally as StackExchangeAPI namespace
1.0.0 Fixed type date from the API being incorrectly interpreted as Date (it is a number)
2.0.0 "may be absent" fields are now considered optional interface members. This makes the types more accurate but might be a breaking change for your codebase
3.1.1 Common Wrapper Object that the API sends the responses wrapped into is added to the list of generated types. The interface accepts a generic type parameter for the items array values
3.2.4 Built-in filters (e.g. default or total) string union grouped under Filters namespace
3.3.0 API errors as Name and Code unions grouped under Errors namespace
3.4.0 API error types are propagated to the common wrapper object fields error_name and error_id

Contact

Author: Oleg Valter
Organization: UserScripters

Please, submit bug reports on the source repository.
Before adding a new one, please check if it hasn't been raised before.

You can also drop by to chat, we are a friendly bunch.

Code

Source code is written TypeScript (d.ts declaration files and type generator in proper TypeScript).

The project is using tsd (see repo) for unit-testing types.

Contributions are welcome, you can always submit a PR here.

3
  • Why is the Answer interface listed twice in the types.d.ts file?
    – rene
    Sep 19 '21 at 13:26
  • 1
    @rene v0.2.0, that's why :) I was a bit too busy with setting up AST parsing -> pretty-printing, so I forgot that some of the definitions can duplicate the way SE sets things up - and since TS simply does declaration merging on interfaces, no errors popped up - should work fine as is, but I'll add a filter for the duplicate interfaces in the next version Sep 19 '21 at 13:32
  • @rene done, version 0.3.0 features interface deduplication :) Since the compiler API is incredibly poorly documented I am not sure if there is a way to dedupe them properly, but should be enough unless SE suddenly decides to use partial declarations. On an off-note, the types are now also exported as a global namespace to make them viable in non-module userscripts too. Sep 22 '21 at 11:00

You must log in to answer this question.

Browse other questions tagged .