fix (doc&type): improve doc and add some types to help user to understand schema and options

AMontagu · AMontagu · commit d56052308ce4 · 2021-04-09T15:26:23.000+02:00
diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@ Now there is already some other lib even in pure Vanilla to sync the query param
 
 By separating the filters and the datable options vue-datatable-url-sync automatise all the desired behavior for working with datatable.
 
-Example of usage with a vuetify datatable:
+Example of usage with a vuetify datatable (It can work with any datatable):
 
 // coming soon
 
@@ -81,7 +81,7 @@ return {
 
 Prototype:
 ```js
-function useDatatableUrlSync(route: any, router: any, form: GenericDictionnary, fetchDatas: Function, options: GenericDictionnary, formSchema?: GenericDictionnary, initializeForm?: Function, configurations?: VDUSConfiguration)
+function useDatatableUrlSync(route: any, router: any, form: GenericDictionnary, fetchDatas: Function, options: GenericDictionnary, formSchema?: VDUSFormSchema, initializeForm?: Function, configurations?: VDUSConfiguration)
 ```
 
 | Params | Description |
@@ -90,15 +90,42 @@ function useDatatableUrlSync(route: any, router: any, form: GenericDictionnary,
 | router | The route instance from vue router. As it differe from Vue2 and Vue3 we can't import it automatically and need to have the instance in parameter |
 | form | A simple object used to filter the form. This object is synchronized with the url. When it change it reset the page attribute of the options variable |
 | fetchDatas | Callback function called when options or form changed or after a reload with the correct parameter to send to the backend for backend pagination or custom actions. This function take 2 parameter: queryParams, queryAsObject that are the data transformed by VDUS to match your backend criteria in string or object format.  |
-| options | The options used for the datatable. It follow a strict pattern. See [DatatableOptions](#TODO) type for more informations. If your server use other query identifier use formSchema to change their name before fetchDatas been called |
-| formSchema | The object that allow you to customize the defaut value, the type and the names send to the backend. See [FormSchema](#TODO) type for the structure and [the documentation section](#TODO) to understand how to use it |
-| initializeForm | A callback function called at the component creation to allow developer to adapt behavior depending of the query params in the url if needed. Usefull if to value are non-compatible because user change it manually. |
-| configurations | Object that allow to personnalise the behavior of VDUS in specific case. See [VDUSConfiguration](#TODO) type and [the documentation section](#TODO) to understand how to use it |
+| options | The options used for the datatable. It follow a strict pattern. See [VDUSDatatableOptions](#TODO) type for more informations. If your server use other query identifier use formSchema to change their name before fetchDatas been called |
+| formSchema | Optional. The object that allow you to customize the defaut value, the type and the names send to the backend. See [VDUSFormSchema](#TODO) type for the structure and [the documentation section](#TODO) to understand how to use it |
+| initializeForm | Optional. A callback function called at the component creation to allow developer to adapt behavior depending of the query params in the url if needed. Usefull if to value are non-compatible because user change it manually. |
+| configurations | Optional. Object that allow to personnalise the behavior of VDUS in specific case. See [VDUSConfiguration](#TODO) type and [the documentation section](#TODO) to understand how to use it |
 
 
-# useDatatableUrlSync returned value
+# useDatatableUrlSync returned values
 
 | Key name | Description |
 | --------- | ----------------------------------------------------------------- |
 | loading | Boolean value to be able to wait in the template that the data is correctly setted from the url and the data retrieve or filtered in fetchDatas especially if your fetchDatas is asynchronous |
 | vuetifyOptions | The datatable options on the vuetify format to be able to use it directly in the template without the need to transform it |
+
+
+# FormSchema 
+
+The parameter formSchema allow you to adapt the default behavior of vue-datatable-url-sync for each parameter (for the form AND for the options).
+With it you can specify the type of the params, the default value and the query param name to send to the server.
+
+[See the type to understand better](#TODO)
+
+Here is the description of the type for the configuration of each params ((ParamSchema)[#TODO]) 
+
+| Key name | Description |
+| --------- | ----------------------------------------------------------------- |
+| name | The name to send to the backend server |
+| default | The default value. It prevent default value to show in the url |
+| type | The type of the params to cast it correctly into your form or your options |
+
+
+# VDUS Types
+
+| Type name | Description |
+| ----------- | ------------------------------------------------------------------- |
+| [GenericDictionnary](#TODO) | Generic object that accept any key and any value |
+| [VDUSParamSchema](#TODO) | Object describing how to handle query param when reading them from url or before sending them to the backend server |
+| [VDUSFormSchema](#TODO) | Object describing how to handle the form and options object passed as parameter of useDatatableUrlSync |
+| [VDUSDatatableOptions](#TODO) | Object describing the params accepted in the datatable options |
+| [VDUSConfiguration](#TODO) | Configuration object for vue datatable url sync |
diff --git a/src/useDatatableUrlSync.ts b/src/useDatatableUrlSync.ts
@@ -13,13 +13,13 @@ import {
 import cloneDeep from "lodash.clonedeep";
 import isEqual from "lodash.isequal";
 
-import { ref, watch, nextTick, computed } from 'vue-demi'
-import {GenericDictionnary, VDUSConfiguration, VuetifyOptions} from "./utils/VDUSTypes"
+import { ref, watch, nextTick, computed, Ref } from 'vue-demi'
+import {GenericDictionnary, VDUSConfiguration, VuetifyOptions, VDUSFormSchema, VDUSDatatableOptions} from "./utils/VDUSTypes"
 
 /*
 DOC here on params and return value
 */
-export default function useDatatableUrlSync(route: any, router: any, form: GenericDictionnary, fetchDatas: Function, options: GenericDictionnary, formSchema?: GenericDictionnary, initializeForm?: Function, configurations?: VDUSConfiguration) { 
+export default function useDatatableUrlSync(route: any, router: any, form: Ref<GenericDictionnary>, fetchDatas: Function, options: Ref<VDUSDatatableOptions>, formSchema?: VDUSFormSchema, initializeForm?: Function, configurations?: VDUSConfiguration) { 
 
   // ----------------------------- DEFAULTING PARAMS ------------------------------
   configurations = {
@@ -33,6 +33,12 @@ export default function useDatatableUrlSync(route: any, router: any, form: Gener
     extraQueryParams: {},
     ...configurations || {}
   }
+  options.value = {
+    page: 1,
+    page_size: configurations.serveurDefaultPageSize,
+    ordering: [],
+    ...options.value
+  }
   formSchema = {
     page: { type: "integer", default: 1 },
     page_size: { type: "integer", default: 10 },
@@ -202,7 +208,7 @@ export default function useDatatableUrlSync(route: any, router: any, form: Gener
       if (
         key.startsWith(configurations?.prefix || "") &&
         (typeof form.value[keyWithoutPrefix] !== "undefined" ||
-          typeof options.value[keyWithoutPrefix] !== "undefined")
+          typeof (options.value as GenericDictionnary)[keyWithoutPrefix] !== "undefined")
       ) {
         newLocalQuery[keyWithoutPrefix] = convertParamIfTypeInSchema(
           route.query,
@@ -234,7 +240,7 @@ export default function useDatatableUrlSync(route: any, router: any, form: Gener
   /*
   Doc
   */
-  const updateOptionsIfNeeded = (newOptions: GenericDictionnary) => {
+  const updateOptionsIfNeeded = (newOptions: VDUSDatatableOptions) => {
     newOptions = { ...options.value, ...newOptions };
     if (isEqual(options.value, newOptions)) {
       return false;
@@ -292,7 +298,8 @@ export default function useDatatableUrlSync(route: any, router: any, form: Gener
 
     // If the form is updated because an other component pushed a new value that we was watching
     // And we was not on the first page we need to go back to the first page
-    if (formUpdated && options.value.page > 1) {
+    const currentPageNumber: number = options.value.page || 1;
+    if (formUpdated && currentPageNumber > 1) {
       options.value.page = 1;
     }
 
diff --git a/src/utils/VDUSTypes.ts b/src/utils/VDUSTypes.ts
@@ -1,11 +1,28 @@
 type GenericDictionnary = {
   [key: string]: any;
 }
+
+type VDUSParamSchema = {
+  name?: string;
+  default?: any;
+  type?: "string" | "boolean" | "integer" | "arrayInt" | "arrayString";
+}
+
+type VDUSFormSchema = {
+  [key: string]: VDUSParamSchema;
+}
+
+type VDUSDatatableOptions = {
+  page?: number;
+  page_size?: number;
+  ordering?: Array<string>;
+}
+
 type VDUSConfiguration = {
-  prefix: string;
-  debounceTime: number;
-  serveurDefaultPageSize: number;
-  extraQueryParams: GenericDictionnary;
+  prefix?: string;
+  debounceTime?: number;
+  serveurDefaultPageSize?: number;
+  extraQueryParams?: GenericDictionnary;
 }
 
 type VuetifySortArraysObject = {
@@ -24,4 +41,4 @@ type VuetifyOptions = {
   mustSort: boolean;
 }
 
-export {GenericDictionnary, VDUSConfiguration, VuetifySortArraysObject, VuetifyOptions}
+export {GenericDictionnary, VDUSConfiguration, VuetifySortArraysObject, VuetifyOptions, VDUSParamSchema, VDUSFormSchema, VDUSDatatableOptions}
diff --git a/src/utils/listPaginatedTools.ts b/src/utils/listPaginatedTools.ts
@@ -5,9 +5,9 @@ import {
   extractIntegerValue
 } from "./helpers";
 import isEqual from "lodash.isequal";
-import {GenericDictionnary} from "./VDUSTypes"
+import {GenericDictionnary, VDUSDatatableOptions, VDUSFormSchema} from "./VDUSTypes"
 
-function getDefaultValueForParam(param: string, schema?: GenericDictionnary): any {
+const getDefaultValueForParam = (param: string, schema?: VDUSFormSchema): any => {
   if (schema && schema[param]) {
     // if there is a defautl value we change the condition to is non equality
     if (schema[param].default) {
@@ -18,15 +18,15 @@ function getDefaultValueForParam(param: string, schema?: GenericDictionnary): an
     else if (schema[param].type === "boolean") {
       // Default for boolean is false
       return false;
-    } else if (["arrayInt", "arrayString"].includes(schema[param].type)) {
+    } else if (["arrayInt", "arrayString"].includes(schema[param].type as string)) {
       // Default for array is empty array or first element null or empty
       return [];
     }
   }
   return null;
 }
 
-function isValueDefault(value: any, param: string, schema?: GenericDictionnary): boolean {
+const isValueDefault = (value: any, param: string, schema?: VDUSFormSchema): boolean => {
   // Default is string
   let isValueDefault: boolean = value === "";
 
@@ -44,7 +44,7 @@ function isValueDefault(value: any, param: string, schema?: GenericDictionnary):
     else if (schema[param].type === "boolean") {
       // Default for boolean is false
       isValueDefault = value === false;
-    } else if (["arrayInt", "arrayString"].includes(schema[param].type)) {
+    } else if (["arrayInt", "arrayString"].includes(schema[param].type as string)) {
       // Default for array is empty array or first element null or empty
       isValueDefault =
         value.length === 0 || value[0] === null || value[0] === "";
@@ -61,7 +61,7 @@ function isValueDefault(value: any, param: string, schema?: GenericDictionnary):
   if localName is true it will no replace the param key with the real used for backend query
   if localName is false the name will be replaced by the correct one sended to backend
   */
-function generateQueryFromObject(object: GenericDictionnary, schema?: GenericDictionnary, localName = true): GenericDictionnary {
+const generateQueryFromObject = (object: GenericDictionnary, schema?: VDUSFormSchema, localName = true): GenericDictionnary => {
   const queryUrl: GenericDictionnary = {};
   for (const [key, value] of Object.entries(object)) {
     // We do not want to send a default value
@@ -73,15 +73,15 @@ function generateQueryFromObject(object: GenericDictionnary, schema?: GenericDic
     let queryKey = key;
     // But this can be overrided if name attribute is defined in the param schema
     if (!localName && schema && schema[key] && schema[key].name) {
-      queryKey = schema[key].name;
+      queryKey = (schema[key].name as string); // typescript error because .name can be undefined but if check it before
     }
 
     queryUrl[queryKey] = value;
   }
   return queryUrl;
 }
 
-function convertParamIfTypeInSchema(query: GenericDictionnary, param: string, schema?: GenericDictionnary, prefix = ""): any {
+const convertParamIfTypeInSchema = (query: GenericDictionnary, param: string, schema?: VDUSFormSchema, prefix = ""): any => {
   if (!schema || !schema[param] || !schema[param].type) {
     return query[prefix + param];
   }
@@ -104,22 +104,22 @@ function convertParamIfTypeInSchema(query: GenericDictionnary, param: string, sc
 /*
   Transform query parameter from vue router to two javascript objects representing the filtering form and the options
   */
-function readFormAndOptionsFromLocalQuery(
+const readFormAndOptionsFromLocalQuery = (
   query: GenericDictionnary,
   form: GenericDictionnary,
-  options: GenericDictionnary,
-  schema?: GenericDictionnary,
+  options: VDUSDatatableOptions,
+  schema?: VDUSFormSchema,
   removedParam: Array<string> = []
-): {newOptions: GenericDictionnary; newForm: GenericDictionnary} {
+): {newOptions: VDUSDatatableOptions; newForm: GenericDictionnary} => {
 
-  const newOptions: GenericDictionnary = {};
+  const newOptions: VDUSDatatableOptions = {};
   const newForm: GenericDictionnary = {};
   
   for (const param in query) {
     if (typeof form[param] !== "undefined") {
       newForm[param] = convertParamIfTypeInSchema(query, param, schema);
-    } else if (typeof options[param] !== "undefined") {
-      newOptions[param] = convertParamIfTypeInSchema(query, param, schema);
+    } else if (typeof (options as GenericDictionnary)[param] !== "undefined") {
+      (newOptions as GenericDictionnary)[param] = convertParamIfTypeInSchema(query, param, schema);
     }
   }
   // This allow to reset to default deleted param by other component
@@ -129,14 +129,14 @@ function readFormAndOptionsFromLocalQuery(
     }
   });
   removedParam.forEach(param => {
-    if (typeof options[param] !== "undefined") {
-      newOptions[param] = getDefaultValueForParam(param, schema);
+    if (typeof (options as GenericDictionnary)[param] !== "undefined") {
+      (newOptions as GenericDictionnary)[param] = getDefaultValueForParam(param, schema);
     }
   });
   return { newOptions, newForm };
 }
 
-function getRemovedKeyBetweenTwoObject(originalObject: GenericDictionnary, newObject: GenericDictionnary): Array<string> {
+const getRemovedKeyBetweenTwoObject = (originalObject: GenericDictionnary, newObject: GenericDictionnary): Array<string> => {
   const originalObjectKeys: Array<string> = Object.keys(originalObject);
   const newObjectKeys: Array<string> = Object.keys(newObject);
   return originalObjectKeys.filter(
