@augment-vir/common 30.0.0 → 30.0.2

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

@@ -1,2 +1,22 @@
 import { type Values } from '@augment-vir/core';
+/**
+ * Filters an object. Like
+ * [`[].filter`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/fromEntries)
+ * but for objects.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {filterObject} from '@augment-vir';
+ *
+ * filterObject({a: 1, b: 2, c: 3}, (key, value) => {
+ *     return value >= 2;
+ * });
+ * // output is `{b: 2, c: 3}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function filterObject<ObjectGeneric>(inputObject: ObjectGeneric, callback: (key: keyof ObjectGeneric, value: Values<ObjectGeneric>, fullObject: ObjectGeneric) => boolean): Partial<ObjectGeneric>;

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

@@ -1,4 +1,24 @@
 import { getObjectTypedEntries, typedObjectFromEntries } from './object-entries.js';
+/**
+ * Filters an object. Like
+ * [`[].filter`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/fromEntries)
+ * but for objects.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {filterObject} from '@augment-vir';
+ *
+ * filterObject({a: 1, b: 2, c: 3}, (key, value) => {
+ *     return value >= 2;
+ * });
+ * // output is `{b: 2, c: 3}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function filterObject(inputObject, callback) {
     const filteredEntries = getObjectTypedEntries(inputObject).filter(([key, value,]) => {
         return callback(key, value, inputObject);

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

@@ -1,2 +1,34 @@
+/**
+ * Same as the TypeScript built-in type `Omit` except that it works on actual runtime values.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {omitObjectKeys} from '@augment-vir/common';
+ *
+ * omitObjectKeys({a: 'a', b: 'b'}, ['a']);
+ * // output is `{b: 'b'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function omitObjectKeys<const ObjectGeneric, const KeyGeneric extends keyof ObjectGeneric>(inputObject: Readonly<ObjectGeneric>, omitTheseKeys: ReadonlyArray<KeyGeneric>): Omit<ObjectGeneric, KeyGeneric>;
+/**
+ * Same as the TypeScript built-in type `Pick` except that it works on actual runtime values.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {pickObjectKeys} from '@augment-vir/common';
+ *
+ * pickObjectKeys({a: 'a', b: 'b'}, ['a']);
+ * // output is `{a: 'a'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function pickObjectKeys<const ObjectGeneric, const KeyGeneric extends keyof ObjectGeneric>(inputObject: Readonly<ObjectGeneric>, pickTheseKeys: ReadonlyArray<KeyGeneric>): Pick<ObjectGeneric, KeyGeneric>;

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

@@ -1,9 +1,41 @@
 import { filterObject } from './object-filter.js';
+/**
+ * Same as the TypeScript built-in type `Omit` except that it works on actual runtime values.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {omitObjectKeys} from '@augment-vir/common';
+ *
+ * omitObjectKeys({a: 'a', b: 'b'}, ['a']);
+ * // output is `{b: 'b'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function omitObjectKeys(inputObject, omitTheseKeys) {
     return filterObject(inputObject, (currentKey) => {
         return !omitTheseKeys.includes(currentKey);
     });
 }
+/**
+ * Same as the TypeScript built-in type `Pick` except that it works on actual runtime values.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {pickObjectKeys} from '@augment-vir/common';
+ *
+ * pickObjectKeys({a: 'a', b: 'b'}, ['a']);
+ * // output is `{a: 'a'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function pickObjectKeys(inputObject, pickTheseKeys) {
     return filterObject(inputObject, (currentKey) => {
         return pickTheseKeys.includes(currentKey);

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

@@ -1,2 +1,11 @@
 import { CompleteRequire } from '@augment-vir/core';
+/**
+ * Gets an object's values. This is the same as
+ * [`Object.values`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/values)
+ * except that it has better TypeScript types.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function getObjectTypedValues<ObjectGeneric>(input: ObjectGeneric): CompleteRequire<ObjectGeneric>[keyof CompleteRequire<ObjectGeneric>][];

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

@@ -1,4 +1,13 @@
 import { getObjectTypedKeys } from '@augment-vir/core';
+/**
+ * Gets an object's values. This is the same as
+ * [`Object.values`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/values)
+ * except that it has better TypeScript types.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function getObjectTypedValues(input) {
     return getObjectTypedKeys(input).map((key) => input[key]);
 }

package/dist/augments/path/esm-path.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Creates the equivalent of CJS's
+ * [`__dirname`](https://nodejs.org/docs/latest/api/globals.html#__dirname) and
+ * [`__filename`](https://nodejs.org/docs/latest/api/globals.html#__filename) for ESM modules.
+ *
+ * This is the equivalent of
+ * [`import.meta.dirname`](https://nodejs.org/api/esm.html#importmetadirname) and
+ * [`import.meta.filename`](https://nodejs.org/api/esm.html#importmetafilename) added to Node.js
+ * v20.11.0 but is compatible with older versions of Node.js as well as browsers.
+ *
+ * @category Path : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {getEsmPath} from '@augment-vir/common';
+ *
+ * const {filePath, dirPath} = getEsmPath(import.meta);
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function getEsmPath(importMeta: ImportMeta): {
+    filePath: string;
+    dirPath: string;
+};

package/dist/augments/path/esm-path.js

@@ -0,0 +1,31 @@
+import { removeSuffix } from '../string/suffix.js';
+/**
+ * Creates the equivalent of CJS's
+ * [`__dirname`](https://nodejs.org/docs/latest/api/globals.html#__dirname) and
+ * [`__filename`](https://nodejs.org/docs/latest/api/globals.html#__filename) for ESM modules.
+ *
+ * This is the equivalent of
+ * [`import.meta.dirname`](https://nodejs.org/api/esm.html#importmetadirname) and
+ * [`import.meta.filename`](https://nodejs.org/api/esm.html#importmetafilename) added to Node.js
+ * v20.11.0 but is compatible with older versions of Node.js as well as browsers.
+ *
+ * @category Path : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {getEsmPath} from '@augment-vir/common';
+ *
+ * const {filePath, dirPath} = getEsmPath(import.meta);
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function getEsmPath(importMeta) {
+    const filePath = new URL('', importMeta.url).pathname;
+    const dirPath = removeSuffix({ value: new URL('.', importMeta.url).pathname, suffix: '/' });
+    return {
+        filePath,
+        dirPath,
+    };
+}

package/dist/augments/prisma/base-prisma-types.d.ts

@@ -0,0 +1,38 @@
+import { AnyObject, type AnyFunction } from '@augment-vir/core';
+/**
+ * A base type for Prisma model payloads because Prisma doesn't give us one. This currently only
+ * includes the properties that are used within this package.
+ *
+ * Note: this omits the `composites` property because I don't have any examples of what those
+ * actually are.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type BasePrismaPayload = {
+    name: string;
+    objects: Record<string, BasePrismaPayload | BasePrismaPayload[] | null>;
+    scalars: AnyObject;
+};
+/**
+ * Base Prisma client type that all `PrismaClient` instances should be able to match, with enough
+ * data that it'll omit random accidental objects.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type BasePrismaClient = {
+    $connect: AnyFunction;
+    $disconnect: AnyFunction;
+    $executeRaw: AnyFunction;
+    $executeRawUnsafe: AnyFunction;
+    $extends: AnyFunction;
+    $on: AnyFunction;
+    $queryRaw: AnyFunction;
+    $queryRawUnsafe: AnyFunction;
+    $transaction: AnyFunction;
+} & {
+    [ModelName in string]: any;
+};

package/dist/augments/prisma/prisma-basic-model.d.ts

@@ -0,0 +1,29 @@
+import type { BasePrismaClient } from './base-prisma-types.js';
+import type { PrismaModelName } from './prisma-model-name.js';
+/**
+ * A basic model entry with only its immediate properties.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import type {PrismaClient} from '@prisma/client';
+ * import type {PrismaBasicModel} from '@augment-vir/common';
+ *
+ * function doThing(fullModel: PrismaBasicModel<PrismaClient, 'user'>) {}
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type PrismaBasicModel<PrismaClient extends BasePrismaClient, Model extends PrismaModelName<PrismaClient>> = PrismaClient['model'][Model]['payload']['scalars'];
+/**
+ * Basic model entries for all models in the database.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type PrismaAllBasicModels<PrismaClient extends BasePrismaClient> = Partial<{
+    [ModelName in PrismaModelName<PrismaClient>]: PrismaBasicModel<PrismaClient, ModelName>[];
+}>;

package/dist/augments/prisma/prisma-basic-model.js

@@ -0,0 +1 @@
+export {};

package/dist/augments/prisma/prisma-full-model.d.ts

@@ -0,0 +1,37 @@
+import { type BasePrismaClient, type BasePrismaPayload } from './base-prisma-types.js';
+import type { PrismaModelName } from './prisma-model-name.js';
+/**
+ * A full model entry with all relations from the given Prisma type map and model name.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import type {Prisma} from '@prisma/client';
+ * import type {FullPrismaModel} from '@augment-vir/common';
+ *
+ * function doThing(fullModel: FullModel<Prisma.TypeMap, 'User'>) {}
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type PrismaFullModel<PrismaClient extends BasePrismaClient, Model extends PrismaModelName<PrismaClient>> = ExpandPrismaTypeMapPayload<PrismaClient[Model][symbol]['types']['payload']>;
+/**
+ * Expand a Prisma payload into its scalars and recursive relations.
+ *
+ * @category Prisma : Common : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type ExpandPrismaTypeMapPayload<Payload extends BasePrismaPayload> = Payload['scalars'] & {
+    [Key in keyof Payload['objects']]: ExpandPotentialArrayPrismaTypeMapPayload<NonNullable<Payload['objects'][Key]>> | (null extends Payload['objects'][Key] ? null : never);
+};
+/**
+ * Expand a payload that might be inside of an array, keeping it inside of an array if it is.
+ *
+ * @category Prisma : Common : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type ExpandPotentialArrayPrismaTypeMapPayload<PayloadWrapper extends BasePrismaPayload | BasePrismaPayload[]> = PayloadWrapper extends (infer ActualPayload extends BasePrismaPayload)[] ? ExpandPrismaTypeMapPayload<ActualPayload>[] : PayloadWrapper extends BasePrismaPayload ? ExpandPrismaTypeMapPayload<PayloadWrapper> : never;

package/dist/augments/prisma/prisma-full-model.js

@@ -0,0 +1 @@
+export {};

package/dist/augments/prisma/prisma-model-create.d.ts

@@ -0,0 +1,159 @@
+import type { BasePrismaClient } from './base-prisma-types.js';
+import type { PrismaModelName } from './prisma-model-name.js';
+/**
+ * Use this to define mock entries that _shouldn't_ be saved to the database so that we can easily
+ * write tests for missing data.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import type {PrismaClient} from '@prisma/client';
+ * import {prismaModelCreateExclude, PrismaKeyedModelCreate} from '@augment-vir/common';
+ *
+ * export const mockUsers = {
+ *     user1: {
+ *         id: 1,
+ *         authRole: 'admin',
+ *     },
+ *     missingUser: {
+ *         id: -1,
+ *         authRole: 'user',
+ *         [prismaModelCreateExclude]: true,
+ *     },
+ * } as const satisfies PrismaKeyedModelCreate<PrismaClient, 'User'>;
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare const prismaModelCreateExclude: unique symbol;
+/**
+ * Use this to prevent the id property from being included when creating a mock record, allowing the
+ * database's internal auto-increment functionality to generate one. This is necessary when testing
+ * creation of new records because manually specified ids do not increment the auto incrementor.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import type {PrismaClient} from '@prisma/client';
+ * import {prismaModelCreateOmitId, PrismaKeyedModelCreate} from '@augment-vir/common';
+ *
+ * export const mockUsers = {
+ *     user1: {
+ *         id: 1,
+ *         authRole: 'admin',
+ *         [prismaModelCreateOmitId]: true,
+ *     },
+ *     user2: {
+ *         id: 2,
+ *         authRole: 'admin',
+ *         [prismaModelCreateOmitId]: true,
+ *     },
+ * } as const satisfies PrismaKeyedModelCreate<PrismaClient, 'User'>;
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare const prismaModelCreateOmitId: unique symbol;
+/**
+ * Extracts the creation data for a model from the given `PrismaClient` type.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import type {PrismaClient} from '@prisma/client';
+ * import type {PrismaModelCreate} from '@augment-vir/common';
+ *
+ * function doThing(entry: PrismaModelCreate<PrismaClient, 'User'>) {}
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type PrismaModelCreate<PrismaClient extends BasePrismaClient, Model extends PrismaModelName<PrismaClient>> = NonNullable<Parameters<PrismaClient[Model]['create']>[0]> extends {
+    data?: infer Data;
+} ? NonNullable<Data> & Partial<{
+    [prismaModelCreateExclude]: true;
+    [prismaModelCreateOmitId]: true;
+}> : `ERROR: failed to infer creation entry for model '${Model}'`;
+/**
+ * A type for creating multiple Prisma create mocks that are named for future reference.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {PrismaKeyedModelCreate} from '@augment-vir/common';
+ * import type {PrismaClient} from '@prisma/client';
+ *
+ * const mockUsers = {
+ *     mockUser1: {
+ *         first_name: 'one',
+ *         id: 123,
+ *         // etc.
+ *     },
+ *     mockUser2: {
+ *         first_name: 'two',
+ *         id: 124,
+ *         auth_role: 'user',
+ *         // etc.
+ *     },
+ * } as const satisfies PrismaKeyedModelCreate<PrismaClient, 'User'>;
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type PrismaKeyedModelCreate<PrismaClient extends BasePrismaClient, Model extends PrismaModelName<PrismaClient>> = {
+    [EntryName in string]: PrismaModelCreate<PrismaClient, Model>;
+};
+/**
+ * Model create data stored by model name in either array or keyed form. Used in
+ * `prisma.client.addData()` from `@augment-vir/node`.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {PrismaKeyedModelCreate} from '@augment-vir/common';
+ * import type {PrismaClient} from '@prisma/client';
+ *
+ * const mockData: ModelCreateData<PrismaClient> = {
+ *     user: {
+ *         mockUser1: {
+ *             first_name: 'one',
+ *             id: 123,
+ *             // etc.
+ *         },
+ *         mockUser2: {
+ *             first_name: 'two',
+ *             id: 124,
+ *             auth_role: 'user',
+ *             // etc.
+ *         },
+ *     },
+ *     region: [
+ *         {
+ *             id: 1,
+ *             name: 'North America',
+ *             // etc.
+ *         },
+ *         {
+ *             id: 2,
+ *             name: 'Europe',
+ *             // etc.
+ *         },
+ *     ],
+ * };
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type PrismaAllModelsCreate<PrismaClient extends BasePrismaClient> = Readonly<Partial<{
+    [Model in PrismaModelName<PrismaClient>]: Readonly<PrismaKeyedModelCreate<PrismaClient, Model>> | ReadonlyArray<Readonly<PrismaModelCreate<PrismaClient, Model>>>;
+}>>;

package/dist/augments/prisma/prisma-model-create.js

@@ -0,0 +1,58 @@
+/**
+ * Use this to define mock entries that _shouldn't_ be saved to the database so that we can easily
+ * write tests for missing data.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import type {PrismaClient} from '@prisma/client';
+ * import {prismaModelCreateExclude, PrismaKeyedModelCreate} from '@augment-vir/common';
+ *
+ * export const mockUsers = {
+ *     user1: {
+ *         id: 1,
+ *         authRole: 'admin',
+ *     },
+ *     missingUser: {
+ *         id: -1,
+ *         authRole: 'user',
+ *         [prismaModelCreateExclude]: true,
+ *     },
+ * } as const satisfies PrismaKeyedModelCreate<PrismaClient, 'User'>;
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export const prismaModelCreateExclude = Symbol('prisma-model-create-exclude');
+/**
+ * Use this to prevent the id property from being included when creating a mock record, allowing the
+ * database's internal auto-increment functionality to generate one. This is necessary when testing
+ * creation of new records because manually specified ids do not increment the auto incrementor.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import type {PrismaClient} from '@prisma/client';
+ * import {prismaModelCreateOmitId, PrismaKeyedModelCreate} from '@augment-vir/common';
+ *
+ * export const mockUsers = {
+ *     user1: {
+ *         id: 1,
+ *         authRole: 'admin',
+ *         [prismaModelCreateOmitId]: true,
+ *     },
+ *     user2: {
+ *         id: 2,
+ *         authRole: 'admin',
+ *         [prismaModelCreateOmitId]: true,
+ *     },
+ * } as const satisfies PrismaKeyedModelCreate<PrismaClient, 'User'>;
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export const prismaModelCreateOmitId = Symbol('prisma-model-create-exclude-id');

package/dist/augments/prisma/prisma-model-name.d.ts

@@ -0,0 +1,18 @@
+import { BasePrismaClient } from './base-prisma-types.js';
+/**
+ * Extracts all model names from a generated `PrismaClient`.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import type {PrismaClient} from '@prisma/client';
+ * import type {PrismaModelName} from '@augment-vir/common';
+ *
+ * function doThing(modelName: PrismaModelName<PrismaClient>) {}
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type PrismaModelName<PrismaClient extends BasePrismaClient> = Exclude<keyof PrismaClient, `$${string}` | symbol>;

package/dist/augments/prisma/prisma-model-name.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,7 +1,22 @@
 import { AnyDuration } from '@date-vir/duration';
+/**
+ * An error thrown by {@link wrapPromiseInTimeout} when the timeout is reached.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare class PromiseTimeoutError extends Error {
     readonly duration: AnyDuration;
     readonly name = "PromiseTimeoutError";
     constructor(duration: AnyDuration, failureMessage?: string | undefined);
 }
+/**
+ * Wraps an already-created Promise in a timeout, causing a rejection if the original Promise isn't
+ * resolved by then.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function wrapPromiseInTimeout<T>(duration: Readonly<AnyDuration>, originalPromise: PromiseLike<T>, failureMessage?: string | undefined): Promise<T>;

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

@@ -1,6 +1,13 @@
 import { check } from '@augment-vir/assert';
 import { ensureError } from '@augment-vir/core';
 import { convertDuration, DurationUnit } from '@date-vir/duration';
+/**
+ * An error thrown by {@link wrapPromiseInTimeout} when the timeout is reached.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export class PromiseTimeoutError extends Error {
     duration;
     name = 'PromiseTimeoutError';
@@ -14,6 +21,14 @@ export class PromiseTimeoutError extends Error {
         this.duration = duration;
     }
 }
+/**
+ * Wraps an already-created Promise in a timeout, causing a rejection if the original Promise isn't
+ * resolved by then.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function wrapPromiseInTimeout(duration, originalPromise, failureMessage) {
     const milliseconds = convertDuration(duration, DurationUnit.Milliseconds).milliseconds;
     return new Promise(async (resolve, reject) => {

package/dist/augments/random/random-boolean.d.ts

@@ -6,13 +6,19 @@
  *
  * This function uses cryptographically secure randomness.
  *
+ * @category Random
+ * @category Package : @augment-vir/common
  * @example
  *
  * ```ts
+ * import {randomBoolean} from '@augment-vir/common';
+ *
  * randomBoolean(50); // 50% chance to return true
  * randomBoolean(0); // always false, 0% chance of being true
  * randomBoolean(100); // always true, 100% chance of being true
  * randomBoolean(59.67); // 59% chance of being true
  * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function randomBoolean(percentLikelyToBeTrue?: number): boolean;

package/dist/augments/random/random-boolean.js

@@ -8,14 +8,20 @@ import { randomInteger } from './random-integer.js';
  *
  * This function uses cryptographically secure randomness.
  *
+ * @category Random
+ * @category Package : @augment-vir/common
  * @example
  *
  * ```ts
+ * import {randomBoolean} from '@augment-vir/common';
+ *
  * randomBoolean(50); // 50% chance to return true
  * randomBoolean(0); // always false, 0% chance of being true
  * randomBoolean(100); // always true, 100% chance of being true
  * randomBoolean(59.67); // 59% chance of being true
  * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function randomBoolean(percentLikelyToBeTrue = 50) {
     return (randomInteger({ min: 0, max: 99 }) <