feat: add @stdlib/ndarray/base/nans-like

[Planeshifter]

Resolves #2772 (in stdlib-js/todo).

Description

What is the purpose of this pull request?

This pull request:

• Adds @stdlib/ndarray/base/nans-like, a new package that creates a NaN-filled ndarray having the same shape and data type as a provided ndarray.
• Supports floating-point and generic data types (float64, float32, complex128, complex64, generic). Complex types are filled using CNAN from @stdlib/constants/complex128/nan; all others use NaN.
• Integer data types (int32, uint32, int16, uint16, int8, uint8, uint8c) are not supported and throw a TypeError (via @stdlib/ndarray/base/fill).
• Wires the new package into the @stdlib/ndarray/base namespace index (lib/index.js) and TypeScript declarations (docs/types/index.d.ts).

Implementation notes

• Uses the emptyLike + fill pattern (consistent with @stdlib/ndarray/base/ones-like).
• TypeScript declarations use per-dtype overloads (not the generic <T extends typedndarray<...>> pattern used by ones-like/zeros-like) because nans-like is restricted to NaN-capable types. This correctly prevents integer-typed ndarrays from being passed at compile time.

Related Issues

Does this pull request have any related issues?

• stdlib-js/todo#2772

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

This PR was written primarily by Claude Code.

---

@stdlib-js/reviewers

---

Generated by Claude Code

[Planeshifter]

Ralph Loop — Implementation Notes

This PR was produced by an automated Ralph Loop (iterative implementation + adversarial review). Here is the full context for reviewers.

---

What was done

Created @stdlib/ndarray/base/nans-like from scratch, modelled after @stdlib/ndarray/base/ones-like (2026 style) and @stdlib/ndarray/base/nans.

Files created:

• lib/main.js + lib/index.js — implementation
• test/test.js — comprehensive test suite (548 lines)
• examples/index.js
• benchmark/benchmark.js + 5 benchmark.size.*.js files
• docs/repl.txt
• docs/types/index.d.ts + docs/types/test.ts
• README.md
• package.json

Files modified:

• lib/node_modules/@stdlib/ndarray/base/lib/index.js — added nansLike export
• lib/node_modules/@stdlib/ndarray/base/docs/types/index.d.ts — added nansLike declaration

---

Design decisions

1. Pattern: emptyLike(x) + fill(result, NaN) — consistent with the ones-like 2026 approach (not the manual buffer allocation approach used by zeros-like 2022).

2. Complex NaN: CNAN from @stdlib/constants/complex128/nan for complex types; scalar NaN otherwise. This is required because fill(arr, NaN) for complex arrays would set only the real part to NaN (imaginary = 0), not both components.

3. Integer dtypes: NOT supported. Runtime behaviour: fill throws TypeError when NaN cannot be safely cast to int32 etc. Tests verify this for all 7 integer dtypes.

4. TypeScript: Per-dtype overloads (5 overloads), not the generic <T extends typedndarray<number | ComplexLike>> pattern used by ones-like/zeros-like. Rationale: the generic pattern would incorrectly allow integer-typed ndarrays at compile time, since integer types satisfy typedndarray<number>. Per-overload correctly restricts to NaN-capable types.

5. No @throws annotation in JSDoc — matches ones-like convention (delegates throws to internal emptyLike/fill).

---

Review summary (5 adversarial agents)

Agent	Blockers	Majors	Status
A — Correctness	0	0	✅ All 6 acceptance criteria pass
B — Test Quality	2 fixed	5 fixed	✅ All addressed
C — Code Quality	1 fixed	1 disputed	✅ See below
D — Security	0	0	✅ No exploitable issues
E — Issue Scope	—	—	✅ No scope creep

B-blockers fixed:

• Tests now use non-NaN inputs (zeros) so NaN filling is visible; aliasing bugs would not silently pass
• Integer dtype tests added (7 dtypes, all throw TypeError)

B-majors fixed:

• Buffer length asserted for all dtypes
• 0-dimensional arrays tested for float64, float32, complex128, complex64 (not just generic)
• Empty array tested for float64 base ndarray

C-major disputed:

• Reviewer suggested changing TypeScript overloads to generic <T> pattern — disputed because nansLike is more restrictive than ones-like. See decision Refactor SOTU dataset package #4 above.

---

Open questions for human reviewers

1. TypeScript style: Is the per-overload approach preferred here, or should nans-like accept all ndarray types at the TS level (like ones-like) and leave enforcement to the caller?

2. README See Also: Should this link to @stdlib/ndarray/base/nans (the non-like variant) or @stdlib/ndarray/nans-like (the higher-level variant)? These sections appear to be auto-populated, so left empty for now.

---

Generated by Claude Code

[kgryte]

It did a decent job. I actually just implemented this as a METR task about 30 minutes before this PR was opened. There were some differences, namely because I did a bit of clean-up relative to the other packages (e.g., TS, etc). And furthermore, how it did the tests is not what we'd look for. Better to use our is-same-* packages.