@jmlq/logger-plugin-fs 0.1.0-alpha.0 → 0.1.0-alpha.10

package/dist/infrastructure/adapters/system-file-path.adapter.js

@@ -0,0 +1,141 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SystemFilePathAdapter = void 0;
+const path = __importStar(require("path"));
+const value_objects_1 = require("../../domain/value-objects");
+/**
+ * SystemFilePathAdapter
+ * --------------------
+ * Adapter de infraestructura que implementa IFilePathPort usando el módulo `path`
+ * del entorno de ejecución (típicamente Node.js).
+ *
+ * Responsabilidad:
+ * - Aceptar rutas crudas (relativas o absolutas).
+ * - Normalizar y resolver siempre a una ruta absoluta.
+ * - Construir y transformar el Value Object FilePath de forma consistente.
+ *
+ * Nota de diseño:
+ * - Este adapter centraliza TODA la lógica "dependiente del sistema" (path/OS).
+ * - El dominio no debería usar `path.*` directamente.
+ */
+class SystemFilePathAdapter {
+    // ---------------------------------------------------------------------------
+    // Creación: desde input crudo
+    // ---------------------------------------------------------------------------
+    /**
+     * Crea un FilePath desde una ruta cruda (relativa o absoluta).
+     * La implementación:
+     * - valida input
+     * - normaliza
+     * - resuelve a absoluta (path.resolve)
+     */
+    fromRaw(inputPath) {
+        // Validación de entrada: evita valores nulos, no-string o vacíos.
+        if (typeof inputPath !== "string") {
+            throw new Error("SystemFilePathAdapter.fromRaw: inputPath must be a string");
+        }
+        const trimmed = inputPath.trim();
+        if (!trimmed) {
+            throw new Error("SystemFilePathAdapter.fromRaw: inputPath cannot be empty or whitespace");
+        }
+        // Importante: NO resolvemos aquí y también en buildFromAnyPath.
+        // Reducimos redundancia: delegamos la normalización/resolución en un único helper.
+        return this.buildFromAnyPath(trimmed);
+    }
+    // ---------------------------------------------------------------------------
+    // Transformaciones: derivar nuevas rutas desde un FilePath existente
+    // ---------------------------------------------------------------------------
+    /**
+     * Une segmentos a la ruta base.
+     *
+     * Nota importante:
+     * - Aquí es clave definir semántica. Para evitar el caso raro:
+     *     "/logs/app.log" + "x" -> "/logs/app.log/x"
+     *   unimos los segmentos al DIRECTORIO del FilePath.
+     *
+     * Si tu intención era tratar FilePath como "basePath" que puede ser directorio,
+     * entonces tu VO debería representar directorios explícitamente.
+     */
+    join(filePath, ...segments) {
+        // Unimos respecto al directorio del archivo (semántica segura).
+        const fullPath = path.join(filePath.directory, ...segments);
+        return this.buildFromAnyPath(fullPath);
+    }
+    // ---------------------------------------------------------------------------
+    // Helper privado: construcción consistente de IFilePathProps
+    // ---------------------------------------------------------------------------
+    /**
+     * Construye un FilePath resolviendo y normalizando en UN SOLO lugar.
+     *
+     * Redundancia corregida:
+     * - Antes se hacía path.resolve() en métodos públicos y también en el builder.
+     * - Ahora todos pasan por este helper y aquí se aplica resolve/normalize.
+     */
+    buildFromAnyPath(anyPath) {
+        const raw = anyPath.trim();
+        const isDirHint = /[\\\/]$/.test(raw);
+        // Resolver a absoluto y normalizar (maneja ., .., separadores OS, etc.)
+        const normalized = path.resolve(anyPath);
+        if (isDirHint) {
+            // Representa directorio
+            return new value_objects_1.FilePath({
+                kind: "dir",
+                absolutePath: normalized,
+                directory: normalized, // para dirs, directory = sí mismo
+                filename: null,
+                extension: null,
+                basename: null,
+            });
+        }
+        // Derivar partes a partir de la ruta normalizada.
+        const directory = path.dirname(normalized);
+        const filename = path.basename(normalized);
+        const extension = path.extname(normalized);
+        const basename = path.basename(normalized, extension);
+        // Props canónicas del VO.
+        const props = {
+            kind: "file",
+            absolutePath: normalized,
+            directory,
+            filename,
+            extension,
+            basename,
+        };
+        // Crear VO: aquí el dominio puede validar invariantes adicionales si lo deseas.
+        return new value_objects_1.FilePath(props);
+    }
+}
+exports.SystemFilePathAdapter = SystemFilePathAdapter;

