Default engine — `@suaveplan/rules-hono/engine`

(no submodules)

Purpose

getDefaultEngine() exposes a lazy, per-process RuleEngine instance for callers who do not want to construct or thread an engine through their middleware stack. It is constructed exactly once on first call and cached for the lifetime of the process; every subsequent call returns the identical reference. Tests break the cache via resetDefaultEngine() exposed under the ./testing subpath.

This pattern replaces the upstream module-level singleton defaultEngine = new RuleEngine() — eager module-scope instantiation is a hidden global per AGENTS.md §6a and creates a side-effect on import that prevents tree-shaking even when no caller uses the default. Lazy construction defers the cost until a real call site fires.

Features

Lazy singleton, identity-stable across calls.
Cache reset hook surfaced only via the ./testing subpath — production import paths cannot drop the cache.
Zero arguments — the default engine is constructed with the RuleEngine defaults; consumers that want a configured engine should instantiate new RuleEngine(config) themselves and pass it explicitly to the relevant middleware factory.

Usage: Basic Example

import { getDefaultEngine } from "@suaveplan/rules-hono/engine";

const engine = getDefaultEngine();
// engine is the process singleton — every other caller of getDefaultEngine sees the same instance

Usage: Advanced Example

import { describe, it, expect } from "@suaveplan/testing/runner";
import { getDefaultEngine } from "@suaveplan/rules-hono/engine";
import { resetDefaultEngine } from "@suaveplan/rules-hono/testing";

describe("my middleware", () => {
    it("uses a fresh engine per test", () => {
        resetDefaultEngine();
        const a = getDefaultEngine();
        // ... test against a ...
        resetDefaultEngine();
        const b = getDefaultEngine();
        expect(a).not.toBe(b);
    });
});

API Reference

`getDefaultEngine(): RuleEngine`

Returns the cached default engine; constructs it on first call.

`resetDefaultEngine(): void` (`./testing` subpath only)

Drops the cache. Strictly test-only — production code that needs a fresh engine should call new RuleEngine() directly.

Implementation Notes

The cache lives in module scope, so identity is per-process (matching every other ES-module-loaded singleton in Suaveplan).
The exported reset symbol is named __resetDefaultEngineForTesting internally and re-exported from the ./testing subpath as resetDefaultEngine. The double-underscore prefix is a soft convention to discourage accidental production imports; the hard guarantee is the subpath split.
If consumers want telemetry-instrumented or plugin-configured engines, they construct their own and pass it via the engine option on every middleware factory. The default engine is for the "I just want this to work" path.

2.9 KiB Raw Blame History

Default engine — @suaveplan/rules-hono/engine