# @lazy-node/windows-unsafe-filename

> Windows 不安全檔案名稱檢測模組 - 檢測和處理 Windows 系統中不安全的檔案名稱，支援保留字元和裝置名稱檢測

Latest version **1.0.16** (published 2026-03-02) · ISC license · 0 weekly downloads

## Install

```sh
npm install @lazy-node/windows-unsafe-filename
pnpm add @lazy-node/windows-unsafe-filename
yarn add @lazy-node/windows-unsafe-filename
bun add @lazy-node/windows-unsafe-filename
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.0.16 |
| Published | 2026-03-02 |
| First published | 2021-07-17 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 23.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | bluelovers |
| Maintainers | bluelovers |
| Keywords | create-by-yarn-tool, windows, unsafe, filename, reserved, illegal, device, con, prn, aux, nul, com, lpt, regex, regexp, security |

## Links

- npm: https://www.npmjs.com/package/@lazy-node/windows-unsafe-filename
- Repository: https://github.com/bluelovers/ws-iconv
- Homepage: https://github.com/bluelovers/ws-iconv/tree/master/packages/@lazy-node/windows-unsafe-filename#readme
- Issues: https://github.com/bluelovers/ws-iconv/issues
- npm.io page: https://npm.io/package/@lazy-node/windows-unsafe-filename

## Dependencies (1)

- [tslib](https://npm.io/package/tslib.md) ^2

## Alternatives

- [@fortawesome/react-fontawesome](https://npm.io/package/@fortawesome/react-fontawesome.md) — 2.2M weekly downloads
- [roboto-fontface](https://npm.io/package/roboto-fontface.md) — 196.0K weekly downloads
- [@react-native-vector-icons/common](https://npm.io/package/@react-native-vector-icons/common.md) — 150.4K weekly downloads
- [stockfish](https://npm.io/package/stockfish.md) — 27.0K weekly downloads
- [@procore/core-icons](https://npm.io/package/@procore/core-icons.md) — 4.6K weekly downloads

## Recent versions

- 1.0.16 (latest) — 2026-03-02
- 1.0.15 — 2026-03-01
- 1.0.13 — 2024-08-29
- 1.0.12 — 2022-10-02
- 1.0.11 — 2022-09-29
- 1.0.9 — 2022-09-28
- 1.0.8 — 2022-08-11
- 1.0.7 — 2022-05-11
- 1.0.5 — 2021-12-29
- 1.0.2 — 2021-08-13
- 1.0.1 — 2021-07-17

## README

# @lazy-node/windows-unsafe-filename - Windows 不安全檔案名稱檢測模組

這個模組提供了檢測和處理 Windows 系統中不安全檔案名稱的功能。Windows 系統有特定的保留字元和裝置名稱，不能用作檔案名稱。

## 主要功能

- 檢測 Windows 保留的裝置名稱
- 支援標準模式和擴展模式
- 提供正規表示式建立功能
- 支援字串替換功能
- 跨平台相容性

## 安裝

```bash
yarn add @lazy-node/windows-unsafe-filename
yarn-tool add @lazy-node/windows-unsafe-filename
yt add @lazy-node/windows-unsafe-filename
```

## 快速開始

```typescript
import { hasWindowsUnsafeName, replaceWindowsUnsafeName } from '@lazy-node/windows-unsafe-filename';

// 檢測不安全名稱
const isUnsafe = hasWindowsUnsafeName('con.txt');
console.log(isUnsafe); // 匹配結果陣列

// 替換不安全名稱
const safeName = replaceWindowsUnsafeName('con.txt', 'safe_name');
console.log(safeName); // 'safe_name.txt'
```

## API 文件

### 主要函數

#### newRegExpWindowsUnsafeName(mode?: boolean): RegExp
建立 Windows 不安全名稱的正規表示式。

**參數：**
- `mode` (boolean): 是否使用擴展模式（支援 com00-lpt99）

**返回值：**
- `RegExp`: 檢測 Windows 不安全名稱的正規表示式

**模式說明：**
- `false` (預設): 標準模式，支援 com0-lpt9
- `true`: 擴展模式，支援 com00-lpt99

#### hasWindowsUnsafeName(name: string, mode?: boolean): RegExpMatchArray | null
檢測字串是否包含 Windows 不安全名稱。

**參數：**
- `name` (string): 要檢測的字串
- `mode` (boolean): 是否使用擴展模式

**返回值：**
- `RegExpMatchArray | null`: 匹配結果，null 表示安全

#### replaceWindowsUnsafeName(name: string, replaceValue: string | ((substring: string, ...args: (string | undefined)[]) => string), mode?: boolean): string
替換 Windows 不安全名稱。

**參數：**
- `name` (string): 要處理的字串
- `replaceValue` (string | function): 替換值或回呼函數
- `mode` (boolean): 是否使用擴展模式

**返回值：**
- `string`: 處理後的字串

## 使用範例

### 基本檢測

```typescript
import { hasWindowsUnsafeName } from '@lazy-node/windows-unsafe-filename';

