xrootd 0.1.12 → 0.2.0

package/README.md

@@ -1,23 +1,144 @@
-# XRootD Typescript Support
+# 🚀 XRootD TypeScript Support (`xrootd`)
 
-> [!WARNING]
-> **Working in process**. This package is currently under active development and not ready for production use. Stay tuned!
+A high-performance, enterprise-grade Node.js binding for the [XRootD](https://github.com/xrootd/xrootd) client library. Designed to bring seamless, extreme-throughput data access to the TypeScript ecosystem.
 
-- now complete: FileSystem/Url/Env/File
-- in progress: CopyProcess/ErrorProcess/And others
+> [!NOTE]
+> **Work in Progress**: This package is currently under active development. While core features are highly functional, the API may undergo minor refinements.
+
+
+## Supported Capabilities
+
+* **`FileSystem`**: Cluster-level operations (`stat`, `dirList`, `rm`, `mkdir`, `locate`).
+* **`File`**: High-performance I/O (`open`, `read`, `write`, `vectorRead`, server-side `clone`).
+* **`CopyProcess`**: Asynchronous, highly-parallel data transfers with real-time progress callbacks.
+* **`Env`**: Type-safe configuration management and OS-level auth protocol routing.
+* **`Url`**: XRootD-specific URI scheme parsing and validation.
+
+
+## Prerequisites
+
+To ensure compatibility with the pre-compiled native bindings, your environment must meet the following requirements:
+
+* **Node.js**: Version 20.x or higher.
+* **System Dependencies (Linux)**: Requires `libstdc++` providing `GLIBCXX_3.4.26` or newer (typically GCC 9+, e.g., CentOS 9 / Ubuntu 20.04+).
+* **System Dependencies (Macos)**: Requires macos 14 or later for arm64 architecture, macos 15 or later for intel architecture.
+* **Authentication**: Ensure your host machine has valid tickets (e.g., `kinit` for Kerberos) if accessing a secured cluster.
+
+
+## Installation
+
+```bash
+npm install xrootd
+# or
+yarn add xrootd
+
+```
 
 ---
 
-minimium gcc version for linux: GLIBCXX_3.4.26 (GCC 9 or newer) <br> minimium node version: node20
+## Usage Examples
+
+### 1. Configuration & Basic FileSystem
+
+```typescript
+import { Env, FileSystem } from 'xrootd';
+
+// Safely configure underlying XRootD environment
+Env.configure({
+    RequestTimeout: 30,       // Prevent 30-min infinite hangs (Node.js friendly)
+    WorkerThreads: 4,         // Boost underlying multiplexing
+    SecProtocol: 'krb5,unix'  // Force Kerberos or Unix socket auth
+});
+
+const fs = new FileSystem('root://eos01.ihep.ac.cn/');
+
+async function checkCluster() {
+    try {
+        const stat = await fs.stat('/eos/lhaaso/data');
+        console.log(`Directory size: ${stat.size} bytes`);
+        console.log(`Modified at: ${stat.modTimeAsString}`);
+    } catch (err: any) {
+        if (err.code === 'ENOENT') {
+            console.error('File not found in cluster.');
+        } else {
+            console.error(err.message);
+        }
+    }
+}
+
+```
+
+### 2. Zero-Copy File Reading
+
+```typescript
+import { File, OpenFlags } from 'xrootd';
+
+async function readHeader() {
+    const file = new File();
+    
+    // Auto-translates and handles C++ lifecycle
+    await file.open('root://eos01.ihep.ac.cn//eos/test.dat', OpenFlags.Read);
+    
+    // The returned buffer is a zero-copy mapping of C++ allocated memory
+    const buffer = await file.read(0n, 1024);
+    console.log(buffer.toString('utf-8'));
+    
+    await file.close();
+}
+
+```
+
+### 3. High-Performance CopyProcess with Progress
+
+```typescript
+import { CopyProcess } from 'xrootd';
+
+async function syncData() {
+    const cp = new CopyProcess();
+    
+    cp.addJob({
+        source: 'root://eos01.ihep.ac.cn//eos/data.raw',
+        target: '/local/disk/data.raw',
+        force: true,
+        parallelChunks: 4
+    });
+
+    await cp.prepare();
+    
+    const results = await cp.run((jobNum, processed, total) => {
+        const percent = ((processed / total) * 100).toFixed(2);
+        console.log(`Job ${jobNum} Progress: ${percent}%`);
+    });
+
+    console.log('Copy completed:', results);
+}
+
+```
+
+## ✨ Why `xrootd`? (Core Architecture)
+
+Unlike traditional Node.js C++ addons, `xrootd` is architected for **High Energy Physics (HEP)** and **Big Data** workloads:
+
+*  **True Native Async**: Bypasses the notoriously limited Node.js `libuv` thread pool (default 4 threads). It hooks directly into XRootD's underlying C++ event loop via N-API `ThreadSafeFunction`, allowing thousands of concurrent requests without blocking the V8 engine.
+*  **Absolute Zero-Copy I/O**: Implements direct memory handoffs. Data read from the EOS cluster is mounted directly as V8 `Buffer` objects without a single byte of internal memory copying, completely eliminating GC (Garbage Collection) pauses during heavy I/O.
+*  **Idiomatic Node.js Experience**: "Thin C++, Thick TS". Complex XRootD protocol errors (e.g., `3011`) are smartly translated into standard Node.js exceptions (e.g., `ENOENT`, `EACCES`), complete with system call contexts and retryable flags.
+*  **Zero-Config Authentication**: Bundles essential security plugins (Kerberos, SSS, Unix, Token) natively. Path injection is handled automatically under the hood—no more `[FATAL] Auth failed` or missing `.so` nightmares.
 
 ---
 
-License
+##  Licensing
+
+This project is released under a **Dual License** strategy to balance open-source compatibility and developer freedom:
 
-This project follows the dual license: [GNU GPLv3](LICENSE-GPLv3) and [MIT](LICENSE-MIT).
+1. **[GNU GPLv3](https://www.google.com/search?q=https://www.gnu.org/licenses/gpl-3.0.en.html)**: The native binding codebase adheres to the GPLv3 license to remain fully compatible with the upstream C++ XRootD project.
+2. **[MIT](https://www.google.com/search?q=https://opensource.org/licenses/MIT)**: The core TypeScript APIs, interface definitions, and glue layers are provided under the MIT license, allowing you to integrate the TS components into your own software architectures without viral restrictive requirements.
 
-The XRootD project is GPL, so this project is also GPL. However, the API of this project is provided under MIT license, so you can use this project in your project without any restriction.
+*Disclaimer: This project is a third-party community initiative built for modern web ecosystems and is not affiliated with, officially endorsed by, or sponsored by the core XRootD project.*
+
+---
 
+## Contributing
 
+We welcome contributions from the high-energy physics, astrophysics, and Node.js communities! Whether it's reporting bugs, improving documentation, or adding support for advanced XRootD features.
 
-This project is not affiliated with the XRootD project. It is a third-party project that provides a Node.js interface to the XRootD library.
+*Contribution guidelines coming soon.*

package/dist/index.cjs

@@ -179,7 +179,9 @@ var File = class {
 		return this._internal.IsOpen();
 	}
 	async getProperty(name) {
-		return this._internal.GetProperty(name);
+		const ret = this._internal.GetProperty(name);
+		if (ret.success) return ret.value;
+		throw new Error("TODO");
 	}
 	async setProperty(name, value) {
 		return this._internal.SetProperty(name, value);
@@ -211,25 +213,37 @@ var File = class {
 	/**
 	* 设置文件的扩展属性
 	*/
-	async setXAttr(name, value) {
-		return this._internal.SetXAttr(name);
+	async setXAttrs(attrs) {
+		return this._internal.SetXAttr(attrs);
+	}
+	/**
+	* 设置文件的扩展属性
+	*/
+	async setXAttr(key, value) {
+		return (await this._internal.SetXAttr({ [key]: value }))[0].ok;
 	}
 	/**
 	* 获取文件的扩展属性
 	*/
-	async getXAttr(name) {
-		return this._internal.GetXAttr(name);
+	async getXAttrs(keys) {
+		return this._internal.GetXAttr(keys);
+	}
+	async getXAttr(key) {
+		return (await this._internal.GetXAttr([key]))[key];
 	}
 	/**
 	* 删除文件的扩展属性
 	*/
-	async delXAttr(name) {
-		return this._internal.DelXAttr(name);
+	async delXAttrs(keys) {
+		return this._internal.DelXAttr(keys);
+	}
+	async delXAttr(key) {
+		return (await this._internal.DelXAttr([key]))[0].ok;
 	}
 	/**
-	* 列出文件所有的扩展属性名称
+	* 列出文件所有的扩展属性和内容
 	*/
-	async listXAttr() {
+	async listXAttrs() {
 		return this._internal.ListXAttr();
 	}
 	/**
@@ -535,25 +549,34 @@ var FileSystem = class {
 	* @param targetPath 目标路径
 	* @param attrs 扩展属性键值对记录
 	*/
-	async setXAttr(targetPath, attrs) {
+	async setXAttrs(targetPath, attrs) {
 		return this._internal.SetXAttr(this._normalize(targetPath), attrs);
 	}
+	async setXAttr(targetPath, key, value) {
+		return (await this.setXAttrs(targetPath, { [key]: value }))[0].ok;
+	}
 	/**
 	* 获取扩展属性
 	* @param targetPath 目标路径
 	* @param keys 需要获取的属性名数组
 	*/
-	async getXAttr(targetPath, keys) {
+	async getXAttrs(targetPath, keys) {
 		return this._internal.GetXAttr(this._normalize(targetPath), keys);
 	}
+	async getXAttr(targetPath, key) {
+		return (await this.getXAttrs(targetPath, [key]))[key];
+	}
 	/**
 	* 删除指定的扩展属性
 	* @param targetPath 目标路径
 	* @param keys 需要删除的属性名数组
 	*/
-	async delXAttr(targetPath, keys) {
+	async delXAttrs(targetPath, keys) {
 		return this._internal.DelXAttr(this._normalize(targetPath), keys);
 	}
+	async delXAttr(targetPath, key) {
+		return (await this.delXAttrs(targetPath, [key]))[0].ok;
+	}
 	/**
 	* 列出目标文件或目录的所有扩展属性
 	*/
@@ -562,6 +585,47 @@ var FileSystem = class {
 	}
 };
 //#endregion
+//#region lib/copy.ts
+var CopyProcess = class {
+	nativeCp;
+	constructor() {
+		this.nativeCp = new nativeAddon.CopyProcess();
+	}
+	/**
+	* Add a job to the copy process synchronously
+	*/
+	addJob(config) {
+		this.nativeCp.AddJob(config);
+	}
+	/**
+	* Asynchronously prepare the jobs (resolve DNS, check endpoints, etc.)
+	*/
+	async prepare() {
+		return this.nativeCp.Prepare();
+	}
+	/**
+	* Run the copy process.
+	* @param onProgress Optional progress callback
+	* @returns Array of results corresponding to the jobs added
+	*/
+	async run(onProgress) {
+		if (onProgress) this.nativeCp.SetEventListener("progress", onProgress);
+		return this.nativeCp.Run();
+	}
+	/**
+	* Abort the running copy process.
+	*/
+	abort() {
+		this.nativeCp.CancelJob();
+	}
+	/**
+	* Abort the running copy process. (alias for abort)
+	*/
+	cancelJob() {
+		this.nativeCp.CancelJob();
+	}
+};
+//#endregion
 //#region lib/url.ts
 /**
 * 纯 TypeScript 实现的 XRootD URL 解析器
@@ -747,6 +811,7 @@ Env.configure({
 });
 //#endregion
 exports.AccessMode = AccessMode;
+exports.CopyProcess = CopyProcess;
 exports.Env = Env;
 exports.File = File;
 exports.FileSystem = FileSystem;

package/dist/index.d.cts

@@ -8,6 +8,18 @@ interface IXRootDError extends Error {
   xrdErrNo: number;
   xrdErrMsg: string;
 }
+type XRootDOkError = {
+  ok: true;
+} | ({
+  ok: false;
+} & IXRootDError);
+type XAttrStatusResult = {
+  ok: true;
+  name: string;
+} | ({
+  ok: false;
+  name: string;
+} & IXRootDError);
 interface StatInfo {
   id: string;
   size: bigint;
@@ -56,16 +68,10 @@ interface DirListEntry {
   hostAddress: string;
   stat: StatInfo | null;
 }
-interface XAttrStatusResult {
-  name: string;
-  isOk: boolean;
-  code: number;
-  message: string;
-}
 declare class XRootDError extends Error {
   code: number;
   status: number;
-  constructor(status: IXRootDError);
+  constructor(status: XRootDOkError);
 }
 /**
  * 对应 src/core/XrdNodeFile.cc 中 Init 暴露的类
@@ -93,6 +99,65 @@ interface INativeFile {
   ListXAttr(): Promise<Record<string, string>>;
   Clone(list: CloneLocationRequest[]): Promise<void>;
 }
+interface CopyJobConfig {
+  /** original source URL */
+  source: string;
+  /** target directory or file */
+  target: string;
+  /** maximum number sources */
+  sourceLimit?: number;
+  /** overwrite target if exists */
+  force?: boolean;
+  /** persistify only on successful close */
+  posc?: boolean;
+  /** ignore locking semantics on destination */
+  coerce?: boolean;
+  /** create path to the file if it doesn't exist */
+  makeDir?: boolean;
+  /** "first" try third party copy, if it fails try normal copy; "only" only try third party copy */
+  thirdParty?: string;
+  /** "none"    - no checksumming
+      "end2end" - end to end checksumming
+      "source"  - calculate checksum at source
+      "target"  - calculate checksum at target */
+  checkSumMode?: "none" | "end2end" | "source" | "target";
+  /** type of the checksum to be used */
+  checkSumType?: string;
+  /** checksum preset */
+  checkSumPreset?: string;
+  /** size of a copy chunks in bytes */
+  chunkSize?: number;
+  /** number of chunks that should be requested in parallel
+   *
+   * [uint8_t]
+   */
+  parallelChunks?: number;
+  /** time limit for successfull initialization of the copy job
+   * [time_t]
+   */
+  initTimeout?: number;
+  /** time limit for the actual copy to finish
+   * [time_t]
+   */
+  tpcTimeout?: number;
+  /** support for the case where the size source file may change during reading process */
+  dynamicSource?: boolean;
+}
+interface CopyJobResult {
+  /** checksum at source, if requested */
+  sourceCheckSum?: string;
+  /** checksum at target, if requested */
+  targetCheckSum?: string;
+  /** file size */
+  size: bigint;
+  /** status of the copy operation */
+  status?: XRootDOkError;
+  /** all sources used */
+  sources?: string[];
+  /** the actual disk server target */
+  realTarget?: string;
+}
+type ProgressCallback = (jobNum: number, processed: number, total: number) => void;
 interface ReadStreamOptions {
   start?: bigint;
   end?: bigint;
@@ -232,7 +297,7 @@ declare class File$1 {
    */
   isOpen(): boolean;
   getProperty(name: string): Promise<string>;
-  setProperty(name: string, value: string): Promise<void>;
+  setProperty(name: string, value: string): Promise<boolean>;
   /**
    * 向量化读取 (Vector Read)
    * 在单个请求中从文件的多个非连续区域读取数据，极大地减少网络往返开销。
@@ -248,19 +313,25 @@ declare class File$1 {
   /**
    * 设置文件的扩展属性
    */
-  setXAttr(name: string, value: string): Promise<void>;
+  setXAttrs(attrs: Record<string, string>): Promise<XAttrStatusResult[]>;
+  /**
+   * 设置文件的扩展属性
+   */
+  setXAttr(key: string, value: string): Promise<boolean>;
   /**
    * 获取文件的扩展属性
    */
-  getXAttr(name: string): Promise<string>;
+  getXAttrs(keys: string[]): Promise<Record<string, string>>;
+  getXAttr(key: string): Promise<string>;
   /**
    * 删除文件的扩展属性
    */
-  delXAttr(name: string): Promise<void>;
+  delXAttrs(keys: string[]): Promise<XAttrStatusResult[]>;
+  delXAttr(key: string): Promise<boolean>;
   /**
-   * 列出文件所有的扩展属性名称
+   * 列出文件所有的扩展属性和内容
    */
-  listXAttr(): Promise<string[]>;
+  listXAttrs(): Promise<Record<string, string>>;
   /**
    * 将其他文件的指定区间在服务器端克隆到当前文件
    * 当前文件必须以写入/更新模式打开
@@ -408,25 +479,56 @@ declare class FileSystem {
    * @param targetPath 目标路径
    * @param attrs 扩展属性键值对记录
    */
-  setXAttr(targetPath: string, attrs: Record<string, string>): Promise<XAttrStatusResult[]>;
+  setXAttrs(targetPath: string, attrs: Record<string, string>): Promise<XAttrStatusResult[]>;
+  setXAttr(targetPath: string, key: string, value: string): Promise<boolean>;
   /**
    * 获取扩展属性
    * @param targetPath 目标路径
    * @param keys 需要获取的属性名数组
    */
-  getXAttr(targetPath: string, keys: string[]): Promise<Record<string, string>>;
+  getXAttrs(targetPath: string, keys: string[]): Promise<Record<string, string>>;
+  getXAttr(targetPath: string, key: string): Promise<string>;
   /**
    * 删除指定的扩展属性
    * @param targetPath 目标路径
    * @param keys 需要删除的属性名数组
    */
-  delXAttr(targetPath: string, keys: string[]): Promise<XAttrStatusResult[]>;
+  delXAttrs(targetPath: string, keys: string[]): Promise<XAttrStatusResult[]>;
+  delXAttr(targetPath: string, key: string): Promise<boolean>;
   /**
    * 列出目标文件或目录的所有扩展属性
    */
   listXAttr(targetPath: string): Promise<Record<string, string>>;
 }
 //#endregion
+//#region lib/copy.d.ts
+declare class CopyProcess {
+  private nativeCp;
+  constructor();
+  /**
+   * Add a job to the copy process synchronously
+   */
+  addJob(config: CopyJobConfig): void;
+  /**
+   * Asynchronously prepare the jobs (resolve DNS, check endpoints, etc.)
+   */
+  prepare(): Promise<void>;
+  /**
+   * Run the copy process.
+   * @param onProgress Optional progress callback
+   * @returns Array of results corresponding to the jobs added
+   */
+  run(onProgress?: ProgressCallback): Promise<CopyJobResult[]>;
+  /**
+   * Abort the running copy process.
+   */
+  abort(): void;
+  /**
+   * Abort the running copy process. (alias for abort)
+   */
+  cancelJob(): void;
+}
+//#endregion
 //#region lib/url.d.ts
 /**
  * 纯 TypeScript 实现的 XRootD URL 解析器
@@ -758,4 +860,4 @@ declare class XRootDEnvironment {
 }
 declare const Env: XRootDEnvironment;
 //#endregion
-export { AccessMode, Env, File$1 as File, FileSystem, type LocationInfo, MkDirFlags, OpenFlags, type PropertyList, type ReadChunkRequest, type ReadStreamOptions, type StatInfo, type StatVFSInfo, XRootDUrl as URL, type WriteStreamOptions, type XRootDError };
+export { AccessMode, CopyProcess, Env, File$1 as File, FileSystem, type LocationInfo, MkDirFlags, OpenFlags, type PropertyList, type ReadChunkRequest, type ReadStreamOptions, type StatInfo, type StatVFSInfo, XRootDUrl as URL, type WriteStreamOptions, type XRootDError };

package/dist/index.d.mts

@@ -8,6 +8,18 @@ interface IXRootDError extends Error {
   xrdErrNo: number;
   xrdErrMsg: string;
 }
+type XRootDOkError = {
+  ok: true;
+} | ({
+  ok: false;
+} & IXRootDError);
+type XAttrStatusResult = {
+  ok: true;
+  name: string;
+} | ({
+  ok: false;
+  name: string;
+} & IXRootDError);
 interface StatInfo {
   id: string;
   size: bigint;
@@ -56,16 +68,10 @@ interface DirListEntry {
   hostAddress: string;
   stat: StatInfo | null;
 }
-interface XAttrStatusResult {
-  name: string;
-  isOk: boolean;
-  code: number;
-  message: string;
-}
 declare class XRootDError extends Error {
   code: number;
   status: number;
-  constructor(status: IXRootDError);
+  constructor(status: XRootDOkError);
 }
 /**
  * 对应 src/core/XrdNodeFile.cc 中 Init 暴露的类
@@ -93,6 +99,65 @@ interface INativeFile {
   ListXAttr(): Promise<Record<string, string>>;
   Clone(list: CloneLocationRequest[]): Promise<void>;
 }
+interface CopyJobConfig {
+  /** original source URL */
+  source: string;
+  /** target directory or file */
+  target: string;
+  /** maximum number sources */
+  sourceLimit?: number;
+  /** overwrite target if exists */
+  force?: boolean;
+  /** persistify only on successful close */
+  posc?: boolean;
+  /** ignore locking semantics on destination */
+  coerce?: boolean;
+  /** create path to the file if it doesn't exist */
+  makeDir?: boolean;
+  /** "first" try third party copy, if it fails try normal copy; "only" only try third party copy */
+  thirdParty?: string;
+  /** "none"    - no checksumming
+      "end2end" - end to end checksumming
+      "source"  - calculate checksum at source
+      "target"  - calculate checksum at target */
+  checkSumMode?: "none" | "end2end" | "source" | "target";
+  /** type of the checksum to be used */
+  checkSumType?: string;
+  /** checksum preset */
+  checkSumPreset?: string;
+  /** size of a copy chunks in bytes */
+  chunkSize?: number;
+  /** number of chunks that should be requested in parallel
+   *
+   * [uint8_t]
+   */
+  parallelChunks?: number;
+  /** time limit for successfull initialization of the copy job
+   * [time_t]
+   */
+  initTimeout?: number;
+  /** time limit for the actual copy to finish
+   * [time_t]
+   */
+  tpcTimeout?: number;
+  /** support for the case where the size source file may change during reading process */
+  dynamicSource?: boolean;
+}
+interface CopyJobResult {
+  /** checksum at source, if requested */
+  sourceCheckSum?: string;
+  /** checksum at target, if requested */
+  targetCheckSum?: string;
+  /** file size */
+  size: bigint;
+  /** status of the copy operation */
+  status?: XRootDOkError;
+  /** all sources used */
+  sources?: string[];
+  /** the actual disk server target */
+  realTarget?: string;
+}
+type ProgressCallback = (jobNum: number, processed: number, total: number) => void;
 interface ReadStreamOptions {
   start?: bigint;
   end?: bigint;
@@ -232,7 +297,7 @@ declare class File$1 {
    */
   isOpen(): boolean;
   getProperty(name: string): Promise<string>;
-  setProperty(name: string, value: string): Promise<void>;
+  setProperty(name: string, value: string): Promise<boolean>;
   /**
    * 向量化读取 (Vector Read)
    * 在单个请求中从文件的多个非连续区域读取数据，极大地减少网络往返开销。
@@ -248,19 +313,25 @@ declare class File$1 {
   /**
    * 设置文件的扩展属性
    */
-  setXAttr(name: string, value: string): Promise<void>;
+  setXAttrs(attrs: Record<string, string>): Promise<XAttrStatusResult[]>;
+  /**
+   * 设置文件的扩展属性
+   */
+  setXAttr(key: string, value: string): Promise<boolean>;
   /**
    * 获取文件的扩展属性
    */
-  getXAttr(name: string): Promise<string>;
+  getXAttrs(keys: string[]): Promise<Record<string, string>>;
+  getXAttr(key: string): Promise<string>;
   /**
    * 删除文件的扩展属性
    */
-  delXAttr(name: string): Promise<void>;
+  delXAttrs(keys: string[]): Promise<XAttrStatusResult[]>;
+  delXAttr(key: string): Promise<boolean>;
   /**
-   * 列出文件所有的扩展属性名称
+   * 列出文件所有的扩展属性和内容
    */
-  listXAttr(): Promise<string[]>;
+  listXAttrs(): Promise<Record<string, string>>;
   /**
    * 将其他文件的指定区间在服务器端克隆到当前文件
    * 当前文件必须以写入/更新模式打开
@@ -408,25 +479,56 @@ declare class FileSystem {
    * @param targetPath 目标路径
    * @param attrs 扩展属性键值对记录
    */
-  setXAttr(targetPath: string, attrs: Record<string, string>): Promise<XAttrStatusResult[]>;
+  setXAttrs(targetPath: string, attrs: Record<string, string>): Promise<XAttrStatusResult[]>;
+  setXAttr(targetPath: string, key: string, value: string): Promise<boolean>;
   /**
    * 获取扩展属性
    * @param targetPath 目标路径
    * @param keys 需要获取的属性名数组
    */
-  getXAttr(targetPath: string, keys: string[]): Promise<Record<string, string>>;
+  getXAttrs(targetPath: string, keys: string[]): Promise<Record<string, string>>;
+  getXAttr(targetPath: string, key: string): Promise<string>;
   /**
    * 删除指定的扩展属性
    * @param targetPath 目标路径
    * @param keys 需要删除的属性名数组
    */
-  delXAttr(targetPath: string, keys: string[]): Promise<XAttrStatusResult[]>;
+  delXAttrs(targetPath: string, keys: string[]): Promise<XAttrStatusResult[]>;
+  delXAttr(targetPath: string, key: string): Promise<boolean>;
   /**
    * 列出目标文件或目录的所有扩展属性
    */
   listXAttr(targetPath: string): Promise<Record<string, string>>;
 }
 //#endregion
+//#region lib/copy.d.ts
+declare class CopyProcess {
+  private nativeCp;
+  constructor();
+  /**
+   * Add a job to the copy process synchronously
+   */
+  addJob(config: CopyJobConfig): void;
+  /**
+   * Asynchronously prepare the jobs (resolve DNS, check endpoints, etc.)
+   */
+  prepare(): Promise<void>;
+  /**
+   * Run the copy process.
+   * @param onProgress Optional progress callback
+   * @returns Array of results corresponding to the jobs added
+   */
+  run(onProgress?: ProgressCallback): Promise<CopyJobResult[]>;
+  /**
+   * Abort the running copy process.
+   */
+  abort(): void;
+  /**
+   * Abort the running copy process. (alias for abort)
+   */
+  cancelJob(): void;
+}
+//#endregion
 //#region lib/url.d.ts
 /**
  * 纯 TypeScript 实现的 XRootD URL 解析器
@@ -758,4 +860,4 @@ declare class XRootDEnvironment {
 }
 declare const Env: XRootDEnvironment;
 //#endregion
-export { AccessMode, Env, File$1 as File, FileSystem, type LocationInfo, MkDirFlags, OpenFlags, type PropertyList, type ReadChunkRequest, type ReadStreamOptions, type StatInfo, type StatVFSInfo, XRootDUrl as URL, type WriteStreamOptions, type XRootDError };
+export { AccessMode, CopyProcess, Env, File$1 as File, FileSystem, type LocationInfo, MkDirFlags, OpenFlags, type PropertyList, type ReadChunkRequest, type ReadStreamOptions, type StatInfo, type StatVFSInfo, XRootDUrl as URL, type WriteStreamOptions, type XRootDError };

package/dist/index.mjs

@@ -154,7 +154,9 @@ var File = class {
 		return this._internal.IsOpen();
 	}
 	async getProperty(name) {
-		return this._internal.GetProperty(name);
+		const ret = this._internal.GetProperty(name);
+		if (ret.success) return ret.value;
+		throw new Error("TODO");
 	}
 	async setProperty(name, value) {
 		return this._internal.SetProperty(name, value);
@@ -186,25 +188,37 @@ var File = class {
 	/**
 	* 设置文件的扩展属性
 	*/
-	async setXAttr(name, value) {
-		return this._internal.SetXAttr(name);
+	async setXAttrs(attrs) {
+		return this._internal.SetXAttr(attrs);
+	}
+	/**
+	* 设置文件的扩展属性
+	*/
+	async setXAttr(key, value) {
+		return (await this._internal.SetXAttr({ [key]: value }))[0].ok;
 	}
 	/**
 	* 获取文件的扩展属性
 	*/
-	async getXAttr(name) {
-		return this._internal.GetXAttr(name);
+	async getXAttrs(keys) {
+		return this._internal.GetXAttr(keys);
+	}
+	async getXAttr(key) {
+		return (await this._internal.GetXAttr([key]))[key];
 	}
 	/**
 	* 删除文件的扩展属性
 	*/
-	async delXAttr(name) {
-		return this._internal.DelXAttr(name);
+	async delXAttrs(keys) {
+		return this._internal.DelXAttr(keys);
+	}
+	async delXAttr(key) {
+		return (await this._internal.DelXAttr([key]))[0].ok;
 	}
 	/**
-	* 列出文件所有的扩展属性名称
+	* 列出文件所有的扩展属性和内容
 	*/
-	async listXAttr() {
+	async listXAttrs() {
 		return this._internal.ListXAttr();
 	}
 	/**
@@ -510,25 +524,34 @@ var FileSystem = class {
 	* @param targetPath 目标路径
 	* @param attrs 扩展属性键值对记录
 	*/
-	async setXAttr(targetPath, attrs) {
+	async setXAttrs(targetPath, attrs) {
 		return this._internal.SetXAttr(this._normalize(targetPath), attrs);
 	}
+	async setXAttr(targetPath, key, value) {
+		return (await this.setXAttrs(targetPath, { [key]: value }))[0].ok;
+	}
 	/**
 	* 获取扩展属性
 	* @param targetPath 目标路径
 	* @param keys 需要获取的属性名数组
 	*/
-	async getXAttr(targetPath, keys) {
+	async getXAttrs(targetPath, keys) {
 		return this._internal.GetXAttr(this._normalize(targetPath), keys);
 	}
+	async getXAttr(targetPath, key) {
+		return (await this.getXAttrs(targetPath, [key]))[key];
+	}
 	/**
 	* 删除指定的扩展属性
 	* @param targetPath 目标路径
 	* @param keys 需要删除的属性名数组
 	*/
-	async delXAttr(targetPath, keys) {
+	async delXAttrs(targetPath, keys) {
 		return this._internal.DelXAttr(this._normalize(targetPath), keys);
 	}
+	async delXAttr(targetPath, key) {
+		return (await this.delXAttrs(targetPath, [key]))[0].ok;
+	}
 	/**
 	* 列出目标文件或目录的所有扩展属性
 	*/
@@ -537,6 +560,47 @@ var FileSystem = class {
 	}
 };
 //#endregion
+//#region lib/copy.ts
+var CopyProcess = class {
+	nativeCp;
+	constructor() {
+		this.nativeCp = new nativeAddon.CopyProcess();
+	}
+	/**
+	* Add a job to the copy process synchronously
+	*/
+	addJob(config) {
+		this.nativeCp.AddJob(config);
+	}
+	/**
+	* Asynchronously prepare the jobs (resolve DNS, check endpoints, etc.)
+	*/
+	async prepare() {
+		return this.nativeCp.Prepare();
+	}
+	/**
+	* Run the copy process.
+	* @param onProgress Optional progress callback
+	* @returns Array of results corresponding to the jobs added
+	*/
+	async run(onProgress) {
+		if (onProgress) this.nativeCp.SetEventListener("progress", onProgress);
+		return this.nativeCp.Run();
+	}
+	/**
+	* Abort the running copy process.
+	*/
+	abort() {
+		this.nativeCp.CancelJob();
+	}
+	/**
+	* Abort the running copy process. (alias for abort)
+	*/
+	cancelJob() {
+		this.nativeCp.CancelJob();
+	}
+};
+//#endregion
 //#region lib/url.ts
 /**
 * 纯 TypeScript 实现的 XRootD URL 解析器
@@ -721,4 +785,4 @@ Env.configure({
 	WorkerThreads: 4
 });
 //#endregion
-export { AccessMode, Env, File, FileSystem, MkDirFlags, OpenFlags, XRootDUrl as URL };
+export { AccessMode, CopyProcess, Env, File, FileSystem, MkDirFlags, OpenFlags, XRootDUrl as URL };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xrootd",
-  "version": "0.1.12",
+  "version": "0.2.0",
   "description": "Prebuilt Node.js Native Addon for XRootD, allowing JS access to EOS file systems",
   "type": "module",
   "exports": {
@@ -77,7 +77,7 @@
     "build": "pnpm run build:addon && pnpm run build:binaries && pnpm run build:tsc && pnpm run build:ts",
     "build:clean": "rm -r ./build && pnpm run build",
     "pack": "mkdir -p packages && pnpm pack --pack-destination ./packages",
-    "test:prep": "unrun ./test/prepare.ts",
-    "test": "node --test test/*.mjs"
+    "test:prep": "unrun ./tests/prepare.ts",
+    "test": "node --test tests/*.mjs"
   }
 }