@datocms/rest-client-utils 5.2.8 → 5.7.0

package/src/__tests__/errors.test.ts

@@ -0,0 +1,141 @@
+import { ApiError, TimeoutError } from '../errors';
+import { CanceledPromiseError } from '../makeCancelablePromise';
+
+function buildApiError() {
+  return new ApiError({
+    request: {
+      url: '/items/bad-id',
+      method: 'GET',
+      headers: {},
+      body: undefined,
+    },
+    response: {
+      status: 422,
+      statusText: 'Unprocessable Entity',
+      headers: {},
+      body: {
+        data: [
+          {
+            id: '1',
+            type: 'api_error' as const,
+            attributes: {
+              code: 'INVALID_FIELD',
+              doc_url: 'https://www.datocms.com/docs',
+              details: { field: 'item_id' },
+            },
+          },
+        ],
+      },
+    },
+  });
+}
+
+function buildTimeoutError() {
+  return new TimeoutError({
+    request: { url: '/items', method: 'GET', headers: {}, body: undefined },
+  });
+}
+
+describe('ApiError', () => {
+  it('keeps a correct prototype chain and name', () => {
+    const error = buildApiError();
+
+    expect(error).toBeInstanceOf(ApiError);
+    expect(error).toBeInstanceOf(Error);
+    expect(error.name).toBe('ApiError');
+    expect(error.constructor.name).toBe('ApiError');
+  });
+
+  it('exposes request, response and parsed errors', () => {
+    const error = buildApiError();
+
+    expect(error.response.status).toBe(422);
+    expect(error.request.url).toBe('/items/bad-id');
+    expect(error.errors).toHaveLength(1);
+    expect(error.findError('INVALID_FIELD')).toBeTruthy();
+  });
+
+  // These packages ship parallel CJS and ESM builds, so a bundler can load two
+  // distinct copies of this module. `instanceof` must still work for an error
+  // produced by the other copy.
+  it('recognizes an instance coming from a duplicate copy of the module', () => {
+    const fromOtherCopy = Object.assign(new Error('API Error!'), {
+      name: 'ApiError',
+      [Symbol.for('@datocms/rest-client-utils:ApiError')]: true,
+    });
+
+    expect(fromOtherCopy).toBeInstanceOf(ApiError);
+  });
+
+  it('does not recognize unrelated values', () => {
+    expect(new Error('nope')).not.toBeInstanceOf(ApiError);
+    expect({}).not.toBeInstanceOf(ApiError);
+    expect(null).not.toBeInstanceOf(ApiError);
+    expect(buildTimeoutError()).not.toBeInstanceOf(ApiError);
+    // merely borrowing the name is not enough
+    expect(
+      Object.assign(new Error('impostor'), { name: 'ApiError' }),
+    ).not.toBeInstanceOf(ApiError);
+  });
+
+  it('keeps subclass checks exact', () => {
+    class SubclassedApiError extends ApiError {}
+
+    const parent = buildApiError();
+    const child = new SubclassedApiError({
+      request: { url: '/items', method: 'GET', headers: {}, body: undefined },
+      response: { status: 500, statusText: 'Error', headers: {}, body: {} },
+    });
+
+    expect(child).toBeInstanceOf(SubclassedApiError);
+    expect(child).toBeInstanceOf(ApiError);
+    expect(parent).not.toBeInstanceOf(SubclassedApiError);
+  });
+});
+
+describe('TimeoutError', () => {
+  it('keeps a correct prototype chain and name', () => {
+    const error = buildTimeoutError();
+
+    expect(error).toBeInstanceOf(TimeoutError);
+    expect(error).toBeInstanceOf(Error);
+    expect(error.name).toBe('TimeoutError');
+  });
+
+  it('recognizes an instance coming from a duplicate copy of the module', () => {
+    const fromOtherCopy = Object.assign(new Error('API Error!'), {
+      name: 'TimeoutError',
+      [Symbol.for('@datocms/rest-client-utils:TimeoutError')]: true,
+    });
+
+    expect(fromOtherCopy).toBeInstanceOf(TimeoutError);
+  });
+
+  it('is not confused with an ApiError', () => {
+    expect(buildApiError()).not.toBeInstanceOf(TimeoutError);
+  });
+});
+
+describe('CanceledPromiseError', () => {
+  it('keeps a correct prototype chain and name', () => {
+    const error = new CanceledPromiseError();
+
+    expect(error).toBeInstanceOf(CanceledPromiseError);
+    expect(error).toBeInstanceOf(Error);
+    expect(error.name).toBe('CanceledPromiseError');
+  });
+
+  it('recognizes an instance coming from a duplicate copy of the module', () => {
+    const fromOtherCopy = Object.assign(new Error('Promise canceled!'), {
+      name: 'CanceledPromiseError',
+      [Symbol.for('@datocms/rest-client-utils:CanceledPromiseError')]: true,
+    });
+
+    expect(fromOtherCopy).toBeInstanceOf(CanceledPromiseError);
+  });
+
+  it('is not confused with other error types', () => {
+    expect(buildApiError()).not.toBeInstanceOf(CanceledPromiseError);
+    expect(new Error('nope')).not.toBeInstanceOf(CanceledPromiseError);
+  });
+});

