Add type hints to public APIs

Hello,

I'd like to propose a feature - to add type hints to public functions.

The most basic version of this would be to type hint return types in terms of `TypeVar` of input types, like:
```python
S = TypeVar("S") # type of a structure
def map_structure(func, *structures: S, **kwargs) -> S:
...
```

This could be taken further by making structure generic over it's item types, allowing to type hint functions like `flatten`:
```python
Item = TypeVar("Item")
Node = Union["Structure[Item]", Item]

Structure = Union[
Node,
Sequence['Node'],
Mapping[Any, 'Node'],
'AnyNamedTuple',
]

def flatten(structure: Structure[Item]) -> list[Item]:
...
```

Overall, this should help users avoid preventable bugs and have more readable code. Thanks for considering :)