[RFC]: refactor @stdlib/complex into sub-namespaces

[kgryte]

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

• I have read and understood the Code of Conduct.
• Searched for existing issues and pull requests.
• The issue name begins with RFC:.

[Planeshifter]

This should be fine and seems sensible. We will need to ensure to deprecate the various packages already published to npm.

[kgryte]

@Planeshifter Sorry, I have already forgotten. Can our existing automation work with conventional commits? Or do we need to include additional meta information in the commit messages?

[Planeshifter]

@kgryte Currently, we have https://github.com/stdlib-js/metadata-action to process YAML blocks in commit messages, which could be used to build out a method to deprecate packages via the commit messages. We don't have any existing automation for deprecations where the conventional commit deprecate type would be used to then kick off automatic deprecations. I am also not convinced we really want that, though. Not an everyday occurrence and may be better to perform manually. We have the https://github.com/stdlib-js/stdlib/actions/workflows/deprecate_packages.yml workflow which can be manually invoked with a space separated list of packages to deprecate.

[kgryte]

List of deprecated packages:

• complex/reviver-float32
  • replacement: complex/float32/reviver
• complex/reviver-float64
  • replacement: complex/float64/reviver
• complex/parse-float32
  • replacement: complex/float32/parse
• complex/parse-float64
  • replacement: complex/float64/parse
• complex/base/assert/is-equal
  • replacement: complex/float64/base/assert/is-equal
• complex/base/assert/is-equalf
  • replacement: complex/float32/base/assert/is-equal
• complex/base/assert/is-not-equal
  • replacement: complex/float64/base/assert/is-not-equal
• complex/base/assert/is-not-equalf
  • replacement: complex/float32/base/assert/is-not-equal
• complex/base/assert/is-same-value
  • replacement: complex/float64/base/assert/is-same-value
• complex/base/assert/is-same-valuef
  • replacement: complex/float32/base/assert/is-same-value
• complex/base/assert/is-same-value-zero
  • replacement: complex/float64/base/assert/is-same-value-zero
• complex/base/assert/is-same-value-zerof
  • replacement: complex/float32/base/assert/is-same-value-zero
• complex/conjf
  • replacement: complex/float32/conj
• complex/conj
  • replacement: complex/float64/conj
• complex/reimf
  • replacement: complex/float32/reim
• complex/reim
  • replacement: complex/float64/reim
• complex/imagf
  • replacement: complex/float32/imag
• complex/imag
  • replacement: complex/float64/imag
• complex/realf
  • replacement: complex/float32/real
• complex/real
  • replacement: complex/float64/real