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

package/src/setupGitPluginSpec.ts

@@ -1,75 +1,167 @@
 import type { AssetEntry, Options as GitOptions } from '@semantic-release/git';
-import type { PluginSpec } from 'semantic-release';
+import type { PluginSpecSRGit, PluginSpecTuple } from './semanticReleaseConfig.js';
 
 export const GitPluginId = '@semantic-release/git';
-/** As specified at https://github.com/semantic-release/git#options */
+
+/**
+ * As specified at https://github.com/semantic-release/git#options
+ * To use, assign or create an object with the same (but mutable) properties and deeply-copy to the object
+ * @satisfies { GitOptions }
+ */
 export const DefaultOptions = {
-	assets: ['README.md', 'CHANGELOG.md', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json'],
-	message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
-} satisfies GitOptions;
+  assets: [
+    'README.md',
+    'CHANGELOG.md',
+    'package.json',
+    'package-lock.json',
+    'npm-shrinkwrap.json',
+  ],
+  message:
+    'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
+} as const satisfies GitOptions;
+
+/**
+ * Check if {@link unk} is an {@link AssetEntry}.
+ * @param unk Anything.
+ * @returns `true` if {@link unk} is an {@link AssetEntry}. Else, `false`.
+ */
+function isGitAsset(unk: unknown): unk is AssetEntry {
+  if (typeof unk === 'string')
+    return true;
+  // Avoid ending condition with `typeof unk.path === 'string'`.
+  // TS narrowing is bugged; requires the check to be performed TWICE!!
+  if (typeof unk === 'object' && unk != undefined && 'path' in unk) {
+    return typeof unk.path === 'string';
+  }
+  return false;
+}
+
+/**
+ * Convert one or more {@link AssetEntry AssetEntries} to a `string[]`.
+ * @param assets The `assets` property of a {@link GitOptions} object. This may not be `false`.
+ * @returns A `string[]` of the given {@link AssetEntry} objects or strings.
+ */
+function gitAssetsToStringArray(
+  assets: Exclude<GitOptions['assets'], false>,
+): string[] {
+  if (assets === undefined)
+    return [];
+  if (Array.isArray(assets)) {
+    return assets.filter(asset => isGitAsset(asset))
+      .map(v => typeof v === 'string' ? v : v.path);
+  }
+  if (typeof assets === 'string')
+    return [assets] as string[];
+  if (typeof assets.path === 'string')
+    return [assets.path];
+  else
+    throw new TypeError('assets is not typeof GitOptions[\'assets\'!');
+}
+
+/**
+ * Sanitize a {@link GitOptions} object so its {@link GitOptions#assets} property is either `false` or a `string[]`.
+ * @param opts A {@link GitOptions} object.
+ * @returns A {@link GitOptions} object whose {@link GitOptions#assets} is `string[] | false`.
+ */
+function sanitizeGitOptions(opts: GitOptions): Omit<GitOptions, 'assets'> & { assets: string[] | false } {
+  return { ...opts, assets: opts.assets === false ? opts.assets : gitAssetsToStringArray(opts.assets) };
+}
+
+/**
+ *Determine if {@link opts} is a {@link GitOptions} object.
+ * @param opts Anything.
+ * @returns `true` if {@link opts} is a {@link GitOptions} object. Else, `false`.
+ */
+function isGitOptions(opts: unknown): opts is GitOptions {
+  let isOptions = false;
+
+  if (typeof opts !== 'object' || opts == undefined)
+    return isOptions;
+  if ('assets' in opts) {
+    isOptions = Array.isArray(opts.assets)
+      ? opts.assets.every(unk => isGitAsset(unk))
+      : isGitAsset(opts.assets);
+  }
+  if ('message' in opts)
+    isOptions = typeof opts.message === 'string';
+  return isOptions;
+}
+
+/**
+ * Determine if {@link pluginSpec} includes a {@link GitOptions} object.
+ * @param pluginSpec a {@link PluginSpecTuple}.
+ * @returns `true` if {@link pluginSpec[1]} is a {@link GitOptions} object. Else, `false`.
+ */
+function hasGitOptions<P extends string>(pluginSpec: PluginSpecTuple<P>): pluginSpec is PluginSpecTuple<P, GitOptions> {
+  return isGitOptions(pluginSpec[1]);
+};
 
