The purpose of this page is for a more fluid envisioning and discussion of the file layout for a nanomath-based mathjs overhaul, as touched on in the README file and in issue #38.

We begin with a layout diagram showing the difference between the current actual (in roman type, bold where it coincides with the README and regular where it differs) and as described in the README (in italics, where it differs from the current actual):

src
├─ number
│ ├ NumberT
│ ├ arithmetic
│ ├ helpers
│ ├ logical
│ ├ relational
│ ├ type
│ └ utils
│
├─ generic
│ ├ arithmetic
│ ├ helpers
│ ├ logical
│ ├ relational
│ └ utils
│
├─ core ── (multiple implementation files, not specifically prescribed)
│
├─ boolean
│ ├ BooleanT
│ ├ logical
│ ├ relational
│ └ utils
│
├─ vector
│ ├ Vector
│ ├ arithmetic
│ ├ helpers
│ ├ logical
│ ├ relational
│ ├ type
│ └ utils
│
├─ coretypes (functions for Undefined and TypeOfTypes here)
│ ├ arithmetic
│ ├ relational
│ └ utils
│
├─ builtin
│ ├ scalar
│ │ ├ nullish (Undefined and Null would go here)
│ │ ├ boolean (directory would relocate here)
│ │ ├ bigint
│ │ └ string
│ │
│ └ collection
│ ├ array (would this be vector renamed, or different?
│ ├ object
│ └ (and possibly typedarray, set, and/or map)
├─ complex
│ ├ Complex
│ ├ arithmetic
│ ├ helpers
│ ├ relational
│ ├ type
│ └ utils
│
├─ Fraction ── (same collection of basic categories)
├─ (high-precision floating point, either BigNumber or a new library based on bigints) ── ...
├─ (non-builtin Matrix types, e.g. Sparse; may not need Dense?) ── ...
├─ Unit (if it is not just an add-on) ── ...
│
├─ algebra
│ ├ complex
│ ├ number
│ ├ bigint
│ ├ array
│ └ (other types that have algebra functions)
│
├─expression
│ ├ node
│ └ (other expression operations)
│
├─ bitwise ── (one subdirectory for each type)
├─ combinatorics ── ...
├─ geometry ── ...
├─ numeric ── ...
├─ probability ── ...
├─ signal ── ...
├─ special ── ...
├─ statistics ── ...
└─ trigonometric ── ...

So the questions are:

1. Do we want the more nested builtin/scalar - collection organization, or just leave each standard type at the top level?

2. If the former, where should TypeOfTypes go? (Currently it's in coretypes, but if Undefined moved to nullish then there wouldn't be much of anything left of coretypes, leaving TypeOfTypes a bit of an orphan.)

3. What array/matrix types do we want to end up with?

4. Do we just want to stick with BigNumber (i.e., Decimal.js) or switch to a more modern implementation of high-precision floating point based on bigints, and/or do we even want to try folding in "universal numbers" at this point (from the Android calculator project)?

5. Do we want all of the above to be in the "standard" math bundle, or do we want to split off any of the function categories (like numeric or probability or...) explicitly as add-ons, even if they are in the main source tree or as part of a compartmentalized monorepo? Similarly, do we want to split off any of the types (particularly Unit) as explicit add-ons?

6. Where should documentation go? In mathjs 15, with one file per operation, its very natural to have the documentation in the file for the corresponding operation (in fact more could/should be in that file). But here, the implementation of say cbrt is spread out throughout the different types, and we don't want to reiterate info in multiple places. Some schemes that come to mind:

   A. Have a parallel directory doc/ in addition to src/ laid out as similarly as possible, just with documentation files in place of code directories (and not have things spit by type of course).

   B. Put documentation alongside the number implementations, in their source files. Unfortunately, some functions (like determinant) may not have any number implementation.

   C. Consider doc as if it were a separate "type" and integrate documentation throughout this source tree just the way another basic type would be.

   D. Other possibilities?

7. Unit tests are currently interleaved in __tests__ directories? Can we keep that as opposed to the mathjs 15 organization? I find it easier to navigate. But where should end-to-end tests go?

OK, I think that's enough for now, but feel free to add more questions/answers as needed. Looking forward to moving this toward a mathjs overhaul!