From 692333171e3d911e31232597a2921ed44ce84ff5 Mon Sep 17 00:00:00 2001 From: Lucas Tortora Date: Wed, 5 Aug 2026 17:01:21 -0300 Subject: [PATCH 1/5] chore: document the public API (TSDoc + README) from the type declarations Co-Authored-By: Claude Opus 4.8 --- README.md | 69 ++++++++++++++++++++---------------------------------- index.d.ts | 10 ++++++++ 2 files changed, 36 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index b7fdaeb..677fa66 100644 --- a/README.md +++ b/README.md @@ -17,69 +17,52 @@ assert.equal(1, 1) assert.notEqual(1, 2) ``` -## API - -#### `assert(value[, message])` - -Throws an `AssertionError` unless `value` is truthy. If `message` is an `Error` instance, it is thrown directly instead of being wrapped in an `AssertionError`. - -#### `assert.AssertionError` - -An `Error` subclass thrown by all assertions on failure. Instances have the following properties: - -#### `error.actual` - -The `actual` value passed to the assertion, if any. + -#### `error.expected` - -The `expected` value passed to the assertion, if any. - -#### `error.operator` - -The name of the operator used by the assertion that failed, such as `'=='` or `'strictEqual'`. - -If no `message` is provided to `AssertionError`, one is generated from `actual`, `expected`, and `operator`. - -#### `assert.fail([message])` +## API -Throws an `AssertionError` unconditionally. Defaults `message` to `'Failed'` if not provided. +### AssertionError -#### `assert.ok(value[, message])` +#### `new AssertionError(opts?: { message?: string; actual?: any; expected?: any; operator?: string })` -Throws an `AssertionError` unless `value` is truthy. Equivalent to `assert()`. +Create an `AssertionError`, optionally setting its `message`, `actual`, `expected`, and `operator`. -#### `assert.notOk(value[, message])` +**Parameters** -Throws an `AssertionError` if `value` is truthy. +| Parameter | Type | Default | Description | +| --------- | ----------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `opts?` | `{ message?: string; actual?: any; expected?: any; operator?: string }` | — | Fields to set on the new error: `message` (defaults to a generated `" "` string), `actual`, `expected`, and `operator`. | -#### `assert.equal(actual, expected[, message])` +#### `actual: any` -Throws an `AssertionError` unless `actual == expected`, using the `==` operator. `NaN` is treated as equal to `NaN`. +The actual value that failed the assertion. -#### `assert.notEqual(actual, expected[, message])` +#### `expected: any` -Throws an `AssertionError` unless `actual != expected`, using the `!=` operator. `NaN` is treated as equal to `NaN`. +The expected value the assertion was checked against. -#### `assert.strictEqual(actual, expected[, message])` +#### `operator: string` -Throws an `AssertionError` unless `actual` and `expected` are the same value, as determined by `Object.is()`. +The comparison operator used by the assertion that failed, e.g. `'=='` or `'strictEqual'`. -#### `assert.notStrictEqual(actual, expected[, message])` +### Functions -Throws an `AssertionError` unless `actual` and `expected` are not the same value, as determined by `Object.is()`. +#### `assert(value: any, message?: string | Error): void` -#### `assert.match(actual, regexp[, message])` +Throw an `AssertionError` if `value` is falsy. -Throws an `AssertionError` unless `actual` is a string that matches `regexp`. +**Parameters** -#### `assert.doesNotMatch(actual, regexp[, message])` +| Parameter | Type | Default | Description | +| ---------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | +| `value` | `any` | — | The value to assert is truthy. | +| `message?` | `string \| Error` | — | Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`. | -Throws an `AssertionError` unless `actual` is a string that does not match `regexp`. +**Throws** -#### `assert.ifError(actual)` +- `AssertionError` — thrown if `value` is falsy (unless `message` is an `Error` instance, which is thrown instead). -Throws an `AssertionError` unless `actual` is `undefined` or `null`. + ## License diff --git a/index.d.ts b/index.d.ts index aa4349c..9c097af 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1,11 +1,21 @@ +/** + * Throw an `AssertionError` if `value` is falsy. + * @param value - The value to assert is truthy. + * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`. + * @throws {AssertionError} thrown if `value` is falsy (unless `message` is an `Error` instance, which is thrown instead). + */ declare function assert(value: any, message?: string | Error): void declare namespace assert { + /** Error thrown when an assertion fails, carrying the `actual`, `expected`, and `operator` involved. */ export class AssertionError extends Error { constructor(opts?: { message?: string; actual?: any; expected?: any; operator?: string }) + /** The actual value that failed the assertion. */ actual?: any + /** The expected value the assertion was checked against. */ expected?: any + /** The comparison operator used by the assertion that failed, for example `'=='` or `'strictEqual'`. */ operator?: string } From 06501f4f7ea8ecbf82cdabf1dd27616d423e0826 Mon Sep 17 00:00:00 2001 From: Lucas Tortora Date: Wed, 12 Aug 2026 11:57:30 -0300 Subject: [PATCH 2/5] docs: link to the online reference instead of inlining it Points README ## API to docs.pears.com instead of duplicating the generated reference inline. Co-Authored-By: Claude Sonnet 5 --- README.md | 45 +-------------------------------------------- 1 file changed, 1 insertion(+), 44 deletions(-) diff --git a/README.md b/README.md index 677fa66..92931e5 100644 --- a/README.md +++ b/README.md @@ -17,52 +17,9 @@ assert.equal(1, 1) assert.notEqual(1, 2) ``` - - ## API -### AssertionError - -#### `new AssertionError(opts?: { message?: string; actual?: any; expected?: any; operator?: string })` - -Create an `AssertionError`, optionally setting its `message`, `actual`, `expected`, and `operator`. - -**Parameters** - -| Parameter | Type | Default | Description | -| --------- | ----------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `opts?` | `{ message?: string; actual?: any; expected?: any; operator?: string }` | — | Fields to set on the new error: `message` (defaults to a generated `" "` string), `actual`, `expected`, and `operator`. | - -#### `actual: any` - -The actual value that failed the assertion. - -#### `expected: any` - -The expected value the assertion was checked against. - -#### `operator: string` - -The comparison operator used by the assertion that failed, e.g. `'=='` or `'strictEqual'`. - -### Functions - -#### `assert(value: any, message?: string | Error): void` - -Throw an `AssertionError` if `value` is falsy. - -**Parameters** - -| Parameter | Type | Default | Description | -| ---------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | -| `value` | `any` | — | The value to assert is truthy. | -| `message?` | `string \| Error` | — | Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`. | - -**Throws** - -- `AssertionError` — thrown if `value` is falsy (unless `message` is an `Error` instance, which is thrown instead). - - +See the [full API reference](https://docs.pears.com/reference/bare/modules/bare-assert). ## License From 0d97d2f1ab13c4da1c6523f5f494f55bbd352323 Mon Sep 17 00:00:00 2001 From: Lucas Tortora Date: Wed, 12 Aug 2026 14:07:46 -0300 Subject: [PATCH 3/5] docs: wrap TSDoc comments to 100 columns Reflows comment text added by the earlier TSDoc commit so no line exceeds 100 columns, matching the convention settled on in bare-fs #44. Co-Authored-By: Claude Sonnet 5 --- index.d.ts | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/index.d.ts b/index.d.ts index 9c097af..e38068e 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1,13 +1,18 @@ /** * Throw an `AssertionError` if `value` is falsy. * @param value - The value to assert is truthy. - * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown directly instead of an `AssertionError`. - * @throws {AssertionError} thrown if `value` is falsy (unless `message` is an `Error` instance, which is thrown instead). + * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown + * directly instead of an `AssertionError`. + * @throws {AssertionError} thrown if `value` is falsy (unless `message` is an `Error` instance, + * which is thrown instead). */ declare function assert(value: any, message?: string | Error): void declare namespace assert { - /** Error thrown when an assertion fails, carrying the `actual`, `expected`, and `operator` involved. */ + /** + * Error thrown when an assertion fails, carrying the `actual`, `expected`, and `operator` + * involved. + */ export class AssertionError extends Error { constructor(opts?: { message?: string; actual?: any; expected?: any; operator?: string }) @@ -15,7 +20,10 @@ declare namespace assert { actual?: any /** The expected value the assertion was checked against. */ expected?: any - /** The comparison operator used by the assertion that failed, for example `'=='` or `'strictEqual'`. */ + /** + * The comparison operator used by the assertion that failed, for example `'=='` or + * `'strictEqual'`. + */ operator?: string } From e40bafaf6015b91c30e3c4aab17386cc270a6db9 Mon Sep 17 00:00:00 2001 From: Lucas Tortora Date: Wed, 12 Aug 2026 14:27:32 -0300 Subject: [PATCH 4/5] docs: match the bare-fs/bare-ws reference-link convention Switches the README API link text from "full API reference" to the ` reference` form, matching the pattern settled on in bare-fs #44 and merged in bare-ws. Long module names use a reference-style link to stay within 100 columns. Co-Authored-By: Claude Sonnet 5 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 92931e5..e3bc2e9 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ assert.notEqual(1, 2) ## API -See the [full API reference](https://docs.pears.com/reference/bare/modules/bare-assert). +See the [`bare-assert` reference](https://docs.pears.com/reference/bare/modules/bare-assert). ## License From 3a5f6aef36b68f121dff12e82251b7ef60529bd9 Mon Sep 17 00:00:00 2001 From: Lucas Tortora Date: Thu, 13 Aug 2026 14:29:27 -0300 Subject: [PATCH 5/5] docs: document the remaining assertion functions Co-Authored-By: Claude Opus 5 --- index.d.ts | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/index.d.ts b/index.d.ts index e38068e..61b0499 100644 --- a/index.d.ts +++ b/index.d.ts @@ -27,20 +27,94 @@ declare namespace assert { operator?: string } + /** + * Throw an `AssertionError` if `value` is falsy. + * @param value - The value to assert is truthy. + * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown + * directly instead of an `AssertionError`. + * @throws {AssertionError} thrown if `value` is falsy (unless `message` is an `Error` instance, + * which is thrown instead). + */ export function ok(value: any, message?: string | Error): void + /** + * Throw an `AssertionError` unless `actual` and `expected` are loosely equal (`==`), with `NaN` + * treated as equal to `NaN`. + * @param actual - The value produced. + * @param expected - The value to compare `actual` against. + * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown + * directly instead of an `AssertionError`. + * @throws {AssertionError} thrown if the values are not loosely equal (unless `message` is an + * `Error` instance, which is thrown instead). + */ export function equal(actual: any, expected: any, message?: string | Error): void + /** + * Throw an `AssertionError` unless `actual` and `expected` are loosely unequal (`!=`), with + * `NaN` treated as equal to `NaN`. + * @param actual - The value produced. + * @param expected - The value to compare `actual` against. + * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown + * directly instead of an `AssertionError`. + * @throws {AssertionError} thrown if the values are loosely equal (unless `message` is an + * `Error` instance, which is thrown instead). + */ export function notEqual(actual: any, expected: any, message?: string | Error): void + /** + * Throw an `AssertionError` unless `actual` and `expected` are the same value according to + * `Object.is()`, which treats `NaN` as equal to `NaN` and `0` as distinct from `-0`. + * @param actual - The value produced. + * @param expected - The value to compare `actual` against. + * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown + * directly instead of an `AssertionError`. + * @throws {AssertionError} thrown if the values are not the same value (unless `message` is an + * `Error` instance, which is thrown instead). + */ export function strictEqual(actual: any, expected: any, message?: string | Error): void + /** + * Throw an `AssertionError` unless `actual` and `expected` are different values according to + * `Object.is()`, which treats `NaN` as equal to `NaN` and `0` as distinct from `-0`. + * @param actual - The value produced. + * @param expected - The value to compare `actual` against. + * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown + * directly instead of an `AssertionError`. + * @throws {AssertionError} thrown if the values are the same value (unless `message` is an + * `Error` instance, which is thrown instead). + */ export function notStrictEqual(actual: any, expected: any, message?: string | Error): void + /** + * Throw an `AssertionError` unless `actual` is a string that matches the `expected` regular + * expression. + * @param actual - The string to test. + * @param expected - The regular expression that `actual` must match. + * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown + * directly instead of an `AssertionError`. + * @throws {AssertionError} thrown if `actual` is not a string or does not match `expected` + * (unless `message` is an `Error` instance, which is thrown instead). + */ export function match(actual: string, expected: RegExp, message?: string | Error): void + /** + * Throw an `AssertionError` unless `actual` is a string that does not match the `expected` + * regular expression. + * @param actual - The string to test. + * @param expected - The regular expression that `actual` must not match. + * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown + * directly instead of an `AssertionError`. + * @throws {AssertionError} thrown if `actual` is not a string or matches `expected` (unless + * `message` is an `Error` instance, which is thrown instead). + */ export function doesNotMatch(actual: string, expected: RegExp, message?: string | Error): void + /** + * Throw an `AssertionError` unless `actual` is `null` or `undefined`. + * @param actual - The value to assert is `null` or `undefined`. + * @throws {AssertionError} thrown if `actual` is neither `null` nor `undefined`, with the + * message `ifError got `. + */ export function ifError(actual: any): void }