Class FunctionShape<ArgsShape, ReturnShape, ThisShape>

The shape of a function.

Type Parameters

ArgsShape extends Shape<readonly any[], readonly any[]>
The shape of the array of arguments.
ReturnShape extends AnyShape | null
The return value shape, or null if unconstrained.
ThisShape extends AnyShape | null
The shape of this argument, or null if unconstrained.

Hierarchy (view full)

Shape<((this: InferOrDefault<ThisShape, OUTPUT>, ...args: Output<ArgsShape>) => InferOrDefault<ReturnShape, INPUT>), ((this: InferOrDefault<ThisShape, INPUT>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, OUTPUT>)>
- FunctionShape

Constructors

constructor

new FunctionShape<ArgsShape, ReturnShape, ThisShape>(argsShape, returnShape, thisShape, options?): FunctionShape<ArgsShape, ReturnShape, ThisShape>
Creates a new FunctionShape instance.
Type Parameters
- ArgsShape extends Shape<readonly any[], readonly any[]>
  The shape of the array of arguments.
- ReturnShape extends null | AnyShape
  The return value shape, or null if unconstrained.
- ThisShape extends null | AnyShape
  The shape of this argument, or null if unconstrained.
Parameters
- argsShape: ArgsShape
  The shape of the array of arguments.
- returnShape: ReturnShape
  The return value shape, or null if unconstrained.
- thisShape: ThisShape
  The shape of this argument, or null if unconstrained.
- Optionaloptions: IssueOptions | Message
  The issue options or the issue message.
Returns FunctionShape<ArgsShape, ReturnShape, ThisShape>
Overrides Shape.constructor

Properties

`Protected`_options

_options: undefined | IssueOptions | Message

The type issue options or the type issue message.

`Protected`_parseOptions

_parseOptions: undefined | ParseOptions

Parsing options that are used by a wrapper.

annotations

annotations: Dict<any> = {}

The dictionary of shape annotations.

See

Shape.annotate

`Readonly`argsShape

argsShape: ArgsShape

The shape of the array of arguments.

`Readonly`inputs

inputs: readonly unknown[]

The array of unique input types and values that are accepted by the shape.

`Readonly`isAsync

isAsync: boolean

true if the shape allows only Shape.parseAsync and throws an error if Shape.parse is called, or false if the shape can be used in both sync and async contexts.

isStrict

isStrict: boolean = false

true if input functions are wrapped during parsing to ensure runtime signature type-safety, or false otherwise.

operations

operations: readonly Operation[] = []

The array of operations that are applied to the shape output.

See

`Readonly`returnShape

returnShape: ReturnShape

The return value shape, or null if unconstrained.

`Readonly`thisShape

thisShape: ThisShape

The shape of this value, or null if unconstrained.

Methods

`Protected`_apply

_apply(input, options, _nonce): Result<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>
Synchronously parses the input.
Parameters
- input: any
  The shape input to parse.
- options: ParseOptions
  Parsing options.
- _nonce: number
  The globally unique number that identifies the parsing process.
Returns Result<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>
null if input matches the output, Ok that wraps the output, or an array of captured issues.

See
Advanced shapes

Overrides Shape._apply

`Protected`_applyAsync

_applyAsync(input, options, _nonce): Promise<Result<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>>
Asynchronously parses the input.
Parameters
- input: any
  The shape input to parse.
- options: ParseOptions
  Parsing options.
- _nonce: number
Returns Promise<Result<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>>
null if input matches the output, Ok that wraps the output, or an array of captured issues.

See
Advanced shapes

Overrides Shape._applyAsync

`Protected`_applyOperations

_applyOperations(input, output, options, issues): Result | Promise<Result>
The callback that applies Shape.operations to the shape output value.

This method returns a promise if there are async Shape.operations.

If the shape overrides only Shape._apply and doesn't override Shape._applyAsync then it's only safe to call this method as the last statement in Shape._apply. Otherwise, it may return an unexpected promise.

If the shape overrides both Shape._apply and Shape._applyAsync then this method would always synchronously return a Result inside Shape._apply.
Parameters
- input: unknown
- output: unknown
- options: ParseOptions
- issues: null | Issue[]
Returns Result | Promise<Result>
Inherited from Shape._applyOperations

`Protected`_clone

_clone(): this
Clones the shape.

Returns this
See
Advanced shapes

Inherited from Shape._clone

`Protected`_getInputs

_getInputs(): readonly unknown[]
Returns input types and literal values that this shape can accept as an input.

Returns readonly unknown[]
See
Advanced shapes

Overrides Shape._getInputs

`Protected`_isAsync

_isAsync(): boolean
Must return true if the shape must be used in async context only, otherwise the shape can be used in both sync and async contexts. Override this method to implement a custom shape.

Returns boolean
See
Advanced shapes

Inherited from Shape._isAsync

accepts

accepts(input): boolean
Returns true if the shape accepts given input type or value, or false otherwise.
Parameters
- input: unknown
  The type or value that must be checked.
Returns boolean
Inherited from Shape.accepts

addAsyncOperation

addAsyncOperation<Param>(cb, options?): this
Adds an asynchronous operation to the shape.
Type Parameters
- Param
  The param that is passed to the operation when it is applied.
Parameters
- cb: OperationCallback<PromiseLike<Result<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>>, ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>), Param>
  The callback that asynchronously applies an operation to the shape output value.
