succulent
Version:
Powerful and easy runtime type checking
158 lines (157 loc) • 6.32 kB
TypeScript
import { LiteralSchema, Schema, SchemaBase } from "../schema.js";
export declare function $instanceof<T extends Function>(t: T): Schema<T["prototype"]>;
/**
* @internalRemarks
* Like `instanceof`, but for constructors that might not actually be defined, such as
* `Blob` or `File`. If the type `T` is not available in the current environment, the
* returned schema will be an alias of `$never`.
*/
export declare function $tryinstanceof<T extends Function>(mapT: () => T): Schema<(x: unknown) => x is never> | Schema<T["prototype"]>;
/**
* Alias for $instanceof, i.e. checks if a value is "a"/an `T`
*/
export declare const a: typeof $instanceof;
/**
* Checks for equality with `Object.is`.
* @example
* ```ts
* guard(1, $literal(1)); // ok
* guard(2, $literal(1)); // throws a `TypeError` because `1 !== 2`
* guard("hello", $literal("hello")); // ok
* guard("hey", $literal("hello")); // throws a `TypeError` because `"hey" !== "hello"`
* ```
*/
export declare function $literal<T extends LiteralSchema>(t: T): Schema<T>;
export type nullish = undefined | null;
/**
* Matches `null` or `undefined`.
* @example
* ```ts
* guard(undefined, $nullish); // ok
* guard(null, $nullish); // ok
* guard(0, $nullish); // throws a `TypeError` because `0` is not `null` or `undefined`
* ```
*/
export declare const $nullish: Schema<((x: unknown) => x is nullish) | null | undefined>;
/**
* @internalRemarks
* Notably missing is (typeof NaN), which can't be included because it just
* evaluates to `number`, and the vast majority of numbers are not falsy
*/
export type falsy = false | 0 | 0n | "" | nullish;
/**
* @example
* ```ts
*/
export declare const $falsy: Schema<false | "" | 0 | 0n | null | undefined>;
/**
* Alias for `union($T, undefined)` (with a prettier display name).
* @example
* ```ts
* guard(undefined, $optional($string)); // ok
* guard("hello, computer!", $optional($string)); // ok
* guard(0, $optional($string)); // throws a `TypeError` because `0` is not a string
* ```
*/
export declare function $optional<T>(base: SchemaBase<T>): Schema<T | undefined>;
/**
* Alias for `union($T, null, undefined)` (with a prettier display name).
* @example
* ```ts
* guard(undefined, $optional($string)); // ok
* guard("hello, computer!", $optional($string)); // ok
* guard(0, $optional($string)); // throws a `TypeError` because `0` is not a string
* ```
*/
export declare function $maybe<T>(base: SchemaBase<T>): Schema<T | nullish>;
/**
* As the name suggests, any value passed will be valid, even values you might really not
* expect, like functions.
* @remarks
* Probably shouldn't be used very frequently, but occasionally useful for
* stuff like `$array($any)` or just specifying that an object should have a
* key, without needing to specify the whole type. Basically the same kind of
* cases you might want to use it for in TypeScript.
* @example
* ```ts
* guard(undefined, $any); // ok
* guard(null, $any); // ok
* guard(1, $any); // ok
* guard("hello", $any); // ok
* guard({}, $any); // ok
* guard([], $any); // ok
* guard(Symbol(), $any); // ok
* guard(() => {}, $any); // ok
* guard(class {}, $any); // ok
* guard(new Date(), $any); // ok
* guard(/friend/, $any); // ok
* // ...you get the point
* ```
*/
export declare const $any: Schema<any>;
/**
* The opposite of `$any`, this schema will never match anything.
* @remarks
* Mostly useful for tests to convey that something should never match.
* @example
* ```ts
* guard(undefined, $never); // throws a `TypeError`
* guard(null, $never); // throws a `TypeError`
* guard(1, $never); // throws a `TypeError`
* guard("hello", $never); // throws a `TypeError`
* guard({}, $never); // throws a `TypeError`
* guard([], $never); // throws a `TypeError`
* guard(Symbol(), $never); // throws a `TypeError`
* guard(() => {}, $never); // throws a `TypeError`
* guard(class {}, $never); // throws a `TypeError`
* guard(new Date(), $never); // throws a `TypeError`
* guard(/friend/, $never); // throws a `TypeError`
* // ...you get the point
* ```
*/
export declare const $never: Schema<(x: unknown) => x is never>;
export declare const $Blob: Schema<(x: unknown) => x is never> | Schema<Blob>;
export declare const $Buffer: Schema<any> | Schema<(x: unknown) => x is never>;
export declare const $Date: Schema<Date>;
export declare const $File: Schema<(x: unknown) => x is never> | Schema<File>;
export declare const $Error: Schema<Error>;
export declare const $RegExp: Schema<RegExp>;
export declare const $Request: Schema<(x: unknown) => x is never> | Schema<Request>;
export declare const $Response: Schema<(x: unknown) => x is never> | Schema<Response>;
export declare const $URL: Schema<URL>;
/**
* @remarks
* One subtle use case for for `$ArrayBuffer` is to ensure that you *actually* have an
* `ArrayBuffer` object, and not a `Uint8Array` or some other view. A little known fact is
* that TypeScript will happily let you use a typed array in place of an `ArrayBuffer`,
* which is almost never what you want.
* @example
* ```ts
* function doSomeMagic(buffer: ArrayBuffer) {
* guard(buffer, $ArrayBuffer);
* // now you can *actually* be sure that `buffer` is an `ArrayBuffer`
* }
* ```
*/
export declare const $ArrayBuffer: Schema<ArrayBuffer>;
/**
* `ArrayBufferView`s are anything that's backed by an `ArrayBuffer`, like a `Uint8Array`
* or any other typed array.
* @example
* ```ts
* guard(new Uint8Array(), $ArrayBufferView); // ok
* guard(new ArrayBuffer(), $ArrayBufferView); // throws a `TypeError`, `ArrayBuffer` is not an `ArrayBufferView`
* ```
*/
export declare const $ArrayBufferView: Schema<ArrayBufferView>;
export declare const $Int8Array: Schema<Int8Array>;
export declare const $Int16Array: Schema<Int16Array>;
export declare const $Int32Array: Schema<Int32Array>;
export declare const $BigInt64Array: Schema<BigInt64Array>;
export declare const $Uint8Array: Schema<Uint8Array>;
export declare const $Uint8ClampedArray: Schema<Uint8ClampedArray>;
export declare const $Uint16Array: Schema<Uint16Array>;
export declare const $Uint32Array: Schema<Uint32Array>;
export declare const $BigUint64Array: Schema<BigUint64Array>;
export declare const $Float32Array: Schema<Float32Array>;
export declare const $Float64Array: Schema<Float64Array>;