penultimate 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Woodell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+# penultimate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![Vitest](https://img.shields.io/badge/Vitest-4.1+-6E9F18?logo=vitest&logoColor=white)](package.json)
+[![CI](https://github.com/woodie/penultimate/actions/workflows/ci.yml/badge.svg)](https://github.com/woodie/penultimate/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/penultimate.svg)](https://www.npmjs.com/package/penultimate)
+[![Release](https://img.shields.io/github/v/release/woodie/penultimate.svg)](https://github.com/woodie/penultimate/releases/latest)
+[![License](https://img.shields.io/github/license/woodie/penultimate.svg)](LICENSE)
+
+A `justBeforeEach` hook for Vitest -- real nested `context`s with less
+duplication between them, inspired by [Quick](https://github.com/Quick/Quick).
+The name says when it runs: penultimate, second to last, right before the
+test itself. Works with Vitest 4.1 and later 4.x releases; Vitest 5 isn't
+supported yet (see [Requirements](#requirements)).
+
+## Installation
+
+Since `penultimate` is only ever imported from test files, it belongs in
+`devDependencies`:
+
+```
+npm install --save-dev penultimate
+```
+
+There's nothing to register or configure -- import it and use it.
+
+## `justBeforeEach`
+
+Vitest's own `beforeEach` runs fresh before every `it`, from the outermost
+`describe` inward -- but there's no hook that runs *after* every
+`beforeEach` at every nesting depth, immediately before the `it` itself.
+That's `justBeforeEach`'s job: separate what varies (set by an ordinary
+`beforeEach` in each `context`) from the action under test (declared once,
+in the parent):
+
+```js
+import { beforeEach, describe, expect, it } from 'vitest'
+import { justBeforeEach } from 'penultimate'
+
+const context = describe
+
+describe('Calculator', () => {
+  let calculator
+
+  beforeEach(() => { calculator = new Calculator() })
+
+  describe('#divide', () => {
+    let numerator, denominator, result
+
+    beforeEach(() => { numerator = 10; denominator = 2 })
+
+    justBeforeEach(() => { result = calculator.divide(numerator, denominator) })
+
+    it('returns the quotient', () => {
+      expect(result).toBe(5)
+    })
+
+    context('when the numerator leaves a remainder', () => {
+      beforeEach(() => { numerator = 7 })
+
+      it('drops the remainder', () => {
+        expect(result).toBe(3)
+      })
+    })
+
+    context('when the denominator is 1', () => {
+      beforeEach(() => { denominator = 1 })
+
+      it('returns the numerator', () => {
+        expect(result).toBe(10)
+      })
+    })
+  })
+})
+```
+
+Here, `#divide` sets default inputs in an ordinary `beforeEach`, and each
+`context` overrides only the one it's about. The call itself can't go in
+that `beforeEach`, because Vitest runs a parent's `beforeEach` before its
+children's: it would divide 10 by 2 every time, before any `context` had
+changed an input. Because `justBeforeEach` runs after every `beforeEach` at
+every depth, it always sees the final inputs, and each `it` just checks
+`result`. In RSpec terms, the defaults play the part of `let`, and
+`justBeforeEach` plays `subject`, which RSpec can leave lazy instead.
+
+When several `justBeforeEach` blocks apply to one test, they run outermost
+first, the same order as `beforeEach`. Each one gets the same test context
+a `beforeEach` gets (`({ task }) => ...`), and an `async` one is awaited
+before the next.
+
+## Works with Vitest's own `it`
+
+You keep importing `it` and `test` from `vitest`, since `penultimate`
+doesn't replace them, so `it.each`, `it.skip`, `it.only`, `it.fails`, `it.concurrent`
+and `retry` all behave as usual. Each test gets its own queue of
+`justBeforeEach` steps, so concurrent tests don't share them, and a retried
+test runs them again.
+
+## A step that might throw
+
+The usual reason to hoist an action into `justBeforeEach` is to share it
+across sibling `context`s -- including ones where the action is expected to
+fail. Left alone, a throw inside the step fails the test before any
+expectation runs, so the error-path `context` can't assert on it. Capture
+the outcome instead, and let each `it` check whichever half it cares about:
+
+```js
+describe('#divide', () => {
+  let numerator, denominator, result, error
+
+  beforeEach(() => { numerator = 10; denominator = 2 })
+
+  justBeforeEach(() => {
+    result = error = undefined
+    try { result = calculator.divide(numerator, denominator) } catch (e) { error = e }
+  })
+
+  it('returns the quotient', () => {
+    expect(result).toBe(5)
+  })
+
+  context('when the denominator is 0', () => {
+    beforeEach(() => { denominator = 0 })
+
+    it('reports it', () => {
+      expect(error.message).toBe('division by zero')
+    })
+  })
+})
+```
+
+Clearing `result` and `error` at the top of the step means no test can see
+an outcome left over from the one before it.
+
+## Scoping variables
+
+The usual way to share a value between hooks and tests is a `let` declared
+in the `describe` body. Vitest runs that body only once, to collect the
+tests, so anything assigned there is shared by every test below it -- and a
+test that changes it leaves the change behind for the next one. Assign
+starting values in a `beforeEach` instead, so every test begins from the
+same place, and let each `context`'s own `beforeEach` change only what it's
+about.
+
+## Requirements
+
+Vitest 4.1 or a later 4.x release, and Node 20 or later.
+
+Under the hood, `penultimate` works by replacing each test's body with one that runs the queued
+steps first, using `getFn` and `setFn` from `@vitest/runner`, which Vitest 4
+installs alongside itself. Vitest 5 bundles that package inside `vitest`
+instead, and the replacement it offers, `TestRunner.setTestFn`, currently
+reads a test's body rather than setting it -- so there's no working way to
+do this on Vitest 5 yet.
+
+## Development
+
+```
+make build   # tsc -p tsconfig.build.json
+make test    # vitest run --reporter=tree
+make lint    # eslint . && tsc --noEmit
+make check   # terse: lint, typecheck, and tests
+```

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { type TestContext } from 'vitest';
+export type Step = (context: TestContext) => unknown;
+export declare function justBeforeEach(step: Step): void;

package/dist/index.js

@@ -0,0 +1,25 @@
+import { beforeEach } from 'vitest';
+import { getFn, setFn } from '@vitest/runner';
+const queues = new WeakMap();
+function queueFor(task) {
+    const queued = queues.get(task);
+    if (queued !== undefined)
+        return queued;
+    const queue = [];
+    queues.set(task, queue);
+    const test = getFn(task);
+    // Vitest reads the test body only after every beforeEach has run, so the steps land in between.
+    setFn(task, async () => {
+        for (const step of queue)
+            await step();
+        return test();
+    });
+    return queue;
+}
+export function justBeforeEach(step) {
+    beforeEach((context) => {
+        const queue = queueFor(context.task);
+        queue.push(() => step(context));
+        return () => { queue.length = 0; };
+    });
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "penultimate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "A justBeforeEach hook for Vitest, inspired by Quick",
+  "keywords": [
+    "vitest",
+    "justBeforeEach",
+    "beforeEach",
+    "bdd",
+    "rspec",
+    "quick",
+    "describe",
+    "context"
+  ],
+  "license": "MIT",
+  "author": "John Woodell <woodie@netpress.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/woodie/penultimate.git"
+  },
+  "homepage": "https://github.com/woodie/penultimate#readme",
+  "bugs": "https://github.com/woodie/penultimate/issues",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "npm run build",
+    "lint": "eslint . && tsc --noEmit",
+    "test": "vitest run --reporter=tree",
+    "check": "eslint . && tsc --noEmit && vitest run --reporter=dot",
+    "prepublishOnly": "npm run check && npm run build"
+  },
+  "peerDependencies": {
+    "@vitest/runner": ">=4.1.0 <5",
+    "vitest": ">=4.1.0 <5"
+  },
+  "devDependencies": {
+    "@vitest/eslint-plugin": "^1.6.27",
+    "@vitest/runner": "^4.1.11",
+    "eslint": "^10.12.0",
+    "neostandard": "^0.14.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11"
+  }
+}