refactor: update type definitions for file system API functions to return Promise<unknown> instead of Promise<void>; enhance CI workflow for testing with improved Docker run command; refine timestamp handling in stat functions for better precision and compatibility

Author: CoderSerio

.github/workflows/CI.yml

@@ -223,11 +223,15 @@ jobs:
       - run: docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
         if: ${{ contains(matrix.target, 'armv7') }}
       - name: Test bindings
-        uses: addnab/docker-run-action@v3
-        with:
-          image: ${{ steps.docker.outputs.IMAGE }}
-          options: '-v ${{ github.workspace }}:${{ github.workspace }} -w ${{ github.workspace }} --platform ${{ steps.docker.outputs.PLATFORM }}'
-          run: corepack enable && pnpm test
+        run: |
+          docker run --rm \
+            -e CI=true \
+            -e GITHUB_ACTIONS=true \
+            -v "${{ github.workspace }}:${{ github.workspace }}" \
+            -w "${{ github.workspace }}" \
+            --platform "${{ steps.docker.outputs.PLATFORM }}" \
+            "${{ steps.docker.outputs.IMAGE }}" \
+            sh -lc "corepack enable && pnpm test"
   publish:
     name: Publish
     runs-on: ubuntu-latest

Cargo.toml

@@ -22,6 +22,12 @@ walkdir        = "2.5.0"
 [target.'cfg(unix)'.dependencies]
 libc = "0.2"
 
+[target.'cfg(windows)'.dependencies]
+windows-sys = { version = "0.59.0", features = [
+  "Win32_Foundation",
+  "Win32_Storage_FileSystem",
+] }
+
 [build-dependencies]
 napi-build = "2"
 

__test__/glob.spec.ts

