# subarray

**Repository Path**: nodets/subarray

## Basic Information

- **Project Name**: subarray
- **Description**: 为 JavaScript 数组添加与 TypedArray 行为一致的 subarray方法，支持 ESM、CommonJS 和 IIFE 多种模块格式。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-07
- **Last Updated**: 2025-10-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# subarray

为 JavaScript 数组添加与 TypedArray 行为一致的 `subarray` 方法，支持 ESM、CommonJS 和 IIFE 多种模块格式。

## 简介

`subarray` 包为普通 JavaScript 数组提供了与 TypedArray 相同的 `subarray` 方法实现。该方法返回原数组的一个子数组视图，修改子数组会影响原数组，反之亦然，完美模拟了 TypedArray 的内存共享特性。

## 特性

- 与 TypedArray.subarray 行为完全一致
- 支持负数索引（从数组末尾计算）
- 自动处理索引边界
- 当 end < begin 时自动交换索引
- 子数组与原数组双向同步修改
- 支持所有核心数组方法（push、pop、splice 等）
- 兼容 ESM、CommonJS 和浏览器全局变量

## 安装

```bash
npm install subarray
```

## 使用方法

### ESM (ECMAScript Modules)

```javascript
import 'subarray';

const arr = [1, 2, 3, 4, 5];
const sub = arr.subarray(1, 4);
```

### CommonJS

```javascript
require('subarray');

const arr = [1, 2, 3, 4, 5];
const sub = arr.subarray(1, 4);
```

### IIFE (浏览器直接使用)

通过 script 标签引入，会自动为 Array.prototype 添加 subarray 方法：

```html
<script src="node_modules/subarray/dist/subarray.iife.js"></script>
<script>
  const arr = [1, 2, 3, 4, 5];
  const sub = arr.subarray(1, 4);
</script>
```

## API

### Array.prototype.subarray(begin?: number, end?: number): Array

#### 参数

- `begin` (可选): 子数组的起始索引（包含），默认为 0。支持负数（从数组末尾计算）。
- `end` (可选): 子数组的结束索引（不包含），默认为数组长度。支持负数（从数组末尾计算）。

#### 返回值

返回一个新的数组对象，该对象是原数组的子数组视图。

## 示例

### 基本用法

```javascript
const original = [10, 20, 30, 40, 50];

// 获取索引 1 到 4 的子数组（不包含 4）
const sub1 = original.subarray(1, 4);
console.log(sub1); // [20, 30, 40]

// 从索引 2 到数组末尾
const sub2 = original.subarray(2);
console.log(sub2); // [30, 40, 50]

// 使用负数索引（从末尾计算）
const sub3 = original.subarray(-3, -1);
console.log(sub3); // [30, 40]

// 当 end < begin 时自动交换
const sub4 = original.subarray(3, 1);
console.log(sub4); // [20, 30]
```

### 双向同步修改

```javascript
const original = [10, 20, 30, 40, 50];
const sub = original.subarray(1, 4); // [20, 30, 40]

// 修改子数组会影响原数组
sub[0] = 200;
console.log(original); // [10, 200, 30, 40, 50]

// 修改原数组会影响子数组
original[2] = 300;
console.log(sub); // [200, 300, 40]

// 子数组上的方法操作会影响原数组
sub.push(60);
console.log(sub); // [200, 300, 40, 60]
console.log(original); // [10, 200, 300, 40, 60, 50]
```

### 支持数组方法

```javascript
const original = [10, 20, 30, 40, 50];
const sub = original.subarray(1, 4); // [20, 30, 40]

// 支持 splice
sub.splice(1, 1, 35);
console.log(sub); // [20, 35, 40]
console.log(original); // [10, 20, 35, 40, 50]

// 支持 forEach
sub.forEach((value, index) => {
  console.log(`[${index}]: ${value}`);
});

// 支持 map
const mapped = sub.map(value => value * 2);
console.log(mapped); // [40, 70, 80]
```

## 注意事项

- 该实现使用 Proxy 实现双向绑定，虽然性能良好，但在极高性能要求的场景下可能不如原生 TypedArray
- 不建议在需要严格保持数组纯净性的场景中使用
- 与 TypedArray 不同，这不是真正的内存共享，而是通过代理实现的同步修改

## 许可证

MIT