- Optionaloptions: ParameterizedOperationOptions<Param>
  The operation options.
Returns this
The clone of the shape.

See
Operations

Inherited from Shape.addAsyncOperation
addAsyncOperation(cb, options?): this
Adds an asynchronous operation to the shape.
Parameters
- cb: OperationCallback<PromiseLike<Result<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>>, ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>
  The callback that asynchronously applies an operation to the shape output value.
- Optionaloptions: OperationOptions
  The operation options.
Returns this
The clone of the shape.

See
Operations

Inherited from Shape.addAsyncOperation

addOperation

addOperation<Param>(cb, options?): this
Adds a synchronous operation to the shape.
Type Parameters
- Param
  The param that is passed to the operation when it is applied.
Parameters
- cb: OperationCallback<Result<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>, ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>), Param>
  The callback that synchronously applies an operation to the shape output value.
- Optionaloptions: ParameterizedOperationOptions<Param>
  The operation options.
Returns this
The clone of the shape.

See
Operations

Inherited from Shape.addOperation
addOperation(cb, options?): this
Adds a synchronous operation to the shape.
Parameters
- cb: OperationCallback<Result<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>, ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>
  The callback that synchronously applies an operation to the shape output value.
- Optionaloptions: OperationOptions
  The operation options.
Returns this
The clone of the shape.

See
Operations

Inherited from Shape.addOperation

allow

allow<AllowedValue>(value): AllowShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, AllowedValue>
Allows an input value, so it is passed directly to the output.
Type Parameters
- AllowedValue extends Any
  The allowed value.
Parameters
- value: AllowedValue
  The allowed value.
Returns AllowShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, AllowedValue>
Inherited from Shape.allow

alter

alter<Param>(cb, options): this
Adds a synchronous operation that alters the output value without changing its type.

If you want to change the base type, consider using Shape.convert.
Type Parameters
- Param
  The param that is passed to the operation when it is applied.
Parameters
- cb: OperationCallback<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>), ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>), Param>
  The callback that alters the shape output. Throw a ValidationError to notify that the alteration cannot be successfully completed.
- options: ParameterizedOperationOptions<Param>
  The operation options.
Returns this
The clone of the shape.
See
Inherited from Shape.alter
alter(cb, options?): this
Adds a synchronous operation that alters the output value without changing its type.

If you want to change the base type, consider using Shape.convert.
Parameters
- cb: OperationCallback<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>), ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>
  The callback that alters the shape output. Throw a ValidationError to notify that the alteration cannot be successfully completed.
- Optionaloptions: OperationOptions
  The operation options.
Returns this
The clone of the shape.
See
Inherited from Shape.alter

alterAsync

alterAsync<Param>(cb, options): this
Adds an asynchronous operation that alters the output value without changing its type.

If you want to change the base type, consider using Shape.convertAsync.
Type Parameters
- Param
  The param that is passed to the operation when it is applied.
