@augment-vir/core 30.0.0 → 30.0.1

package/README.md

@@ -0,0 +1,7 @@
+# @augment-vir/core
+
+A collection of helpers that is used within multiple `@augment-vir/*` packages.
+
+This should be imported through [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common) instead of directly installing this package.
+
+See all `@augment-vir` docs here: https://electrovir.github.io/augment-vir

package/dist/augments/array/array.d.ts

@@ -1,4 +1,28 @@
-/** Extract the element type out of an array type. */
+/**
+ * Extract the type of the elements in an array.
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type ArrayElement<ArrayType extends ReadonlyArray<any>> = ArrayType[number];
+/**
+ * Either an array of `T` or just `T` itself.
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ * @see
+ * - {@link MaybeReadonlyArray}: the readonly array version.
+ */
 export type MaybeArray<T> = T | T[];
+/**
+ * Either a readonly array of `T` or just `T` itself.
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ * @see
+ * - {@link MaybeArray}: the non-readonly array version.
+ */
 export type MaybeReadonlyArray<T> = T | ReadonlyArray<T>;

package/dist/augments/array/tuple.d.ts

@@ -1,13 +1,55 @@
-export type MappedTuple<Tuple extends ReadonlyArray<any>, NewValueType> = {
-    [I in keyof Tuple]: NewValueType;
+/**
+ * Creates a tuple with length of `OriginalTuple` with values of `NewValueType`.
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type MappedTuple<OriginalTuple extends ReadonlyArray<any>, NewValueType> = {
+    [I in keyof OriginalTuple]: NewValueType;
 };
-export type AtLeastTuple<ArrayElementGeneric, LengthGeneric extends number> = readonly [
-    ...Tuple<ArrayElementGeneric, LengthGeneric>,
-    ...ArrayElementGeneric[]
+/**
+ * Creates a tuple that is _at least_ of length `Length`.
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type AtLeastTuple<Element, Length extends number> = readonly [
+    ...Tuple<Element, Length>,
+    ...Element[]
 ];
+/**
+ * Either a tuple of `T` with length at least 1 or just `T` itself.
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type MaybeTuple<T> = T | AtLeastTuple<T, 1>;
+/**
+ * Remove the last entry in a tuple.
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type RemoveLastTupleEntry<T extends any[]> = T extends [...infer Head, any?] ? Head : any[];
+/**
+ * Remove the first entry in a tuple.
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type RemoveFirstTupleEntry<T extends any[]> = T extends [any?, ...infer Tail] ? Tail : any[];
-export type Tuple<ArrayElementGeneric, LengthGeneric extends number> = LengthGeneric extends LengthGeneric ? number extends LengthGeneric ? ArrayElementGeneric[] : _TupleOf<ArrayElementGeneric, LengthGeneric, []> : never;
+/**
+ * A tuple with entries of type `Element` and length of `Length`.
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type Tuple<Element, Length extends number> = Length extends Length ? number extends Length ? Element[] : _TupleOf<Element, Length, []> : never;
 type _TupleOf<ArrayElementGeneric, LengthGeneric extends number, FullArrayGeneric extends unknown[]> = FullArrayGeneric['length'] extends LengthGeneric ? FullArrayGeneric : _TupleOf<ArrayElementGeneric, LengthGeneric, [ArrayElementGeneric, ...FullArrayGeneric]>;
 export {};

package/dist/augments/enum/enum-type.d.ts

@@ -1 +1,8 @@
+/**
+ * A base enum type, useful for enum type parameter baselines.
+ *
+ * @category Enum
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type EnumBaseType = Record<string, number | string>;

package/dist/augments/enum/enum-values.d.ts

@@ -1,2 +1,9 @@
 import type { EnumBaseType } from './enum-type.js';
+/**
+ * Gets all values within an enum as an array.
+ *
+ * @category Enum
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function getEnumValues<T extends EnumBaseType>(input: T): T[keyof T][];

package/dist/augments/enum/enum-values.js

@@ -4,6 +4,13 @@ function getEnumKeys(input) {
     // enum keys are always strings
     return getObjectTypedKeys(input).filter((key) => isNaN(Number(key)));
 }
+/**
+ * Gets all values within an enum as an array.
+ *
+ * @category Enum
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function getEnumValues(input) {
     const keys = getEnumKeys(input);
     return keys.map((key) => input[key]);

package/dist/augments/error/ensure-error.d.ts

@@ -1,2 +1,17 @@
+/**
+ * Either returns the input if it's already an Error instance or converts it into an Error instance.
+ *
+ * @category Error
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function ensureError(maybeError: unknown): Error;
+/**
+ * Ensures that the given input is an error and prepends the given message to the ensured Error
+ * instance's message.
+ *
+ * @category Error
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function ensureErrorAndPrependMessage(maybeError: unknown, prependMessage: string): Error;

package/dist/augments/error/ensure-error.js

@@ -1,4 +1,11 @@
 import { combineErrorMessages, extractErrorMessage } from './error-message.js';
+/**
+ * Either returns the input if it's already an Error instance or converts it into an Error instance.
+ *
+ * @category Error
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function ensureError(maybeError) {
     if (maybeError instanceof Error) {
         return maybeError;
@@ -7,6 +14,14 @@ export function ensureError(maybeError) {
         return new Error(extractErrorMessage(maybeError));
     }
 }
+/**
+ * Ensures that the given input is an error and prepends the given message to the ensured Error
+ * instance's message.
+ *
+ * @category Error
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function ensureErrorAndPrependMessage(maybeError, prependMessage) {
     const error = ensureError(maybeError);
     error.message = combineErrorMessages(prependMessage, error.message);

package/dist/augments/error/error-message.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Tries its hardest to extract an error message from the input, which may be anything (not even an
+ * Error instance).
+ *
+ * @category Error
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function extractErrorMessage(maybeError: unknown): string;
 export declare function combineErrorMessages(...messages: ReadonlyArray<string | undefined>): string;
 export declare function combineErrorMessages(messages: ReadonlyArray<string | undefined>): string;

package/dist/augments/error/error-message.js

@@ -1,5 +1,13 @@
 import { stringify } from '../object/stringify.js';
 import { removeEndingPunctuation } from '../string/punctuation.js';
+/**
+ * Tries its hardest to extract an error message from the input, which may be anything (not even an
+ * Error instance).
+ *
+ * @category Error
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function extractErrorMessage(maybeError) {
     if (!maybeError) {
         return '';
@@ -17,6 +25,13 @@ export function extractErrorMessage(maybeError) {
         return stringify(maybeError);
     }
 }
+/**
+ * Combines multiple error messages into a single error message.
+ *
+ * @category Error
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function combineErrorMessages(...rawMessages) {
     const messages = (Array.isArray(rawMessages[0]) ? rawMessages[0] : rawMessages).filter((message) => {
         return message && removeEndingPunctuation(message);

package/dist/augments/function/generic-function-type.d.ts

@@ -1,2 +1,16 @@
-export type NoInputsFunction<ReturnGeneric = any> = () => ReturnGeneric;
-export type AnyFunction<ReturnGeneric = any> = (...args: any[]) => ReturnGeneric;
+/**
+ * A Function with no inputs and a return type of `Return` (which defaults to `any`).
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type NoInputsFunction<Return = any> = () => Return;
+/**
+ * A Function with any inputs and a return type of `Return` (which defaults to `any`).
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type AnyFunction<Return = any> = (...args: any[]) => Return;

package/dist/augments/function/typed-function-type.d.ts

@@ -4,6 +4,8 @@
  * instead of a rest parameter, put it inside of a tuple. If no arguments should be possible, pass
  * void to "Arguments". If you need an optional argument, pass it inside of a tuple.
  *
+ * @category Function
+ * @category Package : @augment-vir/common
  * @example
  *
  * ```ts
@@ -13,5 +15,7 @@
  * TypedFunction<[string, number], number>; // (input1: string, input2: number) => number
  * TypedFunction<[string | undefined], number>; // (input1: string|undefined) => number
  * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type TypedFunction<Arguments, Return> = Arguments extends readonly any[] ? number extends Arguments['length'] ? (...args: Arguments[number][]) => Return : (...args: Arguments) => Return : void extends Arguments ? () => Return : (arg: Arguments) => Return;

package/dist/augments/http/http-status.d.ts

@@ -4,6 +4,10 @@ import type { ArrayElement } from '../array/array.js';
  *
  * These values are automatically parsed from https://developer.mozilla.org/docs/Web/HTTP/Status via
  * https://github.com/electrovir/augment-vir/blob/dev/packages/scripts/src/scripts/generate-http-status.script.ts
+ *
+ * @category HTTP
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare enum HttpStatus {
     /** 100 level codes (information) */
@@ -479,6 +483,14 @@ export declare enum HttpStatus {
      */
     NetworkAuthenticationRequired = 511
 }
+/**
+ * All standardized HTTP status code categories. These are determined by the first number in the
+ * HTTP status code.
+ *
+ * @category HTTP
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare enum HttpStatusCategory {
     Information = "information",
     Success = "success",
@@ -486,6 +498,13 @@ export declare enum HttpStatusCategory {
     ClientError = "clientError",
     ServerError = "serverError"
 }
+/**
+ * All standardized HTTP status codes grouped into their respective categories.
+ *
+ * @category HTTP
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare const httpStatusByCategory: {
     readonly information: readonly [HttpStatus.Continue, HttpStatus.SwitchingProtocols, HttpStatus.Processing, HttpStatus.EarlyHints];
     readonly success: readonly [HttpStatus.Ok, HttpStatus.Created, HttpStatus.Accepted, HttpStatus.NonAuthoritativeInformation, HttpStatus.NoContent, HttpStatus.ResetContent, HttpStatus.PartialContent, HttpStatus.MultiStatus, HttpStatus.AlreadyReported, HttpStatus.ImUsed];
@@ -493,4 +512,11 @@ export declare const httpStatusByCategory: {
     readonly clientError: readonly [HttpStatus.BadRequest, HttpStatus.Unauthorized, HttpStatus.PaymentRequired, HttpStatus.Forbidden, HttpStatus.NotFound, HttpStatus.MethodNotAllowed, HttpStatus.NotAcceptable, HttpStatus.ProxyAuthenticationRequired, HttpStatus.RequestTimeout, HttpStatus.Conflict, HttpStatus.Gone, HttpStatus.LengthRequired, HttpStatus.PreconditionFailed, HttpStatus.PayloadTooLarge, HttpStatus.UriTooLong, HttpStatus.UnsupportedMediaType, HttpStatus.RangeNotSatisfiable, HttpStatus.ExpectationFailed, HttpStatus.ImATeapot, HttpStatus.MisdirectedRequest, HttpStatus.UnprocessableContent, HttpStatus.Locked, HttpStatus.FailedDependency, HttpStatus.TooEarly, HttpStatus.UpgradeRequired, HttpStatus.PreconditionRequired, HttpStatus.TooManyRequests, HttpStatus.RequestHeaderFieldsTooLarge, HttpStatus.UnavailableForLegalReasons];
     readonly serverError: readonly [HttpStatus.InternalServerError, HttpStatus.NotImplemented, HttpStatus.BadGateway, HttpStatus.ServiceUnavailable, HttpStatus.GatewayTimeout, HttpStatus.HttpVersionNotSupported, HttpStatus.VariantAlsoNegotiates, HttpStatus.InsufficientStorage, HttpStatus.LoopDetected, HttpStatus.NotExtended, HttpStatus.NetworkAuthenticationRequired];
 };
+/**
+ * All possible HTTP status codes for the given {@link HttpStatusCategory}.
+ *
+ * @category HTTP
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type HttpStatusByCategory<Category extends HttpStatusCategory> = ArrayElement<(typeof httpStatusByCategory)[Category]>;

package/dist/augments/http/http-status.js

@@ -3,6 +3,10 @@
  *
  * These values are automatically parsed from https://developer.mozilla.org/docs/Web/HTTP/Status via
  * https://github.com/electrovir/augment-vir/blob/dev/packages/scripts/src/scripts/generate-http-status.script.ts
+ *
+ * @category HTTP
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export var HttpStatus;
 (function (HttpStatus) {
@@ -479,6 +483,14 @@ export var HttpStatus;
      */
     HttpStatus[HttpStatus["NetworkAuthenticationRequired"] = 511] = "NetworkAuthenticationRequired";
 })(HttpStatus || (HttpStatus = {}));
