feat: enhance file system API with new features and improvements, including Date object support for timestamps, updated README, and additional tests for access and stat functions

Author: CoderSerio

.gitignore

@@ -132,3 +132,6 @@ Cargo.lock
 
 # vibe coding 🤓
 .cursor/
+
+# 本地开发备忘，不进入版本控制
+TODO.md

CONTRIBUTING.md

@@ -76,6 +76,7 @@ hyper-fs/
 │   ├── stat.rs             # stat / lstat
 │   ├── read_file.rs        # readFile / readFileSync
 │   ├── write_file.rs       # writeFile / appendFile
+│   ├── cp.rs               # cp / cpSync（递归复制，支持并发）
 │   └── ...                 # 每个 API 一个文件
 ├── __test__/               # 测试文件（TypeScript, AVA 框架）
 │   ├── readdir.spec.ts
@@ -91,7 +92,8 @@ hyper-fs/
 │   ├── copy_file.ts        # copyFile 性能对比
 │   ├── exists.ts           # exists / access 性能对比
 │   ├── mkdir.ts            # mkdir 性能对比
-│   └── rm.ts               # rm 性能对比（含并发）
+│   ├── rm.ts               # rm 性能对比（含并发）
+│   └── cp.ts               # cp 性能对比（含并发，树形/平铺目录）
 ├── reference/              # Node.js fs 模块源码参考
 │   ├── fs.js               # Node.js 主 fs 模块
 │   └── internal/fs/        # Node.js 内部实现

Cargo.toml

@@ -9,9 +9,10 @@ version = "0.1.0"
 crate-type = ["cdylib"]
 
 [dependencies]
+chrono         = { version = "0.4", features = ["clock"] }
 ignore         = "0.4.25"
 jwalk          = "0.8.1"
-napi           = "3.0.0"
+napi           = { version = "3.0.0", features = ["chrono_date"] }
 napi-derive    = "3.4"
 rayon          = "1.11.0"
 remove_dir_all = "1.0.0"

README.md

@@ -35,7 +35,7 @@ We are rewriting `fs` APIs one by one.
   ```ts
   path: string; // ✅
   options?: {
-    encoding?: string; // ❌
+    encoding?: string; // 🚧 ('utf8' default; 'buffer' not supported)
     withFileTypes?: boolean; // ✅
     recursive?: boolean; // ✅
     concurrency?: number; // ✨
@@ -154,7 +154,11 @@ We are rewriting `fs` APIs one by one.
   ```ts
   path: string // ✅
   ```
-- **Return Type**: `Stats` (dev, mode, nlink, uid, gid, rdev, blksize, ino, size, blocks, atimeMs, mtimeMs, ctimeMs, birthtimeMs + isFile/isDirectory/isSymbolicLink/...)
+- **Return Type**: `Stats`
+  - Numeric fields: `dev`, `mode`, `nlink`, `uid`, `gid`, `rdev`, `blksize`, `ino`, `size`, `blocks`, `atimeMs`, `mtimeMs`, `ctimeMs`, `birthtimeMs`
+  - **Date fields**: `atime`, `mtime`, `ctime`, `birthtime` → `Date` objects ✅
+  - Methods: `isFile()`, `isDirectory()`, `isSymbolicLink()`, ...
+- **Error distinction**: `ENOENT` vs `EACCES` ✅
 
 ### `lstat`
 
@@ -281,6 +285,7 @@ We are rewriting `fs` APIs one by one.
   ```ts
   target: string // ✅
   path: string // ✅
+  type?: 'file' | 'dir' | 'junction' // ✅ (Windows only, ignored on Unix)
   ```
 
 ### `link`
@@ -298,6 +303,7 @@ We are rewriting `fs` APIs one by one.
   prefix: string // ✅
   ```
 - **Return Type**: `string`
+- Uses OS-level random source (`/dev/urandom` on Unix, `BCryptGenRandom` on Windows) with up to 10 retries ✅
 
 ### `watch`
 

README.zh-CN.md

