Skip to content

Publish the adapter contract suite as a reusable test kit #58

Description

@camcima

Deferred from the architecture review (finding L7) — see ARCHITECTURE_REVIEW.md.

Problem

packages/core/tests/contract/adapter-contract.test.ts is what keeps the four built-in adapters behaviorally interchangeable. Every adapter package imports it by relative path:

import { runAdapterContractTests } from "../../../core/tests/contract/adapter-contract.test.js";

That works inside the monorepo and nowhere else. @ziggurat-cache/core ships only dist and README.md, so the suite is not on npm.

Meanwhile docs/custom-adapters.md invites people to build their own CacheAdapter. They cannot run the compliance suite that the first-party adapters are held to — the doc currently just lists the behaviors in prose and asks them to reproduce it by hand.

For a library whose selling point is a modular adapter ecosystem, this is the gap worth closing: it turns "implement this interface" into "pass this suite."

Sketch

Publish the suite as @ziggurat-cache/adapter-testkit:

  • New package exporting runAdapterContractTests(name, factory, options).
  • vitest moves to a peer dependency — consumers bring their own runner.
  • The four adapter packages import the published entry point instead of reaching across directories, which also removes the rootDir TypeScript complaints those relative imports currently produce.
  • docs/custom-adapters.md replaces its prose checklist with real usage, and drops the "not published yet" caveat added in docs: separate the dev and consumer Node floors #57.

Done when

  • An adapter developed outside this repo can npm i -D @ziggurat-cache/adapter-testkit and run the same suite CI runs here.
  • No adapter package imports across package boundaries by relative path.
  • Release wiring covers the new package.

Notes

Deliberately left out of #56 because it is a new published package — build config, release wiring, docs — rather than a fix to existing code.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions