xenopomp-essentials 0.3.2 → 0.3.4-hotfix.0

package/index.d.mts

@@ -0,0 +1,613 @@
+import { ElementType, ComponentProps, FC, ReactNode, Dispatch, SetStateAction } from 'react';
+import { Jsonifiable } from 'type-fest';
+import * as transliteration from 'transliteration';
+
+/**
+ * Matches any object but not arrays, class instances etc.
+ * @since 0.0.1
+ */
+type AnyObject = Record<PropertyKey, unknown>;
+
+/**
+ * This type stands for empty object type.
+ *
+ * @since 0.0.1
+ * @example
+ * const message: EmptyObject = { type: string; }; // Will cause error.
+ */
+type EmptyObject = Record<PropertyKey, never>;
+
+/**
+ * Simple alias for creating function types. You can use it for type guards
+ * as representation of any function, also you can create cleaner type declarations
+ * for functions.
+ *
+ * @since 0.0.1
+ * @example
+ * type MyFn = Fn<[a: string, b: string], string>;
+ */
+type Fn<Args extends any[] = any[], Res = unknown> = (...args: Args) => Res;
+
+type ParamObj<P extends string> = Record<P, string>;
+/**
+ * Represents Next.js routing params.
+ * @since 0.0.1
+ */
+interface NextParams<P extends string> {
+    params: ParamObj<P>;
+}
+/**
+ * Represents Next.js routing search params.
+ * @since 0.0.1
+ */
+interface NextSearchParams<P extends string> {
+    searchParams: ParamObj<P>;
+}
+/**
+ * This type describes Next error page params.
+ * @since 0.0.1
+ */
+interface NextErrorParams<E extends Error = any> {
+    error: E;
+    reset: () => void;
+}
+
+/**
+ * This type wraps ComponentProps<A> to your FC.
+ *
+ * - __A__  - element type
+ * - __P__  - wrapping props
+ * - __Ex__ - excluded component props (for example, if you do not want to include 'children' prop in component)
+ *
+ * @since 0.0.1
+ *
+ * @example
+ * type VariableComponentPropsWithChildren = ComponentProps<VariableFC<'div'>>;
+ * type VariableComponentPropsWithoutChildren = ComponentProps<VariableFC<'div', {}, 'children'>>;
+ *
+ * @example
+ * // With children
+ * const VariableComponent: VariableFC<'section', { variant?: 'default' }> = ({ variant, ...props }) => {
+ *   return <section {...props}></section>
+ * }
+ *
+ * @example
+ * // Without children
+ * const VariableComponent: VariableFC<'section', { variant?: 'default' }, 'children'> = ({ variant, ...props }) => {
+ *   return (
+ *    <section {...props}>
+ *      <div>Insert your own children</div>
+ *    </section>
+ *   );
+ * }
+ */
+type VariableFC<A extends ElementType, P = unknown, Ex extends keyof ComponentProps<A> | undefined = undefined> = FC<P & WeakOmit<ComponentProps<A>, Ex>>;
+/**
+ * Works similar to {@link VariableFC}, but return type is Promise<ReactNode>;
+ * @since 0.0.1
+ */
+type AsyncVariableFC<A extends ElementType, P = unknown, Ex extends keyof ComponentProps<A> | undefined = undefined> = AsyncFC<P & WeakOmit<ComponentProps<A>, Ex>>;
+
+/**
+ * Same as **FC** (or FunctionalComponent), but it returns Promise.
+ *
+ * @since 0.0.1
+ * @example
+ * const Header: AsyncFC<HeaderProps> = async ({}) => {
+ *   // Do async stuff here...
+ *
+ *   return <div></div>;
+ * };
+ */
+type AsyncFC<T = unknown> = ReplaceReturnType<FC<T>, Promise<ReactNode>>;
+
+/**
+ * Type of set state function from useState.
+ *
+ * @since 0.0.1
+ * @example
+ * // typeof setState => SetState<string>
+ * const [state, setState] = useState<string>('example');
+ */
+type SetState<TType> = Dispatch<SetStateAction<TType>>;
+
+/**
+ * This type allows you to make children that can be function.
+ *
+ * @since 0.0.1
+ * @example
+ * type Child = FunctionalChildren<[options: string]>;
+ * // ReactNode | ((options: string) => ReactNode)
+ */
+type FunctionalChildren<Args extends any[]> = ReactNode | ((...args: Args) => ReactNode);
+
+/**
+ * @deprecated use {@link FCProps} instead.
+ */
+type FcProps<Comp> = FCProps<Comp>;
+/**
+ * Extracts type of props from FC type.
+ *
+ * @since 0.0.1
+ * @example
+ * type Props = FcProps<FC<{ align?: boolean }>>;
+ * //   ^? { align?: boolean }
+ *
+ * type VariableProps = FcProps<VariableFC<'button', { notAlign?: boolean }>>;
+ * //   ^? {notAlign?: boolean} & Omit<ClassAttributes<HTMLButtonElement> & React.ButtonHTMLAttributes<HTMLButtonElement>, undefined>
+ */
+type FCProps<Comp> = Comp extends FC<infer Props> ? Props : never;
+
+/**
+ * Matches any proper React component.
+ */
+type AnyFC = FC<unknown>;
+
+/**
+ * Type that represents data-{attr} keys.
+ */
+type Attribute = `data-${string}`;
+/**
+ * Matches any proper data-{attr} keys.
+ */
+type DataAttributeShape = Record<Attribute, any>;
+/**
+ * Represents React`s data-{attr} properties for components.
+ *
+ * @example
+ * type AdditionalAttributes = DataAttributes<{ 'data-disabled': boolean }>;
+ *
+ * const attrs: AdditionalAttributes = {
+ *   'data-disabled': false, // this attr is required
+ * };
+ */
+type DataAttributes<Shape extends DataAttributeShape> = Shape;
+
+type VariableProps<A extends ElementType, P = unknown, Ex extends keyof ComponentProps<A> | undefined = undefined> = FCProps<VariableFC<A, P, Ex>>;
+
+/**
+ * Make any async func synchronous.
+ *
+ * Return never, if __Func__ is not a function, actually.
+ *
+ * @since 0.0.1
+ * @example
+ * type NormalFunc = Synchronous<(one: string, two: number) => void>; // (one: string, two: number) => void
+ * type AsyncFunc = Synchronous<(one: string, two: number) => Promise<void>>; // (one: string, two: number) => void
+ * type NotAFunc = Synchronous<'sus'>; // never
+ */
+type Synchronous<Func> = Func extends Fn ? Func extends (...args: any[]) => Promise<infer Result> ? ReplaceReturnType<Func, Result> : Func : never;
+
+/**
+ * Removes readonly from type.
+ * @since 0.0.1
+ */
+type Writeable<T> = {
+    -readonly [P in keyof T]: T[P];
+};
+/**
+ * @deprecated Use {@link WriteableDeep} instead.
+ */
+type DeepWriteable<T> = WriteableDeep<T>;
+/**
+ * Removes readonly from type deeply.
+ * @since 0.0.1
+ */
+type WriteableDeep<T> = {
+    -readonly [P in keyof T]: DeepWriteable<T[P]>;
+};
+
+/**
+ * Checks if type **T** matches type **M**.
+ *
+ * @since 0.0.1
+ *
+ * @example Not matching
+ * type ViewStyles = {
+ *   paddingHorizontal: number
+ * }
+ *
+ * type Styles = MatchType<{}, ViewStyles>; // TSERROR
+ *
+ * @example Matching
+ * type ViewStyles = {
+ *   paddingHorizontal: number;
+ * };
+ *
+ * // No error
+ * type Styles = MatchType<
+ *   {
+ *     paddingHorizontal: number;
+ *   },
+ *   ViewStyles
+ * >;
+ */
+type MatchType<T extends M, M> = T extends M ? T : never;
+
+/**
+ * This type gets type of array`s item.
+ *
+ * @since 0.0.1
+ * @example
+ * type Super = ArrayType<string[]>; // string
+ *
+ * type Good = ArrayType<(string|number)[]>; // string | number
+ */
+type ArrayType<T> = T extends Array<infer A> ? A : never;
+type ArrayItemType<T> = ArrayType<T>;
+
+/**
+ * Get return type of function that returns Promise ((...args: any) => Promise<any>).
+ *
+ * @since 0.0.1
+ * @example
+ * const doSomething = async (): Promise<string|number> => {
+ *   return 'result';
+ * }
+ *
+ * type Something = PromiseReturnType<typeof doSomething>;
+ * // string|number
+ */
+type AsyncReturnType<F extends (...args: any[]) => Promise<any>> = Awaited<ReturnType<F>>;
+
+/**
+ * @deprecated Use {@link InjectDeep} instead.
+ */
+type DeepInject<T, I extends AnyObject> = InjectDeep<T, I>;
+/**
+ * Recursively add some type inside all keys of target type.
+ *
+ * @since 0.0.1
+ * @example
+ * type Sups = DeepInject<{ supa: { sups: number } }, { _ignore: boolean }>;
+ * const asp: Sups = { supa: { sups: 1, _ignore: false }, _ignore: false };
+ */
+type InjectDeep<T, I extends AnyObject> = T extends object ? {
+    [K in keyof T]: T[K] extends object ? T[K] & I & DeepInject<T[K], I> : T[K];
+} & I : T;
+
+/**
+ * Removes undefined from union type.
+ * @since 0.0.1
+ */
+type Defined<T> = Exclude<T, undefined>;
+
+/**
+ * Return never if type does not match JSON schema.
+ *
+ * @since 0.0.1
+ * @example
+ * type Schema = Jsonish<{ sus: string; am: string; }>; // OK
+ * type AlterSchema = Jsonish<{ sus: string; am: () => {}; }>; // Causes error
+ */
+type Jsonish<T extends Jsonifiable> = T extends Jsonifiable ? T : never;
+
+/**
+ * Modifies K (Key) in T (Type), replace it with R (Replacement).
+ *
+ * @since 0.0.1
+ * @example
+ * type ExcludedStore = Modify<IStore, 'appSettings', { appName: 'Simple name' }>; // Key in IStore has been replaced with new type.
+ */
+type Modify<T, K extends keyof T, R> = Omit<T, K> & {
+    [Key in K]: R;
+};
+
+/**
+ * Make union type of T and null.
+ * @since 0.0.1
+ */
+type Nullable<T> = T | null;
+
+/**
+ * Get typeof key of Record.
+ *
+ * @since 0.0.1
+ * @example
+ * type Key = RecordKey<Record<string, number>>; // string
+ */
+type RecordKey<R extends Record<any, any>> = R extends Record<infer K, any> ? K : never;
+
+/**
+ * Get typeof value of Record.
+ *
+ * @since 0.0.1
+ * @example
+ * type Value = RecordValue<Record<string, number>>; // number
+ */
+type RecordValue<R extends Record<any, any>> = R extends Record<any, infer V> ? V : never;
+
+/**
+ * This type replace return type of function with other type.
+ *
+ * @since 0.0.1
+ * @example
+ * type StringFC<T = {}> = ReplaceReturnType<FC<T>, string>;
+ */
+type ReplaceReturnType<TFn, TR> = TFn extends (...a: infer A) => any ? (...a: A) => TR : never;
+
+/**
+ * Works as Partial, but makes only specified keys partial.
+ *
+ * @since 0.0.1
+ * @example
+ * type Super = SelectivePartial<{
+ *  name: string;
+ *  address: {
+ *    street: string;
+ *    number: number
+ *  }
+ * }, 'address'>;
+ *
+ * // Property 'address' will be partial.
+ */
+type SelectivePartial<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+/**
+ * Makes type union of type T and undefined
+ * @since 0.0.1
+ */
+type Undefinable<T> = T | undefined;
+
+/**
+ * The strict version of Omit. Allows to remove only
+ * keys that are presented in T type.
+ *
+ * @since 0.0.1
+ * @example
+ * type Tree = {
+ *   height: number;
+ *   age: number;
+ *   name: string;
+ * };
+ *
+ * // TS2344: Type 'weight' does not satisfy the constraint keyof Tree
+ * type TreeInfo = StrictOmit<Tree, 'weight'>;
+ *
+ * // Works just like usual Omit
+ * type CorrectTreeInfo = StrictOmit<Tree, 'name'>;
+ */
+type StrictOmit<T, K extends keyof T> = Omit<T, K>;
+
+/**
+ * Extracts first type from two generics. Is helper type for {@link OneOf} type.
+ * @since 0.0.1
+ */
+type OnlyFirst<F, S> = F & {
+    [Key in keyof Omit<S, keyof F>]?: never;
+};
+/**
+ * Chooses only one of types array.
+ *
+ * @since 0.0.1
+ * @example
+ * type Email = {
+ *   person: string;
+ *   content: string;
+ *   address: string;
+ * };
+ *
+ * type Mail = {
+ *   person: string;
+ *   content: string;
+ *   postCode: number;
+ * };
+ *
+ * type Letter = OneOf<[Email, Mail]>;
+ *
+ * // Will error, cause address is not assignable to type never.
+ * const email: Letter = {
+ *   person: 'person',
+ *   content: 'content',
+ *   address: '',
+ *   postCode: 12,
+ * };
+ */
+type OneOf<TypesArray extends any[], Res = never, AllProperties = MergeTypes<TypesArray>> = TypesArray extends [infer Head, ...infer Rem] ? OneOf<Rem, Res | OnlyFirst<Head, AllProperties>, AllProperties> : Res;
+
+/**
+ * Merge array of types to one type.
+ * @since 0.0.1
+ */
+type MergeTypes<TypesArray extends any[], Res = EmptyObject> = TypesArray extends [infer Head, ...infer Rem] ? MergeTypes<Rem, Res & Head> : Res;
+
+/**
+ * Allows to pass undefined as Omit`s generic. Weakly omits type.
+ *
+ * @since 0.0.1
+ * @example
+ * // Will not omit any keys
+ * type Lib = WeakOmit<{ bookCount: number; date: string }, undefined>;
+ *
+ * // Will omit
+ * type LibStrong = WeakOmit<{ bookCount: number; date: string }, 'date'>;
+ */
+type WeakOmit<Obj extends AnyObject, Keys extends keyof Obj | undefined = undefined> = Keys extends keyof Obj ? Omit<Obj, Keys> : Obj;
+
+/**
+ * Makes types don`t merging in unions.
+ *
+ * @since 0.0.1
+ * @example
+ * type Languages = 'TypeScript' | 'JavaScript' | Lenient<string>;
+ * //     ^? "TypeScript" | "JavaScript" | string
+ */
+type Lenient<T> = T & {};
+/**
+ * This type allows any string, but also saves compiler`s autocomplete
+ * feature.
+ *
+ * @since 0.0.1
+ * @example
+ * type Languages = 'TypeScript' | 'JavaScript';
+ *
+ * function handleLanguage(lang: LenientAutocomplete<Languages>) {
+ *   //                      ^? string (but autocomplete feature is still here)
+ *   console.log(lang);
+ * }
+ */
+type LenientAutocomplete<T extends string> = T | Lenient<string>;
+
+/**
+ * Presents plain object in pretty form.
+ */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Presents object in pretty form recursively.
+ */
+type PrettifyDeep<T> = {
+    [K in keyof T]: T[K] extends AnyObject ? Prettify<PrettifyDeep<T[K]>> : T[K];
+};
+
+/**
+ * Creates pipelines of functions that will be executed only
+ * when you will call whole pipeline.
+ *
+ * @since 0.0.1
+ *
+ * @param fn
+ *
+ * @example
+ * const stringToDateAndTime = pipe(Date.parse)
+ *   .pipe(n => new Date(n))
+ *   .pipe(d => d.toDateString())
+ *   .pipe(s => s.split('T'))
+ *   .pipe(([date, time]) => ({ date, time }));
+ *
+ * const res = stringToDateAndTime('Jan 1, 2024');
+ * //     ^? {   date: string | undefined; time: string | undefined }
+ *
+ * @see https://youtu.be/bH61wRMqp-o?si=D-2Az-_dUFBxG9HG&t=429
+ */
+declare function pipe<A, B>(fn: (a: A) => B): {
+    (a: A): B;
+    pipe<C>(fn2: (b: B) => C): {
+        (a: A): C;
+        pipe<C_1>(fn2: (b: C) => C_1): {
+            (a: A): C_1;
+            pipe<C_2>(fn2: (b: C_1) => C_2): {
+                (a: A): C_2;
+                pipe<C_3>(fn2: (b: C_2) => C_3): {
+                    (a: A): C_3;
+                    pipe<C_4>(fn2: (b: C_3) => C_4): {
+                        (a: A): C_4;
+                        pipe<C_5>(fn2: (b: C_4) => C_5): {
+                            (a: A): C_5;
+                            pipe<C_6>(fn2: (b: C_5) => C_6): {
+                                (a: A): C_6;
+                                pipe<C_7>(fn2: (b: C_6) => C_7): {
+                                    (a: A): C_7;
+                                    pipe<C_8>(fn2: (b: C_7) => C_8): {
+                                        (a: A): C_8;
+                                        pipe<C_9>(fn2: (b: C_8) => C_9): {
+                                            (a: A): C_9;
+                                            pipe<C_10>(fn2: (b: C_9) => C_10): /*elided*/ any;
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
+
+/**
+ * Capitalizes string (makes first letter uppercase).
+ * @since 0.0.1
+ */
+declare function capitalize<T extends string>(str: T): Capitalize<T>;
+/**
+ * Un-capitalizes string (makes first letter lowercase).
+ * @since 0.0.1
+ */
+declare function uncapitalize<T extends string>(str: T): Uncapitalize<T>;
+
+type Preid = 'alpha' | 'beta' | 'rc';
+interface VersionData {
+    /** Version in format: (__``x.x.x``__-beta.x) */
+    version: Nullable<string>;
+    /** Version preid. (x.x.x-__``beta``__.x) */
+    preid?: LenientAutocomplete<Preid>;
+    /** Number of pre-release. (x.x.x-beta.__``12``__) */
+    prerelease?: string;
+}
+/**
+ * Parses version with preid.
+ *
+ * @since 0.0.1
+ *
+ * @param raw
+ *
+ * @example
+ * const { version, preid } = parseVersion('0.0.0-beta.0');
+ * // version = '0.0.0'
+ * // preid = 'beta'
+ */
+declare const parseVersion: (raw: string) => VersionData;
+
+/**
+ * Transforms any given string to transliterated variant.
+ *
+ * @since 0.0.1
+ */
+declare const transliterate: transliteration.TransliterateFunction;
+
+/**
+ * Constraints number with min and max values.
+ *
+ * @example Min value
+ * console.log({
+ *   ogNum: 1, // 1
+ *   minmax: minmax(1, [2, undefined]), // 2
+ * });
+ *
+ * @example Max value
+ * console.log({
+ *   ogNum: 1001, // 1001
+ *   minmax: minmax(1001, [undefined, 900]), // 900
+ * });
+ *
+ * @example Min and max value
+ * console.log({
+ *   ogNum: 600, // 600
+ *   minmax: minmax(1001, [2, 900]), // 600
+ * });
+ */
+declare const minmax: (num: number, [min, max]: [min: number | undefined, max: number | undefined]) => number;
+
+/**
+ * Creates properly type object with jsxDotNotation.
+ *
+ * @param comp
+ * @param rest
+ *
+ * @example
+ * const FlexComp: FC<PropsWithChildren> = ({ children }) => <div>{children}</div>;
+ * const FlexRow: FC<PropsWithChildren & { short?: boolean }> = ({ children }) => (
+ *   <div>{children}</div>
+ * );
+ * const FlexCol: FC<PropsWithChildren> = ({ children }) => <div>{children}</div>;
+ *
+ * const Flex = jsxDotNotation(FlexComp, {
+ *   Row: FlexRow,
+ *   Col: FlexCol,
+ * });
+ *
+ * const Am = () => {
+ *   return (
+ *     <Flex>
+ *       <Flex.Row short>
+ *         <Flex.Col></Flex.Col>
+ *       </Flex.Row>
+ *     </Flex>
+ *   );
+ * };
+ */
+declare function jsxDotNotation<Props = EmptyObject, Rest extends Record<string, FC<any>> = EmptyObject>(comp: FC<Props>, rest: Rest): FC<Props> & Rest;
+
+export { type AnyFC, type AnyObject, type ArrayItemType, type ArrayType, type AsyncFC, type AsyncReturnType, type AsyncVariableFC, type DataAttributes, type Defined, type EmptyObject, type FCProps, type FcProps, type Fn, type FunctionalChildren, type InjectDeep, type Jsonish, type Lenient, type LenientAutocomplete, type MatchType, type MergeTypes, type Modify, type NextErrorParams, type NextParams, type NextSearchParams, type Nullable, type OneOf, type OnlyFirst, type Preid, type Prettify, type PrettifyDeep, type RecordKey, type RecordValue, type ReplaceReturnType, type SelectivePartial, type SetState, type StrictOmit, type Synchronous, type Undefinable, type VariableFC, type VariableProps, type VersionData, type WeakOmit, type Writeable, type WriteableDeep, capitalize, jsxDotNotation, minmax, parseVersion, pipe, transliterate, uncapitalize };