@@ -37,7 +37,7 @@ pnpm add hyper-fs
   ```ts
   path: string; // ✅
   options?: {
-    encoding?: string; // ❌
+    encoding?: string; // 🚧（默认 'utf8'；'buffer' 暂不支持）
     withFileTypes?: boolean; // ✅
     recursive?: boolean; // ✅
     concurrency?: number; // ✨
@@ -156,7 +156,11 @@ pnpm add hyper-fs
   ```ts
   path: string // ✅
   ```
-- **返回类型**：`Stats`（dev, mode, nlink, uid, gid, rdev, blksize, ino, size, blocks, atimeMs, mtimeMs, ctimeMs, birthtimeMs + isFile/isDirectory/isSymbolicLink/...）
+- **返回类型**：`Stats`
+  - 数值字段：`dev`, `mode`, `nlink`, `uid`, `gid`, `rdev`, `blksize`, `ino`, `size`, `blocks`, `atimeMs`, `mtimeMs`, `ctimeMs`, `birthtimeMs`
+  - **Date 字段**：`atime`, `mtime`, `ctime`, `birthtime` → `Date` 对象 ✅
+  - 方法：`isFile()`, `isDirectory()`, `isSymbolicLink()`, ...
+- **错误区分**：`ENOENT` vs `EACCES` ✅
 
 ### `lstat`
 
@@ -283,6 +287,7 @@ pnpm add hyper-fs
   ```ts
   target: string // ✅
   path: string // ✅
+  type?: 'file' | 'dir' | 'junction' // ✅（仅 Windows 有效，Unix 忽略）
   ```
 
 ### `link`
@@ -300,6 +305,7 @@ pnpm add hyper-fs
   prefix: string // ✅
   ```
 - **返回类型**：`string`
+- 使用系统随机源（Unix: `/dev/urandom`，Windows: `BCryptGenRandom`），最多重试 10 次 ✅
 
 ### `watch`
 

__test__/access.spec.ts

@@ -1,10 +1,21 @@
 import test from 'ava'
 import * as nodeFs from 'node:fs'
 import { accessSync, access } from '../index.js'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
 
 const F_OK = 0
 const R_OK = 4
 const W_OK = 2
