@data-client/rest 0.1.0

package/src/RestEndpoint.js

@@ -0,0 +1,262 @@
+import { Endpoint } from '@data-client/endpoint';
+import { pathToRegexp } from 'path-to-regexp';
+
+import extractCollection from './extractCollection.js';
+import mapCollection from './mapCollection.js';
+import NetworkError from './NetworkError.js';
+import { paginatedMerge, paginatedFilter } from './paginatedCollections.js';
+import paginationUpdate from './paginationUpdate.js';
+import paramsToString from './paramsToString.js';
+import { getUrlBase, getUrlTokens, isPojo } from './RestHelpers.js';
+
+/** Simplifies endpoint definitions that follow REST patterns
+ *
+ * @see https://resthooks.io/rest/api/RestEndpoint
+ */
+export default class RestEndpoint extends Endpoint {
+  #hasBody;
+  constructor(options) {
+    super(
+      options.fetch ??
+        function (...args) {
+          const urlParams =
+            this.#hasBody && args.length < 2 ? {} : args[0] || {};
+          const body = this.#hasBody ? args[args.length - 1] : undefined;
+          return this.fetchResponse(
+            this.url(urlParams),
+            this.getRequestInit(body),
+          )
+            .then(response => this.parseResponse(response))
+            .then(res => this.process(res, ...args));
+        },
+      options,
+    );
+    // we want to use the prototype chain here
+    if (
+      !('sideEffect' in this) ||
+      ('method' in options && !('sideEffect' in options))
+    ) {
+      this.sideEffect =
+        options.method === 'GET' || options.method === undefined
+          ? undefined
+          : true;
+    }
+    if (this.method === undefined) {
+      this.method = this.sideEffect ? 'POST' : 'GET';
+    }
+    if (this.urlPrefix === undefined) {
+      this.urlPrefix = '';
+    }
+    this.#hasBody =
+      (!('body' in this) || this.body !== undefined) &&
+      !['GET', 'DELETE'].includes(this.method);
+
+    Object.defineProperty(this, 'name', {
+      get() {
+        // using 'in' to ensure inheritance lookup
+        if ('__name' in this) return this.__name;
+        return this.urlPrefix + this.path;
+      },
+    });
+  }
+
+  key(...args) {
+    return `${this.method} ${this.url(
+      this.#hasBody && args.length < 2 ? {} : args[0] || {},
+    )}`;
+  }
+
+  /** Get the url */
+  url(urlParams = {}) {
+    const urlBase = getUrlBase(this.path)(urlParams);
+    const tokens = getUrlTokens(this.path);
+    const searchParams = {};
+    Object.keys(urlParams).forEach(k => {
+      if (!tokens.has(k)) {
+        searchParams[k] = urlParams[k];
+      }
+    });
+    if (Object.keys(searchParams).length) {
+      return `${this.urlPrefix}${urlBase}?${paramsToString(searchParams)}`;
+    }
+    return `${this.urlPrefix}${urlBase}`;
+  }
+
+  getHeaders(headers) {
+    return headers;
+  }
+
+  /** Init options for fetch - run at fetch */
+  getRequestInit(body) {
+    const bodyIsPojo = isPojo(body);
+    if (bodyIsPojo) {
+      body = JSON.stringify(body);
+    }
+    const init = {
+      ...this.requestInit,
+      method: this.method,
+      signal: this.signal,
+      body,
+    };
+    if (!body || bodyIsPojo) {
+      init.headers = {
+        // default to application/json but allow user explicit overrides
+        'Content-Type': 'application/json',
+        ...init.headers,
+      };
+    }
+    init.headers = this.getHeaders(init.headers);
+    return init;
+  }
+
+  /** Perform network request and resolve with HTTP Response */
+  fetchResponse(input, init) {
+    return fetch(input, init)
+      .then(response => {
+        if (!response.ok) {
+          throw new NetworkError(response);
+        }
+        return response;
+      })
+      .catch(error => {
+        // ensure CORS, network down, and parse errors are still caught by NetworkErrorBoundary
+        if (error instanceof TypeError) {
+          error.status = 500;
+        }
+        throw error;
+      });
+  }
+
+  parseResponse(response) {
+    // this should not have any content to read
+    if (response.status === 204) return Promise.resolve(null);
+    if (!response.headers.get('content-type')?.includes('json')) {
+      return response.text().then(text => {
+        // string or 'not set' schema, are valid
+        // when overriding process they might handle other cases, so we don't want to block on our logic
+        if (
+          ['string', 'undefined'].includes(typeof this.schema) ||
+          this.schema === null ||
+          this.process !== RestEndpoint.prototype.process
+        )
+          return text;
+
+        const error = new NetworkError(response);
+        error.status = 404;
+        error.message = `Unexpected text response for schema ${this.schema}`;
+        // custom dev-only messages for more detailed cause
+        /* istanbul ignore else */
+        if (process.env.NODE_ENV !== 'production') {
+          if (
+            !(
+              response.headers.get('content-type')?.includes('html') ||
+              text.startsWith('<!doctype html>')
+            )
+          ) {
+            if (tryParse(text) !== undefined) {
+              error.message = `"content-type" header does not include "json", but JSON response found.
+See https://www.rfc-editor.org/rfc/rfc4627 for information on JSON responses
+
+Using parsed JSON.
+If text content was expected see https://resthooks.io/rest/api/RestEndpoint#parseResponse`;
+            }
+          } else {
+            error.message = `Unexpected html response for schema ${this.schema}
+This likely means no API endpoint was configured for this request, resulting in an HTML fallback.
+
+Response (first 300 characters): ${text.substring(0, 300)}`;
+          }
+        }
+        throw error;
+      });
+    }
+    return response.json().catch(error => {
+      error.status = 400;
+      throw error;
+    });
+  }
+
+  process(value) {
+    return value;
+  }
+
+  errorPolicy(error) {
+    return error.status >= 500 ? 'soft' : undefined;
+  }
+
+  get pathRegex() {
+    return pathToRegexp(this.path);
+  }
+
+  testKey(key) {
+    const prefix = this.method + ' ' + this.urlPrefix;
+    if (!key.startsWith(prefix)) return false;
+    let lastQuestion = key.lastIndexOf('?');
+    if (lastQuestion === -1) lastQuestion = undefined;
+    return this.pathRegex.test(key.substring(prefix.length, lastQuestion));
+  }
+
+  extend(options) {
+    // make a constructor/prototype based off this
+    // extend from it and init with options sent
+    class E extends this.constructor {}
+
+    Object.assign(E.prototype, this);
+    const instance = new E(
+      //  fetch get overridden by function prototype, so we must set it explicitly every time
+      { fetch: this.fetch, ...options },
+    );
+
+    return instance;
+  }
+
+  paginated(removeCursor) {
+    if (typeof removeCursor === 'string') {
+      const fieldName = removeCursor;
+      removeCursor = ({ ...params }) => {
+        delete params[fieldName];
+        return [params];
+      };
+    }
+    let found = false;
+    const createPaginatedSchema = collection => {
+      found = true;
+      return collection.addWith(paginatedMerge, paginatedFilter(removeCursor));
+    };
+    const newSchema = mapCollection(this.schema, createPaginatedSchema);
+    if (found) {
+      return this.extend({ schema: newSchema });
+    }
+
+    return this.extend({ update: paginationUpdate(this, removeCursor) });
+  }
+
+  get push() {
+    return this.extend({
+      method: 'POST',
+      schema: extractCollection(this.schema, s => s.push),
+    });
+  }
+
+  get unshift() {
+    return this.extend({
+      method: 'POST',
+      schema: extractCollection(this.schema, s => s.unshift),
+    });
+  }
+
+  get assign() {
+    return this.extend({
+      method: 'POST',
+      schema: extractCollection(this.schema, s => s.assign),
+    });
+  }
+}
+
+const tryParse = input => {
+  try {
+    return JSON.parse(input);
+  } catch (e) {
+    return undefined;
+  }
+};

