object-shape-tester
Version:
Test object properties and value types.
76 lines (75 loc) • 2.73 kB
TypeScript
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(myShape, {a: 'hi'}); // `true`
* isValidShape(myShape, {a: 3}); // `false`
* isValidShape(myShape, {a: 'hi', b: 'bye'}, {allowExtraKeys: true}); // `true`
* ```
*
* @returns `true` or `false`
*/
export declare function isValidShape<Shape, IsReadonly extends boolean>(subject: unknown, shapeDefinition: ShapeDefinition<Shape, IsReadonly>, options?: PartialWithUndefined<CheckShapeValidityOptions>): subject is ShapeDefinition<Shape, IsReadonly>['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(myShape, {a: 'hi'}); // succeeds
* assertValidShape(myShape, {a: 'hi', b: 'bye'}, {allowExtraKeys: true}); // succeeds
* assertValidShape(myShape, {a: 3}); // fails
* ```
*
* @throws {@link ShapeMismatchError} If there is a mismatch
*/
export declare function assertValidShape<Shape, IsReadonly extends boolean>(subject: unknown, shapeDefinition: ShapeDefinition<Shape, IsReadonly>, options?: PartialWithUndefined<CheckShapeValidityOptions>, failureMessage?: string): asserts subject is ShapeDefinition<Shape, IsReadonly>['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, 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;