@halospv3/hce.shared-config 2.6.4 → 3.0.0-develop.10

package/src/utils/reflection/OwnPropertyDescriptorMap.d.ts

@@ -0,0 +1,82 @@
+import type {
+  BaseClass,
+  ClassLike,
+  ClassLike_Unknown,
+  ProtoOrSuperClass,
+  WithProto,
+} from './inheritance.ts';
+
+// todo: Omit [P in keyof T] where T['__proto__'][P] === T[P].
+// todo: NEVER omit overridden class members! Does TypeScript expose that override in accessible metadata?
+
+/**
+ * A typed {@link PropertyDescriptorMap} without any keys found in its `[[Prototype]]` chain.
+ * This may mean overridden class properties are wrongly omitted.
+ * @template T Any type with its `[[Prototype]]` attached via a type-only `__proto__` property. The type of `__proto__` must extends {@link ProtoOrSuperClass}.
+ * @since 3.0.0
+ */
+export type OwnPropertyDescriptorMap<T extends WithProto<ProtoOrSuperClass>>
+  = T['__proto__'] extends null
+    ? { [P0 in keyof T]: TypedPropertyDescriptor<T[P0]>; }
+    : Omit<
+      { [P0 in keyof T]: TypedPropertyDescriptor<T[P0]>; },
+      Exclude<
+        keyof { [P1 in keyof T['__proto__']]: TypedPropertyDescriptor<T['__proto__'][P1]> },
+        keyof ClassLike<BaseClass<ClassLike_Unknown>>
+      >
+    >;
+
+// // todo: use SharedKeys to only keys where SharedKeys<T> in keyof T
+// // eslint-disable-next-line @typescript-eslint/no-unused-vars
+// type SharedKeys<T extends WithProto<ProtoOrSuperClass>> = Extract<keyof T, keyof T['__proto__']>;
+
+// // todo: make this useful. The ReturnType is incorrect
+// // eslint-disable-next-line @typescript-eslint/no-unused-vars
+// declare function removeMatchingPropertyDescriptors<T0, T1>(
+//   a: { [P0 in keyof T0]: TypedPropertyDescriptor<T0[P0]> },
+//   b: { [P1 in keyof T1]: TypedPropertyDescriptor<T1[P1]> }
+// ): Omit<typeof a, keyof (T0 & T1)>;
+
+// /**
+//  * @see https://stackoverflow.com/a/56874389/1489478
+//  * @example
+//  * ```ts
+//  * interface MyInterface {
+//  *   a: number;
+//  *   b: string;
+//  *   c: number;
+//  * }
+//  * type MyType = KeysMatching<MyInterface, number>;
+//  * type MyType = "a" | "c";
+//  * @todo KeysMatching
+// */
+// // eslint-disable-next-line @typescript-eslint/no-unused-vars
+// type KeysMatching<T extends object, V> = {
+//   [K in keyof T]-?: T[K] extends V ? K : never
+// }[keyof T];
+
+// /**
+//  * @todo KeysNotMatching
+//  */
+// // eslint-disable-next-line @typescript-eslint/no-unused-vars
+// type KeysNotMatching<T extends object, V> = {
+//   [K in keyof T]-?: T[K] extends V ? never : K
+// }[keyof T];
+
+// // type _ = KeysMatching<Class_NPP,Class_MSBPP[keyof Class_MSBPP]>
+// /**
+//  * @see https://stackoverflow.com/a/56874389/14894786
+//  * @example
+//  * interface AnotherInterface {
+//  *   narrower: 1;
+//  *   exact: number;
+//  *   wider: string | number;
+//  * }
+//  * type AnotherTypeWrite = KeysMatchingWrite<AnotherInterface, number>;
+//  * type AnotherTypeWrite = 'exact' | 'wider';
+//  * @todo KeysMatchingWrite
+//  */
+// // eslint-disable-next-line @typescript-eslint/no-unused-vars
+// type KeysMatchingWrite<T extends object, V> = {
+//   [K in keyof T]-?: [V] extends [T[K]] ? K : never
+// }[keyof T];

package/src/utils/reflection/PropertyDescriptorMap.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A variant of TypeScript's ES5 PropertyDescriptorMap with an extra generic
+ * parameter for omitting inherited keys.
+ * @template T The type described by the {@link PropertyDescriptorMap}.
+ * @template [__proto__=null]
+ * The `null` or the `object`-like `[[Prototype]]` of {@link T}.
+ * @since 3.0.0
+ */
+export type PropertyDescriptorMap<T, __proto__ extends object | null = null>
+  = __proto__ extends null
+    ? { [P0 in keyof T]: TypedPropertyDescriptor<T[P0]>; }
+    : Omit<
+      { [P0 in keyof T]: TypedPropertyDescriptor<T[P0]>; },
+      keyof { [P1 in keyof __proto__]: TypedPropertyDescriptor<__proto__[P1]> }
+    >;

