xenopomp-essentials 0.3.0 → 0.3.2

package/src/types/react/VariableProps.ts

@@ -0,0 +1,9 @@
+import type { ComponentProps, ElementType } from 'react';
+
+import type { FCProps, VariableFC } from '@/types';
+
+export type VariableProps<
+  A extends ElementType,
+  P = unknown,
+  Ex extends keyof ComponentProps<A> | undefined = undefined,
+> = FCProps<VariableFC<A, P, Ex>>;

package/src/types/react/index.ts

@@ -0,0 +1,8 @@
+export * from './VariableFC';
+export * from './AsyncFC';
+export * from './SetState';
+export * from './FunctionalChildren';
+export * from './FCProps';
+export * from './AnyFc';
+export * from './DataAttributes';
+export * from './VariableProps';

package/src/types/utilities/ArrayType.ts

@@ -0,0 +1,12 @@
+/**
+ * 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
+ */
+export type ArrayType<T> = T extends Array<infer A> ? A : never;
+
+export type ArrayItemType<T> = ArrayType<T>;

package/src/types/utilities/AsyncReturnType.ts

@@ -0,0 +1,14 @@
+/**
+ * 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
+ */
+export type AsyncReturnType<F extends (...args: any[]) => Promise<any>> =
+  Awaited<ReturnType<F>>;

package/src/types/utilities/DeepInject.ts

@@ -0,0 +1,22 @@
+import type { AnyObject } from '@/types';
+
+/**
+ * @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 };
+ */
+export 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;

package/src/types/utilities/Defined.ts

@@ -0,0 +1,5 @@
+/**
+ * Removes undefined from union type.
+ * @since 0.0.1
+ */
+export type Defined<T> = Exclude<T, undefined>;

package/src/types/utilities/Jsonish.ts

@@ -0,0 +1,11 @@
+import type { Jsonifiable } from 'type-fest';
+
+/**
+ * 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
+ */
+export type Jsonish<T extends Jsonifiable> = T extends Jsonifiable ? T : never;

package/src/types/utilities/LenientAutocomplete.ts

@@ -0,0 +1,24 @@
+/**
+ * Makes types don`t merging in unions.
+ *
+ * @since 0.0.1
+ * @example
+ * type Languages = 'TypeScript' | 'JavaScript' | Lenient<string>;
+ * //     ^? "TypeScript" | "JavaScript" | string
+ */
+export 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);
+ * }
+ */
+export type LenientAutocomplete<T extends string> = T | Lenient<string>;

package/src/types/utilities/MatchType.ts

@@ -0,0 +1,26 @@
+/**
+ * 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
+ * >;
+ */
+export type MatchType<T extends M, M> = T extends M ? T : never;

package/src/types/utilities/MergeTypes.ts

@@ -0,0 +1,12 @@
+import type { EmptyObject } from '@/types';
+
+/**
+ * Merge array of types to one type.
+ * @since 0.0.1
+ */
+export type MergeTypes<
+  TypesArray extends any[],
+  Res = EmptyObject,
+> = TypesArray extends [infer Head, ...infer Rem]
+  ? MergeTypes<Rem, Res & Head>
+  : Res;

package/src/types/utilities/Modify.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+export type Modify<T, K extends keyof T, R> = Omit<T, K> & {
+  [Key in K]: R;
+};

package/src/types/utilities/Nullable.ts

@@ -0,0 +1,5 @@
+/**
+ * Make union type of T and null.
+ * @since 0.0.1
+ */
+export type Nullable<T> = T | null;

package/src/types/utilities/OneOf.ts

@@ -0,0 +1,42 @@
+import type { MergeTypes } from '@/types';
+
+/**
+ * Extracts first type from two generics. Is helper type for {@link OneOf} type.
+ * @since 0.0.1
+ */
+export 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,
+ * };
+ */
+export type OneOf<
+  TypesArray extends any[],
+  Res = never,
+  AllProperties = MergeTypes<TypesArray>,
+> = TypesArray extends [infer Head, ...infer Rem]
+  ? OneOf<Rem, Res | OnlyFirst<Head, AllProperties>, AllProperties>
+  : Res;

package/src/types/utilities/Prettify.ts

@@ -0,0 +1,15 @@
+import type { AnyObject } from '@/types';
+
+/**
+ * Presents plain object in pretty form.
+ */
+export type Prettify<T> = {
+  [K in keyof T]: T[K];
+} & {};
+
+/**
+ * Presents object in pretty form recursively.
+ */
+export type PrettifyDeep<T> = {
+  [K in keyof T]: T[K] extends AnyObject ? Prettify<PrettifyDeep<T[K]>> : T[K];
+};

