From 54597687b33ad2caf1c6549f4474dde09ab2dbd6 Mon Sep 17 00:00:00 2001 From: Alex Reardon Date: Fri, 23 Feb 2024 10:31:23 +1100 Subject: [PATCH] adding jsdoc --- src/tiny-invariant.ts | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/src/tiny-invariant.ts b/src/tiny-invariant.ts index 6c82392..72edc6b 100644 --- a/src/tiny-invariant.ts +++ b/src/tiny-invariant.ts @@ -1,13 +1,28 @@ const isProduction: boolean = process.env.NODE_ENV === 'production'; const prefix: string = 'Invariant failed'; -// Throw an error if the condition fails -// Strip out error messages for production -// > Not providing an inline default argument for message as the result is smaller +/** + * `invariant` is used to [assert](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions) that the `condition` is [truthy](https://github.com/getify/You-Dont-Know-JS/blob/bdbe570600d4e1107d0b131787903ca1c9ec8140/up%20%26%20going/ch2.md#truthy--falsy). + * + * 💥 `invariant` will `throw` an `Error` if the `condition` is [falsey](https://github.com/getify/You-Dont-Know-JS/blob/bdbe570600d4e1107d0b131787903ca1c9ec8140/up%20%26%20going/ch2.md#truthy--falsy) + * + * 🤏 `message`s are not displayed in production environments to help keep bundles small + * + * @example + * + * ```ts + * const value: Person | null = { name: 'Alex' }; + * invariant(value, 'Expected value to be a person'); + * // type of `value`` has been narrowed to `Person` + * ``` + */ export default function invariant( condition: any, - // Can provide a string, or a function that returns a string for cases where - // the message takes a fair amount of effort to compute + // Not providing an inline default argument for message as the result is smaller + /** + * Can provide a string, or a function that returns a string for cases where + * the message takes a fair amount of effort to compute + */ message?: string | (() => string), ): asserts condition { if (condition) {