+const X_OK = 1
+
+function tmpFile(name: string): string {
+  const dir = join(tmpdir(), `hyper-fs-test-access-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+  nodeFs.mkdirSync(dir, { recursive: true })
+  const file = join(dir, name)
+  nodeFs.writeFileSync(file, 'test')
+  return file
+}
 
 test('accessSync: should succeed for existing file (F_OK)', (t) => {
   t.notThrows(() => accessSync('./package.json'))
@@ -72,3 +83,36 @@ test('dual-run: accessSync should both throw for non-existent file', (t) => {
 
   t.is(hyperThrew, nodeThrew)
 })
+
+test('accessSync: X_OK should succeed for executable file', (t) => {
+  if (process.platform === 'win32') {
+    t.pass('Skipping X_OK test on Windows')
+    return
+  }
+  const file = tmpFile('exec.sh')
+  nodeFs.chmodSync(file, 0o755)
+  t.notThrows(() => accessSync(file, X_OK))
+})
+
+test('accessSync: should throw ENOENT (not EACCES) for missing file', (t) => {
+  const target = '/tmp/no-such-file-access-' + Date.now()
+  t.throws(() => accessSync(target), { message: /ENOENT/ })
+})
+
+test('dual-run: accessSync ENOENT error message starts with ENOENT like node:fs', (t) => {
+  const target = '/tmp/no-such-file-access-dual-' + Date.now()
+  let nodeMsg = ''
+  let hyperMsg = ''
+  try {
+    nodeFs.accessSync(target)
+  } catch (e) {
+    nodeMsg = (e as Error).message
+  }
+  try {
+    accessSync(target)
+  } catch (e) {
+    hyperMsg = (e as Error).message
+  }
+  t.true(nodeMsg.startsWith('ENOENT'))
+  t.true(hyperMsg.startsWith('ENOENT'))
+})

__test__/read_file.spec.ts

@@ -35,3 +35,16 @@ test('readFile: async should read file', async (t) => {
 test('readFile: async should throw on non-existent file', async (t) => {
   await t.throwsAsync(async () => await readFile('./no-such-file'), { message: /ENOENT/ })
 })
+
+test('dual-run: readFileSync Buffer should match node:fs byte-for-byte', (t) => {
+  const nodeResult = nodeFs.readFileSync('./package.json')
+  const hyperResult = readFileSync('./package.json') as Buffer
+  t.true(Buffer.isBuffer(hyperResult))
+  t.deepEqual(hyperResult, nodeResult)
+})
+
+test('dual-run: readFileSync utf8 string should match node:fs', (t) => {
+  const nodeResult = nodeFs.readFileSync('./package.json', 'utf8')
+  const hyperResult = readFileSync('./package.json', { encoding: 'utf8' }) as string
+  t.is(hyperResult, nodeResult)
+})

__test__/realpath.spec.ts

@@ -2,6 +2,14 @@ import test from 'ava'
 import { realpathSync, realpath } from '../index.js'
 import * as nodeFs from 'node:fs'
 import * as path from 'node:path'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+
+function tmpDir(): string {
+  const dir = join(tmpdir(), `hyper-fs-test-realpath-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+  nodeFs.mkdirSync(dir, { recursive: true })
+  return dir
+}
 
 test('realpathSync: should resolve to absolute path', (t) => {
   const result = realpathSync('.')
@@ -26,3 +34,37 @@ test('realpath: async should resolve path', async (t) => {
 test('realpath: async should throw on non-existent path', async (t) => {
   await t.throwsAsync(async () => await realpath('./no-such-path'), { message: /ENOENT/ })
 })
+
+test('dual-run: realpathSync should resolve symlink to real path', (t) => {
+  const dir = tmpDir()
+  const target = join(dir, 'real-target.txt')
+  const link = join(dir, 'link.txt')
+  nodeFs.writeFileSync(target, 'hello')
+  nodeFs.symlinkSync(target, link)
+
+  const nodeResult = nodeFs.realpathSync(link)
+  const hyperResult = realpathSync(link)
+  // Compare against node:fs (not raw `target`): on macOS /tmp is a symlink to /private/tmp,
+  // so realpath resolves through it.
+  t.is(hyperResult, nodeResult)
+  // The resolved path should end with the target filename
+  t.true(hyperResult.endsWith('real-target.txt'))
+})
+
+test('dual-run: realpathSync should resolve relative path same as node:fs', (t) => {
+  const nodeResult = nodeFs.realpathSync('src')
+  const hyperResult = realpathSync('src')
+  t.is(hyperResult, nodeResult)
+})
+
+test('realpath: async dual-run should resolve symlink same as node:fs', async (t) => {
+  const dir = tmpDir()
+  const target = join(dir, 'async-target.txt')
+  const link = join(dir, 'async-link.txt')
+  nodeFs.writeFileSync(target, 'hello')
+  nodeFs.symlinkSync(target, link)
+
+  const nodeResult = nodeFs.realpathSync(link)
+  const hyperResult = await realpath(link)
+  t.is(hyperResult, nodeResult)
+})

__test__/stat.spec.ts

@@ -1,6 +1,14 @@
 import test from 'ava'
 import { statSync, stat, lstatSync, lstat } from '../index.js'
 import * as nodeFs from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+
+function tmpDir(): string {
+  const dir = join(tmpdir(), `hyper-fs-test-stat-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+  nodeFs.mkdirSync(dir, { recursive: true })
+  return dir
+}
 
 test('statSync: should return stats for a file', (t) => {
   const s = statSync('./package.json')
@@ -62,3 +70,55 @@ test('statSync: atimeMs/mtimeMs/ctimeMs/birthtimeMs should be numbers', (t) => {
   t.is(typeof s.birthtimeMs, 'number')
   t.true(s.mtimeMs > 0)
 })
+
+test('statSync: atime/mtime/ctime/birthtime should be Date objects', (t) => {
+  const s = statSync('./package.json')
+  t.true(s.atime instanceof Date)
+  t.true(s.mtime instanceof Date)
+  t.true(s.ctime instanceof Date)
+  t.true(s.birthtime instanceof Date)
+  t.true(s.mtime.getTime() > 0)
+})
+
+test('statSync: atime.getTime() should be close to atimeMs', (t) => {
+  const s = statSync('./package.json')
+  t.true(Math.abs(s.atime.getTime() - s.atimeMs) < 1000)
+})
+
+test('statSync: should match node:fs atime/mtime Date values', (t) => {
+  const nodeStat = nodeFs.statSync('./package.json')
+  const hyperStat = statSync('./package.json')
+  t.is(hyperStat.mtime.getTime(), nodeStat.mtime.getTime())
+})
+
+test('lstatSync: dual-run — symlink should report isSymbolicLink()', (t) => {
+  const dir = tmpDir()
+  const target = join(dir, 'target.txt')
+  const link = join(dir, 'link.txt')
+  nodeFs.writeFileSync(target, 'hello')
+  nodeFs.symlinkSync(target, link)
+
+  const nodeLstat = nodeFs.lstatSync(link)
+  const hyperLstat = lstatSync(link)
+
+  t.is(hyperLstat.isSymbolicLink(), nodeLstat.isSymbolicLink())
+  t.true(hyperLstat.isSymbolicLink())
+  t.is(hyperLstat.isFile(), nodeLstat.isFile())
+  t.false(hyperLstat.isFile())
+})
+
+test('statSync: dual-run — stat follows symlink (shows target not link)', (t) => {
+  const dir = tmpDir()
+  const target = join(dir, 'target.txt')
+  const link = join(dir, 'link.txt')
+  nodeFs.writeFileSync(target, 'hello')
+  nodeFs.symlinkSync(target, link)
+
+  const nodeStat = nodeFs.statSync(link)
+  const hyperStat = statSync(link)
+
+  t.is(hyperStat.isFile(), nodeStat.isFile())
+  t.true(hyperStat.isFile())
+  t.is(hyperStat.isSymbolicLink(), nodeStat.isSymbolicLink())
+  t.false(hyperStat.isSymbolicLink())
+})

__test__/symlink.spec.ts

@@ -1,5 +1,6 @@
 import test from 'ava'
 import { symlinkSync, symlink, readlinkSync, statSync, lstatSync } from '../index.js'
+import * as nodeFs from 'node:fs'
 import { writeFileSync, mkdirSync, existsSync, readlinkSync as nodeReadlinkSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
@@ -58,6 +59,30 @@ test('symlinkSync: should throw EEXIST if link path already exists', (t) => {
   t.throws(() => symlinkSync(target, link), { message: /EEXIST/ })
 })
 
+// ===== dual-run =====
+
+test('dual-run: symlinkSync result should match node:fs.symlinkSync', (t) => {
+  const dir = tmpDir()
+  const target = join(dir, 'dual-target.txt')
+  const hyperLink = join(dir, 'dual-hyper-link.txt')
+  const nodeLink = join(dir, 'dual-node-link.txt')
+  nodeFs.writeFileSync(target, 'hello')
+
+  nodeFs.symlinkSync(target, nodeLink)
+  symlinkSync(target, hyperLink)
+
+  // Both should be symlinks pointing to the same target
+  const nodeReadlink = nodeReadlinkSync(nodeLink, 'utf8')
+  const hyperReadlink = nodeReadlinkSync(hyperLink, 'utf8')
+  t.is(hyperReadlink, nodeReadlink)
+
+  // Both should resolve to the same file
+  const nodeLstat = nodeFs.lstatSync(nodeLink)
+  const hyperLstat = nodeFs.lstatSync(hyperLink)
+  t.is(hyperLstat.isSymbolicLink(), nodeLstat.isSymbolicLink())
+  t.true(hyperLstat.isSymbolicLink())
+})
+
 // ===== async =====
 
 test('symlink: async should create a symbolic link', async (t) => {