Manually fix other lint errors

.depcheckrc.json

@@ -5,6 +5,7 @@
     "@metamask/auto-changelog",
     "@types/*",
     "prettier-plugin-packagejson",
+    "superstruct",
     "ts-node",
     "typedoc"
   ]

.eslintrc.js

@@ -23,6 +23,14 @@ module.exports = {
         '@metamask/eslint-config-jest',
         '@metamask/eslint-config-nodejs',
       ],
+      rules: {
+        '@typescript-eslint/no-shadow': [
+          'error',
+          {
+            allow: ['describe', 'it'],
+          },
+        ],
+      },
     },
   ],
 
@@ -32,5 +40,6 @@ module.exports = {
     'dist/',
     'docs/',
     '.yarn/',
+    'examples/',
   ],
 };

package.json

@@ -79,7 +79,6 @@
     "@types/expect": "^24.3.0",
     "@types/lodash": "^4.14.144",
     "@types/lodash-es": "^4.17.12",
-    "@types/mocha": "^10.0.0",
     "@types/node": "^18.7.14",
     "@typescript-eslint/eslint-plugin": "^5.43.0",
     "@typescript-eslint/parser": "^5.43.0",
@@ -97,7 +96,6 @@
     "is-uuid": "^1.0.2",
     "jest": "^29.7.0",
     "lodash-es": "^4.17.21",
-    "mocha": "^10.0.0",
     "np": "^7.6.2",
     "prettier": "^2.7.1",
     "prettier-plugin-packagejson": "^2.3.0",

src/error.ts

@@ -8,7 +8,7 @@ export type Failure = {
   type: string;
   refinement: string | undefined;
   message: string;
-  explanation?: string;
+  explanation?: string | undefined;
   branch: any[];
   path: any[];
 };
