@bigbinary/neeto-commons-frontend 2.0.59 → 2.0.61

package/utils.d.ts

@@ -1,65 +1,189 @@
 import dayjs from "dayjs";
 import React from "react";
-
 export function resetAuthTokens(): void;
-
-export function withEventTargetValue(
-  func: (value: string) => void,
-  event: React.ChangeEventHandler<HTMLInputElement>
-): void;
-
-export function withEventTargetValue(
-  func: (value: string) => void
-): (event: React.ChangeEventHandler<HTMLInputElement>) => void;
-
+/**
+ *
+ * Curried: true
+ *
+ * It is a curried function that accepts a function as the first parameter and an
+ *
+ * event as the second, and executes the given function with event.target.value
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * const onChange = val => console.log(`Value = ${val}`);
+ * 
+ * <input onChange={withEventTargetValue(onChange)} />;
+ * 
+ * // For example, in this case when user types "1" in the input field, "Value = 1" will be printed in the console.
+ * @endexample
+*/
+export function withEventTargetValue(func: (value: string) => void, event: React.ChangeEventHandler<HTMLInputElement>): void;
+/**
+ *
+ * Curried: true
+ *
+ * It is a curried function that accepts a function as the first parameter and an
+ *
+ * event as the second, and executes the given function with event.target.value
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * const onChange = val => console.log(`Value = ${val}`);
+ * 
+ * <input onChange={withEventTargetValue(onChange)} />;
+ * 
+ * // For example, in this case when user types "1" in the input field, "Value = 1" will be printed in the console.
+ * @endexample
+*/
+export function withEventTargetValue(func: (value: string) => void): (event: React.ChangeEventHandler<HTMLInputElement>) => void;
+/**
+ *
+ * Curried: false
+ *
+ * This function returns the subdomain of the current URL.
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * // Let the current url be "https://spinkart.example.com".
+ * getSubdomain();
+ * 
+ * // output: spinkart
+ * @endexample
+*/
 export function getSubdomain(): string;
-
-export function simulateApiCall<T>(
-  result: T,
-  error?: any,
-  errorProbability?: number,
-  delayMs?: number
-): Promise<T>;
-
-export function copyToClipboard(
-  text: string,
-  configs?: { showToastr?: boolean; message?: string }
-): void;
-
+/**
+ *
+ * Curried: false
+ *
+ * Returns the specified hardcoded data after some delay for simulating an API
+ *
+ * call.
+ *
+ * This function will simulate an API call and retrieve the hardcoded success/error
+ *
+ * responses after some delay based on the given error probability. This function
+ *
+ * is helpful when we are building the frontend before the backend is ready.
+ *
+ * @example 
+ *
+ * simulateApiCall(hardCodedResponseData, hardCodedErrorResponse);
+ * @endexample
+*/
+export function simulateApiCall<T>(result: T, error?: any, errorProbability?: number, delayMs?: number): Promise<T>;
+/**
+ *
+ * Curried: false
+ *
+ * Copies the given string to clipboard and shows a success toaster message.
+ *
+ * This function accepts a string as an argument and copies it to the clipboard.
+ *
+ * Also, it accepts two optional arguments: a boolean flag to indicate whether a
+ *
+ * toaster should be shown and a message to be shown in the toaster. By default the
+ *
+ * show toaster flag is set to true and the toaster message is set to "Copied to
+ *
+ * clipboard!". You can override these defaults by passing the appropriate values
+ *
+ * to the function.
+ *
+ * @example 
+ *
+ * copyToClipboard("https://spinkart.example.com", {
+ *   showToastr: true,
+ *   message: "URL copied successfully!",
+ * });
+ * 
+ * // If the URL is copied to the clipboard, a toaster message will be shown with the message "URL copied successfully!"
+ * @endexample
+*/
+export function copyToClipboard(text: string, configs?: {
+  showToastr?: boolean;
+  message?: string;
+}): void;
+/**
+ *
+ * Curried: false
+ *
+ * Builds a URL by inflating route like template string (example:
+ *
+ * /products/:productId/variants/:id) using the given params. Any extra
+ *
+ * properties in the params will be attached as query parameters to the URL.
+ *
+ * @example 
+ *
+ * buildUrl("/products/:id", { id: "123" }); // output "/products/123"
+ * buildUrl("/products", { search: "abc" }); // output "/products?search=abc"
+ * buildUrl("/products/:productId/variants/:variantId/attributes", {
+ *   productId: "123",
+ *   variantId: "456",
+ *   search: "abc",
+ *   page: 1,
+ *   per_page: 10,
+ * }); // output "/products/123/variants/456/attributes?page=1&per_page=10&search=abc"
+ * @endexample
+*/
 export function buildUrl(route: string, params: object): string;
-
 type DateTimeType = string | number | dayjs.Dayjs | Date | null | undefined;
