@lingxia/rong 0.2.0 → 0.3.0

package/dist/fs.d.ts

@@ -2,108 +2,28 @@
  * File System module type definitions
  * Corresponds to: modules/rong_fs
  *
- * Provides APIs for file system operations including reading, writing, and directory management.
- * All file system APIs are mounted under the global `Rong` namespace.
- */
-/**
- * Options for reading files.
+ * Core API:
+ *   Rong.file(path) → RongFile (lazy file reference)
+ *   Rong.write(dest, data) → Promise<number> (universal write)
+ *
+ * All directory/path/permission APIs remain under the global `Rong` namespace.
  */
-export interface ReadFileOptions {
-    /**
-     * AbortSignal to cancel the read operation.
-     * When aborted, the operation will throw an AbortError.
-     *
-     * @see {@link AbortSignal}
-     * @example
-     * ```typescript
-     * const controller = new AbortController();
-     * const promise = Rong.readTextFile('/file.txt', {
-     *   signal: controller.signal
-     * });
-     * // Cancel after 1 second
-     * setTimeout(() => controller.abort(), 1000);
-     * ```
-     */
-    signal?: AbortSignal;
-}
 /**
- * Options for writing files.
- */
-export interface WriteFileOptions {
-    /**
-     * Append to file instead of overwriting.
-     * Cannot be used together with `createNew`.
-     *
-     * @default false
-     */
-    append?: boolean;
-    /**
-     * Create file only if it doesn't exist.
-     * Throws AlreadyExistsError if the file already exists.
-     * Cannot be used together with `append`.
-     *
-     * @default false
-     * @throws {AlreadyExistsError} If file already exists
-     */
-    createNew?: boolean;
-    /**
-     * File permissions mode (Unix-like systems only).
-     * Octal number (e.g., 0o644 for rw-r--r--).
-     * Ignored on Windows.
-     *
-     * @default 0o666 (modified by process umask)
-     * @platform unix
-     * @example
-     * ```typescript
-     * await Rong.writeTextFile('/script.sh', '#!/bin/bash\necho hello', {
-     *   mode: 0o755  // rwxr-xr-x
-     * });
-     * ```
-     */
-    mode?: number;
-    /**
-     * AbortSignal to cancel the write operation.
-     *
-     * @see {@link AbortSignal}
-     */
-    signal?: AbortSignal;
-}
-/**
- * Options for opening files.
+ * Options for opening files via {@link RongFile.open}.
  */
 export interface FileOpenOptions {
-    /**
-     * Open file for reading.
-     * @default false
-     */
+    /** Open file for reading. @default true */
     read?: boolean;
-    /**
-     * Open file for writing.
-     * @default false
-     */
+    /** Open file for writing. @default false */
     write?: boolean;
-    /**
-     * Open file for appending (writes go to end of file).
-     * @default false
-     */
+    /** Open file for appending (writes go to end of file). @default false */
     append?: boolean;
-    /**
-     * Truncate file to 0 bytes when opening (if it exists).
-     * Only valid when `write` is true.
-     * @default false
-     */
+    /** Truncate file to 0 bytes when opening. Only valid when `write` is true. @default false */
     truncate?: boolean;
-    /**
-     * Create file if it doesn't exist.
-     * Only valid when `write` is true.
-     * @default false
-     */
+    /** Create file if it doesn't exist. Only valid when `write` is true. @default false */
     create?: boolean;
     /**
      * Create file only if it doesn't exist (exclusive creation).
-     * Throws AlreadyExistsError if file exists.
-     * Only valid when `write` is true.
-     *
      * @default false
      * @throws {AlreadyExistsError} If file already exists
      */
@@ -121,15 +41,8 @@ export interface FileOpenOptions {
 export interface MkdirOptions {
     /**
      * Create parent directories as needed.
-     * If false and parent doesn't exist, throws NotFoundError.
-     *
      * @default false
      * @throws {NotFoundError} If parent doesn't exist and recursive is false
-     * @example
-     * ```typescript
-     * // Create nested directories
-     * await Rong.mkdir('/path/to/nested/dir', { recursive: true });
-     * ```
      */
     recursive?: boolean;
     /**
@@ -145,14 +58,7 @@ export interface MkdirOptions {
 export interface RemoveOptions {
     /**
      * Remove directories and their contents recursively.
-     * If false and path is a non-empty directory, throws an error.
-     *
      * @default false
-     * @example
-     * ```typescript
-     * // Remove directory and all its contents
-     * await Rong.remove('/path/to/dir', { recursive: true });
-     * ```
      */
     recursive?: boolean;
 }
@@ -160,87 +66,59 @@ export interface RemoveOptions {
  * Options for setting file timestamps via {@link FsModule.utime}.
  */
 export interface UTimeOptions {
+    /** Access time in milliseconds since Unix epoch. */
+    accessed?: number;
+    /** Modified time in milliseconds since Unix epoch. */
+    modified?: number;
+}
+/**
+ * Options for creating a FileSink writer via {@link RongFile.writer}.
+ */
+export interface FileSinkOptions {
     /**
-     * Access time in milliseconds since Unix epoch.
-     * If omitted, defaults to "now" (runtime-dependent).
+     * If true, open file in append mode. Default is truncate (overwrite).
+     * @default false
      */
-    accessed?: number;
+    append?: boolean;
     /**
-     * Modified time in milliseconds since Unix epoch.
-     * If omitted, defaults to "now" (runtime-dependent).
+     * File permissions mode (Unix-like systems only).
+     * @platform unix
      */
-    modified?: number;
+    mode?: number;
 }
 /**
  * File or directory metadata information.
- * Returned by `stat()` and `lstat()` functions.
+ * Returned by `RongFile.stat()` and `RongFile.lstat()`.
  */
 export interface FileInfo {
-    /**
-     * Whether this is a regular file.
-     * Mutually exclusive with `isDirectory` and `isSymlink`.
-     */
     readonly isFile: boolean;
-    /**
-     * Whether this is a directory.
-     * Mutually exclusive with `isFile` and `isSymlink`.
-     */
     readonly isDirectory: boolean;
-    /**
-     * Whether this is a symbolic link.
-     * For symbolic links, use `lstat()` instead of `stat()`
-     * to get link information rather than target information.
-     */
     readonly isSymlink: boolean;
-    /**
-     * File size in bytes.
-     * For directories, this is the size of the directory entry, not its contents.
-     */
+    /** File size in bytes. */
     readonly size: number;
-    /**
-     * Last modified time in milliseconds since Unix epoch.
-     * May be undefined if not supported by the file system.
-     */
+    /** Last modified time in milliseconds since Unix epoch. */
     readonly modified?: number;
-    /**
-     * Last accessed time in milliseconds since Unix epoch.
-     * May be undefined if not supported by the file system.
-     */
+    /** Last accessed time in milliseconds since Unix epoch. */
     readonly accessed?: number;
-    /**
-     * Creation time in milliseconds since Unix epoch.
-     * May be undefined if not supported by the file system.
-     */
+    /** Creation time in milliseconds since Unix epoch. */
     readonly created?: number;
-    /**
-     * File permissions mode (Unix-like systems only).
-     * Octal representation of file permissions.
-     * Undefined on Windows.
-     *
-     * @platform unix
-     */
+    /** File permissions mode (Unix only). @platform unix */
     readonly mode?: number;
 }
 /**
  * Directory entry information.
- * Returned by `readDir()` function.
+ * Returned by `Rong.readDir()`.
  */
 export interface DirEntry {
-    /**
-     * Entry name (without directory path).
-     * @example For `/path/to/file.txt`, name is `file.txt`
-     */
+    /** Entry name (without directory path). */
     readonly name: string;
-    /** Whether this entry is a regular file */
     readonly isFile: boolean;
-    /** Whether this entry is a directory */
     readonly isDirectory: boolean;
-    /** Whether this entry is a symbolic link */
     readonly isSymlink: boolean;
 }
 /**
  * Seek modes for file positioning.
- * Used with `FsFile.seek()` method.
+ * Used with `FileHandle.seek()` method.
  */
 export declare enum SeekMode {
     /** Seek from start of file (absolute position) */
@@ -251,195 +129,118 @@ export declare enum SeekMode {
     End = 2
 }
 /**
- * File handle for advanced file operations.
- * Obtained from `Rong.open()`.
+ * Incremental file writer with optional append support.
+ * Obtained from `RongFile.writer()`.
  *
  * @example
  * ```typescript
- * const file = await Rong.open('/path/to/file.txt', {
+ * const w = await Rong.file('/log.txt').writer({ append: true });
+ * await w.write("line 1\n");
+ * await w.write("line 2\n");
+ * await w.flush();
+ * await w.end();
+ * ```
+ */
+export interface FileSink {
+    /** Write data. Accepts string, TypedArray, or ArrayBuffer. Returns bytes written. */
+    write(data: string | ArrayBufferView | ArrayBuffer): Promise<number>;
+    /** Flush buffered data to disk. */
+    flush(): Promise<void>;
+    /** Flush and close the writer. */
+    end(): Promise<void>;
+}
+/**
+ * File handle for low-level file operations.
+ * Obtained from `RongFile.open()`.
+ *
+ * @example
+ * ```typescript
+ * const handle = await Rong.file('/path/to/file.txt').open({
  *   read: true,
  *   write: true
  * });
  *
  * try {
  *   const buffer = new ArrayBuffer(1024);
- *   const bytesRead = await file.read(buffer);
+ *   const bytesRead = await handle.read(buffer);
  *   console.log(`Read ${bytesRead} bytes`);
  * } finally {
- *   await file.close();
+ *   await handle.close();
  * }
  * ```
  */
-export interface FsFile {
-    /**
-     * Get file metadata.
-     *
-     * @returns Promise with file information
-     * @throws {IOError} If stat operation fails
-     * @example
-     * ```typescript
-     * const info = await file.stat();
-     * console.log(`File size: ${info.size} bytes`);
-     * ```
-     */
+export interface FileHandle {
     stat(): Promise<FileInfo>;
-    /**
-     * Read from file into buffer.
-     * Reads from current file position and advances the position.
-     *
-     * @param buffer - ArrayBuffer to read into
-     * @returns Promise with bytes read, or null on EOF
-     * @throws {IOError} If read operation fails
-     * @example
-     * ```typescript
-     * const buffer = new ArrayBuffer(4096);
-     * const bytesRead = await file.read(buffer);
-     * if (bytesRead === null) {
-     *   console.log('Reached end of file');
-     * } else {
-     *   console.log(`Read ${bytesRead} bytes`);
-     * }
-     * ```
-     */
     read(buffer: ArrayBuffer): Promise<number | null>;
-    /**
-     * Write buffer to file.
-     * Writes at current file position and advances the position.
-     *
-     * @param buffer - ArrayBuffer to write
-     * @returns Promise with number of bytes written
-     * @throws {IOError} If write operation fails
-     * @example
-     * ```typescript
-     * const data = new TextEncoder().encode('Hello World');
-     * const bytesWritten = await file.write(data.buffer);
-     * console.log(`Wrote ${bytesWritten} bytes`);
-     * ```
-     */
     write(buffer: ArrayBuffer): Promise<number>;
-    /**
-     * Sync file contents to disk.
-     * Ensures all buffered writes are flushed to storage.
-     *
-     * @returns Promise that resolves when sync is complete
-     * @throws {IOError} If sync operation fails
-     */
     sync(): Promise<void>;
-    /**
-     * Truncate or extend file to specified length.
-     *
-     * @param len - Target length in bytes (default: 0)
-     * @returns Promise that resolves when truncate is complete
-     * @throws {IOError} If truncate operation fails
-     * @example
-     * ```typescript
-     * // Truncate to 100 bytes
-     * await file.truncate(100);
-     *
-     * // Truncate to 0 bytes (clear file)
-     * await file.truncate();
-     * ```
-     */
     truncate(len?: number): Promise<void>;
-    /**
-     * Seek to position in file.
-     *
-     * @param offset - Byte offset
-     * @param whence - Seek mode (Start, Current, or End)
-     * @returns Promise with new absolute position
-     * @throws {IOError} If seek operation fails
-     * @example
-     * ```typescript
-     * // Seek to byte 100 from start
-     * await file.seek(100, Rong.SeekMode.Start);
-     *
-     * // Seek forward 50 bytes from current position
-     * await file.seek(50, Rong.SeekMode.Current);
-     *
-     * // Seek to 10 bytes before end
-     * await file.seek(-10, Rong.SeekMode.End);
-     * ```
-     */
     seek(offset: number, whence?: SeekMode): Promise<number>;
-    /**
-     * Close file handle.
-     * After closing, no further operations can be performed.
-     * It's recommended to use try-finally to ensure files are closed.
-     *
-     * @returns Promise that resolves when file is closed
-     * @example
-     * ```typescript
-     * const file = await Rong.open('/file.txt', { read: true });
-     * try {
-     *   // Use file...
-     * } finally {
-     *   await file.close();
-     * }
-     * ```
-     */
     close(): Promise<void>;
-    /**
-     * Get ReadableStream for reading file contents.
-     * The stream reads from the current file position.
-     * Cannot be used simultaneously with direct read operations.
-     *
-     * @example
-     * ```typescript
-     * const file = await Rong.open('/file.txt', { read: true });
-     * const readable = file.readable;
-     *
-     * for await (const chunk of readable) {
-     *   console.log('Received chunk:', chunk.length, 'bytes');
-     * }
-     * ```
-     */
     readonly readable: ReadableStream<Uint8Array>;
-    /**
-     * Get WritableStream for writing file contents.
-     * The stream writes to the current file position.
-     * Cannot be used simultaneously with direct write operations.
-     *
-     * @example
-     * ```typescript
-     * const file = await Rong.open('/file.txt', { write: true, create: true });
-     * const writable = file.writable;
-     * const writer = writable.getWriter();
-     *
-     * await writer.write(new TextEncoder().encode('Hello'));
-     * await writer.close();
-     * ```
-     */
     readonly writable: WritableStream<Uint8Array>;
 }
+/**
+ * Lazy file reference. Created by `Rong.file(path)`.
+ * Does NOT touch the filesystem until a method is called.
+ *
+ * @example
+ * ```typescript
+ * const f = Rong.file('/data.json');
+ *
+ * // Convenient whole-file operations
+ * const text = await f.text();
+ * const data = await f.json();
+ * const exists = await f.exists();
+ *
+ * // Low-level access when needed
+ * const handle = await f.open({ read: true, write: true });
+ * await handle.seek(100, Rong.SeekMode.Start);
+ * await handle.close();
+ * ```
+ */
+export interface RongFile {
+    /** The original path passed to `Rong.file()`. */
+    readonly name: string;
+    /** Read file contents as a UTF-8 string. */
+    text(): Promise<string>;
+    /** Read file contents and parse as JSON. */
+    json(): Promise<any>;
+    /** Read file contents as Uint8Array. */
+    bytes(): Promise<Uint8Array>;
+    /** Read file contents as ArrayBuffer. */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /** Get a ReadableStream of file contents. */
+    stream(): ReadableStream<Uint8Array>;
+    /** Check if the file exists. */
+    exists(): Promise<boolean>;
+    /** Delete the file. */
+    delete(): Promise<void>;
+    /** Get file metadata. */
+    stat(): Promise<FileInfo>;
+    /** Get file metadata (does not follow symlinks). */
+    lstat(): Promise<FileInfo>;
+    /** Open a low-level file handle for seek/truncate/random-access. */
+    open(options?: FileOpenOptions): Promise<FileHandle>;
+    /** Create an incremental writer (default: truncate; use `{ append: true }` for append). */
+    writer(options?: FileSinkOptions): Promise<FileSink>;
+}
 /**
  * File System module interface.
  * All operations are available under the global `Rong` namespace.
  */
 export interface FsModule {
-    readTextFile(path: string, options?: ReadFileOptions): Promise<string>;
-    readFile(path: string, options?: ReadFileOptions): Promise<ArrayBuffer>;
-    writeTextFile(path: string, text: string, options?: WriteFileOptions): Promise<void>;
-    writeFile(path: string, data: ArrayBufferView, options?: WriteFileOptions): Promise<void>;
-    copyFile(from: string, to: string): Promise<void>;
-    truncate(path: string, len?: number): Promise<void>;
-    open(path: string, options?: FileOpenOptions): Promise<FsFile>;
+    file(path: string): RongFile;
+    write(dest: string | RongFile, data: string | ArrayBufferView | ArrayBuffer | RongFile): Promise<number>;
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     readDir(path: string): Promise<AsyncIterableIterator<DirEntry>>;
-    stat(path: string): Promise<FileInfo>;
-    lstat(path: string): Promise<FileInfo>;
     remove(path: string, options?: RemoveOptions): Promise<void>;
     chdir(path: string): Promise<void>;
     symlink(target: string, path: string): Promise<void>;
     readlink(path: string): Promise<string>;
-    /**
-     * Change file permissions (Unix only)
-     * @platform unix
-     */
+    /** Change file permissions (Unix only) @platform unix */
     chmod(path: string, mode: number): Promise<void>;
-    /**
-     * Change file ownership (Unix only)
-     * @platform unix
-     */
+    /** Change file ownership (Unix only) @platform unix */
     chown(path: string, uid: number, gid: number): Promise<void>;
     utime(path: string, options: UTimeOptions): Promise<void>;
     rename(oldPath: string, newPath: string): Promise<void>;

package/dist/fs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAID;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAEzB,wCAAwC;IACxC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,oBAAY,QAAQ;IAClB,kDAAkD;IAClD,KAAK,IAAI;IACT,4CAA4C;IAC5C,OAAO,IAAI;IACX,sDAAsD;IACtD,GAAG,IAAI;CACR;AAID;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,MAAM;IACrB;;;;;;;;;;OAUG;IACH,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE1B;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAElD;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5C;;;;;;OAMG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtC;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzD;;;;;;;;;;;;;;;OAeG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAE9C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;CAC/C;AAID;;;GAGG;AACH,MAAM,WAAW,QAAQ;IAEvB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAGxE,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrF,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1F,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAGpD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAG/D,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,QAAQ,CAAC,CAAC,CAAC;IAChE,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACtC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAGnC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAGxC;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAG1D,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAGxC,QAAQ,CAAC,QAAQ,EAAE,OAAO,QAAQ,CAAC;CACpC;AAGD,OAAO,EAAE,CAAC"}
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"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"}

package/dist/fs.js

@@ -3,14 +3,17 @@
  * File System module type definitions
  * Corresponds to: modules/rong_fs
  *
- * Provides APIs for file system operations including reading, writing, and directory management.
- * All file system APIs are mounted under the global `Rong` namespace.
+ * Core API:
+ *   Rong.file(path) → RongFile (lazy file reference)
+ *   Rong.write(dest, data) → Promise<number> (universal write)
+ *
+ * All directory/path/permission APIs remain under the global `Rong` namespace.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SeekMode = void 0;
 /**
  * Seek modes for file positioning.
- * Used with `FsFile.seek()` method.
+ * Used with `FileHandle.seek()` method.
  */
 var SeekMode;
 (function (SeekMode) {
@@ -20,4 +23,4 @@ var SeekMode;
     SeekMode[SeekMode["Current"] = 1] = "Current";
     /** Seek from end of file (usually negative offset) */
     SeekMode[SeekMode["End"] = 2] = "End";
-})(SeekMode = exports.SeekMode || (exports.SeekMode = {}));
+})(SeekMode || (exports.SeekMode = SeekMode = {}));