package/src/RestEndpointTypeHelp.ts

@@ -0,0 +1,20 @@
+import type {
+  FetchFunction,
+  ResolveType,
+  Normalize,
+} from '@data-client/endpoint';
+
+export type EndpointUpdateFunction<
+  Source extends FetchFunction,
+  Schema,
+  Updaters extends Record<string, any> = Record<string, any>,
+> = (
+  source: ResultEntry<Source & { schema: Schema }>,
+  ...args: Parameters<Source>
+) => {
+  [K in keyof Updaters]: (result: Updaters[K]) => Updaters[K];
+};
+export type ResultEntry<E extends FetchFunction & { schema: any }> =
+  E['schema'] extends undefined | null
+    ? ResolveType<E>
+    : Normalize<E['schema']>;

package/src/RestHelpers.ts

@@ -0,0 +1,48 @@
+import { compile, PathFunction, parse } from 'path-to-regexp';
+
+import { ShortenPath } from './pathTypes.js';
+
+const urlBaseCache: Record<string, PathFunction<object>> = Object.create(null);
+export function getUrlBase(path: string): PathFunction {
+  if (!(path in urlBaseCache)) {
+    urlBaseCache[path] = compile(path, {
+      encode: encodeURIComponent,
+      validate: false,
+    });
+  }
+  return urlBaseCache[path];
+}
+
+const urlTokensCache: Record<string, Set<string>> = Object.create(null);
+export function getUrlTokens(path: string): Set<string> {
+  if (!(path in urlTokensCache)) {
+    urlTokensCache[path] = new Set(
+      parse(path).map(t => (typeof t === 'string' ? t : `${t['name']}`)),
+    );
+  }
+  return urlTokensCache[path];
+}
+
+const proto = Object.prototype;
+const gpo = Object.getPrototypeOf;
+
+export function isPojo(obj: unknown): obj is Record<string, any> {
+  if (obj === null || typeof obj !== 'object') {
+    return false;
+  }
+  return gpo(obj) === proto;
+}
+
+export function shortenPath<S extends string>(path: S): ShortenPath<S> {
+  // this is for when not specifying a specific item like create/list
+  let shortUrlRoot: ShortenPath<S> = path.substring(
+    0,
+    path.lastIndexOf(':'),
+  ) as any;
+  if (shortUrlRoot[shortUrlRoot.length - 1] === '/')
+    shortUrlRoot = shortUrlRoot.substring(
+      0,
+      shortUrlRoot.length - 1,
+    ) as ShortenPath<S>;
+  return shortUrlRoot;
+}

