@spinajs/fs 2.0.481 → 2.0.484

package/lib/cjs/file-hasher.js

@@ -14,40 +14,132 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultFileHasher = void 0;
 const di_1 = require("@spinajs/di");
+const configuration_1 = require("@spinajs/configuration");
 const crypto_1 = __importDefault(require("crypto"));
 const node_fs_1 = __importDefault(require("node:fs"));
 const exceptions_1 = require("@spinajs/exceptions");
 const interfaces_js_1 = require("./interfaces.js");
+/**
+ * Hard fallback algorithm used when nothing is provided and no config default is set.
+ */
+const DEFAULT_ALGORITHM = 'sha256';
+/**
+ * Default {@link FileHasher} implementation backed by node's `crypto` module.
+ *
+ * The algorithm is fixed per instance and provided as the first constructor
+ * argument ( eg. `DI.resolve(FileHasher, ['md5'])` ). When no algorithm is
+ * given it falls back to the value configured under `fs.hasher.defaultAlgorithm`,
+ * and finally to {@link DEFAULT_ALGORITHM} ( sha256 ).
+ *
+ * Instances are cached per algorithm via {@link PerInstanceCheck} /
+ * {@link __checkInstance__}, so resolving the same algorithm twice reuses the
+ * same hasher while different algorithms get distinct instances.
+ */
 let DefaultFileHasher = class DefaultFileHasher extends interfaces_js_1.FileHasher {
+    /**
+     * Per-instance cache predicate used by {@link PerInstanceCheck}.
+     *
+     * Returns `true` when this instance was created for the algorithm requested in
+     * `creationOptions`. The requested algorithm is resolved exactly like the
+     * constructor does ( explicit arg, else the configured default ), so cached
+     * instances match reliably.
+     *
+     * @param creationOptions constructor arguments the container is resolving with
+     */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     __checkInstance__(creationOptions) {
         // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-        const requestedAlgo = creationOptions?.[0]?.alghoritm ?? 'sha256';
-        return this.Alghoritm === requestedAlgo;
+        const requestedAlgo = creationOptions?.[0] ?? this.ConfiguredAlgorithm;
+        return this.Algorithm === requestedAlgo;
     }
-    constructor(Alghoritm, HashOptions) {
+    /**
+     * @param Algorithm hash algorithm to use ( eg. `sha256`, `md5` ). When omitted,
+     *                  the configured default ( `fs.hasher.defaultAlgorithm` ) or
+     *                  sha256 is used.
+     * @param HashOptions optional node `crypto` hash options ( eg. `outputLength`
+     *                    for XOF algorithms such as shake256 )
+     */
+    constructor(Algorithm, HashOptions) {
         super();
-        this.Alghoritm = Alghoritm;
+        this.Algorithm = Algorithm;
         this.HashOptions = HashOptions;
-        this.Alghoritm = this.Alghoritm || 'sha256';
+        this.Algorithm = this.Algorithm || this.ConfiguredAlgorithm;
     }
-    async hash(pathToFile) {
+    /**
+     * Creates a `crypto.Hash` for the configured algorithm.
+     *
+     * The algorithm is validated against the platform's supported hashes first so
+     * an unsupported/typo'd algorithm produces a clear {@link IOFail} instead of a
+     * cryptic native crypto error.
+     *
+     * @throws {IOFail} when the configured algorithm is not supported
+     */
+    createHasher() {
+        const algo = this.Algorithm;
+        if (!crypto_1.default.getHashes().includes(algo)) {
+            throw new exceptions_1.IOFail(`Unsupported hash algorithm '${algo}'. Use one of: ${crypto_1.default.getHashes().join(', ')}`);
+        }
+        return crypto_1.default.createHash(algo, this.HashOptions);
+    }
+    /**
+     * Hashes the content of a file by streaming it through the hash.
+     *
+     * @param pathToFile absolute path to the file to hash
+     * @param encoding digest output encoding ( default `hex` )
+     * @returns the digest string in the requested encoding
+     * @throws {IOFail} when the file does not exist, the algorithm is unsupported,
+     *                  or the file cannot be read
+     */
+    async hash(pathToFile, encoding = 'hex') {
         if (!node_fs_1.default.existsSync(pathToFile)) {
             throw new exceptions_1.IOFail(`File ${pathToFile} not exists`);
         }
-        if (!this.Alghoritm) {
-            throw new exceptions_1.IOFail(`Hashing algorithm is not specified for file hasher. Please provide algorithm as constructor parameter or set default algorithm in configuration`);
-        }
-        const algo = crypto_1.default.createHash(this.Alghoritm, this.HashOptions);
+        return this.digestStream(node_fs_1.default.createReadStream(pathToFile), encoding, (err) => new exceptions_1.IOFail(`Cannot read file ${pathToFile} for hashing`, err));
+    }
+    /**
+     * Consumes a readable stream through a fresh hasher and resolves with the
+     * digest. Stream errors are wrapped by `wrapError` so file and raw-stream
+     * callers surface their own context.
+     */
+    digestStream(stream, encoding, wrapError) {
+        const hasher = this.createHasher();
         return new Promise((resolve, reject) => {
-            node_fs_1.default.createReadStream(pathToFile)
-                .on('data', (data) => algo.update(data))
-                .on('end', () => resolve(algo.digest('hex')))
-                .on('error', (err) => reject(err));
+            stream
+                .on('data', (data) => hasher.update(data))
+                .on('end', () => resolve(hasher.digest(encoding)))
+                .on('error', (err) => reject(wrapError(err)));
         });
     }
+    /**
+     * Hashes raw in-memory data.
+     *
+     * @param data string or binary data to hash
+     * @param encoding digest output encoding ( default `hex` )
+     * @returns the digest string in the requested encoding
+     * @throws {IOFail} when the configured algorithm is unsupported
+     */
+    async hashData(data, encoding = 'hex') {
+        const hasher = this.createHasher();
+        hasher.update(data);
+        return hasher.digest(encoding);
+    }
+    /**
+     * Hashes the content of a readable stream by consuming it to the end.
+     *
+     * @param stream readable stream to consume
+     * @param encoding digest output encoding ( default `hex` )
+     * @returns the digest string in the requested encoding
+     * @throws {IOFail} when the configured algorithm is unsupported or the stream errors
+     */
+    async hashStream(stream, encoding = 'hex') {
+        return this.digestStream(stream, encoding, (err) => new exceptions_1.IOFail(`Error while hashing stream`, err));
+    }
 };
 exports.DefaultFileHasher = DefaultFileHasher;
+__decorate([
+    (0, configuration_1.Config)('fs.hasher.defaultAlgorithm', { defaultValue: DEFAULT_ALGORITHM }),
+    __metadata("design:type", String)
+], DefaultFileHasher.prototype, "ConfiguredAlgorithm", void 0);
 exports.DefaultFileHasher = DefaultFileHasher = __decorate([
     (0, di_1.Injectable)(interfaces_js_1.FileHasher),
     (0, di_1.PerInstanceCheck)(),

package/lib/cjs/file-hasher.js.map

@@ -1 +1 @@
-{"version":3,"file":"file-hasher.js","sourceRoot":"","sources":["../../src/file-hasher.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,oCAA2D;AAC3D,oDAA4B;AAC5B,sDAAyB;AACzB,oDAA6C;AAC7C,mDAA6C;AAItC,IAAM,iBAAiB,GAAvB,MAAM,iBAAkB,SAAQ,0BAAU;IAC/C,8DAA8D;IACvD,iBAAiB,CAAC,eAAoB;QAC3C,sEAAsE;QACtE,MAAM,aAAa,GAAG,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,IAAI,QAAQ,CAAC;QAClE,OAAO,IAAI,CAAC,SAAS,KAAK,aAAa,CAAC;IAC1C,CAAC;IAID,YAAmB,SAAkB,EAAS,WAAgC;QAC5E,KAAK,EAAE,CAAC;QADS,cAAS,GAAT,SAAS,CAAS;QAAS,gBAAW,GAAX,WAAW,CAAqB;QAG5E,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,QAAQ,CAAC;IAC9C,CAAC;IAEM,KAAK,CAAC,IAAI,CAAC,UAAkB;QAClC,IAAI,CAAC,iBAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,mBAAM,CAAC,QAAQ,UAAU,aAAa,CAAC,CAAC;QACpD,CAAC;QAED,IAAG,CAAC,IAAI,CAAC,SAAS,EAAC,CAAC;YAClB,MAAM,IAAI,mBAAM,CAAC,iJAAiJ,CAAC,CAAC;QACtK,CAAC;QAED,MAAM,IAAI,GAAG,gBAAM,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAEjE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,iBAAE,CAAC,gBAAgB,CAAC,UAAU,CAAC;iBAC5B,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;iBACvC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;iBAC5C,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AAlCY,8CAAiB;4BAAjB,iBAAiB;IAF7B,IAAA,eAAU,EAAC,0BAAU,CAAC;IACtB,IAAA,qBAAgB,GAAE;;GACN,iBAAiB,CAkC7B"}
+{"version":3,"file":"file-hasher.js","sourceRoot":"","sources":["../../src/file-hasher.ts"],"names":[],"mappings":"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"}

package/lib/cjs/file-info.d.ts

@@ -1,11 +1,100 @@
-import { Log } from '@spinajs/log';
+import { ChildProcessWithoutNullStreams } from 'node:child_process';
+import { Log } from '@spinajs/log-common';
 import { FileInfoService, IFileInfo } from './interfaces.js';
+import { DateTime } from 'luxon';
+/**
+ * A single extracted metadata value.
+ */
+type ExifValue = string | number | DateTime;
+/**
+ * Resolves the path to the exiftool binary.
+ *
+ * Prefers the vendored binary shipped with the `exiftool-vendored` platform
+ * packages ( no system installation required ), and falls back to `exiftool`
+ * available on PATH.
+ */
+export declare function resolveExifToolPath(): Promise<string>;
+/**
+ * Default {@link FileInfoService} implementation backed by the `exiftool`
+ * command line tool.
+ *
+ * The binary is auto-resolved ( vendored, then PATH ) unless overridden with
+ * the `fs.fileInfo.exifToolPath` configuration key. The invocation is bounded
+ * by the `fs.fileInfo.timeout` configuration ( default {@link DEFAULT_TIMEOUT} ).
+ */
 export declare class DefaultFileInfo extends FileInfoService {
     protected Log: Log;
+    /**
+     * Optional exiftool binary path override from configuration. When unset, the
+     * binary is auto-resolved via {@link resolveExifToolPath}.
+     */
+    protected ConfiguredPath?: string;
+    /**
+     * Timeout ( ms ) for the exiftool process, from configuration.
+     */
+    protected Timeout: number;
+    /**
+     * exiftool arguments controlling extraction breadth, from configuration
+     * ( default {@link DEFAULT_ARGS} ). The file spec ( path or `-` ) is appended
+     * automatically. NOTE: some flags ( eg. `-G` ) change the output tag names.
+     */
+    protected ExifArgs: string[];
+    /**
+     * Auto-resolved exiftool binary path, cached after first use.
+     */
+    protected ExifToolPath: string;
+    /**
+     * Extracts file information from a file on disk.
+     *
+     * @param pathToFile absolute path to the file
+     * @throws {IOFail} when the file does not exist or exiftool fails
+     */
     getInfo(pathToFile: string): Promise<IFileInfo>;
-    protected spawnExifProcess(file: string): Promise<string>;
-    protected getMetadata(file: string): Promise<{
-        [key: string]: string | number;
-    }>;
+    /**
+     * Extracts file information from a readable stream by piping its content to
+     * exiftool via stdin ( `exiftool -n -` ).
+     *
+     * @param stream readable stream with the file content
+     * @throws {IOFail} when exiftool fails or the stream errors
+     */
+    getInfoFromStream(stream: NodeJS.ReadableStream): Promise<IFileInfo>;
+    /**
+     * Resolves the exiftool binary path, preferring the configured override.
+     */
+    protected binaryPath(): Promise<string>;
+    /**
+     * Spawns the exiftool process. Extracted so it can be overridden ( eg. in tests ).
+     */
+    protected spawnExif(binary: string, args: string[]): ChildProcessWithoutNullStreams;
+    /**
+     * Runs exiftool against a file spec ( a path, or `-` for stdin ) and returns
+     * its stdout.
+     *
+     * Success/failure is determined by the process exit code ( not by the mere
+     * presence of stderr, which exiftool uses for non-fatal warnings ). The call
+     * is bounded by {@link Timeout} and any failure is surfaced as {@link IOFail}.
+     *
+     * @param fileArg file path or `-` to read from stdin
+     * @param input optional readable stream piped to the process stdin
+     */
+    protected runExifTool(fileArg: string, input?: NodeJS.ReadableStream): Promise<string>;
+    /**
+     * Parses raw exiftool text output into a `{ normalisedTag: value }` map with
+     * EVERY emitted tag ( nothing is filtered ).
+     *
+     * Each line is split on the FIRST `': '` only, so values that themselves
+     * contain `': '` are preserved. Values are coerced by {@link coerceValue}
+     * ( numbers and date-shaped strings ).
+     */
+    protected parseMetadata(raw: string): Record<string, ExifValue>;
+    /**
+     * Projects a parsed metadata map onto {@link IFileInfo}.
+     *
+     * Every extracted tag is promoted: known tags via their {@link TAG_ALIASES}
+     * friendly field name, all others under their PascalCased tag name. The full
+     * unmodified map is always available under `Raw`.
+     */
+    protected toFileInfo(metadata: Record<string, ExifValue>): IFileInfo;
 }
+export {};
 //# sourceMappingURL=file-info.d.ts.map

package/lib/cjs/file-info.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-info.d.ts","sourceRoot":"","sources":["../../src/file-info.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,GAAG,EAAU,MAAM,cAAc,CAAC;AAG3C,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AA4C7D,qBACa,eAAgB,SAAQ,eAAe;IAElD,SAAS,CAAC,GAAG,EAAG,GAAG,CAAC;IAEP,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;cAsB5C,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;cAa/C,WAAW,CAAC,IAAI,EAAE,MAAM;;;CAsCzC"}
+{"version":3,"file":"file-info.d.ts","sourceRoot":"","sources":["../../src/file-info.ts"],"names":[],"mappings":"AACA,OAAO,EAAS,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AAI3E,OAAO,EAAE,GAAG,EAAU,MAAM,qBAAqB,CAAC;AAGlD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAcjC;;GAEG;AACH,KAAK,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAmF5C;;;;;;GAMG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAa3D;AAED;;;;;;;GAOG;AACH,qBACa,eAAgB,SAAQ,eAAe;IAElD,SAAS,CAAC,GAAG,EAAG,GAAG,CAAC;IAEpB;;;OAGG;IAEH,SAAS,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAElC;;OAEG;IAEH,SAAS,CAAC,OAAO,EAAG,MAAM,CAAC;IAE3B;;;;OAIG;IAEH,SAAS,CAAC,QAAQ,EAAG,MAAM,EAAE,CAAC;IAE9B;;OAEG;IACH,SAAS,CAAC,YAAY,EAAG,MAAM,CAAC;IAEhC;;;;;OAKG;IACU,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAS5D;;;;;;OAMG;IACU,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC;IAKjF;;OAEG;cACa,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAa7C;;OAEG;IACH,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,8BAA8B;IAInF;;;;;;;;;;OAUG;cACa,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IA8C5F;;;;;;;OAOG;IACH,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC;IAqB/D;;;;;;OAMG;IACH,SAAS,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,SAAS;CAarE"}