@@ -43,12 +43,14 @@ export class StructError extends TypeError {
     let cached: Failure[] | undefined;
     const { message, explanation, ...rest } = failure;
     const { path } = failure;
-    const msg =
+    const cause =
       path.length === 0 ? message : `At path: ${path.join('.')} -- ${message}`;
-    super(explanation ?? msg);
-    if (explanation != null) {
-      this.cause = msg;
+    super(explanation ?? cause);
+
+    if (explanation !== null && explanation !== undefined) {
+      this.cause = cause;
     }
+
     Object.assign(this, rest);
     this.name = this.constructor.name;
     this.failures = () => {

src/index.ts

@@ -1,6 +1,6 @@
-export * from './error.js'
-export * from './struct.js'
-export * from './structs/coercions.js'
-export * from './structs/refinements.js'
-export * from './structs/types.js'
-export * from './structs/utilities.js'
+export * from './error.js';
+export * from './struct.js';
+export * from './structs/coercions.js';
+export * from './structs/refinements.js';
+export * from './structs/types.js';
+export * from './structs/utilities.js';

src/struct.ts

@@ -9,18 +9,19 @@ import { toFailures, shiftIterator, run } from './utils.js';
  * validate unknown input data against the struct.
  */
 
-export class Struct<T = unknown, S = unknown> {
-  readonly TYPE!: T;
+export class Struct<Type = unknown, Schema = unknown> {
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  readonly TYPE!: Type;
 
   type: string;
 
-  schema: S;
+  schema: Schema;
 
   coercer: (value: unknown, context: Context) => unknown;
 
   validator: (value: unknown, context: Context) => Iterable<Failure>;
 
-  refiner: (value: T, context: Context) => Iterable<Failure>;
+  refiner: (value: Type, context: Context) => Iterable<Failure>;
 
   entries: (
     value: unknown,
@@ -29,19 +30,21 @@ export class Struct<T = unknown, S = unknown> {
 
   constructor(props: {
     type: string;
-    schema: S;
-    coercer?: Coercer;
-    validator?: Validator;
-    refiner?: Refiner<T>;
-    entries?: Struct<T, S>['entries'];
+    schema: Schema;
+    coercer?: Coercer | undefined;
+    validator?: Validator | undefined;
+    refiner?: Refiner<Type> | undefined;
+    entries?: Struct<Type, Schema>['entries'] | undefined;
   }) {
     const {
       type,
       schema,
       validator,
       refiner,
       coercer = (value: unknown) => value,
-      entries = function* () {},
+      entries = function* () {
+        /* noop */
+      },
     } = props;
 
     this.type = type;
@@ -72,23 +75,23 @@ export class Struct<T = unknown, S = unknown> {
    * Assert that a value passes the struct's validation, throwing if it doesn't.
    */
 
-  assert(value: unknown, message?: string): asserts value is T {
+  assert(value: unknown, message?: string): asserts value is Type {
     return assert(value, this, message);
   }
 
   /**
    * Create a value with the struct's coercion logic, then validate it.
    */
 
-  create(value: unknown, message?: string): T {
+  create(value: unknown, message?: string): Type {
     return create(value, this, message);
   }
 
   /**
    * Check if a value passes the struct's validation.
    */
 
-  is(value: unknown): value is T {
+  is(value: unknown): value is Type {
     return is(value, this);
   }
 
@@ -97,7 +100,7 @@ export class Struct<T = unknown, S = unknown> {
    * properties defined by the struct's schema.
    */
 
-  mask(value: unknown, message?: string): T {
+  mask(value: unknown, message?: string): Type {
     return mask(value, this, message);
   }
 
@@ -116,26 +119,23 @@ export class Struct<T = unknown, S = unknown> {
       coerce?: boolean;
       message?: string;
     } = {},
-  ): [StructError, undefined] | [undefined, T] {
+  ): [StructError, undefined] | [undefined, Type] {
     return validate(value, this, options);
   }
 }
 
 /**
  * Assert that a value passes a struct, throwing if it doesn't.
- */
-
-/**
  *
- * @param value
- * @param struct
- * @param message
+ * @param value - The value to validate.
+ * @param struct - The struct to validate against.
+ * @param message - An optional message to include in the error.
  */
-export function assert<T, S>(
+export function assert<Type, Schema>(
   value: unknown,
-  struct: Struct<T, S>,
+  struct: Struct<Type, Schema>,
   message?: string,
-): asserts value is T {
+): asserts value is Type {
   const result = validate(value, struct, { message });
 
   if (result[0]) {
@@ -145,19 +145,17 @@ export function assert<T, S>(
 
 /**
  * Create a value with the coercion logic of struct and validate it.
- */
-
-/**
  *
- * @param value
- * @param struct
- * @param message
+ * @param value - The value to coerce and validate.
+ * @param struct - The struct to validate against.
+ * @param message - An optional message to include in the error.
+ * @returns The coerced and validated value.
  */
-export function create<T, S>(
+export function create<Type, Schema>(
   value: unknown,
-  struct: Struct<T, S>,
+  struct: Struct<Type, Schema>,
   message?: string,
-): T {
+): Type {
   const result = validate(value, struct, { coerce: true, message });
 
   if (result[0]) {
@@ -169,19 +167,17 @@ export function create<T, S>(
 
 /**
  * Mask a value, returning only the subset of properties defined by a struct.
- */
-
-/**
  *
- * @param value
- * @param struct
- * @param message
+ * @param value - The value to mask.
+ * @param struct - The struct to mask against.
+ * @param message - An optional message to include in the error.
+ * @returns The masked value.
  */
-export function mask<T, S>(
+export function mask<Type, Schema>(
   value: unknown,
-  struct: Struct<T, S>,
+  struct: Struct<Type, Schema>,
   message?: string,
-): T {
+): Type {
   const result = validate(value, struct, { coerce: true, mask: true, message });
 
   if (result[0]) {
@@ -193,57 +189,60 @@ export function mask<T, S>(
 
 /**
  * Check if a value passes a struct.
- */
-
-/**
  *
- * @param value
- * @param struct
+ * @param value - The value to validate.
+ * @param struct - The struct to validate against.
+ * @returns `true` if the value passes the struct, `false` otherwise.
  */
-export function is<T, S>(value: unknown, struct: Struct<T, S>): value is T {
+export function is<Type, Schema>(
+  value: unknown,
+  struct: Struct<Type, Schema>,
+): value is Type {
   const result = validate(value, struct);
   return !result[0];
 }
 
 /**
  * Validate a value against a struct, returning an error if invalid, or the
  * value (with potential coercion) if valid.
- */
-
-/**
  *
- * @param value
- * @param struct
- * @param options
- * @param options.coerce
- * @param options.mask
- * @param options.message
+ * @param value - The value to validate.
+ * @param struct - The struct to validate against.
+ * @param options - Optional settings.
+ * @param options.coerce - Whether to coerce the value before validating it.
+ * @param options.mask - Whether to mask the value before validating it.
+ * @param options.message - An optional message to include in the error.
+ * @returns A tuple containing the error (if invalid) and the validated value.
  */
-export function validate<T, S>(
+export function validate<Type, Schema>(
   value: unknown,
-  struct: Struct<T, S>,
+  struct: Struct<Type, Schema>,
   options: {
-    coerce?: boolean;
-    mask?: boolean;
-    message?: string;
+    coerce?: boolean | undefined;
+    mask?: boolean | undefined;
+    message?: string | undefined;
   } = {},
-): [StructError, undefined] | [undefined, T] {
+): [StructError, undefined] | [undefined, Type] {
   const tuples = run(value, struct, options);
-  const tuple = shiftIterator(tuples)!;
+  const tuple = shiftIterator(tuples) as [
+    Failure | undefined,
+    Type | undefined,
+  ];
 
   if (tuple[0]) {
     const error = new StructError(tuple[0], function* () {
-      for (const t of tuples) {
-        if (t[0]) {
-          yield t[0];
+      for (const innerTuple of tuples) {
+        if (innerTuple[0]) {
+          yield innerTuple[0];
         }
       }
     });
 
     return [error, undefined];
   }
-  const v = tuple[1];
-  return [undefined, v];
+
+  const validatedValue = tuple[1] as Type;
+  return [undefined, validatedValue];
 }
 
 /**
@@ -260,13 +259,13 @@ export type Context = {
  * A type utility to extract the type from a `Struct` class.
  */
 
-export type Infer<T extends Struct<any, any>> = T['TYPE'];
+export type Infer<StructType extends Struct<any, any>> = StructType['TYPE'];
 
 /**
  * A type utility to describe that a struct represents a TypeScript type.
  */
 
-export type Describe<T> = Struct<T, StructSchema<T>>;
+export type Describe<Type> = Struct<Type, StructSchema<Type>>;
 
 /**
  * A `Result` is returned from validation functions.
@@ -282,7 +281,10 @@ export type Result =
  * A `Coercer` takes an unknown value and optionally coerces it.
  */
 
-export type Coercer<T = unknown> = (value: T, context: Context) => unknown;
+export type Coercer<Type = unknown> = (
+  value: Type,
+  context: Context,
+) => unknown;
 
 /**
  * A `Validator` takes an unknown value and validates it.
@@ -295,4 +297,4 @@ export type Validator = (value: unknown, context: Context) => Result;
  * constraint.
  */
 
-export type Refiner<T> = (value: T, context: Context) => Result;
+export type Refiner<Type> = (value: Type, context: Context) => Result;