@mephisto5558/better-types 1.0.1 → 2.0.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@mephisto5558/better-types",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "A collection of useful TypeScript types and augmentations to improve developer experience.",
   "keywords": [
-    "typing",
-    "typescript"
+    "typescript",
+    "typing"
   ],
   "homepage": "https://github.com/Mephisto5558/Better-Types#readme",
   "bugs": {
@@ -19,17 +19,20 @@
   "type": "module",
   "exports": {
     ".": {
-      "types": "./index.d.ts"
+      "types": "./src/index.d.ts"
     },
-    "./eslint": "./eslint.js"
+    "./eslint": {
+      "types": "./src/eslint.d.ts",
+      "import": "./src/eslint.js",
+      "require": "./src/eslint.js"
+    }
   },
-  "types": "index.d.ts",
+  "types": "src/index.d.ts",
   "files": [
-    "index.d.ts",
-    "eslint.js",
-    "eslint.d.ts"
+    "src"
   ],
   "scripts": {
+    "lint": "eslint . --cache --cache-location ./node_modules/.cache/eslint/ >eslint.log",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "devDependencies": {
@@ -43,5 +46,12 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "onFail": "error",
+      "version": ">=20"
+    }
   }
 }

package/src/eslint.js

@@ -0,0 +1,57 @@
+/* eslint-disable-next-line import-x/prefer-default-export -- easier import */
+export const globals = Object.freeze(Object.fromEntries([
+  'Snowflake',
+  'GenericFunction',
+  'GenericConstructor',
+  'OmitFirstParameters',
+  'ReplaceMethods',
+  'Prettify',
+  'ShallowPrettify',
+
+  // logicShortcuts/normal.ts
+  'If',
+  'IfD',
+  'IfEquals',
+  'IfExtends',
+  'IfExtendsD',
+  'AddIf',
+  'Extends',
+  'GetAll',
+  'And',
+  'Or',
+  'Not',
+  'Match',
+  'ExtendsMatch',
+  'ExtendsMultiMatch',
+  'Fn',
+  'IsEmptyArray',
+  'LooseOmit',
+
+  // logicShortcuts/strict.ts
+  'IfExtendsStrict',
+  'IfExtendsStrictD',
+  'IfExtendsNever',
+  'ExtendsStrict',
+  'ExtendsNever',
+  'ExtendsMatchStrict',
+  'ExtendsMultiMatchStrict',
+  'StrictPick',
+  'GetAllStrict',
+  'StrictOmit',
+
+  // better-typescript-lib
+  'JSONPrimitive',
+  'JSONComposite',
+  'JSONValueF',
+  'JSONValue',
+  'JSONObject',
+  'JSONHolder',
+  'ToJSON',
+  'SomeExtends',
+
+  // "SomeFunction", // use GenericFunction instead
+  'SomeConstructor',
+  'UndefinedDomain',
+  'StringifyResultT',
+  'StringifyResult'
+].map(e => [e, 'readonly'])));

package/{index.d.ts → src/index.d.ts}

@@ -1,33 +1,24 @@
 /* eslint-disable-next-line @typescript-eslint/triple-slash-reference -- required to load before this file when this lib is loaded locally */
 /// <reference types="node" />
 
-/* eslint-disable sonarjs/no-built-in-override */
+/* eslint-disable @typescript-eslint/triple-slash-reference, @stylistic/multiline-comment-style
+  -- required to load other globals without affecting the global scope */
+/// <reference path="./logicShortcuts/normal.d.ts" />
+/// <reference path="./logicShortcuts/strict.d.ts" />
+/* eslint-enable @typescript-eslint/triple-slash-reference, @stylistic/multiline-comment-style */
 
+/* eslint-disable sonarjs/no-built-in-override -- overwriting builtins */
+
+import type { AssignThis, ISODateTime, KeyToString, Split, StripExtension, _Prettify } from './utils.js';
 /* eslint-disable-next-line unicorn/require-module-specifiers -- required */
 export {};
 
