feat: add array/complex-factory

[udaykakade25]

Resolves none.

Description

What is the purpose of this pull request?

This pull request:

• Adds array/complex-factory package.

Related Issues

Does this pull request have any related issues?

This pull request has the following related issues:

• None

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

No.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• Read, understood, and followed the contributing guidelines.

AI Assistance

When authoring the changes proposed in this PR, did you use any kind of AI assistance?

• Yes
• [] No

If you answered "yes" above, how did you use AI assistance?

• Code generation (e.g., when writing an implementation or fixing a bug)
• Test/benchmark generation
• Documentation (including examples)
• Research and understanding

Disclosure

If you answered "yes" to using AI assistance, please provide a short disclosure indicating how you used AI assistance. This helps reviewers determine how much scrutiny to apply when reviewing your contribution. Example disclosures: "This PR was written primarily by Claude Code." or "I consulted ChatGPT to understand the codebase, but the proposed changes were fully authored manually by myself.".

I used Claude during my R&D by taking references from array/complex128, array/complex64, array/fix-endian-factory. Later used Claude to automate some of repetitive tasks in docs and benchmark files.

---

@stdlib-js/reviewers

[udaykakade25]

/stdlib update-copyright-years

[kgryte]

This alone is too weak a check. There is a reason why we check the constructor name in, e.g., array/complex128.

[kgryte]

The following is a general comment that is more intended for discussion rather than providing something actionable...

The factory approach does work and it will reduce bundle sizes as the implementation would now be centralized.

That said, the factory approach does suffer from one drawback, which is it doesn't allow for inheritance from a parent constructor (e.g., ComplexArray -> Complex128Array). This lack of inheritance means that brand checks are more expensive (i.e., for many operations, we don't care which type of complex typed array we were given; we just want a complex typed array). If we had a parent class, we could simply check x instanceof ComplexArray (i.e., is this value an instance of the parent class?). With the factory approach, we cannot do that, as each ComplexXXArray is a separate class with no common inheritance.

Furthermore, separate classes are treated as objects having different hidden shapes. This then results in JS optimizing compilers treating input arrays as distinct and thus leading the compiler to mark a function as polymorphic. This can degrade performance. This is also true of built-in arrays, so we are not an outlier here, but the factory approach does introduce a potential performance cliff.

I am not sure that a parent class approach is actually feasible, but I at least wanted to document that there are trade-offs associated with a factory approach.

[udaykakade25]

Hey Athan,
I have addressed all the ESLint errors and refactored main.js based on your earlier feedback:

1. Removed spellcheck.js changes to include realf and imagf (the change was unnecessary)
2. Fixed minor issues such as position of Section Header and eslint warnings
3. isComplexArrayConstructor and isComplexArray compares against constructor name thus fixing weak check
4. complex-factory now uses factory('dtype') similar to fixed-endian-factory`
5. Forgot to replace new ComplexArray( tmp ) with this.constructor (we discussed this in the office hours - now fixed

The package is finally ready for the final review.

Regarding discussion:
I see array/fixed-endian-factory and array/little-endian-factory uses Factory approach. While implementing array/float16 polyfill, i had to create all the packges however, with Complex Factory, array/complex32 requires no huge package but simple refactoring to get included in array/complex-factory. This heavily reduces code and bundle size.
With tradeoffs such as performance cliff issue and branch check that you mentioned, i would love to go deep and research on Parent Class Approach. Surely, we can do discussion and get direction on use and possibly implementation of this approach in complex typed array in the next office hours.

[stdlib-bot]

Coverage Report

No coverage information available.