eslint-plugin-ts-data-forge 0.8.1 → 0.8.3

package/src/rules/prefer-canonical-length-guard.test.mts

@@ -305,3 +305,102 @@ describe('prefer-canonical-length-guard', () => {
     ],
   });
 });
+
+describe('prefer-canonical-length-guard through type wrappers', () => {
+  tester.run('prefer-canonical-length-guard', preferCanonicalLengthGuard, {
+    valid: [
+      {
+        name: 'a wrapped bound other than the degenerate one',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isFixedLengthArray(1 as const, xs);
+        `,
+      },
+    ],
+    invalid: [
+      {
+        name: 'a bound wrapped in `as const` or `satisfies`',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const a = Arr.isFixedLengthArray(0 as const, xs);
+          const b = Arr.isBoundedLengthTuple(0 satisfies number, 0, xs!);
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const a = Arr.isEmpty(xs);
+          const b = Arr.isEmptyTuple(xs!);
+        `,
+        errors: [
+          { messageId: 'useCanonicalGuard' },
+          { messageId: 'useCanonicalGuard' },
+        ],
+      },
+    ],
+  });
+
+  typedTester.run('prefer-canonical-length-guard', preferCanonicalLengthGuard, {
+    valid: [
+      {
+        name: 'a computed index named `length` is not the length',
+        code: dedent`
+          declare const xs: readonly number[];
+          declare const length: number;
+          const ok = xs[length] > 0;
+        `,
+      },
+    ],
+    invalid: [
+      {
+        name: 'a folded-in comparison on a wrapped length',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+          declare const xs: readonly number[];
+          const a = (xs.length satisfies number) > 0;
+          const b = xs.length >= 1 && (xs as readonly number[]).length <= 3;
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+          declare const xs: readonly number[];
+          const a = Arr.isNonEmpty(xs);
+          const b = Arr.isBoundedLengthArray(1, 3, xs);
+        `,
+        errors: [
+          { messageId: 'useIsNonEmpty' },
+          { messageId: 'useIsBoundedLengthArray' },
+        ],
+      },
+    ],
+  });
+});
+
+describe('prefer-canonical-length-guard with parenthesized operands', () => {
+  tester.run('prefer-canonical-length-guard', preferCanonicalLengthGuard, {
+    valid: [],
+    invalid: [
+      {
+        name: 'a sequence array keeps its parentheses',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          declare const log: () => void;
+          const ok = Arr.isFixedLengthArray(0, (log(), xs));
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          declare const log: () => void;
+          const ok = Arr.isEmpty((log(), xs));
+        `,
+        errors: [{ messageId: 'useCanonicalGuard' }],
+      },
+    ],
+  });
+});

package/src/rules/prefer-comparison-over-nullish-guard.mts

@@ -3,7 +3,7 @@ import {
   type TSESLint,
   type TSESTree,
 } from '@typescript-eslint/utils';
-import { type DeepReadonly, type ReadonlyRecord } from 'ts-type-forge';
+import type { DeepReadonly, ReadonlyRecord } from 'ts-type-forge';
 import { buildCalleeResolver, getTsDataForgeImport } from './import-utils.mjs';
 
 type Options = readonly [];