+/**
+ * All standardized HTTP status code categories. These are determined by the first number in the
+ * HTTP status code.
+ *
+ * @category HTTP
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export var HttpStatusCategory;
 (function (HttpStatusCategory) {
     HttpStatusCategory["Information"] = "information";
@@ -487,6 +499,13 @@ export var HttpStatusCategory;
     HttpStatusCategory["ClientError"] = "clientError";
     HttpStatusCategory["ServerError"] = "serverError";
 })(HttpStatusCategory || (HttpStatusCategory = {}));
+/**
+ * All standardized HTTP status codes grouped into their respective categories.
+ *
+ * @category HTTP
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export const httpStatusByCategory = {
     [HttpStatusCategory.Information]: [
         HttpStatus.Continue,

package/dist/augments/narrow-type.d.ts

@@ -1,2 +1,22 @@
+/**
+ * Narrows the given `Actual` type to the given `Expected` type as much as possible, or falls back
+ * to just `Expected` itself.
+ *
+ * @category Type
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ * @see
+ *  - {@link NarrowToActual}: narrowing in the other direction.
+ */
 export type NarrowToExpected<Actual, Expected> = Extract<Expected, Actual> extends never ? Extract<Actual, Expected> extends never ? Expected extends Actual ? Expected : never : Extract<Actual, Expected> : Extract<Expected, Actual>;
