rspec/rules/S4322/javascript/rule.adoc

== Why is this an issue?

A type guard is a TypeScript feature that allows you to narrow the type of a variable within a conditional block of code. It is a way to tell the TypeScript compiler that an expression is of a certain type, based on some condition that you check at runtime.

[source,javascript]
----
function printLength(x: any) {
  if (typeof x === 'string') {
    console.log(x.length);
  }
}
----

Type predicates are user-defined functions that work as type guards, where you define yourself how to narrow the type of an expression based on some custom condition. These are just functions with a return type of ``++argumentName is SomeType++``. Such functions return ``++true++`` if the argument is of the specified type. 

[source,javascript]
----
function isString(x: any): x is string {
  return typeof x === 'string';
}

function printLength(x: any) {
  if (isString(x)) {
    console.log(x.length);
  }
}
----

One of the advantages of using such a function is that in a conditional block where the condition is a type guard, the compiler automatically performs the appropriate casts, so explicit casting becomes unnecessary.

Type predicates provide a more precise, readable, and flexible way to check types in your code, which can lead to more robust and maintainable code.

This rule raises an issue when a boolean function checking for the type of its only argument can be replaced with a type predicate.

[source,javascript,diff-id=1,diff-type=noncompliant]
----
function isSomething(x: BaseType): boolean { // Noncompliant
  return (<Something>x).foo !== undefined;
}

if (isSomething(v)) {
  (<Something>v).foo();
  (v as Something).foo();
}
----

Transform the function into a type predicate, adding a return type annotation that specifies the type predicate.

[source,javascript,diff-id=1,diff-type=compliant]
----
function isSomething(x: BaseType): x is Something {
  return (<Something>x).foo !== undefined;
}

if (isSomething(v)) {
  v.foo();
}
----


== Resources

=== Documentation

* https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates[TypeScript - Using type predicates]

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

Change this boolean return type into a type predicate


=== Highlighting

The function declaration


'''
== Comments And Links
(visible only on this page)

=== on 14 Nov 2017, 21:23:12 Ann Campbell wrote:
\[~jeanchristophe.collet] from this description I don't understand what type guards do, and from the examples, I have no idea how they work.

endif::env-github,rspecator-view[]