bupkis 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## [0.0.2](https://github.com/boneskull/bupkis/compare/bupkis-v0.0.1...bupkis-v0.0.2) (2025-09-07)
+
+
+### Bug Fixes
+
+* add repository to package.json ([4d687a5](https://github.com/boneskull/bupkis/commit/4d687a54c4fb34331508011df14fcfd966bf7ad3))
+
+## 0.0.1 (2025-09-07)
+
+
+### Features
+
+* "initial commit" ([04f234c](https://github.com/boneskull/bupkis/commit/04f234c8f8cea4cef5bae0dc7ccb692eb91d8748))
+
+
+### Bug Fixes
+
+* remove ref to distfile ([5de9a6b](https://github.com/boneskull/bupkis/commit/5de9a6b6f7bebe3f8898eecc3ae2212e183c3a16))

package/LICENSE.md

@@ -0,0 +1,55 @@
+# Blue Oak Model License
+
+Version 1.0.0
+
+## Purpose
+
+This license gives everyone as much permission to work with
+this software as possible, while protecting contributors
+from liability.
+
+## Acceptance
+
+In order to receive this license, you must agree to its
+rules. The rules of this license are both obligations
+under that agreement and conditions to your license.
+You must not do anything with this software that triggers
+a rule that you cannot or will not follow.
+
+## Copyright
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe that contributor's
+copyright in it.
+
+## Notices
+
+You must ensure that everyone who gets a copy of
+any part of this software from you, with or without
+changes, also gets the text of this license or a link to
+<https://blueoakcouncil.org/license/1.0.0>.
+
+## Excuse
+
+If anyone notifies you in writing that you have not
+complied with [Notices](#notices), you can keep your
+license by taking all practical steps to comply within 30
+days after the notice. If you do not do so, your license
+ends immediately.
+
+## Patent
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe any patent claims
+they can license or become able to license.
+
+## Reliability
+
+No contributor can revoke this license.
+
+## No Liability
+
+**_As far as the law allows, this software comes as is,
+without any warranty or condition, and no contributor
+will be liable to anyone for any damages related to this
+software or this license, under any kind of legal claim._**

package/README.md

@@ -0,0 +1,170 @@
+<p align="center">
+  <img src="https://github.com/boneskull/bupkis/blob/main/assets/bupkis-logo-256.png" width="256px" align="center" alt="BUPKIS logo"/>
+  <h1 align="center"><em><span class="federo-caps">BUPKIS<span></em></h1>
+  <p align="center">
+    A well-typed and easily exensible <em>BDD-style</em> assertion library.
+    <br/>
+    by <a href="https://github.com/boneskull">@boneskull</a>
+  </p>
+</p>
+
+## Motivation
+
+Look, I'm ~~old~~ ~~wizened~~ ~~experienced~~ knowledegable and I've written a lot of tests. I've used a lot of assertion libraries. There are ones I prefer and ones I don't.
+
+But none of them do quite what _this_ does. The main goals of this library are:
+
+- Type safety
+- Dead-simple creation of custom assertions
+- Minimal API surface
+
+A chainable API may provide type safety. But it seems to _guarantee_ implementing a custom assertion will be complicated. The API surface is necessarily a combinatoric explosion of methods.
+
+> [!WARNING]
+>
+> Because chainable APIs are familiar, you may hate _BUPKIS_ once you see some examples. You don't have to use it, but please: _don't confuse familiarity with usability_.
+
+To achieve these goals, I've adopted the following design principles:
+
+### Natural-Language Assertions
+
+In `bupkis` (stylized as "_BUPKIS_"), you **don't** write this:
+
+```js
+expect(actual).toEqual(expected);
+```
+
+Instead, you write this:
+
+```js
+expect(actual, 'is', expected);
+// or this
+expect(actual, 'to be', expected);
+// or this
+expect(actual, 'to equal', expected);
+// or even this
+expect(actual, 'equals', expected);
+// or yet another way
+expect(actual, 'is equal to', expected);
+// or believe it or not, even this
+expect(actual, 'to strictly equal', expected);
+```
+
+If Chai wants you to write:
+
+```js
+expect(actual).to.be.a('string');
+```
+
+Then _BUPKIS_ wants you to write:
+
+```js
+expect(actual, 'to be a string');
+// it is tolerant of poor/ironic grammar
+expect(actual, 'to be an string');
+```
+
+Can't remember the string? Did you forget a word or make a typo? Maybe you also forgot _BUPKIS_ is type-safe? You'll get a nice squiggly for your trouble.
+
+The "string" part of an expectation is known as a _phrase_. Every expectation will contain, at minimum, one phrase. As you can see from the above example, phrases often have aliases.
+
+You can negate just about any phrase:
+
+```js
+expect(actual, 'to be', expected);
+// did they not teach grammar in nerd school??
+expect(actual, 'not is', expected);
+
+expect(
+  () => throw new TypeError('aww, shucks'),
+  'to throw a',
+  TypeError,
+  'not satisfying',
+  /gol durn/,
+);
+```
+
+### Custom Assertions
+
+In _BUPKIS_, custom assertions are _first-class citizens_. You can create your own assertions with minimal boilerplate. You don't have to learn a new API or a new DSL (maybe); you just use [Zod][]. _It's so easy, even a **archaic human** could do it!_
+
+Read [Guide: How to Create a Custom Assertion](https://boneskull.github.io/bupkis/documents/Guides.How_to_Create_a_Custom_Assertion) to learn more.
+
+## Prerequisites
+
+_BUPKIS_ requires **Node.js ^20.19.0 || ^22.12.0 || >=23** and ships as a dual CJS/ESM package.
+
+The library has been designed for Node.js environments and testing frameworks.
+
+## Installation
+
+```bash
+npm install bupkis -D
+```
+
+## Usage
+
+Here:
+
+```ts
+import { expect } from 'bupkis';
+
+// Basic type assertions
+expect('hello', 'to be a string');
+expect(42, 'to be a number');
+expect(true, 'to be a boolean');
+
+// Value comparisons
+expect(10, 'to equal', 10);
+expect('hello world', 'to contain', 'world');
+expect([1, 2, 3], 'to have length', 3);
+
+// Negation
+expect(42, 'not to be a string');
+expect('hello', 'not to equal', 'goodbye');
+
+// Object assertions
+const user = { name: 'Alice', age: 30 };
+expect(user, 'to be an object');
+expect(user, 'to have property', 'name');
+expect(user, 'to satisfy', { name: 'Alice' });
+```
+
+For comprehensive documentation and guides, visit the [project documentation](https://boneskull.github.io/bupkis/).
+
+### Worth Mentioning Right Now
+
+_BUPKIS_ has two main exports:
+
+- `expect()`: the main entrypoint for synchronous assertions
+- `expectAsync()`: the main entrypoint for asynchronous assertions
+
+> [!IMPORTANT]
+>
+> As of this writing, the assertions available in `expectAsync()` are all `Promise`-related (and custom assertions can even use an async schema for the subject); they are completely disjoint from the assertions available in `expect()`. **This will likely change in the future.**
+
+## Project Scope
+
+1. It's an assertion library
+
+### TODO
+
+## Prior Art & Appreciation
+
+- [Unexpected][] is the main inspiration for _BUPKIS_. However, creating types for this library is exceedingly difficult (and was in fact the first thing I tried). Despite that drawback, I find it more usable than any other assertion library I've tried.
+- [Zod][] is a popular object validation library which does most of the heavy lifting for _BUPKIS_. It's not an assertion library, but there's enough overlap in its use case that it makes sense to leverage it.
+- [fast-check][]: A big thanks to Nicholas Dubien for this library. There is **no better library** for an assertion library to use to test itself! Well, besides itself, I mean. How about _in addition to_ itself? Yes. Thank you!
+
+## A Note From The Author
+
+> _"This is my assertion library. Many are like it, but this one is mine."_
+>
+> ‒boneskull, 2025
+
+## License
+
+Copyright © 2025 Christopher Hiller. Licensed under [BlueOak-1.0.0](https://blueoakcouncil.org/license/1.0.0).
+
+[zod]: https://zod.dev
+[unexpected]: https://unexpected.js.org
+[fast-check]: https://fast-check.dev

package/package.json

@@ -0,0 +1,164 @@
+{
+  "name": "bupkis",
+  "version": "0.0.2",
+  "type": "module",
+  "description": "",
+  "repository": {
+    "url": "git+https://github.com/boneskull/bupkis.git"
+  },
+  "author": {
+    "name": "Christopher Hiller",
+    "email": "boneskull@boneskull.com"
+  },
+  "license": "BlueOak-1.0.0",
+  "engines": {
+    "node": "^20.19.0 || ^22.12.0 || >=23"
+  },
+  "main": "./dist/commonjs/index.js",
+  "types": "./dist/commonjs/index.d.ts",
+  "module": "./dist/esm/index.js",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/index.d.ts",
+        "default": "./dist/commonjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "CHANGELOG.md",
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "test",
+    "expect",
+    "assert",
+    "assertion",
+    "expectation",
+    "assertion library",
+    "assertions",
+    "zod",
+    "validation",
+    "testing",
+    "jest",
+    "mocha",
+    "chai",
+    "vitest",
+    "ava",
+    "tap",
+    "tape"
+  ],
+  "scripts": {
+    "build": "tshy",
+    "build:docs": "typedoc",
+    "build:docs:watch": "npm run --silent build:docs -- --watch",
+    "dev": "tshy --watch",
+    "dev:docs": "run-p build:docs:watch serve",
+    "lint": "eslint .",
+    "lint:commit": "commitlint",
+    "lint:fix": "eslint . --fix",
+    "lint:staged": "lint-staged",
+    "lint:types": "tsc -b .config/tsconfig.eslint.json",
+    "lint:types:dev": "npm run --silent lint:types -- --watch",
+    "prepare": "husky",
+    "serve": "serve docs",
+    "test": "node --import tsx --test \"test/**/*.ts\"",
+    "test:property": "node --import tsx --test \"test/property/**/*.test.ts\"",
+    "test:property:dev": "node --import tsx --test --watch \"test/property/**/*.test.ts\"",
+    "test:watch": "node --import tsx --test \"test/**/*.ts\" --watch"
+  },
+  "peerDependencies": {
+    "zod": "^4.1.5"
+  },
+  "dependencies": {
+    "debug": "^4.4.1",
+    "slug": "^11.0.0"
+  },
+  "optionalDependencies": {
+    "zod": "^4.1.5"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "19.8.1",
+    "@commitlint/config-conventional": "19.8.1",
+    "@eslint/js": "9.33.0",
+    "@stylistic/eslint-plugin": "5.2.3",
+    "@types/node": "22.7.4",
+    "@types/slug": "5.0.9",
+    "@types/wallabyjs": "0.0.15",
+    "eslint": "9.33.0",
+    "eslint-plugin-jsonc": "2.20.1",
+    "eslint-plugin-perfectionist": "4.15.0",
+    "expect-type": "1.2.2",
+    "fast-check": "4.2.0",
+    "husky": "9.1.7",
+    "knip": "5.62.0",
+    "lint-staged": "16.1.5",
+    "npm-run-all2": "8.0.4",
+    "prettier": "3.6.2",
+    "prettier-plugin-jsdoc": "1.3.3",
+    "prettier-plugin-pkg": "0.21.2",
+    "prettier-plugin-sort-json": "4.1.1",
+    "serve": "14.2.5",
+    "tshy": "3.0.2",
+    "tsx": "4.20.5",
+    "type-fest": "4.41.0",
+    "typedoc": "0.28.12",
+    "typedoc-github-theme": "0.3.1",
+    "typedoc-plugin-mdn-links": "5.0.9",
+    "typedoc-plugin-zod": "1.4.2",
+    "typescript": "5.9.2",
+    "typescript-eslint": "8.40.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "knip": {
+    "ignoreDependencies": [
+      "@types/wallabyjs",
+      "serve"
+    ],
+    "ignore": [
+      ".wallaby.js",
+      "**/*.cts",
+      "**/*.d.ts"
+    ],
+    "tags": [
+      "-knipignore"
+    ],
+    "node": {
+      "entry": [
+        "test/**/*.test.ts"
+      ]
+    }
+  },
+  "lint-staged": {
+    "*.{ts,cts,js,json,md,yml,json5}": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  },
+  "prettier": {
+    "jsdocCommentLineStrategy": "keep",
+    "jsdocPreferCodeFences": true,
+    "plugins": [
+      "prettier-plugin-jsdoc",
+      "prettier-plugin-pkg",
+      "prettier-plugin-sort-json"
+    ],
+    "singleQuote": true,
+    "tsdoc": true
+  },
+  "tshy": {
+    "exports": {
+      "./package.json": "./package.json",
+      ".": "./src/index.ts"
+    }
+  }
+}

package/src/api.ts

@@ -0,0 +1,149 @@
+/**
+ * Contains the main API types
+ *
+ * @packageDocumentation
+ */
+
+import type { TupleToUnion, UnionToIntersection } from 'type-fest';
+
+import type {
+  AnyAsyncAssertion,
+  AnyAsyncAssertions,
+  AnySyncAssertion,
+  AnySyncAssertions,
+  BuiltinAsyncAssertions,
+  BuiltinSyncAssertions,
+} from './assertion/assertion-types.js';
+import type {
+  createAssertion,
+  createAsyncAssertion,
+} from './assertion/create.js';
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { expect, expectAsync } from './bootstrap.js';
+
+import {
+  type InferredExpectSlots,
+  type MutableOrReadonly,
+  type UseFn,
+} from './types.js';
+
+/**
+ * Base set of properties included in both {@link Expect} and {@link ExpectAsync}.
+ */
+export interface BaseExpect {
+  /**
+   * Creates a new synchronous assertion.
+   */
+  createAssertion: typeof createAssertion;
+  /**
+   * Creates a new asynchronous assertion.
+   */
+  createAsyncAssertion: typeof createAsyncAssertion;
+  /**
+   * Fails immediately with optional `reason`.
+   *
+   * @param reason Reason for failure
+   * @throws {AssertionError}
+   */
+  fail(this: void, reason?: string): never;
+}
+
+/**
+ * The main synchronous assertion function.
+ *
+ * Contains properties in {@link ExpectSyncProps}.
+ *
+ * @template T All synchronous assertions available
+ * @template U All asynchronous assertions available; for use in
+ *   {@link ExpectSyncProps.use}
+ * @useDeclaredType
+ * @see {@link expect}
+ */
+
+export type Expect<
+  T extends AnySyncAssertions = BuiltinSyncAssertions,
+  U extends AnyAsyncAssertions = BuiltinAsyncAssertions,
+> = ExpectFunction<T> & ExpectSyncProps<T, U>;
+
+/**
+ * The main asynchronous assertion function.
+ *
+ * Contains properties in {@link ExpectSyncProps}.
+ *
+ * @useDeclaredType
+ * @see {@link expectAsync}
+ */
+
+export type ExpectAsync<
+  T extends AnyAsyncAssertions = BuiltinAsyncAssertions,
+  U extends AnySyncAssertions = BuiltinSyncAssertions,
+> = ExpectAsyncFunction<T> & ExpectAsyncProps<T, U>;
+
+/**
+ * All function overloads for `expectAsync()`; part of {@link ExpectAsync}.
+ */
+
+export type ExpectAsyncFunction<
+  T extends AnyAsyncAssertions = BuiltinAsyncAssertions,
+> = UnionToIntersection<
+  TupleToUnion<{
+    [K in keyof T]: T[K] extends AnyAsyncAssertion
+      ? (
+          ...args: MutableOrReadonly<InferredExpectSlots<T[K]['parts']>>
+        ) => Promise<void>
+      : never;
+  }>
+>;
+
+/**
+ * Properties available on `expectAsync()`; part of {@link ExpectAsync}.
+ */
+
+export interface ExpectAsyncProps<
+  T extends AnyAsyncAssertions,
+  U extends AnySyncAssertions,
+> extends BaseExpect {
+  /**
+   * Tuple of all assertions available in this `expect()`.
+   */
+  assertions: T;
+  /**
+   * Function to add more assertions to this `expect()`, returning a new
+   * `expect()` and `expectAsync()` pair with the combined assertions.
+   */
+  use: UseFn<U, T>;
+}
+
+/**
+ * All function overloads for `expect()`; part of {@link Expect}.
+ *
+ * @useDeclaredType
+ */
+export type ExpectFunction<
+  T extends AnySyncAssertions = BuiltinSyncAssertions,
+> = UnionToIntersection<
+  TupleToUnion<{
+    [K in keyof T]: T[K] extends AnySyncAssertion
+      ? (...args: MutableOrReadonly<InferredExpectSlots<T[K]['parts']>>) => void
+      : never;
+  }>
+>;
+
+/**
+ * Properties for `expect()`; part of {@link Expect}.
+ */
+export interface ExpectSyncProps<
+  T extends AnySyncAssertions,
+  U extends AnyAsyncAssertions,
+> extends BaseExpect {
+  /**
+   * Tuple of all assertions available in this `expect()`.
+   */
+  assertions: T;
+
+  /**
+   * Function to add more assertions to this `expect()`, returning a new
+   * `expect()` and `expectAsync()` pair with the combined assertions.
+   */
+  use: UseFn<T, U>;
+}