Parameters
- cb: OperationCallback<PromiseLike<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>, ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>), Param>
  The callback that alters the shape output. Throw a ValidationError to notify that the alteration cannot be successfully completed.
- options: ParameterizedOperationOptions<Param>
  The operation options.
Returns this
The clone of the shape.
See
Inherited from Shape.alterAsync
alterAsync(cb, options?): this
Adds an asynchronous operation that alters the output value without changing its type.

If you want to change the base type, consider using Shape.convertAsync.
Parameters
- cb: OperationCallback<PromiseLike<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>, ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>
  The callback that alters the shape output. Throw a ValidationError to notify that the alteration cannot be successfully completed.
- Optionaloptions: OperationOptions
  The operation options.
Returns this
The clone of the shape.
See
Inherited from Shape.alterAsync

annotate

annotate(annotations): this
Adds annotations to the shape.
Parameters
- annotations: ReadonlyDict<any>
  Annotations to add.
Returns this
The clone of the shape with the updated annotations.

See
Shape.annotations

Inherited from Shape.annotate

at

at(_key): null | AnyShape
Returns a sub-shape that describes a value associated with the given property name, or null if there's no such sub-shape.
Parameters
- _key: unknown
  The key for which the sub-shape must be retrieved.
Returns null | AnyShape
The sub-shape or null if there's no such key in the shape.

Inherited from Shape.at

brand

brand<Brand>(): RefineShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, Branded<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>), Brand>>
Returns a shape that adds a brand to the output type.
Type Parameters
- Brand extends string | number | symbol
  The brand value.
Returns RefineShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, Branded<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>), Brand>>
A shape with the branded output type.

Inherited from Shape.brand

catch

catch(): CatchShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, undefined>
Returns undefined if parsing fails.

Returns CatchShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, undefined>
Inherited from Shape.catch
catch<FallbackValue>(fallback): CatchShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, FallbackValue>
Returns the fallback value if parsing fails.
Type Parameters
- FallbackValue extends Any
  The fallback value.
Parameters
- fallback: FallbackValue | ((input: any, issues: Issue[], options: ParseOptions) => FallbackValue)
  The value or a callback that returns a value that is returned if parsing has failed. A callback receives an input value, an array of raised issues, and parsing options.
Returns CatchShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, FallbackValue>
Inherited from Shape.catch

check

check<Param>(cb, options): this
Adds a synchronous operation that checks that the shape output satisfies a requirement.

The callback must return null or undefined if value is valid, or an issue or an array of issues if value is invalid. If a callback returns an empty array, it is considered that no issues have occurred.
Type Parameters
- Param
  The param that is passed to the operation when it is applied.
Parameters
- cb: OperationCallback<CheckResult, ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>), Param>
  The callback that checks that a value satisfies a requirement and returns issues if it doesn't.
- options: ParameterizedOperationOptions<Param>
  The operation options.
Returns this
The clone of the shape.
See
Inherited from Shape.check
check(cb, options?): this
Adds a synchronous operation that checks that the shape output satisfies a requirement.

The callback must return null or undefined if value is valid, or an issue or an array of issues if value is invalid. If a callback returns an empty array, it is considered that no issues have occurred.
Parameters
- cb: OperationCallback<CheckResult, ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>
  The callback that checks that a value satisfies a requirement and returns issues if it doesn't.
- Optionaloptions: OperationOptions
  The operation options.
Returns this
The clone of the shape.
See
Inherited from Shape.check

checkAsync

checkAsync<Param>(cb, options): this
Adds an asynchronous operation that checks that the shape output satisfies a requirement.

The callback must return a promise that is resolved with null or undefined if value is valid, or an issue or an array of issues if value is invalid. If promise resolves with an empty array, it is considered that no issues have occurred.
Type Parameters
- Param
  The param that is passed to the operation when it is applied.
Parameters
- cb: OperationCallback<PromiseLike<CheckResult>, ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>), Param>
  The callback that checks that a value satisfies a requirement and returns issues if it doesn't.
- options: ParameterizedOperationOptions<Param>
  The operation options.
Returns this
The clone of the shape.
See
Inherited from Shape.checkAsync
checkAsync(cb, options?): this
Adds an asynchronous operation that checks that the shape output satisfies a requirement.

