@autometa/assertions 1.0.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) undefined Ben Aherne
+
+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

@@ -0,0 +1,19 @@
+# @autometa/assertions
+
+Autometa's assertion toolkit built around the `ensure(value)` entry point. The package provides a fluent matcher chain with TypeScript-aware narrowing so you can write expressive assertions across runners without depending on Jest/Vitest globals.
+
+```ts
+import { ensure } from "@autometa/assertions";
+
+const result: string | undefined = fetchName();
+
+const narrowed = ensure(result, { label: "result" })
+	.toBeDefined()
+	.toBeInstanceOf(String)
+	.value;
+
+ensure({ count: 1, name: "Foo" }).toBeObjectContaining({ name: "Foo" });
+ensure([1, 2, 3]).toBeArrayContaining([2]);
+ensure(new Set([1, 2, 3])).toBeIterableContaining([3]);
+ensure("text").toHaveLength(4);
+```

package/dist/__tests__/ensure.test-d.d.ts

@@ -0,0 +1,67 @@
+import type { EnsureChain, EnsureNegatedChain } from "../ensure";
+type Assert<T extends true> = T;
+type BaseValue = EnsureChain<string>["value"];
+type NegatedBaseValue = EnsureNegatedChain<boolean>["value"];
+export type _baseValue = Assert<[BaseValue] extends [string] ? true : false>;
+export type _negatedBaseValue = Assert<[NegatedBaseValue] extends [boolean] ? true : false>;
+type DefinedChain = ReturnType<EnsureChain<string | undefined>["toBeDefined"]>;
+type DefinedValue = DefinedChain["value"];
+export type _definedNarrows = Assert<[DefinedValue] extends [string] ? true : false>;
+export type _definedEqualsString = Assert<[string] extends [DefinedValue] ? true : false>;
+type NegatedDefinedChain = ReturnType<EnsureNegatedChain<string | undefined>["toBeDefined"]>;
+type NegatedDefinedValue = NegatedDefinedChain["value"];
+export type _negatedDefinedRetains = Assert<[
+    NegatedDefinedValue
+] extends [string | undefined] ? true : false>;
+export type _negatedDefinedAllowsUndefined = Assert<[
+    string | undefined
+] extends [NegatedDefinedValue] ? true : false>;
+type InstanceNarrows = EnsureChain<Error | TypeError> extends {
+    toBeInstanceOf(ctor: typeof TypeError): {
+        value: TypeError;
+    };
+} ? true : false;
+export type _instanceNarrows = Assert<InstanceNarrows>;
+type NegatedInstanceRetains = EnsureNegatedChain<Error | TypeError> extends {
+    toBeInstanceOf(ctor: typeof TypeError): {
+        value: Error | TypeError;
+    };
+} ? true : false;
+export type _negatedInstanceRetains = Assert<NegatedInstanceRetains>;
+type ArrayContainingNarrows = EnsureChain<readonly number[] | Set<number>> extends {
+    toBeArrayContaining(expected: readonly number[]): {
+        value: readonly number[];
+    };
+} ? true : false;
+export type _arrayContainingNarrows = Assert<ArrayContainingNarrows>;
+type NegatedArrayContainingRetains = EnsureNegatedChain<readonly number[] | Set<number>> extends {
+    toBeArrayContaining(expected: readonly number[]): {
+        value: readonly number[] | Set<number>;
+    };
+} ? true : false;
+export type _negatedArrayContainingRetains = Assert<NegatedArrayContainingRetains>;
+type IterableContainingNarrows = EnsureChain<Iterable<number> | number> extends {
+    toBeIterableContaining(expected: readonly unknown[]): {
+        value: Iterable<number>;
+    };
+} ? true : false;
+export type _iterableContainingNarrows = Assert<IterableContainingNarrows>;
+type NegatedIterableContainingRetains = EnsureNegatedChain<Iterable<number> | number> extends {
+    toBeIterableContaining(expected: readonly unknown[]): {
+        value: Iterable<number> | number;
+    };
+} ? true : false;
+export type _negatedIterableContainingRetains = Assert<NegatedIterableContainingRetains>;
+type LengthNarrows = EnsureChain<string | number> extends {
+    toHaveLength(expected: number): {
+        value: string;
+    };
+} ? true : false;
+export type _lengthNarrows = Assert<LengthNarrows>;
+type NegatedLengthRetains = EnsureNegatedChain<string | number> extends {
+    toHaveLength(expected: number): {
+        value: string | number;
+    };
+} ? true : false;
+export type _negatedLengthRetains = Assert<NegatedLengthRetains>;
+export {};

package/dist/__tests__/helpers/matcher-context.d.ts

@@ -0,0 +1,18 @@
+import type { FailureDetails, MatcherContext } from "../../core/context";
+export declare class TestMatcherError extends Error {
+    readonly matcher: string;
+    readonly details: FailureDetails;
+    constructor(matcher: string, details: FailureDetails);
+}
+export interface TestMatcherContext<T> extends MatcherContext<T> {
+    readonly failCalls: readonly TestMatcherCall[];
+}
+export interface TestMatcherCall {
+    readonly matcher: string;
+    readonly details: FailureDetails;
+}
+export interface CreateMatcherContextOptions {
+    readonly negated?: boolean;
+    readonly label?: string;
+}
+export declare function createMatcherContext<T>(value: T, options?: CreateMatcherContextOptions): TestMatcherContext<T>;

