bupkis 0.0.2 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.1.0](https://github.com/boneskull/bupkis/compare/bupkis-v0.0.2...bupkis-v0.1.0) (2025-09-08)
+
+
+### Features
+
+* **use:** use() returns an object with a use() in it ([fb383d6](https://github.com/boneskull/bupkis/commit/fb383d6fb2f541085d2300664fe73b25c6249e42))
+
+
+### Bug Fixes
+
+* **package:** add description and homepage ([2ff82ea](https://github.com/boneskull/bupkis/commit/2ff82ea715280098f59612ba32da808308aced0e))
+
 ## [0.0.2](https://github.com/boneskull/bupkis/compare/bupkis-v0.0.1...bupkis-v0.0.2) (2025-09-07)
 
 

package/README.md

@@ -1,34 +1,51 @@
 <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>
+  <img src="./assets/bupkis-logo-512.png" width="512px" align="center" alt="BUPKIS logo"/>
+  <h1 align="center"><span class="twentieth-century-caps">⁓ BUPKIS ⁓<span></h1>
   <p align="center">
-    A well-typed and easily exensible <em>BDD-style</em> assertion library.
+    Uncommonly extensible assertions for the beautiful people
     <br/>
-    by <a href="https://github.com/boneskull">@boneskull</a>
+    <small>by <a href="https://github.com/boneskull">@boneskull</a></small>
   </p>
 </p>
 
+## Quick Links
+
+- [BUPKIS' Homepage][docs] (<https://bupkis.zip>)
+- [Assertion Reference][assertion-reference]
+- [Guide: Basic Usage][basic-usage]
+- [Guide: How to Create a Custom Assertion][create-a-custom-assertion]
+
 ## Motivation
 
+> "_Another_ assertion library? You cannot be serious. My test framework has its own assertions!"
+>
+> ‒sickos, probably
+
 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:
+But none of them do quite what _BUPKIS_ does. I want an assertion library that prioritizes:
 
 - Type safety
-- Dead-simple creation of custom assertions
-- Minimal API surface
+- Uncompromisable extensibility
+- A small 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.
+I can think of several that tick two-thirds of those boxes! But _I demand the total package_ (And You Should Too).
 
-> [!WARNING]
+> ⚠️ **Caution!**
+>
+> Assertion libraries tend come in two flavors: chainable or stiff & traditional. But because these styles are likely _familiar_ to you, you may hate _BUPKIS_.
+>
+> I _want_ you to like it, yes. But if you don't, I'm content with just making my point and asking the following favor of the reader:
 >
-> 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_.
+> **Do not confuse _familiarity_ with _usability_.**
 
-To achieve these goals, I've adopted the following design principles:
+The following is a brief overview of the design choices We made to serve these goals.
 
-### Natural-Language Assertions
+### Natural Language Assertions
 
-In `bupkis` (stylized as "_BUPKIS_"), you **don't** write this:
+In _BUPKIS_, "natural language" is the means to the end of "a small API surface".
+
+When you're using _BUPKIS_, you **don't** write this:
 
 ```js
 expect(actual).toEqual(expected);
@@ -50,7 +67,7 @@ expect(actual, 'is equal to', expected);
 expect(actual, 'to strictly equal', expected);
 ```
 
-If Chai wants you to write:
+If another assertion library wants you to write:
 
 ```js
 expect(actual).to.be.a('string');
@@ -60,111 +77,150 @@ Then _BUPKIS_ wants you to write:
 
 ```js
 expect(actual, 'to be a string');
-// it is tolerant of poor/ironic grammar
+// it is tolerant of poor/ironic grammar, sometimes
 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.
+Can't remember the phrase? 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.
+This isn't black magic. It ain't no _cauldron_. We're not just _throwing rat tails and `string`s into a function and stirring that shit up._
 
-You can negate just about any phrase:
+> "Preposterous! Codswallop!"
+>
+> ‒the reader and/or more sickos
 
-```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/,
-);
-```
+You may wonder how this could this be anything _but_ loosey-goosey _senselessness_. On the contrary—we have _conventions_!
 
-### Custom Assertions
+#### Conventions of `expect()`
 
-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!_
+To formalize the conventions at a high level:
 
-Read [Guide: How to Create a Custom Assertion](https://boneskull.github.io/bupkis/documents/Guides.How_to_Create_a_Custom_Assertion) to learn more.
+- The first parameter to a _BUPKIS_ assertion is always the _subject_ ([def.](https://bupkis.zip/documents/Reference.Glossary_of_Terms#subject)).
 
-## Prerequisites
+- The "string" part of a _BUPKIS_ assertion is known as a _phrase_. Every expectation will contain _at minimum_ one (1) phrase. As you can see from the above "to be a string" example, phrases often have aliases.
 
-_BUPKIS_ requires **Node.js ^20.19.0 || ^22.12.0 || >=23** and ships as a dual CJS/ESM package.
+- Assertions may have multiple phrases or parameters, but the simplest assertions always look like this:
 
-The library has been designed for Node.js environments and testing frameworks.
+  ```ts
+  expect(subject, 'phrase');
+  ```
 
-## Installation
+  ...and more complex assertions look like this:
 
-```bash
-npm install bupkis -D
-```
+  ```ts
+  expect(subject, 'phrase', [parameter?, phrase?, parameter?, ...]);
+  ```
 
-## Usage
+- One more convention worth mentioning is _negation_.
+
+  You can _negate_ just about any phrase by prepending it with `not` and a space. For example:
+
+  ```js
+  expect(actual, 'to be', expected);
+  expect(actual, 'not to be', expected);
+
+  expect(
+    () => throw new TypeError('aww, shucks'),
+    'not to throw a',
+    TypeError,
+    'satisfying',
+    /gol durn/,
+  );
+  ```
+
+  Handy!
+
+### Custom Assertions Built With Zod
+
+[Zod][] is a popular object validation library which does some heavy lifting for _BUPKIS_—most of the built-in assertions are implemented using Zod schemas. And so _BUPKIS_ extends this capability to you.
 
-Here:
+An example will be illuminating. What follows is a ~~stupid~~ ~~quick~~ _stupid_ example of a creating and "registering" a basic assertion _which can be invoked using two different phrases_:
 
 ```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' });
-```
+import { z, use, createAssertion } from 'bupkis';
 
-For comprehensive documentation and guides, visit the [project documentation](https://boneskull.github.io/bupkis/).
+const stringAssertion = createAssertion(
+  z.string(),
+  [['to be based', 'to be bussin']],
+  z.string(),
+);
 
-### Worth Mentioning Right Now
+const { expect } = use([stringAssertion]);
 
-_BUPKIS_ has two main exports:
+expect('chat', 'to be based');
+expect('fam', 'to be bussin');
 
-- `expect()`: the main entrypoint for synchronous assertions
-- `expectAsync()`: the main entrypoint for asynchronous assertions
+// did you know? includes all builtin assertions!
+expect('skiball lavatory', 'to be a string');
+```
 
-> [!IMPORTANT]
+> 📒 Registration?
 >
-> 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.**
+> "Registration" of an assertion (though there is no stateful "registry" anywhere) is as straightforward as passing an array of `Assertion` instances (created via `createAssertion()`/`createAsyncAssertion()`) to the `use()` function.
+>
+> `use()`, as exported from `bupkis`, returns a new `expect()`/`expectAsync()` pair that includes your custom assertions alongside all the built-in ones. The new `expect()`/`expectAsync()` functions are fully type-safe and aware of your custom assertions. They _also_ have a `.use()` method, which allows you to compose sets of assertions from disjoint sources.
+
+**Zod makes it extremely easy to create most custom assertions**. But despite its power, it can't do _everything_ we need an assertion to do; for those situations, there's also a [function-based API][custom-assertion-function] for use with [parametric][] and behavioral (e.g., involving function execution) assertions.
+
+👉 For an assiduous guide on creating assertions, read [Guide: How to Create a Custom Assertion][create-a-custom-assertion].
+
+### Excruciating Type Safety
+
+We have tried to make _BUPKIS_ is as type-safe as possible. To be clear, _that is pretty damn possible_. This means:
+
+- Every built-in assertion is fully type-safe and is declared as an overload for `expect()` or `expectAsync()`.
+- Every _custom_ assertion is _also_ fully type-safe and is declared as an overload for `expect()` or `expectAsync()` (as returned from `use()`)
+- If an assertion demands the _subject_ be of a certain type, the TS compiler will squawk if you try to use an incompatible subject type. For example, `<Map> to have size <number>` will only accept a `Map` as the subject, and this will be obvious in your editor.
+
+> _Note_: `expect()` is not and cannot be a type guard; see the ["Caveats" Reference doc](http://bupkis.zip/documents/Reference.Caveats#expect-is-not-a-type-guard) for more information.
+
+## Prerequisites
 
-## Project Scope
+**Node.js**: ^20.19.0, ^22.12.0, >=23
 
-1. It's an assertion library
+_BUPKIS_ has a peer dependency on [Zod][] v4+, but will install it as an optional dependency if you are not already using it.
 
-### TODO
+_BUPKIS_ ships as a dual CJS/ESM package.
 
-## Prior Art & Appreciation
+> Disclaimer: _BUPKIS_ has been designed to run on Node.js in a development environment. Anyone attempting to deploy _BUPKIS_ to some server somewhere will get what is coming to them.
+
+## Installation
+
+```bash
+npm install bupkis -D
+```
+
+## Usage
+
+👉 See the [Basic Usage Guide](https://bupkis.zip/documents/guides.basic_usage) for a quick introduction.
+
+📖 Visit [https://bupkis.zip](https://bupkis.zip) for comprehensive guides and reference.
+
+## Acknowledgements
 
 - [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!
+- [Zod][] is a popular object validation library upon which _BUPKIS_ builds many of its own assertions.
+- [fast-check][]: 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!
+- [tshy][] from Isaac Schlueter. Thanks for making dual ESM/CJS packages easy and not too fancy.
+- [TypeDoc][] it really documents the hell out of TypeScript projects.
+- [@cjihrig](https://github.com/cjihrig) and other Node.js contributors for the thoughtfulness put into [`node:test`](https://nodejs.org/api/test.html) that make it my current test-runner-of-choice.
 
-## A Note From The Author
+## Why is it called _BUPKIS_?
 
-> _"This is my assertion library. Many are like it, but this one is mine."_
->
-> ‒boneskull, 2025
+TODO: think of good reason and fill in later
 
 ## License
 
 Copyright © 2025 Christopher Hiller. Licensed under [BlueOak-1.0.0](https://blueoakcouncil.org/license/1.0.0).
 
 [zod]: https://zod.dev
+[docs]: https://bupkis.zip
+[basic-usage]: https://bupkis.zip/documents/guides.basic_usage
 [unexpected]: https://unexpected.js.org
 [fast-check]: https://fast-check.dev
+[parametric]: https://bupkis.zip/documents/Reference.Glossary_of_Terms#parametric-assertion
+[custom-assertion-function]: https://bupkis.zip/documents/guides.how_to_create_a_custom_assertion#using-a-function
+[create-a-custom-assertion]: https://bupkis.zip/documents/Guides.How_to_Create_a_Custom_Assertion
+[assertion-reference]: https://bupkis.zip/documents/reference.assertions
+[tshy]: https://github.com/isaacs/tshy
+[typedoc]: https://typedoc.org

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "bupkis",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "type": "module",
-  "description": "",
+  "description": "Uncommonly extensible assertions for the beautiful people",
   "repository": {
     "url": "git+https://github.com/boneskull/bupkis.git"
   },
+  "homepage": "https://bupkis.zip",
   "author": {
     "name": "Christopher Hiller",
     "email": "boneskull@boneskull.com"
@@ -60,9 +61,11 @@
     "build:docs:watch": "npm run --silent build:docs -- --watch",
     "dev": "tshy --watch",
     "dev:docs": "run-p build:docs:watch serve",
-    "lint": "eslint .",
+    "lint": "run-p lint:eslint lint:types lint:knip",
     "lint:commit": "commitlint",
-    "lint:fix": "eslint . --fix",
+    "lint:eslint": "eslint .",
+    "lint:fix": "run-s \"lint:eslint -- --fix\"",
+    "lint:knip": "knip",
     "lint:staged": "lint-staged",
     "lint:types": "tsc -b .config/tsconfig.eslint.json",
     "lint:types:dev": "npm run --silent lint:types -- --watch",
@@ -86,19 +89,19 @@
   "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",
+    "@eslint/js": "9.34.0",
+    "@stylistic/eslint-plugin": "5.3.1",
+    "@types/node": "22.18.1",
     "@types/slug": "5.0.9",
     "@types/wallabyjs": "0.0.15",
-    "eslint": "9.33.0",
+    "eslint": "9.34.0",
     "eslint-plugin-jsonc": "2.20.1",
     "eslint-plugin-perfectionist": "4.15.0",
     "expect-type": "1.2.2",
-    "fast-check": "4.2.0",
+    "fast-check": "4.3.0",
     "husky": "9.1.7",
-    "knip": "5.62.0",
-    "lint-staged": "16.1.5",
+    "knip": "5.63.1",
+    "lint-staged": "16.1.6",
     "npm-run-all2": "8.0.4",
     "prettier": "3.6.2",
     "prettier-plugin-jsdoc": "1.3.3",
@@ -109,11 +112,10 @@
     "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"
+    "typescript-eslint": "8.42.0"
   },
   "publishConfig": {
     "access": "public",
@@ -121,13 +123,13 @@
   },
   "knip": {
     "ignoreDependencies": [
-      "@types/wallabyjs",
-      "serve"
+      "@types/wallabyjs"
     ],
     "ignore": [
       ".wallaby.js",
       "**/*.cts",
-      "**/*.d.ts"
+      "**/*.d.ts",
+      "assets/**/*"
     ],
     "tags": [
       "-knipignore"

package/src/bootstrap.ts

@@ -24,7 +24,7 @@ import {
  * @returns Object containing `expect` and `expectAsync` functions
  * @internal
  */
-export const bootstrap = (): {
+const bootstrap = (): {
   expect: Expect<typeof SyncAssertions>;
   expectAsync: ExpectAsync<typeof AsyncAssertions>;
 } => {

package/src/expect.ts

@@ -225,7 +225,7 @@ const execute = <
  * @param stackStartFn - Function for stack trace management
  * @param isNegated - Whether the assertion should be negated
  */
-export const executeAsync = async <
+const executeAsync = async <
   T extends AssertionAsync<Parts, AssertionImplAsync<Parts>, Slots>,
   Parts extends AssertionParts,
   Slots extends AssertionSlots<Parts>,

package/src/types.ts

@@ -147,13 +147,19 @@ export type MutableOrReadonly<T> = T extends readonly (infer U)[]
  */
 export type Negation<T extends string> = `not ${T}`;
 
-export type UseFn<T extends AnySyncAssertions, U extends AnyAsyncAssertions> = <
-  V extends readonly AnyAssertion[],
-  W extends FilterSyncAssertions<V>,
-  X extends FilterAsyncAssertions<V>,
->(
-  assertions: V,
-) => {
-  expect: Expect<Concat<T, W>, Concat<U, X>>;
-  expectAsync: ExpectAsync<Concat<U, X>, Concat<T, W>>;
-};
+export interface UseFn<
+  T extends AnySyncAssertions,
+  U extends AnyAsyncAssertions,
+> {
+  <
+    V extends readonly AnyAssertion[],
+    W extends FilterSyncAssertions<V>,
+    X extends FilterAsyncAssertions<V>,
+  >(
+    assertions: V,
+  ): {
+    expect: Expect<Concat<T, W>, Concat<U, X>>;
+    expectAsync: ExpectAsync<Concat<U, X>, Concat<T, W>>;
+    use: UseFn<Concat<T, W>, Concat<U, X>>;
+  };
+}

package/src/use.ts

@@ -56,7 +56,10 @@ export function createUse<
 
     return {
       expect,
-      expectAsync: expectAsync,
+      expectAsync,
+      get use() {
+        return createUse(allSyncAssertions, allAsyncAssertions);
+      },
     };
   };
   return use;