@affiant/core 0.1.0-alpha.0 → 0.1.0-alpha.2

package/dist/testing-store.d.ts

@@ -0,0 +1,214 @@
+/**
+ * The store contract — every assertion a Docket store has to pass, written once and
+ * parametrised over the store under test.
+ *
+ * `@affiant/core` ships an in-memory reference store, and a host running on a
+ * database ships its own. The two are only interchangeable if they are measured by
+ * the same assertions, so the assertions live here rather than in the reference
+ * store's own suite: {@link runDocketStoreContract} and
+ * {@link runSessionStoreContract} register them against whatever factory they are
+ * handed, and the reference store is simply the first caller.
+ *
+ * ```ts
+ * import { describe, it, expect, beforeAll, afterAll } from "vitest";
+ * import { InMemoryDocketStore } from "@affiant/core/store-memory";
+ * import { runDocketStoreContract } from "@affiant/core/testing";
+ *
+ * runDocketStoreContract((clock) => new InMemoryDocketStore({ clock }), {
+ *   api: { describe, it, expect, beforeAll, afterAll },
+ * });
+ * ```
+ *
+ * **The test runner comes in as a parameter.** Nothing here imports `vitest`, and
+ * `@affiant/core` gains no dependency — runtime, peer or optional — from carrying
+ * the contract. The caller passes the four functions it already has in scope, which
+ * is also what lets a store built on another runner run the same assertions.
+ *
+ * **A store is built once per block, and every case owns a tenant.** The factory is
+ * called from the block's `beforeAll`, because a store backed by a database is
+ * expensive to build and a fresh instance would not give a fresh database anyway.
+ * Isolation comes from tenancy instead: each case files under a tenant id of its
+ * own, which is a property the contract requires regardless (AZ-2). A case that
+ * needs a second tenant is handed one.
+ *
+ * **The clock is the case's.** A store is built with a {@link Clock} rather than
+ * handed an instant per call, so the harness owns a settable one, hands it to the
+ * factory, and resets it before every case.
+ *
+ * Rules the cases serve: DK-1 (idempotent filing, the guarded compare-and-set,
+ * expiry as queryable state, preserved amendments, execution recorded once,
+ * lineage), DK-2 (an amendment's `null` clears a field and an absent key leaves it
+ * alone), DK-3 (a bounded, paged, host-scheduled sweep and an opaque cursor on
+ * every list), DK-4 (retention, purge and export as hooks, and a row that reads
+ * forward), DK-5 (rehydration order), AZ-2 (a wrong-tenant lookup is a miss),
+ * AZ-5 (an approved write nobody has reported on is never aged out), GT-4 (a
+ * re-file never refreshes the deadline).
+ *
+ * @packageDocumentation
+ */
+import type { DocketEntry, NewEntryInit } from "./docket/entry.js";
+import type { DocketStore, Scope, SessionStore } from "./docket/store.js";
+import type { Affidavit, AffidavitField, JsonValue } from "./model/affidavit.js";
+import type { Clock } from "./ports.js";
+/**
+ * The matchers the contract uses.
+ *
+ * Declared here rather than imported so that this module names no test runner. The
+ * shape is a subset of what `vitest`, `jest` and `bun:test` all expose, so passing
+ * any of their `expect` functions satisfies it.
+ */
+export interface ContractMatchers {
+    toBe(expected: unknown): void;
+    toEqual(expected: unknown): void;
+    toBeNull(): void;
+    toHaveLength(length: number): void;
+    toContain(item: unknown): void;
+}
+/** One assertion, with its negation and its rejection form. */
+export interface ContractAssertion extends ContractMatchers {
+    /** The same matchers, inverted. */
+    readonly not: ContractMatchers;
+    /** Assertions about a rejected promise. */
+    readonly rejects: {
+        toThrow(expected?: ErrorConstructor): Promise<unknown>;
+    };
+}
+/** The `expect` function the contract is written against. */
+export interface ContractExpect {
+    (actual: unknown, message?: string): ContractAssertion;
+}
+/**
+ * The test runner's own API, handed in by the caller.
+ *
+ * Every member is declared as a method so that a runner's richer signature — a
+ * `describe` that also carries `.skip`, an `it` that takes a timeout — is accepted
+ * as it stands.
+ */
+export interface ContractRunnerApi {
+    describe(name: string, fn: () => void): void;
+    it(name: string, fn: () => Promise<void> | void): void;
+    beforeAll(fn: () => Promise<void> | void): void;
+    afterAll(fn: () => Promise<void> | void): void;
+    expect: ContractExpect;
+}
+/** How a contract run is configured. */
+export interface StoreContractOptions<TStore, TSection extends string> {
+    /** The test runner's `describe`, `it`, `beforeAll`, `afterAll` and `expect`. */
+    readonly api: ContractRunnerApi;
+    /** A label put in front of every block, when one store runs the contract twice. */
+    readonly name?: string;
+    /**
+     * Case ids not to register, each of which must be one this contract defines — an
+     * id nothing matches is a {@link RangeError}, because a skip that silently matches
+     * nothing is a case a store stopped running and nobody noticed.
+     */
+    readonly skip?: readonly string[];
+    /**
+     * The sections to register, defaulting to all of them. Same rule as `skip`: a
+     * section name this contract does not define is a {@link RangeError}.
+     */
+    readonly sections?: readonly TSection[];
+    /**
+     * Released in the block's `afterAll`, once per store the factory produced — where
+     * a store holds a database handle its owner has to close.
+     */
+    readonly dispose?: (store: TStore) => void | Promise<void>;
+}
+/** Builds the store under test on the harness's own clock. */
+export type DocketStoreFactory = (clock: Clock) => DocketStore | Promise<DocketStore>;
+/** Builds a store that is both a Docket and the rehydration surface over it. */
+export type SessionStoreFactory = (clock: Clock) => (DocketStore & SessionStore) | Promise<DocketStore & SessionStore>;
+/** A {@link Clock} a test drives by hand, so a deadline can be pinned to the millisecond. */
+export interface StubClock extends Clock {
+    /** Move the clock to `instant`. */
+    set(instant: string): void;
+}
+/** A {@link Clock} that reads `start` until a test moves it. */
+export declare function stubClock(start: string): StubClock;
+/** One sworn field, filled in enough to be a real Affidavit field. */
+export declare function sampleField(name: string, value: JsonValue): AffidavitField;
+/**
+ * An Affidavit over `names`, shaped like something a pipeline would actually file.
+ *
+ * Built through `withConfidence` rather than as an object literal so the three
+ * numbers on it are the ones AF-2 computes, never numbers a test author typed.
+ */
+export declare function sampleAffidavit(names?: readonly string[]): Affidavit;
+/** A filed entry with `entryId`, overridable field by field. */
+export declare function sampleEntry(entryId: string, overrides?: Partial<Omit<NewEntryInit, "entryId">>): DocketEntry;
+/** The ids of `entries`, in the order they were returned. */
+export declare function entryIds(entries: readonly DocketEntry[]): string[];
+/**
+ * One object that is both a Docket and the rehydration surface over it.
+ *
+ * A store built on a database implements both interfaces itself; the reference
+ * pair is two objects, and this is what hands them to
+ * {@link runSessionStoreContract} as one.
+ */
+export declare function withSessionStore(docket: DocketStore, sessions: SessionStore): DocketStore & SessionStore;
+/** What one contract case is handed. */
+export interface ContractCaseContext<TStore> {
+    /** The store under test, shared with the other cases of the same block. */
+    readonly store: TStore;
+    /** The harness's clock, reset to a fixed instant before this case. */
+    readonly clock: StubClock;
+    /** The runner's `expect`. */
+    readonly expect: ContractExpect;
+    /** This case's own tenant: nothing another case filed is visible in it. */
+    readonly scope: Scope;
+    /** A second tenant, for the cases that need one. */
+    readonly otherScope: Scope;
+    /** This case's tenant narrowed to one conversation. */
+    conversation(conversationId: string): Scope;
+    /** An entry in this case's tenant, overridable field by field. */
+    entry(entryId: string, overrides?: Partial<Omit<NewEntryInit, "entryId">>): DocketEntry;
+}
+/** The blocks {@link runDocketStoreContract} registers. */
+export type DocketContractSection = "filing" | "transition" | "deadline" | "execution" | "lineage" | "sweep" | "paging" | "retention" | "purge" | "export" | "tenancy";
+/** The blocks {@link runSessionStoreContract} registers. */
+export type SessionContractSection = "rehydration";
+/** The rehydration sequence DK-5 fixes, for the store the harness was handed. */
+type SessionStoreUnderTest = DocketStore & SessionStore;
+/** Every block {@link runDocketStoreContract} registers, in registration order. */
+export declare const DOCKET_CONTRACT_SECTIONS: readonly DocketContractSection[];
+/** Every block {@link runSessionStoreContract} registers, in registration order. */
+export declare const SESSION_CONTRACT_SECTIONS: readonly SessionContractSection[];
+/**
+ * One case of a contract, as a caller sees it from outside.
+ *
+ * `id` is what `skip` names; `block` and `title` are the two names the case is
+ * registered under, which is what lets a caller check that a suite registered the
+ * cases it was supposed to rather than that it meant to.
+ */
+export interface ContractCaseSummary {
+    /** The id `skip` names. Stable across releases. */
+    readonly id: string;
+    /** The block the case belongs to, which `sections` names. */
+    readonly section: string;
+    /** The name of the `describe` the case is registered under, without any label. */
+    readonly block: string;
+    /** The name the case is registered as. */
+    readonly title: string;
+}
+/** Every case {@link runDocketStoreContract} registers, in registration order. */
+export declare const DOCKET_CONTRACT_CASES: readonly ContractCaseSummary[];
+/** Every case {@link runSessionStoreContract} registers, in registration order. */
+export declare const SESSION_CONTRACT_CASES: readonly ContractCaseSummary[];
+/**
+ * Register the Docket store contract against `factory`.
+ *
+ * The factory is called once per block with the harness's clock, and may be async —
+ * a store backed by a database is built from a connection the caller opened. Pass
+ * `dispose` to release it when the block ends.
+ */
+export declare function runDocketStoreContract(factory: DocketStoreFactory, options: StoreContractOptions<DocketStore, DocketContractSection>): void;
+/**
+ * Register the rehydration contract (DK-5) against `factory`.
+ *
+ * The factory returns one object that is both the Docket and the rehydration
+ * surface over it, because the cases file the rows they then rehydrate. A pair of
+ * separate reference objects is joined by {@link withSessionStore}.
+ */
+export declare function runSessionStoreContract(factory: SessionStoreFactory, options: StoreContractOptions<SessionStoreUnderTest, SessionContractSection>): void;
+export {};
+//# sourceMappingURL=testing-store.d.ts.map

package/dist/testing-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing-store.d.ts","sourceRoot":"","sources":["../src/testing-store.ts"],"names":[],"mappings":"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"}