+/**
+ * Narrows the given `Expected` type to the given `Actual` type as much as possible, or falls back
+ * to just `Expected` itself.
+ *
+ * @category Type
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ * @see
+ *  - {@link NarrowToExpected}: narrowing in the other direction.
+ */
 export type NarrowToActual<Actual, Expected> = Extract<Actual, Expected> extends never ? Extract<Expected, Actual> extends never ? Expected extends Actual ? Expected : never : Extract<Expected, Actual> : Extract<Actual, Expected>;

package/dist/augments/object/generic-object-type.d.ts

@@ -1,2 +1,16 @@
+/**
+ * Any object with any allowed key and `any` values.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type AnyObject = Record<PropertyKey, any>;
+/**
+ * Any object with any allowed key and `unknown` value.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type UnknownObject = Record<PropertyKey, unknown>;

package/dist/augments/object/object-keys.d.ts

@@ -1,7 +1,50 @@
+/**
+ * Gets all keys of an object. This is similar to
+ * [`Object.keys`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/keys)
+ * except that it also grabs symbol keys and has better TypeScript typing.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function getObjectTypedKeys<const ObjectGeneric>(input: ObjectGeneric): Array<keyof ObjectGeneric>;
+/**
+ * Performs `keyof` on all keys within the `OriginalObject` that have values matching the given
+ * `Matcher`.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {ExtractKeysWithMatchingValues} from '@augment-vir/common';
+ *
+ * type ExtractedKeys = ExtractKeysWithMatchingValues<{a: RegExp; b: string}, string>;
+ * // `ExtractedKeys` is `'b'`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type ExtractKeysWithMatchingValues<OriginalObject extends object, Matcher> = keyof {
     [Prop in keyof OriginalObject as OriginalObject[Prop] extends Matcher ? Prop : never]: Prop;
 };
+/**
+ * Performs `keyof` on all keys within the `OriginalObject` that have values _not_ matching the
+ * given `Matcher`.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {ExcludeKeysWithMatchingValues} from '@augment-vir/common';
+ *
+ * type ExcludedKeys = ExcludeKeysWithMatchingValues<{a: RegExp; b: string}, string>;
+ * // `ExcludedKeys` is `'a'`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type ExcludeKeysWithMatchingValues<OriginalObject extends object, Matcher> = keyof {
     [Prop in keyof OriginalObject as OriginalObject[Prop] extends Matcher ? never : Prop]: Prop;
 };

package/dist/augments/object/object-keys.js

@@ -1,3 +1,12 @@
+/**
+ * Gets all keys of an object. This is similar to
+ * [`Object.keys`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/keys)
+ * except that it also grabs symbol keys and has better TypeScript typing.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function getObjectTypedKeys(input) {
     let reflectKeys;
     try {

package/dist/augments/object/object-value-types.d.ts

@@ -1,3 +1,17 @@
 import type { CompleteRequire } from './required-keys.js';
+/**
+ * Gets all values of an object.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type Values<T> = CompleteRequire<T>[keyof T];
+/**
+ * Gets the value within an object when all its keys are required.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type ValueAtRequiredKey<Parent, Key extends keyof Parent> = CompleteRequire<Parent>[Key];

package/dist/augments/object/required-keys.d.ts

@@ -3,6 +3,10 @@ export type { SetRequired } from 'type-fest';
 /**
  * Same as the Required<> built-in type helper but this requires that each property be present and
  * be not null.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type RequiredAndNotNull<T> = {
     [P in keyof CompleteRequire<T>]-?: NonNullable<T[P]>;
@@ -10,16 +14,31 @@ export type RequiredAndNotNull<T> = {
 /**
  * Require only a subset of object properties and require that they be not null. This is
  * particularly useful in conjunction with the "exactOptionalPropertyTypes" tsconfig flag.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type SetRequiredAndNotNull<T, K extends keyof T> = Omit<T, K> & CompleteRequire<{
     [PropertyName in K]: NonNullable<T[PropertyName]>;
 }>;
+/**
+ * Sets a key as optional but also nullable.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type SetOptionalAndNullable<OriginalObjectGeneric, OptionalKeysGeneric extends keyof OriginalObjectGeneric> = Simplify<Except<OriginalObjectGeneric, OptionalKeysGeneric> & {
     [PropKey in OptionalKeysGeneric]?: OriginalObjectGeneric[PropKey] | null | undefined;
 }>;
 /**
  * Modified version of `RequiredKeys` from `type-fest` that does not require `BaseType` to extends
  * `object`.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type RequiredKeysOf<BaseType> = Exclude<{
     [Key in keyof BaseType]: BaseType extends Record<Key, BaseType[Key]> ? Key : never;
@@ -29,7 +48,9 @@ export type RequiredKeysOf<BaseType> = Exclude<{
  * `Required<Partial<T>>` doesn't fully remove `| undefined` from indexed keys when the
  * `noUncheckedIndexedAccess` TSConfig compiler option is enabled.
  *
- * @category Object:Common
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type CompleteRequire<Parent> = {
     [Prop in keyof Parent]-?: Parent extends Partial<Record<Prop, infer V>> ? V : never;

package/dist/augments/object/stringify.d.ts

@@ -1 +1,10 @@
+/**
+ * Converts the input into a string. Tries first with JSON5 and, if that fails, falls back to a
+ * regular `.toString()` conversion.
+ *
+ * @category Object
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function stringify(input: unknown): string;

package/dist/augments/object/stringify.js

@@ -1,4 +1,13 @@
 import JSON5 from 'json5';
+/**
+ * Converts the input into a string. Tries first with JSON5 and, if that fails, falls back to a
+ * regular `.toString()` conversion.
+ *
+ * @category Object
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function stringify(input) {
     try {
         return JSON5.stringify(input);

package/dist/augments/overwrite-type.d.ts

@@ -1,2 +1,8 @@
-/** Replace properties in T with properties in U. */
+/**
+ * Replace properties in T with properties in U.
+ *
+ * @category Type
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type Overwrite<T, U> = Pick<T, Exclude<keyof T, keyof U>> & U;

package/dist/augments/partial-type.d.ts

@@ -1,7 +1,23 @@
 import { AnyObject } from './object/generic-object-type.js';
+/**
+ * Allow `T` to be partial or have `null` or `undefined` as the value for any of its keys.
+ *
+ * @category Type
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type PartialWithNullable<T extends AnyObject> = {
     [Prop in keyof T]?: T[Prop] | null | undefined;
 };
+/**
+ * Allow `T` to be partial or have `undefined` as the value for any of its keys.
+ *
+ * @category Type
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type PartialWithUndefined<T extends AnyObject> = {
     [Prop in keyof T]?: T[Prop] | undefined;
 };

package/dist/augments/promise/deferred-promise.d.ts

@@ -1,7 +1,34 @@
+/**
+ * Creates a promise that can be resolved or rejected at any later time. It also includes indication
+ * on whether its been settled yet or not.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {DeferredPromise} from '@augment-vir/common';
+ *
+ * function waitForInput() {
+ *     const deferred = new DeferredPromise<string>();
+ *
+ *     window.addEventListener('keydown', (event) => {
+ *         deferred.resolve(event.code);
+ *     });
+ *     return deferred.promise;
+ * }
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare class DeferredPromise<T = void> {
+    /** The deferred promise which can be awaited. */
     promise: Promise<T>;
