object-shape-tester/dist/verify-shape/verify-shape.d.ts

Test object properties and value types.

import { type PartialWithUndefined } from '@augment-vir/common';
import { type BaseIndexedKeys, type ShapeDefinition, type ShapeIndexedKeys } from '../define-shape/shape-specifiers.js';
/**
 * Extra options for {@link isValidShape} and {@link assertValidShape}.
 *
 * @category Util
 */
export type CheckShapeValidityOptions = {
    allowExtraKeys: boolean;
};
/**
 * Check if a variable matches the given shape.
 *
 * @category Main
 * @example
 *
 * ```ts
 * import {defineShape, isValidShape} from 'object-shape-tester';
 *
 * const myShape = defineShape({
 *     a: '',
 * });
 *
 * isValidShape({a: 'hi'}, myShape); // `true`
 * isValidShape({a: 3}, myShape); // `false`
 * isValidShape({a: 'hi', b: 'bye'}, {allowExtraKeys: true}, myShape); // `true`
 * ```
 *
 * @returns `true` or `false`
 */
export declare function isValidShape<Shape extends ShapeDefinition<any, IsReadonly>, IsReadonly extends boolean>(subject: unknown, shapeDefinition: Shape, options?: PartialWithUndefined<CheckShapeValidityOptions>): subject is Shape['runtimeType'];
/**
 * Check if a variable matches the given shape. Returns the variable if it matches, otherwise
 * returns `undefined`
 *
 * @category Main
 * @example
 *
 * ```ts
 * import {defineShape, checkWrapValidShape} from 'object-shape-tester';
 *
 * const myShape = defineShape({
 *     a: '',
 * });
 *
 * checkWrapValidShape({a: 'hi'}, myShape); // returns `{a: 'hi'}`
 * checkWrapValidShape({a: 3}, myShape); // returns `undefined`
 * checkWrapValidShape({a: 'hi', b: 'bye'}, {allowExtraKeys: true}, myShape); // returns `{a: 'hi', b: 'bye'}`
 * ```
 *
 * @returns `true` or `false`
 */
export declare function checkWrapValidShape<Shape extends ShapeDefinition<any, IsReadonly>, IsReadonly extends boolean>(subject: unknown, shapeDefinition: Shape, options?: PartialWithUndefined<CheckShapeValidityOptions>): Shape['runtimeType'] | undefined;
/**
 * Assets that a variable matches the given shape and then returns the variable.
 *
 * @category Main
 * @example
 *
 * ```ts
 * import {defineShape, assertWrapValidShape} from 'object-shape-tester';
 *
 * const myShape = defineShape({
 *     a: '',
 * });
 *
 * assertValidShape({a: 'hi'}, myShape); // returns `{a: 'hi'}`
 * assertValidShape({a: 'hi', b: 'bye'}, myShape, {allowExtraKeys: true}); // returns `{a: 'hi', b: 'bye'}`
 * assertValidShape({a: 3, myShape}); // throws an error
 * ```
 *
 * @throws {@link ShapeMismatchError} If there is a mismatch
 */
export declare function assertWrapValidShape<Shape extends ShapeDefinition<any, IsReadonly>, IsReadonly extends boolean>(subject: unknown, shapeDefinition: Shape, options?: PartialWithUndefined<CheckShapeValidityOptions>, failureMessage?: string): Shape['runtimeType'];
/**
 * Assets that a variable matches the given shape.
 *
 * @category Main
 * @example
 *
 * ```ts
 * import {defineShape, assertValidShape} from 'object-shape-tester';
 *
 * const myShape = defineShape({
 *     a: '',
 * });
 *
 * assertValidShape({a: 'hi'}, myShape); // succeeds
 * assertValidShape({a: 'hi', b: 'bye'}, myShape, {allowExtraKeys: true}); // succeeds
 * assertValidShape({a: 3, myShape}); // fails
 * ```
 *
 * @throws {@link ShapeMismatchError} If there is a mismatch
 */
export declare function assertValidShape<Shape extends ShapeDefinition<any, IsReadonly>, IsReadonly extends boolean>(subject: unknown, shapeDefinition: Shape, options?: PartialWithUndefined<CheckShapeValidityOptions>, failureMessage?: string): asserts subject is Shape['runtimeType'];
/**
 * Options for shape validation.
 *
 * @category Internal
 */
export type InternalIsValidShapeOptions = {
    ignoreExtraKeys: boolean;
    exactValues: boolean;
};
/**
 * Checks if the given `subject` matches the given `shape`.
 *
 * @category Internal
 */
export declare function matchesShape(subject: unknown, shape: unknown, keys: ReadonlyArray<PropertyKey>, options: InternalIsValidShapeOptions & {
    throw?: boolean | undefined;
}, checkValues?: boolean | undefined): boolean;
/**
 * Expands an {@link indexedKeys} shape part into an array of its valid keys.
 *
 * @category Internal
 * @returns `true` if any keys are allowed. `false` if a bounded set of keys cannot be determined.
 *   `PropertyKey[]` if there's a specific set of keys that can be extracted.
 */
export declare function expandIndexedKeysKeys(specifier: ShapeIndexedKeys<Readonly<[BaseIndexedKeys]>>): PropertyKey[] | boolean;