package/src/utils/reflection/filterForGetters.ts

@@ -0,0 +1,59 @@
+import type {
+  BaseClassProto,
+  baseClassProto,
+  ClassLike,
+  ConstructorConstraint,
+  InstanceTypeOrSelf,
+  SuperClassLike,
+  WithProto,
+} from './inheritance.js';
+import type { InstancePropertyDescriptorMap } from './InstancePropertyDescriptorMap.js';
+import type { OwnGetterDescriptorMap } from './OwnGetterDescriptorMap.js';
+import type { OwnPropertyDescriptorMap } from './OwnPropertyDescriptorMap.js';
+import type { PropertyDescriptorMap } from './PropertyDescriptorMap.js';
+
+export function filterForGetters<
+  Class extends ClassLike<ConstructorConstraint<Class> & WithProto<SuperClassLike | typeof baseClassProto>>,
+>(
+  descriptorMap: InstancePropertyDescriptorMap<Class>,
+): Partial<OwnGetterDescriptorMap<
+  InstanceType<Class>,
+  Class['__proto__'] extends BaseClassProto ? null : InstanceTypeOrSelf<Class['__proto__']>
+>>;
+export function filterForGetters<
+  Class extends ClassLike<ConstructorConstraint<Class> & WithProto<SuperClassLike | BaseClassProto>>,
+>(
+  descriptorMap: OwnPropertyDescriptorMap<Class>,
+): Partial<OwnGetterDescriptorMap<Class, Class['__proto__']>>;
+/**
+ * Iterates through the descriptors object, checking for property descriptors whose `get` is a function.
+ * Returns an {@link OwnGetterDescriptorMap} of the getters.
+ * If you want only own, non-inherited getters, you must filter sanitize the
+ * type the `descriptors` parameter yourself e.g. `Omit<Class, keyof
+ * SuperClass>`.
+ * @param descriptorMap An object like the return value of Object.getOwnPropertyDescriptors
+ * @template Class Any ClassLike type
+ * @template T Any `object`-like type.
+ * @template [__proto__=null] If {@link Class} is not {@link ClassLike}, the `__proto__` of {@link T}.
+ * @returns An {@link OwnGetterDescriptorMap}.
+ * @since 3.0.0
+ */
+export function filterForGetters<
+  T extends object,
+  __proto__ extends object | null = null,
+>(
+  descriptorMap: PropertyDescriptorMap<T, __proto__> | PropertyDescriptorMap<T>,
+): Partial<OwnGetterDescriptorMap<T, __proto__>> {
+  let getterDescriptorMap: Partial<OwnGetterDescriptorMap<T, __proto__>> = {};
+  for (const key in descriptorMap) {
+    const element = descriptorMap[key as keyof typeof descriptorMap];
+    if (typeof element.get === 'function') {
+      getterDescriptorMap = Object.assign(
+        getterDescriptorMap,
+        { [key]: element },
+      );
+    }
+  }
+
+  return getterDescriptorMap;
+}

package/src/utils/reflection/getOwnPropertyDescriptors.ts

