fullnative 0.1.0

package/dist/core/file/File.js

@@ -0,0 +1,397 @@
+import { promises as fs, createReadStream, createWriteStream } from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+/**
+ * Representa un archivo individual accesible mediante una API sencilla.
+ * Las operaciones son perezosas: leen/escriben en disco solo cuando se invocan.
+ */
+export class File {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    /** Nombre del archivo incluyendo su extensión. */
+    get name() {
+        return path.basename(this.path);
+    }
+    /** Nombre del archivo sin la extensión. */
+    get baseName() {
+        return path.basename(this.path, path.extname(this.path));
+    }
+    /** Extensión del archivo sin el punto inicial (ej. `txt`, `json`). */
+    get ext() {
+        return path.extname(this.path).slice(1);
+    }
+    /** Ruta absoluta del directorio que contiene al archivo. */
+    get dirname() {
+        return path.dirname(this.path);
+    }
+    /**
+     * Tipo MIME inferido a partir de la extensión del archivo.
+     * Devuelve `application/octet-stream` para extensiones desconocidas.
+     */
+    get mimeType() {
+        const ext = this.ext.toLowerCase();
+        const types = {
+            txt: "text/plain",
+            html: "text/html",
+            css: "text/css",
+            js: "text/javascript",
+            mjs: "text/javascript",
+            cjs: "text/javascript",
+            ts: "text/typescript",
+            json: "application/json",
+            xml: "application/xml",
+            yaml: "text/yaml",
+            yml: "text/yaml",
+            md: "text/markdown",
+            csv: "text/csv",
+            pdf: "application/pdf",
+            zip: "application/zip",
+            gz: "application/gzip",
+            png: "image/png",
+            jpg: "image/jpeg",
+            jpeg: "image/jpeg",
+            gif: "image/gif",
+            svg: "image/svg+xml",
+            webp: "image/webp",
+            mp3: "audio/mpeg",
+            mp4: "video/mp4",
+            webm: "video/webm",
+        };
+        return types[ext] ?? "application/octet-stream";
+    }
+    /**
+     * Verifica si el archivo existe en disco.
+     * @returns `true` si el archivo existe, `false` en caso contrario.
+     */
+    async exists() {
+        try {
+            await fs.access(this.path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Obtiene los metadatos (stat) del archivo en disco.
+     * @returns Una promesa con el objeto `Stats` de Node.js.
+     */
+    async stat() {
+        return fs.stat(this.path);
+    }
+    /**
+     * Obtiene el tamaño del archivo en bytes.
+     * @returns Tamaño en bytes.
+     */
+    async size() {
+        return (await this.stat()).size;
+    }
+    /**
+     * Indica si el archivo está vacío (0 bytes).
+     * @returns `true` si el tamaño es 0, `false` en caso contrario.
+     */
+    async isEmpty() {
+        return (await this.size()) === 0;
+    }
+    /**
+     * Obtiene la fecha de creación del archivo.
+     * @returns La fecha (`birthtime`) de creación.
+     */
+    async createdAt() {
+        return (await this.stat()).birthtime;
+    }
+    /**
+     * Obtiene la fecha de última modificación del archivo.
+     * @returns La fecha (`mtime`) de última modificación.
+     */
+    async modifiedAt() {
+        return (await this.stat()).mtime;
+    }
+    /**
+     * Obtiene la fecha de último acceso al archivo.
+     * @returns La fecha (`atime`) de último acceso.
+     */
+    async accessedAt() {
+        return (await this.stat()).atime;
+    }
+    /**
+     * Lee el contenido del archivo como texto.
+     * @param encoding Codificación a utilizar (por defecto `utf8`).
+     * @returns El contenido del archivo como cadena.
+     */
+    async read(encoding = "utf8") {
+        return fs.readFile(this.path, encoding);
+    }
+    /**
+     * Lee el contenido del archivo como `Buffer` binario.
+     * @returns Un `Buffer` con los bytes del archivo.
+     */
+    async readBuffer() {
+        return fs.readFile(this.path);
+    }
+    /**
+     * Lee y parsea el contenido del archivo como JSON.
+     * @returns El valor parseado, tipado genéricamente como `T`.
+     */
+    async readJson() {
+        return JSON.parse(await this.read());
+    }
+    /**
+     * Lee el contenido del archivo y lo divide en líneas.
+     * @returns Un arreglo de cadenas, una por línea.
+     */
+    async readLines() {
+        const content = await this.read();
+        return content.split(/\r?\n/);
+    }
+    /**
+     * Escribe datos en el archivo. Crea el directorio padre automáticamente
+     * si no existe (comportamiento intencional para que el caller no necesite
+     * un `mkdir -p` previo explícito). Sobrescribe el contenido existente.
+     * @param data Contenido a escribir (cadena, `Buffer` o `Uint8Array`).
+     * @returns Promesa que se resuelve cuando la escritura termina.
+     */
+    async write(data) {
+        await fs.mkdir(path.dirname(this.path), { recursive: true });
+        await fs.writeFile(this.path, data);
+    }
+    /**
+     * Serializa `data` a JSON y lo escribe en el archivo (creando el directorio padre).
+     * @param data Valor a serializar.
+     * @param pretty Si `true` (por defecto), indenta con 2 espacios; si `false`, compacto.
+     * @returns Promesa que se resuelve cuando la escritura termina.
+     */
+    async writeJson(data, pretty = true) {
+        await this.write(JSON.stringify(data, null, pretty ? 2 : 0));
+    }
+    /**
+     * Escribe un arreglo de líneas en el archivo, unidas por `\n`.
+     * Crea el directorio padre automáticamente.
+     * @param lines Líneas a escribir.
+     * @returns Promesa que se resuelve cuando la escritura termina.
+     */
+    async writeLines(lines) {
+        await this.write(lines.join("\n"));
+    }
+    /**
+     * Añade datos al final del archivo. Crea el directorio padre automáticamente
+     * si no existe.
+     * @param data Contenido a añadir (cadena, `Buffer` o `Uint8Array`).
+     * @returns Promesa que se resuelve cuando la operación termina.
+     */
+    async append(data) {
+        await fs.mkdir(path.dirname(this.path), { recursive: true });
+        await fs.appendFile(this.path, data);
+    }
+    /**
+     * Añade una línea al final del archivo, seguida de un salto de línea.
+     * Crea el directorio padre automáticamente.
+     * @param line Texto de la línea a añadir.
+     * @returns Promesa que se resuelve cuando la operación termina.
+     */
+    async appendLine(line) {
+        await this.append(line + "\n");
+    }
+    /**
+     * Prependa datos al inicio del archivo, leyendo el contenido existente y
+     * reescribiendo el archivo completo. Crea el directorio padre automáticamente.
+     * @param data Contenido a prepend (cadena, `Buffer` o `Uint8Array`).
+     * @returns Promesa que se resuelve cuando la operación termina.
+     */
+    async prepend(data) {
+        const existing = (await this.exists()) ? await this.readBuffer() : Buffer.alloc(0);
+        const next = Buffer.concat([Buffer.from(data), existing]);
+        await this.write(next);
+    }
+    /**
+     * Inserta una línea en una posición específica del archivo (por índice de línea).
+     * El índice se ajusta dentro de los límites válidos.
+     * @param lineIndex Índice (base 0) donde insertar la línea.
+     * @param content Texto de la línea a insertar.
+     * @returns Promesa que se resuelve cuando la escritura termina.
+     */
+    async insertAt(lineIndex, content) {
+        const lines = await this.readLines();
+        const clamped = Math.max(0, Math.min(lineIndex, lines.length));
+        lines.splice(clamped, 0, content);
+        await this.writeLines(lines);
+    }
+    /**
+     * Reemplaza la primera ocurrencia de `search` por `replacement` en el contenido
+     * del archivo y lo reescribe.
+     * @param search Cadena o expresión regular a buscar.
+     * @param replacement Texto de reemplazo.
+     * @returns Promesa que se resuelve cuando la escritura termina.
+     */
+    async replace(search, replacement) {
+        const content = await this.read();
+        await this.write(content.replace(search, replacement));
+    }
+    /**
+     * Aplica múltiples reemplazos en secuencia sobre el contenido del archivo.
+     * Renombrado desde `replaceAll()` para evitar colisión con el método nativo
+     * de cadenas. Cada reemplazo se aplica al resultado del anterior, en orden.
+     * @param replacements Arreglo de pares `{ search, replacement }` aplicados en orden.
+     * @returns Promesa que se resuelve cuando la escritura termina.
+     */
+    async replaceMany(replacements) {
+        let content = await this.read();
+        for (const { search, replacement } of replacements) {
+            content = content.replace(search, replacement);
+        }
+        await this.write(content);
+    }
+    /**
+     * Trunca el archivo al tamaño indicado.
+     * @param size Tamaño en bytes (por defecto 0, vacía el archivo).
+     * @returns Promesa que se resuelve al completar el truncado.
+     */
+    async truncate(size = 0) {
+        await fs.truncate(this.path, size);
+    }
+    /**
+     * Actualiza la fecha de acceso/modificación al momento actual, o crea el
+     * archivo vacío si no existe.
+     * @returns Promesa que se resuelve al completar la operación.
+     */
+    async touch() {
+        const now = new Date();
+        if (await this.exists()) {
+            await fs.utimes(this.path, now, now);
+        }
+        else {
+            await this.write("");
+        }
+    }
+    /**
+     * Cambia los permisos del archivo.
+     * @param mode Máscode de permisos numérico (ej. `0o644`).
+     * @returns Promesa que se resuelve al completar el cambio.
+     */
+    async chmod(mode) {
+        await fs.chmod(this.path, mode);
+    }
+    /**
+     * Establece el archivo como solo lectura (modo `0o444`).
+     * @returns Promesa que se resuelve al completar el cambio.
+     */
+    async setReadOnly() {
+        await this.chmod(0o444);
+    }
+    /**
+     * Establece el archivo como lectura/escritura (modo `0o644`).
+     * @returns Promesa que se resuelve al completar el cambio.
+     */
+    async setReadWrite() {
+        await this.chmod(0o644);
+    }
+    /**
+     * Calcula el hash criptográfico del contenido del archivo.
+     * @param algo Algoritmo de hash (por defecto `sha256`).
+     * @returns El hash en formato hexadecimal.
+     */
+    async hash(algo = "sha256") {
+        return crypto.createHash(algo).update(await this.readBuffer()).digest("hex");
+    }
+    /**
+     * Compara este archivo con otro por contenido (usando hash).
+     * @param other Otro `File` a comparar.
+     * @returns `true` si ambos existen y su hash coincide, `false` en caso contrario.
+     */
+    async equals(other) {
+        if (!(await this.exists()) || !(await other.exists()))
+            return false;
+        return (await this.hash()) === (await other.hash());
+    }
+    /**
+     * Compara el contenido del archivo con una cadena o `Buffer` dada.
+     * @param content Contenido a comparar.
+     * @returns `true` si el contenido coincide, `false` si no existe o difiere.
+     */
+    async contentEquals(content) {
+        if (!(await this.exists()))
+            return false;
+        const existing = await this.readBuffer();
+        const incoming = Buffer.isBuffer(content) ? content : Buffer.from(content);
+        return existing.equals(incoming);
+    }
+    /**
+     * Crea un stream de lectura para el archivo.
+     * @returns Un `Readable` para consumir el contenido en streaming.
+     */
+    readStream() {
+        return createReadStream(this.path);
+    }
+    /**
+     * Crea un stream de escritura hacia el archivo.
+     * @returns Un `Writable` para escribir contenido en streaming.
+     */
+    writeStream() {
+        return createWriteStream(this.path);
+    }
+    /**
+     * Elimina el archivo del disco.
+     * @returns `true` si el archivo existía y fue eliminado, `false` si no existía.
+     */
+    async delete() {
+        if (!(await this.exists()))
+            return false;
+        await fs.unlink(this.path);
+        return true;
+    }
+    /**
+     * Copia este archivo a una ruta destino. Crea el directorio padre del destino
+     * automáticamente si no existe.
+     * @param dest Ruta absoluta del archivo destino.
+     * @returns Una **nueva** instancia de `File` apuntando al destino.
+     */
+    async copyTo(dest) {
+        await fs.mkdir(path.dirname(dest), { recursive: true });
+        await fs.copyFile(this.path, dest);
+        return new File(dest);
+    }
+    /**
+     * Copia este archivo dentro de un directorio, conservando su nombre.
+     * @param dir Ruta del directorio destino.
+     * @returns Una **nueva** instancia de `File` apuntando a `dir/name`.
+     */
+    async copyInto(dir) {
+        return this.copyTo(path.join(dir, this.name));
+    }
+    /**
+     * Mueve este archivo a una ruta destino. Crea el directorio padre del destino
+     * automáticamente si no existe. **Muta `this.path`** al nuevo destino y
+     * devuelve `this` para encadenamiento.
+     * @param dest Ruta absoluta del archivo destino.
+     * @returns La misma instancia (`this`) con `path` actualizado.
+     */
+    async moveTo(dest) {
+        await fs.mkdir(path.dirname(dest), { recursive: true });
+        await fs.rename(this.path, dest);
+        this.path = dest;
+        return this;
+    }
+    /**
+     * Mueve este archivo dentro de un directorio, conservando su nombre.
+     * **Muta `this.path`** y devuelve `this`.
+     * @param dir Ruta del directorio destino.
+     * @returns La misma instancia (`this`) con `path` actualizado.
+     */
+    async moveInto(dir) {
+        await this.moveTo(path.join(dir, this.name));
+        return this;
+    }
+    /**
+     * Renombra este archivo dentro de su mismo directorio.
+     * **Muta `this.path`** y devuelve `this`.
+     * @param newName Nuevo nombre del archivo (sin ruta).
+     * @returns La misma instancia (`this`) con `path` actualizado.
+     */
+    async rename(newName) {
+        await this.moveTo(path.join(this.dirname, newName));
+        return this;
+    }
+}
+//# sourceMappingURL=File.js.map

package/dist/core/file/File.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"File.js","sourceRoot":"","sources":["../../../src/core/file/File.ts"],"names":[],"mappings":"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"}

package/dist/core/file/Folder.d.ts

@@ -0,0 +1,235 @@
+import { type FSWatcher } from "node:fs";
+import { File } from "./File.js";
+/**
+ * Representa un directorio accesible mediante una API sencilla.
+ */
+export declare class Folder {
+    path: string;
+    constructor(path: string);
+    /** Nombre del directorio (último segmento de la ruta). */
+    get name(): string;
+    /** Ruta absoluta del directorio padre. */
+    get parent(): string;
+    /** Instancia de `Folder` que representa al directorio padre. */
+    get parentDir(): Folder;
+    /** Ruta absoluta resuelta del directorio. */
+    get absolute(): string;
+    /**
+     * Verifica si el directorio existe en disco.
+     * @returns `true` si existe y es un directorio, `false` en caso contrario.
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Indica si el directorio está vacío (sin entradas).
+     * @returns `true` si no existe o no contiene entradas, `false` si tiene contenido.
+     */
+    isEmpty(): Promise<boolean>;
+    /**
+     * Obtiene los metadatos (stat) del directorio.
+     * @returns Una promesa con el objeto `Stats` de Node.js.
+     */
+    stat(): Promise<import("node:fs").Stats>;
+    /**
+     * Obtiene la fecha de creación del directorio.
+     * @returns La fecha (`birthtime`) de creación.
+     */
+    createdAt(): Promise<Date>;
+    /**
+     * Obtiene la fecha de última modificación del directorio.
+     * @returns La fecha (`mtime`) de última modificación.
+     */
+    modifiedAt(): Promise<Date>;
+    /**
+     * Calcula el tamaño total del directorio sumando el tamaño de todos los
+     * archivos contenidos recursivamente.
+     * @returns Tamaño total en bytes (0 si no existe).
+     */
+    size(): Promise<number>;
+    /**
+     * Crea el directorio (y sus padres) en disco.
+     * @returns Promesa que se resuelve al completar la creación.
+     */
+    create(): Promise<void>;
+    /**
+     * Garantiza que el directorio exista, creándolo si es necesario.
+     * @returns Promesa que se resuelve al asegurar la existencia.
+     */
+    ensure(): Promise<void>;
+    /**
+     * Elimina el directorio del disco.
+     * @param recursive Si `true`, elimina recursivamente su contenido.
+     * @returns `true` si existía y fue eliminado, `false` si no existía.
+     */
+    delete(recursive?: boolean): Promise<boolean>;
+    /**
+     * Vacía el directorio eliminando todo su contenido (archivos y subdirectorios)
+     * sin eliminar el directorio mismo.
+     * @returns Promesa que se resuelve al completar el vaciado.
+     */
+    clear(): Promise<void>;
+    /**
+     * Cambia los permisos del directorio.
+     * @param mode Máscode de permisos numérico (ej. `0o755`).
+     * @returns Promesa que se resuelve al completar el cambio.
+     */
+    chmod(mode: number): Promise<void>;
+    /**
+     * Construye una referencia `File` a un archivo dentro de este directorio.
+     * @param name Nombre del archivo (relativo al directorio).
+     * @returns Una nueva instancia de `File` (no verifica existencia).
+     */
+    file(name: string): File;
+    /**
+     * Construye una referencia `Folder` a un subdirectorio de este directorio.
+     * @param name Nombre del subdirectorio (relativo al directorio).
+     * @returns Una nueva instancia de `Folder` (no verifica existencia).
+     */
+    dir(name: string): Folder;
+    /**
+     * Verifica si existe un archivo con el nombre dado dentro del directorio.
+     * @param name Nombre del archivo a buscar.
+     * @returns `true` si el archivo existe, `false` en caso contrario.
+     */
+    hasFile(name: string): Promise<boolean>;
+    /**
+     * Verifica si existe un subdirectorio con el nombre dado.
+     * @param name Nombre del subdirectorio a buscar.
+     * @returns `true` si el subdirectorio existe, `false` en caso contrario.
+     */
+    hasDir(name: string): Promise<boolean>;
+    /**
+     * Lista las entradas directas (archivos y subdirectorios) del directorio.
+     * @returns Arreglo de instancias `File` y `Folder`.
+     */
+    list(): Promise<(File | Folder)[]>;
+    /**
+     * Lista solo los archivos (no directorios) en el nivel actual.
+     * @returns Arreglo de instancias `File`.
+     */
+    listFiles(): Promise<File[]>;
+    /**
+     * Lista solo los subdirectorios en el nivel actual.
+     * @returns Arreglo de instancias `Folder`.
+     */
+    listDirs(): Promise<Folder[]>;
+    /**
+     * Lista los nombres de las entradas directas del directorio.
+     * @returns Arreglo de cadenas con los nombres de las entradas.
+     */
+    listNames(): Promise<string[]>;
+    /**
+     * Lista los archivos del nivel actual cuya extensión coincide con `ext`.
+     * @param ext Extensión a filtrar (con o sin punto inicial, sin distinguir mayúsculas).
+     * @returns Arreglo de instancias `File` que coinciden.
+     */
+    listByExt(ext: string): Promise<File[]>;
+    /**
+     * Busca recursivamente un archivo por nombre exacto.
+     * @param name Nombre del archivo a buscar.
+     * @returns La instancia `File` si se encuentra, `undefined` en caso contrario.
+     */
+    find(name: string): Promise<File | undefined>;
+    /**
+     * Busca recursivamente un subdirectorio por nombre exacto.
+     * @param name Nombre del subdirectorio a buscar.
+     * @returns La instancia `Folder` si se encuentra, `undefined` en caso contrario.
+     */
+    findDir(name: string): Promise<Folder | undefined>;
+    /**
+     * Filtra archivos recursivamente mediante una expresión regular.
+     * Renombrado desde `glob()`: usa sintaxis **RegExp**, no patrones glob.
+     * @param pattern Expresión regular a probar contra la ruta completa de cada archivo.
+     * @returns Arreglo de instancias `File` cuya ruta coincide con el patrón.
+     */
+    matchFiles(pattern: RegExp): Promise<File[]>;
+    /**
+     * Recorre recursivamente el directorio acumulando todas las entradas
+     * (archivos y subdirectorios) en un arreglo.
+     * @returns Arreglo con todas las instancias `File` y `Folder` encontradas.
+     */
+    walk(): Promise<(File | Folder)[]>;
+    /**
+     * Recorre recursivamente y devuelve solo los archivos.
+     * @returns Arreglo con todas las instancias `File` encontradas.
+     */
+    walkFiles(): Promise<File[]>;
+    /**
+     * Recorre recursivamente y devuelve solo los subdirectorios.
+     * @returns Arreglo con todas las instancias `Folder` encontradas.
+     */
+    walkDirs(): Promise<Folder[]>;
+    /**
+     * Versión streaming de `walk()` como async generator, ideal para carpetas
+     * grandes: produce entradas (`File` o `Folder`) a medida que se recorre el
+     * árbol, sin acumular todo en memoria.
+     * @yields Instancias `File` o `Folder` conforme se descubre cada entrada.
+     */
+    walkIter(): AsyncGenerator<File | Folder>;
+    /**
+     * Versión streaming de `walkFiles()` como async generator: produce solo
+     * archivos a medida que recorre el árbol, sin acumular todo en memoria.
+     * @yields Instancias `File` conforme se descubre cada archivo.
+     */
+    walkFilesIter(): AsyncGenerator<File>;
+    /**
+     * Crea un archivo dentro de este directorio con el contenido indicado.
+     * @param name Nombre del archivo a crear.
+     * @param content Contenido inicial (cadena o `Buffer`, por defecto vacío).
+     * @returns La instancia `File` recién creada.
+     */
+    createFile(name: string, content?: string | Buffer): Promise<File>;
+    /**
+     * Crea un subdirectorio dentro de este directorio (garantizando su existencia).
+     * @param name Nombre del subdirectorio a crear.
+     * @returns La instancia `Folder` del subdirectorio creado.
+     */
+    createDir(name: string): Promise<Folder>;
+    /**
+     * Copia este directorio (y todo su contenido) a una ruta destino, creando
+     * el destino si no existe.
+     * @param dest Ruta absoluta del directorio destino.
+     * @returns Una **nueva** instancia de `Folder` apuntando al destino.
+     */
+    copyTo(dest: string): Promise<Folder>;
+    /**
+     * Copia este directorio dentro de otro, conservando su nombre.
+     * @param parent Ruta del directorio padre destino.
+     * @returns Una **nueva** instancia de `Folder` apuntando a `parent/name`.
+     */
+    copyInto(parent: string): Promise<Folder>;
+    /**
+     * Mueve este directorio a una ruta destino. Crea el directorio padre del
+     * destino automáticamente si no existe. **Muta `this.path`** al nuevo destino
+     * y devuelve `this` para encadenamiento.
+     * @param dest Ruta absoluta del directorio destino.
+     * @returns La misma instancia (`this`) con `path` actualizado.
+     */
+    moveTo(dest: string): Promise<this>;
+    /**
+     * Mueve este directorio dentro de otro, conservando su nombre.
+     * **Muta `this.path`** y devuelve `this`.
+     * @param parent Ruta del directorio padre destino.
+     * @returns La misma instancia (`this`) con `path` actualizado.
+     */
+    moveInto(parent: string): Promise<this>;
+    /**
+     * Renombra este directorio dentro de su mismo directorio padre.
+     * **Muta `this.path`** y devuelve `this`.
+     * @param newName Nuevo nombre del directorio (sin ruta).
+     * @returns La misma instancia (`this`) con `path` actualizado.
+     */
+    rename(newName: string): Promise<this>;
+    /**
+     * Observa cambios en el directorio de forma recursiva.
+     * @param callback Función invocada por cada evento (`change` o `rename`).
+     * @returns Un `FSWatcher` que debe cerrarse cuando ya no se necesite.
+     */
+    watch(callback: (event: "change" | "rename", filename: string | null) => void): Promise<FSWatcher>;
+    /**
+     * Genera una representación visual en árbol (tipo `tree`) del directorio y
+     * su contenido recursivo.
+     * @returns Una cadena con la representación del árbol.
+     */
+    tree(): Promise<string>;
+}
+//# sourceMappingURL=Folder.d.ts.map

package/dist/core/file/Folder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Folder.d.ts","sourceRoot":"","sources":["../../../src/core/file/Folder.ts"],"names":[],"mappings":"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"}