stdlib-js / stdlib-js/stdlib

[RFC]: rename primitive array `assert` packages

オープン
#14,283 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る
Maintainers Needs Discussion release: Major RFC
主要言語
JavaScript
スター
6k
フォーク
1.3k
平均マージ
1日 3時間
マージ済み PR(30日)
611

説明

### Description

This RFC proposes renaming the following packages:

- [ ] `is-array-array` => `is-array-of-arrays`

- alias: `isArrayArray` => `isArrayOfArrays`

- [ ] `is-boolean-array` => `is-array-of-booleans`

- alias: `isBooleanArray` => `isArrayOfBooleans`

- [ ] `is-date-object-array` => `is-array-of-date-objects`

- alias: `isDataObjectArray` => `isArrayOfDateObjects`

- [ ] `is-function-array` => `is-array-of-functions`

- alias: `isFunctionArray` => `isArrayOfFunctions`

- [ ] `is-integer-array` => `is-array-of-integers`

- alias: `isIntegerArray` => `isArrayOfIntegers`

- [ ] `is-nan-array` => `is-array-of-nans`

- alias: `isNaNArray` => `isArrayOfNaNs`

- [ ] `is-negative-integer-array` => `is-array-of-negative-integers`

- alias: `isNegativeIntegerArray` => `isArrayOfNegativeIntegers`

- [ ] `is-negative-number-array` => `is-array-of-negative-numbers`

- alias: `isNegativeNumberArray` => `isArrayOfNegativeNumbers`

- [ ] `is-nonnegative-integer-array` => `is-array-of-nonnegative-integers`

- alias: `isNonNegativeIntegerArray` => `isArrayOfNonNegativeIntegers`

- [ ] `is-nonnegative-number-array` => `is-array-of-nonnegative-numbers`

- alias: `isNonNegativeNumberArray` => `isArrayOfNonNegativeNumbers`

- [ ] `is-nonpositive-integer-array` => `is-array-of-nonpositive-integers`

- alias: `isNonPositiveIntegerArray` => `isArrayOfNonPositiveIntegers`

- [ ] `is-nonpositive-number-array` => `is-array-of-nonpositive-numbers`

- alias: `isNonPositiveNumberArray` => `isArrayOfNonPositiveNumbers`

- [ ] `is-null-array` => `is-array-of-nulls`

- alias: `isNullArray` => `isArrayOfNulls`

- [ ] `is-object-array` => `is-array-of-objects`

- alias: `isObjectArray` => `isArrayOfObjects`

- [ ] `is-plain-object-array` => `is-array-of-plain-objects`

- alias: `isPlainObjectArray` => `isArrayOfPlainObjects`

- [ ] `is-positive-integer-array` => `is-array-of-positive-integers`

- alias: `isPositiveIntegerArray` => `isArrayOfPositiveIntegers`

- [ ] `is-positive-number-array` => `is-array-of-positive-numbers`

- alias: `isPositiveNumberArray` => `isArrayOfPositiveNumbers`

- [ ] `is-primitive-array` => `is-array-of-primitives`

- alias: `isPrimitiveArray` => `isArrayOfPrimitives`

- [ ] `is-probability-array` => `is-array-of-probabilities`

- alias: `isProbabilityArray` => `isArrayOfProbabilities`

- [ ] `is-safe-integer-array` => `is-array-of-safe-integers`

- alias: `isSafeIntegerArray` => `isArrayOfSafeIntegers`

- [ ] `is-string-array` => `is-array-of-strings`

- alias: `isStringArray` => `isArrayOfStrings`

- [ ] `is-symbol-array` => `is-array-of-symbols`

- alias: `isSymbolArray` => `isArrayOfSymbols`

### Rationale

As the project has grown and started accumulating custom array types (e.g., `BooleanArray`, `Complex128Array`, `Int64Array`, etc), older naming conventions are beginning to conflict with continued project evolution.

The most immediate example is `is-booleanarray` and `is-boolean-array`. Which is the assertion package for `BooleanArray` and which is for an array of booleans (e.g., `[ true, false, true ]`)? It is not obvious which is which and can be a point of confusion.

This RFC proposes migrating existing packages which refer explicitly to the contents of a collection and not to a particular instance type to a new naming convention which more explicitly indicates what the package is intended to test for and should avoid conflicts with any future array types (e.g., `StringArray`, `ObjectArray`, etc).

### Notes

Packages which are not included in the proposed migration:

- `is-between-array`
- `is-falsy-array`
- `is-finite-array`
- `is-truthy-array`
- `is-unity-probability-array`

These packages were considered to be (a) highly unlikely to conflict with future specialized array constructors and (b) not have good readability with the proposed naming convention (e.g., `isArrayOfBetween`).

### Related Issues

N/A

### Questions

1. The proposed changes will create quite a bit of churn throughout the project as many of these packages are heavily used. The question is then whether the churn is worth it. In my opinion, it is, but others may have different opinions.

2. Is there a better naming convention than the `*-of-*` proposal above?

3. JSDoc conventions are intentionally left out (e.g., `@param {NonNegativeIntegerArray}`). IMO, these also need to be migrated in order to avoid confusion with class instances, but I think this is something which can be addressed in a separate RFC, as it is not clear what the naming convention should be (e.g., `Array`, `Array`, something else?).

### Other

cc @Planeshifter as we previously discussed the confusion between `is-boolean-array` and `is-booleanarray`. This is my attempt to resolve that confusion.

Should this RFC be accepted and completed, we'll want to deprecate the existing packages and have them point to the new packages on both npm and GitHub.

### Checklist

- [x] I have read and understood the [Code of Conduct](https://github.com/stdlib-js/stdlib/blob/develop/CODE_OF_CONDUCT.md).
- [x] Searched for existing issues and pull requests.
- [x] The issue name begins with `RFC:`.

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

Start by reviewing the listed primitive-array package names and searching the project for their uses. Consider the proposed *-of-* convention, the migration churn, JSDoc implications, and deprecation on npm and GitHub. Done means the naming approach is agreed and the resulting migration scope is defined.

索引モデルが issue の本文から書いたものです。

評価

技術スタック
javascript
領域
developer-experience, tooling
issue の種類
機能追加
難易度
5/5
見積もり時間
1週間以上
活発さ
活発
明瞭さ
おおむね明確
初心者へのやさしさ
25/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。