chore: update package metadata, improve type definitions, and enhance README documentation

Author: CoderSerio

.github/workflows/CI.yml

@@ -152,7 +152,7 @@ jobs:
       - name: Install dependencies
         run: pnpm install
       - name: Download artifacts
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v4
         with:
           name: bindings-${{ matrix.settings.target }}
           path: .
@@ -208,7 +208,7 @@ jobs:
           pnpm config set supportedArchitectures.libc "[\"current\", \"musl\", \"gnu\"]" --json
           pnpm install
       - name: Download artifacts
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v4
         with:
           name: bindings-${{ matrix.target }}
           path: .
@@ -252,7 +252,7 @@ jobs:
       - name: create npm dirs
         run: pnpm napi create-npm-dirs
       - name: Download all artifacts
-        uses: actions/download-artifact@v4 # v4 is standard, v6 is user specific maybe? keeping consistent with other edits
+        uses: actions/download-artifact@v4
         with:
           path: artifacts
       - name: Move artifacts

Cargo.toml

@@ -1,6 +1,6 @@
 
 [package]
-authors = ["LongYinan <lynweklm@gmail.com>"]
+authors = []
 edition = "2021"
 name    = "hyper_fs"
 version = "0.1.0"

README.md

@@ -10,7 +10,7 @@
   A high-performance, drop-in replacement for Node.js <code>fs</code> module, powered by Rust.
 </p>
 
-## Installation (⚠️ Not Ready Yet)
+## Installation
 
 ```bash
 npm install hyper-fs

README.zh-CN.md

@@ -12,7 +12,7 @@
   由 Rust 驱动的高性能 Node.js <code>fs</code> 模块「即插即用」替代品。
 </p>
 
-## 安装（⚠️ 暂未就绪）
+## 安装
 
 ```bash
 npm install hyper-fs

__test__/glob.spec.ts

@@ -47,25 +47,16 @@ test('globSync: should support exclude option', (t) => {
   t.true(filteredFiles.length < allFiles.length)
 })
 
-test('globSync: should respect git_ignore (default: true)', (t) => {
-  // 'target' directory is usually gitignored in Rust projects
-  // Note: This test assumes 'target' directory exists and is ignored.
-  // If running in a fresh clone without build, target might not exist.
-  // We can skip if target doesn't exist, or just check node_modules which is definitely ignored?
-  // node_modules is ignored by default in many setups but strict gitignore check depends on .gitignore file.
-
-  // Let's assume 'target' exists because we built the project
+test('globSync: should respect gitIgnore (default: true)', (t) => {
+  // When gitIgnore: true (default), files in .gitignore are excluded.
+  // When gitIgnore: false, they are included.
   const ignoredFiles = globSync('target/**/*.d', { cwd: CWD })
-  // Should be empty or very few if ignored (actually cargo ignores target/)
-  // But wait, standard_filters includes .ignore and .gitignore.
-
-  // If we force git_ignore: false, we should see files
-  const includedFiles = globSync('target/**/*.d', { cwd: CWD, git_ignore: false })
+  const includedFiles = globSync('target/**/*.d', { cwd: CWD, gitIgnore: false })
 
   if (includedFiles.length > 0) {
     t.true(ignoredFiles.length < includedFiles.length, 'Should find fewer files when respecting gitignore')
   } else {
-    t.pass('Target directory empty or not present, skipping git_ignore comparison')
+    t.pass('Target directory empty or not present, skipping gitIgnore comparison')
   }
 })
 

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

package.json

@@ -1,21 +1,27 @@
 {
   "name": "hyper-fs",
   "version": "0.0.1",
-  "description": "Template project for writing node package with napi-rs",
+  "description": "High-performance drop-in replacement for Node.js fs module, powered by Rust",
   "main": "index.js",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/napi-rs/package-template.git"
+    "url": "git+https://github.com/hyper-fs/hyper-fs.git"
   },
   "license": "MIT",
   "browser": "browser.js",
   "keywords": [
+    "fs",
+    "filesystem",
+    "file-system",
+    "performance",
+    "rust",
+    "napi",
     "napi-rs",
-    "NAPI",
-    "N-API",
-    "Rust",
-    "node-addon",
-    "node-addon-api"
+    "native",
+    "readdir",
+    "glob",
+    "readFile",
+    "writeFile"
   ],
   "files": [
     "index.d.ts",
@@ -32,7 +38,7 @@
     ]
   },
   "engines": {
-    "node": ">= 10.16.0 < 11 || >= 11.8.0 < 12 || >= 12.0.0"
+    "node": ">= 18.0.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",