object-shape-tester
Version:
Test object properties and value types.
63 lines (62 loc) • 2.82 kB
TypeScript
import { type PartialWithUndefined } from '@augment-vir/common';
import { type TSchema } from '@sinclair/typebox';
import { type Shape } from '../shape/shape.js';
/**
* Options for checking and asserting shapes.
*
* @category Internal
*/
export type CheckShapeOptions = PartialWithUndefined<{
/**
* Determines if extra keys are allowed, blocked, or not forced:
*
* - `true`: extra keys are forcibly allowed in all objects (`additionalProperties` is forced to
* `true` for all nested schemas).
* - `false`: extra keys are forcibly blocked in all objects (`additionalProperties` is forced to
* `false` for all nested schemas).
*
* @default false
*/
allowExtraKeys: boolean;
}>;
/**
* Checks if the given value matches the given shape and returns `true` or `false` as a type guard.
*
* @category Check
* @returns `true` or `false`
*/
export declare function checkValidShape<SpecificShape extends Shape | TSchema>(this: void, value: unknown, shape: SpecificShape, options?: CheckShapeOptions): value is RuntimeTypeOf<SpecificShape>;
/**
* Checks if the given value matches the given shape. If it does, returns the value. If not, returns
* `undefined`.
*
* @category Check
* @returns The original `value` or `undefined.
*/
export declare function checkWrapValidShape<SpecificShape extends Shape | TSchema>(this: void, value: unknown, shape: SpecificShape, options?: CheckShapeOptions): RuntimeTypeOf<SpecificShape> | undefined;
/**
* Asserts that the given value matches the given shape.
*
* @category Check
* @throws `ShapeMismatchError` if `value` does not match the shape.
*/
export declare function assertValidShape<SpecificShape extends Shape | TSchema>(this: void, value: unknown, shape: SpecificShape, options?: CheckShapeOptions, failureMessage?: string | undefined): asserts value is RuntimeTypeOf<SpecificShape>;
/**
* Asserts that the given value matches the given shape and returns the original `value` if so.
*
* @category Check
* @throws `ShapeMismatchError` if `value` does not match the shape.
*/
export declare function assertWrapValidShape<SpecificShape extends Shape | TSchema>(this: void, value: unknown, shape: SpecificShape, options?: CheckShapeOptions, failureMessage?: string | undefined): RuntimeTypeOf<SpecificShape>;
/**
* Extracts the runtime type of the given Shape or Schema.
*
* @category Internal
*/
export type RuntimeTypeOf<SpecificShape extends Shape | TSchema> = (SpecificShape extends Shape ? SpecificShape : Shape<SpecificShape>)['runtimeType'];
/**
* Ensures that the given shape or schema is a shape.
*
* @category Internal
*/
export declare function ensureShape<SpecificShape extends Shape | TSchema>(shape: SpecificShape): SpecificShape extends Shape ? SpecificShape : Shape<SpecificShape>;