import { MaybeFn, Maybe, AnyObject } from 'yummies/types';

/**
 * ---header-docs-section---
 * # yummies/assert
 *
 * ## Description
 *
 * Runtime **assertions** for invariants, narrowing, and exhaustiveness. Helpers throw
 * {@link AssertionError} with an optional message (`string` or {@link MaybeFn}) so failing fast stays
 * explicit without a heavy assertion library. Use `assert.ok`, `assert.string`, `assert.defined`,
 * `assert.fail`, and the rest on the namespace export from the package entry.
 *
 * ## Usage
 *
 * ```ts
 * import { assert } from "yummies/assert";
 *
 * assert.ok(user.id, "user id is required");
 * assert.defined(maybeName);
 * assert.string(raw);
 * ```
 */

/**
 * Error thrown by assertion helpers in this module.
 */
declare class AssertionError extends Error {
    name: string;
}
/**
 * Throws when `condition` is falsy; narrows the type when it is truthy.
 *
 * @param condition Value treated as a boolean guard.
 * @param message Optional message or lazy message factory.
 *
 * @example
 * ```ts
 * assert.ok(user.id, "user id is required");
 * ```
 */
declare function ok(condition: unknown, message?: MaybeFn<string>): asserts condition;
/**
 * Same as {@link ok}; common alias for internal invariants (e.g. after optional checks).
 */
declare const invariant: typeof ok;
/**
 * Throws when the value is `null` or `undefined`; otherwise narrows away nullish.
 *
 * @param value Possibly nullish value.
 * @param message Optional message or lazy message factory.
 *
 * @example
 * ```ts
 * assert.defined(maybeName, "name must be present");
 * ```
 */
declare function defined<T>(value: Maybe<T>, message?: MaybeFn<string>): asserts value is NonNullable<T>;
/**
 * Throws when the value is `null`; allows `undefined` unless combined with other checks.
 *
 * @param value Value that may be `null`.
 * @param message Optional message or lazy message factory.
 */
declare function notNull<T>(value: T | null, message?: MaybeFn<string>): asserts value is T;
/**
 * Throws when the value is `undefined`.
 *
 * @param value Value that may be `undefined`.
 * @param message Optional message or lazy message factory.
 */
declare function notUndefined<T>(value: T | undefined, message?: MaybeFn<string>): asserts value is T;
/**
 * Throws when `value` is not a string (primitive or `String` object); uses `typeGuard.isString`.
 *
 * @param value Value to narrow.
 * @param message Optional message or lazy message factory.
 */
declare function string(value: unknown, message?: MaybeFn<string>): asserts value is string;
/**
 * Throws when `value` is not a object (primitive or `AnyObject` object); uses `typeGuard.isObject`.
 *
 * @param value Value to narrow.
 * @param message Optional message or lazy message factory.
 */
declare function object<T extends AnyObject = AnyObject>(value: unknown, message?: MaybeFn<string>): asserts value is T;
/**
 * Throws when `value` is not a object (primitive or `AnyObject` object); uses `typeGuard.isArray`.
 *
 * @param value Value to narrow.
 * @param message Optional message or lazy message factory.
 */
declare function array<T extends any[] = any[]>(value: unknown, message?: MaybeFn<string>): asserts value is T;
/**
 * Throws when `value` is not a finite non-NaN number; uses `typeGuard.isNumber`.
 *
 * @param value Value to narrow.
 * @param message Optional message or lazy message factory.
 */
declare function number(value: unknown, message?: MaybeFn<string>): asserts value is number;
/**
 * Throws when `value` is not a boolean; uses `typeGuard.isBoolean`.
 *
 * @param value Value to narrow.
 * @param message Optional message or lazy message factory.
 */
declare function boolean(value: unknown, message?: MaybeFn<string>): asserts value is boolean;
/**
 * Throws when `value` is not a symbol; uses `typeGuard.isSymbol`.
 *
 * @param value Value to narrow.
 * @param message Optional message or lazy message factory.
 */
declare function symbol(value: unknown, message?: MaybeFn<string>): asserts value is symbol;
/**
 * Always throws; use for branches that must be impossible or as a typed “abort”.
 *
 * @param message Optional message or lazy message factory.
 *
 * @example
 * ```ts
 * function parse(kind: "a" | "b") {
 *   if (kind === "a") return 1;
 *   if (kind === "b") return 2;
 *   assert.fail("unreachable");
 * }
 * ```
 */
declare function fail(message?: MaybeFn<string>): never;
/**
 * Exhaustiveness helper: call with a `never` value when all union cases are handled.
 *
 * @param value Should be `never` when the type checker is satisfied.
 * @param message Optional message (this path always throws, so a lazy factory is unnecessary).
 */
declare function unreachable(value: never, message?: string): never;

/**
 * Throws when `value` is not an instance of `ctor`.
 *
 * @param value Value to check.
 * @param ctor Constructor used with `instanceof`.
 * @param message Optional message or lazy message factory.
 *
 * @example
 * ```ts
 * assert.instanceOf(el, HTMLElement, "expected a DOM element");
 * ```
 */
declare function instanceOf<T>(value: unknown, ctor: abstract new (...args: never[]) => T, message?: MaybeFn<string>): asserts value is T;

type _exports_AssertionError = AssertionError;
declare const _exports_AssertionError: typeof AssertionError;
declare const _exports_array: typeof array;
declare const _exports_boolean: typeof boolean;
declare const _exports_defined: typeof defined;
declare const _exports_fail: typeof fail;
declare const _exports_instanceOf: typeof instanceOf;
declare const _exports_invariant: typeof invariant;
declare const _exports_notNull: typeof notNull;
declare const _exports_notUndefined: typeof notUndefined;
declare const _exports_number: typeof number;
declare const _exports_object: typeof object;
declare const _exports_ok: typeof ok;
declare const _exports_string: typeof string;
declare const _exports_symbol: typeof symbol;
declare const _exports_unreachable: typeof unreachable;
declare namespace _exports {
  export {
    _exports_AssertionError as AssertionError,
    _exports_array as array,
    _exports_boolean as boolean,
    _exports_defined as defined,
    _exports_fail as fail,
    _exports_instanceOf as instanceOf,
    _exports_invariant as invariant,
    unreachable as never,
    _exports_notNull as notNull,
    _exports_notUndefined as notUndefined,
    _exports_number as number,
    _exports_object as object,
    _exports_ok as ok,
    _exports_string as string,
    _exports_symbol as symbol,
    _exports_unreachable as unreachable,
  };
}

export { _exports as assert };