{"id":10558,"library":"bare-assert","title":"Bare Assert","description":"bare-assert is a minimalist assertion library for JavaScript, designed to be lightweight and efficient. It provides fundamental assertion utilities like `ok`, `equal`, and `deepEqual`, suitable for testing or validating conditions in various JavaScript environments. The current stable version is 1.2.0, released in December 2025. This library is part of the broader Holepunchto 'bare' ecosystem, which focuses on small, modular JavaScript runtimes for desktop and mobile, suggesting an emphasis on performance and a reduced footprint. Its release cadence appears to be on an 'as-needed' basis, with updates roughly annually or semi-annually. A key differentiator is its 'bare-bones' philosophy, offering essential assertions without the extensive feature sets found in larger frameworks like Chai or Node.js's built-in `assert` module. It ships with TypeScript types, leveraging TypeScript's `asserts` keyword for enhanced type narrowing.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/holepunchto/bare-assert","tags":["javascript","typescript"],"install":[{"cmd":"npm install bare-assert","lang":"bash","label":"npm"},{"cmd":"yarn add bare-assert","lang":"bash","label":"yarn"},{"cmd":"pnpm add bare-assert","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally for some test-related functionalities; a lightweight testing framework.","package":"brittle","optional":false}],"imports":[{"note":"Imports the default export, which is an instance of the `Assert` class containing all assertion methods.","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'.","symbol":"assert","correct":"import assert from 'bare-assert';"},{"note":"Imports the specific `ok` assertion function as a named export. Other methods like `equal`, `deepEqual` can be imported similarly.","wrong":"const ok = require('bare-assert').ok; // While functional, 'import' is preferred in modern JavaScript and TypeScript projects.\nimport assert from 'bare-assert'; assert.ok(value); // This is also correct but `ok` can be directly imported for brevity.","symbol":"ok","correct":"import { ok } from 'bare-assert';"},{"note":"For CommonJS environments, the main `assert` object is the direct return value of `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.","symbol":"CommonJS require","correct":"const assert = require('bare-assert');"}],"quickstart":{"code":"import assert, { ok, equal, deepEqual } from 'bare-assert';\n\nfunction processData(data: unknown): asserts data is { id: number, name: string } {\n  ok(data !== null && typeof data === 'object', 'Data must be an object.');\n  equal(typeof (data as any).id, 'number', 'Data must have a numeric ID.');\n  equal(typeof (data as any).name, 'string', 'Data must have a string name.');\n}\n\ntry {\n  const validData = { id: 123, name: 'Alice' };\n  processData(validData);\n  console.log('Valid data processed:', validData.name); // TypeScript knows validData is now { id: number, name: string }\n\n  ok(1 + 1 === 2, 'Arithmetic works!');\n  equal('hello', 'hello', 'Strings should be equal.');\n  deepEqual({ a: 1, b: { c: 2 } }, { a: 1, b: { c: 2 } }, 'Deep equality works for objects.');\n\n  const invalidData = { id: 456, title: 'Invalid' };\n  // This will throw an error and be caught\n  // processData(invalidData); // Uncomment to see error\n\n} catch (error: any) {\n  console.error('Assertion failed:', error.message);\n}\n\n// Example of using an individual named export\nfunction checkConfig(config: { API_KEY?: string }): asserts config is { API_KEY: string } {\n  ok(config.API_KEY, 'API_KEY must be defined in config.');\n}\n\nconst myConfig = { API_KEY: process.env.MY_API_KEY ?? 'default-key' };\ntry {\n  checkConfig(myConfig);\n  console.log('API Key is:', myConfig.API_KEY);\n} catch (error: any) {\n  console.error('Config error:', error.message);\n}","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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(...)`.","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.","error":"TypeError: assert is not a function"},{"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 } { /* ... */ }`.","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.","error":"Property 'someProperty' does not exist on type 'unknown'."}],"ecosystem":"npm"}