Merge pull request #13 from slocka/renaming-types

Vincent Comby · web-flow · commit bccbca4805c4 · 2020-11-24T09:54:24.000+01:00
Renaming types
diff --git a/src/buildQueryString.ts b/src/buildQueryString.ts
@@ -1,4 +1,4 @@
-import { IQueryParamsSchema, QueryParams } from './types';
+import { IQueryParamsStateSchema, QueryParamsState } from './types';
 
 import { runParamsValidatorsPartial } from './validators';
 import { serializeQueryParamsValues } from './internal/serializer/serialize';
@@ -8,7 +8,9 @@ import { createQueryString } from './internal/queryString';
  * Create a new query string based on the provided schema and a matching query params object.
  * An error will be thrown if the param does not match the type defined in the schema.
  */
-export function buildQueryString<QueryParamsSchema extends IQueryParamsSchema>(
+export function buildQueryString<
+  QueryParamsSchema extends IQueryParamsStateSchema
+>(
   /**
    * The parameters schema followed by the query string.
    */
@@ -17,7 +19,7 @@ export function buildQueryString<QueryParamsSchema extends IQueryParamsSchema>(
    * The query parameters you want to add to the query string and belong
    * to the schema.
    */
-  newQueryParams: Partial<QueryParams<QueryParamsSchema>> = {},
+  newQueryParams: Partial<QueryParamsState<QueryParamsSchema>> = {},
   contextData?: any,
   /**
    * The query parameters you want to add to the query string but don't
diff --git a/src/createUseQueryParamsStateHook.ts b/src/createUseQueryParamsStateHook.ts
@@ -1,4 +1,4 @@
-import { IQueryParamsSchema } from './types';
+import { IQueryParamsStateSchema } from './types';
 import { useQueryParamsState } from './useQueryParamsState';
 
 /**
@@ -7,7 +7,7 @@ import { useQueryParamsState } from './useQueryParamsState';
  * @param queryParamsConfig
  */
 export function createUseQueryParamsStateHook<
-  QueryParamsSchema extends IQueryParamsSchema
+  QueryParamsSchema extends IQueryParamsStateSchema
 >(queryParamsSchena: QueryParamsSchema) {
   return (contextData?: any) => {
     return useQueryParamsState(queryParamsSchena, contextData);
diff --git a/src/internal/buildQueryStringFromCurrentURL.ts b/src/internal/buildQueryStringFromCurrentURL.ts
@@ -1,6 +1,10 @@
 import { useLocation } from 'react-router-dom';
 
-import { IQueryParamsSchema, QueryParams, QS_BUILD_STRATEGY } from '../types';
+import {
+  IQueryParamsStateSchema,
+  QueryParamsState,
+  QS_BUILD_STRATEGY,
+} from '../types';
 
 import {
   getAllRawQueryParamsFromURL,
@@ -15,11 +19,11 @@ import { buildQueryString } from '../buildQueryString';
  * @internal
  */
 export function buildQueryStringFromCurrentURL<
-  QueryParamsSchema extends IQueryParamsSchema
+  QueryParamsSchema extends IQueryParamsStateSchema
 >(
   location: ReturnType<typeof useLocation>,
   queryParamsSchema: QueryParamsSchema,
-  newQueryParams: Partial<QueryParams<QueryParamsSchema>> = {},
+  newQueryParams: Partial<QueryParamsState<QueryParamsSchema>> = {},
   buildStrategy: QS_BUILD_STRATEGY = QS_BUILD_STRATEGY.PRESERVE_ALL,
   contextData?: any
 ): string {
@@ -42,7 +46,7 @@ export function buildQueryStringFromCurrentURL<
  * Get object in which the new query params are going be merged into.
  * The returned object has its valued already stringified.
  */
-function getMergeDestination<QueryParamsSchema extends IQueryParamsSchema>(
+function getMergeDestination<QueryParamsSchema extends IQueryParamsStateSchema>(
   location: ReturnType<typeof useLocation>,
   queryParamsSchema: QueryParamsSchema,
   buildStrategy: QS_BUILD_STRATEGY,
diff --git a/src/internal/getDefaultQueryParamsState.ts b/src/internal/getDefaultQueryParamsState.ts
@@ -1,20 +1,20 @@
-import { IQueryParamsSchema, QueryParams } from '../types';
+import { IQueryParamsStateSchema, QueryParamsState } from '../types';
 
 /**
  * @internal
  */
 export function getDefaultQueryParamsState<
-  QueryParamsSchema extends IQueryParamsSchema
+  QueryParamsSchema extends IQueryParamsStateSchema
 >(
   queryParamsSchema: QueryParamsSchema,
   contextData?: any
-): QueryParams<QueryParamsSchema> {
+): QueryParamsState<QueryParamsSchema> {
   return Object.keys(queryParamsSchema).reduce(
     (acc, queryParamKey: keyof QueryParamsSchema) => {
       const queryParamDef = queryParamsSchema[queryParamKey];
       acc[queryParamKey] = queryParamDef.getDefaultValue(contextData);
       return acc;
     },
-    {} as QueryParams<QueryParamsSchema>
+    {} as QueryParamsState<QueryParamsSchema>
   );
 }
diff --git a/src/internal/getQueryParamsFromURL.ts b/src/internal/getQueryParamsFromURL.ts
@@ -1,4 +1,4 @@
-import { IQueryParamsSchema, RawQueryParams } from '../types';
+import { IQueryParamsStateSchema, RawQueryParams } from '../types';
 
 import { useLocation } from 'react-router-dom';
 
@@ -19,7 +19,7 @@ export function getAllRawQueryParamsFromURL(
  * @internal
  */
 export function getRawQueryParamsInSchemaFromURL<
-  QueryParamsSchema extends IQueryParamsSchema
+  QueryParamsSchema extends IQueryParamsStateSchema
 >(
   location: ReturnType<typeof useLocation>,
   schema: QueryParamsSchema
@@ -45,7 +45,7 @@ export function getRawQueryParamsInSchemaFromURL<
  * @internal
  */
 export function getExternalQueryParamsFromURL<
-  QueryParamsSchema extends IQueryParamsSchema
+  QueryParamsSchema extends IQueryParamsStateSchema
 >(
   location: ReturnType<typeof useLocation>,
   schema: QueryParamsSchema
diff --git a/src/internal/getRawQueryParams.ts b/src/internal/getRawQueryParams.ts
@@ -1,13 +1,19 @@
-import { RawQueryParams, IQueryParamsSchema, QueryParams } from '../types';
+import {
+  RawQueryParams,
+  IQueryParamsStateSchema,
+  QueryParamsState,
+} from '../types';
 import { serializeQueryParamsValues } from '../internal/serializer/serialize';
 
 /**
  * Convert each queryParams value to its "raw" (stringified) version based
  * on the provided schema.
  * @internal
  */
-export function getRawQueryParams<QueryParamsSchema extends IQueryParamsSchema>(
-  queryParams: QueryParams<QueryParamsSchema>,
+export function getRawQueryParams<
+  QueryParamsSchema extends IQueryParamsStateSchema
+>(
+  queryParams: QueryParamsState<QueryParamsSchema>,
   queryParamsSchema: QueryParamsSchema
 ): RawQueryParams<QueryParamsSchema> {
   return serializeQueryParamsValues(queryParamsSchema, queryParams);
diff --git a/src/internal/serializer/serialize.ts b/src/internal/serializer/serialize.ts
@@ -1,5 +1,9 @@
 import { isUndefined } from '../typeChecking';
-import { QueryParams, RawQueryParams, IQueryParamsSchema } from '../../types';
+import {
+  QueryParamsState,
+  RawQueryParams,
+  IQueryParamsStateSchema,
+} from '../../types';
 
 import { Errors } from '../../errors';
 
@@ -12,12 +16,12 @@ import { Errors } from '../../errors';
  * @param queryParams - Raw query params extracted from the URL but not parsed.
  */
 export function deserializeQueryParamsValues<
-  QueryParamsSchema extends IQueryParamsSchema
+  QueryParamsSchema extends IQueryParamsStateSchema
 >(
   queryParamsSchema: QueryParamsSchema,
   rawQueryParams: Partial<RawQueryParams<QueryParamsSchema>>,
   contextData?: any
-): QueryParams<QueryParamsSchema> {
+): QueryParamsState<QueryParamsSchema> {
   return Object.keys(queryParamsSchema).reduce(
     (acc, queryParamKey: keyof QueryParamsSchema) => {
       const queryParamDef = queryParamsSchema[queryParamKey];
@@ -28,15 +32,15 @@ export function deserializeQueryParamsValues<
 
       return acc;
     },
-    {} as QueryParams<QueryParamsSchema>
+    {} as QueryParamsState<QueryParamsSchema>
   );
 }
 
 export function serializeQueryParamsValues<
-  QueryParamsSchema extends IQueryParamsSchema
+  QueryParamsSchema extends IQueryParamsStateSchema
 >(
   queryParamsSchema: QueryParamsSchema,
-  queryParams: Partial<QueryParams<QueryParamsSchema>>
+  queryParams: Partial<QueryParamsState<QueryParamsSchema>>
 ): RawQueryParams<QueryParamsSchema> {
   return Object.keys(queryParams).reduce(
     (acc, queryParamKey: keyof QueryParamsSchema) => {
diff --git a/src/internal/serializer/serializers.ts b/src/internal/serializer/serializers.ts
@@ -1,4 +1,4 @@
-import { isNumber, isNil } from '../typeChecking';
+import { isNumber, isNil, getTypeName } from '../typeChecking';
 import { Serializer } from '../../types';
 import { Errors } from '../../errors';
 
@@ -23,7 +23,7 @@ const arrayStringsSerializer: Serializer<string[]> = {
 
     if (!Array.isArray(array)) {
       throw new Errors.QueryParamsUpdateError(
-        `was expecting an array but received a ${typeof array}.`
+        `was expecting an array but received a ${getTypeName(array)}.`
       );
     }
 
@@ -50,7 +50,7 @@ const arrayNumbersSerializer: Serializer<number[]> = {
 
     if (!Array.isArray(array)) {
       throw new Errors.QueryParamsUpdateError(
-        `was expecting an array but received a ${typeof array}.`
+        `was expecting an array but received a ${getTypeName(array)}.`
       );
     }
 
@@ -69,7 +69,7 @@ const stringSerializer: Serializer<string> = {
 
     if (typeof str !== 'string') {
       throw new Errors.QueryParamsUpdateError(
-        `was expecting a string but received a ${typeof str}.`
+        `was expecting a string but received a ${getTypeName(str)}.`
       );
     }
 
@@ -106,7 +106,7 @@ const booleanSerializer: Serializer<boolean> = {
 
     if (typeof bool !== 'boolean') {
       throw new Errors.QueryParamsUpdateError(
-        `was expecting a boolean but received a ${typeof bool}.`
+        `was expecting a boolean but received a ${getTypeName(bool)}.`
       );
     }
 
@@ -130,7 +130,7 @@ const numberSerializer: Serializer<number> = {
 
     if (!isNumber(number)) {
       throw new Errors.QueryParamsUpdateError(
-        `was expecting a number but received a ${typeof number}.`
+        `was expecting a number but received a ${getTypeName(number)}.`
       );
     }
 
diff --git a/src/internal/typeChecking.ts b/src/internal/typeChecking.ts
@@ -23,3 +23,16 @@ export function isNumber(value: any): value is number {
 export function isNil(value: any): value is undefined | null {
   return isUndefined(value) || value === null;
 }
+
+/**
+ * Returns the type of the value.
+ * This is a slightly smarter version of `typeof X`
+ * which can handle arrays.
+ */
+export function getTypeName(value: any): string {
+  if (Array.isArray(value)) {
+    return 'array';
+  }
+
+  return typeof value;
+}
diff --git a/src/pickQueryParamsMatchingSchema.ts b/src/pickQueryParamsMatchingSchema.ts
@@ -1,4 +1,4 @@
-import { QueryParams, IQueryParamsSchema } from './types';
+import { QueryParamsState, IQueryParamsStateSchema } from './types';
 
 /**
  * Take an object as input and return a new object keeping only
@@ -16,17 +16,17 @@ import { QueryParams, IQueryParamsSchema } from './types';
  * This util does not do any type validation.
  */
 export function pickQueryParamsMatchingSchema<
-  QueryParamsSchema extends IQueryParamsSchema
+  QueryParamsSchema extends IQueryParamsStateSchema
 >(
   queryParamsSchema: QueryParamsSchema,
   queryParams: Record<string, any>
-): Partial<QueryParams<QueryParamsSchema>> {
+): Partial<QueryParamsState<QueryParamsSchema>> {
   if (!queryParams) {
     return {};
   }
   return Object.keys(queryParamsSchema).reduce(
     (
-      acc: Partial<QueryParams<QueryParamsSchema>>,
+      acc: Partial<QueryParamsState<QueryParamsSchema>>,
       queryParamsKey: keyof QueryParamsSchema
     ) => {
       if (queryParams.hasOwnProperty(queryParamsKey)) {
diff --git a/src/types.ts b/src/types.ts
@@ -1,5 +1,38 @@
 import { QueryParamDef } from './internal/queryParamDef';
 
+/**
+ * Interface any query-params-state schema needs to extend.
+ */
+export type IQueryParamsStateSchema = Record<string, QueryParamDef<any>>;
+
+/**
+ * The Javascript state representing the content of the URL query string based on the associated
+ * query-params-state schema.
+ */
+export type QueryParamsState<S extends IQueryParamsStateSchema> = {
+  [K in keyof S]: S[K] extends QueryParamDef<infer T>
+    ? T | null | undefined
+    : never;
+};
+
+export type SetQueryParamsState<T extends IQueryParamsStateSchema> = (
+  newQueryParams: Partial<QueryParamsState<T>>,
+  fromCurrent?: boolean
+) => void;
+
+/**
+ * Javascript object representing the "raw" (not decoded) content of the URL,
+ * without validation nor type transformation.
+ */
+export type RawQueryParams<S extends IQueryParamsStateSchema> = Record<
+  keyof S,
+  string | null | undefined
+>;
+
+/**
+ * Enum of build strategies determining how a newly build query string should preserve
+ * parameters from the current query string.
+ */
 export enum QS_BUILD_STRATEGY {
   /**
    * Create a new query string from new params and preserve all pre-existing params.
@@ -21,35 +54,23 @@ export enum QS_BUILD_STRATEGY {
   PRESERVE_NONE,
 }
 
+export type BuildQueryStringFromCurrentUrl<
+  T extends IQueryParamsStateSchema
+> = (
+  newQueryParams?: Partial<QueryParamsState<T>>,
+  buildStrategy?: QS_BUILD_STRATEGY,
+  contextData?: any
+) => string;
+
+export type DefaultValueFunction<T> = (context?: any) => T;
+export type DefaultValue<T> = T | DefaultValueFunction<T> | undefined | null;
+
 export type ValidatorFunction<T> = (
   value: T,
   queryParams: object,
   contextData: any
 ) => void;
 
-export type IQueryParamsSchema = Record<string, QueryParamDef<any>>;
-export type QueryParams<S extends IQueryParamsSchema> = {
-  [K in keyof S]: S[K] extends QueryParamDef<infer T>
-    ? T | null | undefined
-    : never;
-};
-
-export type QueryParamsSetter<T extends IQueryParamsSchema> = (
-  newQueryParams: Partial<QueryParams<T>>,
-  fromCurrent?: boolean
-) => void;
-
-export type RawQueryParams<S extends IQueryParamsSchema> = Record<
-  keyof S,
-  string | null | undefined
->;
-
-export type QueryStringBuilderFunction<T extends IQueryParamsSchema> = (
-  newQueryParams?: Partial<QueryParams<T>>,
-  buildStrategy?: QS_BUILD_STRATEGY,
-  contextData?: any
-) => string;
-
 export type SerializerToUrlFunction<T> = (
   param?: T | null
 ) => string | null | undefined;
@@ -62,6 +83,3 @@ export type Serializer<T> = {
   toUrl: SerializerToUrlFunction<T>;
   fromUrl: SerializerFromUrlFunction<T>;
 };
-
-export type DefaultValueFunction<T> = (context?: any) => T;
-export type DefaultValue<T> = T | DefaultValueFunction<T> | undefined | null;
diff --git a/src/useBuildQueryStringFromCurrentURL.ts b/src/useBuildQueryStringFromCurrentURL.ts
diff --git a/src/useQueryParamsState.ts b/src/useQueryParamsState.ts
diff --git a/src/validators.ts b/src/validators.ts
diff --git a/test/serializers.test.ts b/test/serializers.test.ts