package/dist/infrastructure/errors/file-operation.error.d.ts

@@ -0,0 +1,28 @@
+import { FileOperation, FileOperationErrorOptions, FsErrorScope } from "./types";
+/**
+ * Error especializado para fallos de operaciones de filesystem.
+ *
+ * Encapsula errores de I/O (read, write, delete, mkdir, move) agregando
+ * contexto técnico relevante:
+ *   - operation: operación de filesystem que falló.
+ *   - filePath: ruta afectada (si aplica).
+ *   - cause: error original que provocó el fallo.
+ *   - scope: origen del error (por ejemplo, "fs-plugin").
+ *
+ * Su propósito es:
+ *   - Normalizar errores de filesystem dentro del plugin FS.
+ *   - Evitar el uso de Error genérico sin contexto.
+ *   - Facilitar logging, debugging y traducción a errores de capas superiores.
+ *
+ * No representa errores de dominio ni de configuración; solo fallos de I/O.
+ */
+export declare class FileOperationError extends Error {
+    readonly name = "FileOperationError";
+    readonly scope?: FsErrorScope;
+    readonly operation: FileOperation;
+    readonly filePath?: string;
+    readonly cause?: unknown;
+    constructor(opts: FileOperationErrorOptions);
+    static create(operation: FileOperation, filePath?: string, cause?: unknown): FileOperationError;
+    static fs(operation: FileOperation, filePath?: string, cause?: unknown): FileOperationError;
+}

package/dist/infrastructure/errors/file-operation.error.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileOperationError = void 0;
+/**
+ * Error especializado para fallos de operaciones de filesystem.
+ *
+ * Encapsula errores de I/O (read, write, delete, mkdir, move) agregando
+ * contexto técnico relevante:
+ *   - operation: operación de filesystem que falló.
+ *   - filePath: ruta afectada (si aplica).
+ *   - cause: error original que provocó el fallo.
+ *   - scope: origen del error (por ejemplo, "fs-plugin").
+ *
+ * Su propósito es:
+ *   - Normalizar errores de filesystem dentro del plugin FS.
+ *   - Evitar el uso de Error genérico sin contexto.
+ *   - Facilitar logging, debugging y traducción a errores de capas superiores.
+ *
+ * No representa errores de dominio ni de configuración; solo fallos de I/O.
+ */
+class FileOperationError extends Error {
+    constructor(opts) {
+        const message = opts.message ??
+            buildDefaultMessage({
+                operation: opts.operation,
+                filePath: opts.filePath,
+            });
+        super(message);
+        this.name = "FileOperationError";
+        this.scope = opts.scope;
+        this.operation = opts.operation;
+        this.filePath = opts.filePath;
+        this.cause = opts.cause;
+    }
+    // ---------------------------------------------------------------------------
+    // Factories: I/O
+    // ---------------------------------------------------------------------------
+    static create(operation, filePath, cause) {
+        return new FileOperationError({ operation, filePath, cause });
+    }
+    static fs(operation, filePath, cause) {
+        return new FileOperationError({
+            scope: "fs-plugin",
+            operation,
+            filePath,
+            cause,
+        });
+    }
+}
+exports.FileOperationError = FileOperationError;
+function buildDefaultMessage(opts) {
+    // I/O normal
+    return `Failed to ${opts.operation} file: ${opts.filePath ?? "(unknown)"}`;
+}

package/dist/infrastructure/errors/index.d.ts

@@ -0,0 +1 @@
+export * from "./file-operation.error";

package/dist/infrastructure/errors/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./file-operation.error"), exports);

package/dist/infrastructure/errors/types/file-operation-error-options.type.d.ts

@@ -0,0 +1,8 @@
+import { FileOperation, FsErrorScope } from ".";
+export type FileOperationErrorOptions = {
+    scope?: FsErrorScope;
+    operation: FileOperation;
+    filePath?: string;
+    cause?: unknown;
+    message?: string;
+};

