[RFC]: refactor `@stdlib/complex` into sub-namespaces
- Dominant language
- JavaScript
- Stars
- 6k
- Forks
- 1.3k
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 611
Description
### Description
This RFC proposes refactoring the `@stdlib/complex` namespace into separate sub-namespaces for `float32` and `float64`.
Currently, the `@stdlib/complex` is a flat(ish) namespace, containing top-level packages which are tailored to specific data types.
```
$ make list-pkgs-tree LIST_PKGS_TREE_DIR="$PWD/lib/node_modules/@stdlib/complex"
@stdlib
└── complex
├── base
│ ├── assert
│ │ ├── is-equal
│ │ ├── is-equalf
│ │ ├── is-not-equal
│ │ ├── is-not-equalf
│ │ ├── is-same-value-zero
│ │ ├── is-same-value-zerof
│ │ ├── is-same-value
│ │ └── is-same-valuef
│ ├── cast-return
│ ├── parse
│ └── wrap-function
├── cmplx
├── conj
├── conjf
├── ctors
├── dtype
├── dtypes
├── float32
├── float64
├── imag
├── imagf
├── parse-float32
├── parse-float64
├── promotion-rules
├── real
├── realf
├── reim
├── reimf
├── reviver-float32
├── reviver-float64
└── reviver
```
For example, for double-precision complex floating-point numbers, we have
- `@stdlib/complex/conj`
- `@stdlib/complex/float64`
- `@stdlib/complex/imag`
- `@stdlib/complex/parse-float64`
- `@stdlib/complex/real`
- `@stdlib/complex/reim`
- `@stdlib/complex/reviver-float64`
Similarly, we have equivalent packages for single-precision complex floating-point numbers.
Accordingly, in order to distinguish double- and single-precision variants, we resort to suffixes (e.g., `*f` or `-floatXX`). This has worked fine and mirrors `@stdlib/math/base/special/*`.
However, this structure departs from the structure of `@stdlib/number/*`, where number dtypes and their associated functionality is broken down into sub-namespaces. This has the advantage in that we can avoid suffix name pollution and have similarly named packages across each of the different numeric data types. This will be especially useful when we add base operations (e.g., `@stdlib/number/int32/base/add`), where for many numeric dtypes (e.g., `int8`, `uint8`, etc), we don't have suffix conventions (i.e., we have no `int8` equivalent of `f` and are unlikely to ever have such an equivalent).
Accordingly, what this RFC proposes is a refactoring of the `@stdlib/complex/*` namespace to match the `@stdlib/number/*` namespace. E.g.,
- `@stdlib/complex/float64/ctor`
- `@stdlib/complex/float64/real`
- `@stdlib/complex/float64/imag`
- `@stdlib/complex/float64/add`
- ...
- `@stdlib/complex/float32/ctor`
- `@stdlib/complex/float32/real` (no suffix!)
- `@stdlib/complex/float32/imag` (no suffix!)
- `@stdlib/complex/float32/add` (no suffix!)
- ...
- `@stdlib/complex/ctors`
- `@stdlib/complex/cmplx`
- `@stdlib/complex/reviver`
- ...
where we keep the APIs which operate on or return either complex dtype at the top-level.
A consequence of this refactoring is that it should help make things a bit cleaner in the top-level `@stdlib/complex` namespace when adding support for half-precision complex floating-point numbers (as needed based on future inclusion of `Float16Array` in ECMAScript) and allow us to avoid needing to use a new suffix to differentiate the associated APIs.
As it is, that `@stdlib/number` and `@stdlib/complex` are organized differently has been a source of friction for me and having organizational parity seems more intuitive.
### Related Issues
No.
### Questions
No.
### Other
The migration path would be as follows:
1. Rename `@stdlib/complex/float32` and `@stdlib/complex/float64` to `@stdlib/complex/float32/ctor` and `@stdlib/complex/float64/ctor`, respectively.
2. Update all `require` paths using those packages.
3. Copy dtype-specific complex packages to their respective sub-namespaces.
4. Update all `require` paths using the dtype-specific complex packages.
5. Remove all dtype-specific complex packages from the top-level `@stdlib/complex` namespace.
cc @Planeshifter
### Checklist
- [X] I have read and understood the [Code of Conduct](https://github.com/stdlib-js/stdlib/blob/develop/CODE_OF_CONDUCT.md).
- [X] Searched for existing issues and pull requests.
- [X] The issue name begins with `RFC:`.
Contributor guide
Assessment
This issue has not been assessed yet.