Bare Assert

Common errors

• TypeError: assert is not a function

  cause Attempting to call `require('bare-assert').assert()` or `import { assert } from 'bare-assert'; assert()`. The primary `assert` object is the default export, not a named property on the module.
  fix For CommonJS, use `const assert = require('bare-assert'); assert.ok(...)`. For ESM, use `import assert from 'bare-assert'; assert.ok(...)` or `import { ok } from 'bare-assert'; ok(...)`.

• Property 'someProperty' does not exist on type 'unknown'.

  cause Trying to access properties on a value after an assertion function, but TypeScript's type narrowing has not been applied, often due to incorrect usage of assertion functions or type guards.
  fix Ensure the assertion function has a proper `asserts value is Type` signature and that the code path after the assertion only executes if the assertion passes. For example: `function assertHasProperty(obj: unknown): asserts obj is { someProperty: any } { /* ... */ }`.

Warnings

• gotcha bare-assert is designed as a minimalist library. Users accustomed to feature-rich assertion libraries like Chai or Jest's expect API may find its functionality limited. It focuses on core assertions (e.g., ok, equal, deepEqual) without advanced matchers, spies, or mock capabilities.
  Fix: Review the `bare-assert` API before integrating to ensure it meets testing or validation requirements. For more complex scenarios, consider integrating a full-featured testing framework.
• gotcha The `asserts` keyword in TypeScript (which `bare-assert` utilizes for its type definitions) provides compile-time type narrowing, but it relies on runtime checks to guarantee types. Misunderstanding its behavior can lead to false confidence if the underlying runtime assertion logic is flawed or bypassed.
  Fix: Ensure a solid understanding of TypeScript's `asserts` keyword and its interaction with runtime checks. Always ensure the runtime assertion logic correctly validates the intended type to prevent unexpected runtime errors despite compile-time type safety.
• gotcha While `bare-assert` is an assertion library for JavaScript, its origin within the Holepunchto 'bare' ecosystem suggests it might be particularly tuned for that specific runtime. Although available on npm for general use, subtle differences in environment (e.g., browser vs. Node.js) might behave differently than Node.js's native `assert` module.
  Fix: Test `bare-assert` thoroughly in your target environment, especially if it's a non-standard JavaScript runtime or a browser environment, to confirm consistent behavior. Do not assume direct parity with Node.js's built-in `assert` module without verification.

Install

• npm install bare-assert npm
• yarn add bare-assert yarn
• pnpm add bare-assert pnpm

Imports

• assert
  wrong:

  import { assert } from 'bare-assert'; // 'assert' is the default export, not a named export. Named imports are for individual methods like 'ok' or 'equal'.

  correct:

  import assert from 'bare-assert';

  Imports the default export, which is an instance of the `Assert` class containing all assertion methods.
• ok
  wrong:

  const ok = require('bare-assert').ok; // While functional, 'import' is preferred in modern JavaScript and TypeScript projects.
  import assert from 'bare-assert'; assert.ok(value); // This is also correct but `ok` can be directly imported for brevity.

  correct:

  import { ok } from 'bare-assert';

  Imports the specific `ok` assertion function as a named export. Other methods like `equal`, `deepEqual` can be imported similarly.
• CommonJS require
  wrong:

  const { assert } = require('bare-assert'); // This would attempt to destructure a named 'assert' export, which doesn't exist as the main assert object is the default export.

  correct:

  const assert = require('bare-assert');

  For CommonJS environments, the main `assert` object is the direct return value of `require`.

Quickstart

Demonstrates importing the default assert object and individual assertion functions, applying basic and deep equality checks, and leveraging TypeScript's `asserts` keyword for type narrowing at runtime.

import assert, { ok, equal, deepEqual } from 'bare-assert';

function processData(data: unknown): asserts data is { id: number, name: string } {
  ok(data !== null && typeof data === 'object', 'Data must be an object.');
  equal(typeof (data as any).id, 'number', 'Data must have a numeric ID.');
  equal(typeof (data as any).name, 'string', 'Data must have a string name.');
}

try {
  const validData = { id: 123, name: 'Alice' };
  processData(validData);
  console.log('Valid data processed:', validData.name); // TypeScript knows validData is now { id: number, name: string }

  ok(1 + 1 === 2, 'Arithmetic works!');
  equal('hello', 'hello', 'Strings should be equal.');
  deepEqual({ a: 1, b: { c: 2 } }, { a: 1, b: { c: 2 } }, 'Deep equality works for objects.');

  const invalidData = { id: 456, title: 'Invalid' };
  // This will throw an error and be caught
  // processData(invalidData); // Uncomment to see error

} catch (error: any) {
  console.error('Assertion failed:', error.message);
}

// Example of using an individual named export
function checkConfig(config: { API_KEY?: string }): asserts config is { API_KEY: string } {
  ok(config.API_KEY, 'API_KEY must be defined in config.');
}

const myConfig = { API_KEY: process.env.MY_API_KEY ?? 'default-key' };
try {
  checkConfig(myConfig);
  console.log('API Key is:', myConfig.API_KEY);
} catch (error: any) {
  console.error('Config error:', error.message);
}