[RFC]: add `ndarray/tensor3d/ctor`

[0PrashantYadav0]

Description

This RFC proposes adding @stdlib/ndarray/tensor3d/ctor, the three-dimensional counterpart to the existing @stdlib/ndarray/vector/ctor and @stdlib/ndarray/matrix/ctor packages, as the next step toward providing dedicated dimensional constructors up to five dimensions.

Motivation

As with ndarray/vector/* and ndarray/matrix/*, these APIs provide convenient dedicated interfaces for constructing arrays of a known dimensionality from nested arrays, together with the corresponding validation. For example,

var x = new Float64Tensor3D( [ [ [ 1, 2, 3 ], [ 4, 5, 6 ] ], [ [ 7, 8, 9 ], [ 10, 11, 12 ] ] ] );
// returns <ndarray>

Dimensional constructors up to 5D cover more than 80% of end-user use cases for ndarray dimensionality. Arrays of six or more dimensions are markedly less common and are adequately served by the general-purpose @stdlib/ndarray/ctor and @stdlib/ndarray/array APIs.

Supported options (readonly, mode, submode, order) and their defaults are unchanged from matrix/ctor.

Future plan

This RFC covers tensor3d/ctor and the typed constructors. The sequence:

1. The parent @stdlib/ndarray/tensor3d namespace package — handled separately by a maintainer. Not done here.
2. Typed 3D constructors — done. The complete set matching vector: bool (BooleanTensor3D), complex64, complex128, float32, float64, int8, int16, int32, uint8, uint8c (Uint8ClampedTensor3D), uint16, uint32. Each is a thin wrapper over require( '@stdlib/ndarray/tensor3d/ctor' ).factory( dtype ) accompanied by documentation, types, tests, and benchmarks.
3. ndarray/tensor4d — constructor plus typed packages, using @stdlib/array/base/flatten4d.
4. ndarray/tensor5d — constructor plus typed packages, using @stdlib/array/base/flatten5d, completing coverage through five dimensions.

Constructor names follow the vector convention rather than a literal data type transliteration: bool exports BooleanTensor3D and uint8c exports Uint8ClampedTensor3D. Package descriptions use the repository's dominant phrasing for integer types ("signed 32-bit integer", used by 39 packages) rather than the inverted form used by matrix/int32 and two others.

Related Issues

None.

Questions

No.

Three questions were raised while drafting and have since been resolved by a maintainer:

1. Should the thin parent @stdlib/ndarray/tensor3d namespace package land together with tensor3d/ctor? — No. It will be handled separately by a maintainer.
2. Should the typed constructors mirror the matrix set or the broader vector set? — The full set, matching vector. Work is already in progress to bring the matrix namespace up to the complete set.
3. Should the from_arraybuffer.js TODO be tackled as part of this work? — No. Work on @stdlib/ndarray/from-arraybuffer is already in progress separately; copying the helper is acceptable for now.

Other

No.

Checklist

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