package/src/types/utilities/RecordKey.ts

@@ -0,0 +1,9 @@
+/**
+ * Get typeof key of Record.
+ *
+ * @since 0.0.1
+ * @example
+ * type Key = RecordKey<Record<string, number>>; // string
+ */
+export type RecordKey<R extends Record<any, any>> =
+  R extends Record<infer K, any> ? K : never;

package/src/types/utilities/RecordValue.ts

@@ -0,0 +1,9 @@
+/**
+ * Get typeof value of Record.
+ *
+ * @since 0.0.1
+ * @example
+ * type Value = RecordValue<Record<string, number>>; // number
+ */
+export type RecordValue<R extends Record<any, any>> =
+  R extends Record<any, infer V> ? V : never;

package/src/types/utilities/ReplaceReturnType.ts

@@ -0,0 +1,10 @@
+/**
+ * This type replace return type of function with other type.
+ *
+ * @since 0.0.1
+ * @example
+ * type StringFC<T = {}> = ReplaceReturnType<FC<T>, string>;
+ */
+export type ReplaceReturnType<TFn, TR> = TFn extends (...a: infer A) => any
+  ? (...a: A) => TR
+  : never;

package/src/types/utilities/SelectivePartial.ts

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+export type SelectivePartial<T, K extends keyof T> = Omit<T, K> &
+  Partial<Pick<T, K>>;

package/src/types/utilities/StrictOmit.ts

@@ -0,0 +1,19 @@
+/**
+ * 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'>;
+ */
+export type StrictOmit<T, K extends keyof T> = Omit<T, K>;

package/src/types/utilities/Synchronous.ts

@@ -0,0 +1,18 @@
+import type { Fn, ReplaceReturnType } from '@/types';
+
+/**
+ * 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
+ */
+export type Synchronous<Func> = Func extends Fn
+  ? Func extends (...args: any[]) => Promise<infer Result>
+    ? ReplaceReturnType<Func, Result>
+    : Func
+  : never;

package/src/types/utilities/Undefinable.ts

@@ -0,0 +1,5 @@
+/**
+ * Makes type union of type T and undefined
+ * @since 0.0.1
+ */
+export type Undefinable<T> = T | undefined;

package/src/types/utilities/WeakOmit.ts

@@ -0,0 +1,17 @@
+import type { AnyObject } from '@/types';
+
+/**
+ * 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'>;
+ */
+export type WeakOmit<
+  Obj extends AnyObject,
+  Keys extends keyof Obj | undefined = undefined,
+> = Keys extends keyof Obj ? Omit<Obj, Keys> : Obj;

package/src/types/utilities/Writeable.ts

@@ -0,0 +1,18 @@
+/**
+ * Removes readonly from type.
+ * @since 0.0.1
+ */
+export 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
+ */
+export type WriteableDeep<T> = {
+  -readonly [P in keyof T]: DeepWriteable<T[P]>;
+};

package/src/types/utilities/index.ts

@@ -0,0 +1,24 @@
+export * from './Synchronous';
+export * from './Writeable';
+export * from './MatchType';
+export * from './ArrayType';
+export * from './AsyncReturnType';
+export * from './DeepInject';
+export * from './Defined';
+export * from './Jsonish';
+export * from './Modify';
+export * from './Nullable';
+export * from './RecordKey';
+export * from './RecordValue';
+export * from './ReplaceReturnType';
+export * from './SelectivePartial';
+export * from './Undefinable';
+export * from './StrictOmit';
+
+export * from './OneOf';
+
+export * from './MergeTypes';
+
+export * from './WeakOmit';
+export * from './LenientAutocomplete';
+export * from './Prettify';

package/src/utils/capitalize.ts

@@ -0,0 +1,15 @@
+/**
+ * Capitalizes string (makes first letter uppercase).
+ * @since 0.0.1
+ */
+export function capitalize<T extends string>(str: T): Capitalize<T> {
+  return (str.charAt(0).toUpperCase() + str.slice(1)) as Capitalize<T>;
+}
+
+/**
+ * Un-capitalizes string (makes first letter lowercase).
+ * @since 0.0.1
+ */
+export function uncapitalize<T extends string>(str: T): Uncapitalize<T> {
+  return (str.charAt(0).toLowerCase() + str.slice(1)) as Uncapitalize<T>;
+}

package/src/utils/index.ts

@@ -0,0 +1,7 @@
+export * from './pipe';
+export * from './capitalize';
+
+export * from './parseVersion';
+export * from './transliterate';
+
+export * from './minmax';