The callback must return a promise that is resolved with null or undefined if value is valid, or an issue or an array of issues if value is invalid. If promise resolves with an empty array, it is considered that no issues have occurred.
Parameters
- cb: OperationCallback<PromiseLike<CheckResult>, ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>
  The callback that checks that a value satisfies a requirement and returns issues if it doesn't.
- Optionaloptions: OperationOptions
  The operation options.
Returns this
The clone of the shape.
See
Inherited from Shape.checkAsync

convert

convert<ConvertedValue>(cb): Shape<((this: InferOrDefault<ThisShape, typeof OUTPUT, any>, ...args: Output<ArgsShape>) => InferOrDefault<ReturnShape, typeof INPUT, any>), ConvertedValue>
Synchronously converts the output value of the shape.

If you want to don't want to change the base type, consider using Shape.alter.
Type Parameters
- ConvertedValue
  The value returned from the callback that converts the output value of this shape.
Parameters
- cb: ((value: ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>), options: ParseOptions) => ConvertedValue)
  The callback that converts the input value. Throw a ValidationError to notify that the conversion cannot be successfully completed.
  - - (value, options): ConvertedValue
    - Parameters
      value: ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)
      (this, ...args): InferOrDefault<ReturnShape, typeof OUTPUT, any>
      Parameters
      this: InferOrDefault<ThisShape, typeof INPUT, any>
      Rest...args: Input<ArgsShape>
      Returns InferOrDefault<ReturnShape, typeof OUTPUT, any>
      options: ParseOptions
      Returns ConvertedValue
Returns Shape<((this: InferOrDefault<ThisShape, typeof OUTPUT, any>, ...args: Output<ArgsShape>) => InferOrDefault<ReturnShape, typeof INPUT, any>), ConvertedValue>
The ConvertShape instance.
See
- Shape.convertAsync
- Shape.alter
Inherited from Shape.convert

convertAsync

convertAsync<ConvertedValue>(cb): Shape<((this: InferOrDefault<ThisShape, typeof OUTPUT, any>, ...args: Output<ArgsShape>) => InferOrDefault<ReturnShape, typeof INPUT, any>), ConvertedValue>
Asynchronously converts the output value of the shape.

If you want to don't want to change the base type, consider using Shape.alterAsync.
Type Parameters
- ConvertedValue
  The value returned from the callback that converts the output value of this shape.
Parameters
- cb: ((value: ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>), options: ParseOptions) => PromiseLike<ConvertedValue>)
  The callback that converts the input value asynchronously. The returned promise can be rejected with a ValidationError to notify that the conversion cannot be successfully completed.
  - - (value, options): PromiseLike<ConvertedValue>
    - Parameters
      value: ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)
      (this, ...args): InferOrDefault<ReturnShape, typeof OUTPUT, any>
      Parameters
      this: InferOrDefault<ThisShape, typeof INPUT, any>
      Rest...args: Input<ArgsShape>
      Returns InferOrDefault<ReturnShape, typeof OUTPUT, any>
      options: ParseOptions
      Returns PromiseLike<ConvertedValue>
Returns Shape<((this: InferOrDefault<ThisShape, typeof OUTPUT, any>, ...args: Output<ArgsShape>) => InferOrDefault<ReturnShape, typeof INPUT, any>), ConvertedValue>
The ConvertShape instance.
See
- Shape.convert
- Shape.alterAsync
Inherited from Shape.convertAsync

deny

deny<DeniedValue>(value, options?): DenyShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, DeniedValue>
Excludes value from both input and output.
Type Parameters
- DeniedValue extends ((this: InferOrDefault<ThisShape, typeof OUTPUT, any>, ...args: Output<ArgsShape>) => InferOrDefault<ReturnShape, typeof INPUT, any>) | ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)
  The denied value.
Parameters
- value: DeniedValue
  The excluded value.
- Optionaloptions: IssueOptions | Message
  The issue options or the issue message.
Returns DenyShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, DeniedValue>
Inherited from Shape.deny

ensure

