naria2 - npm Package Compare versions

Comparing version 0.0.22 to 0.0.23

dist/index.d.ts

 import * as maria2_index from 'maria2/index';
 import { PartialDeep } from 'type-fest';
-import { Conn, Socket, Aria2ServerVersion, Aria2ServerGlobalStat } from 'maria2';
+import { Conn, Socket, Aria2ServerVersion, Aria2ServerGlobalStat, PreconfiguredSocket } from 'maria2';
 import { Aria2InputOptions } from '@naria2/options';
 export * from '@naria2/options';
-import { Emitter } from 'mitt';
 
-type Aria2TaskEvents = Record<`start` | `progress` | `pause` | `stop` | `complete` | `error`, Task>;
-type Aria2TorrentEvents = Record<`start` | `progress` | `pause` | `stop` | `complete` | `bt-complete` | `error`, Torrent>;
+type Aria2EventKeyPrefix = `start` | `pause` | `stop` | `complete` | `bt-complete` | `error`;
+interface ClientOptions {
+    secret?: string;
+    /**
+     * Timeout for each request (ms).
+     * @default 5000
+     * @public
+     */
+    timeout?: number;
+    /**
+     * Timeout for waiting socket (ms).
+     * @default 5000
+     * @public
+     */
+    openTimeout?: number;
+    /**
+     * Time interval for polling download status (ms).
+     *
+     * @default 1000
+     */
+    progressInterval?: number;
+}
+interface DownloadOptions {
+    position?: number;
+}
+interface TorrentFile {
+}
+interface TorrentPiece {
+    readonly length: number;
+    readonly missing: number;
+}
+
+type Aria2TaskEvents = Record<Exclude<Aria2EventKeyPrefix, 'bt-complete'>, Task>;
+type Aria2TorrentEvents = Record<Aria2EventKeyPrefix, Torrent>;
 declare class Task {
@@ -30,3 +61,4 @@ protected readonly client: Aria2Client;
     off<Key extends keyof Aria2TaskEvents>(key: Key, handler?: (param: Aria2TaskEvents[Key]) => void | Promise<void>): void;
-    waitComplete(): Promise<Task>;
+    watch(handler: (param: Task) => void | Promise<void>): Promise<Task>;
+    waitForCompletion(): Promise<Task>;
 }
@@ -37,4 +69,5 @@ declare class Torrent extends Task {
     constructor(client: Aria2Client, gid: string, following?: Torrent);
-    get state(): maria2_index.Aria2DownloadState;
+    get name(): string;
     get progress(): number;
+    updateStatus(): Promise<Pick<maria2_index.Aria2DownloadStatus, keyof maria2_index.Aria2DownloadStatus>>;
     get followedBy(): Torrent | undefined;
@@ -47,38 +80,22 @@ private setFollowedBy;
     off<Key extends keyof Aria2TorrentEvents>(key: Key, handler?: (param: Aria2TorrentEvents[Key]) => void | Promise<void>): void;
-    waitComplete(): Promise<Torrent>;
-}
-
-interface ClientOptions {
-    secret?: string;
+    watch(handler: (param: Torrent) => void | Promise<void>, target?: `complete` | `bt-complete`): Promise<Task>;
+    watchFollowedBy(handler: (param: Torrent) => void | Promise<void>, target?: `complete` | `bt-complete`): Promise<Torrent>;
     /**
-     * Timeout for each request (ms).
-     * @default 5000
-     * @public
-     */
-    timeout?: number;
-    /**
-     * Timeout for waiting socket (ms).
-     * @default 5000
-     * @public
-     */
-    openTimeout?: number;
-    /**
-     * Time interval for polling download status (ms).
+     * Wait for the full torrent download completion
      *
-     * @default 1000
+     * If this is a metadata torrent (used for downloading metadata), it has two steps:
+     *
+     * 1. Downloading the metadata
+     * 2. Downloading the actual data
+     *
+     * If this is a actual data torrent, it will just wait for the download compeltion
+     *
+     * @param target
+     * @returns
      */
-    progressInterval?: number;
+    waitForCompletion(target?: `complete` | `bt-complete`): Promise<Torrent>;
 }
