@sapporta/rest-core 3.52.1

package/src/lib/query.spec.ts

@@ -0,0 +1,329 @@
+import {
+  convertQueryParamsToUrlString,
+  encodeQueryParams,
+  encodeQueryParamsJson,
+  parseJsonQueryObject,
+} from './query';
+import { parse as qsParse, stringify as qsStringify } from 'qs';
+
+describe('convertQueryParamsToUrlString', () => {
+  it('should convert query params to url string', () => {
+    const query = {
+      id: 'abc',
+    };
+
+    expect(convertQueryParamsToUrlString(query)).toBe('?id=abc');
+    expect(convertQueryParamsToUrlString(query, true)).toBe(`?id=abc`);
+  });
+
+  it('should convert query params to url string with no params', () => {
+    const query = {};
+
+    expect(convertQueryParamsToUrlString(query)).toBe('');
+    expect(convertQueryParamsToUrlString(query, true)).toBe('');
+  });
+
+  it('should convert query params to url string with primitives', () => {
+    expect(convertQueryParamsToUrlString(null)).toBe('');
+    expect(convertQueryParamsToUrlString(undefined)).toBe('');
+    expect(convertQueryParamsToUrlString(true)).toBe('');
+    expect(convertQueryParamsToUrlString(123)).toBe('');
+
+    expect(convertQueryParamsToUrlString(null, true)).toBe('');
+    expect(convertQueryParamsToUrlString(undefined, true)).toBe('');
+    expect(convertQueryParamsToUrlString(true, true)).toBe('');
+    expect(convertQueryParamsToUrlString(123, true)).toBe('');
+  });
+});
+
+describe('encodeQueryParams', () => {
+  it('should be empty if no params', () => {
+    const query = {};
+
+    const result = encodeQueryParams(query);
+
+    expect(result).toBe('');
+    expect(qsStringify(query)).toBe(result);
+  });
+
+  it('should convert query params to url string with many params', () => {
+    const query = {
+      id: '1',
+      commentId: '2',
+      commentId2: '3',
+    };
+
+    const result = encodeQueryParams(query);
+
+    expect(result).toBe(encodeURI('id=1&commentId=2&commentId2=3'));
+
+    expect(qsParse(result)).toEqual({
+      id: '1',
+      commentId: '2',
+      commentId2: '3',
+    });
+    expect(qsStringify(query)).toBe(result);
+  });
+
+  it('should explode arrays', () => {
+    const query = {
+      array: ['1', '2', '3'],
+      id: '1',
+    };
+
+    const result = encodeQueryParams(query);
+
+    expect(result).toBe(encodeURI('array[0]=1&array[1]=2&array[2]=3&id=1'));
+
+    expect(qsParse(result)).toEqual({
+      array: ['1', '2', '3'],
+      id: '1',
+    });
+    expect(qsStringify(query)).toBe(result);
+  });
+
+  it('should explode nested query strings with arrays and other keys', () => {
+    const query = {
+      nested: {
+        array: ['1', '2', '3'],
+        id: '1',
+        nestedNested: {
+          id: '2',
+        },
+      },
+    };
+
+    const result = encodeQueryParams(query);
+
+    expect(result).toBe(
+      encodeURI(
+        'nested[array][0]=1&nested[array][1]=2&nested[array][2]=3&nested[id]=1&nested[nestedNested][id]=2',
+      ),
+    );
+
+    expect(qsParse(result)).toEqual({
+      nested: {
+        array: ['1', '2', '3'],
+        id: '1',
+        nestedNested: {
+          id: '2',
+        },
+      },
+    });
+    expect(qsStringify(query)).toBe(result);
+  });
+
+  it('should work for null, undefined, and NaN', () => {
+    const query = {
+      null: null,
+      undefined: undefined,
+      nan: NaN,
+    };
+
+    const result = encodeQueryParams(query);
+
+    expect(result).toBe(encodeURI('null=&nan=NaN'));
+
+    // qs compatibility
+    expect(qsParse(result)).toEqual({
+      null: '',
+      nan: 'NaN',
+    });
+    expect(qsStringify(query)).toBe(result);
+  });
+
+  it('should format dates as ISO strings', () => {
+    const query = {
+      date: new Date('2020-01-01'),
+    };
+
+    const result = encodeQueryParams(query);
+
+    expect(result).toBe('date=2020-01-01T00%3A00%3A00.000Z');
+    expect(qsParse(result)).toEqual({
+      date: '2020-01-01T00:00:00.000Z',
+    });
+    expect(qsStringify(query)).toBe(result);
+  });
+
+  it('should parse booleans', () => {
+    const query = {
+      bool: true,
+      false: false,
+    };
+
+    const result = encodeQueryParams(query);
+
+    expect(result).toBe(encodeURI('bool=true&false=false'));
+    expect(qsParse(result)).toEqual({
+      bool: 'true',
+      false: 'false',
+    });
+    expect(qsStringify(query)).toBe(result);
+  });
+
+  it('should parse numbers', () => {
+    const query = {
+      number: 1,
+      float: 1.1,
+    };
+
+    const result = encodeQueryParams(query);
+
+    expect(result).toBe(encodeURI('number=1&float=1.1'));
+    expect(qsParse(result)).toEqual({
+      number: '1',
+      float: '1.1',
+    });
+    expect(qsStringify(query)).toBe(result);
+  });
+
+  it('should parse objects', () => {
+    const query = {
+      object: { id: '1' },
+    };
+
+    const result = encodeQueryParams(query);
+    expect(result).toBe(encodeURI('object[id]=1'));
+    expect(qsParse(result)).toEqual(query);
+    expect(qsStringify(query)).toBe(result);
+  });
+
+  it('should parse with arrays of objects', () => {
+    const query = {
+      array: [{ id: '1' }, { id: '2' }],
+    };
+
+    const result = encodeQueryParams(query);
+
+    expect(result).toBe(encodeURI('array[0][id]=1&array[1][id]=2'));
+    expect(qsParse(result)).toEqual(query);
+    expect(qsStringify(query)).toBe(result);
+  });
+
+  it('should parse arrays in arrays', () => {
+    const query = {
+      array: [['1', '2']],
+    };
+
+    const result = encodeQueryParams(query);
+
+    expect(result).toBe(encodeURI('array[0][0]=1&array[0][1]=2'));
+    expect(qsParse(result)).toEqual(query);
+    expect(qsStringify(query)).toBe(result);
+  });
+
+  it('should encode values with equals sign in key', () => {
+    const query = {
+      'foo=bar': 'baz',
+    };
+
+    const result = encodeQueryParams(query);
+
+    expect(result).toBe('foo%3Dbar=baz');
+    expect(qsParse(result)).toEqual(query);
+    expect(qsStringify(query)).toBe(result);
+  });
+
+  it('should encode values with equals sign in value', () => {
+    const query = {
+      foo: 'bar=baz',
+    };
+
+    const result = encodeQueryParams(query);
+
+    expect(result).toBe('foo=bar%3Dbaz');
+    expect(qsParse(result)).toEqual(query);
+    expect(qsStringify(query)).toBe(result);
+  });
+});
+
+describe('encodeQueryParamsJson', () => {
+  it('should be empty if no params', () => {
+    const query = {};
+
+    const result = encodeQueryParamsJson(query);
+
+    expect(result).toBe('');
+  });
+
+  it('should convert query params to url string with many params', () => {
+    const query = {
+      id: 123,
+      string: 'ABC',
+      trueString: 'true',
+      falseString: 'false',
+      nullString: 'null',
+      numberString: '123',
+      boolean: true,
+      null: null,
+      undefined: undefined,
+      sorting: {
+        by: 'date',
+        order: 'asc',
+      },
+      filter: {
+        date: {
+          gt: new Date('2020-01-01'),
+        },
+      },
+    };
+
+    const result = encodeQueryParamsJson(query);
+
+    expect(result).toBe(
+      `id=123&string=ABC&trueString=%22true%22&falseString=%22false%22&nullString=%22null%22&numberString=%22123%22&boolean=true&null=null&sorting=${encodeURIComponent(
+        '{"by":"date","order":"asc"}',
+      )}&filter=${encodeURIComponent(
+        '{"date":{"gt":"2020-01-01T00:00:00.000Z"}}',
+      )}`,
+    );
+  });
+});
+
+describe('parseJsonQueryObject', () => {
+  it('should be empty if no params', () => {
+    const query = {};
+
+    const result = parseJsonQueryObject(query);
+
+    expect(result).toEqual({});
+  });
+
+  it('should convert json query object to regular object', () => {
+    const query = {
+      id: '123',
+      string: 'ABC',
+      trueString: '"true"',
+      falseString: '"false"',
+      nullString: '"null"',
+      numberString: '"123"',
+      boolean: 'true',
+      null: 'null',
+      sorting: '{"by":"date","order":"asc"}',
+      filter: '{"date":{"gt":"2020-01-01T00:00:00.000Z"}}',
+    };
+
+    const result = parseJsonQueryObject(query);
+
+    expect(result).toEqual({
+      id: 123,
+      string: 'ABC',
+      trueString: 'true',
+      falseString: 'false',
+      nullString: 'null',
+      numberString: '123',
+      boolean: true,
+      null: null,
+      sorting: {
+        by: 'date',
+        order: 'asc',
+      },
+      filter: {
+        date: {
+          gt: '2020-01-01T00:00:00.000Z',
+        },
+      },
+    });
+  });
+});