-
 export const timeFormat: {
   fromNow: (time: DateTimeType) => string;
   time: (time: DateTimeType) => string;
+  timeWithSeconds: (time: DateTimeType) => string;
   date: (time: DateTimeType) => string;
   dateWeek: (time: DateTimeType) => string;
   dateWeekWithoutYear: (time: DateTimeType) => string;
   dateTime: (time: DateTimeType) => string;
+  dateTimeWithSeconds: (time: DateTimeType) => string;
   dateWeekTime: (time: DateTimeType) => string;
   extended: (time: DateTimeType) => string;
 };
-
 export const dateFormat: typeof timeFormat;
-
-export function toLocale(
-  number: string | number,
-  options?: Intl.NumberFormatOptions
-): string;
-
+/**
+ *
+ * Curried: false
+ *
+ * Converts the given number to a locale string (converts to a comma separated
+ *
+ * string). It automatically identifies the locale using globalProps. If a valid
+ *
+ * value isn't present in globalProps, it will rely on the current browser's
+ *
+ * locale.
+ *
+ * The function also accepts options, which will be forwarded to
+ *
+ * Number.prototype.toLocaleString, which can be used for additional
+ *
+ * configurations like rounding, currency, units etc.
+ *
+ * @example 
+ *
+ * toLocale(1000000); // "1,000,000" when locale is "en-US"
+ * toLocale(1000000); // "10,00,000" when locale is "en-IN"
+ * toLocale(1000000.987, { maximumFractionDigits: 2 }); // "1,000,000.99"
+ * toLocale(1000000.987, {
+ *   currencyDisplay: "narrowSymbol",
+ *   style: "currency",
+ *   currency: "INR",
+ * }); // "₹1,000,000.99"
+ * @endexample
+*/
+export function toLocale(number: string | number, options?: Intl.NumberFormatOptions): string;
 type qsOptionsType = {
   comma?: boolean | undefined;
   delimiter?: string | RegExp | undefined;
   depth?: number | false | undefined;
-  decoder?:
-    | ((
-        str: string,
-        defaultDecoder: any,
-        charset: string,
-        type: "key" | "value"
-      ) => any)
-    | undefined;
+  decoder?: ((str: string, defaultDecoder: any, charset: string, type: "key" | "value") => any) | undefined;
   arrayLimit?: number | undefined;
   parseArrays?: boolean | undefined;
   allowDots?: boolean | undefined;
@@ -72,15 +196,108 @@ type qsOptionsType = {
   charsetSentinel?: boolean | undefined;
   interpretNumericEntities?: boolean | undefined;
 };
-
-type QueryParamsType = { [key: string]: any };
-
+type QueryParamsType = {
+  [key: string]: any;
+};
+/**
+ *
+ * Curried: false
+ *
+ * This function returns all the query parameters of the current URL as an object.
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * // Let the current url be "https://example.com?search=something&sort=date".
+ * getQueryParams();
+ * 
+ * // output: { search: "something", sort: "date" }
+ * @endexample
+*/
 export function getQueryParams(options?: qsOptionsType): QueryParamsType;
-
+/**
+ *
+ * Curried: false
+ *
+ * This function joins the given strings with hyphen.
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * joinHyphenCase("hello", "world"); // output: "hello-world"
+ * @endexample
+*/
 export function joinHyphenCase(...args: string[]): string;
-
+/**
+ *
+ * Curried: false
+ *
+ * Creates a debounced function that will execute the given function after the
+ *
+ * stated wait time in milliseconds has elapsed since the last time it was invoked.
+ *
+ * It accepts the function to be debounced as the first argument, the delay in
+ *
+ * milliseconds as the second argument.
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * const searchForProducts = debounce(async key => {
+ *   // this function will be triggered once after user stops typing for 300ms
+ *   const products = await productsApi.fetch(key);
+ *   // do something with the products
+ * }, 300);
+ * <input onChange={e => searchForProducts(e.target.value)} />;
+ * @endexample
+*/
 export function debounce<F extends Function>(func: F, delay?: number): F;
-
+/**
+ *
+ * Curried: false
+ *
+ * This function will return true if the current user has the given permission.
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * hasPermission("user.view_settings");
+ * @endexample
+*/
 export function hasPermission(permission: string): boolean;
+/**
+ *
+ * Curried: false
+ *
+ * This function will return true if the current user has any of the given
+ *
+ * permissions.
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * hasAnyPermission("user.view_settings", "user.edit_settings");
+ * @endexample
+*/
 export function hasAnyPermission(...permissions: string[]): boolean;
-export function hasAllPermissions(...permissions: string[]): boolean;
+/**
+ *
+ * Curried: false
+ *
+ * This function will return true if the current user has all of the given
+ *
+ * permissions.
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * hasAllPermissions("user.view_settings", "user.edit_settings");
+ * @endexample
+*/
+export function hasAllPermissions(...permissions: string[]): boolean;