package/src/utils/minmax.ts

@@ -0,0 +1,35 @@
+/**
+ * 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
+ * });
+ */
+export const minmax = (
+  num: number,
+  [min, max]: [min: number | undefined, max: number | undefined],
+) => {
+  if (!!min && num <= min) {
+    return min;
+  }
+
+  if (!!max && num >= max) {
+    return max;
+  }
+
+  return num;
+};

package/src/utils/parseVersion.ts

@@ -0,0 +1,42 @@
+import type { LenientAutocomplete, Nullable } from '@/types';
+
+export type Preid = 'alpha' | 'beta' | 'rc';
+
+export 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'
+ */
+export const parseVersion = (raw: string): VersionData => {
+  /** Parsed version. */
+  // eslint-disable-next-line regexp/no-useless-flag,regexp/no-unused-capturing-group
+  const version = raw.match(/(\d\.){2}\d/gi)?.at(0) || null;
+  // eslint-disable-next-line regexp/no-useless-flag
+  const preid = raw.match(/(?<=-)\w+(?=\.\d)/gi)?.at(0);
+  // eslint-disable-next-line regexp/no-useless-flag,regexp/no-unused-capturing-group
+  const prerelease = raw.match(/(?<=((\d\.){2}\d-\w+\.))\d+/gi)?.at(0);
+
+  return {
+    version,
+    preid,
+    prerelease,
+  };
+};

package/src/utils/pipe.ts

@@ -0,0 +1,29 @@
+/**
+ * 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
+ */
+export function pipe<A, B>(fn: (a: A) => B) {
+  function run(a: A) {
+    return fn(a);
+  }
+
+  run.pipe = <C>(fn2: (b: B) => C) => pipe((a: A) => fn2(fn(a)));
+
+  return run;
+}

package/src/utils/transliterate.ts

@@ -0,0 +1,8 @@
+import { transliterate as t } from 'transliteration';
+
+/**
+ * Transforms any given string to transliterated variant.
+ *
+ * @since 0.0.1
+ */
+export const transliterate = t;

package/tsconfig.json

@@ -0,0 +1,43 @@
+{
+  "compilerOptions": {
+    /* Next default options. */
+    "target": "es5",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "allowImportingTsExtensions": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    // "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    // "incremental": true,
+//    "plugins": [
+//      {
+//        "name": "next"
+//      }
+//    ],
+    "paths": {
+      "@/*": ["./src/*"],
+      "@test/*": ["./__tests__/*"]
+    },
+
+    /* Make compiler more strict. */
+    "noImplicitAny": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "strictNullChecks": true
+  },
+  "include": [
+    "next-env.d.ts",
+    ".config/declarations/vitest.d.ts", ".config/declarations/*.d.ts",
+    "**/*.ts", "**/*.tsx",
+    ".next/types/**/*.ts",
+    "./src"
+  ],
+  "exclude": ["node_modules"]
+}

package/cli-tools/index.d.mts

@@ -1,60 +0,0 @@
-/**
- * Fluent interface for creating paths of application.
- *
- * @since 0.0.1
- *
- * @example
- * import { PathBuilder } from 'xenopomp-essentials/cli-tools';
- *
- * const builder = new PathBuilder();
- *
- * const res = builder
- *  .appSource()
- *  .cd('./dist/src')
- *  .file('.prettierrc')
- *  .build();
- *
- *  console.log(res); //? C:/Projects/example/node_modules/xenopomp-essentials/dist/src/.prettierrc
- */
-declare class PathBuilder {
-    private paths;
-    private pushPaths;
-    /**
-     * Pushes any custom paths to builder.
-     * @since 0.0.1
-     * @param paths
-     */
-    cd(...paths: string[]): PathBuilder;
-    /**
-     * Pushes filename to paths.
-     * @since 0.0.1
-     * @param fileName
-     */
-    file<T extends `${string}.${string}`>(fileName: T): PathBuilder;
-    /**
-     * Pushes path to compiled app directory.
-     * Is useful for cli tools that have to access files inside their bundles.
-     *
-     * It probably may take no effect (if import.meta is not available in a scope).
-     * If it is, will push cwd.
-     *
-     * @since 0.0.1
-     */
-    appSource(): PathBuilder;
-    /**
-     * Gets path of directory where script is running. In cli tools it access
-     * path, where cli tool was started.
-     * @since 0.0.1
-     */
-    cwd(): PathBuilder;
-    /**
-     * @since 0.0.1
-     */
-    clear(): PathBuilder;
-    /**
-     * @since 0.0.1
-     */
-    build(): string;
-}
-
-export { PathBuilder };