@@ -0,0 +1,52 @@
+import type { InstanceOrStatic } from '../miscTypes.js';
+import type { BaseClassProto, ClassLike, ConstructorConstraint, SuperClassLike, WithProto } from './inheritance.js';
+import type { InstancePropertyDescriptorMap } from './InstancePropertyDescriptorMap.js';
+import type { OwnPropertyDescriptorMap } from './OwnPropertyDescriptorMap.js';
+
+/**
+ * Get the property descriptors of the class or constructor similar to {@link Object.getOwnPropertyDescriptors}, but with more options--including recursion.
+ * @template {InstanceOrStatic} _InstanceOrStatic 'Instance' or 'Static'. Determines the return type.
+ * @param classDefinition A class or constructor, cast to {@link ClassLike}.
+ * @param instanceOrStatic 'Instance' or 'Static'. Determines the return type.
+ * @template {ClassLike<ConstructorConstraint<Class> & WithProto<SuperClassLike | BaseClassProto>>} Class
+ * The typeof {@link classDefinition}.
+ * {@link WithProto}<{@link SuperClassLike}> is necessary for walking the
+ * prototype chain for both Instance  and Static properties.
+ * If unspecified, the return type may be incorrect.
+ * @returns ({@link instanceOrStatic} === 'Instance') ? {@link InstancePropertyDescriptorMap<Class>}\
+ * : ({@link instanceOrStatic} === 'Static') ? {@link OwnPropertyDescriptorMap<Class>}\
+ * : never
+ * @throws {TypeError}
+ * @since 3.0.0
+ */
+export function getOwnPropertyDescriptors<
+  Class extends ClassLike<ConstructorConstraint<Class> & WithProto<SuperClassLike | BaseClassProto>>,
+  _InstanceOrStatic extends InstanceOrStatic,
+>(
+  classDefinition: Class,
+  instanceOrStatic: _InstanceOrStatic,
+): [_InstanceOrStatic] extends ['Instance']
+  ? InstancePropertyDescriptorMap<Class>
+  : [_InstanceOrStatic] extends ['Static']
+      ? OwnPropertyDescriptorMap<Class>
+      : never {
+  switch (instanceOrStatic) {
+    case 'Instance': {
+      return Object.getOwnPropertyDescriptors(classDefinition.prototype) as [Extract<typeof instanceOrStatic, 'Instance'>] extends ['Instance']
+        ? InstancePropertyDescriptorMap<Class>
+        : [_InstanceOrStatic] extends ['Static']
+            ? OwnPropertyDescriptorMap<Class>
+            : never;
+    }
+    case 'Static': {
+      return Object.getOwnPropertyDescriptors(classDefinition) as [Extract<typeof instanceOrStatic, 'Static'>] extends ['Instance']
+        ? InstancePropertyDescriptorMap<Class>
+        : [_InstanceOrStatic] extends ['Static']
+            ? OwnPropertyDescriptorMap<Class>
+            : never;
+    }
+    default: {
+      throw new TypeError('Argument `instanceOrStatic` must be "Instance" or "Static".');
+    }
+  }
+}

package/src/utils/reflection/getOwnPropertyDescriptorsRecursively.ts