package/src/__tests__/Resource.test.ts

@@ -0,0 +1,317 @@
+import { Entity, Schema } from '@data-client/endpoint';
+import { useController } from '@data-client/react';
+import { useSuspense } from '@data-client/react';
+import { CacheProvider } from '@data-client/react';
+import { act } from '@testing-library/react-hooks';
+import nock from 'nock';
+
+import { makeRenderRestHook } from '../../../test';
+import createResource from '../createResource';
+import RestEndpoint from '../RestEndpoint';
+import {
+  payload,
+  createPayload,
+  users,
+  nested,
+  moreNested,
+  paginatedFirstPage,
+  paginatedSecondPage,
+} from '../test-fixtures';
+
+export class User extends Entity {
+  readonly id: number | undefined = undefined;
+  readonly username: string = '';
+  readonly email: string = '';
+  readonly isAdmin: boolean = false;
+
+  pk() {
+    return this.id?.toString();
+  }
+}
+export const UserResource = createResource({
+  path: 'http\\://test.com/user/:id',
+  schema: User,
+});
+export class PaginatedArticle extends Entity {
+  readonly id: number | undefined = undefined;
+  readonly title: string = '';
+  readonly content: string = '';
+  readonly author: number | null = null;
+  readonly tags: string[] = [];
+
+  pk() {
+    return this.id?.toString();
+  }
+
+  static schema = {
+    author: User,
+  };
+}
+function createPaginatableResource<U extends string, S extends Schema>({
+  path,
+  schema,
+  Endpoint = RestEndpoint,
+}: {
+  readonly path: U;
+  readonly schema: S;
+  readonly Endpoint?: typeof RestEndpoint;
+}) {
+  const baseResource = createResource({ path, schema, Endpoint });
+  const getList = baseResource.getList.extend({
+    path: 'http\\://test.com/article-paginated',
+    schema: {
+      nextPage: '',
+      data: { results: [PaginatedArticle] },
+    },
+  });
+  const getNextPage = getList.paginated((v: { cursor: string | number }) => []);
+  return {
+    ...baseResource,
+    getList,
+    getNextPage,
+  };
+}
+const PaginatedArticleResource = createPaginatableResource({
+  path: 'http\\://test.com/article-paginated/:id',
+  schema: PaginatedArticle,
+});
+
+export class UrlArticle extends PaginatedArticle {
+  readonly url: string = 'happy.com';
+}
+
+describe('createResource()', () => {
+  const renderRestHook: ReturnType<typeof makeRenderRestHook> =
+    makeRenderRestHook(CacheProvider);
+  let mynock: nock.Scope;
+
+  beforeEach(() => {
+    nock(/.*/)
+      .persist()
+      .defaultReplyHeaders({
+        'Access-Control-Allow-Origin': '*',
+        'Content-Type': 'application/json',
+      })
+      .options(/.*/)
+      .reply(200)
+      .get(`/article-cooler/${payload.id}`)
+      .reply(200, payload)
+      .delete(`/article-cooler/${payload.id}`)
+      .reply(204, '')
+      .delete(`/article/${payload.id}`)
+      .reply(200, {})
+      .get(`/article-cooler/0`)
+      .reply(403, {})
+      .get(`/article-cooler/666`)
+      .reply(200, '')
+      .get(`/article-cooler`)
+      .reply(200, nested)
+      .post(`/article-cooler`)
+      .reply(200, createPayload)
+      .get(`/user`)
+      .reply(200, users);
+    mynock = nock(/.*/).defaultReplyHeaders({
+      'Access-Control-Allow-Origin': '*',
+      'Content-Type': 'application/json',
+    });
+  });
+
+  afterEach(() => {
+    nock.cleanAll();
+  });
+
+  it('should handle simple urls', () => {
+    expect(UserResource.get.url({ id: '5' })).toBe('http://test.com/user/5');
+    expect(UserResource.get.url({ id: '100' })).toBe(
+      'http://test.com/user/100',
+    );
+    /*expect(UserResource.getList.url({ bob: '100' })).toBe(
+      'http://test.com/user?bob=100',
+    );
+    expect(UserResource.create.url({ bob: '100' })).toBe(
+      'http://test.com/user',
+    );*/
+    expect(
+      UserResource.update.url({ id: '100' }, { id: 100, username: 'bob' }),
+    ).toBe('http://test.com/user/100');
+
+    // @ts-expect-error
+    () => UserResource.get.url({ sdf: '5' });
+  });
+
+  it('should handle multiarg urls', () => {
+    const MyUserResource = createResource({
+      path: 'http\\://test.com/groups/:group/users/:id',
+      schema: User,
+    });
+
+    expect(MyUserResource.get.url({ group: 'big', id: '5' })).toBe(
+      'http://test.com/groups/big/users/5',
+    );
+    expect(MyUserResource.get.url({ group: 'big', id: '100' })).toBe(
+      'http://test.com/groups/big/users/100',
+    );
+    /*expect(MyUserResource.getList.url({ group: 'big', bob: '100' })).toBe(
+      'http://test.com/groups/big/users?bob=100',
+    );*/
+    expect(
+      MyUserResource.create.url({ group: 'big' }, { username: '100' }),
+    ).toBe('http://test.com/groups/big/users');
+    expect(
+      MyUserResource.update.url(
+        { group: 'big', id: '100' },
+        { id: 100, username: 'bob' },
+      ),
+    ).toBe('http://test.com/groups/big/users/100');
+
+    // missing required
+    expect(() =>
+      // @ts-expect-error
+      MyUserResource.get.url({ id: '5' }),
+    ).toThrow();
+    // extra fields
+    () =>
+      MyUserResource.get.url({
+        group: 'mygroup',
+        id: '5',
+        // @ts-expect-error
+        notexisting: 'hi',
+      });
+
+    // @ts-expect-error
+    () => useSuspense(MyUserResource.get, { id: '5' });
+    // @ts-expect-error
+    () => useSuspense(MyUserResource.get);
+    () => useSuspense(MyUserResource.get, { group: 'yay', id: '5' });
+  });
+
+  it('should automatically name methods', () => {
+    expect(PaginatedArticleResource.get.name).toBe('PaginatedArticle.get');
+    expect(PaginatedArticleResource.create.name).toBe(
+      'PaginatedArticle.create',
+    );
+    expect(PaginatedArticleResource.getList.name).toBe(
+      'PaginatedArticle.getList',
+    );
+    expect(PaginatedArticleResource.delete.name).toBe(
+      'PaginatedArticle.delete',
+    );
+  });
+
+  it('should update on get for a paginated resource', async () => {
+    mynock.get(`/article-paginated`).reply(200, paginatedFirstPage);
+    mynock.get(`/article-paginated?cursor=2`).reply(200, paginatedSecondPage);
+
+    const { result, waitForNextUpdate } = renderRestHook(() => {
+      const { fetch } = useController();
+      const {
+        data: { results: articles },
+        nextPage,
+      } = useSuspense(PaginatedArticleResource.getList);
+      return { articles, nextPage, fetch };
+    });
+    await waitForNextUpdate();
+    () =>
+      // @ts-expect-error
+      result.current.fetch(PaginatedArticleResource.getNextPage);
+    await result.current.fetch(PaginatedArticleResource.getNextPage, {
+      cursor: 2,
+    });
+    expect(result.current.articles.map(({ id }) => id)).toEqual([5, 3, 7, 8]);
+  });
+
+  it('should deduplicate results', async () => {
+    mynock.get(`/article-paginated`).reply(200, paginatedFirstPage);
+    mynock.get(`/article-paginated?cursor=2`).reply(200, {
+      ...paginatedSecondPage,
+      results: [nested[nested.length - 1], ...moreNested],
+    });
+
+    const { result, waitForNextUpdate } = renderRestHook(() => {
+      const { fetch } = useController();
+      const {
+        data: { results: articles },
+        nextPage,
+      } = useSuspense(PaginatedArticleResource.getList);
+      return { articles, nextPage, fetch };
+    });
+    await waitForNextUpdate();
+    await result.current.fetch(PaginatedArticleResource.getNextPage, {
+      cursor: 2,
+    });
+    expect(result.current.articles.map(({ id }) => id)).toEqual([5, 3, 7, 8]);
+  });
+
+  it('should not deep-merge deeply defined entities', async () => {
+    interface Complex {
+      firstvalue: number;
+      secondthing: {
+        arg?: number;
+        other?: string;
+      };
+    }
+    class ComplexEntity extends Entity {
+      readonly id: string = '';
+      readonly complexThing?: Complex = undefined;
+      readonly extra: string = '';
+
+      pk() {
+        return this.id;
+      }
+    }
+    const ComplexResource = createResource({
+      path: '/complex-thing/:id',
+      schema: ComplexEntity,
+    });
+    const firstResponse = {
+      id: '5',
+      complexThing: {
+        firstvalue: 233,
+        secondthing: { arg: 88 },
+      },
+      extra: 'hi',
+    };
+    mynock.get(`/complex-thing/5`).reply(200, firstResponse);
+
+    const { result, waitForNextUpdate } = renderRestHook(() => {
+      const { fetch } = useController();
+      const article = useSuspense(ComplexResource.get, { id: '5' });
+      return { article, fetch };
+    });
+    await waitForNextUpdate();
+    expect(result.current.article).toEqual(firstResponse);
+
+    const secondResponse = {
+      id: '5',
+      complexThing: {
+        firstvalue: 5,
+        secondthing: { other: 'hi' },
+      },
+    };
+
+    mynock.get(`/complex-thing/5`).reply(200, secondResponse);
+    await result.current.fetch(ComplexResource.get, {
+      id: '5',
+    });
+    expect(result.current.article).toEqual({ ...secondResponse, extra: 'hi' });
+  });
+
+  it('delete() should fallback to params when response is empty object', async () => {
+    mynock.delete(`/article-paginated/500`).reply(200, {});
+    const res = await PaginatedArticleResource.delete({ id: 500 });
+    expect(res).toEqual({ id: 500 });
+  });
+
+  it('delete() should fallback to params when response is undefined', async () => {
+    mynock.delete(`/article-paginated/500`).reply(204, undefined);
+    const res = await PaginatedArticleResource.delete({ id: 500 });
+    expect(res).toEqual({ id: 500 });
+  });
+
+  it('should spread `url` member', () => {
+    const entity = UrlArticle.fromJS({ url: 'five' });
+    const spread = { ...entity };
+    expect(spread.url).toBe('five');
+    expect(Object.hasOwn(entity, 'url')).toBeTruthy();
+  });
+});