npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

dfx-openapi

v0.0.2

Published

dfx-openapi is a type-safe Angular HttpClient that pulls in your OpenAPI schema. It has virtually zero runtime and is fully compatible with Http Interceptors.

Downloads

196

Readme

dfx-openapi

npm version npm downloads per week npm bundle size

dfx-openapi is a type-safe Angular HttpClient that pulls in your OpenAPI schema. It has virtually zero runtime and is fully compatible with Http Interceptors.

The syntax is inspired by openapi-fetch.

import { inject, Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { createOpenAPIHttpClient } from 'dfx-openapi';

import type { paths } from './my-openapi-3-schema';

export function injectAPI() {
  const httpClient = inject(HttpClient);

  return createOpenAPIHttpClient<paths>(httpClient, { baseUrl: 'https://myapi.dev/v1/' });
}

@Injectable()
export class YourService {
  private api = injectAPI();

  // Return type (Oberservable<ItemResponse>) gets inferred
  getItem(itemId: string) {
    return this.api.get('/items/{item_id}', {
      params: {
        path: {
          item_id: '1234',
        },
      },
    });
  }

  // Return type (Oberservable<ItemResponse>) gets inferred
  updateItem(id: string, name: string) {
    return this.api.put('/items', {
      body: {
        // Body is type-safe
        id,
        name,
      },
    });
  }
}

get(), put(), post(), etc. are thin wrappers around the Angular HttpClient.

Notice there are no generics, and no manual typing. Your endpoint’s request and response were inferred automatically. This is a huge improvement in the type safety of your endpoints because every manual assertion could lead to a bug! This eliminates all of the following:

  • ✅ No typos in URLs or params
  • ✅ All parameters, request bodies, and responses are type-checked and 100% match your schema
  • ✅ No manual typing of your API
  • ✅ Eliminates any types that hide bugs
  • ✅ Also eliminates as type overrides that can also hide bugs

Setup

Install this library along with openapi-typescript:

npm i dfx-openapi
npm i -D openapi-typescript

Highly recommended

Enable noUncheckedIndexedAccess in your tsconfig.json (docs)

Next, generate TypeScript types from your OpenAPI schema using openapi-typescript:

npx openapi-typescript ./path/to/api/v1.yaml -o ./src/app/api/v1.d.ts

Basic usage

The best part about using dfx-openapi over oldschool codegen is no documentation needed. dfx-openapi encourages using your existing OpenAPI documentation rather than trying to find what function to import, or what parameters that function wants:

import { inject, Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { createOpenAPIHttpClient } from 'dfx-openapi';

import type { paths } from './my-openapi-3-schema';

export function injectAPI() {
  const httpClient = inject(HttpClient);

  return createOpenAPIHttpClient<paths>(httpClient, { baseUrl: 'https://myapi.dev/v1/' });
}

@Injectable()
export class YourService {
  private api = injectAPI();

  // Return type (Oberservable<ItemResponse>) gets inferred
  getItem(itemId: string) {
    return this.api.get('/items/{item_id}', {
      params: {
        path: {
          item_id: '1234',
        },
      },
    });
  }

  // Return type (Oberservable<ItemResponse>) gets inferred
  updateItem(id: string, name: string) {
    return this.api.put('/items', {
      body: {
        // Body is type-safe
        id,
        name,
      },
    });
  }
}
  1. The HTTP method is pulled directly from createOpenAPIHttpClient()
  2. You pass in your desired path to get(), put(), etc.
  3. TypeScript takes over the rest and returns helpful errors for anything missing or invalid

Pathname

The pathname of get(), put(), post(), etc. must match your schema literally. Note in the example, the URL is /items/{item_id}. This library will quickly replace all path params for you (so they can be typechecked).

TIP

dfx-openapi infers types from the URL. Prefer static string values over dynamic runtime values, e.g.:

  • "/items/{item_id}"
  • [...pathParts].join("/") + "{item_id}"

This library also supports the label and matrix serialization styles as well (docs) automatically.

Request

The get() request shown needed the params object that groups parameters by type (path or query). If a required param is missing, or the wrong type, a type error will be thrown.

The post() and put() request required a body object that provided all necessary requestBody data.

Support

| Platform | Support | | -------------------------- | --------- | | Angular | >=18.0 | | openapi-typescript-helpers | >=0.0.13 |