@metamask/snaps-utils 8.0.1 → 8.1.0

package/dist/structs.d.cts

@@ -0,0 +1,181 @@
+import type { AnyStruct, Assign, Failure, ObjectSchema, ObjectType } from "@metamask/superstruct";
+import { Struct, StructError } from "@metamask/superstruct";
+/**
+ * Infer a struct type, only if it matches the specified type. This is useful
+ * for defining types and structs that are related to each other in separate
+ * files.
+ *
+ * @example
+ * ```typescript
+ * // In file A
+ * export type GetFileArgs = {
+ *   path: string;
+ *   encoding?: EnumToUnion<AuxiliaryFileEncoding>;
+ * };
+ *
+ * // In file B
+ * export const GetFileArgsStruct = object(...);
+ *
+ * // If the type and struct are in the same file, this will return the type.
+ * // Otherwise, it will return `never`.
+ * export type GetFileArgs =
+ *   InferMatching<typeof GetFileArgsStruct, GetFileArgs>;
+ * ```
+ */
+export type InferMatching<StructType extends Struct<any, any>, Type> = StructType['TYPE'] extends Type ? Type : never;
+/**
+ * Define a struct, and also define the name of the struct as the given name.
+ *
+ * This is useful for improving the error messages returned by `superstruct`.
+ *
+ * @param name - The name of the struct.
+ * @param struct - The struct.
+ * @returns The struct.
+ */
+export declare function named<Type, Schema>(name: string, struct: Struct<Type, Schema>): Struct<Type, Schema>;
+export declare class SnapsStructError<Type, Schema> extends StructError {
+    constructor(struct: Struct<Type, Schema>, prefix: string, suffix: string, failure: StructError, failures: () => Generator<Failure>, colorize?: boolean);
+}
+type GetErrorOptions<Type, Schema> = {
+    struct: Struct<Type, Schema>;
+    prefix: string;
+    suffix?: string;
+    error: StructError;
+    colorize?: boolean;
+};
+/**
+ * Converts an array to a generator function that yields the items in the
+ * array.
+ *
+ * @param array - The array.
+ * @returns A generator function.
+ * @yields The items in the array.
+ */
+export declare function arrayToGenerator<Type>(array: Type[]): Generator<Type, void, undefined>;
+/**
+ * Returns a `SnapsStructError` with the given prefix and suffix.
+ *
+ * @param options - The options.
+ * @param options.struct - The struct that caused the error.
+ * @param options.prefix - The prefix to add to the error message.
+ * @param options.suffix - The suffix to add to the error message. Defaults to
+ * an empty string.
+ * @param options.error - The `superstruct` error to wrap.
+ * @param options.colorize - Whether to colorize the value. Defaults to `true`.
+ * @returns The `SnapsStructError`.
+ */
+export declare function getError<Type, Schema>({ struct, prefix, suffix, error, colorize, }: GetErrorOptions<Type, Schema>): SnapsStructError<Type, Schema>;
+/**
+ * A wrapper of `superstruct`'s `create` function that throws a
+ * `SnapsStructError` instead of a `StructError`. This is useful for improving
+ * the error messages returned by `superstruct`.
+ *
+ * @param value - The value to validate.
+ * @param struct - The `superstruct` struct to validate the value against.
+ * @param prefix - The prefix to add to the error message.
+ * @param suffix - The suffix to add to the error message. Defaults to an empty
+ * string.
+ * @returns The validated value.
+ */
+export declare function createFromStruct<Type, Schema>(value: unknown, struct: Struct<Type, Schema>, prefix: string, suffix?: string): Type;
+/**
+ * Get a struct from a failure path.
+ *
+ * @param struct - The struct.
+ * @param path - The failure path.
+ * @returns The struct at the failure path.
+ */
+export declare function getStructFromPath<Type, Schema>(struct: Struct<Type, Schema>, path: string[]): AnyStruct;
+/**
+ * Get the union struct names from a struct.
+ *
+ * @param struct - The struct.
+ * @param colorize - Whether to colorize the value. Defaults to `true`.
+ * @returns The union struct names, or `null` if the struct is not a union
+ * struct.
+ */
+export declare function getUnionStructNames<Type, Schema>(struct: Struct<Type, Schema>, colorize?: boolean): string[] | null;
+/**
+ * Get an error prefix from a `superstruct` failure. This is useful for
+ * formatting the error message returned by `superstruct`.
+ *
+ * @param failure - The `superstruct` failure.
+ * @param colorize - Whether to colorize the value. Defaults to `true`.
+ * @returns The error prefix.
+ */
+export declare function getStructErrorPrefix(failure: Failure, colorize?: boolean): string;
+/**
+ * Get a string describing the failure. This is similar to the `message`
+ * property of `superstruct`'s `Failure` type, but formats the value in a more
+ * readable way.
+ *
+ * @param struct - The struct that caused the failure.
+ * @param failure - The `superstruct` failure.
+ * @param colorize - Whether to colorize the value. Defaults to `true`.
+ * @returns A string describing the failure.
+ */
+export declare function getStructFailureMessage<Type, Schema>(struct: Struct<Type, Schema>, failure: Failure, colorize?: boolean): string;
+/**
+ * Get a string describing the errors. This formats all the errors in a
+ * human-readable way.
+ *
+ * @param struct - The struct that caused the failures.
+ * @param failures - The `superstruct` failures.
+ * @param colorize - Whether to colorize the value. Defaults to `true`.
+ * @returns A string describing the errors.
+ */
+export declare function getStructErrorMessage<Type, Schema>(struct: Struct<Type, Schema>, failures: Failure[], colorize?: boolean): string;
+/**
+ * Validate a union struct, and throw readable errors if the value does not
+ * satisfy the struct. This is useful for improving the error messages returned
+ * by `superstruct`.
+ *
+ * @param value - The value to validate.
+ * @param struct - The `superstruct` union struct to validate the value against.
+ * This struct must be a union of object structs, and must have at least one
+ * shared key to validate against.
+ * @param structKey - The key to validate against. This key must be present in
+ * all the object structs in the union struct, and is expected to be a literal
+ * value.
+ * @param coerce - Whether to coerce the value to satisfy the struct. Defaults
+ * to `false`.
+ * @returns The validated value.
+ * @throws If the value does not satisfy the struct.
+ * @example
+ * const struct = union([
+ *   object({ type: literal('a'), value: string() }),
+ *   object({ type: literal('b'), value: number() }),
+ *   object({ type: literal('c'), value: boolean() }),
+ *   // ...
+ * ]);
+ *
+ * // At path: type — Expected the value to be one of: "a", "b", "c", but received: "d".
+ * validateUnion({ type: 'd', value: 'foo' }, struct, 'type');
+ *
+ * // At path: value — Expected a value of type string, but received: 42.
+ * validateUnion({ type: 'a', value: 42 }, struct, 'value');
+ */
+export declare function validateUnion<Type, Schema extends readonly Struct<any, any>[]>(value: unknown, struct: Struct<Type, Schema>, structKey: keyof Type, coerce?: boolean): any;
+/**
+ * Create a value with the coercion logic of a union struct, and throw readable
+ * errors if the value does not satisfy the struct. This is useful for improving
+ * the error messages returned by `superstruct`.
+ *
+ * @param value - The value to validate.
+ * @param struct - The `superstruct` union struct to validate the value against.
+ * This struct must be a union of object structs, and must have at least one
+ * shared key to validate against.
+ * @param structKey - The key to validate against. This key must be present in
+ * all the object structs in the union struct, and is expected to be a literal
+ * value.
+ * @returns The validated value.
+ * @throws If the value does not satisfy the struct.
+ * @see validateUnion
+ */
+export declare function createUnion<Type, Schema extends readonly Struct<any, any>[]>(value: unknown, struct: Struct<Type, Schema>, structKey: keyof Type): any;
+export declare function mergeStructs<ObjectA extends ObjectSchema, ObjectB extends ObjectSchema>(A: Struct<ObjectType<ObjectA>, ObjectA>, B: Struct<ObjectType<ObjectB>, ObjectB>): Struct<ObjectType<Assign<ObjectA, ObjectB>>, Assign<ObjectA, ObjectB>>;
+export declare function mergeStructs<ObjectA extends ObjectSchema, ObjectB extends ObjectSchema, ObjectC extends ObjectSchema>(A: Struct<ObjectType<ObjectA>, ObjectA>, B: Struct<ObjectType<ObjectB>, ObjectB>, C: Struct<ObjectType<ObjectC>, ObjectC>): Struct<ObjectType<Assign<Assign<ObjectA, ObjectB>, ObjectC>>, Assign<Assign<ObjectA, ObjectB>, ObjectC>>;
+export declare function mergeStructs<ObjectA extends ObjectSchema, ObjectB extends ObjectSchema, ObjectC extends ObjectSchema, ObjectD extends ObjectSchema>(A: Struct<ObjectType<ObjectA>, ObjectA>, B: Struct<ObjectType<ObjectB>, ObjectB>, C: Struct<ObjectType<ObjectC>, ObjectC>, D: Struct<ObjectType<ObjectD>, ObjectD>): Struct<ObjectType<Assign<Assign<Assign<ObjectA, ObjectB>, ObjectC>, ObjectD>>, Assign<Assign<Assign<ObjectA, ObjectB>, ObjectC>, ObjectD>>;
+export declare function mergeStructs<ObjectA extends ObjectSchema, ObjectB extends ObjectSchema, ObjectC extends ObjectSchema, ObjectD extends ObjectSchema, ObjectE extends ObjectSchema>(A: Struct<ObjectType<ObjectA>, ObjectA>, B: Struct<ObjectType<ObjectB>, ObjectB>, C: Struct<ObjectType<ObjectC>, ObjectC>, D: Struct<ObjectType<ObjectD>, ObjectD>, E: Struct<ObjectType<ObjectE>, ObjectE>): Struct<ObjectType<Assign<Assign<Assign<Assign<ObjectA, ObjectB>, ObjectC>, ObjectD>, ObjectE>>, Assign<Assign<Assign<Assign<ObjectA, ObjectB>, ObjectC>, ObjectD>, ObjectE>>;
+export {};
+//# sourceMappingURL=structs.d.cts.map