-type ISODate = `${number}${number}${number}${number}-${number}${number}-${number}${number}`;
-type ISOTime = `${number}${number}:${number}${number}:${number}${number}.${number}${number}${number}`;
-type ISODateTime = `${ISODate}T${ISOTime}Z`;
-
-type KeyToString<K extends PropertyKey> = K extends string ? K : K extends number ? `${K}` : never;
-
-type Split<S extends string, SEP extends string | undefined, L extends number = number, Acc extends string[] = []> = SEP extends unknown
-  ? [L] extends [Acc['length']] ? Acc
-    : SEP extends undefined ? [S]
-    : string extends S | SEP ? string[]
-    : SEP extends ''
-      ? S extends `${infer Head}${infer Tail}`
-        ? Split<Tail, SEP, L, [...Acc, Head]>
-        : Acc
-      : S extends `${infer Head}${SEP}${infer Tail}`
-        ? Split<Tail, SEP, L, [...Acc, Head]>
-        : [...Acc, S]
-  : never;
-
 declare global {
+  /** The maximum depth for {@link Prettify}. Change with caution. */
+  type __MAX_PRETTIFY_DEPTH = 5;
+
   // #region Buildins
-  /* eslint-disable @typescript-eslint/consistent-type-definitions */
+  /* eslint-disable @typescript-eslint/consistent-type-definitions -- overwriting interfaces */
   namespace NodeJS {
     interface Require {
       /* eslint-disable-next-line @typescript-eslint/prefer-function-type -- overwriting only the function signature */
@@ -79,20 +70,42 @@ declare global {
   /* eslint-enable @typescript-eslint/consistent-type-definitions */
 
   // #region useful Generics
-  /* eslint-disable-next-line @typescript-eslint/no-explicit-any -- used only as generic constraint */
-  type GenericFunction<Ret = any> = (...args: any) => Ret;
+  /* eslint-disable @typescript-eslint/no-explicit-any -- used only as generic constraint */
+
+  /** A function with some parameters and some return type. */
+  type GenericFunction<Ret = any> = (...args: any[]) => Ret;
+
+  /** A potentially abstract class or declared class. */
+  type GenericConstructor<Ret = object> = { prototype: Ret };
+
+  /* eslint-enable @typescript-eslint/no-explicit-any */
 
   type OmitFirstParameters<
     T extends GenericFunction, N extends number = 1, Acc extends unknown[] = []
   > = Acc['length'] extends N ? Parameters<T> extends [...Acc, ...infer Rest] ? Rest : never : OmitFirstParameters<T, N, [...Acc, unknown]>;
 
-  /**
-   * A stricter version of `Omit` that preserves modifiers better by using a mapped type.
-   *
-   * {@link https://github.com/microsoft/TypeScript/issues/54451#issue-1732749888 More info} */
-  type StrictOmit<T, K extends keyof T> = { [P in keyof T as P extends K ? never : P]: T[P] };
-
-  type ReplaceMethod<T, K extends keyof T, This, Args extends unknown[] = Parameters<T[K]>> = StrictOmit<T, K> & {
-    [P in K]: Exclude<T[P], GenericFunction> | ((this: This, ...args: Args) => ReturnType<Extract<T[P], GenericFunction>>);
+  type ReplaceMethods<T, ContextMap extends Partial<Record<keyof T, unknown>>> = {
+    [K in keyof T]: K extends keyof ContextMap
+      ? AssignThis<T[K], ContextMap[K]>
+      : T[K];
   };
+
+  type Prettify<T> = _Prettify<T, true>;
+  type ShallowPrettify<T> = _Prettify<T, false>;
+}
+
+declare module 'node:path' {
+  export function basename<P extends string, E extends string | undefined = undefined>(
+    path: P, ext?: E
+  ): Lowercase<P> extends P ? Lowercase<StripExtension<P, E>> : StripExtension<P, E>;
+
+  export function extname<T extends string>(path: T): T extends Lowercase<string> ? Lowercase<string> : string;
+}
+
+declare module 'path' {
+  export * from 'node:path';
+}
+
+declare module 'discord-api-types/v10' {
+  export type Snowflake = globalThis.Snowflake;
 }

package/src/logicShortcuts/index.d.ts

@@ -0,0 +1,2 @@
+export type BooleanOptions = { ifTrue?: unknown; ifFalse?: unknown };
+export type ResolveBooleanResult<O extends BooleanOptions, K extends keyof BooleanOptions> = K extends keyof O ? O[K] : never;

package/src/logicShortcuts/normal.d.ts

@@ -0,0 +1,111 @@
+import type { BooleanOptions, ResolveBooleanResult } from './index.js';
+import type { AllKeys } from '#/utils.js';
+
+/* eslint-disable-next-line unicorn/require-module-specifiers -- required */
+export {};
+
+declare global {
+
+  /**
+   * Resolves to 'Options.ifTrue` if 'Condition` resolves to `true`,
+   * otherwise to `Options.ifFalse`.
+   *
+   * Defaults to `never` for either result. */
+  type If<Condition extends boolean, Options extends BooleanOptions>
+    = Condition extends true
+      ? ResolveBooleanResult<Options, 'ifTrue'>
+      : ResolveBooleanResult<Options, 'ifFalse'>
+  ;
+
+  /** Non-Object version of {@link If} to support use of `this`. */
+  type IfD<Condition extends boolean, IfTrue, IfFalse> = NoInfer<Condition> extends true ? IfTrue : IfFalse;
+
+  type IfEquals<A, B, Options extends BooleanOptions> = Prettify<
+    /* eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- these are nessesary. */
+    (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2)
+      ? ResolveBooleanResult<Options, 'ifTrue'>
+      : ResolveBooleanResult<Options, 'ifFalse'>
+  >;
+
+  /**
+   * Resolves to `Options.ifTrue` if `T` extends `Type`,
+   * otherwise to `Options.ifFalse`.
+   *
+   * Defaults to `never` for either result. */
+  type IfExtends<T, Type, Options extends BooleanOptions> = Prettify<
+    T extends NoInfer<Type>
+      ? ResolveBooleanResult<Options, 'ifTrue'>
+      : ResolveBooleanResult<Options, 'ifFalse'>
+  >;
+
+  /** Non-Object version of {@link IfExtends} to support use of `this`. */
+  type IfExtendsD<T, Type, IfTrue, IfFalse> = T extends NoInfer<Type> ? IfTrue : IfFalse;
+
+  /**
+   * Adds `Options.ifTrue` to `Base` if `Condition` resolves to `true`,
+   * otherwise adds `Options.ifFalse`.
+   *
+   * Defaults to `never` for either result. */
+  type AddIf<Base, Condition extends boolean, Options extends BooleanOptions> = Prettify<
+    NoInfer<Condition> extends true
+      ? Base | ResolveBooleanResult<Options, 'ifTrue'>
+      : Base | ResolveBooleanResult<Options, 'ifFalse'>
+  >;
+
+  /** Resolves to `true` if `T extends Type`, otherwise to `false`. */
+  type Extends<T, Type> = T extends NoInfer<Type> ? true : false;
+
+  /** Extract from `T` those types that have might have a property of key `K`. */
+  type GetAll<T, K extends AllKeys<T>> = Extract<T, Partial<Record<K, unknown>>>;
+
+  type And<T extends readonly [boolean, boolean, ...boolean[]]>
+    = NoInfer<T>[number] extends true ? true : false;
+
+  type Or<T extends readonly [boolean, boolean, ...boolean[]]>
+    = true extends NoInfer<T>[number] ? true : false;
+
+  type Not<T extends boolean> = NoInfer<T> extends true ? false : true;
+
+  type Match<Cases extends readonly (readonly [boolean, unknown])[], Default = never>
+    = Cases extends readonly [readonly [infer Condition, infer Result], ...infer Rest]
+      ? NoInfer<Condition> extends true
+        ? Result
+        : Rest extends readonly (readonly [boolean, unknown])[]
+          ? Match<Rest, Default>
+          : Default
+      : Default;
+
+  type ExtendsMatch<T, Cases extends readonly (readonly [unknown, unknown])[], Default = never>
+    = Cases extends readonly [readonly [infer Condition, infer Result], ...infer Rest]
+      ? T extends NoInfer<Condition>
+        ? Result
+        : Rest extends readonly (readonly [unknown, unknown])[]
+          ? ExtendsMatch<T, Rest, Default>
+          : Default
+      : Default;
+
+  type ExtendsMultiMatch<
+    BASE,
+    KEYS extends readonly BASE[],
+    Cases extends readonly (readonly [BASE, unknown])[]
+  > = ShallowPrettify<
+    { [I in keyof KEYS]: ExtendsMatch<KEYS[I], NoInfer<Cases>> }[number]
+  >;
+
+  type Fn<This, Args extends unknown[], Return> = Prettify<
+    NoInfer<This> extends never
+      ? (...args: NoInfer<Args>) => NoInfer<Return>
+      : (this: This, ...args: NoInfer<Args>) => NoInfer<Return>
+  >;
+
+  /**
+   * Resolves to `true` if the `Arr`'s length is `0`,
+   * `false` if it's not, and `boolean` if we don't know. */
+  type IsEmptyArray<Arr extends readonly unknown[]>
+    = number extends Arr['length']
+      ? boolean
+      : [Arr['length']] extends [0] ? true : false;
+
+  /** A loose implementation of {@link StrictOmit} that allows any `PropertyKey`s for `K`. */
+  type LooseOmit<T, K extends PropertyKey> = Pick<T, Exclude<keyof T, K>>;
+}

package/src/logicShortcuts/strict.d.ts

@@ -0,0 +1,67 @@
+import type { BooleanOptions, ResolveBooleanResult } from './index.js';
+import type { AllKeys } from '#/utils.js';
+
+/* eslint-disable-next-line unicorn/require-module-specifiers -- required */
+export {};
+
+declare global {
+  /** Non-distributive version of {@link IfExtends}. */
+  type IfExtendsStrict<T, Type, Options extends BooleanOptions> = Prettify<
+    [T] extends [NoInfer<Type>]
+      ? ResolveBooleanResult<Options, 'ifTrue'>
+      : ResolveBooleanResult<Options, 'ifFalse'>
+  >;
+
+  /** Non-Object version of {@link IfExtendsStrict} to support use of `this`. */
+  type IfExtendsStrictD<T, Type, IfTrue, IfFalse>
+    = [T] extends [NoInfer<Type>] ? IfTrue : IfFalse;
+
+  /** Shortcut of {@link IfExtendsStrict} to check if a type extends never. */
+  type IfExtendsNever<T, Options extends BooleanOptions> = [T] extends [never]
+    ? ResolveBooleanResult<Options, 'ifTrue'>
+    : ResolveBooleanResult<Options, 'ifFalse'>;
+
+  /** Non-distributive version of {@link Extends}. */
+  type ExtendsStrict<T, Type> = [T] extends [NoInfer<Type>] ? true : false;
+
+  /** Shortcut of {@link ExtendsStrict} to check if a type extends never. */
+  type ExtendsNever<T> = [T] extends [never] ? true : false;
+
+  /** Non-distributive version of {@link ExtendsMatch}. */
+  type ExtendsMatchStrict<T, Cases extends readonly (readonly [unknown, unknown])[], Default = never>
+    = Cases extends readonly [readonly [infer Condition, infer Result], ...infer Rest]
+      ? [T] extends [NoInfer<Condition>]
+          ? Result
+          : Rest extends readonly (readonly [unknown, unknown])[]
+            ? ExtendsMatchStrict<T, Rest, Default>
+            : Default
+      : Default;
+
+  /** Non-distributive version of {@link ExtendsMultiMatch}. */
+  type ExtendsMultiMatchStrict<
+    BASE,
+    KEYS extends readonly BASE[],
+    Cases extends readonly (readonly [BASE, unknown])[]
+  > = Prettify<
+    { [I in keyof KEYS]: ExtendsMatchStrict<KEYS[I], NoInfer<Cases>> }[number]
+  >;
+
+  /**
+   * Strict version of {@link Pick}. Validates that all keys in `Target` exist in `Base`.
+   * Keys not present in `Base` are resolved to `never`. */
+  type StrictPick<Target, Base> = {
+    [K in keyof Target]: K extends keyof Base ? Target[K] : never;
+  };
+
+  /** Strict Version of {@link GetAll} that does not allow `K` to be optional. */
+  type GetAllStrict<T, K extends AllKeys<T>> = Extract<T, Record<K, unknown>>;
+
+  // /**
+  //  * A stricter version of `Omit` that preserves modifiers better by using a mapped type.
+  //  *
+  //  * {@link https://github.com/microsoft/TypeScript/issues/54451#issue-1732749888 More info} */
+  // type StrictOmit<T, K extends keyof T> = { [P in keyof T as P extends K ? never : P]: T[P] };
+
+  /** A stricter version of `Omit` that keeps interfaces' identity using `Pick` and `Exclude`. */
+  type StrictOmit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
+}

package/src/utils.d.ts

@@ -0,0 +1,46 @@
+type ISODate = `${number}${number}${number}${number}-${number}${number}-${number}${number}`;
+type ISOTime = `${number}${number}:${number}${number}:${number}${number}.${number}${number}${number}`;
+export type ISODateTime = `${ISODate}T${ISOTime}Z`;
+
+export type KeyToString<K extends PropertyKey> = K extends string ? K : K extends number ? `${K}` : never;
+
+export type Split<S extends string, SEP extends string | undefined, L extends number = number, Acc extends string[] = []> = SEP extends unknown
+  ? [L] extends [Acc['length']] ? Acc
+    : SEP extends undefined ? [S]
+    : string extends S | SEP ? string[]
+    : SEP extends ''
+      ? S extends `${infer Head}${infer Tail}`
+        ? Split<Tail, SEP, L, [...Acc, Head]>
+        : Acc
+      : S extends `${infer Head}${SEP}${infer Tail}`
+        ? Split<Tail, SEP, L, [...Acc, Head]>
+        : [...Acc, S]
+  : never;
+
+type ProbablyDiscordJs = { client: unknown };
+type ShouldSkip<T> = [T] extends [object]
+  ? T extends ProbablyDiscordJs | GenericFunction | GenericConstructor | { constructor: GenericConstructor }
+    ? true
+    : false
+  : true;
+
+export type _Prettify<T, Deep extends boolean, Depth extends unknown[] = []>
+  = ShouldSkip<T> extends true ? T
+  : Depth['length'] extends __MAX_PRETTIFY_DEPTH ? T : {
+    [K in keyof T]: Deep extends true
+      ? _Prettify<T[K], Deep, [...Depth, unknown]>
+      : T[K]
+  } & {};
+
+export type StripExtension<T extends string, Ext extends string | undefined>
+  = Ext extends string
+    ? T extends `${infer R}${Ext}`
+      ? R
+      : T
+    : T;
+
+export type AllKeys<T> = T extends unknown ? keyof T : never;
+
+export type AssignThis<F, This> = F extends (...args: infer Args) => infer Return
+  ? (this: This, ...args: Args) => Return
+  : F;

package/eslint.js

@@ -1,25 +0,0 @@
-/* eslint-disable-next-line import-x/prefer-default-export */
-export const globals = Object.freeze({
-  GenericFunction: 'readonly',
-  OmitFirstParameters: 'readonly',
-  StrictOmit: 'readonly',
-  ReplaceMethod: 'readonly',
-  Snowflake: 'readonly',
-
-
-  // better-typescript-lib
-  JSONPrimitive: 'readonly',
-  JSONComposite: 'readonly',
-  JSONValueF: 'readonly',
-  JSONValue: 'readonly',
-  JSONObject: 'readonly',
-  JSONHolder: 'readonly',
-  ToJSON: 'readonly',
-  SomeExtends: 'readonly',
-
-  // SomeFunction: 'readonly', // use GenericFunction instead
-  SomeConstructor: 'readonly',
-  UndefinedDomain: 'readonly',
-  StringifyResultT: 'readonly',
-  StringifyResult: 'readonly'
-});