package/dist/infrastructure/errors/types/file-operation-error-options.type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/infrastructure/errors/types/file-operation.type.d.ts

@@ -0,0 +1 @@
+export type FileOperation = "read" | "write" | "delete" | "mkdir" | "move";

package/dist/infrastructure/errors/types/file-operation.type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/infrastructure/errors/types/fs-error-scope.type.d.ts

@@ -0,0 +1 @@
+export type FsErrorScope = "fs-plugin";

package/dist/infrastructure/errors/types/fs-error-scope.type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/infrastructure/errors/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./file-operation.type";
+export * from "./fs-error-scope.type";
+export * from "./file-operation-error-options.type";

package/dist/infrastructure/errors/types/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./file-operation.type"), exports);
+__exportStar(require("./fs-error-scope.type"), exports);
+__exportStar(require("./file-operation-error-options.type"), exports);

package/dist/infrastructure/filesystem/index.d.ts

@@ -0,0 +1 @@
+export * from "./types";

package/dist/infrastructure/filesystem/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);

package/dist/infrastructure/filesystem/types/filesystem-datasource-options.type.d.ts

@@ -0,0 +1,45 @@
+import { FilePath } from "../../../domain/value-objects";
+import { IFileSystemRotationConfig } from ".";
+/**
+ * Opciones de configuración para la fuente de datos del sistema de archivos.
+ * Es el objeto de configuración para un datasource de logs basado en filesystem
+ */
+export interface IFilesystemDatasourceOptions {
+    /**
+     * Directorio base donde se van a crear/leer los archivos de log.
+     */
+    basePath: string;
+    /**
+     * Indica si se deben crear los directorios padres si no existen
+     * Si es true, la implementación puede crear el basePath (con fs.mkdir({ recursive: true })) si no existe.
+     * Si es false o undefined, o no lo crea o depende de tu implementación.
+     */
+    mkdir?: boolean;
+    /**
+     * Patrón de nombre del archivo de log
+     */
+    fileNamePattern?: string;
+    /**
+     * Conecta con la política de rotación: "none" | "day" | "size", tamaño máximo, número de archivos, etc
+     */
+    rotation?: IFileSystemRotationConfig;
+    /**
+     * Hook que se dispara cuando se rota un archivo de log. Útil para:
+     * - Notificar a otro sistema.
+     * - Enviar el archivo rotado a S3.
+     * - Hacer limpieza adicional.
+     * @param oldPath Ruta del archivo de log antes de la rotación
+     * @param newPath Ruta del archivo de log después de la rotación
+     * @returns
+     */
+    onRotate?: (oldPath: FilePath, newPath: FilePath) => void | Promise<void>;
+    /**
+     * Hook centralizado para manejar errores del datasource:
+     * - Loggear en otro canal.
+     * - Enviar métricas / alertas.
+     * - Evitar que el logger “reviente” la app.
+     * @param error Error ocurrido en el datasource
+     * @returns
+     */
+    onError?: (error: Error) => void | Promise<void>;
+}

package/dist/infrastructure/filesystem/types/filesystem-datasource-options.type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/infrastructure/filesystem/types/filesystem-rotation.type.d.ts

@@ -0,0 +1,12 @@
+import { FsRotationBy } from "../../../domain/types";
+/**
+ * Representa la configuración que el sistema de log debe seguir para decidir cuándo rotar archivos.
+ * by: Estrategia principal de rotación: "none", "day", "size".
+ * maxSizeMB: Tamaño máximo del archivo antes de rotar (solo aplica si by === "size").
+ * maxFiles: Cuántos archivos rotados se mantienen. Ejemplo: si maxFiles = 5, se mantienen:
+ */
+export interface IFileSystemRotationConfig {
+    by: FsRotationBy;
+    maxSizeMB?: number;
+    maxFiles?: number;
+}

package/dist/infrastructure/filesystem/types/filesystem-rotation.type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/infrastructure/filesystem/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./filesystem-datasource-options.type";
+export * from "./filesystem-rotation.type";

package/dist/infrastructure/filesystem/types/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./filesystem-datasource-options.type"), exports);
+__exportStar(require("./filesystem-rotation.type"), exports);