ensure<F>(fn, options?): ((this: InferOrDefault<ThisShape, typeof INPUT, ThisType<F>>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, ReturnType<F>>)
Creates a function that ensures that fn receives arguments and this value that conform the argsShape and the thisShape respectively, and synchronously returns the value that conforms the returnShape.
Type Parameters
- F extends ((this: InferOrDefault<ThisShape, typeof OUTPUT, any>, ...args: Output<ArgsShape>) => InferOrDefault<ReturnShape, typeof INPUT, any>)
  The function to which signature must be ensured.
Parameters
- fn: F
  The underlying function.
- Optionaloptions: ParseOptions
  Parsing options. By default, options provided to the strict method are used.
Returns ((this: InferOrDefault<ThisShape, typeof INPUT, ThisType<F>>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, ReturnType<F>>)
The wrapper function.
- - (this, ...args): InferOrDefault<ReturnShape, typeof OUTPUT, ReturnType<F>>
  - Parameters
    - this: InferOrDefault<ThisShape, typeof INPUT, ThisType<F>>
    - Rest...args: Input<ArgsShape>
    Returns InferOrDefault<ReturnShape, typeof OUTPUT, ReturnType<F>>

ensureAsync

ensureAsync<F>(fn, options?): ((this: InferOrDefault<ThisShape, typeof INPUT, ThisType<F>>, ...args: Input<ArgsShape>) => Promisify<InferOrDefault<ReturnShape, typeof OUTPUT, ReturnType<F>>>)
Creates a function that ensures that fn receives arguments and this value that conform the argsShape and the thisShape respectively, and asynchronously returns the value that conforms the returnShape.

Use this method if some shapes that describe the function signature are async.
Type Parameters
- F extends ((this: InferOrDefault<ThisShape, typeof OUTPUT, any>, ...args: Output<ArgsShape>) => Awaitable<InferOrDefault<ReturnShape, typeof INPUT, any>>)
  The function to which signature must be ensured.
Parameters
- fn: F
  The underlying function.
- Optionaloptions: ParseOptions
  Parsing options. By default, options provided to the strict method are used.
Returns ((this: InferOrDefault<ThisShape, typeof INPUT, ThisType<F>>, ...args: Input<ArgsShape>) => Promisify<InferOrDefault<ReturnShape, typeof OUTPUT, ReturnType<F>>>)
The wrapper function.
- - (this, ...args): Promisify<InferOrDefault<ReturnShape, typeof OUTPUT, ReturnType<F>>>
  - Parameters
    - this: InferOrDefault<ThisShape, typeof INPUT, ThisType<F>>
    - Rest...args: Input<ArgsShape>
    Returns Promisify<InferOrDefault<ReturnShape, typeof OUTPUT, ReturnType<F>>>

exclude

exclude<ExcludedShape>(shape, options?): ExcludeShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, ExcludedShape>
Checks that the input doesn't match the shape.
Type Parameters
- ExcludedShape extends AnyShape
  The shape to which the output must not conform.
Parameters
- shape: ExcludedShape
  The shape to which the output must not conform.
- Optionaloptions: IssueOptions | Message
  The issue options or the issue message.
Returns ExcludeShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, ExcludedShape>
Inherited from Shape.exclude

nonOptional

nonOptional(options?): DenyShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, undefined>
Prevents an input and output from being undefined.
Parameters
- Optionaloptions: IssueOptions | Message
  The issue options or the issue message.
Returns DenyShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, undefined>
Inherited from Shape.nonOptional

not

not<ExcludedShape>(shape, options?): NotShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, ExcludedShape>
Checks that the input doesn't match the shape.

This method works exactly as Shape.exclude at runtime, but it doesn't perform the exclusion on the type level.
Type Parameters
- ExcludedShape extends AnyShape
  The shape to which the output must not conform.
Parameters
- shape: ExcludedShape
  The shape to which the output must not conform.
- Optionaloptions: IssueOptions | Message
  The issue options or the issue message.
Returns NotShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, ExcludedShape>
Inherited from Shape.not

nullable

nullable(): AllowShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, null>
Replaces null input value with an null output value.

Returns AllowShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, null>
Inherited from Shape.nullable
nullable<DefaultValue>(defaultValue): ReplaceShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, null, DefaultValue>
Replaces null input value with a default output value.
Type Parameters
- DefaultValue extends Any
  The value that is used as the replacement for null.
Parameters
- defaultValue: DefaultValue
  The value that should be used if an input value is null.
Returns ReplaceShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, null, DefaultValue>
Inherited from Shape.nullable

nullish

nullish(): AllowShape<AllowShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, null>, undefined>
Passes null and undefined input values directly to the output without parsing.

Returns AllowShape<AllowShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, null>, undefined>
Inherited from Shape.nullish
nullish<DefaultValue>(defaultValue?): ReplaceShape<ReplaceShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, null, DefaultValue>, undefined, DefaultValue>
Replaces null and undefined input value with a default output value.
Type Parameters
- DefaultValue extends Any
  The value that is used as the replacement for undefined and null.
Parameters
- OptionaldefaultValue: DefaultValue
  The value that should be used if an input value is undefined or null.
Returns ReplaceShape<ReplaceShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, null, DefaultValue>, undefined, DefaultValue>
Inherited from Shape.nullish

optional

optional(): AllowShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, undefined>
Replaces undefined input value with an undefined output value.

Returns AllowShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, undefined>
Inherited from Shape.optional
optional<DefaultValue>(defaultValue): ReplaceShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, undefined, DefaultValue>
Replaces undefined input value with a default output value.
Type Parameters
- DefaultValue extends Any
  The value that is used as the replacement for undefined.
Parameters
- defaultValue: DefaultValue
  The value that should be used if an input value is undefined.
Returns ReplaceShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, undefined, DefaultValue>
Inherited from Shape.optional

parse

parse(input, options?): ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)
Synchronously parses the value.
Parameters
- input: unknown
  The value to parse.
- Optionaloptions: ParseOptions
  Parsing options.
Returns ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)
The value that conforms the output type of the shape.
- - (this, ...args): InferOrDefault<ReturnShape, typeof OUTPUT, any>
  - Parameters
    - this: InferOrDefault<ThisShape, typeof INPUT, any>
    - Rest...args: Input<ArgsShape>
    Returns InferOrDefault<ReturnShape, typeof OUTPUT, any>