@@ -0,0 +1,127 @@
+import type { Increment } from '../GracefulRecursion.js';
+import type { InstanceOrStatic, Integer } from '../miscTypes.js';
+import { getOwnPropertyDescriptors } from './getOwnPropertyDescriptors.js';
+import { getPrototypesChainOf } from './getPrototypeChainOf.js';
+import type {
+  BaseClass,
+  BaseClassProto,
+  ClassLike,
+  ConstructorConstraint,
+  ConstructorLike,
+  ProtoChainOfClass,
+  SuperClassLike,
+  WithProto,
+} from './inheritance.js';
+import type { InstanceTypeOrSelfPropertyDescriptorMap } from './InstanceTypeOrSelfPropertyDescriptorMap.js';
+import type { OwnPropertyDescriptorMap } from './OwnPropertyDescriptorMap.js';
+/* eslint-disable jsdoc/check-tag-names */
+/**
+ * JSDoc type imports
+ * @typedef {import('./getPrototypeOf.js').getPrototypeOf} getPrototypeOf
+ * @typedef {import('./listOwnGetters.js').listOwnGetters} listOwnGetters
+ * @typedef {import('./InstancePropertyDescriptorMap.js').InstancePropertyDescriptorMap} InstancePropertyDescriptorMap
+ */
+/* eslint-enable jsdoc/check-tag-names */
+
+/**
+ * A conditional wrapper for {@link InstanceTypeOrSelfPropertyDescriptorMap} and
+ * {@link OwnPropertyDescriptorMap}.
+ *
+ * If {@link _InstanceOrStatic} is 'Instance', {@link InstanceTypeOrSelfPropertyDescriptorMap}.\
+ * Else if {@link _InstanceOrStatic} is 'Static',
+ * {@link OwnPropertyDescriptorMap }.\
+ * Else, `never`.
+ * @template {ConstructorConstraint<Class> & WithProto<SuperClassLike | BaseClassProto>} Class
+ * A class definition cast to {@link ClassLike}.
+ * @template {InstanceOrStatic} _InstanceOrStatic
+ * 'Instance' or 'Static'. Determines the return type.
+ * @since 3.0.0
+ */
+export type RecursedPropertyDescriptorMap<
+  Class extends ConstructorConstraint<Class> & WithProto<SuperClassLike | BaseClassProto>,
+  _InstanceOrStatic extends InstanceOrStatic,
+> = [_InstanceOrStatic] extends ['Instance'] ? InstanceTypeOrSelfPropertyDescriptorMap<Class, Class['__proto__']>
+  : [_InstanceOrStatic] extends ['Static'] ? OwnPropertyDescriptorMap<Class>
+      : never;
+
+/**
+ * An
+ * ordered array of {@link OwnPropertyDescriptorMap} or
+ * {@link InstancePropertyDescriptorMap} starting with {@link classDefinition}
+ * and ending with a {@link BaseClass}.
+ * @template {ConstructorConstraint<Class> & WithProto<SuperClassLike | BaseClassProto>} Class
+ * @template {'Instance' | 'Static'} InstanceOrStatic
+ * @template {Integer<number>} [Limit=16]
+ * @template {Integer<number>} [CurrentLevel=0]
+ */
+export type RecursedPropertyDescriptorMapArray<
+  Class extends ConstructorConstraint<Class> & WithProto<SuperClassLike | BaseClassProto>,
+  InstanceOrStatic extends 'Instance' | 'Static',
+  Limit extends Integer<number> = 16,
+  CurrentLevel extends Integer<number> = 0,
+> = Class['__proto__'] extends BaseClassProto['__proto__'] | BaseClassProto['__proto__']['__proto__'] ? never
+  : Class['__proto__'] extends BaseClassProto ? [RecursedPropertyDescriptorMap<BaseClass<Class>, InstanceOrStatic>]
+    : Class['__proto__'] extends ConstructorLike<Class['__proto__']>
+      ? [
+          RecursedPropertyDescriptorMap<Class, InstanceOrStatic>,
+          ...RecursedPropertyDescriptorMapArray<
+            ClassLike<Exclude<Class['__proto__'], BaseClassProto> & WithProto<SuperClassLike | BaseClassProto>>,
+            InstanceOrStatic,
+            Limit,
+            Increment<CurrentLevel>
+          >,
+        ]
+      : never;
+/**
+ * Walks the class inheritance chain to get a PropertyDescriptorMap of each class.
+ *
+ * While you _can_ use this to get an array of getter names/keys, you should use {@link getPrototypeOf} and {@link listOwnGetters}, instead!
+ * @template Class Any class definition type-cast to {@link ClassLike}
+ * @template _InstanceOrStatic
+ * @param classDefinition Any class definition type-cast to {@link ClassLike}
+ * @param instanceOrStatic 'Instance' or 'Static'. Determines the return type.
+ * @returns An
+ * ordered array of {@link OwnPropertyDescriptorMap} or
+ * {@link InstancePropertyDescriptorMap} starting with {@link classDefinition}
+ * and ending with a {@link BaseClass}.
+ * @since 3.0.0
+ */
+export function getOwnPropertyDescriptorsRecursively<
+  // Class extends ClassLike<ConstructorConstraint<Class> & WithProto<SuperClassLike | BaseClassProto>>,
+  Class extends ClassLike<ConstructorConstraint<Class> & WithProto<SuperClassLike | BaseClassProto>>,
+  _InstanceOrStatic extends InstanceOrStatic,
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+  Limit extends Integer<number> = 16,
+>(
+  classDefinition: Class,
+  instanceOrStatic: _InstanceOrStatic,
+): RecursedPropertyDescriptorMapArray<Class, _InstanceOrStatic> {
+  const staticProtoChain: ProtoChainOfClass<Class> = getPrototypesChainOf(classDefinition, 'classes');
+  if (isSingleTuple(staticProtoChain)) {
+    return [
+      getOwnPropertyDescriptors(
+        staticProtoChain[0],
+        instanceOrStatic,
+      ) as RecursedPropertyDescriptorMap<Class, _InstanceOrStatic>,
+    ] as unknown as RecursedPropertyDescriptorMapArray<Class, _InstanceOrStatic, Limit>;
+  }
+
+  const recursedPropertyDescriptorMapArray = staticProtoChain.map(classDefinition =>
+    getOwnPropertyDescriptors(
+      classDefinition,
+      instanceOrStatic,
+    ),
+  );
+
+  return recursedPropertyDescriptorMapArray as RecursedPropertyDescriptorMapArray<Class, _InstanceOrStatic>;
+}
+
+/**
+ * Simple utility for single-tuple type assertion
+ * @template {T} T T in T[]
+ * @param array an array
+ * @returns array is [T]
+ */
+function isSingleTuple<T>(array: T[]): array is [T] {
+  return Array.isArray(array) && array.length === 1;
+}

package/src/utils/reflection/getPrototypeChainOf.ts