@@ -161,9 +161,11 @@ test('dual-run: globSync "src/*" should match node:fs.globSync behavior for dire
   try {
     // @ts-ignore - globSync 在旧版 Node 可能不存在
     const nodeGlob = nodeFs.globSync as ((p: string, o: object) => string[]) | undefined
-    if (typeof nodeGlob === 'function') {
-      nodeResults.push(...nodeGlob('src/*', { cwd: base }))
+    if (typeof nodeGlob !== 'function') {
+      t.pass('node:fs.globSync not available, skipping dual-run comparison')
+      return
     }
+    nodeResults.push(...nodeGlob('src/*', { cwd: base }))
   } catch {
     // 旧版 Node.js 不支持 fs.globSync，跳过对比
     t.pass('node:fs.globSync not available, skipping dual-run comparison')

__test__/stat.spec.ts

@@ -113,8 +113,11 @@ test('statSync: atime Date should be correct for pre-epoch (negative ms) timesta
   const file = join(dir, 'pre-epoch.txt')
   nodeFs.writeFileSync(file, 'x')
   // -500 ms = 1969-12-31T23:59:59.500Z
-  const preEpochSecs = -0.5
-  nodeFs.utimesSync(file, preEpochSecs, preEpochSecs)
+  // NOTE: Passing a negative number to utimesSync is not reliably supported across
+  // platforms/Node versions. Use Date objects to ensure the pre-epoch timestamp
+  // is actually applied.
+  const preEpoch = new Date(-500)
+  nodeFs.utimesSync(file, preEpoch, preEpoch)
 
   const hyperStat = statSync(file)
   const nodeStat = nodeFs.statSync(file)

index.d.ts

@@ -45,35 +45,35 @@ export declare class Stats {
   get birthtime(): Date
 }
 
-export declare function access(path: string, mode?: number | undefined | null): Promise<void>
+export declare function access(path: string, mode?: number | undefined | null): Promise<unknown>
 
 export declare function accessSync(path: string, mode?: number | undefined | null): void
 
 export declare function appendFile(
   path: string,
   data: string | Buffer,
   options?: WriteFileOptions | undefined | null,
-): Promise<void>
+): Promise<unknown>
 
 export declare function appendFileSync(
   path: string,
   data: string | Buffer,
   options?: WriteFileOptions | undefined | null,
 ): void
 
-export declare function chmod(path: string, mode: number): Promise<void>
+export declare function chmod(path: string, mode: number): Promise<unknown>
 
 export declare function chmodSync(path: string, mode: number): void
 
-export declare function chown(path: string, uid: number, gid: number): Promise<void>
+export declare function chown(path: string, uid: number, gid: number): Promise<unknown>
 
 export declare function chownSync(path: string, uid: number, gid: number): void
 
-export declare function copyFile(src: string, dest: string, mode?: number | undefined | null): Promise<void>
+export declare function copyFile(src: string, dest: string, mode?: number | undefined | null): Promise<unknown>
 
 export declare function copyFileSync(src: string, dest: string, mode?: number | undefined | null): void
 
-export declare function cp(src: string, dest: string, options?: CpOptions | undefined | null): Promise<void>
+export declare function cp(src: string, dest: string, options?: CpOptions | undefined | null): Promise<unknown>
 
 export interface CpOptions {
   recursive?: boolean
@@ -91,21 +91,17 @@ export interface CpOptions {
 
 export declare function cpSync(src: string, dest: string, options?: CpOptions | undefined | null): void
 
-export declare function exists(path: string): Promise<boolean>
+export declare function exists(path: string): Promise<unknown>
 
 export declare function existsSync(path: string): boolean
 
-export declare function glob(
-  pattern: string,
-  options?: GlobOptions | undefined | null,
-): Promise<Array<string> | Array<Dirent>>
+export declare function glob(pattern: string, options?: GlobOptions | undefined | null): Promise<unknown>
 
 export interface GlobOptions {
   cwd?: string
   withFileTypes?: boolean
   exclude?: Array<string>
   concurrency?: number
-  /** Respect .gitignore / .ignore files (default: true) */
   gitIgnore?: boolean
 }
 
@@ -114,15 +110,15 @@ export declare function globSync(
   options?: GlobOptions | undefined | null,
 ): Array<string> | Array<Dirent>
 
-export declare function link(existingPath: string, newPath: string): Promise<void>
+export declare function link(existingPath: string, newPath: string): Promise<unknown>
 
 export declare function linkSync(existingPath: string, newPath: string): void
 
-export declare function lstat(path: string): Promise<Stats>
+export declare function lstat(path: string): Promise<unknown>
 
 export declare function lstatSync(path: string): Stats
 
-export declare function mkdir(path: string, options?: MkdirOptions | undefined | null): Promise<string | null>
+export declare function mkdir(path: string, options?: MkdirOptions | undefined | null): Promise<unknown>
 
 export interface MkdirOptions {
   recursive?: boolean
@@ -131,19 +127,29 @@ export interface MkdirOptions {
 
 export declare function mkdirSync(path: string, options?: MkdirOptions | undefined | null): string | null
 
-export declare function mkdtemp(prefix: string): Promise<string>
+export declare function mkdtemp(prefix: string): Promise<unknown>
 
 export declare function mkdtempSync(prefix: string): string
 
-export declare function readdir(
-  path: string,
-  options?: ReaddirOptions | undefined | null,
-): Promise<Array<string> | Array<Dirent>>
-
+export declare function readdir(path: string, options?: ReaddirOptions | undefined | null): Promise<unknown>
+
+/** * Reads the contents of a directory.
+ * @param {string | Buffer | URL} path
+ * @param {string | {
+ *   encoding?: string;
+ *   withFileTypes?: boolean;
+ *   recursive?: boolean;
+ *   }} [options]
+ * @param {(
+ *   err?: Error,
+ *   files?: string[] | Buffer[] | Dirent[]
+ * ) => any} callback
+ * @returns {void}
+ */
 export interface ReaddirOptions {
   /**
    * File name encoding. 'utf8' (default) returns strings.
-   * 'buffer' returns Buffer objects for each name (not yet supported, treated as 'utf8').
+   * 'buffer' returns Buffer objects for each name.
    * Other values are treated as 'utf8'.
    */
   encoding?: string
@@ -158,7 +164,7 @@ export declare function readdirSync(
   options?: ReaddirOptions | undefined | null,
 ): Array<string> | Array<Dirent>
 
-export declare function readFile(path: string, options?: ReadFileOptions | undefined | null): Promise<string | Buffer>
+export declare function readFile(path: string, options?: ReadFileOptions | undefined | null): Promise<unknown>
 
 export interface ReadFileOptions {
   encoding?: string
@@ -167,21 +173,21 @@ export interface ReadFileOptions {
 
 export declare function readFileSync(path: string, options?: ReadFileOptions | undefined | null): string | Buffer
 
-export declare function readlink(path: string): Promise<string>
+export declare function readlink(path: string): Promise<unknown>
 
 export declare function readlinkSync(path: string): string
 
-export declare function realpath(path: string): Promise<string>
+export declare function realpath(path: string): Promise<unknown>
 
 export declare function realpathSync(path: string): string
 
-export declare function rename(oldPath: string, newPath: string): Promise<void>
+export declare function rename(oldPath: string, newPath: string): Promise<unknown>
 
 export declare function renameSync(oldPath: string, newPath: string): void
 
-export declare function rm(path: string, options?: RmOptions | undefined | null): Promise<void>
+export declare function rm(path: string, options?: RmOptions | undefined | null): Promise<unknown>
 
-export declare function rmdir(path: string): Promise<void>
+export declare function rmdir(path: string): Promise<unknown>
 
 export declare function rmdirSync(path: string): void
 
@@ -191,7 +197,8 @@ export declare function rmdirSync(path: string): void
  * - `force`: When true, silently ignore errors when path does not exist.
  * - `recursive`: When true, remove directory and all its contents.
  * - `maxRetries`: If an `EBUSY`, `EMFILE`, `ENFILE`, `ENOTEMPTY`, or `EPERM` error is
- *   encountered, retries with a linear backoff of `retryDelay` ms on each try.
+ *   encountered, Node.js retries the operation with a linear backoff of `retryDelay` ms longer on
+ *   each try. This option represents the number of retries.
  * - `retryDelay`: The amount of time in milliseconds to wait between retries (default 100ms).
  * - `concurrency` (hyper-fs extension): Number of parallel threads for recursive removal.
  */
@@ -205,41 +212,31 @@ export interface RmOptions {
 
 export declare function rmSync(path: string, options?: RmOptions | undefined | null): void
 
-export declare function stat(path: string): Promise<Stats>
+export declare function stat(path: string): Promise<unknown>
 
 export declare function statSync(path: string): Stats
 
-export declare function symlink(
-  target: string,
-  path: string,
-  /** On Windows: 'file' | 'dir' | 'junction'. Ignored on Unix. */
-  symlinkType?: string | undefined | null,
-): Promise<void>
+export declare function symlink(target: string, path: string, symlinkType?: string | undefined | null): Promise<unknown>
 
-export declare function symlinkSync(
-  target: string,
-  path: string,
-  /** On Windows: 'file' | 'dir' | 'junction'. Ignored on Unix. */
-  symlinkType?: string | undefined | null,
-): void
+export declare function symlinkSync(target: string, path: string, symlinkType?: string | undefined | null): void
 
-export declare function truncate(path: string, len?: number | undefined | null): Promise<void>
+export declare function truncate(path: string, len?: number | undefined | null): Promise<unknown>
 
 export declare function truncateSync(path: string, len?: number | undefined | null): void
 
-export declare function unlink(path: string): Promise<void>
+export declare function unlink(path: string): Promise<unknown>
 
 export declare function unlinkSync(path: string): void
 
-export declare function utimes(path: string, atime: number, mtime: number): Promise<void>
+export declare function utimes(path: string, atime: number, mtime: number): Promise<unknown>
 
 export declare function utimesSync(path: string, atime: number, mtime: number): void
 
 export declare function writeFile(
   path: string,
   data: string | Buffer,
   options?: WriteFileOptions | undefined | null,
-): Promise<void>
+): Promise<unknown>
 
 export interface WriteFileOptions {
   encoding?: string

src/realpath.rs

@@ -4,6 +4,18 @@ use napi_derive::napi;
 use std::fs;
 use std::path::Path;
 
+#[cfg(windows)]
+fn strip_verbatim_prefix(s: String) -> String {
+  if let Some(rest) = s.strip_prefix(r"\\?\UNC\") {
+    // \\?\UNC\server\share\path -> \\server\share\path
+    return format!(r"\\{}", rest);
+  }
+  if let Some(rest) = s.strip_prefix(r"\\?\") {
+    return rest.to_string();
+  }
+  s
+}
+
 fn realpath_impl(path_str: String) -> Result<String> {
   let path = Path::new(&path_str);
   let resolved = fs::canonicalize(path).map_err(|e| {
@@ -16,6 +28,33 @@ fn realpath_impl(path_str: String) -> Result<String> {
       Error::from_reason(e.to_string())
     }
   })?;
+
+  #[cfg(windows)]
+  {
+    use std::ffi::OsString;
+    use std::os::windows::ffi::OsStrExt;
+    use std::os::windows::ffi::OsStringExt;
+    use windows_sys::Win32::Storage::FileSystem::GetShortPathNameW;
+
+    let wide: Vec<u16> = resolved
+      .as_os_str()
+      .encode_wide()
+      .chain(std::iter::once(0))
+      .collect();
+    let mut buf: Vec<u16> = vec![0; 32768];
+    let len = unsafe { GetShortPathNameW(wide.as_ptr(), buf.as_mut_ptr(), buf.len() as u32) };
+    if len > 0 && (len as usize) < buf.len() {
+      buf.truncate(len as usize);
+      let short = OsString::from_wide(&buf);
+      let s = short.to_string_lossy().to_string();
+      return Ok(strip_verbatim_prefix(s));
+    }
+
+    let s = resolved.to_string_lossy().to_string();
+    return Ok(strip_verbatim_prefix(s));
+  }
+
+  #[cfg(not(windows))]
   Ok(resolved.to_string_lossy().to_string())
 }