stdlib-js / stdlib-js/stdlib

[RFC]: rename primitive array `assert` packages

未关闭
#14,283 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
Maintainers Needs Discussion release: Major RFC
主要语言
JavaScript
星标
6k
派生
1.3k
平均合并
1 天 3 小时
30 天内合并 PR
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:`.

贡献指南

打开贡献指南

调研方向

首先检查列出的 primitive-array 包名称,并在项目中搜索它们的使用位置。考虑提议的 *-of-* 约定、迁移工作量、对 JSDoc 的影响,以及在 npm 和 GitHub 上进行弃用。完成的标准是就命名方案达成一致,并确定由此产生的迁移范围。

由索引模型根据 Issue 内容生成。

评估

技术栈
javascript
领域
developer-experience, tooling
Issue 类型
功能
难度
5/5
预计耗时
一周以上
活跃度
活跃
描述清晰度
基本清楚
新手友好度
25/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。