fullnative 0.2.0 → 1.0.0

package/dist/core/utils/tempDir.js

@@ -0,0 +1,92 @@
+import { promises as fs, rmSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Folder } from "../file/Folder.js";
+/**
+ * Registro a nivel de módulo con las rutas de los directorios temporales
+ * pendientes de limpieza automática. Solo contiene las rutas creadas con
+ * `keep !== true`; las de `keep: true` no se registran.
+ */
+const pending = new Set();
+/** Marca si el hook de `exit` ya se registró (único por proceso). */
+let hookInstalled = false;
+/**
+ * Limpieza al finalizar el proceso: elimina cada ruta registrada.
+ *
+ * Se registra UNA sola vez (aunque se creen N tempdirs) para no acumular
+ * listeners de `exit`. Los fallos de `rmSync` se tragan a propósito: la
+ * limpieza en el cierre del proceso es de "mejor esfuerzo" y no debe
+ * interrumpir el shutdown.
+ */
+const cleanupPending = () => {
+    for (const dir of pending) {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            // Mejor esfuerzo en el cierre del proceso.
+        }
+    }
+    pending.clear();
+};
+/**
+ * Registra el hook de `exit` (solo la primera vez que se necesita).
+ */
+function installExitHook() {
+    if (hookInstalled)
+        return;
+    hookInstalled = true;
+    process.once("exit", cleanupPending);
+}
+/**
+ * Directorio temporal gestionado, creado con `fs.mkdtemp` bajo `os.tmpdir()`.
+ *
+ * Extiende `Folder`, así que hereda toda la API de directorios (`list`,
+ * `createFile`, `walk`, etc.). Añade `dispose()` para eliminarlo bajo demanda:
+ * `dispose()` es idempotente y quita la ruta del registro del auto-cleanup,
+ * así que no hay doble intento de borrado al salir del proceso.
+ */
+export class TempDir extends Folder {
+    /** Indica si el directorio fue creado con `keep: true`. */
+    keep;
+    /**
+     * @param dirPath Ruta (absoluta) del directorio temporal.
+     * @param keep `true` si se creó con `keep: true` (sin auto-cleanup).
+     */
+    constructor(dirPath, keep = false) {
+        super(dirPath);
+        this.keep = keep;
+    }
+    /**
+     * Elimina el directorio y todo su contenido del disco
+     * (`fs.rm` con `recursive` y `force`) y lo saca del registro de
+     * auto-cleanup. No falla si ya no existe.
+     */
+    async dispose() {
+        await fs.rm(this.path, { recursive: true, force: true });
+        pending.delete(this.path);
+    }
+}
+/**
+ * Crea un directorio temporal único bajo `os.tmpdir()` con `fs.mkdtemp`.
+ *
+ * Por defecto (`keep: false`) la ruta se registra y un hook **único** de
+ * `process.once("exit")` la elimina automáticamente al finalizar el proceso
+ * (un solo listener para todos los tempdirs, nunca uno por creación), con
+ * `rmSync` recursive + force.
+ *
+ * @param options Opciones `prefix` (default `"fullnative-"`) y `keep`
+ *   (default `false`).
+ * @returns Una promesa con la instancia `TempDir`; el directorio ya existe
+ *   en disco al resolverse.
+ */
+export async function tempDir(options = {}) {
+    const { prefix = "fullnative-", keep = false } = options;
+    const dirPath = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+    if (!keep) {
+        pending.add(dirPath);
+        installExitHook();
+    }
+    return new TempDir(dirPath, keep);
+}
+//# sourceMappingURL=tempDir.js.map

package/dist/core/utils/tempDir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tempDir.js","sourceRoot":"","sources":["../../../src/core/utils/tempDir.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C;;;;GAIG;AACH,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;AAElC,qEAAqE;AACrE,IAAI,aAAa,GAAG,KAAK,CAAC;AAE1B;;;;;;;GAOG;AACH,MAAM,cAAc,GAAG,GAAS,EAAE;IAChC,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,2CAA2C;QAC7C,CAAC;IACH,CAAC;IACD,OAAO,CAAC,KAAK,EAAE,CAAC;AAClB,CAAC,CAAC;AAEF;;GAEG;AACH,SAAS,eAAe;IACtB,IAAI,aAAa;QAAE,OAAO;IAC1B,aAAa,GAAG,IAAI,CAAC;IACrB,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AACvC,CAAC;AAwBD;;;;;;;GAOG;AACH,MAAM,OAAO,OAAQ,SAAQ,MAAM;IACjC,2DAA2D;IAC3C,IAAI,CAAU;IAE9B;;;OAGG;IACH,YAAY,OAAe,EAAE,IAAI,GAAG,KAAK;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO;QACX,MAAM,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;CACF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,UAA0B,EAAE;IACxD,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,IAAI,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IACzD,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;IACjE,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACrB,eAAe,EAAE,CAAC;IACpB,CAAC;IACD,OAAO,IAAI,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACpC,CAAC"}