// 檢測常見的 Windows 保留名稱
const testNames = [
  'con.txt',
  'prn.doc',
  'aux.exe',
  'nul.bat',
  'com1.log',
  'lpt1.dat',
  'normal.txt'
];

testNames.forEach(name => {
  const result = hasWindowsUnsafeName(name);
  console.log(`${name}: ${result ? '不安全' : '安全'}`);
});

// 輸出：
// con.txt: 不安全
// prn.doc: 不安全
// aux.exe: 不安全
// nul.bat: 不安全
// com1.log: 不安全
// lpt1.dat: 不安全
// normal.txt: 安全
```

### 使用替換功能

```typescript
import { replaceWindowsUnsafeName } from '@lazy-node/windows-unsafe-filename';

// 使用字串替換
const unsafeName = 'con.txt';
const safeName = replaceWindowsUnsafeName(unsafeName, 'safe_name');
console.log(safeName); // 'safe_name.txt'

// 使用回呼函數替換
const unsafeName2 = 'com1.log';
const safeName2 = replaceWindowsUnsafeName(unsafeName2, (match, name, ext) => {
  return `device_${name}${ext || ''}`;
});
console.log(safeName2); // 'device_com1.log'
```

### 擴展模式使用

```typescript
import { hasWindowsUnsafeName, replaceWindowsUnsafeName } from '@lazy-node/windows-unsafe-filename';

// 標準模式（預設）
console.log(hasWindowsUnsafeName('com10.txt')); // null (安全)
console.log(hasWindowsUnsafeName('lpt20.txt')); // null (安全)

// 擴展模式
console.log(hasWindowsUnsafeName('com10.txt', true)); // 匹配結果 (不安全)
console.log(hasWindowsUnsafeName('lpt20.txt', true)); // 匹配結果 (不安全)

// 擴展模式替換
const result = replaceWindowsUnsafeName('com10.txt', 'safe', true);
console.log(result); // 'safe.txt'
```

### 實際應用場景

```typescript
import { hasWindowsUnsafeName, replaceWindowsUnsafeName } from '@lazy-node/windows-unsafe-filename';

// 安全的檔案名稱處理
function createSafeFilename(filename: string): string {
  if (hasWindowsUnsafeName(filename)) {
    return replaceWindowsUnsafeName(filename, (match, name, ext) => {
      return `safe_${name}${ext || ''}`;
    });
  }
  return filename;
}

// 批量處理檔案名稱
function processFilenames(filenames: string[]): string[] {
  return filenames.map(name => createSafeFilename(name));
}

// 使用範例
const unsafeFilenames = [
  'con.txt',
  'prn.doc',
  'com1.log',
  'normal.txt'
];

const safeFilenames = processFilenames(unsafeFilenames);
console.log(safeFilenames);
// ['safe_con.txt', 'safe_prn.doc', 'safe_com1.log', 'normal.txt']
```

### 與其他模組整合

```typescript
import { sanitizeFilename } from '@lazy-node/sanitize-filename';
import { replaceWindowsUnsafeName } from '@lazy-node/windows-unsafe-filename';

// 綜合檔案名稱安全化
function comprehensiveSanitize(filename: string): string {
  // 先處理 Windows 不安全名稱
  let safeName = replaceWindowsUnsafeName(filename, 'safe_device');
  
  // 再進行完整的檔案名稱安全化
  safeName = sanitizeFilename(safeName, {
    trim: true,
    replaceToFullWidth: true
  });
  
  return safeName;
}

// 使用範例
const unsafeInput = 'con?.txt';
const safeOutput = comprehensiveSanitize(unsafeInput);
console.log(safeOutput); // 'safe_device！.txt'
```

## Windows 保留名稱列表

### 標準模式支援的名稱
- `con` - 控制台
- `prn` - 印表機
- `aux` - 輔助設備
- `nul` - 空設備
- `com0` 到 `com9` - 通訊埠
- `lpt0` 到 `lpt9` - 並列埠

### 擴展模式額外支援的名稱
- `com00` 到 `com99` - 擴展通訊埠
- `lpt00` 到 `lpt99` - 擴展並列埠

## 注意事項

- 模組會自動忽略大小寫
- 支援帶有副檔名的檔案名稱
- 擴展模式提供更嚴格的檢查
- 可以與其他檔案名稱處理模組配合使用

## 貢獻

歡迎提交問題和拉取請求！

## 授權

ISC

---
_Source: https://npm.io/package/@lazy-node/windows-unsafe-filename · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._