Skip to content

Latest commit

 

History

History
158 lines (111 loc) · 5.24 KB

UPGRADE.md

File metadata and controls

158 lines (111 loc) · 5.24 KB
Raw

Upgrade guide

7.0.0

This version brings TypeScript support as well as many quality-of-life improvements and internal improvements. To see what's new and noteworthy, check the changelog. The PR offers all the change details in depth. Here are the important changes to know when migrating to this version:

Retrieving paginated results

APIs that are paginated have helper submethods that assist with fetching items across all pages. For an API that returns a paginate property, you can use either the iterateAll or collectAll submethods:

  • iterateAll: return an asynchronous iterator of items that are returned from the API. When the last item on a page is iterated, the next page will be fetched. This continues until there are no more pages.

  • collectAll: fetch all pages and collect all the items in order into an array.

Examples:

// iterateAll
for await (const certificate of client.certificates.listCertificates.iterateAll(1010, "bingo.pizza")) {
  console.log(certificate);
}
// collectAll
const certificates: Array<Certificate> = await client.certificates.listCertificates.collectAll(1010, "bingo.pizza");
console.log(certificates.length);

These general methods replace custom helper methods per API, so the following methods are no longer available:

  • Certificates.allCertificates
  • Contacts.allContacts
  • Domains.allDelegationSignerRecords
  • Domains.allDomains
  • Domains.allEmailForwards
  • Services.allAppliedServices
  • Services.allServices
  • Templates.allTemplateRecords
  • Templates.allTemplates
  • Tlds.allTlds
  • Webhooks.allWebhooks
  • Zones.allZoneRecords
  • Zones.allZones

Methods

Method names have been kept the same to make migration easier.

Some parameters may have different types to reflect the true type from the OpenAPI definitions. For example, account IDs are now numbers, as they are defined as integers in the OpenAPI definitions. This may require some minor refactoring, and TypeScript can be used to quickly check usage types are correct. Argument names may have also changed but these don't affect behaviour.

The options parameter on every API method has been renamed to params and now takes a flat object of query parameters. query and filter are no longer special properties, as internally they were simply unpacked into the parent object (overwriting anything existing) and did nothing special.

  • Parameter values can be strings, numbers, booleans, null, or undefined. If they are false, null, or undefined, they will be omitted. If they are true, they will be provided in the query string with no value.

The JSDoc comments for API methods are now autogenerated from OpenAPI definitions; some descriptions of methods and parameters may have changed.

Errors

Request errors are now dedicated classes that inherit from the RequestError base class, instead of being plain objects and strings. This is more standard JS and allows for matching on error types. Errors thrown elsewhere (e.g. HTTP request library) are passed through instead of only providing its error message so that they can be handled as required by the user.

Example:

import { DNSimple, NotFoundError } from "dnsimple";

const dnsimple = new DNSimple();
let domain;
try {
  domain = await dnsimple.domains.getDomain(1010, "bingo.pizza");
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log("Domain not found");
  } else {
    console.error(err);
  }
}

Error type hierarchy:

  • TimeoutError

  • RequestError

    • AuthenticationError

    • NotFoundError

    • MethodNotAllowedError

    • TooManyRequestsError

    • ClientError

    • ServerError

Deprecated removals

Some deprecated classes and methods have been removed:

  • Collaborators.*
  • Registrar.disableAutoRenewal
  • Registrar.enableAutoRenewal

DNSimple class

The main class has been renamed to DNSimple and is a named export:

// Previous versions

const DNSimple = require("dnsimple");
const dnsimple = DNSimple({});
// Version 7

import { DNSimple } from "dnsimple";
// Or use this for CommonJS (e.g. Node.js and JS):
// const { DNSimple } = require("dnsimple");

// The class is now an actual ES6 class, so make sure to call the constructor with the `new` keyword:
const dnsimple = new DNSimple();

Configuration properties on DNSimple can be accessed and assigned to directly, instead of via getter and setter methods:

// Previous versions

const DNSimple = require("dnsimple");
// Provide initial configuration.
const dnsimple = DNSimple({
  accessToken: "secret",
  userAgent: "world",
});
// Changing after instantiation.
dnsimple.setTimeout(3);
dnsimple.setUserAgent("hello");
// Version 7

import { DNSimple } from "dnsimple";
// Provide initial configuration, or omit to use defaults.
const dnsimple = new DNSimple({
  accessToken: "secret",
  userAgent: "world",
});
// Changing after instantiation.
dnsimple.timeout = 3;
dnsimple.userAgent = "hello";

The VERSION and services instance properties have been removed:

  • Use DNSimple.VERSION (static/class property) instead.
  • All services are instantiated and available as properties on instances of DNSimple just as before, so there should be no need to access service classes directly.