Throws
Error if the shape doesn't support the sync parsing, see Shape.isAsync.

Throws
ValidationError if any issues occur during parsing.

Inherited from Shape.parse

parseAsync

parseAsync(input, options?): Promisify<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>
Asynchronously parses the value.
Parameters
- input: unknown
  The value to parse.
- Optionaloptions: ParseOptions
  Parsing options.
Returns Promisify<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>
The promise that resolves with the value that conforms the output type of the shape, or rejects with a ValidationError if any issues occur during parsing.

Inherited from Shape.parseAsync

parseOrDefault

parseOrDefault(input): undefined | ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)
Synchronously parses the value and returns undefined if parsing fails.
Parameters
- input: unknown
  The value to parse.
Returns undefined | ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)
The value that conforms the output type of the shape.

Throws
Error if the shape doesn't support the sync parsing, see Shape.isAsync.

Inherited from Shape.parseOrDefault
parseOrDefault<DefaultValue>(input, defaultValue, options?): ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>) | DefaultValue
Synchronously parses the value and returns the default value if parsing fails.
Type Parameters
- DefaultValue
  The default value that is returned if parsing fails.
Parameters
- input: unknown
  The value to parse.
- defaultValue: DefaultValue
  The default value that is returned if parsing fails.
- Optionaloptions: ParseOptions
  Parsing options.
Returns ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>) | DefaultValue
The value that conforms the output type of the shape.

Throws
Error if the shape doesn't support the sync parsing, see Shape.isAsync.

Inherited from Shape.parseOrDefault

parseOrDefaultAsync

parseOrDefaultAsync(input): Promisify<undefined | ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>
Asynchronously parses the value and returns undefined value if parsing fails.
Parameters
- input: unknown
  The value to parse.
Returns Promisify<undefined | ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>
The value that conforms the output type of the shape.

Inherited from Shape.parseOrDefaultAsync
parseOrDefaultAsync<DefaultValue>(input, defaultValue, options?): Promisify<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>) | DefaultValue>
Asynchronously parses the value and returns the default value if parsing fails.
Type Parameters
- DefaultValue
  The default value that is returned if parsing fails.