package/src/lib/query.ts

@@ -0,0 +1,114 @@
+/**
+ *
+ * @param query - Any JSON object
+ * @param json - Use JSON.stringify to encode the query values
+ * @returns - The query url segment, using explode array syntax, and deep object syntax
+ */
+export const convertQueryParamsToUrlString = (query: unknown, json = false) => {
+  const queryString = json
+    ? encodeQueryParamsJson(query)
+    : encodeQueryParams(query);
+  return queryString?.length > 0 ? '?' + queryString : '';
+};
+
+export const encodeQueryParamsJson = (query: unknown) => {
+  if (!query) {
+    return '';
+  }
+
+  return Object.entries(query)
+    .filter(([, value]) => value !== undefined)
+    .map(([key, value]) => {
+      let encodedValue;
+
+      // if value is a string and is not a reserved JSON value or a number, pass it without encoding
+      // this makes strings look nicer in the URL (e.g. ?name=John instead of ?name=%22John%22)
+      // this is also how OpenAPI will pass strings even if they are marked as application/json types
+      if (
+        typeof value === 'string' &&
+        !['true', 'false', 'null'].includes(value.trim()) &&
+        isNaN(Number(value))
+      ) {
+        encodedValue = value;
+      } else {
+        encodedValue = JSON.stringify(value);
+      }
+
+      return `${encodeURIComponent(key)}=${encodeURIComponent(encodedValue)}`;
+    })
+    .join('&');
+};
+
+export const encodeQueryParams = (query: unknown) => {
+  if (!query) {
+    return '';
+  }
+
+  return (
+    Object.keys(query)
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      .flatMap((key) => tokeniseValue(key, query[key]))
+      .map(([key, value]) => {
+        return `${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+      })
+      .join('&')
+  );
+};
+
+/**
+ * A recursive function to convert an object/string/number/Date/whatever into an array of key=value pairs
+ *
+ * The output of this should be flatMap-able to a string of key=value pairs which can be
+ * joined with & to form a query string
+ *
+ * This should be fully compatible with the "qs" library, but without the need to add a dependency
+ */
+const tokeniseValue = (key: string, value: unknown): [string, string][] => {
+  if (Array.isArray(value)) {
+    return value.flatMap((v, idx) => tokeniseValue(`${key}[${idx}]`, v));
+  }
+
+  if (value instanceof Date) {
+    return [[`${key}`, value.toISOString()]];
+  }
+
+  if (value === null) {
+    return [[`${key}`, '']];
+  }
+
+  if (value === undefined) {
+    return [];
+  }
+
+  if (typeof value === 'object') {
+    return Object.keys(value).flatMap((k) =>
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      tokeniseValue(`${key}[${k}]`, value[k]),
+    );
+  }
+
+  return [[`${key}`, `${value}`]];
+};
+
+/**
+ *
+ * @param query - A server-side query object where values have been encoded as JSON strings
+ * @returns - The same object with the JSON strings decoded. Objects that were encoded using toJSON such as Dates will remain as strings
+ */
+export const parseJsonQueryObject = (query: Record<string, string>) => {
+  return Object.fromEntries(
+    Object.entries(query).map(([key, value]) => {
+      let parsedValue: any;
+      // if json parse fails, treat the value as a string
+      // this allows us to pass strings without having to surround them with quotes
+      try {
+        parsedValue = JSON.parse(value);
+      } catch {
+        parsedValue = value;
+      }
+      return [key, parsedValue];
+    }),
+  );
+};

package/src/lib/response-error.spec.ts

@@ -0,0 +1,67 @@
+import type { Equal, Expect } from './test-helpers';
+import { initContract } from './dsl';
+import { z } from 'zod';
+import { TsRestResponseError } from './response-error';
+import { HTTPStatusCode } from './status-codes';
+
+const c = initContract();
+
+const contract = c.router(
+  {
+    posts: {
+      getPost: {
+        method: 'GET',
+        path: '/posts/:id',
+        responses: {
+          200: z.object({
+            id: z.number(),
+            content: z.string(),
+          }),
+        },
+      },
+    },
+    users: {
+      getUser: {
+        method: 'GET',
+        path: '/users/:id',
+        responses: {
+          200: z.object({
+            id: z.number(),
+            name: z.string(),
+          }),
+        },
+      },
+    },
+  },
+  {
+    commonResponses: {
+      404: z.object({
+        message: z.string(),
+      }),
+    },
+  },
+);
+
+describe('TsRestResponseError', () => {
+  it('correctly sets response type for single endpoint', () => {
+    type ResponseType = Expect<
+      Equal<
+        ConstructorParameters<
+          typeof TsRestResponseError<typeof contract.posts.getPost>
+        >[1],
+        | { status: 200; body: { id: number; content: string } }
+        | { status: 404; body: { message: string } }
+        | { status: Exclude<HTTPStatusCode, 200 | 404>; body: unknown }
+      >
+    >;
+  });
+
+  it('correctly sets response type for entire contract', () => {
+    type ResponseType = Expect<
+      Equal<
+        ConstructorParameters<typeof TsRestResponseError<typeof contract>>[1],
+        { status: 404; body: { message: string } }
+      >
+    >;
+  });
+});

package/src/lib/response-error.ts

@@ -0,0 +1,61 @@
+import { AppRoute, AppRouter, AppRouteResponse } from './dsl';
+import { ResolveResponseType, ServerInferResponses } from './infer-types';
+import { HTTPStatusCode } from './status-codes';
+import { CommonAndEqual, SchemaInputOrType } from './type-utils';
+
+export class TsRestResponseError<T extends AppRoute | AppRouter> extends Error {
+  public statusCode: HTTPStatusCode;
+  public body: any;
+
+  constructor(
+    route: T,
+    response: T extends AppRouter
+      ? ServerCommonResponses<T>
+      : ServerInferResponses<T>,
+  ) {
+    super();
+
+    this.statusCode = response.status as HTTPStatusCode;
+    this.body = response.body;
+    this.name = this.constructor.name;
+
+    if (typeof response.body === 'string') {
+      this.message = response.body;
+    } else if (
+      typeof response.body === 'object' &&
+      response.body !== null &&
+      'message' in response.body &&
+      typeof response.body.message === 'string'
+    ) {
+      this.message = response.body['message'];
+    } else {
+      this.message = 'Error';
+    }
+  }
+}
+
+type FlattenAppRouter<T extends AppRouter | AppRoute> = T extends AppRoute
+  ? T
+  : {
+      [TKey in keyof T]: T[TKey] extends AppRoute
+        ? T[TKey]
+        : T[TKey] extends AppRouter
+        ? FlattenAppRouter<T[TKey]>
+        : never;
+    }[keyof T];
+
+type AppRouterCommonResponses<T extends AppRouter> = CommonAndEqual<
+  FlattenAppRouter<T>['responses']
+>;
+
+type ServerCommonResponses<
+  T extends AppRouter,
+  TResponses = AppRouterCommonResponses<T>,
+> = {
+  [K in keyof TResponses]: {
+    status: K;
+    body: TResponses[K] extends AppRouteResponse
+      ? SchemaInputOrType<ResolveResponseType<TResponses[K]>>
+      : never;
+  };
+}[keyof TResponses];

package/src/lib/response-validation-error.ts

@@ -0,0 +1,24 @@
+import { AppRoute } from './dsl';
+import { StandardSchemaError } from './validation-error';
+
+export class TsRestResponseValidationError extends Error {
+  constructor(
+    public appRoute: AppRoute,
+    public cause: StandardSchemaError,
+  ) {
+    super(
+      `[ts-rest] Response validation failed for ${appRoute.method} ${appRoute.path}: ${cause.message}`,
+    );
+  }
+}
+
+export class TsRestRequestValidationError extends Error {
+  constructor(
+    public pathParams: StandardSchemaError | null,
+    public headers: StandardSchemaError | null,
+    public query: StandardSchemaError | null,
+    public body: StandardSchemaError | null,
+  ) {
+    super('[ts-rest] request validation failed');
+  }
+}