@@ -29,7 +29,11 @@ const COMPARISON_GUARDS: ReadonlyRecord<string, ComparisonSpec> = {
 
 /**
  * Argument expression kinds whose precedence is lower than equality, so they
- * must be parenthesized when placed on the left of `===` / `!==`.
+ * must be parenthesized when placed on the left of `===` / `!==`. A node's text
+ * never includes the parentheses the source wrote around it, so this is decided
+ * on the kind alone. `as` / `satisfies` and a nested equality would parse as
+ * intended, but are parenthesized so that the type or the grouping is not read
+ * as part of the comparison.
  */
 const ARG_NEEDS_PARENS: ReadonlySet<string> = new Set([
   AST_NODE_TYPES.LogicalExpression,
@@ -38,11 +42,33 @@ const ARG_NEEDS_PARENS: ReadonlySet<string> = new Set([
   AST_NODE_TYPES.SequenceExpression,
   AST_NODE_TYPES.ArrowFunctionExpression,
   AST_NODE_TYPES.YieldExpression,
+  AST_NODE_TYPES.TSAsExpression,
+  AST_NODE_TYPES.TSSatisfiesExpression,
 ]);
 
+/** Binary operators that bind no tighter than `===` / `!==`. */
+const LOOSE_BINARY_OPERATORS: ReadonlySet<string> = new Set([
+  '|',
+  '^',
+  '&',
+  '==',
+  '!=',
+  '===',
+  '!==',
+]);
+
+const argumentNeedsParens = (
+  argument: DeepReadonly<TSESTree.Expression>,
+): boolean =>
+  ARG_NEEDS_PARENS.has(argument.type) ||
+  (argument.type === AST_NODE_TYPES.BinaryExpression &&
+    LOOSE_BINARY_OPERATORS.has(argument.operator));
+
 /**
  * Returns `true` when the comparison must be wrapped in parentheses to preserve
- * the original grouping given the call expression's parent context.
+ * the original grouping given the call expression's parent context. A type
+ * wrapper around the call is one such context: `x === null satisfies boolean`
+ * would apply the wrapper to `null`.
  */
 const needsWrappingInParent = (
   node: DeepReadonly<TSESTree.CallExpression>,
@@ -56,6 +82,9 @@ const needsWrappingInParent = (
     case AST_NODE_TYPES.AwaitExpression:
     case AST_NODE_TYPES.BinaryExpression:
     case AST_NODE_TYPES.TSNonNullExpression:
+    case AST_NODE_TYPES.TSAsExpression:
+    case AST_NODE_TYPES.TSSatisfiesExpression:
+    case AST_NODE_TYPES.TSTypeAssertion:
       return true;
 
     case AST_NODE_TYPES.MemberExpression:
@@ -97,7 +126,9 @@ export const preferComparisonOverNullishGuard: TSESLint.RuleModule<
 
     return {
       CallExpression: (node) => {
-        if (node.arguments.length !== 1) return;
+        if (node.arguments.length !== 1) {
+          return;
+        }
 
         const argument = node.arguments[0];
 
@@ -110,17 +141,19 @@ export const preferComparisonOverNullishGuard: TSESLint.RuleModule<
 
         const resolved = resolveGuard(node.callee);
 
-        if (resolved === undefined) return;
+        if (resolved === undefined) {
+          return;
+        }
 
         const spec = COMPARISON_GUARDS[resolved.canonicalName];
 
-        if (spec === undefined) return;
+        if (spec === undefined) {
+          return;
+        }
 
         const argRaw = sourceCode.getText(argument);
 
-        const argText = ARG_NEEDS_PARENS.has(argument.type)
-          ? `(${argRaw})`
-          : argRaw;
+        const argText = argumentNeedsParens(argument) ? `(${argRaw})` : argRaw;
 
         const comparison = `${argText} ${spec.op} ${spec.literal}`;
 

package/src/rules/prefer-comparison-over-nullish-guard.test.mts

@@ -169,3 +169,139 @@ describe('prefer-comparison-over-nullish-guard', () => {
     },
   );
 });
+
+describe('prefer-comparison-over-nullish-guard through type wrappers', () => {
+  tester.run(
+    'prefer-comparison-over-nullish-guard',
+    preferComparisonOverNullishGuard,
+    {
+      valid: [],
+      invalid: [
+        {
+          name: 'the call wrapped in `satisfies`, `as` or `<T>`',
+          code: dedent`
+            import { isNull, isNotUndefined } from 'ts-data-forge';
+            declare const x: string | null | undefined;
+            const a = isNull(x) satisfies boolean;
+            const b = isNotUndefined(x) as boolean;
+            const c = <boolean>isNull(x);
+          `,
+          output: dedent`
+            import { isNull, isNotUndefined } from 'ts-data-forge';
+            declare const x: string | null | undefined;
+            const a = (x === null) satisfies boolean;
+            const b = (x !== undefined) as boolean;
+            const c = <boolean>(x === null);
+          `,
+          errors: [
+            { messageId: 'preferComparison' },
+            { messageId: 'preferComparison' },
+            { messageId: 'preferComparison' },
+          ],
+        },
+        {
+          name: 'a wrapped argument is parenthesized under `===`',
+          code: dedent`
+            import { isNull } from 'ts-data-forge';
+            declare const x: unknown;
+            const a = isNull(x as string | null);
+            const b = isNull(x satisfies unknown);
+            const c = isNull(x!);
+          `,
+          output: dedent`
+            import { isNull } from 'ts-data-forge';
+            declare const x: unknown;
+            const a = (x as string | null) === null;
+            const b = (x satisfies unknown) === null;
+            const c = x! === null;
+          `,
+          errors: [
+            { messageId: 'preferComparison' },
+            { messageId: 'preferComparison' },
+            { messageId: 'preferComparison' },
+          ],
+        },
+        {
+          name: 'the guard itself reached through a wrapper',
+          code: dedent`
+            import { isNull } from 'ts-data-forge';
+            declare const x: string | null | undefined;
+            const a = (isNull as (u: unknown) => boolean)(x);
+          `,
+          output: dedent`
+            import { isNull } from 'ts-data-forge';
+            declare const x: string | null | undefined;
+            const a = x === null;
+          `,
+          errors: [{ messageId: 'preferComparison' }],
+        },
+        {
+          name: 'the namespace reached through a wrapper',
+          code: dedent`
+            import * as tf from 'ts-data-forge';
+            declare const x: string | null | undefined;
+            const b = (tf as typeof tf).isNotUndefined(x);
+          `,
+          output: dedent`
+            import * as tf from 'ts-data-forge';
+            declare const x: string | null | undefined;
+            const b = x !== undefined;
+          `,
+          errors: [{ messageId: 'preferComparison' }],
+        },
+      ],
+    },
+  );
+});
+
+describe('prefer-comparison-over-nullish-guard with parenthesized operands', () => {
+  tester.run(
+    'prefer-comparison-over-nullish-guard',
+    preferComparisonOverNullishGuard,
+    {
+      valid: [],
+      invalid: [
+        {
+          name: 'bitwise operators bind looser than `===`',
+          code: dedent`
+            import { isNull } from 'ts-data-forge';
+            declare const a: number;
+            declare const b: number;
+            const p = isNull(a | b);
+            const q = isNull(a ^ b);
+            const r = isNull((a & b));
+          `,
+          output: dedent`
+            import { isNull } from 'ts-data-forge';
+            declare const a: number;
+            declare const b: number;
+            const p = (a | b) === null;
+            const q = (a ^ b) === null;
+            const r = (a & b) === null;
+          `,
+          errors: [
+            { messageId: 'preferComparison' },
+            { messageId: 'preferComparison' },
+            { messageId: 'preferComparison' },
+          ],
+        },
+        {
+          name: 'an equality argument is parenthesized for readability',
+          code: dedent`
+            import { isNotUndefined } from 'ts-data-forge';
+            declare const a: unknown;
+            declare const b: unknown;
+            const p = isNotUndefined(a === b);
+          `,
+          output: dedent`
+            import { isNotUndefined } from 'ts-data-forge';
+            declare const a: unknown;
+            declare const b: unknown;
+            const p = (a === b) !== undefined;
+          `,
+          errors: [{ messageId: 'preferComparison' }],
+        },
+      ],
+    },
+  );
+});

package/src/rules/prefer-is-non-null-object.mts

@@ -3,7 +3,7 @@ import {
   type TSESLint,
   type TSESTree,
 } from '@typescript-eslint/utils';
-import { type DeepReadonly } from 'ts-type-forge';
+import { skipTypeWrappers } from './ast-utils.mjs';
 import {
   buildImportFixes,
   getNamedImports,
@@ -45,7 +45,9 @@ export const preferIsNonNullObject: TSESLint.RuleModule<MessageIds, Options> = {
       LogicalExpression: (node) => {
         const identifierName = getNonNullObjectIdentifierName(node);
 
-        if (identifierName === undefined) return;
+        if (identifierName === undefined) {
+          return;
+        }
 
         mut_nodesToFix.push({ node, identifierName });
       },
@@ -86,60 +88,82 @@ export const preferIsNonNullObject: TSESLint.RuleModule<MessageIds, Options> = {
   defaultOptions: [],
 } as const;
 
+/**
+ * The name of the value checked by `typeof u === 'object' && u !== null`, or
+ * `undefined`. Every operand is read through type wrappers:
+ * `(u satisfies unknown) !== null` and `u! !== null` check the same `u`.
+ */
 const getNonNullObjectIdentifierName = (
-  node: DeepReadonly<TSESTree.LogicalExpression>,
+  // AST nodes hold mutable child arrays, so they are not deeply readonly.
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.LogicalExpression,
 ): string | undefined => {
-  if (node.operator !== '&&') return undefined;
+  if (node.operator !== '&&') {
+    return undefined;
+  }
 
   const leftIdentifierName = getTypeofObjectIdentifierName(node.left);
 
   const rightIdentifierName = getNonNullCheckIdentifierName(node.right);
 
-  if (leftIdentifierName === undefined) return undefined;
-
-  if (rightIdentifierName === undefined) return undefined;
-
-  if (leftIdentifierName !== rightIdentifierName) return undefined;
-
-  return leftIdentifierName;
+  return leftIdentifierName === undefined ||
+    rightIdentifierName === undefined ||
+    leftIdentifierName !== rightIdentifierName
+    ? undefined
+    : leftIdentifierName;
 };
 
 const getTypeofObjectIdentifierName = (
-  node: DeepReadonly<TSESTree.Expression>,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.Expression,
 ): string | undefined => {
-  if (node.type !== AST_NODE_TYPES.BinaryExpression) return undefined;
+  if (node.type !== AST_NODE_TYPES.BinaryExpression) {
+    return undefined;
+  }
 
-  if (node.operator !== '===') return undefined;
+  if (node.operator !== '===') {
+    return undefined;
+  }
 
-  const { left, right } = node;
+  const left = skipTypeWrappers(node.left);
 
-  if (left.type !== AST_NODE_TYPES.UnaryExpression) return undefined;
+  const right = skipTypeWrappers(node.right);
 
-  if (left.operator !== 'typeof') return undefined;
+  if (
+    left.type !== AST_NODE_TYPES.UnaryExpression ||
+    left.operator !== 'typeof' ||
+    right.type !== AST_NODE_TYPES.Literal ||
+    right.value !== 'object'
+  ) {
+    return undefined;
+  }
 
-  if (right.type !== AST_NODE_TYPES.Literal) return undefined;
+  const argument = skipTypeWrappers(left.argument);
 
-  if (right.value !== 'object') return undefined;
-
-  if (left.argument.type !== AST_NODE_TYPES.Identifier) return undefined;
-
-  return left.argument.name;
+  return argument.type === AST_NODE_TYPES.Identifier
+    ? argument.name
+    : undefined;
 };
 
 const getNonNullCheckIdentifierName = (
-  node: DeepReadonly<TSESTree.Expression>,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.Expression,
 ): string | undefined => {
-  if (node.type !== AST_NODE_TYPES.BinaryExpression) return undefined;
-
-  if (node.operator !== '!==') return undefined;
-
-  const { left, right } = node;
+  if (node.type !== AST_NODE_TYPES.BinaryExpression) {
+    return undefined;
+  }
 
-  if (left.type !== AST_NODE_TYPES.Identifier) return undefined;
+  if (node.operator !== '!==') {
+    return undefined;
+  }
 
-  if (right.type !== AST_NODE_TYPES.Literal) return undefined;
+  const left = skipTypeWrappers(node.left);
 
-  if (right.value !== null) return undefined;
+  const right = skipTypeWrappers(node.right);
 
-  return left.name;
+  return left.type !== AST_NODE_TYPES.Identifier ||
+    right.type !== AST_NODE_TYPES.Literal ||
+    right.value !== null
+    ? undefined
+    : left.name;
 };

package/src/rules/prefer-is-non-null-object.test.mts

@@ -154,3 +154,45 @@ describe('prefer-is-non-null-object', () => {
     ],
   });
 }, 20000);
+
+describe('prefer-is-non-null-object through type wrappers', () => {
+  tester.run('prefer-is-non-null-object', preferIsNonNullObject, {
+    valid: [
+      {
+        name: 'checks on two different values, one wrapped',
+        code: dedent`
+          declare const u: unknown;
+          declare const v: unknown;
+          const ok = typeof u === 'object' && (v satisfies unknown) !== null;
+        `,
+      },
+    ],
+    invalid: [
+      {
+        name: 'the value wrapped on either side',
+        code: dedent`
+          import { isNonNullObject } from 'ts-data-forge';
+          declare const u: unknown;
+          const a = typeof u === 'object' && (u satisfies unknown) !== null;
+          const b = typeof u === 'object' && u! !== null;
+          const c = typeof (u satisfies unknown) === 'object' && u !== null;
+          const d = typeof u === ('object' as const) && u !== (null as null);
+        `,
+        output: dedent`
+          import { isNonNullObject } from 'ts-data-forge';
+          declare const u: unknown;
+          const a = isNonNullObject(u);
+          const b = isNonNullObject(u);
+          const c = isNonNullObject(u);
+          const d = isNonNullObject(u);
+        `,
+        errors: [
+          { messageId: 'useIsNonNullObject' },
+          { messageId: 'useIsNonNullObject' },
+          { messageId: 'useIsNonNullObject' },
+          { messageId: 'useIsNonNullObject' },
+        ],
+      },
+    ],
+  });
+}, 20000);

package/src/rules/prefer-is-record-and-has-key.mts

@@ -5,6 +5,7 @@ import {
 } from '@typescript-eslint/utils';
 import { Arr } from 'ts-data-forge';
 import * as ts from 'typescript';
+import { typeWrapperLayers } from './ast-utils.mjs';
 import {
   buildImportFixes,
   getNamedImports,
@@ -54,14 +55,20 @@ export const preferIsRecordAndHasKey: TSESLint.RuleModule<MessageIds, Options> =
         // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
         expression: TSESTree.Expression,
       ): boolean => {
-        if (checker === undefined) return false;
-
-        const tsNode = services?.esTreeNodeToTSNodeMap?.get(expression);
-
-        return (
-          tsNode !== undefined &&
-          isAlreadyRecordType(checker, checker.getTypeAtLocation(tsNode))
-        );
+        if (checker === undefined) {
+          return false;
+        }
+
+        // At every layer of type wrappers (see typeWrapperLayers): an array
+        // cast to `Record<string, unknown>` still needs its `isRecord`.
+        return typeWrapperLayers(expression).every((layer) => {
+          const tsNode = services?.esTreeNodeToTSNodeMap?.get(layer);
+
+          return (
+            tsNode !== undefined &&
+            isAlreadyRecordType(checker, checker.getTypeAtLocation(tsNode))
+          );
+        });
       };
 
       const mut_nodesToFix: {
@@ -84,13 +91,17 @@ export const preferIsRecordAndHasKey: TSESLint.RuleModule<MessageIds, Options> =
           }
 
           // Check arguments: Object.hasOwn(obj, key)
-          if (node.arguments.length !== 2) return;
+          if (node.arguments.length !== 2) {
+            return;
+          }
 
           const objArg = node.arguments[0];
 
           const keyArg = node.arguments[1];
 
-          if (objArg === undefined || keyArg === undefined) return;
+          if (objArg === undefined || keyArg === undefined) {
+            return;
+          }
 
           // Type guard: ensure arguments are Expressions (not SpreadElement)
           if (
@@ -109,14 +120,18 @@ export const preferIsRecordAndHasKey: TSESLint.RuleModule<MessageIds, Options> =
 
         // Handle key in obj
         BinaryExpression: (node) => {
-          if (node.operator !== 'in') return;
+          if (node.operator !== 'in') {
+            return;
+          }
 
           const keyExpression = node.left;
 
           const objExpression = node.right;
 
           // Type guard: ensure keyExpression is Expression (not PrivateIdentifier)
-          if (keyExpression.type === AST_NODE_TYPES.PrivateIdentifier) return;
+          if (keyExpression.type === AST_NODE_TYPES.PrivateIdentifier) {
+            return;
+          }
 
           mut_nodesToFix.push({
             node,

package/src/rules/prefer-is-record-and-has-key.test.mts

@@ -289,3 +289,37 @@ describe('prefer-is-record-and-has-key', () => {
     ],
   });
 }, 20000);
+
+describe('prefer-is-record-and-has-key through type wrappers', () => {
+  tester.run('prefer-is-record-and-has-key', preferIsRecordAndHasKey, {
+    valid: [],
+    invalid: [
+      {
+        name: 'keeps isRecord for an array cast to a record: the value is still an array',
+        code: dedent`
+          declare const arr: readonly string[];
+          const ok = Object.hasOwn(arr as unknown as Record<string, unknown>, '0');
+        `,
+        output: dedent`
+          import { isRecord, hasKey } from 'ts-data-forge';
+          declare const arr: readonly string[];
+          const ok = (isRecord(arr as unknown as Record<string, unknown>) && hasKey(arr as unknown as Record<string, unknown>, '0'));
+        `,
+        errors: [{ messageId: 'useIsRecordAndHasKey' }],
+      },
+      {
+        name: 'keeps isRecord for a record widened to include an array: the author says it may be one',
+        code: dedent`
+          declare const obj: Readonly<Record<string, unknown>>;
+          const ok = Object.hasOwn(obj as Readonly<Record<string, unknown>> | readonly unknown[], 'a');
+        `,
+        output: dedent`
+          import { isRecord, hasKey } from 'ts-data-forge';
+          declare const obj: Readonly<Record<string, unknown>>;
+          const ok = (isRecord(obj as Readonly<Record<string, unknown>> | readonly unknown[]) && hasKey(obj as Readonly<Record<string, unknown>> | readonly unknown[], 'a'));
+        `,
+        errors: [{ messageId: 'useIsRecordAndHasKey' }],
+      },
+    ],
+  });
+});