Parameters
- input: unknown
  The value to parse.
- defaultValue: DefaultValue
  The default value that is returned if parsing fails.
- Optionaloptions: ParseOptions
  Parsing options.
Returns Promisify<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>) | DefaultValue>
The value that conforms the output type of the shape.

Inherited from Shape.parseOrDefaultAsync

refine

refine<RefinedValue, Param>(cb, options): RefineShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, RefinedValue>
Adds a synchronous operation that refines the shape output type with the narrowing predicate.
Type Parameters
- RefinedValue extends ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)
  The narrowed output value.
- Param
  The param that is passed to the operation when it is applied.
Parameters
- cb: RefinePredicate<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>), RefinedValue, Param>
  The predicate that returns true if the value conforms the required type, or false otherwise.
- options: Message | ParameterizedRefineOptions<Param>
  The operation options or the issue message.
Returns RefineShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, RefinedValue>
The shape with the narrowed output.
See
Inherited from Shape.refine
refine<RefinedValue>(cb, options?): RefineShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, RefinedValue>
Adds a synchronous operation that refines the shape output type with the narrowing predicate.
Type Parameters
- RefinedValue extends ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)
  The narrowed output value.
Parameters
- cb: RefinePredicate<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>), RefinedValue>
  The predicate that returns true if the value conforms the required type, or false otherwise.
- Optionaloptions: Message | RefineOptions
  The operation options or the issue message.
Returns RefineShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, RefinedValue>
The shape with the narrowed output.
See
Inherited from Shape.refine
refine<Param>(cb, options?): this
Adds a synchronous operation that checks that the output value conforms the predicate.
Type Parameters
- Param
  The param that is passed to the operation when it is applied.
Parameters
- cb: OperationCallback<unknown, ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>), Param>
  The predicate that returns truthy result if the value is valid, or returns falsy result otherwise.
- Optionaloptions: Message | ParameterizedRefineOptions<Param>
  The operation options or the issue message.
Returns this
The clone of the shape.
See
Inherited from Shape.refine
refine(cb, options?): this
Adds a synchronous operation that checks that the output value conforms the predicate.
Parameters
- cb: OperationCallback<unknown, ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>
  The predicate that returns truthy result if the value is valid, or returns falsy result otherwise.
- Optionaloptions: Message | RefineOptions
  The operation options or the issue message.
Returns this
The clone of the shape.
See
Inherited from Shape.refine

refineAsync

refineAsync<Param>(cb, options?): this
Adds an asynchronous operation that checks that the output value conforms the predicate.
Type Parameters
- Param
  The param that is passed to the operation when it is applied.
Parameters
- cb: OperationCallback<PromiseLike<unknown>, ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>), Param>
  The predicate that returns a promise that resolves with a truthy result if the value is valid, or a falsy result otherwise.
- Optionaloptions: Message | ParameterizedRefineOptions<Param>
  The operation options or the issue message.
