Improve type safety for recursive objects

With the removal of the `{ [key: string]: any }` extension on the
`Filter<TSchema>` type, we find some serious new shortcomings on the
handling of Recursive types: they break type safety for some
non-recursive types!

Failing Example
===============

Consider the case in the tests with the following schema:
```
interface TypedDoc {
  name: string;
  age: number;
  listOfNumbers: number[];
  tag: {
    name: string;
  };
}
```

The way we were detecting recursion was to check if, for a given `Type
extends Object` and a `Key` in that object, if `Type extends Type[Key]`.

Note that in the `TypedDoc` interface there is no recursive structure,
but that `TypedDoc extends TypedDoc['tag']` is true, because the set of
keys in `TypedDoc` is a superset of the keys in `TypedDoc['tag']`.

This meant that, for this simple schema, the `tag.name` property was
considered to be within a recursion, and so was not getting properly
type checked in filtering.

Solution Explanation
====================

I've added a new generic type helper, `isInUnion<A,B>` that checks if
`A` is a union type that includes `B`. We start by using the `Extract`
utility to find the set of types in `A` that are assignable to `B`. If
the only overlapping entry is `B` itself, then either:
- `A` and `B` are the same type, or
- `A` is a union type that includes `B`.

Of course, testing equality of Types is also not trivial; there is some
discussion at microsoft/TypeScript#27024,
with a solution by [@mattmccutchen](https://github.com/mattmccutchen).

This should be enough to differentiate when we have recursive
structures, even when the recursive part is inside a union.

Downsides
=========

There are several test cases for recursive data structures that become
more cumbersome with the improved type checking. Where the earlier type
check would allow querying with deeply nested recursive values, the
stricter type checks now added would require that the query author
annotate the key with a `@ts-expect-error` directive to opt-out of the
type checker.

This is likely to be somewhat irksome for folks who commonly write these
types of queries, but I believe that this is preferable to the loss of
type safety that used to exist (as these were implicitly matching an
`any` value).

Follow Ups
==========

I suspect that it is possible to write a much simpler version of the
`NestedPaths` helper; for example, [@jcalz](https://github.com/jcalz)
offers a much tighter implementation in
https://stackoverflow.com/questions/58434389/typescript-deep-keyof-of-a-nested-object/58436959#58436959
that uses a maximum depth to allow traversing recursive data structures
up to a given limit. This kind of implementation would improve the type
safety of recursive data structures at the cost of limiting the depth of
query nodes. I'm not in a position to understand the common usage of the
library, so I'm leaving this alone for future contributors to consider.

Author: noahsilas

src/index.ts

@@ -284,6 +284,7 @@ export type {
   InferIdType,
   IntegerType,
   IsAny,
+  IsInUnion,
   Join,
   KeysOfAType,
   KeysOfOtherType,
@@ -306,6 +307,7 @@ export type {
   RootFilterOperators,
   SchemaMember,
   SetFields,
+  TypeEquals,
   UpdateFilter,
   WithId,
   WithoutId

src/mongo_types.ts

@@ -481,6 +481,24 @@ export type PropertyType<Type, Property extends string> = string extends Propert
     : unknown
   : unknown;
 
+/**
+ * Check if two types are exactly equal
+ *
+ * From https://github.com/microsoft/TypeScript/issues/27024#issuecomment-421529650,
+ * credit to https://github.com/mattmccutchen.
+ * @public
+ */
+// prettier-ignore
+export type TypeEquals<X, Y> =
+    (<T>() => T extends X ? 1 : 2) extends
+    (<T>() => T extends Y ? 1 : 2) ? true : false
+
+/**
+ * Check if A is a union type that includes B
+ * @public
+ */
+export type IsInUnion<A, B> = TypeEquals<Extract<A, B>, B>;
+
 /**
  * @public
  * returns tuple of strings (keys to be joined on '.') that represent every path into a schema
@@ -506,9 +524,7 @@ export type NestedPaths<Type> = Type extends
   ? {
       [Key in Extract<keyof Type, string>]: Type[Key] extends Type // type of value extends the parent
         ? [Key]
-        : // for a recursive union type, the child will never extend the parent type.
-        // but the parent will still extend the child
-        Type extends Type[Key]
+        : IsInUnion<Type[Key], Type> extends true
         ? [Key]
         : Type[Key] extends ReadonlyArray<infer ArrayType> // handling recursive types with arrays
         ? Type extends ArrayType // is the type of the parent the same as the type of the array?

test/types/community/collection/findX-recursive-types.test-d.ts

@@ -87,6 +87,7 @@ recursiveOptionalCollection.find({
  * recursive union types are supported
  */
 interface Node {
+  value?: string;
   next: Node | null;
 }
 
@@ -103,10 +104,12 @@ expectError(
 );
 
 nodeCollection.find({
-  'next.next': 'asdf'
+  'next.value': 'asdf'
 });
 
-nodeCollection.find({ 'next.next.next': 'yoohoo' });
+// type safety is lost through recursive relations; callers will
+// need to annotate queries with `ts-expect-error` comments
+expectError(nodeCollection.find({ 'next.next.value': 'yoohoo' }));
 
 /**
  * Recursive schemas with arrays are also supported
@@ -149,9 +152,11 @@ expectError(
 
 // type safety breaks after the first
 //   level of nested types
-recursiveSchemaWithArray.findOne({
-  'branches.0.directories.0.files.0.id': 'hello'
-});
+expectError(
+  recursiveSchemaWithArray.findOne({
+    'branches.0.directories.0.files.0.id': 'hello'
+  })
+);
 
 recursiveSchemaWithArray.findOne({
   branches: [