package/dist/core/utils/timeout.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Error que indica que una operación superó el plazo máximo permitido.
+ *
+ * Se usa como rechazo estándar de `timeout()` y permite detectar caducidades
+ * de forma tipada sin depender del mensaje literal.
+ *
+ * @example
+ * try {
+ *   await timeout(slowTask(), 5_000);
+ * } catch (err) {
+ *   if (err instanceof TimeoutError) console.error("se pasó de plazo");
+ * }
+ */
+export declare class TimeoutError extends Error {
+    /**
+     * @param message Descripción del vencimiento (por defecto, genérica).
+     */
+    constructor(message?: string);
+}
+/**
+ * Compite una promesa contra un temporizador y limita su plazo de resolución.
+ *
+ * - Si `promise` se resuelve a tiempo, su valor gana la carrera y el timer
+ *   se limpia con `clearTimeout` (vía `finally`).
+ * - Si expira el plazo, la promesa devuelta rechaza con `TimeoutError`
+ *   (el `message` dado, o uno por defecto que incluye los `ms`).
+ *
+ * El `promise` subyacente nunca se cancela (las promesas nativas no se pueden
+ * cancelar): si rechaza después de que el timer haya ganado, `Promise.race`
+ * ya tenía handlers adjuntos a ambos, así que no hay unhandled rejection.
+ *
+ * @param promise Promesa a la que se quiere limitar el plazo.
+ * @param ms Plazo máximo en milisegundos antes de rechazar.
+ * @param message Mensaje opcional para el `TimeoutError`. Por defecto,
+ *   `"Operation timed out after {ms}ms"`.
+ * @returns Una promesa con el valor de `promise`, o que rechaza con
+ *   `TimeoutError` si vence el plazo.
+ */
+export declare function timeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;
+//# sourceMappingURL=timeout.d.ts.map

package/dist/core/utils/timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../../../src/core/utils/timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC;;OAEG;gBACS,OAAO,SAAwB;CAI5C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,CAAC,CAAC,CAYZ"}

package/dist/core/utils/timeout.js

@@ -0,0 +1,54 @@
+/**
+ * Error que indica que una operación superó el plazo máximo permitido.
+ *
+ * Se usa como rechazo estándar de `timeout()` y permite detectar caducidades
+ * de forma tipada sin depender del mensaje literal.
+ *
+ * @example
+ * try {
+ *   await timeout(slowTask(), 5_000);
+ * } catch (err) {
+ *   if (err instanceof TimeoutError) console.error("se pasó de plazo");
+ * }
+ */
+export class TimeoutError extends Error {
+    /**
+     * @param message Descripción del vencimiento (por defecto, genérica).
+     */
+    constructor(message = "Operation timed out") {
+        super(message);
+        this.name = "TimeoutError";
+    }
+}
+/**
+ * Compite una promesa contra un temporizador y limita su plazo de resolución.
+ *
+ * - Si `promise` se resuelve a tiempo, su valor gana la carrera y el timer
+ *   se limpia con `clearTimeout` (vía `finally`).
+ * - Si expira el plazo, la promesa devuelta rechaza con `TimeoutError`
+ *   (el `message` dado, o uno por defecto que incluye los `ms`).
+ *
+ * El `promise` subyacente nunca se cancela (las promesas nativas no se pueden
+ * cancelar): si rechaza después de que el timer haya ganado, `Promise.race`
+ * ya tenía handlers adjuntos a ambos, así que no hay unhandled rejection.
+ *
+ * @param promise Promesa a la que se quiere limitar el plazo.
+ * @param ms Plazo máximo en milisegundos antes de rechazar.
+ * @param message Mensaje opcional para el `TimeoutError`. Por defecto,
+ *   `"Operation timed out after {ms}ms"`.
+ * @returns Una promesa con el valor de `promise`, o que rechaza con
+ *   `TimeoutError` si vence el plazo.
+ */
+export function timeout(promise, ms, message) {
+    let timer;
+    const guard = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new TimeoutError(message ?? `Operation timed out after ${ms}ms`));
+        }, ms);
+    });
+    return Promise.race([promise, guard]).finally(() => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    });
+}
+//# sourceMappingURL=timeout.js.map

package/dist/core/utils/timeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.js","sourceRoot":"","sources":["../../../src/core/utils/timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC;;OAEG;IACH,YAAY,OAAO,GAAG,qBAAqB;QACzC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,OAAO,CACrB,OAAmB,EACnB,EAAU,EACV,OAAgB;IAEhB,IAAI,KAAgD,CAAC;IAErD,MAAM,KAAK,GAAG,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;QAC7C,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YACtB,MAAM,CAAC,IAAI,YAAY,CAAC,OAAO,IAAI,6BAA6B,EAAE,IAAI,CAAC,CAAC,CAAC;QAC3E,CAAC,EAAE,EAAE,CAAC,CAAC;IACT,CAAC,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE;QACjD,IAAI,KAAK,KAAK,SAAS;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullnative",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "description": "TypeScript toolchain for Node.js — files, folders, processes, shell sessions, and env loading with a clean, object-oriented API.",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,8 @@
     "dist",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "MIGRATION.md"
   ],
   "scripts": {
     "build": "tsc",