-function gitAssetsToArray(assets: AssetEntry | AssetEntry[] | false | undefined) {
-	if (assets === undefined || assets === false) return [];
-	if (Array.isArray(assets)) return assets;
-	if (typeof assets === 'string') return [assets];
-	return assets.path === 'string' ? [assets.path] : [];
+/**
+ * Determined if the plugin ID in {@link pluginSpec} is {@link GitPluginId}.
+ * @param pluginSpec A {@link PluginSpecTuple}
+ * @returns `true` if {@link pluginSpec[0]} is {@link GitPluginId}
+ */
+function isGitPluginSpecTuple<T>(pluginSpec: [string, T]): pluginSpec is [typeof GitPluginId, T] {
+  return pluginSpec[0] === GitPluginId;
 }
 
 /**
  * https://github.com/semantic-release/git#options
  *
  * This plugin may be deprecated at a later date.
- * Why do you need to commit during release?
- * If you don't need to update a changelog or version in a file, then you don't need this.
- *
- * @returns A {@link PluginSpec} array with {@link PluginSpec<GitOptions>}. If Git plugin not in original array, returns the original array.
- * todo: deprecate for generic or parameterized function
+ * Q: Why would I need to commit during release?
+ * A: This is for committing your changelog, README, and/or other files updated during the release procedure.
+ * @param plugins An ordered array of {@link PluginSpecTuple PluginSpecTuples}.
+ * @returns A {@link PluginSpecTuple}[]. Duplicate `@semantic-release/git` plugin entries are merged or overridden. The last entry takes priority e.g. if the last entry is `{assets: false}`, previous entries' assets are ignored.
  */
-export function setupGitPluginSpec(plugins: PluginSpec[]): PluginSpec[] {
-	let newPlugins = plugins;
-	let gitPluginIndex = -1;
-
-	function pluginSpecIsGit(pluginSpec: PluginSpec, pluginSpecIndex: number) {
-		if (pluginSpec === GitPluginId || pluginSpec[0] === GitPluginId) {
-			gitPluginIndex = pluginSpecIndex;
-			return true;
-		}
-		return false;
-	}
-
-	// if Git plugin not in load order, return as-is.
-	if (!newPlugins.some(pluginSpecIsGit)) return plugins;
+export function setupGitPluginSpec(plugins: PluginSpecTuple[]): PluginSpecTuple[] {
+  /** if Git plugin not in load order, return as-is. */
+  const firstGitPluginIndex = plugins.findIndex(plugin => isGitPluginSpecTuple(plugin));
+  if (firstGitPluginIndex === -1)
+    return plugins;
 
-	// if string, replace with tuple with default options.
-	newPlugins = newPlugins.map((plugin) =>
-		plugin === GitPluginId ? [GitPluginId, DefaultOptions] : plugin,
-	);
+  /**
+   * the following two const variables are references--not clones.
+   * Modifying them will affect the plugins array.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const firstGitPlugin = plugins[firstGitPluginIndex]!;
+  const firstGitOpts: ReturnType<typeof sanitizeGitOptions> = isGitOptions(firstGitPlugin[1])
+    ? sanitizeGitOptions(firstGitPlugin[1])
+    : DefaultOptions;
 
-	// ensure assets is an array
-	(newPlugins[gitPluginIndex][1] as GitOptions).assets = gitAssetsToArray(
-		(newPlugins[gitPluginIndex][1] as GitOptions).assets,
-	);
+  /**
+   * remove duplicate Git plugin entries;
+   * merge extra options into firstGitPlugin's options
+   * if `firstGitOpts.assets === false`, do not change it.
+   * All duplicate PluginSpecSRGit entries are then reassigned `undefined` and all
+   * `undefined` items are filtered from the plugins array.
+   */
+  return plugins.map((current: PluginSpecTuple, index): PluginSpecTuple | PluginSpecSRGit | undefined => {
+    // skip everything up to and including the first Git PluginSpec
+    if (index <= firstGitPluginIndex || !isGitPluginSpecTuple(current))
+      return current;
 
-	const discardPile: number[] = [];
+    /** if another Git PluginSpec is discovered, copy its options to the first Git PluginSpec and return undefined. */
+    if (hasGitOptions(current)) {
+      const currentGitOpts = sanitizeGitOptions(current[1]);
 
-	// de-duplicate Git plugin entries; assign single entry to newPlugins[gitPluginIndex]
-	newPlugins.forEach((current, i) => {
-		if (i > gitPluginIndex && pluginSpecIsGit(current, gitPluginIndex)) {
-			// convert its assets to an array
-			const { assets } = newPlugins[i][1] as GitOptions;
-			const { message } = newPlugins[i][1] as GitOptions;
-			// push unique assets to first entry's assets array
-			if (assets !== undefined)
-				((newPlugins[gitPluginIndex][1] as GitOptions).assets as AssetEntry[]).push(
-					...gitAssetsToArray(assets),
-				);
-			if (message !== undefined) (newPlugins[gitPluginIndex][1] as GitOptions).message = message;
-			discardPile.push(i);
-		}
-	});
-	for (const i of discardPile.sort().reverse()) {
-		newPlugins.splice(i, 1);
-	}
+      if (currentGitOpts.assets === false) {
+        firstGitOpts.assets = false;
+      }
+      else {
+        const assets: string[] = gitAssetsToStringArray(currentGitOpts.assets);
+        if (Array.isArray(firstGitOpts.assets)) {
+          firstGitOpts.assets.push(...assets);
+        }
+        else {
+          firstGitOpts.assets = assets;
+        }
+      }
 
-	return newPlugins;
+      if (typeof currentGitOpts.message === 'string')
+        firstGitOpts.message = currentGitOpts.message;
+    }
+    return undefined;
+  }).filter(pluginSpec => pluginSpec !== undefined);
 }

package/src/tsconfig.json

@@ -1,10 +1,10 @@
 {
-    "extends": "../baseTsconfig.json",
-    "compilerOptions": {
-        "outDir": "../_tsout/src",
-        "target": "ES5"
-    },
-    "include": [
-        "./**/*"
-    ]
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "../_tsout/src",
+    "isolatedDeclarations": false
+  },
+  "include": [
+    "./**/*"
+  ]
 }

package/src/utils/Exact.ts

@@ -0,0 +1,49 @@
+/**
+ * ### `Exact<T, S>`
+ *
+ * [issue](https://github.com/microsoft/TypeScript/issues/12936#issuecomment-2816928183)\
+ * [author](https://github.com/ahrjarrett)\
+ * license: unlicensed[!]
+ * @see
+ * - {@link https://tsplay.dev/NnGG6m}
+ */
+export type Exact<T, S> = [keyof T] extends [keyof S]
+  ? [T] extends [S] ? { [K in keyof T]: T[K] } : S
+  : { [K in keyof T as K extends keyof S ? never : K]: TypeError<`Excess: '${Coerce<K>}'`> };
+
+// eslint-disable-next-line jsdoc/require-jsdoc, @typescript-eslint/no-unused-vars
+function exact<S, T extends Exact<T, S>>(x: S, _y: T): T {
+  return x as unknown as T;
+};
+
+// should succeed
+exact({ a: 1 }, { a: 1 });
+exact({ a: 1, b: 'two' }, { a: 1, b: 'two' });
+
+// should raise a TypeError
+try {
+  // @ts-expect-error Type 'boolean' is not assignable to type 'TypeError<"Excess: 'c'">'.ts(2322)
+  exact({ a: 1 }, { a: 1, b: 'two', c: false });
+}
+catch { /* empty */ }
+try {
+  // @ts-expect-error Type 'number' is not assignable to type 'TypeError<"Excess: 'c'">'.ts(2322)
+  exact({ a: 1, b: 2 }, { a: 1, b: 2, c: 3 });
+}
+catch { /* empty */ }
+try {
+  // @ts-expect-error Argument of type '{ a: number; }' is not assignable to parameter of type '{ a: number; b: number; }'. Property 'b' is missing in type '{ a: number; }' but required in type '{ a: number; b: number; }'.ts(2345)
+  exact({ a: 1, b: 2 }, { a: 1 });
+}
+catch { /* empty */ }
+interface TypeError<Message> { [' TypeError']: Message }
+// prior art: use arktype's ^^^ leading whitespace trick to avoid collisions
+
+type Coerce<T> = `${T & (string | number)}`;
+
+try {
+  // @ts-expect-error Should error
+  exact({ a: 1 }, { a: 1, b: 2 });
+  //                           ^ 🚫 raises a TypeError here
+}
+catch { /* empty */ }

package/src/utils/GracefulRecursion.d.ts

@@ -0,0 +1,12 @@
+// #region https://dev.to/adrien2p/mastering-recursive-types-in-typescript-handling-depth-limitations-gracefully-5f4o#a-more-robust-solution-tuplebased-increment-and-decrement-types
+export type Length<T extends unknown[]> = (T extends { length: number } ? T['length'] : never) & number;
+export type TupleOf<N extends number, T extends unknown[] = []> = Length<T> extends N
+  ? T
+  : TupleOf<N, [...T, unknown]>;
+export type Pop<T extends unknown[]> = T extends [...infer U, unknown] ? U : never;
+// Increment adds an element to a tuple, effectively creating N + 1
+export type Increment<N extends number> = Length<[1, ...TupleOf<N>]>;
+// Decrement removes an element from a tuple, effectively creating N - 1
+export type Decrement<N extends number> = Length<Pop<TupleOf<N>>>;
+
+// #endregion https://dev.to/adrien2p/mastering-recursive-types-in-typescript-handling-depth-limitations-gracefully-5f4o#a-more-robust-solution-tuplebased-increment-and-decrement-types

package/src/utils/env.ts

@@ -0,0 +1,44 @@
+import { get,
+  config as loadDotenv,
+  type DotenvConfigOptions,
+  type GetOptions,
+} from '@dotenvx/dotenvx';
+import { env } from 'node:process';
+
+/**
+ * A thin wrapper for {@link loadDotenv}. Loads a .env file from {@link process.cwd()} with the given options (or defaults), returns the new value of {@link process.env} with optional overrides.
+ * @param [dotenvOptions] An optional {@link DotenvConfigOptions} object to pass to {@link loadDotenv}.
+ * @param [overrides] If provided, this {@link NodeJS.ProcessEnv} object is merged into the return value, overriding existing properties where overlap occurs.
+ * @returns A {@link NodeJS.ProcessEnv} object whose properties are variables loaded from the
+ * process environment, the nearest .env file, and {@link overrides} (if provided). Where
+ * overlap occurs, the later source takes priority.
+ */
+export function getEnv(dotenvOptions?: DotenvConfigOptions, overrides?: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  loadDotenv(dotenvOptions);
+
+  if (overrides)
+    Object.assign(env, overrides);
+
+  return env;
+}
+
+/**
+ * Get the value from the given env var in the current process or nearby .env file.
+ * If found in process environment, its value is returned.
+ * Else, try to get it from the nearest .env file.
+ * If NOT found, return `undefined`
+ * @param envVar The environment variable to lookup.
+ * @param [options] Options to pass to {@link get}
+ * @returns The string value of the environment variable or `undefined`.
+ * `undefined` may be returned when the variable is undefined or its string is
+ * empty, whitespace, or appears to have been converted from `null` or
+ * `undefined`.
+ */
+export function getEnvVarValue(envVar: string, options?: GetOptions): string | undefined {
+  options ??= { ignore: ['MISSING_KEY', 'MISSING_ENV_FILE'] };
+  const value = String(env[envVar] ?? get(envVar, options)).trim();
+  // I hate this. Why is undefined converted to a string?
+  return value === '' || value === 'undefined'
+    ? undefined
+    : value;
+}

package/src/utils/execAsync.ts

@@ -0,0 +1,77 @@
+/* eslint-disable jsdoc/no-defaults */
+import { type } from 'arktype';
+import { exec } from 'node:child_process';
+import { constants } from 'node:os';
+import { promisify } from 'node:util';
+import { isNativeError } from 'node:util/types';
+
+/**
+ * A `promisify(exec)` wrapper to optionally assign the child process's STDERR as the {@link Error.prototype.cause}.
+ * @see {@link promisify}, {@link exec}
+ * @param command The command to run, with space-separated arguments.
+ * @param [setStderrAsCause=false] If true and the child process's stderr is available, the thrown Error's {@link Error.prototype.cause} is assigned the stderr string.
+ * @returns A promise of the child process's STDOUT and STDERR streams as strings
+ * @throws {Error | ChildProcessSpawnException}
+ */
+export async function execAsync(command: string, setStderrAsCause = false): Promise<{
+  stdout: string;
+  stderr: string;
+}> {
+  return await promisify(exec)(command).catch((error: unknown): never => {
+    if (!isNativeError(error))
+      throw new Error(JSON.stringify(error));
+
+    if (setStderrAsCause && 'stderr' in error && typeof error.stderr === 'string' && error.stderr !== '')
+      error.cause ??= error.stderr;
+
+    if ('stdout' in error && typeof error.stdout === 'string') {
+      error.message
+        += '\nSTDOUT:\n'
+          + `  ${error.stdout.replaceAll('\n', '\n  ')}`;
+    }
+    if ('stderr' in error && typeof error.stderr === 'string') {
+      error.message
+        += '\nSTDERR:\n'
+          + `  ${error.stderr.replaceAll('\n', '\n  ')}`;
+    }
+
+    throw new ChildProcessSpawnException(error.message, error);
+  });
+}
+
+const T_ExecException = type('Error').and({
+  'cmd?': 'string | null',
+  'killed?': 'boolean | null',
+  'code?': 'number | null',
+  'signal?': type.null.or((Object.keys(constants.signals) as NodeJS.Signals[])
+    .map(v => type(`'${v}'`))
+    // eslint-disable-next-line unicorn/no-array-reduce
+    .reduce((previous, current) => previous.or(current))),
+  'stdout?': 'string',
+  'stderr?': 'string',
+});
+
+type _ExecException = typeof T_ExecException.inferOut;
+
+export class ChildProcessSpawnException extends Error implements _ExecException {
+  constructor(
+    message: Parameters<typeof Error>[0],
+    options: typeof T_ExecException.inferIn,
+  ) {
+    options = T_ExecException.from(options);
+    super(message, options);
+    this.cmd = options.cmd;
+    this.code = options.code;
+    this.killed = options.killed;
+    this.signal = options.signal;
+    this.stderr = options.stderr;
+    this.stdout = options.stdout;
+  }
+
+  cmd: typeof T_ExecException.inferOut.cmd;
+  code: typeof T_ExecException.inferOut.code;
+  killed: typeof T_ExecException.inferOut.killed;
+  signal: typeof T_ExecException.inferOut.signal;
+  stderr: typeof T_ExecException.inferOut.stderr;
+  stdout: typeof T_ExecException.inferOut.stdout;
+}

package/src/utils/miscTypes.ts

@@ -0,0 +1,17 @@
+import { type } from 'arktype';
+
+export const tBooleanString = type('"true" | "false"');
+export type BooleanString = typeof tBooleanString.infer;
+
+export const tEmptyOrBooleanString = type(tBooleanString.or('""'));
+export type EmptyOrBooleanString = typeof tEmptyOrBooleanString.infer;
+
+export type Integer<N extends number> = `${N}` extends `${number}.${number}` ? never : N;
+
+/**
+ * @see https://stackoverflow.com/a/73920140/14894786
+ */
+export type TupleIndices<T extends readonly unknown[]>
+  = Extract<keyof T, `${number}`> extends `${infer N extends number}` ? N : never;
+
+export type InstanceOrStatic = 'Instance' | 'Static';

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

@@ -0,0 +1,17 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * A generic alternative to the boxing {@link Function} type. Based on the
+ * expressions of {@link Parameters} and {@link ReturnType}.
+ * @template [T=((...args: any[] | readonly any[]) => any)] Any function-like type.
+ * @template [P=Parameters<T>]
+ * [INTERNAL] The parameters of {@link T}.
+ * @template [R=ReturnType<T>]
+ * [INTERNAL] The return type of {@link T}.
+ * @default ((...args: any[] | readonly any[]) => any)
+ * @since 3.0.0
+ */
+export type FunctionLike<
+  T extends ((...args: any[] | readonly any[]) => any) = ((...args: any[] | readonly any[]) => any),
+  P extends Parameters<T> = Parameters<T>,
+  R extends ReturnType<T> = ReturnType<T>,
+> = T & ((...args: P) => R);

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

@@ -0,0 +1,8 @@
+/**
+ * A type for casting a property descriptor to a getter descriptor.\
+ * Cast to this only after checking `typeof propertyDescriptor.get === 'function`
+ * @template [T=unknown] The type of the property.
+ * @since 4.0.0
+ */
+export type GetterDescriptor<T = unknown> = Omit<TypedPropertyDescriptor<T>, 'get'>
+  & Required<Pick<TypedPropertyDescriptor<T>, 'get'>>;

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

@@ -0,0 +1,32 @@
+import type { PropertyDescriptorMap } from './PropertyDescriptorMap.ts';
+import type {
+  BaseClassProto,
+  ConstructorConstraint,
+  InstanceTypeOrSelf,
+  SuperClassLike,
+  WithProto,
+} from './inheritance.ts';
+
+/**
+ * Generically-typed return type of `Object.GetOwnPropertyDescriptors` for class
+ * instances.
+ *
+ * Allows for statically-inferred property keys and values.
+ *
+ * Classes' `public` members are returned, including instance Getters and
+ * Setters.
+ * @template Class
+ * Any class type with its `[[Prototype]]` attached via a type-only `__proto__` property.
+ * The type of `__proto__` must extend {@link SuperClassLike} or {@link BaseClassProto}.
+ * @example
+ * ```ts
+ * const { NugetProjectProperties: NPP } = await import('../dotnet/NugetProjectProperties.js');
+ * const _instanceMembers: InstancePropertyDescriptorMap<typeof NPP>  = Object.getOwnPropertyDescriptors(new NugetProjectProperties('',new CaseInsensitiveMap([['','']])));
+ * ```
+ * @since 3.0.0
+ */
+export type InstancePropertyDescriptorMap<
+  Class extends ConstructorConstraint<Class> & WithProto<SuperClassLike | BaseClassProto>,
+> = Class['__proto__'] extends BaseClassProto
+  ? PropertyDescriptorMap<InstanceType<Class>>
+  : PropertyDescriptorMap<InstanceType<Class>, InstanceTypeOrSelf<Class['__proto__']>>;

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

@@ -0,0 +1,20 @@
+import type { BaseClassProto, ConstructorLike, InstanceTypeOrSelf, ProtoOrSuperClass, SuperClassLike, WithProto } from './inheritance.ts';
+import type { InstancePropertyDescriptorMap } from './InstancePropertyDescriptorMap.ts';
+import type { PropertyDescriptorMap } from './PropertyDescriptorMap.ts';
+
+/**
+ * Variant of {@link InstancePropertyDescriptorMap} with a lesser constraint on {@link T}.
+ * If {@link T} and/or {@link __proto__} are instantiable, the resulting
+ * property descriptor maps will be of the instances' types.
+ * @template T `null` or an `object`-like type.
+ * @template __proto__ The `[[Prototype]]` of {@link T}.
+ * @since 3.0.0
+ */
+export type InstanceTypeOrSelfPropertyDescriptorMap<
+  T extends object | null,
+  __proto__ extends ProtoOrSuperClass,
+> = T extends ConstructorLike<T>
+  ? __proto__ extends SuperClassLike | BaseClassProto
+    ? InstancePropertyDescriptorMap<T & WithProto<__proto__>>
+    : PropertyDescriptorMap<InstanceType<T>, InstanceTypeOrSelf<__proto__>>
+  : PropertyDescriptorMap<InstanceTypeOrSelf<T>, InstanceTypeOrSelf<__proto__>>;

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

@@ -0,0 +1,17 @@
+import type { GetterDescriptor } from './GetterDescriptor.ts';
+import type { OwnKeyOf } from './OwnKeyOf.js';
+
+/**
+ * # !WARNING!
+ * > This does _not_ filter out non-getter properties! ALL properties are treated as getters. Because `get` is optional and present on all property descriptors, this type should only be used to cast properties for which `typeof p.get === 'function'`.
+ *
+ * A {@link GetterDescriptorMap} variant for omitting keys inherited from {@link __proto__}.
+ * Note: If `T` is `InstanceOf<class>`, then `__proto__` must be `InstanceTypeOrSelf<__proto__>`
+ * @template T The type the descriptor map describes.
+ * @template __proto__ The `[[Prototype]]` of {@link T}. Keys of {@link __proto__} are omitted from the descriptor map type.
+ * @since 3.0.0
+ */
+export type OwnGetterDescriptorMap<
+  T,
+  __proto__ extends object | null,
+> = { [P in OwnKeyOf<T, __proto__>]: GetterDescriptor<T[P]> };

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

@@ -0,0 +1,20 @@
+/**
+ * The `keyof` type {@link T} excluding any keys of type {@link __proto__}
+ * @template T
+ * @template __proto__ `null` or any `object`-like type.
+ * @example
+ * OwnKeyOf<NPP, MSBPP> === "IsPackable" | "SuppressDependenciesWhenPacking" | "PackageVersion" | "PackageId" | "PackageDescription" | "Authors" | "Copyright" | "PackageRequireLicenseAcceptance" | "DevelopmentDependency" | "PackageLicenseExpression" | "PackageLicenseFile" | "PackageProjectUrl" | "PackageIcon" | "PackageReleaseNotes" | "PackageReadmeFile" | "PackageTags" | "PackageOutputPath" | "IncludeSymbols" | "IncludeSource" | "PackageType" | "IsTool" | "RepositoryUrl" | "RepositoryType" | "RepositoryCommit" | "SymbolPackageFormat" | "NoPackageAnalysis" | "MinClientVersion" | "IncludeBuildOutput" | "IncludeContentInPack" | "BuildOutputTargetFolder" | "ContentTargetFolders" | "NuspecFile" | "NuspecBasePath" | "NuspecProperties" | "Title" | "Company" | "Product"
+ * OwnKeyOf<typeof NPP, typeof MSBPP> === never ; // class NPP does not have non-inherited static members
+ * OwnKeyOf<typeof NPP, null> === "prototype" | "GetFullPath"
+ * @since 3.0.0
+ */
+export type OwnKeyOf<T, __proto__ extends object | null>
+  = Exclude<
+    __proto__ extends null
+      ? keyof T
+      : Exclude<
+        keyof T,
+        keyof __proto__
+      >,
+    '__proto__'
+  >;

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];