package/dist/structs.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structs.d.cts","sourceRoot":"","sources":["../src/structs.ts"],"names":[],"mappings":"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"}

package/dist/structs.d.mts

@@ -0,0 +1,181 @@
+import type { AnyStruct, Assign, Failure, ObjectSchema, ObjectType } from "@metamask/superstruct";
+import { Struct, StructError } from "@metamask/superstruct";
+/**
+ * Infer a struct type, only if it matches the specified type. This is useful
+ * for defining types and structs that are related to each other in separate
+ * files.
+ *
+ * @example
+ * ```typescript
+ * // In file A
+ * export type GetFileArgs = {
+ *   path: string;
+ *   encoding?: EnumToUnion<AuxiliaryFileEncoding>;
+ * };
+ *
+ * // In file B
+ * export const GetFileArgsStruct = object(...);
+ *
+ * // If the type and struct are in the same file, this will return the type.
+ * // Otherwise, it will return `never`.
+ * export type GetFileArgs =
+ *   InferMatching<typeof GetFileArgsStruct, GetFileArgs>;
+ * ```
+ */
+export type InferMatching<StructType extends Struct<any, any>, Type> = StructType['TYPE'] extends Type ? Type : never;
+/**
+ * Define a struct, and also define the name of the struct as the given name.
+ *
+ * This is useful for improving the error messages returned by `superstruct`.
+ *
+ * @param name - The name of the struct.
+ * @param struct - The struct.
+ * @returns The struct.
+ */
+export declare function named<Type, Schema>(name: string, struct: Struct<Type, Schema>): Struct<Type, Schema>;
+export declare class SnapsStructError<Type, Schema> extends StructError {
+    constructor(struct: Struct<Type, Schema>, prefix: string, suffix: string, failure: StructError, failures: () => Generator<Failure>, colorize?: boolean);
+}
+type GetErrorOptions<Type, Schema> = {
+    struct: Struct<Type, Schema>;
+    prefix: string;
+    suffix?: string;
+    error: StructError;
+    colorize?: boolean;
+};
+/**
+ * Converts an array to a generator function that yields the items in the
+ * array.
+ *
+ * @param array - The array.
+ * @returns A generator function.
+ * @yields The items in the array.
+ */
+export declare function arrayToGenerator<Type>(array: Type[]): Generator<Type, void, undefined>;
+/**
+ * Returns a `SnapsStructError` with the given prefix and suffix.
+ *
+ * @param options - The options.
+ * @param options.struct - The struct that caused the error.
+ * @param options.prefix - The prefix to add to the error message.
+ * @param options.suffix - The suffix to add to the error message. Defaults to
+ * an empty string.
+ * @param options.error - The `superstruct` error to wrap.
+ * @param options.colorize - Whether to colorize the value. Defaults to `true`.
+ * @returns The `SnapsStructError`.
+ */
+export declare function getError<Type, Schema>({ struct, prefix, suffix, error, colorize, }: GetErrorOptions<Type, Schema>): SnapsStructError<Type, Schema>;
+/**
+ * A wrapper of `superstruct`'s `create` function that throws a
+ * `SnapsStructError` instead of a `StructError`. This is useful for improving
+ * the error messages returned by `superstruct`.
+ *
+ * @param value - The value to validate.
+ * @param struct - The `superstruct` struct to validate the value against.
+ * @param prefix - The prefix to add to the error message.
+ * @param suffix - The suffix to add to the error message. Defaults to an empty
+ * string.
+ * @returns The validated value.
+ */
+export declare function createFromStruct<Type, Schema>(value: unknown, struct: Struct<Type, Schema>, prefix: string, suffix?: string): Type;
+/**
+ * Get a struct from a failure path.
+ *
+ * @param struct - The struct.
+ * @param path - The failure path.
+ * @returns The struct at the failure path.
+ */
+export declare function getStructFromPath<Type, Schema>(struct: Struct<Type, Schema>, path: string[]): AnyStruct;
+/**
+ * Get the union struct names from a struct.
+ *
+ * @param struct - The struct.
+ * @param colorize - Whether to colorize the value. Defaults to `true`.
+ * @returns The union struct names, or `null` if the struct is not a union
+ * struct.
+ */
+export declare function getUnionStructNames<Type, Schema>(struct: Struct<Type, Schema>, colorize?: boolean): string[] | null;
+/**
+ * Get an error prefix from a `superstruct` failure. This is useful for
+ * formatting the error message returned by `superstruct`.
+ *
+ * @param failure - The `superstruct` failure.
+ * @param colorize - Whether to colorize the value. Defaults to `true`.
+ * @returns The error prefix.
+ */
+export declare function getStructErrorPrefix(failure: Failure, colorize?: boolean): string;
+/**
+ * Get a string describing the failure. This is similar to the `message`
+ * property of `superstruct`'s `Failure` type, but formats the value in a more
+ * readable way.
+ *
+ * @param struct - The struct that caused the failure.
+ * @param failure - The `superstruct` failure.
+ * @param colorize - Whether to colorize the value. Defaults to `true`.
+ * @returns A string describing the failure.
+ */
+export declare function getStructFailureMessage<Type, Schema>(struct: Struct<Type, Schema>, failure: Failure, colorize?: boolean): string;
+/**
+ * Get a string describing the errors. This formats all the errors in a
+ * human-readable way.
+ *
+ * @param struct - The struct that caused the failures.
+ * @param failures - The `superstruct` failures.
+ * @param colorize - Whether to colorize the value. Defaults to `true`.
+ * @returns A string describing the errors.
+ */
+export declare function getStructErrorMessage<Type, Schema>(struct: Struct<Type, Schema>, failures: Failure[], colorize?: boolean): string;
+/**
+ * Validate a union struct, and throw readable errors if the value does not
+ * satisfy the struct. This is useful for improving the error messages returned
+ * by `superstruct`.
+ *
+ * @param value - The value to validate.
+ * @param struct - The `superstruct` union struct to validate the value against.
+ * This struct must be a union of object structs, and must have at least one
+ * shared key to validate against.
+ * @param structKey - The key to validate against. This key must be present in
+ * all the object structs in the union struct, and is expected to be a literal
+ * value.
+ * @param coerce - Whether to coerce the value to satisfy the struct. Defaults
+ * to `false`.
+ * @returns The validated value.
+ * @throws If the value does not satisfy the struct.
+ * @example
+ * const struct = union([
+ *   object({ type: literal('a'), value: string() }),
+ *   object({ type: literal('b'), value: number() }),
+ *   object({ type: literal('c'), value: boolean() }),
+ *   // ...
+ * ]);
+ *
+ * // At path: type — Expected the value to be one of: "a", "b", "c", but received: "d".
+ * validateUnion({ type: 'd', value: 'foo' }, struct, 'type');
+ *
+ * // At path: value — Expected a value of type string, but received: 42.
+ * validateUnion({ type: 'a', value: 42 }, struct, 'value');
+ */
+export declare function validateUnion<Type, Schema extends readonly Struct<any, any>[]>(value: unknown, struct: Struct<Type, Schema>, structKey: keyof Type, coerce?: boolean): any;
+/**
+ * Create a value with the coercion logic of a union struct, and throw readable
+ * errors if the value does not satisfy the struct. This is useful for improving
+ * the error messages returned by `superstruct`.
+ *
+ * @param value - The value to validate.
+ * @param struct - The `superstruct` union struct to validate the value against.
+ * This struct must be a union of object structs, and must have at least one
+ * shared key to validate against.
+ * @param structKey - The key to validate against. This key must be present in
+ * all the object structs in the union struct, and is expected to be a literal
+ * value.
+ * @returns The validated value.
+ * @throws If the value does not satisfy the struct.
+ * @see validateUnion
+ */
+export declare function createUnion<Type, Schema extends readonly Struct<any, any>[]>(value: unknown, struct: Struct<Type, Schema>, structKey: keyof Type): any;
+export declare function mergeStructs<ObjectA extends ObjectSchema, ObjectB extends ObjectSchema>(A: Struct<ObjectType<ObjectA>, ObjectA>, B: Struct<ObjectType<ObjectB>, ObjectB>): Struct<ObjectType<Assign<ObjectA, ObjectB>>, Assign<ObjectA, ObjectB>>;
+export declare function mergeStructs<ObjectA extends ObjectSchema, ObjectB extends ObjectSchema, ObjectC extends ObjectSchema>(A: Struct<ObjectType<ObjectA>, ObjectA>, B: Struct<ObjectType<ObjectB>, ObjectB>, C: Struct<ObjectType<ObjectC>, ObjectC>): Struct<ObjectType<Assign<Assign<ObjectA, ObjectB>, ObjectC>>, Assign<Assign<ObjectA, ObjectB>, ObjectC>>;
+export declare function mergeStructs<ObjectA extends ObjectSchema, ObjectB extends ObjectSchema, ObjectC extends ObjectSchema, ObjectD extends ObjectSchema>(A: Struct<ObjectType<ObjectA>, ObjectA>, B: Struct<ObjectType<ObjectB>, ObjectB>, C: Struct<ObjectType<ObjectC>, ObjectC>, D: Struct<ObjectType<ObjectD>, ObjectD>): Struct<ObjectType<Assign<Assign<Assign<ObjectA, ObjectB>, ObjectC>, ObjectD>>, Assign<Assign<Assign<ObjectA, ObjectB>, ObjectC>, ObjectD>>;
+export declare function mergeStructs<ObjectA extends ObjectSchema, ObjectB extends ObjectSchema, ObjectC extends ObjectSchema, ObjectD extends ObjectSchema, ObjectE extends ObjectSchema>(A: Struct<ObjectType<ObjectA>, ObjectA>, B: Struct<ObjectType<ObjectB>, ObjectB>, C: Struct<ObjectType<ObjectC>, ObjectC>, D: Struct<ObjectType<ObjectD>, ObjectD>, E: Struct<ObjectType<ObjectE>, ObjectE>): Struct<ObjectType<Assign<Assign<Assign<Assign<ObjectA, ObjectB>, ObjectC>, ObjectD>, ObjectE>>, Assign<Assign<Assign<Assign<ObjectA, ObjectB>, ObjectC>, ObjectD>, ObjectE>>;
+export {};
+//# sourceMappingURL=structs.d.mts.map

package/dist/structs.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structs.d.mts","sourceRoot":"","sources":["../src/structs.ts"],"names":[],"mappings":"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"}