@@ -0,0 +1,85 @@
+/* eslint-disable jsdoc/no-defaults */
+import type { TupleIndices } from '../miscTypes.js';
+import { getPrototypeOf } from './getPrototypeOf.js';
+import {
+  baseClassProto,
+  type BaseClassProto,
+  type ClassLike,
+  type ConstructorConstraint,
+  type ProtoChainOfClass,
+  type ProtoChainOfClassInstance,
+  type SuperClassLike,
+  type WithProto,
+} from './inheritance.js';
+import { isConstructor } from './isConstructor.js';
+
+type ProtoChain<
+  Class extends ClassLike<ConstructorConstraint<Class> & WithProto<SuperClassLike | BaseClassProto>>,
+  ClassesOrInstances extends 'classes' | 'classInstances',
+> = [ClassesOrInstances] extends ['classInstances'] ? ProtoChainOfClassInstance<Class>
+  : [ClassesOrInstances] extends ['classes'] ? ProtoChainOfClass<Class>
+      : never;
+
+/**
+ * Iterate through the class and its base/super classes until an anonymous function is reached. This is the default superclass all classes extend.
+ * @template Class Any {@link ClassLike} type.
+ * @template ClassesOrInstances 'classes' or 'classInstances'
+ * @param classDefinition Any class type satisfying {@link Class}. This class (or its instance type) is included in the return value.
+ * @param [returnType='classes'] Determines return type. If 'classInstances', the return type is an array of the classes' `.prototype`. Else, the classes themselves are returned.
+ * @since 3.0.0
+ * @returns
+ * `returnType extends 'classInstances' ? ClassLike<T>[] : ClassLike<T>[].map(c => c.prototype)`
+ * Excludes default superclasses e.g. anonymous functions, native code.
+ */
+export function getPrototypesChainOf<
+  Class extends ClassLike<ConstructorConstraint<Class> & WithProto<SuperClassLike | BaseClassProto>>,
+  ClassesOrInstances extends 'classes' | 'classInstances',
+>(
+  classDefinition: Class,
+  returnType: ClassesOrInstances,
+): ProtoChain<Class, ClassesOrInstances> {
+  // class definitions or their respective .prototype; exclude default superclasses.
+  let current: ProtoChainOfClass<Class>[TupleIndices<ProtoChainOfClass<Class>>] = classDefinition as ProtoChainOfClass<Class>[0 extends TupleIndices<ProtoChainOfClass<Class>> ? 0 : never];
+  let parent: typeof current & WithProto<SuperClassLike | BaseClassProto> | object;
+  const returnValue = [] as unknown as
+  ProtoChain<Class, ClassesOrInstances>;
+  let index: TupleIndices<typeof returnValue> = 0 as TupleIndices<typeof returnValue>;
+
+  while (baseClassProto !== current) {
+    parent = getPrototypeOf<typeof current>(current);
+    // current is a Class symbol/constructor. Object.getOwnPropertyDescriptors on current will include static properties.
+    if (!isConstructor(current))
+      break;
+    if (returnType === 'classInstances') {
+      const instanceOfCurrent = current.prototype as InstanceType<typeof current>;
+
+      returnValue[index] = instanceOfCurrent as typeof returnValue[typeof index];
+    }
+    else {
+      returnValue[index] = current as typeof returnValue[typeof index];
+    }
+
+    /**
+     * Assign the super class to current.
+     * If the argument is a class, Reflect.getPrototypeOf method returns the
+     * superclass.
+     */
+    if (
+      isConstructor(parent)
+      && 'name' in parent
+      && typeof parent.name === 'string'
+      && '' !== parent.name // it's possible for a Function/Constructor to be anonymous...
+    ) {
+      current = parent as ProtoChainOfClass<Class>[TupleIndices<ProtoChainOfClass<Class>>];
+    }
+    else {
+      break;
+    }
+    index++;
+  }
+  return returnValue;
+  /*
+    assuming current is NugetProjectProperties...
+    Reflect.getPrototypeOf(current).name is 'MSBuildProjectProperties'
+   */
+}

package/src/utils/reflection/getPrototypeOf.ts

@@ -0,0 +1,12 @@
+import type { ProtoOrSuperClass, WithProto } from './inheritance.js';
+
+/**
+ * A nearly useless wrapper for {@link Reflect.getPrototypeOf}
+ * @param object An object with the internal `__proto__` property present in its type.
+ * @returns The `__proto__` of the `object` param.
+ */
+export function getPrototypeOf<
+  T extends WithProto<ProtoOrSuperClass>,
+>(object: T): T['__proto__'] {
+  return Reflect.getPrototypeOf(object) as T['__proto__'];
+}