Improve assert docs

.changeset/serious-maps-flash.md

@@ -0,0 +1,5 @@
+---
+"@httpx/assert": patch
+---
+
+Improve documentation

README.md

@@ -2,13 +2,12 @@
 
 ### [@httpx/assert](https://github.com/belgattitude/httpx/tree/main/packages/assert#readme)
 
-Assertions and typeguards 
+Lightweight assertions and typeguards starting at [~60b](https://github.com/belgattitude/httpx/tree/main/packages/assert#bundle-size). 
 
 [![npm](https://img.shields.io/npm/v/@httpx/assert?style=for-the-badge&label=Npm&labelColor=444&color=informational)](https://www.npmjs.com/package/@httpx/assert)
 [![changelog](https://img.shields.io/static/v1?label=&message=changelog&logo=github&style=for-the-badge&labelColor=444&color=informational)](https://github.com/belgattitude/httpx/blob/main/packages/assert/CHANGELOG.md)
 [![codecov](https://img.shields.io/codecov/c/github/belgattitude/httpx?logo=codecov&label=Unit&flag=httpx-assert-unit&style=for-the-badge&labelColor=444)](https://app.codecov.io/gh/belgattitude/httpx/tree/main/packages%2Fassert)
 [![bundles](https://img.shields.io/static/v1?label=&message=cjs|esm@treeshake&logo=webpack&style=for-the-badge&labelColor=444&color=informational)](https://github.com/belgattitude/httpx/blob/main/packages/assert/.size-limit.cjs)
-[![maintainability](https://img.shields.io/codeclimate/maintainability/belgattitude/httpx?label=Quality&logo=code-climate&style=for-the-badge&labelColor=444)](https://codeclimate.com/github/belgattitude/httpx)
 [![downloads](https://img.shields.io/npm/dm/@httpx/assert?style=for-the-badge&labelColor=444)](https://www.npmjs.com/package/@httpx/assert)
 
 
@@ -23,7 +22,6 @@ to cover cross-environments challenges (RSC, SSR...).
 [![changelog](https://img.shields.io/static/v1?label=&message=changelog&logo=github&style=for-the-badge&labelColor=444&color=informational)](https://github.com/belgattitude/httpx/blob/main/packages/exception/CHANGELOG.md)
 [![codecov](https://img.shields.io/codecov/c/github/belgattitude/httpx?logo=codecov&label=Unit&flag=httpx-exception-unit&style=for-the-badge&labelColor=444)](https://app.codecov.io/gh/belgattitude/httpx/tree/main/packages%2Fexception)
 [![bundles](https://img.shields.io/static/v1?label=&message=cjs|esm@treeshake&logo=webpack&style=for-the-badge&labelColor=444&color=informational)](https://github.com/belgattitude/httpx/blob/main/packages/exception/.size-limit.cjs)
-[![maintainability](https://img.shields.io/codeclimate/maintainability/belgattitude/httpx?label=Quality&logo=code-climate&style=for-the-badge&labelColor=444)](https://codeclimate.com/github/belgattitude/httpx)
 [![downloads](https://img.shields.io/npm/dm/@httpx/exception?style=for-the-badge&labelColor=444)](https://www.npmjs.com/package/@httpx/exception)
 
 ### [@httpx/dsn-parser](https://github.com/belgattitude/httpx/tree/main/packages/dsn-parser#readme)
@@ -34,7 +32,6 @@ DSN & JDBC string parser with query params support in a light and modern package
 [![changelog](https://img.shields.io/static/v1?label=&message=changelog&logo=github&style=for-the-badge&labelColor=444&color=informational)](https://github.com/belgattitude/httpx/blob/main/packages/dsn-parser/CHANGELOG.md)
 [![codecov](https://img.shields.io/codecov/c/github/belgattitude/httpx?logo=codecov&label=Unit&flag=httpx-dsn-parser-unit&style=for-the-badge&labelColor=444)](https://app.codecov.io/gh/belgattitude/httpx/tree/main/packages%2Fdsn-parser)
 [![bundles](https://img.shields.io/static/v1?label=&message=cjs|esm@treeshake&logo=webpack&style=for-the-badge&labelColor=444&color=informational)](https://github.com/belgattitude/httpx/blob/main/packages/dsn-parser/.size-limit.cjs)
-[![maintainability](https://img.shields.io/codeclimate/maintainability/belgattitude/httpx?label=Quality&logo=code-climate&style=for-the-badge&labelColor=444)](https://codeclimate.com/github/belgattitude/httpx)
 [![downloads](https://img.shields.io/npm/dm/@httpx/dsn-parser?style=for-the-badge&labelColor=444)](https://www.npmjs.com/package/@httpx/dsn-parser)
 
 

docs/src/pages/assert/index.mdx

@@ -46,6 +46,52 @@ Wip
 
 👉 [Official website](https://belgattitude.github.io/httpx/assert), [Github Readme](https://github.com/belgattitude/httpx/tree/main/packages/assert#readme) or [generated api doc]()
 
+## Introduction
+
+### Consistent style
+
+Typeguards starts with `isXXX` and have an assertion counterpart named `assertXXX`.
+
+### Assertions error messages
+
+When an assertion fail, a native [TypeError](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError)
+is thrown by default with a message indicating the requirement and and information about the
+tested value. As an example:
+
+```typescript
+expect(() => assertUuid('123')).toThrow(
+  new TypeError('Value is expected to be an uuid, got: string(length:3)')
+);
+expect(() => assertUuid(false, undefined, { version: 1 })).toThrow(
+  new TypeError('Value is expected to be an uuid v1, got: boolean(false)')
+);
+expect(() => assertUuidV1(Number.NaN)).toThrow(
+  new TypeError('Value is expected to be an uuid v1, got: NaN')
+);
+expect(() => assertUuidV3(new Error())).toThrow(
+  new TypeError('Value is expected to be an uuid v3, got: Error')
+);
+expect(() => assertUuidV4(new Date())).toThrow(
+  new TypeError('Value is expected to be an uuid v4, got: Date')
+);
+expect(() => assertUuidV5(() => {})).toThrow(
+  new TypeError('Value is expected to be an uuid v5, got: function')
+);
+//...
+```
+
+Alternatively it's possible to provide either a message or function returning
+an Error. For example:
+
+```typescript
+import { assertEan13 } from '@httpx/assert';
+import { HttpBadRequest } from '@httpx/exception';
+
+assertEan13('123', 'Not a barcode'); // 👈 Will throw a TypeError('Not a barcode')
+
+assertStrNotEmpty(lang, () => new HttpBadRequest('Missing language'));
+```
+
 ## Usage
 
 ### Type related
@@ -130,7 +176,6 @@ isStrParsableSafeInt(`${Number.MAX_SAFE_INTEGER}`); // 👉 true
 assertStrParsableSafeInt(`${Number.MAX_SAFE_INTEGER}1`); // 👉 throws
 ```
 
-
 ### Uuid
 
 #### isUuid
@@ -202,6 +247,13 @@ ESM individual imports are tracked by a
 
 > For _older_ browsers: most frontend frameworks can transpile the library (ie: [nextjs](https://nextjs.org/docs/app/api-reference/next-config-js/transpilePackages)...)
 
+## Acknowledgments
+
+Special thanks for inspiration:
+
+- [sindresorhus/is](https://github.com/sindresorhus/is)
+- [webmozarts/assert](https://github.com/webmozarts/assert)
+
 ## Contributors
 
 Contributions are warmly appreciated. Have a look to the [CONTRIBUTING](https://github.com/belgattitude/httpx/blob/main/CONTRIBUTING.md) document.

packages/assert/README.md

@@ -23,23 +23,81 @@ $ pnpm add @httpx/assert
 
 ## Features
 
-Wip
+- 👉  Typeguards and assertions with a consistent style.
+- 🦄  Assertions with useful [default error message](#assertions-error-messages).
+- 🖖  Optimized tree-shakability, starts at [56b](#bundle-size). 
+- 🛡️  Don't leak values in the default assertion error messages.
+- 🤗  No deps. [Node, browser and edge support](#compatibility).
 
 ## Documentation
 
 👉 [Official website](https://belgattitude.github.io/httpx/assert), [GitHub Readme](https://github.com/belgattitude/httpx/tree/main/packages/assert#readme) or [generated api doc](https://github.com/belgattitude/httpx/blob/main/packages/assert/docs/api/README.md)
 
+---
+
+- [Introduction](#introduction)
+  * [Consistent style](#consistent-style)
+  * [Assertions error messages](#assertions-error-messages)
 - [Usage](#usage)
   * [Type related](#type-related)
   * [Object related](#object-related)
+  * [Number related](#number-related)
+  * [Array related](#array-related)
   * [String related](#string-related)
   * [Uuid](#uuid)
   * [Barcode](#barcode)
 - [Bundle size](#bundle-size)
 - [Compatibility](#compatibility)
+- [Acknowledgments](#acknowledgments)
 - [Contributors](#contributors)
 - [Sponsors](#sponsors)
 
+## Introduction
+
+### Consistent style
+
+Typeguards starts with `isXXX` and have an assertion counterpart named `assertXXX`.
+
+### Assertions error messages
+
+When an assertion fail, a native [TypeError](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError) 
+is thrown by default with a message indicating the requirement and and information about the
+tested value. As an example:
+
+```typescript
+expect(() => assertUuid('123')).toThrow(
+  new TypeError('Value is expected to be an uuid, got: string(length:3)')
+);
+expect(() => assertUuid(false, undefined, { version: 1 })).toThrow(
+  new TypeError('Value is expected to be an uuid v1, got: boolean(false)')
+);
+expect(() => assertUuidV1(Number.NaN)).toThrow(
+  new TypeError('Value is expected to be an uuid v1, got: NaN')
+);
+expect(() => assertUuidV3(new Error())).toThrow(
+  new TypeError('Value is expected to be an uuid v3, got: Error')
+);
+expect(() => assertUuidV4(new Date())).toThrow(
+  new TypeError('Value is expected to be an uuid v4, got: Date')
+);
+expect(() => assertUuidV5(() => {})).toThrow(
+  new TypeError('Value is expected to be an uuid v5, got: function')
+);
+//...
+```
+
+Alternatively it's possible to provide either a message or function returning
+an Error. For example:
+
+```typescript
+import { assertEan13 } from '@httpx/assert';
+import { HttpBadRequest } from '@httpx/exception';
+
+assertEan13('123', 'Not a barcode'); // 👈 Will throw a TypeError('Not a barcode')
+
+assertStrNotEmpty(lang, () => new HttpBadRequest('Missing language'));
+```
+
 ## Usage
 
 ### Type related
@@ -124,7 +182,6 @@ isStrParsableSafeInt(`${Number.MAX_SAFE_INTEGER}`); // 👉 true
 assertStrParsableSafeInt(`${Number.MAX_SAFE_INTEGER}1`); // 👉 throws
 ```
 
-
 ### Uuid
 
 #### isUuid
@@ -196,6 +253,13 @@ ESM individual imports are tracked by a
 
 > For _older_ browsers: most frontend frameworks can transpile the library (ie: [nextjs](https://nextjs.org/docs/app/api-reference/next-config-js/transpilePackages)...)
 
+## Acknowledgments
+
+Special thanks for inspiration: 
+
+- [sindresorhus/is](https://github.com/sindresorhus/is)
+- [webmozarts/assert](https://github.com/webmozarts/assert)
+
 ## Contributors
 
 Contributions are warmly appreciated. Have a look to the [CONTRIBUTING](https://github.com/belgattitude/httpx/blob/main/CONTRIBUTING.md) document.