@ethlete/query 5.15.0 → 5.16.0

package/src/lib/request/request.util.spec.ts

@@ -0,0 +1,177 @@
+import { invalidBaseRouteError, invalidRouteError, pathParamsMissingInRouteFunctionError } from '../logger';
+import { RouteString } from '../query';
+import { buildQueryString, buildRoute, isRequestError } from './request.util';
+
+describe('isRequestError', () => {
+  it('should be falsy', () => {
+    expect(isRequestError('foo')).toBeFalsy();
+  });
+
+  it('should by truthy', () => {
+    expect(isRequestError({ status: 200, statusText: 'Error', url: '...' })).toBeTruthy();
+  });
+});
+
+describe('buildQueryString', () => {
+  const uriBrackets = encodeURIComponent('[]');
+  const dot = encodeURIComponent('.');
+  const uriBracketsZero = encodeURIComponent('[0]');
+  const brOpen = encodeURIComponent('[');
+  const brClose = encodeURIComponent(']');
+  const uriBracketsOne = encodeURIComponent('[1]');
+  const uriBracketsTwo = encodeURIComponent('[2]');
+
+  it('should work with a single param', () => {
+    expect(buildQueryString({ foo: 123 })).toEqual('foo=123');
+  });
+
+  it('should work with multiple params', () => {
+    expect(buildQueryString({ foo: 123, bar: 'string' })).toEqual('foo=123&bar=string');
+  });
+
+  it('should work with valid but falsy params', () => {
+    expect(
+      buildQueryString({
+        bar: 0,
+        stuff: -0,
+      }),
+    ).toEqual('bar=0&stuff=0');
+  });
+
+  it('should work with arrays', () => {
+    expect(
+      buildQueryString({
+        foo: ['abc', 'def'],
+        bar: true,
+      }),
+    ).toEqual(`foo${uriBrackets}=abc&foo${uriBrackets}=def&bar=true`);
+  });
+
+  it('should filter out invalid values using default config', () => {
+    expect(
+      buildQueryString({
+        foo: ['abc', 'def', null, undefined, NaN],
+        bar: true,
+        baz: Infinity,
+        bi: '   ',
+      }),
+    ).toEqual(`foo${uriBrackets}=abc&foo${uriBrackets}=def&bar=true`);
+  });
+
+  it('should use correct filtered array indexes', () => {
+    expect(
+      buildQueryString(
+        {
+          foo: ['abc', null, 'def', NaN, Infinity, -Infinity, undefined, 'bar'],
+        },
+        {
+          writeArrayIndexes: true,
+        },
+      ),
+    ).toEqual(`foo${uriBracketsZero}=abc&foo${uriBracketsOne}=def&foo${uriBracketsTwo}=bar`);
+  });
+
+  it('should work with array params containing objects in dot notation', () => {
+    expect(
+      buildQueryString(
+        {
+          filters: [{ name: 'category', values: ['Stuff', 'Other'] }],
+        },
+        {
+          objectNotation: 'dot',
+          writeArrayIndexes: true,
+        },
+      ),
+    ).toEqual(
+      `filters${uriBracketsZero}${dot}name=category&filters${uriBracketsZero}${dot}values${uriBracketsZero}=Stuff&filters${uriBracketsZero}${dot}values${uriBracketsOne}=Other`,
+    );
+  });
+
+  it('should work with array params containing objects in bracket notation', () => {
+    expect(
+      buildQueryString(
+        {
+          filters: [{ name: 'category', values: ['Stuff', 'Other'] }],
+        },
+        {
+          objectNotation: 'bracket',
+          writeArrayIndexes: true,
+        },
+      ),
+    ).toEqual(
+      `filters${uriBracketsZero}${brOpen}name${brClose}=category&filters${uriBracketsZero}${brOpen}values${brClose}${uriBracketsZero}=Stuff&filters${uriBracketsZero}${brOpen}values${brClose}${uriBracketsOne}=Other`,
+    );
+  });
+});
+
+describe('buildRoute', () => {
+  it('should work without params', () => {
+    expect(
+      buildRoute({
+        base: 'https://example.com',
+        route: '/foo',
+      }),
+    ).toBe('https://example.com/foo');
+  });
+
+  it('should work with path params', () => {
+    expect(
+      buildRoute({
+        base: 'https://example.com',
+        route: (args) => '/foo/' + args['id'],
+        pathParams: { id: 1 },
+      }),
+    ).toBe('https://example.com/foo/1');
+  });
+
+  it('should work with query params', () => {
+    expect(
+      buildRoute({
+        base: 'https://example.com',
+        route: '/foo',
+        queryParams: { id: 1 },
+      }),
+    ).toBe('https://example.com/foo?id=1');
+  });
+
+  it('should work with query and path params', () => {
+    expect(
+      buildRoute({
+        base: 'https://example.com',
+        route: (args) => '/foo/' + args['id'],
+        pathParams: { id: 1 },
+        queryParams: { filter: true },
+      }),
+    ).toBe('https://example.com/foo/1?filter=true');
+  });
+
+  it('should fail with a route function without provided path params', () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const fn = (args: any) => '/foo/' + args.id;
+
+    expect(() => {
+      buildRoute({
+        base: 'https://example.com',
+        route: (args) => '/foo/' + args['id'],
+      });
+    }).toThrow(pathParamsMissingInRouteFunctionError(fn({})));
+  });
+
+  it('should fail with  base route ending with a slash', () => {
+    expect(() => {
+      buildRoute({
+        base: 'https://example.com/',
+        route: '/foo',
+      });
+    }).toThrow(invalidBaseRouteError('https://example.com/'));
+  });
+
+  it('should fail with route missing a slash at the start', () => {
+    expect(() => {
+      buildRoute({
+        base: 'https://example.com',
+        route: 'foo' as RouteString,
+      });
+    }).toThrow(invalidRouteError('foo'));
+  });
+});

