@nitpicker/core 0.18.0 → 0.19.0

package/lib/nitpicker.d.ts

@@ -32,8 +32,8 @@ export { definePlugin } from './hooks/define-plugin.js';
  * ```ts
  * import { Nitpicker } from '@nitpicker/core';
  *
- * // Open an existing archive
- * const nitpicker = await Nitpicker.open('./example.nitpicker');
+ * // Open an existing archive — `Symbol.asyncDispose` closes it on scope exit
+ * await using nitpicker = await Nitpicker.open('./example.nitpicker');
  *
  * // Run all configured analyze plugins
  * await nitpicker.analyze();
@@ -56,6 +56,11 @@ export declare class Nitpicker extends EventEmitter<NitpickerEvent> {
      *   Use {@link Nitpicker.open} for a convenient static factory.
      */
     constructor(archive: Archive);
+    /**
+     * Enables `await using nitpicker = ...`. Delegates to the wrapped
+     * archive's `Symbol.asyncDispose` (i.e. {@link Archive.close}).
+     */
+    [Symbol.asyncDispose](): Promise<void>;
     /**
      * Runs all configured analyze plugins (or a filtered subset) against
      * every page in the archive.
@@ -151,6 +156,10 @@ export declare class Nitpicker extends EventEmitter<NitpickerEvent> {
      * the archive to a temporary directory, opens the SQLite database, and
      * enables plugin data access.
      * @param filePath - Path to the `.nitpicker` archive file.
+     * @param onExtractProgress - Forwarded to `Archive.open` — called during
+     *   the untar step with bytes read so far and the archive's total size
+     *   (issue #294: a large archive's extraction can take tens of seconds
+     *   with no other signal it isn't hung).
      * @returns A new Nitpicker instance backed by the opened archive.
      * @example
      * ```ts
@@ -159,5 +168,5 @@ export declare class Nitpicker extends EventEmitter<NitpickerEvent> {
      * await nitpicker.write();
      * ```
      */
-    static open(filePath: string): Promise<Nitpicker>;
+    static open(filePath: string, onExtractProgress?: (readBytes: number, totalBytes: number) => void): Promise<Nitpicker>;
 }

package/lib/nitpicker.js

@@ -89,8 +89,8 @@ function formatTemplateClassificationProgress(event) {
  * ```ts
  * import { Nitpicker } from '@nitpicker/core';
  *
- * // Open an existing archive
- * const nitpicker = await Nitpicker.open('./example.nitpicker');
+ * // Open an existing archive — `Symbol.asyncDispose` closes it on scope exit
+ * await using nitpicker = await Nitpicker.open('./example.nitpicker');
  *
  * // Run all configured analyze plugins
  * await nitpicker.analyze();
@@ -132,6 +132,13 @@ export class Nitpicker extends EventEmitter {
         super();
         this.#archive = archive;
     }
+    /**
+     * Enables `await using nitpicker = ...`. Delegates to the wrapped
+     * archive's `Symbol.asyncDispose` (i.e. {@link Archive.close}).
+     */
+    async [Symbol.asyncDispose]() {
+        await this.#archive.close();
+    }
     /**
      * Runs all configured analyze plugins (or a filtered subset) against
      * every page in the archive.
@@ -561,6 +568,10 @@ export class Nitpicker extends EventEmitter {
      * the archive to a temporary directory, opens the SQLite database, and
      * enables plugin data access.
      * @param filePath - Path to the `.nitpicker` archive file.
+     * @param onExtractProgress - Forwarded to `Archive.open` — called during
+     *   the untar step with bytes read so far and the archive's total size
+     *   (issue #294: a large archive's extraction can take tens of seconds
+     *   with no other signal it isn't hung).
      * @returns A new Nitpicker instance backed by the opened archive.
      * @example
      * ```ts
@@ -569,8 +580,12 @@ export class Nitpicker extends EventEmitter {
      * await nitpicker.write();
      * ```
      */
-    static async open(filePath) {
-        const archive = await Archive.open({ filePath, openPluginData: true });
+    static async open(filePath, onExtractProgress) {
+        const archive = await Archive.open({
+            filePath,
+            openPluginData: true,
+            onExtractProgress,
+        });
         return new Nitpicker(archive);
     }
 }

package/package.json

@@ -1,9 +1,12 @@
 {
 	"name": "@nitpicker/core",
-	"version": "0.18.0",
+	"version": "0.19.0",
 	"description": "Plugin-based page analysis engine for Nitpicker",
 	"author": "D-ZERO",
 	"license": "Apache-2.0",
+	"engines": {
+		"node": ">=24.11.0"
+	},
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/d-zero-dev/nitpicker.git",
@@ -27,14 +30,14 @@
 		"clean": "tsc --build --clean"
 	},
 	"dependencies": {
-		"@d-zero/dealer": "1.10.4",
-		"@d-zero/page-cluster": "0.5.6",
-		"@d-zero/shared": "0.22.5",
-		"@nitpicker/crawler": "0.18.0",
-		"@nitpicker/types": "0.18.0",
+		"@d-zero/dealer": "1.12.0",
+		"@d-zero/page-cluster": "0.6.0",
+		"@d-zero/shared": "0.23.0",
+		"@nitpicker/crawler": "0.19.0",
+		"@nitpicker/types": "0.19.0",
 		"ansi-colors": "4.1.3",
-		"cosmiconfig": "9.0.2",
+		"cosmiconfig": "10.0.0",
 		"jsdom": "29.1.1"
 	},
-	"gitHead": "9be5b756adb5bfaaa3e7fd52fabc93213c7e0b50"
+	"gitHead": "b79b5c304820d924168a139e7148e0593c29fe1c"
 }