Returns this
The clone of the shape.
See
Inherited from Shape.refineAsync
refineAsync(cb, options?): this
Adds an asynchronous operation that checks that the output value conforms the predicate.
Parameters
- cb: OperationCallback<PromiseLike<unknown>, ((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>
  The predicate that returns a promise that resolves with a truthy result if the value is valid, or a falsy result otherwise.
- Optionaloptions: Message | RefineOptions
  The operation options or the issue message.
Returns this
The clone of the shape.
See
Inherited from Shape.refineAsync

replace

replace<InputValue, OutputValue>(inputValue, outputValue): ReplaceShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, InputValue, OutputValue>
Replaces an input value with an output value.
Type Parameters
- InputValue extends Any
  The input value to replace.
- OutputValue extends Any
  The output value that is used as the replacement for an input value.
Parameters
- inputValue: InputValue
  The input value to replace.
- outputValue: OutputValue
  The output value that is returned if an inputValue is received.
Returns ReplaceShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, InputValue, OutputValue>
Inherited from Shape.replace

return

return<S>(shape): FunctionShape<ArgsShape, S, ThisShape>
Constrains the function return value with the given shape.
Type Parameters
- S extends null | AnyShape
  The return value shape.
Parameters
- shape: S
  The return value shape, or null if unconstrained.
Returns FunctionShape<ArgsShape, S, ThisShape>
The new function shape.

strict

strict(options?): this
Enables input function wrapping during parsing to ensure runtime signature type-safety. Wrapper ensures that input function receives arguments and this values that conform the argsShape and thisShape respectively, and returns the value that conforms returnShape.
Parameters
- Optionaloptions: ParseOptions
  Options that are used by the wrapper. If omitted then default options are applied: no early-return, no type coercion.
Returns this
The new function shape.

this

this<S>(shape): FunctionShape<ArgsShape, ReturnShape, S>
Constrains the type of this inside the function.
Type Parameters
- S extends null | AnyShape
  The shape of this argument.
Parameters
- shape: S
  The shape of this argument, or null if unconstrained.
Returns FunctionShape<ArgsShape, ReturnShape, S>
The new function shape.

to

to<OutputShape>(shape): PipeShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, OutputShape>
Pipes the output of this shape to the input of another shape.
Type Parameters
- OutputShape extends AnyShape
  The output value.
Parameters
- shape: OutputShape
  The shape that validates the output if this shape.
Returns PipeShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, OutputShape>
Inherited from Shape.to

try

try(input, options?): Err | Ok<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>
Synchronously parses the value and returns Ok or Err object that wraps the result.
Parameters
- input: unknown
  The value to parse.
- Optionaloptions: ParseOptions
  Parsing options.
Returns Err | Ok<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>
The Ok instance if parsing has succeeded or Err if parsing has failed.

Throws
Error if the shape doesn't support the sync parsing, see Shape.isAsync.

Inherited from Shape.try

tryAsync

tryAsync(input, options?): Promise<Err | Ok<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>>
Asynchronously parses the value and returns Ok or Err object that wraps the result.
Parameters
- input: unknown
  The value to parse.
- Optionaloptions: ParseOptions
  Parsing options.
Returns Promise<Err | Ok<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>>
The Ok instance if parsing has succeeded or Err if parsing has failed.

Inherited from Shape.tryAsync

Accessors

isAsyncFunction

get isAsyncFunction(): boolean
true if some shapes that describe the function signature are async, or false otherwise.

Returns boolean

Class FunctionShape<ArgsShape, ReturnShape, ThisShape>

Type Parameters

Hierarchy (view full)

Index

Constructors

Properties

Methods

Accessors

Constructors

constructor

Type Parameters

Parameters

Returns FunctionShape<ArgsShape, ReturnShape, ThisShape>

Properties

Protected_options

Protected_parseOptions

annotations

See

ReadonlyargsShape

Readonlyinputs

ReadonlyisAsync

isStrict

operations

See

ReadonlyreturnShape

ReadonlythisShape

Methods

Protected_apply

Parameters

Returns Result<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>

See

Protected_applyAsync

Parameters

Returns Promise<Result<((this: InferOrDefault<ThisShape, typeof INPUT, any>, ...args: Input<ArgsShape>) => InferOrDefault<ReturnShape, typeof OUTPUT, any>)>>

See

Protected_applyOperations

Parameters

Returns Result | Promise<Result>

Protected_clone

Returns this

See

Protected_getInputs

Returns readonly unknown[]

See

Protected_isAsync

Returns boolean

See

accepts

Parameters

Returns boolean

addAsyncOperation

Type Parameters

Parameters

Returns this

See

Parameters

Returns this

See

addOperation

Type Parameters

Parameters

Returns this

See

Parameters

Returns this

See

allow

Type Parameters

Parameters

Returns AllowShape<FunctionShape<ArgsShape, ReturnShape, ThisShape>, AllowedValue>

alter

Type Parameters

Parameters

Returns this

See

Parameters

Returns this

See

alterAsync

Type Parameters

`Protected`_options

`Protected`_parseOptions

`Readonly`argsShape

`Readonly`inputs

`Readonly`isAsync

`Readonly`returnShape

`Readonly`thisShape

`Protected`_apply

`Protected`_applyAsync

`Protected`_applyOperations

`Protected`_clone

`Protected`_getInputs

`Protected`_isAsync