+    /** Call this to resolve the deferred promise with the given value. */
     resolve: (value: T | PromiseLike<T>) => void;
+    /** Call this to reject the deferred promise with the given reason. */
     reject: (reason?: any) => void;
-    isSettled: boolean;
+    /** Indicates whether the promise has been settled (resolved or rejected) yet. */
+    readonly isSettled: boolean;
     constructor();
 }

package/dist/augments/promise/deferred-promise.js

@@ -1,8 +1,35 @@
 import { ensureError } from '../error/ensure-error.js';
+/**
+ * Creates a promise that can be resolved or rejected at any later time. It also includes indication
+ * on whether its been settled yet or not.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {DeferredPromise} from '@augment-vir/common';
+ *
+ * function waitForInput() {
+ *     const deferred = new DeferredPromise<string>();
+ *
+ *     window.addEventListener('keydown', (event) => {
+ *         deferred.resolve(event.code);
+ *     });
+ *     return deferred.promise;
+ * }
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export class DeferredPromise {
+    /** The deferred promise which can be awaited. */
     promise;
+    /** Call this to resolve the deferred promise with the given value. */
     resolve;
+    /** Call this to reject the deferred promise with the given reason. */
     reject;
+    /** Indicates whether the promise has been settled (resolved or rejected) yet. */
     isSettled = false;
     constructor() {
         this.promise = new Promise((resolve, reject) => {

package/dist/augments/promise/maybe-promise.d.ts

@@ -1 +1,8 @@
+/**
+ * Either a Promise of `T` or just `T` itself.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type MaybePromise<T> = Promise<T> | T;

package/dist/augments/promise/wait.d.ts

@@ -1,3 +1,21 @@
 import { AnyDuration } from '@date-vir/duration';
+/**
+ * An async pause for the given duration.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ * @see
+ * - {@link waitValue} : return a value after the wait finishes.
+ */
 export declare function wait(duration: Readonly<AnyDuration>): Promise<void>;
+/**
+ * An async pause for the given duration that then returns the given `value`.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ * @see
+ * - {@link wait} : plain wait.
+ */
 export declare function waitValue<Value>(duration: Readonly<AnyDuration>, value: Value): Promise<Value>;

package/dist/augments/promise/wait.js

@@ -1,5 +1,14 @@
 import { convertDuration, DurationUnit } from '@date-vir/duration';
 import { DeferredPromise } from './deferred-promise.js';
+/**
+ * An async pause for the given duration.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ * @see
+ * - {@link waitValue} : return a value after the wait finishes.
+ */
 export function wait(duration) {
     const deferredPromise = new DeferredPromise();
     const milliseconds = convertDuration(duration, DurationUnit.Milliseconds).milliseconds;
@@ -10,6 +19,15 @@ export function wait(duration) {
     }
     return deferredPromise.promise;
 }
+/**
+ * An async pause for the given duration that then returns the given `value`.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ * @see
+ * - {@link wait} : plain wait.
+ */
 export async function waitValue(duration, value) {
     await wait(duration);
     return value;

package/dist/augments/runtime-env.d.ts

@@ -1,7 +1,13 @@
 /**
- * JavaScript run-time env. code, which usually has its own env definition as well.
+ * JavaScript runtime env.
  *
  * @category Env
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ * @see
+ *  - {@link currentRuntimeEnv}
+ *  - {@link isRuntimeEnv}
+ *  - {@link perEnv}
  */
 export declare enum RuntimeEnv {
     Node = "node",
@@ -12,22 +18,54 @@ export declare enum RuntimeEnv {
  * simply import {@link currentRuntimeEnv} directly.
  *
  * @category Env
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function determineRuntimeEnv(): RuntimeEnv;
 /**
- * The current {@link RuntimeEnv} value.
+ * The current {@link RuntimeEnv}.
  *
  * @category Env
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ * @see
+ *  - {@link RuntimeEnv}
+ *  - {@link isRuntimeEnv}
+ *  - {@link perEnv}
  */
 export declare const currentRuntimeEnv: RuntimeEnv;
 /**
  * Checks if the given {@link RuntimeEnv} value is the current {@link RuntimeEnv} value.
  *
  * @category Env
+ * @category Package : @augment-vir/common
  * @returns `true` if the given {@link RuntimeEnv} is the current {@link RuntimeEnv}.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ *  - {@link RuntimeEnv}
+ *  - {@link currentRuntimeEnv}
+ *  - {@link perEnv}
  */
 export declare function isRuntimeEnv(itItThisEnv: RuntimeEnv): boolean;
+/**
+ * Throw this Error to indicate that something was attempted that cannot be done in the current
+ * runtime.
+ *
+ * @category Env
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare class RuntimeEnvError extends Error {
     readonly name = "RuntimeEnvError";
 }
-export declare function forEachEnv<T>(perEnv: Record<RuntimeEnv, () => T>): T;
+/**
+ * Requires defining an object of functions for all possible {@link RuntimeEnv} values and then only
+ * calls the function for the current runtime.
+ *
+ * @category Env
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ *  - {@link RuntimeEnv}
+ *  - {@link currentRuntimeEnv}
+ *  - {@link isRuntimeEnv}
+ */
+export declare function perEnv<T>(perEnv: Record<RuntimeEnv, () => T>): T;

package/dist/augments/runtime-env.js

@@ -1,8 +1,14 @@
 import { isNode } from 'browser-or-node';
 /**
- * JavaScript run-time env. code, which usually has its own env definition as well.
+ * JavaScript runtime env.
  *
  * @category Env
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ * @see
+ *  - {@link currentRuntimeEnv}
+ *  - {@link isRuntimeEnv}
+ *  - {@link perEnv}
  */
 export var RuntimeEnv;
 (function (RuntimeEnv) {
@@ -14,6 +20,8 @@ export var RuntimeEnv;
  * simply import {@link currentRuntimeEnv} directly.
  *
  * @category Env
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function determineRuntimeEnv() {
     /** Coverage in this package is only run in Node. */
@@ -21,23 +29,53 @@ export function determineRuntimeEnv() {
     return isNode ? RuntimeEnv.Node : RuntimeEnv.Web;
 }
 /**
- * The current {@link RuntimeEnv} value.
+ * The current {@link RuntimeEnv}.
  *
  * @category Env
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ * @see
+ *  - {@link RuntimeEnv}
+ *  - {@link isRuntimeEnv}
+ *  - {@link perEnv}
  */
 export const currentRuntimeEnv = determineRuntimeEnv();
 /**
  * Checks if the given {@link RuntimeEnv} value is the current {@link RuntimeEnv} value.
  *
  * @category Env
+ * @category Package : @augment-vir/common
  * @returns `true` if the given {@link RuntimeEnv} is the current {@link RuntimeEnv}.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ *  - {@link RuntimeEnv}
+ *  - {@link currentRuntimeEnv}
+ *  - {@link perEnv}
  */
 export function isRuntimeEnv(itItThisEnv) {
     return currentRuntimeEnv === itItThisEnv;
 }
+/**
+ * Throw this Error to indicate that something was attempted that cannot be done in the current
+ * runtime.
+ *
+ * @category Env
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export class RuntimeEnvError extends Error {
     name = 'RuntimeEnvError';
 }
-export function forEachEnv(perEnv) {
+/**
+ * Requires defining an object of functions for all possible {@link RuntimeEnv} values and then only
+ * calls the function for the current runtime.
+ *
+ * @category Env
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ *  - {@link RuntimeEnv}
+ *  - {@link currentRuntimeEnv}
+ *  - {@link isRuntimeEnv}
+ */
+export function perEnv(perEnv) {
     return perEnv[currentRuntimeEnv]();
 }

package/dist/augments/string/ansi.d.ts

@@ -1,3 +1,20 @@
+/**
+ * Removes ansi escape codes (such as terminal colors) within the given string.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function removeAnsiEscapeCodes(input: string): string;
+/** {@inheritDoc removeAnsiEscapeCodes} */
 export declare const removeColor: typeof removeAnsiEscapeCodes;
+/**
+ * A RegExp that will match all ansi escape codes (such as terminal colors). Used in
+ * {@link removeAnsiEscapeCodes}.
+ *
+ * @category String
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare const ansiRegExp: RegExp;

package/dist/augments/string/ansi.js

@@ -1,6 +1,14 @@
+/**
+ * Removes ansi escape codes (such as terminal colors) within the given string.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function removeAnsiEscapeCodes(input) {
     return input.replace(ansiRegExp, '');
 }
+/** {@inheritDoc removeAnsiEscapeCodes} */
 export const removeColor = removeAnsiEscapeCodes;
 // cspell:disable
 /**
@@ -33,4 +41,13 @@ const patterns = [
     String.raw `[\u001B\u009B][[\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\d\/#&.:=?%@~_]+)*|[a-zA-Z\d]+(?:;[-a-zA-Z\d\/#&.:=?%@~_]*)*)?\u0007)`,
     String.raw `(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]))`,
 ];
+/**
+ * A RegExp that will match all ansi escape codes (such as terminal colors). Used in
+ * {@link removeAnsiEscapeCodes}.
+ *
+ * @category String
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export const ansiRegExp = new RegExp(patterns.join('|'), 'g');

package/dist/augments/string/punctuation.d.ts

@@ -1,6 +1,43 @@
 import type { ArrayElement } from '../array/array.js';
+/**
+ * All characters that are considered punctuation.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare const punctuationLetters: readonly [".", ":", ";", ",", "?", "!"];
+/**
+ * A RegExp matching all letters that are considered punctuation.
+ *
+ * @category String
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare const punctuationRegExp: RegExp;
+/**
+ * A RegExp matching that matches any punctuation at the end of a string.
+ *
+ * @category String
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare const endsWithPunctuationRegExp: RegExp;
+/**
+ * All characters that are considered punctuation.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type PunctuationLetter = ArrayElement<typeof punctuationLetters>;
+/**
+ * Removes any punctuation at the end of the given string.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function removeEndingPunctuation(value: string): string;

package/dist/augments/string/punctuation.js

@@ -1,3 +1,10 @@
+/**
+ * All characters that are considered punctuation.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export const punctuationLetters = [
     '.',
     ':',
@@ -6,8 +13,31 @@ export const punctuationLetters = [
     '?',
     '!',
 ];
+/**
+ * A RegExp matching all letters that are considered punctuation.
+ *
+ * @category String
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export const punctuationRegExp = new RegExp(`[${punctuationLetters.join('')}]+`);
+/**
+ * A RegExp matching that matches any punctuation at the end of a string.
+ *
+ * @category String
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export const endsWithPunctuationRegExp = new RegExp(`[${punctuationLetters.join('')}]+$`);
+/**
+ * Removes any punctuation at the end of the given string.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function removeEndingPunctuation(value) {
     return value.replace(endsWithPunctuationRegExp, '');
 }

package/dist/augments/string/uuid.d.ts

@@ -1,4 +1,19 @@
-/** @category String */
+/**
+ * Any of the UUID versions.
+ *
+ * @category String
+ * @category UUID
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type Uuid = `${string}-${string}-${string}-${string}-${string}`;
-/** Creates a cryptographically secure random v4 UUID using `crypto.randomUUID`. */
+/**
+ * Creates a cryptographically secure random v4 UUID using
+ * [`crypto.randomUUID`](https://developer.mozilla.org/docs/Web/API/Crypto/randomUUID).
+ *
+ * @category String
+ * @category UUID
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function createUuidV4(): `${string}-${string}-${string}-${string}-${string}`;

package/dist/augments/string/uuid.js

@@ -1,4 +1,12 @@
-/** Creates a cryptographically secure random v4 UUID using `crypto.randomUUID`. */
+/**
+ * Creates a cryptographically secure random v4 UUID using
+ * [`crypto.randomUUID`](https://developer.mozilla.org/docs/Web/API/Crypto/randomUUID).
+ *
+ * @category String
+ * @category UUID
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function createUuidV4() {
     return crypto.randomUUID();
 }

package/package.json

@@ -1,13 +1,7 @@
 {
     "name": "@augment-vir/core",
-    "version": "30.0.0",
-    "description": "Core augment-vir augments, especially including run-time environment determination.",
-    "keywords": [
-        "augment-vir",
-        "vir",
-        "core",
-        "env"
-    ],
+    "version": "30.0.1",
+    "description": "Core augment-vir augments. Use @augment-vir/common instead.",
     "homepage": "https://github.com/electrovir/augment-vir",
     "bugs": {
         "url": "https://github.com/electrovir/augment-vir/issues"
@@ -27,11 +21,9 @@
     "types": "dist/index.d.ts",
     "scripts": {
         "compile": "virmator compile",
-        "docs": "virmator docs",
         "start": "tsx src/index.ts",
         "test": "virmator test node",
         "test:coverage": "npm run test coverage",
-        "test:docs": "virmator docs check",
         "test:update": "npm test"
     },
     "dependencies": {