package/src/lib/request/request.util.ts

@@ -0,0 +1,399 @@
+import { invalidBaseRouteError, invalidRouteError, pathParamsMissingInRouteFunctionError } from '../logger';
+import { AnyRoute } from '../query';
+import { isSymfonyPagerfantaOutOfRangeError } from '../symfony';
+import {
+  BuildQueryStringConfig,
+  Method,
+  PathParams,
+  QueryParams,
+  RequestError,
+  RequestHeaders,
+  RequestRetryFn,
+} from './request.types';
+
+export const isNaN = (value: unknown): boolean => typeof value === 'number' && Number.isNaN(value);
+export const isEmptyString = (value: unknown): boolean => typeof value === 'string' && value.trim() === '';
+
+export const isRequestError = <T = unknown>(error: unknown): error is RequestError<T> =>
+  error instanceof Object && 'status' in error && 'statusText' in error && 'url' in error;
+
+export const buildRoute = (options: {
+  base: string;
+  route: AnyRoute | null | undefined;
+  pathParams?: PathParams;
+  queryParams?: QueryParams;
+  queryParamConfig?: BuildQueryStringConfig;
+}) => {
+  if (options.base.endsWith('/')) {
+    throw invalidBaseRouteError(options.base);
+  }
+
+  let route: string | null = null;
+
+  if (typeof options.route === 'function') {
+    if (!options.pathParams) {
+      throw pathParamsMissingInRouteFunctionError(options.route({}));
+    }
+
+    route = options.route(options.pathParams);
+  } else {
+    route = options.route ?? null;
+  }
+
+  if (route && !route.startsWith('/')) {
+    throw invalidRouteError(route);
+  }
+
+  if (options.queryParams) {
+    const queryString = buildQueryString(options.queryParams, options.queryParamConfig);
+
+    if (queryString) {
+      route = route ? `${route}?${queryString}` : `/?${queryString}`;
+    }
+  }
+
+  return `${options.base}${route ?? ''}`;
+};
+
+export const buildQueryString = (params: QueryParams, config?: BuildQueryStringConfig): string | null => {
+  const objectNotation = config?.objectNotation ?? 'bracket';
+  const writeArrayIndexes = config?.writeArrayIndexes ?? false;
+  const ignoredValues = config?.ignoredValues ?? [undefined, null, Infinity, -Infinity];
+  const ignoredValuesFns = config?.ignoredValuesFns ?? [isNaN, isEmptyString];
+
+  const queryParams: string[] = [];
+
+  function processValue(key: string, value: unknown) {
+    if (Array.isArray(value)) {
+      let currentFilteredIndex = 0;
+      for (const arrayValue of value) {
+        const nestedKey = writeArrayIndexes ? `${key}[${currentFilteredIndex}]` : `${key}[]`;
+
+        const didAddValue = processValue(nestedKey, arrayValue);
+
+        if (didAddValue) {
+          currentFilteredIndex++;
+        }
+      }
+
+      return null;
+    } else if (typeof value === 'object' && value !== null) {
+      for (const [objKey, val] of Object.entries(value)) {
+        const nestedKey = objectNotation === 'dot' ? `${key}.${objKey}` : `${key}[${objKey}]`;
+        processValue(nestedKey, val);
+      }
+
+      return null;
+    } else {
+      if (ignoredValues.includes(value)) {
+        return false;
+      }
+
+      if (ignoredValuesFns.some((fn) => fn(value))) {
+        return false;
+      }
+
+      const encodedKey = encodeURIComponent(key);
+      const encodedValue = encodeURIComponent(value as string);
+
+      queryParams.push(`${encodedKey}=${encodedValue}`);
+
+      return true;
+    }
+  }
+
+  for (const [key, val] of Object.entries(params)) {
+    processValue(key, val);
+  }
+
+  return queryParams.length ? queryParams.join('&') : null;
+};
+
+export const extractExpiresInSeconds = (headers: RequestHeaders) => {
+  const cacheControl = headers['cache-control'];
+  const age = headers['age'];
+  const expires = headers['expires'];
+
+  // In seconds
+  let expiresIn: number | null = null;
+  let maxAge: number | null = null;
+
+  if (cacheControl?.includes('no-cache')) {
+    return null;
+  }
+
+  if (cacheControl?.includes('max-age')) {
+    const m = cacheControl.split('max-age=')[1];
+
+    if (m) {
+      maxAge = parseInt(m);
+    }
+  } else if (cacheControl?.includes('s-maxage')) {
+    const m = cacheControl.split('s-maxage=')[1];
+
+    if (m) {
+      maxAge = parseInt(m);
+    }
+  }
+
+  if (maxAge && age) {
+    const ageSeconds = parseInt(age);
+
+    expiresIn = maxAge - ageSeconds;
+  } else if (maxAge) {
+    expiresIn = maxAge / 2; // We assume the response is half way to its expiration
+  } else if (expires) {
+    // Used by some apis to tell the response will never expire
+    // In this case we let the response expire after 1 hour
+    if (expires === '-1') {
+      expiresIn = 3600;
+    } else {
+      const expiresDate = new Date(expires);
+
+      // check if the date is valid
+      if (expiresDate.toString() !== 'Invalid Date') {
+        expiresIn = Math.floor((expiresDate.getTime() - Date.now()) / 1000);
+      }
+    }
+  }
+
+  return expiresIn;
+};
+
+export const buildTimestampFromSeconds = (seconds: number | null) => {
+  if (seconds === null) {
+    return null;
+  }
+
+  return new Date(Date.now() + seconds * 1000).getTime();
+};
+
+export const serializeBody = (body: unknown): ArrayBuffer | URLSearchParams | Blob | FormData | string | null => {
+  if (body === null || body === undefined) {
+    return null;
+  }
+
+  if (
+    body instanceof ArrayBuffer ||
+    body instanceof Blob ||
+    body instanceof FormData ||
+    body instanceof URLSearchParams ||
+    typeof body === 'string'
+  ) {
+    return body as ArrayBuffer | URLSearchParams | Blob | FormData | string;
+  }
+
+  if (typeof body === 'object' || typeof body === 'boolean' || Array.isArray(body)) {
+    return JSON.stringify(body);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (body as any).toString();
+};
+
+export const transformMethod = (config: { method: Method; transferVia?: 'GET' | 'POST' }) => {
+  if (config.method === 'GQL_QUERY' || config.method === 'GQL_MUTATE') {
+    if (!config.transferVia) {
+      return 'POST';
+    }
+
+    return config.transferVia;
+  }
+
+  return config.method;
+};
+
+export const detectContentTypeHeader = (body: unknown) => {
+  // An empty body has no content type.
+  if (body === null) {
+    return null;
+  }
+  // FormData bodies rely on the browser's content type assignment.
+  if (body instanceof FormData) {
+    return null;
+  }
+  // Blobs usually have their own content type. If it doesn't, then
+  // no type can be inferred.
+  if (body instanceof Blob) {
+    return body.type || null;
+  }
+  // Array buffers have unknown contents and thus no type can be inferred.
+  if (body instanceof ArrayBuffer) {
+    return null;
+  }
+  // Technically, strings could be a form of JSON data, but it's safe enough
+  // to assume they're plain strings.
+  if (typeof body === 'string') {
+    return 'text/plain';
+  }
+
+  // Arrays, objects, boolean and numbers will be encoded as JSON.
+  if (typeof body === 'object' || typeof body === 'number' || typeof body === 'boolean') {
+    return 'application/json';
+  }
+  // No type could be inferred.
+  return null;
+};
+
+export const hasHeader = (headers: RequestHeaders, header: string) => {
+  return Object.keys(headers).some((key) => key.toLowerCase() === header.toLowerCase());
+};
+
+export const forEachHeader = (headers: RequestHeaders, callback: (value: string, key: string) => void) => {
+  Object.entries(headers).forEach(([key, value]) => {
+    callback(key, value);
+  });
+};
+
+export const parseAllXhrResponseHeaders = (xhr: XMLHttpRequest) => {
+  const headers = xhr.getAllResponseHeaders();
+  const parsedHeaders: RequestHeaders = {};
+
+  for (const line of headers.split('\n')) {
+    const index = line.indexOf(':');
+    if (index > 0) {
+      const name = line.slice(0, index);
+      const key = name.toLowerCase();
+      const value = line.slice(index + 1).trim();
+
+      parsedHeaders[key] = value;
+    }
+  }
+
+  return parsedHeaders;
+};
+
+export const getResponseUrl = (xhr: XMLHttpRequest): string | null => {
+  if ('responseURL' in xhr && xhr.responseURL) {
+    return xhr.responseURL;
+  }
+  if (/^X-Request-URL:/m.test(xhr.getAllResponseHeaders())) {
+    return xhr.getResponseHeader('X-Request-URL');
+  }
+  return null;
+};
+
+export const shouldRetryRequest: RequestRetryFn = (config) => {
+  const defaultRetryDelay = 1000 + 1000 * config.currentRetryCount;
+
+  if (config.currentRetryCount > 3) {
+    return { retry: false };
+  }
+
+  if (!isRequestError(config.error)) {
+    return { retry: false };
+  }
+
+  const { status, detail } = config.error;
+
+  // Retry on 5xx errors
+  if (status >= 500) {
+    // Don't retry if a requested page is out of range
+    if (isSymfonyPagerfantaOutOfRangeError(detail)) {
+      return { retry: false };
+    }
+
+    return { retry: true, delay: defaultRetryDelay };
+  }
+
+  // Retry on 408 or 425 errors
+  if (status === HttpStatusCode.RequestTimeout || status === HttpStatusCode.TooEarly) {
+    return { retry: true, delay: defaultRetryDelay };
+  }
+
+  // Retry on 429 errors
+  if (status === HttpStatusCode.TooManyRequests) {
+    const retryAfter =
+      config.headers['retry-after'] ||
+      config.headers['Retry-After'] ||
+      config.headers['x-retry-after'] ||
+      config.headers['X-Retry-After'];
+
+    if (retryAfter) {
+      const delay = parseInt(retryAfter) * 1000;
+      return { retry: true, delay: Number.isNaN(delay) ? defaultRetryDelay : delay };
+    }
+
+    return { retry: true, delay: defaultRetryDelay };
+  }
+
+  // Code 0 usually means the internet connection is down. We retry in this case.
+  // It could also be a CORS issue but that should not be the case in production.
+  if (status === 0) {
+    return { retry: true, delay: defaultRetryDelay };
+  }
+
+  return { retry: false };
+};
+
+export const enum HttpStatusCode {
+  Unknown = 0,
+
+  Continue = 100,
+  SwitchingProtocols = 101,
+  Processing = 102,
+  EarlyHints = 103,
+
+  Ok = 200,
+  Created = 201,
+  Accepted = 202,
+  NonAuthoritativeInformation = 203,
+  NoContent = 204,
+  ResetContent = 205,
+  PartialContent = 206,
+  MultiStatus = 207,
+  AlreadyReported = 208,
+  ImUsed = 226,
+
+  MultipleChoices = 300,
+  MovedPermanently = 301,
+  Found = 302,
+  SeeOther = 303,
+  NotModified = 304,
+  UseProxy = 305,
+  Unused = 306,
+  TemporaryRedirect = 307,
+  PermanentRedirect = 308,
+
+  BadRequest = 400,
+  Unauthorized = 401,
+  PaymentRequired = 402,
+  Forbidden = 403,
+  NotFound = 404,
+  MethodNotAllowed = 405,
+  NotAcceptable = 406,
+  ProxyAuthenticationRequired = 407,
+  RequestTimeout = 408,
+  Conflict = 409,
+  Gone = 410,
+  LengthRequired = 411,
+  PreconditionFailed = 412,
+  PayloadTooLarge = 413,
+  UriTooLong = 414,
+  UnsupportedMediaType = 415,
+  RangeNotSatisfiable = 416,
+  ExpectationFailed = 417,
+  ImATeapot = 418,
+  MisdirectedRequest = 421,
+  UnprocessableEntity = 422,
+  Locked = 423,
+  FailedDependency = 424,
+  TooEarly = 425,
+  UpgradeRequired = 426,
+  PreconditionRequired = 428,
+  TooManyRequests = 429,
+  RequestHeaderFieldsTooLarge = 431,
+  UnavailableForLegalReasons = 451,
+
+  InternalServerError = 500,
+  NotImplemented = 501,
+  BadGateway = 502,
+  ServiceUnavailable = 503,
+  GatewayTimeout = 504,
+  HttpVersionNotSupported = 505,
+  VariantAlsoNegotiates = 506,
+  InsufficientStorage = 507,
+  LoopDetected = 508,
+  NotExtended = 510,
+  NetworkAuthenticationRequired = 511,
+}

package/src/lib/stories/angular-example-page.mdx

@@ -0,0 +1,85 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="HttpClient/Angular Usage Example" />
+
+# Example
+
+In Angular there are some helper tools that make it very easy to use the queries in Angular.
+
+```ts
+// product.queries.ts
+
+export interface GetProductsArgs {
+  queryParams: {
+    search?: string;
+  };
+}
+
+export interface ProductView {
+  id: string;
+  name: string;
+}
+
+export const getProducts = client.get({
+  route: '/products',
+  secure: true,
+  types: {
+    args: def<GetProductsArgs>(),
+    response: def<ProductView[]>(),
+  },
+});
+```
+
+```ts
+// product-list.component.ts
+import { getProducts } from './product.queries';
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, effect } from '@angular/core';
+import { ReactiveFormsModule, FormControl } from '@angular/forms';
+import { QueryDirective } from '@ethlete/query';
+import { controlValueSignal } from '@ethlete/core';
+
+@Component({
+  selector: 'app-product-list',
+  standalone: true,
+  imports: [QueryDirective, ReactiveFormsModule],
+  templateUrl: './product-list.component.html',
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ProductListComponent {
+  getProductsQuery = getProducts.createSignal();
+  search = new FormControl<null | string>(null);
+  searchChanges = controlValueSignal(this.search);
+
+  constructor() {
+    effect(() => {
+      const search = this.searchChanges();
+      this.getProductsQuery.set(
+        getProductsQuery
+          .prepare({
+            queryParams: {
+              search,
+            },
+          })
+          .execute(),
+      );
+    });
+  }
+}
+```
+
+```html
+<!-- product-list.component.html -->
+
+<input [formControl]="search" />
+
+<div *etQuery="getProductsQuery() as response; loading as loading; error as error">
+  @for (product of response; track product.id) {
+  <div>{{ product.name }}</div>
+  } @if(loading) {
+  <p>Loading Template</p>
+  } @if(error && !loading) {
+  <p>Error Template</p>
+  }
+</div>
+```

package/src/lib/stories/authentication-page.mdx

@@ -0,0 +1,35 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="HttpClient/Authentication" />
+
+# Authentication
+
+The client offers you the option of using authentication. There are various AuthProviders that you can easily configure and transfer to the client.
+
+## BearerAuthProvider
+
+The BearerAuthProvider is an AuthProvider that works with a Bearer Token. Once you have received the access token after logging in, you can easily pass it to the BearerAuthProvider. The BearerAuthProvider then refreshes the token once it has expired.
+
+```ts
+import { QueryClient } from '@ethlete/query';
+
+export const client = new QueryClient({
+  baseRoute: 'https://api.test.com',
+});
+
+const tokenFromLogin = 'token';
+
+const bearerAuthProvider = new BearerAuthProvider({
+  token: tokenFromLogin,
+  refreshConfig: {
+    queryCreator: postRefreshToken,
+    token: refreshToken,
+    cookieName: 'auth-token',
+    cookieEnabled: true,
+    responseAdapter: (x) => ({ token: x.token, refreshToken: x.refresh_token }),
+    requestArgsAdapter: (token) => ({ body: { refresh_token: token.refreshToken } }),
+  },
+});
+
+client.setAuthProvider(bearerAuthProvider);
+```

package/src/lib/stories/changelog-page.mdx

@@ -0,0 +1,9 @@
+import { Markdown, Meta } from '@storybook/blocks';
+
+import Readme from '../../../CHANGELOG.md?raw';
+
+<Meta title="Changelog/Query" />
+
+# Changelog
+
+<Markdown>{Readme}</Markdown>