package/dist/assertion-error.d.ts

@@ -0,0 +1,13 @@
+export interface EnsureErrorDetails {
+    readonly matcher: string;
+    readonly message: string;
+    readonly actual?: unknown;
+    readonly expected?: unknown;
+    readonly receivedLabel?: string;
+}
+export declare class EnsureError extends Error {
+    readonly matcher: string;
+    readonly actual?: unknown;
+    readonly expected?: unknown;
+    constructor(details: EnsureErrorDetails);
+}

package/dist/core/constants.d.ts

@@ -0,0 +1,4 @@
+import { type Tester } from "@jest/expect-utils";
+export declare const MATCHER_CALL = "ensure(received)";
+export declare const EQUALITY_TESTERS: Tester[];
+export declare const SUBSET_TESTERS: Tester[];

package/dist/core/context.d.ts

@@ -0,0 +1,14 @@
+export interface FailureDetails {
+    readonly message: string;
+    readonly actual?: unknown;
+    readonly expected?: unknown;
+}
+export interface MatcherState<T> {
+    readonly value: T;
+    readonly label?: string;
+    readonly negated: boolean;
+}
+export interface MatcherContext<T> extends MatcherState<T> {
+    fail(matcher: string, details: FailureDetails): never;
+}
+export declare function shouldFail(pass: boolean, negated: boolean): boolean;

package/dist/core/messages.d.ts

@@ -0,0 +1,10 @@
+export interface FailureMessageOptions {
+    readonly expected?: unknown;
+    readonly actual?: unknown;
+    readonly diff?: string | undefined;
+    readonly extra?: readonly (string | undefined)[];
+    readonly actualLabel?: string;
+}
+export declare function buildFailureMessage(matcher: string, baseMessage: string, options?: FailureMessageOptions): string;
+export declare function formatDiff(expected: unknown, actual: unknown): string | undefined;
+export declare function formatMissingList(title: string, values: readonly unknown[]): string;

package/dist/core/predicates.d.ts

@@ -0,0 +1,5 @@
+export declare function isRecord(candidate: unknown): candidate is Record<PropertyKey, unknown>;
+export declare function isIterable(candidate: unknown): candidate is Iterable<unknown>;
+export declare function hasLengthProperty(candidate: unknown): candidate is {
+    length: number;
+};

package/dist/ensure.d.ts

@@ -0,0 +1,33 @@
+export interface EnsureOptions {
+    readonly label?: string;
+}
+type Toggle<Negated extends boolean> = Negated extends true ? false : true;
+interface EnsureChainInternal<T, Negated extends boolean> {
+    readonly value: T;
+    readonly not: EnsureChainInternal<T, Toggle<Negated>>;
+    toBe(expected: T): EnsureChainInternal<T, Negated>;
+    toEqual(expected: unknown): EnsureChainInternal<T, Negated>;
+    toStrictEqual(expected: unknown): EnsureChainInternal<T, Negated>;
+    toBeDefined(): EnsureChainInternal<Negated extends true ? T : NonNullable<T>, Negated>;
+    toBeUndefined(): EnsureChainInternal<Negated extends true ? T : undefined, Negated>;
+    toBeNull(): EnsureChainInternal<Negated extends true ? T : null, Negated>;
+    toBeTruthy(): EnsureChainInternal<T, Negated>;
+    toBeFalsy(): EnsureChainInternal<T, Negated>;
+    toBeGreaterThan(expected: number): EnsureChainInternal<Negated extends true ? T : Extract<T, number>, Negated>;
+    toBeGreaterThanOrEqual(expected: number): EnsureChainInternal<Negated extends true ? T : Extract<T, number>, Negated>;
+    toBeLessThan(expected: number): EnsureChainInternal<Negated extends true ? T : Extract<T, number>, Negated>;
+    toBeLessThanOrEqual(expected: number): EnsureChainInternal<Negated extends true ? T : Extract<T, number>, Negated>;
+    toBeCloseTo(expected: number, precision?: number): EnsureChainInternal<Negated extends true ? T : Extract<T, number>, Negated>;
+    toBeInstanceOf<Ctor extends abstract new (...args: never[]) => unknown>(ctor: Ctor): EnsureChainInternal<Negated extends true ? T : InstanceType<Ctor>, Negated>;
+    toBeObjectContaining<Shape extends Record<PropertyKey, unknown>>(shape: Shape): EnsureChainInternal<T, Negated>;
+    toBeArrayContaining(expected: readonly unknown[]): EnsureChainInternal<Negated extends true ? T : Extract<T, readonly unknown[]>, Negated>;
+    toContainEqual(expected: unknown): EnsureChainInternal<Negated extends true ? T : Extract<T, readonly unknown[]>, Negated>;
+    toBeIterableContaining(expected: readonly unknown[]): EnsureChainInternal<Negated extends true ? T : Extract<T, Iterable<unknown>>, Negated>;
+    toHaveLength(expected: number): EnsureChainInternal<Negated extends true ? T : Extract<T, {
+        length: number;
+    }>, Negated>;
+}
+export type EnsureChain<T> = EnsureChainInternal<T, false>;
+export type EnsureNegatedChain<T> = EnsureChainInternal<T, true>;
+export declare function ensure<T>(value: T, options?: EnsureOptions): EnsureChain<T>;
+export {};