-interface DownloadOptions {
-    position?: number;
-}
-interface TorrentFile {
-}
-interface TorrentPiece {
-    readonly length: number;
-    readonly missing: number;
-}
 
-type Aria2MonitorEvents = Record<`start:${string}` | `progress:${string}` | `pause:${string}` | `stop:${string}` | `complete:${string}` | `error:${string}`, Task> & Record<`bt-complete:${string}`, Torrent>;
-declare class Aria2Monitor implements Pick<Emitter<Aria2MonitorEvents>, 'on' | 'off'> {
+type Aria2MonitorEvents = Record<`${Exclude<Aria2EventKeyPrefix, 'bt-complete'>}:${string}`, Task> & Record<`bt-complete:${string}`, Torrent>;
+declare class Aria2Monitor {
     private readonly client;
@@ -88,3 +105,3 @@ private readonly disposables;
     private readonly map;
-    private readonly progressIds;
+    private readonly watchingIds;
     constructor(client: Aria2Client);
@@ -98,6 +115,7 @@ private get conn();
     listPaused(): Promise<Task[]>;
+    listStopped(): Promise<Task[]>;
     getTask(gid: string): Promise<Task>;
-    watchStatus(gid: string): Promise<Task>;
-    on<Key extends keyof Aria2MonitorEvents>(key: Key, handler: any): void;
-    off<Key extends keyof Aria2MonitorEvents>(key: Key, handler?: any): void;
+    watchStatus<T extends Task = Task>(gid: string, fn?: (task: T) => void | Promise<void>, target?: `complete` | `bt-complete`): Promise<Task>;
+    on<Key extends keyof Aria2MonitorEvents>(key: Key, handler: (param: Aria2MonitorEvents[Key]) => void | Promise<void>): void;
+    off<Key extends keyof Aria2MonitorEvents>(key: Key, handler?: (param: Aria2MonitorEvents[Key]) => void | Promise<void>): void;
     private onDownloadProgress;
@@ -141,6 +159,7 @@ private onDownloadStart;
     listPaused(): Promise<Task[]>;
-    listStopped(offset: number, num: number): Promise<maria2_index.Aria2DownloadStatus[]>;
+    listStopped(): Promise<Task[]>;
 }
-declare function createClient(_socket: Socket | Promise<Socket>, options?: ClientOptions): Promise<Aria2Client>;
+type MaybePromise<T> = T | Promise<T>;
+declare function createClient(_socket: MaybePromise<Socket | PreconfiguredSocket>, _options?: ClientOptions): Promise<Aria2Client>;
 
-export { Aria2Client, type ClientOptions, type DownloadOptions, Task, Torrent, type TorrentFile, type TorrentPiece, createClient };
+export { Aria2Client, type Aria2EventKeyPrefix, type ClientOptions, type DownloadOptions, Task, Torrent, type TorrentFile, type TorrentPiece, createClient };

package.json

 {
   "name": "naria2",
-  "version": "0.0.22",
-  "description": "High-level and Convenient BitTorrent Client based on aria2 JSON-RPC",
+  "version": "0.0.23",
+  "description": "Convenient BitTorrent Client based on the aria2 JSON-RPC",
   "keywords": [
@@ -60,3 +60,3 @@ "aria2",
     "type-fest": "^4.6.0",
-    "@naria2/options": "0.0.22"
+    "@naria2/options": "0.0.23"
   },
@@ -67,6 +67,6 @@ "devDependencies": {
     "ws": "^8.14.2",
-    "@naria2/node": "0.0.22"
+    "@naria2/node": "0.0.23"
   },
   "peerDependencies": {
-    "@naria2/node": "0.0.22"
+    "@naria2/node": "0.0.23"
   },
@@ -73,0 +73,0 @@ "peerDependenciesMeta": {

README.md

 # naria2
 
 [![version](https://img.shields.io/npm/v/naria2?label=naria2)](https://www.npmjs.com/package/naria2)
+[![version](https://img.shields.io/npm/v/naria2c?label=naria2c)](https://www.npmjs.com/package/naria2c)
+[![version](https://img.shields.io/npm/v/vite-plugin-naria2?label=vite-plugin-naria2)](https://www.npmjs.com/package/vite-plugin-naria2)
 [![CI](https://github.com/yjl9903/naria2/actions/workflows/ci.yml/badge.svg)](https://github.com/yjl9903/naria2/actions/workflows/ci.yml)
 
-High-level aria2 abstraction library for Node.
+Convenient BitTorrent Client based on the [aria2 JSON RPC Interface](https://aria2.github.io/manual/en/html/aria2c.html#rpc-interface) and [aria2c](https://aria2.github.io/manual/en/html/aria2c.html#aria2c-1) CLI application with Web UI.
 
-+ Simple BitTorrent downloading API
-+ Event bus for progress, state change, and so on
++ Download aria2 according to your platform
++ Convenient BitTorrent downloading API
++ Event bus used for watching progress, state change
++ Vite plugin which helps you develop aria2 client application
++ Web UI for aria2c (more features is working in progress)
 
+![home](./assets/home.png)
+
+## Cross-platform aria2c
+
+It is used in the same way as [aria2c](https://aria2.github.io/manual/en/html/aria2c.html#aria2c-1).
+
+```bash
+$ npm i -g naria2c
+
+$ naria2c --version
+naria2c/0.0.23
+--------------
+...
+
+$ naria2c --help
+```
+
+You can also launch a Web UI to manage aria2 using the `--ui` option. This feature is provided by this package, not the original aria2.
+
+```bash
+$ naria2c --ui
+...
+10/29 21:22:46 [NOTICE] WebUI is listening on the http://127.0.0.1:6801?port=6800&secret=123456
+...
+```
+
 ## Installation
@@ -63,2 +94,37 @@
 
+## Usage
+
+```ts
+import { createClient } from 'naria2'
+
+// Initialize a client
+const client = await createClient(
+  new WebSocket('ws://localhost:6800/jsonrpc')
+)
+
+// Start downloading a magnet
+const torrent = await client.downloadUri('...')
+
+// Watch metadata progress
+await torrent.watch((torrent) => {
+  console.log(`Downloading [MEATADATA]`)
+})
+// Watch torrent progress
+await torrent.watchFollowedBy((torrent) => {
+  console.log(`Downloading ${torrent.name}`)
+})
+
+// Shutdown client
+await client.shutdown()
+```
+
+Due to the implementation of [aria2](https://aria2.github.io/manual/en/html/index.html), the downloading progress of a magnet uri includes **two steps**:
+
+1. Download the torrent metadata which contains only a special file named `[METADATA]`;
+2. Download the torrent content itself.
+
+So that, in the above code, you should first wait for downloading metadata, and then wait for downloading the followed by task which is the torrent content itself.
+
+You can find an example using Node.js [here](https://github.com/yjl9903/naria2/blob/main/scripts/download.mjs).
+
 ## Credits
@@ -65,0 +131,0 @@

No alert changes

Improved metrics

Total package byte prevSize

63208

increased by17.7%

Lines of code

1337

increased by14.86%

Number of lines in readme file

138

increased by91.67%

Dependency changes

• + Added@naria2/node@0.0.23(transitive)

• + Added@naria2/options@0.0.23(transitive)

• - Removed@naria2/node@0.0.22(transitive)

• - Removed@naria2/options@0.0.22(transitive)

• Updated@naria2/options@0.0.23