@quatrain/worker 1.2.3 → 1.2.5

package/dist/FileSystem.d.ts

@@ -1,9 +1,45 @@
 import { FileType } from '@quatrain/storage';
+/**
+ * Utility class providing synchronous and asynchronous file system operations
+ * specifically tailored for the worker environment (e.g., managing temp folders, downloading remote files).
+ */
 export declare class FileSystem {
+    /**
+     * Prepares a clean processing directory, creating it along with required subdirectories (`images`, `vecto`).
+     * Any existing folder with the same name will be deleted first.
+     *
+     * @param folder - The base directory path to set up.
+     */
     static prepare(folder: string): void;
+    /**
+     * Synchronously creates a single directory.
+     *
+     * @param folder - The directory path.
+     */
     static makeFolder(folder: string): void;
+    /**
+     * Recursively and synchronously removes a folder and its entire contents.
+     *
+     * @param folder - The target directory to destroy.
+     * @param recursively - Whether to traverse and delete nested folders. Defaults to true.
+     * @throws {Error} If `recursively` is false but nested folders are encountered.
+     */
     static removeFolder(folder: string, recursively?: boolean): void;
+    /**
+     * Downloads a file from an external HTTP/HTTPS URL into the local filesystem.
+     *
+     * @param url - The remote resource URL.
+     * @param filepath - The local destination path.
+     * @returns A promise resolving when the download finishes.
+     * @throws {Error} If the HTTP request or stream fails.
+     */
     static downloadFile(url: string, filepath: string): Promise<unknown>;
+    /**
+     * Sanitizes a string to be used safely as a filename by replacing spaces with underscores.
+     *
+     * @param name - The original string.
+     * @returns The sanitized string.
+     */
     static safeString(name: string): string;
     /**
      * Upload file to public URL and return meta data

package/dist/FileSystem.js

@@ -43,7 +43,17 @@ const axios_1 = __importDefault(require("axios"));
 const Worker_1 = require("./Worker");
 const node_fetch_native_1 = __importDefault(require("node-fetch-native"));
 const ffmpeg = __importStar(require("fluent-ffmpeg"));
+/**
+ * Utility class providing synchronous and asynchronous file system operations
+ * specifically tailored for the worker environment (e.g., managing temp folders, downloading remote files).
+ */
 class FileSystem {
+    /**
+     * Prepares a clean processing directory, creating it along with required subdirectories (`images`, `vecto`).
+     * Any existing folder with the same name will be deleted first.
+     *
+     * @param folder - The base directory path to set up.
+     */
     static prepare(folder) {
         Worker_1.Worker.debug(`Setting up process folder ${folder}`);
         this.removeFolder(folder);
@@ -51,9 +61,21 @@ class FileSystem {
         node_fs_1.default.mkdirSync(folder + node_path_1.default.sep + 'images');
         node_fs_1.default.mkdirSync(folder + node_path_1.default.sep + 'vecto');
     }
+    /**
+     * Synchronously creates a single directory.
+     *
+     * @param folder - The directory path.
+     */
     static makeFolder(folder) {
         node_fs_1.default.mkdirSync(folder);
     }
+    /**
+     * Recursively and synchronously removes a folder and its entire contents.
+     *
+     * @param folder - The target directory to destroy.
+     * @param recursively - Whether to traverse and delete nested folders. Defaults to true.
+     * @throws {Error} If `recursively` is false but nested folders are encountered.
+     */
     static removeFolder(folder, recursively = true) {
         if (node_fs_1.default.existsSync(folder)) {
             node_fs_1.default.readdirSync(folder).forEach((element) => {
@@ -71,6 +93,14 @@ class FileSystem {
             node_fs_1.default.rmdirSync(folder);
         }
     }
+    /**
+     * Downloads a file from an external HTTP/HTTPS URL into the local filesystem.
+     *
+     * @param url - The remote resource URL.
+     * @param filepath - The local destination path.
+     * @returns A promise resolving when the download finishes.
+     * @throws {Error} If the HTTP request or stream fails.
+     */
     static async downloadFile(url, filepath) {
         try {
             Worker_1.Worker.debug(`Downloading file at ${url} to ${filepath}`);
@@ -89,6 +119,12 @@ class FileSystem {
             throw err;
         }
     }
+    /**
+     * Sanitizes a string to be used safely as a filename by replacing spaces with underscores.
+     *
+     * @param name - The original string.
+     * @returns The sanitized string.
+     */
     static safeString(name) {
         return name.replaceAll(/\s+/g, '_');
     }

package/dist/Helpers.d.ts

@@ -1,5 +1,9 @@
+/**
+ * General utility class providing common static helpers for workers.
+ */
 export declare class Helpers {
-    static FFMPEG: string;
+    /** Default absolute path to the system's FFmpeg binary. */
+    static FFMPEG: Promise<string>;
     /**
      * Generate a thubnail from a video file at given frame position
      * @param videoPath path to video file

package/dist/Helpers.js

@@ -2,8 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Helpers = void 0;
 const Worker_1 = require("./Worker");
+/**
+ * General utility class providing common static helpers for workers.
+ */
 class Helpers {
-    static FFMPEG = '/usr/bin/ffmpeg';
+    /** Default absolute path to the system's FFmpeg binary. */
+    static FFMPEG = Worker_1.Worker.getSystemCommandPath('ffmpeg');
     /**
      * Generate a thubnail from a video file at given frame position
      * @param videoPath path to video file
@@ -28,7 +32,7 @@ class Helpers {
             '-y',
         ];
         Worker_1.Worker.info(`Generating Thumbnail : ${outputPath}`);
-        return await Worker_1.Worker.execPromise(Helpers.FFMPEG, ffmpegParams);
+        return await Worker_1.Worker.execPromise(await Helpers.FFMPEG, ffmpegParams);
     };
 }
 exports.Helpers = Helpers;

package/dist/Worker.d.ts

@@ -1,7 +1,13 @@
 import { Core } from '@quatrain/core';
 import { HandlerParameters } from './types/HandlerParameters';
+/**
+ * The core orchestration class for background task workers.
+ * Manages event reporting, child process execution, and queue listening.
+ */
 export declare class Worker extends Core {
+    /** The HTTP endpoint used to push worker status events. */
     static endpoint: string;
+    /** Dedicated logger instance for the worker subsystem. */
     static readonly logger: any;
     /**
      * Execute an external command in a promise

package/dist/Worker.js

@@ -8,8 +8,14 @@ const core_1 = require("@quatrain/core");
 const node_os_1 = __importDefault(require("node:os"));
 const axios_1 = __importDefault(require("axios"));
 const node_child_process_1 = require("node:child_process");
+/**
+ * The core orchestration class for background task workers.
+ * Manages event reporting, child process execution, and queue listening.
+ */
 class Worker extends core_1.Core {
+    /** The HTTP endpoint used to push worker status events. */
     static endpoint = '';
+    /** Dedicated logger instance for the worker subsystem. */
     static logger = this.addLogger('Worker');
     /**
      * Execute an external command in a promise

package/dist/Worker.test.js

@@ -8,7 +8,7 @@ const axios_1 = __importDefault(require("axios"));
 const node_child_process_1 = require("node:child_process");
 // Mock dependencies
 jest.mock('axios');
-jest.mock('child_process');
+jest.mock('node:child_process');
 const mockedAxios = axios_1.default;
 const mockedSpawn = node_child_process_1.spawn;
 describe('Worker', () => {
@@ -153,6 +153,7 @@ describe('Worker', () => {
             await expect(Worker_1.Worker.execPromise('ls', ['-la'], '/tmp')).resolves.toBeUndefined();
             expect(mockedSpawn).toHaveBeenCalledWith('ls', ['-la'], {
                 cwd: '/tmp',
+                shell: false,
             });
         });
         it('should reject on command failure', async () => {
@@ -191,6 +192,7 @@ describe('Worker', () => {
             await Worker_1.Worker.execPromise('echo', ['test']);
             expect(mockedSpawn).toHaveBeenCalledWith('echo', ['test'], {
                 cwd: process.cwd(),
+                shell: false,
             });
         });
         it('should pass arguments to command', async () => {
@@ -208,6 +210,7 @@ describe('Worker', () => {
             await Worker_1.Worker.execPromise('command', args, '/custom/path');
             expect(mockedSpawn).toHaveBeenCalledWith('command', args, {
                 cwd: '/custom/path',
+                shell: false,
             });
         });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quatrain/worker",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "Container Worker helpers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -34,9 +34,9 @@
     "typescript": "^5.1.5"
   },
   "dependencies": {
-    "@quatrain/core": "^1.2.5",
-    "@quatrain/queue": "^1.2.2",
-    "@quatrain/storage": "^1.2.3",
+    "@quatrain/core": "^1.2.9",
+    "@quatrain/queue": "^1.2.3",
+    "@quatrain/storage": "^1.2.8",
     "axios": "^1.7.7",
     "fluent-ffmpeg": "^2.1.2",
     "fs-extra": "^11.2.0",

package/src/FileSystem.ts

@@ -6,7 +6,17 @@ import fetch from 'node-fetch-native'
 import * as ffmpeg from 'fluent-ffmpeg'
 import { FileType } from '@quatrain/storage'
 
+/**
+ * Utility class providing synchronous and asynchronous file system operations
+ * specifically tailored for the worker environment (e.g., managing temp folders, downloading remote files).
+ */
 export class FileSystem {
+   /**
+    * Prepares a clean processing directory, creating it along with required subdirectories (`images`, `vecto`).
+    * Any existing folder with the same name will be deleted first.
+    * 
+    * @param folder - The base directory path to set up.
+    */
    static prepare(folder: string) {
       Worker.debug(`Setting up process folder ${folder}`)
       this.removeFolder(folder)
@@ -16,10 +26,22 @@ export class FileSystem {
       fs.mkdirSync(folder + path.sep + 'vecto')
    }
 
+   /**
+    * Synchronously creates a single directory.
+    * 
+    * @param folder - The directory path.
+    */
    static makeFolder(folder: string) {
       fs.mkdirSync(folder)
    }
 
+   /**
+    * Recursively and synchronously removes a folder and its entire contents.
+    * 
+    * @param folder - The target directory to destroy.
+    * @param recursively - Whether to traverse and delete nested folders. Defaults to true.
+    * @throws {Error} If `recursively` is false but nested folders are encountered.
+    */
    static removeFolder(folder: string, recursively = true) {
       if (fs.existsSync(folder)) {
          fs.readdirSync(folder).forEach((element) => {
@@ -38,6 +60,14 @@ export class FileSystem {
       }
    }
 
+   /**
+    * Downloads a file from an external HTTP/HTTPS URL into the local filesystem.
+    * 
+    * @param url - The remote resource URL.
+    * @param filepath - The local destination path.
+    * @returns A promise resolving when the download finishes.
+    * @throws {Error} If the HTTP request or stream fails.
+    */
    static async downloadFile(url: string, filepath: string) {
       try {
          Worker.debug(`Downloading file at ${url} to ${filepath}`)
@@ -58,6 +88,12 @@ export class FileSystem {
       }
    }
 
+   /**
+    * Sanitizes a string to be used safely as a filename by replacing spaces with underscores.
+    * 
+    * @param name - The original string.
+    * @returns The sanitized string.
+    */
    static safeString(name: string) {
       return name.replaceAll(/\s+/g, '_')
    }

package/src/Helpers.ts

@@ -1,8 +1,12 @@
 import { Worker } from './Worker'
 import path from 'node:path'
 
+/**
+ * General utility class providing common static helpers for workers.
+ */
 export class Helpers {
-   static FFMPEG = '/usr/bin/ffmpeg'
+   /** Default absolute path to the system's FFmpeg binary. */
+   static FFMPEG = Worker.getSystemCommandPath('ffmpeg')
 
    /**
     * Generate a thubnail from a video file at given frame position
@@ -35,6 +39,6 @@ export class Helpers {
 
       Worker.info(`Generating Thumbnail : ${outputPath}`)
 
-      return await Worker.execPromise(Helpers.FFMPEG, ffmpegParams)
+      return await Worker.execPromise(await Helpers.FFMPEG, ffmpegParams)
    }
 }

package/src/Worker.test.ts

@@ -4,7 +4,7 @@ import { spawn } from 'node:child_process'
 
 // Mock dependencies
 jest.mock('axios')
-jest.mock('child_process')
+jest.mock('node:child_process')
 
 const mockedAxios = axios as jest.Mocked<typeof axios>
 const mockedSpawn = spawn as jest.MockedFunction<typeof spawn>
@@ -209,6 +209,7 @@ describe('Worker', () => {
 
          expect(mockedSpawn).toHaveBeenCalledWith('ls', ['-la'], {
             cwd: '/tmp',
+            shell: false,
          })
       })
 
@@ -256,6 +257,7 @@ describe('Worker', () => {
 
          expect(mockedSpawn).toHaveBeenCalledWith('echo', ['test'], {
             cwd: process.cwd(),
+            shell: false,
          })
       })
 
@@ -277,6 +279,7 @@ describe('Worker', () => {
 
          expect(mockedSpawn).toHaveBeenCalledWith('command', args, {
             cwd: '/custom/path',
+            shell: false,
          })
       })
    })

package/src/Worker.ts

@@ -4,8 +4,14 @@ import axios from 'axios'
 import { spawn } from 'node:child_process'
 import { HandlerParameters } from './types/HandlerParameters'
 
+/**
+ * The core orchestration class for background task workers.
+ * Manages event reporting, child process execution, and queue listening.
+ */
 export class Worker extends Core {
+   /** The HTTP endpoint used to push worker status events. */
    static endpoint: string = ''
+   /** Dedicated logger instance for the worker subsystem. */
    static readonly logger = this.addLogger('Worker')
 
    /**