package/src/errors.ts

@@ -59,6 +59,19 @@ export type ApiErrorResponse = {
   body?: unknown;
 };
 
+/**
+ * Brands stamped on error instances.
+ *
+ * `Symbol.for()` looks up the cross-realm global symbol registry, so every copy
+ * of this module — CJS or ESM, inlined by a bundler or not — resolves these to
+ * the very same symbols. Since these packages ship parallel CJS and ESM builds
+ * with no guarantee that a consumer ends up with a single copy, identity is
+ * carried by these brands rather than by class identity alone, so `instanceof`
+ * keeps working across duplicated copies.
+ */
+const TIMEOUT_ERROR = Symbol.for('@datocms/rest-client-utils:TimeoutError');
+const API_ERROR = Symbol.for('@datocms/rest-client-utils:ApiError');
+
 export type TimeoutErrorInitObject = {
   request: ApiErrorRequest;
   preCallStack?: string;
@@ -68,12 +81,44 @@ export class TimeoutError extends Error {
   request: ApiErrorRequest;
   preCallStack?: string;
 
+  declare readonly [TIMEOUT_ERROR]: true;
+
+  static [Symbol.hasInstance](value: unknown): value is TimeoutError {
+    if (
+      typeof value !== 'object' ||
+      value === null ||
+      !(TIMEOUT_ERROR in value)
+    ) {
+      return false;
+    }
+
+    // `this` is the constructor `instanceof` was invoked on: when it is a
+    // subclass, defer to a real prototype-chain check so subclasses stay exact.
+    // biome-ignore lint/complexity/noThisInStatic: dynamic `this` is required here; hardcoding the class would break subclass checks
+    const invokedOn = this as unknown as { prototype: object };
+
+    if (invokedOn !== TimeoutError) {
+      return Object.prototype.isPrototypeOf.call(invokedOn.prototype, value);
+    }
+
+    return true;
+  }
+
   constructor(initObject: TimeoutErrorInitObject) {
     super('API Error!');
     Object.setPrototypeOf(this, new.target.prototype);
 
+    Object.defineProperty(this, TIMEOUT_ERROR, {
+      value: true,
+      enumerable: false,
+      writable: false,
+      configurable: false,
+    });
+
+    this.name = 'TimeoutError';
+
     if ('captureStackTrace' in Error) {
-      Error.captureStackTrace(this, ApiError);
+      Error.captureStackTrace(this, TimeoutError);
     } else {
       this.stack = new (Error as any)().stack;
     }
@@ -100,10 +145,38 @@ export class ApiError extends Error {
   response: ApiErrorResponse;
   preCallStack?: string;
 
+  declare readonly [API_ERROR]: true;
+
+  static [Symbol.hasInstance](value: unknown): value is ApiError {
+    if (typeof value !== 'object' || value === null || !(API_ERROR in value)) {
+      return false;
+    }
+
+    // `this` is the constructor `instanceof` was invoked on: when it is a
+    // subclass, defer to a real prototype-chain check so subclasses stay exact.
+    // biome-ignore lint/complexity/noThisInStatic: dynamic `this` is required here; hardcoding the class would break subclass checks
+    const invokedOn = this as unknown as { prototype: object };
+
+    if (invokedOn !== ApiError) {
+      return Object.prototype.isPrototypeOf.call(invokedOn.prototype, value);
+    }
+
+    return true;
+  }
+
   constructor(initObject: ApiErrorInitObject) {
     super('API Error!');
     Object.setPrototypeOf(this, new.target.prototype);
 
+    Object.defineProperty(this, API_ERROR, {
+      value: true,
+      enumerable: false,
+      writable: false,
+      configurable: false,
+    });
+
+    this.name = 'ApiError';
+
     if ('captureStackTrace' in Error) {
       Error.captureStackTrace(this, ApiError);
     } else {

package/src/index.ts

@@ -1,10 +1,10 @@
-export * from './deserialize';
-export * from './errors';
-export * from './makeCancelablePromise';
-export * from './pollJobResult';
-export * from './rawPageIterator';
-export * from './request';
-export * from './serialize';
-export * from './toId';
-export * from './types';
-export * from './wait';
+export * from './deserialize.js';
+export * from './errors.js';
+export * from './makeCancelablePromise.js';
+export * from './pollJobResult.js';
+export * from './rawPageIterator.js';
+export * from './request.js';
+export * from './serialize.js';
+export * from './toId.js';
+export * from './types.js';
+export * from './wait.js';

package/src/makeCancelablePromise.ts

@@ -1,7 +1,48 @@
+/**
+ * See the note on the brands in `errors.ts`: identity is carried by a symbol
+ * from the cross-realm global registry so that `instanceof` keeps working even
+ * when a bundler ends up loading more than one copy of this module.
+ */
+const CANCELED_PROMISE_ERROR = Symbol.for(
+  '@datocms/rest-client-utils:CanceledPromiseError',
+);
+
 export class CanceledPromiseError extends Error {
+  declare readonly [CANCELED_PROMISE_ERROR]: true;
+
+  static [Symbol.hasInstance](value: unknown): value is CanceledPromiseError {
+    if (
+      typeof value !== 'object' ||
+      value === null ||
+      !(CANCELED_PROMISE_ERROR in value)
+    ) {
+      return false;
+    }
+
+    // `this` is the constructor `instanceof` was invoked on: when it is a
+    // subclass, defer to a real prototype-chain check so subclasses stay exact.
+    // biome-ignore lint/complexity/noThisInStatic: dynamic `this` is required here; hardcoding the class would break subclass checks
+    const invokedOn = this as unknown as { prototype: object };
+
+    if (invokedOn !== CanceledPromiseError) {
+      return Object.prototype.isPrototypeOf.call(invokedOn.prototype, value);
+    }
+
+    return true;
+  }
+
   constructor() {
     super('Promise canceled!');
     Object.setPrototypeOf(this, new.target.prototype);
+
+    Object.defineProperty(this, CANCELED_PROMISE_ERROR, {
+      value: true,
+      enumerable: false,
+      writable: false,
+      configurable: false,
+    });
+
+    this.name = 'CanceledPromiseError';
   }
 }
 

package/src/pollJobResult.ts

@@ -1,6 +1,6 @@
-import { ApiError } from './errors';
-import type { JobResult } from './internalTypes';
-import { wait } from './wait';
+import { ApiError } from './errors.js';
+import type { JobResult } from './internalTypes.js';
+import { wait } from './wait.js';
 
 export async function pollJobResult(
   fetcher: () => Promise<JobResult>,

package/src/rawPageIterator.ts

@@ -1,5 +1,5 @@
 import { Scheduler } from 'async-scheduler';
-import { deserializeRawItem } from './deserialize';
+import { deserializeRawItem } from './deserialize.js';
 
 export type IteratorOptions = {
   perPage?: number;

package/src/request.ts

@@ -1,18 +1,18 @@
 /// <reference lib="dom" />
 
-import { buildNormalizedParams } from './buildNormalizedParams';
+import { buildNormalizedParams } from './buildNormalizedParams.js';
 import {
   ApiError,
   type ApiErrorInitObject,
   TimeoutError,
   type TimeoutErrorInitObject,
-} from './errors';
-import type { JobResult } from './internalTypes';
+} from './errors.js';
+import type { JobResult } from './internalTypes.js';
 import {
   CanceledPromiseError,
   makeCancelablePromise,
-} from './makeCancelablePromise';
-import { wait } from './wait';
+} from './makeCancelablePromise.js';
+import { wait } from './wait.js';
 
 const isBrowser =
   typeof window !== 'undefined' && typeof window.document !== 'undefined';