tape-six-invariant 1.0.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Eugene Lazutkin
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,116 @@
+# tape-six-invariant [![NPM version][npm-img]][npm-url]
+
+[npm-img]: https://img.shields.io/npm/v/tape-six-invariant.svg
+[npm-url]: https://npmjs.org/package/tape-six-invariant
+
+`tape-six-invariant` lets you embed `assert`-style **invariant checks** in production or library code that **materialize** into real [`tape-six`](https://github.com/uhop/tape-six) assertions when a tape-six run exercises that code — and stay inert (or do whatever you configure) otherwise.
+
+**Zero runtime dependencies.** Works in [Node](https://nodejs.org/), [Deno](https://deno.land/), [Bun](https://bun.sh/), and browsers. ES modules, TypeScript bindings included. The library never imports tape-six — the two coordinate through a single global slot.
+
+```js
+import check from 'tape-six-invariant';
+
+export function transfer(from, to, amount) {
+  check(amount > 0, 'amount must be positive');
+  check(from.currency === to.currency, 'currencies must match');
+  // …
+}
+```
+
+- **Under a tape-six run** (the code is exercised by a test): each `check()` becomes a counted assertion on the _current_ test — in the plan, in TAP output, with its source location pointing at the `check()` call site.
+- **In production** (no tape-six): a configurable behavior. Default **inert** (does nothing). Overridable to throw, warn, defer to your own `node:assert`, or anything you like.
+
+The same call site means the same thing — an invariant — and is paid for only when something is listening.
+
+## Install
+
+```bash
+npm install --save tape-six-invariant
+```
+
+`tape-six` is needed only to _run_ the invariants as assertions (a dev/test concern), so it is not a dependency of this package.
+
+## Usage
+
+### Materialize under test
+
+Any code reached — directly or transitively — from a tape-six test body routes its `check()` calls to the current test:
+
+```js
+import test from 'tape-six';
+import {transfer} from '../src/bank.js';
+
+test('transfer enforces its invariants', t => {
+  transfer({currency: 'USD'}, {currency: 'USD'}, 10); // the two checks pass as assertions
+  t.pass('done');
+});
+```
+
+### Configure production behavior
+
+By default invariants are inert in production — they cost a single global-property read. Opt into enforcement at startup:
+
+```js
+import {setAbsentBehavior, throwOnFail} from 'tape-six-invariant';
+
+setAbsentBehavior(throwOnFail); // a failing check now throws InvariantError
+```
+
+With no behavior set — the default — a failing check is a no-op. Canned behaviors (exported functions, not magic strings):
+
+| Behavior      | Effect on a failing check |
+| ------------- | ------------------------- |
+| `throwOnFail` | throw `InvariantError`    |
+| `warnOnFail`  | `console.warn`            |
+
+`setAbsentBehavior(null)` (or any non-function) clears a previously set behavior. Or pass your own `(ok, message) => void` — for instance, to defer to `node:assert`, bring your own import so it stays your dependency, not the package's:
+
+```js
+import assert from 'node:assert';
+
+setAbsentBehavior((ok, message) => assert.ok(ok, message));
+```
+
+### Skip expensive pre-check work
+
+`hasHost` is an import-time snapshot — use it to avoid computing an argument that is only worth checking under a run:
+
+```js
+import {check, hasHost} from 'tape-six-invariant';
+
+if (hasHost) check(expensiveToCompute(), 'invariant holds');
+```
+
+Correctness never depends on the snapshot — `check()` always reads the live slot.
+
+### Lazy messages
+
+Pass a `() => string` thunk to build an expensive message only when it is needed:
+
+```js
+check(list.every(valid), () => `invalid items: ${list.filter(x => !valid(x)).join(', ')}`);
+```
+
+## API
+
+See the [wiki](https://github.com/uhop/tape-six-invariant/wiki) for full docs. `check` is the default export (and a named export); everything else is named-only.
+
+- `check(cond, message?)` — record an invariant. `message` may be a string or a `() => string` thunk. TypeScript signature is `asserts cond`.
+- `hasHost` — import-time boolean: was a tape-six host present at load?
+- `setAbsentBehavior(fn)` — set the no-host failure behavior; `null` clears it (default: none, a no-op).
+- `throwOnFail`, `warnOnFail` — canned absent behaviors.
+- `InvariantError` — thrown by `throwOnFail`.
+
+## Related packages
+
+- [tape-six](https://www.npmjs.com/package/tape-six) — the test library these invariants materialize into.
+- [tape-six-proc](https://www.npmjs.com/package/tape-six-proc) — process-isolated test execution.
+- [tape-six-puppeteer](https://www.npmjs.com/package/tape-six-puppeteer) / [tape-six-playwright](https://www.npmjs.com/package/tape-six-playwright) — browser automation.
+
+## Release notes
+
+- **1.0.0** — Initial release: `check`, `hasHost`, `setAbsentBehavior`, canned behaviors (`throwOnFail`/`warnOnFail`), `InvariantError`.
+
+## License
+
+[BSD-3-Clause](./LICENSE) © Eugene Lazutkin

package/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Absent-path behavior — runs when a failing {@link check} finds no host.
+ * @see https://github.com/uhop/tape-six-invariant/wiki/API#canned-behaviors
+ */
+export type AbsentBehavior = (ok: unknown, message?: string) => void;
+
+/**
+ * Records an invariant: a counted tape-six assertion when a run is hosting it,
+ * the configured absent behavior otherwise.
+ * @see https://github.com/uhop/tape-six-invariant/wiki/API#check
+ */
+export declare function check(cond: unknown, message?: string | (() => string)): asserts cond;
+
+/**
+ * Import-time snapshot of whether a tape-six host was present at load. Gate for
+ * skipping expensive pre-check work; correctness never depends on it.
+ * @see https://github.com/uhop/tape-six-invariant/wiki/API#hashost
+ */
+export declare const hasHost: boolean;
+
+/**
+ * Sets the absent-path behavior. Pass `null` (or any non-function) to clear it;
+ * with none set — the default — a failing {@link check} with no host is a no-op.
+ * @see https://github.com/uhop/tape-six-invariant/wiki/API#setabsentbehavior
+ */
+export declare function setAbsentBehavior(fn: AbsentBehavior | null): void;
+
+/** Absent behavior: throw {@link InvariantError} on failure. */
+export declare const throwOnFail: AbsentBehavior;
+
+/** Absent behavior: `console.warn` on failure. */
+export declare const warnOnFail: AbsentBehavior;
+
+/** Error thrown by {@link throwOnFail}. */
+export declare class InvariantError extends Error {
+  constructor(message?: string);
+}
+
+/** {@link check} is also the default export. */
+export default check;

package/index.js

@@ -0,0 +1,43 @@
+// @ts-self-types="./index.d.ts"
+
+const KEY = Symbol.for('tape6.invariant.host.v1');
+
+const resolveMessage = message => (typeof message === 'function' ? message() : message);
+
+export const hasHost = !!globalThis[KEY];
+
+let absentBehavior = null;
+
+export const setAbsentBehavior = fn => {
+  absentBehavior = typeof fn === 'function' ? fn : null;
+};
+
+export class InvariantError extends Error {
+  constructor(message) {
+    super(message || 'Invariant failed');
+    this.name = 'InvariantError';
+    if (typeof Error.captureStackTrace == 'function') {
+      Error.captureStackTrace(this, InvariantError);
+    }
+  }
+}
+
+export const throwOnFail = (ok, message) => {
+  if (!ok) throw new InvariantError(message);
+};
+
+export const warnOnFail = (ok, message) => {
+  if (!ok) console.warn('Invariant failed' + (message ? ': ' + message : ''));
+};
+
+export const check = (cond, message) => {
+  const host = globalThis[KEY];
+  if (host) {
+    host.report({ok: !!cond, message: resolveMessage(message), marker: new Error()});
+    return;
+  }
+  if (!absentBehavior) return;
+  if (!cond) absentBehavior(cond, resolveMessage(message));
+};
+
+export default check;

package/llms-full.txt

@@ -0,0 +1,174 @@
+# tape-six-invariant
+
+> A zero-dependency library of `assert`-style invariant checks that **materialize** into real [tape-six](https://github.com/uhop/tape-six) assertions when a tape-six run exercises the code, and are inert (or a configurable behavior) in production. The library never imports tape-six; the two coordinate purely through a versioned global slot, `Symbol.for('tape6.invariant.host.v1')`.
+
+- Embed invariants in production / library code; they become counted test assertions only when something is listening.
+- Zero runtime dependencies; works in Node, Deno, Bun, and browsers.
+- ES modules, no build step, hand-written TypeScript definitions (`asserts cond` narrowing on `check`).
+- Configurable production behavior via a single generic setter (not an env-flag menu).
+- Designed to be build-time strippable (unassert-style) — `check` stays statically matchable.
+
+## The idea
+
+An invariant check embedded in production or library code:
+
+```js
+import check from 'tape-six-invariant';
+
+export function transfer(from, to, amount) {
+  check(amount > 0, 'amount must be positive');
+  check(from.currency === to.currency, 'currencies must match');
+}
+```
+
+- **Under a tape-six run** (the code is exercised by a test): each `check()` becomes a counted assertion on the _current_ test — in the plan, in TAP output, with source location pointing at the `check()` call site.
+- **In production** (no tape-six): a configurable behavior. Default is none — a failing check is a no-op. Overridable to throw, warn, defer to your own `node:assert`, or anything else.
+
+The same call site means the same thing — an invariant — and is paid for only when something is listening. This routing-to-a-live-harness is the one new element vs. prior art (tiny-invariant, zertosh/invariant, unassert), which is always-on-or-stripped.
+
+## Install
+
+```bash
+npm install --save tape-six-invariant
+```
+
+`tape-six` is needed only to run the invariants as assertions, so it is not a dependency of this package. To run the test suite of this repo against the unreleased host hooks, `npm link` a local tape-six checkout (see the repository AGENTS.md).
+
+## API
+
+### check(cond, message?)
+
+```ts
+function check(cond: unknown, message?: string | (() => string)): asserts cond;
+```
+
+Records an invariant. It is the package's **default export** and also a named export — `import check from 'tape-six-invariant'` for the common single-import case, or `import {check, hasHost} from 'tape-six-invariant'` when pulling several symbols. Every other symbol is named-only.
+
+- `cond` — pass/fail verdict; a falsy value fails the invariant. Normalized with `!!` when reported.
+- `message` — failure message. May be a `() => string` thunk so an expensive message is built only when resolved.
+
+Behavior:
+
+- **Host present** — reports `{ok: !!cond, message, marker: new Error()}` to the host, which routes it to the current tester. The `marker` Error keeps the reported source location at the call site. The message thunk (if any) is resolved before reporting.
+- **No host** — on a falsy `cond`, runs the configured absent behavior with `(cond, resolvedMessage)`. A truthy `cond` is an early return: the only cost when off is one global-property read.
+
+The TypeScript `asserts cond` signature narrows the condition for callers.
+
+```js
+import check from 'tape-six-invariant';
+
+function area(w, h) {
+  check(w > 0 && h > 0, 'dimensions must be positive');
+  return w * h;
+}
+```
+
+### hasHost
+
+```ts
+const hasHost: boolean;
+```
+
+Import-time snapshot of whether a tape-six host was installed when this module loaded. Reliable because tape-six sets the slot at module load and test files import tape-six first; in pure production the slot is absent and `hasHost` is `false`.
+
+Use it to gate expensive pre-check computation:
+
+```js
+import {check, hasHost} from 'tape-six-invariant';
+
+if (hasHost) check(expensiveToCompute(), 'invariant holds');
+```
+
+Correctness never depends on the snapshot — `check()` reads the live slot per call.
+
+### setAbsentBehavior(fn)
+
+```ts
+type AbsentBehavior = (ok: unknown, message?: string) => void;
+function setAbsentBehavior(fn: AbsentBehavior): void;
+```
+
+Replaces the absent-path behavior — what a failing `check` does when no host is present. Pass a canned behavior or your own. The default is none (a failing check is a no-op); passing `null` or any non-function clears a set behavior. Module-scoped: each copy of the library configures itself independently (only the host slot is global).
+
+```js
+import {setAbsentBehavior, throwOnFail} from 'tape-six-invariant';
+
+setAbsentBehavior(throwOnFail);
+
+// custom:
+setAbsentBehavior((ok, message) => {
+  if (!ok) metrics.increment('invariant.failed', {message});
+});
+```
+
+### Canned behaviors
+
+Exported functions passed to `setAbsentBehavior` (not magic strings). With none set — the default — a failing check is a no-op:
+
+| Behavior      | Effect on a failing check       | Use                        |
+| ------------- | ------------------------------- | -------------------------- |
+| `throwOnFail` | throw `InvariantError(message)` | fail-fast enforcement      |
+| `warnOnFail`  | `console.warn`                  | non-fatal telemetry signal |
+
+To defer to `node:assert` (or any other assertion library), bring your own import and pass it to `setAbsentBehavior`. There is no canned `nodeAssert` on purpose: a synchronous `check` should not dynamically import a module, and keeping the import on the caller's side leaves this package zero-dependency.
+
+```js
+import assert from 'node:assert';
+
+setAbsentBehavior((ok, message) => assert.ok(ok, message));
+```
+
+### InvariantError
+
+```ts
+class InvariantError extends Error {
+  constructor(message?: string);
+}
+```
+
+Thrown by `throwOnFail`. `name` is `'InvariantError'`; the default message is `'Invariant failed'`.
+
+## Coordination protocol
+
+The library and tape-six coordinate through a **versioned, Symbol-keyed slot on `globalThis`**:
+
+```js
+const KEY = Symbol.for('tape6.invariant.host.v1');
+```
+
+**Why a global rather than a module variable:** in production the dependency graph can contain several copies/versions of the library (npm does not always dedupe across version ranges). The coordination point must be shared across all copies — a `globalThis` slot is; a module-scoped variable is not. Same precedent as the React DevTools global hook.
+
+**tape-six sets the slot at module load** (not in `init()`), so `hasHost` is reliable — a test file imports tape-six first, so the slot exists before any code-under-test runs:
+
+```js
+globalThis[Symbol.for('tape6.invariant.host.v1')] ||= {
+  version: 1,
+  report(assertion) {
+    const tester = getTester(); // live current tester; null between/outside tests
+    if (tester) tester.reportAssertion(assertion);
+  }
+};
+```
+
+`||=` so the first-loaded tape-six copy wins (redundant copies are functionally identical).
+
+**Cross-realm:** `Symbol.for` is shared within a realm, but each realm (worker thread, iframe, subprocess) has its own `globalThis`. tape-six already runs per worker/process and isolates per realm, so each realm's load sets its own slot.
+
+The tape-six side provides three hooks that back this protocol: `getTester()` (innermost running tester or `null`), `Tester.reportAssertion({ok, message?, marker?, operator?, expected?, actual?})` (a marker-preserving report primitive), and the host slot itself.
+
+## Zero-overhead-when-off
+
+- The off path is one global-property read plus an early return; the marker `Error`, descriptor object, and message resolution happen only on the materialized or failing path.
+- The `hasHost` constant lets callers skip expensive pre-check work entirely when nothing is listening.
+- A `() => string` message thunk avoids building an expensive message unless it is needed.
+- `check` is a plain named import with a static, recognizable signature, so an unassert-style AST transform can delete the calls entirely in release builds.
+
+## Scope
+
+The API is deliberately minimal — predicate-only. The equality family (`deepEqual`, `match`, …) is **out of scope**: deep comparison needs an engine, which would force either a dependency or a silent shallow downgrade in production (the same invariant would mean different things in test vs. prod). A richer package can come later, forming richer descriptors for `reportAssertion`; this one stays predicate-only and zero-dependency.
+
+## Notes
+
+- ES modules only (`"type": "module"`); no CommonJS build, no transpilation.
+- Library, not a CLI — no `bin`. The whole implementation is the single root module `index.js`.
+- TypeScript types live in `index.d.ts` (the sole source of types and docs); `index.js` carries `// @ts-self-types="./index.d.ts"`.

package/llms.txt

@@ -0,0 +1,67 @@
+# tape-six-invariant
+
+> Zero-dependency invariant checks that materialize into real tape-six assertions under test, and are inert (or configurable) in production. Works in Node, Deno, Bun, and browsers. Never imports tape-six — coordinates through the global slot `Symbol.for('tape6.invariant.host.v1')`.
+
+## Install
+
+npm i tape-six-invariant
+
+## Quick start
+
+```js
+import check from 'tape-six-invariant';
+
+export function transfer(from, to, amount) {
+  check(amount > 0, 'amount must be positive');
+  check(from.currency === to.currency, 'currencies must match');
+}
+```
+
+Under a tape-six run each `check()` becomes a counted assertion on the current test. In production it runs the configured absent behavior, if any; by default none is set, so a failing check is a no-op.
+
+## API
+
+### check(cond, message?)
+
+Records an invariant. The default export, also available as a named export (`import check from 'tape-six-invariant'` or `import {check} from 'tape-six-invariant'`). TypeScript signature: `(cond: unknown, message?: string | (() => string)) => asserts cond`.
+
+- `cond` — pass/fail verdict; a falsy value fails the invariant.
+- `message` — failure message, or a `() => string` thunk resolved only when needed.
+
+With a tape-six host present, reports `{ok, message, marker}` to the current test (source location at the call site). With no host, on failure runs the absent behavior; a passing check is a no-op.
+
+### hasHost
+
+`const hasHost: boolean` — import-time snapshot of whether a tape-six host was installed when the module loaded. Gate expensive pre-check computation: `if (hasHost) check(expensiveToCompute(), '…')`. Correctness never depends on it; `check` reads the live slot per call.
+
+### setAbsentBehavior(fn)
+
+Sets the absent-path behavior (what a failing `check` does with no host). `fn: (ok: unknown, message?: string) => void`. Passing `null` or any non-function clears it; the default is none (a failing check is a no-op). Module-scoped — each copy of the library configures itself.
+
+### Canned behaviors
+
+Exported functions to pass to `setAbsentBehavior` (the default is none — a no-op):
+
+- `throwOnFail` — throws `InvariantError`.
+- `warnOnFail` — `console.warn`.
+
+To defer to `node:assert` (or any other assertion library), bring your own import and pass it to `setAbsentBehavior` — it stays your dependency, not the package's: `setAbsentBehavior((ok, message) => assert.ok(ok, message))`.
+
+### InvariantError
+
+`class InvariantError extends Error` — thrown by `throwOnFail`. `name` is `'InvariantError'`; default message `'Invariant failed'`.
+
+## Coordination protocol
+
+- tape-six installs `globalThis[Symbol.for('tape6.invariant.host.v1')] = {version, report(assertion)}` at module load (`||=`, first copy wins).
+- `report` resolves the live current tester via tape-six's `getTester()` and forwards to `Tester.reportAssertion({ok, message?, marker?, operator?, expected?, actual?})`.
+- A global (not a module variable) so duplicate library copies in a dependency graph share one coordination point. Each realm (worker, iframe, subprocess) has its own slot.
+
+## Scope
+
+Predicate-only and zero-dep by design. The equality family (`deepEqual`, `match`, …) is out of scope — deep comparison needs an engine, which would force a dependency or env-divergent semantics.
+
+## Notes
+
+- ES modules only; no build step; TypeScript bindings in `index.d.ts`.
+- `check` is statically matchable so an unassert-style build transform can strip calls in release builds.

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "tape-six-invariant",
+  "version": "1.0.0",
+  "description": "Zero-dependency invariant checks that materialize into real tape-six assertions under test, and stay inert (or configurable) in production.",
+  "type": "module",
+  "main": "index.js",
+  "module": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": "./index.js"
+  },
+  "scripts": {
+    "lint": "prettier --check .",
+    "lint:fix": "prettier --write .",
+    "test": "tape6 --flags FO",
+    "test:bun": "tape6-bun --flags FO",
+    "test:deno": "tape6-deno --flags FO",
+    "ts-test": "tape6 --flags FO 'tests/test-*.ts'",
+    "ts-test:bun": "tape6-bun --flags FO 'tests/test-*.ts'",
+    "ts-test:deno": "tape6-deno --flags FO 'tests/test-*.ts'",
+    "ts-check": "tsc --noEmit",
+    "js-check": "tsc --project tsconfig.check.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uhop/tape-six-invariant.git"
+  },
+  "keywords": [
+    "tape6",
+    "tape-six",
+    "invariant",
+    "invariants",
+    "assert",
+    "assertion",
+    "contract",
+    "design-by-contract",
+    "test",
+    "testing",
+    "unit-test",
+    "cross-runtime",
+    "nodejs",
+    "deno",
+    "bun",
+    "browser",
+    "esm",
+    "es-modules",
+    "typescript",
+    "zero-dependency"
+  ],
+  "author": "Eugene Lazutkin <eugene.lazutkin@gmail.com> (https://www.lazutkin.com/)",
+  "funding": "https://github.com/sponsors/uhop",
+  "license": "BSD-3-Clause",
+  "bugs": {
+    "url": "https://github.com/uhop/tape-six-invariant/issues"
+  },
+  "homepage": "https://github.com/uhop/tape-six-invariant#readme",
+  "llms": "https://raw.githubusercontent.com/uhop/tape-six-invariant/main/llms.txt",
+  "llmsFull": "https://raw.githubusercontent.com/uhop/tape-six-invariant/main/llms-full.txt",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "llms.txt",
+    "llms-full.txt"
+  ],
+  "tape6": {
+    "tests": [
+      "/tests/test-*.js"
+    ],
+    "cli": [
+      "/tests/cli/test-*.*js"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "prettier": "^3.9.0",
+    "tape-six": "^1.11.0",
+    "typescript": "^6.0.3"
+  }
+}