@visulima/pail 4.0.0-alpha.6 → 4.0.0-alpha.8

package/dist/packem_shared/{AbstractJsonReporter-BaZ33PlE.js → AbstractJsonReporter-DDjDkciI.js}

@@ -12,7 +12,7 @@ const ErrorProto = Object.create(
   {},
   {
     cause: {
-      enumerable: true,
+      enumerable: false,
       value: void 0,
       writable: true
     },
@@ -22,32 +22,55 @@ const ErrorProto = Object.create(
       writable: true
     },
     errors: {
-      enumerable: true,
+      enumerable: false,
       value: void 0,
       writable: true
     },
     message: {
-      enumerable: true,
+      enumerable: false,
       value: void 0,
       writable: true
     },
     name: {
-      enumerable: true,
+      enumerable: false,
       value: void 0,
       writable: true
     },
     stack: {
-      enumerable: true,
+      enumerable: false,
       value: void 0,
       writable: true
     }
   }
 );
 const toJsonWasCalled = /* @__PURE__ */ new WeakSet();
+const makePropertiesEnumerable = (object) => {
+  if (!object || typeof object !== "object") {
+    return;
+  }
+  const props = Object.getOwnPropertyNames(object);
+  for (const prop of props) {
+    const descriptor = Object.getOwnPropertyDescriptor(object, prop);
+    if (descriptor) {
+      if (!descriptor.enumerable) {
+        Object.defineProperty(object, prop, {
+          ...descriptor,
+          enumerable: true
+        });
+      }
+      if (descriptor.value && typeof descriptor.value === "object" && !Array.isArray(descriptor.value) && (Object.getPrototypeOf(descriptor.value) === Object.prototype || Object.getPrototypeOf(descriptor.value) === null)) {
+        makePropertiesEnumerable(descriptor.value);
+      }
+    }
+  }
+};
 const toJSON = (from) => {
   toJsonWasCalled.add(from);
   const json = from.toJSON();
   toJsonWasCalled.delete(from);
+  if (json && typeof json === "object" && Object.isExtensible(json)) {
+    makePropertiesEnumerable(json);
+  }
   return json;
 };
 const serializeValue = (value, seen, depth, options) => {
@@ -58,7 +81,7 @@ const serializeValue = (value, seen, depth, options) => {
     return "[object Stream]";
   }
   if (value instanceof Error) {
-    if (seen.includes(value)) {
+    if (seen.has(value)) {
       return "[Circular]";
     }
     depth += 1;
@@ -73,11 +96,14 @@ const serializeValue = (value, seen, depth, options) => {
   if (typeof value === "function") {
     return `[Function: ${value.name || "anonymous"}]`;
   }
+  if (typeof value === "bigint") {
+    return `${value}n`;
+  }
   if (isPlainObject(value)) {
-    depth += 1;
-    if (options.maxDepth && depth >= options.maxDepth) {
+    if (options.maxDepth !== void 0 && options.maxDepth !== Number.POSITIVE_INFINITY && depth + 1 >= options.maxDepth) {
       return {};
     }
+    depth += 1;
     const plainObject = {};
     for (const key in value) {
       plainObject[key] = serializeValue(value[key], seen, depth, options);
@@ -91,7 +117,7 @@ const serializeValue = (value, seen, depth, options) => {
   }
 };
 const _serialize = (error, options, seen, depth) => {
-  seen.push(error);
+  seen.add(error);
   if (options.maxDepth === 0) {
     return {};
   }
@@ -99,31 +125,87 @@ const _serialize = (error, options, seen, depth) => {
     return toJSON(error);
   }
   const protoError = Object.create(ErrorProto);
-  protoError.name = Object.prototype.toString.call(error.constructor) === "[object Function]" ? error.constructor.name : error.name;
-  protoError.message = error.message;
-  protoError.stack = error.stack;
+  Object.defineProperty(protoError, "name", {
+    configurable: true,
+    enumerable: true,
+    value: Object.prototype.toString.call(error.constructor) === "[object Function]" ? error.constructor.name : error.name,
+    writable: true
+  });
+  Object.defineProperty(protoError, "message", {
+    configurable: true,
+    enumerable: true,
+    value: error.message,
+    writable: true
+  });
+  Object.defineProperty(protoError, "stack", {
+    configurable: true,
+    enumerable: true,
+    value: error.stack,
+    writable: true
+  });
   if (Array.isArray(error.errors)) {
     const aggregateErrors = [];
     for (const aggregateError of error.errors) {
       if (!(aggregateError instanceof Error)) {
         throw new TypeError("All errors in the 'errors' property must be instances of Error");
       }
-      if (seen.includes(aggregateError)) {
-        protoError.errors = [];
+      if (seen.has(aggregateError)) {
+        Object.defineProperty(protoError, "errors", {
+          configurable: true,
+          enumerable: true,
+          value: [],
+          writable: true
+        });
         return protoError;
       }
       aggregateErrors.push(_serialize(aggregateError, options, seen, depth));
     }
-    protoError.errors = aggregateErrors;
+    Object.defineProperty(protoError, "errors", {
+      configurable: true,
+      enumerable: true,
+      value: aggregateErrors,
+      writable: true
+    });
   }
-  if (error.cause instanceof Error && !seen.includes(error.cause)) {
-    protoError.cause = _serialize(error.cause, options, seen, depth);
+  if (error.cause !== void 0 && error.cause !== null) {
+    if (error.cause instanceof Error) {
+      if (seen.has(error.cause)) {
+        Object.defineProperty(protoError, "cause", {
+          configurable: true,
+          enumerable: true,
+          value: "[Circular]",
+          writable: true
+        });
+      } else {
+        Object.defineProperty(protoError, "cause", {
+          configurable: true,
+          enumerable: true,
+          value: _serialize(error.cause, options, seen, depth),
+          writable: true
+        });
+      }
+    } else {
+      const serializedCause = serializeValue(error.cause, seen, depth, options);
+      Object.defineProperty(protoError, "cause", {
+        configurable: true,
+        enumerable: true,
+        value: serializedCause,
+        writable: true
+      });
+    }
   }
   for (const key in error) {
-    if (protoError[key] === void 0) {
-      const value = error[key];
-      protoError[key] = serializeValue(value, seen, depth, options);
+    if (key === "name" || key === "message" || key === "stack" || key === "cause" || key === "errors") {
+      continue;
     }
+    const value = error[key];
+    const serializedValue = serializeValue(value, seen, depth, options);
+    Object.defineProperty(protoError, key, {
+      configurable: true,
+      enumerable: true,
+      value: serializedValue,
+      writable: true
+    });
   }
   if (Array.isArray(options.exclude) && options.exclude.length > 0) {
     for (const key of options.exclude) {
@@ -142,7 +224,7 @@ const serialize = (error, options = {}) => _serialize(
     maxDepth: options.maxDepth ?? Number.POSITIVE_INFINITY,
     useToJSON: options.useToJSON ?? false
   },
-  [],
+  /* @__PURE__ */ new Set(),
   0
 );
 

package/dist/packem_shared/{JsonReporter-BV5lMnJX.js → JsonReporter-B3XX8GHN.js}

@@ -9,7 +9,7 @@ const {
   stderr
 } = __cjs_getProcess;
 import { w as writeStream } from './write-stream-BG8fhcs3.js';
-import { AbstractJsonReporter } from './AbstractJsonReporter-DWRpTtGw.js';
+import { AbstractJsonReporter } from './AbstractJsonReporter-CGKHS8_M.js';
 
 class JsonReporter extends AbstractJsonReporter {
   /** Standard output stream */

package/dist/packem_shared/{JsonReporter-BRw4skd5.js → JsonReporter-p_BXg6Sj.js}

@@ -1,4 +1,4 @@
-import { AbstractJsonReporter } from './AbstractJsonReporter-BaZ33PlE.js';
+import { AbstractJsonReporter } from './AbstractJsonReporter-DDjDkciI.js';
 import { w as writeConsoleLogBasedOnLevel } from './write-console-log-based-on-level-DBmRYXpj.js';
 
 class JsonReporter extends AbstractJsonReporter {

package/dist/packem_shared/{PrettyReporter-BjXCFQlo.js → PrettyReporter-CvBn-hxP.js}

@@ -1252,7 +1252,8 @@ class AbstractPrettyReporter {
   }
 }
 
-const pailFileFilter = (line) => !/[\\/]pail[\\/]dist/.test(line);
+const PAIL_DIST_REGEX = /[\\/]pail[\\/]dist/;
+const pailFileFilter = (line) => !PAIL_DIST_REGEX.test(line);
 class PrettyReporter extends AbstractPrettyReporter {
   #stdout;
   #stderr;

package/dist/packem_shared/createPailError-B11aRfrT.js

@@ -0,0 +1,76 @@
+class PailError extends Error {
+  /** HTTP status code (defaults to 500) */
+  status;
+  /** Explanation of what caused the failure */
+  why;
+  /** Suggested resolution steps */
+  fix;
+  /** Link to relevant documentation */
+  link;
+  constructor(options) {
+    const resolvedOptions = typeof options === "string" ? { message: options } : options;
+    super(resolvedOptions.message, resolvedOptions.cause === void 0 ? void 0 : { cause: resolvedOptions.cause });
+    this.name = "PailError";
+    this.status = resolvedOptions.status ?? 500;
+    this.why = resolvedOptions.why;
+    this.fix = resolvedOptions.fix;
+    this.link = resolvedOptions.link;
+  }
+  /**
+   * Converts the error to a JSON-serializable object.
+   *
+   * Includes all self-documenting fields in the output for structured logging.
+   * @returns A plain object representation of the error
+   */
+  toJSON() {
+    const json = {
+      message: this.message,
+      name: this.name,
+      status: this.status
+    };
+    if (this.why) {
+      json.why = this.why;
+    }
+    if (this.fix) {
+      json.fix = this.fix;
+    }
+    if (this.link) {
+      json.link = this.link;
+    }
+    if (this.stack) {
+      json.stack = this.stack;
+    }
+    if (this.cause !== void 0) {
+      json.cause = this.cause instanceof Error ? { message: this.cause.message, name: this.cause.name, stack: this.cause.stack } : this.cause;
+    }
+    return json;
+  }
+  /**
+   * Returns a formatted string representation including self-documenting fields.
+   * @returns Formatted error string with why/fix/link context
+   */
+  toString() {
+    let output = `${this.name} [${this.status}]: ${this.message}`;
+    if (this.why) {
+      output += `
+  Why: ${this.why}`;
+    }
+    if (this.fix) {
+      output += `
+  Fix: ${this.fix}`;
+    }
+    if (this.link) {
+      output += `
+  Link: ${this.link}`;
+    }
+    if (this.cause !== void 0) {
+      const causeMessage = this.cause instanceof Error ? this.cause.message : String(this.cause);
+      output += `
+  Cause: ${causeMessage}`;
+    }
+    return output;
+  }
+}
+const createPailError = (options) => new PailError(options);
+
+export { PailError, createPailError };

package/dist/packem_shared/headers-Cp4uLtr4.js

@@ -0,0 +1,123 @@
+import { WideEvent } from '../wide-event.js';
+
+const patternToRegex = (pattern) => {
+  let regex = "^";
+  let index = 0;
+  while (index < pattern.length) {
+    const char = pattern[index];
+    if (char === "*" && pattern[index + 1] === "*") {
+      index += 2;
+      if (pattern[index] === "/") {
+        index += 1;
+      }
+      if (index >= pattern.length && regex.endsWith("/")) {
+        regex = `${regex.slice(0, -1)}(/.*)?`;
+      } else if (index >= pattern.length) {
+        regex += ".*";
+      } else {
+        regex += "(.*/)?";
+      }
+    } else {
+      switch (char) {
+        case "*": {
+          regex += "[^/]*";
+          index += 1;
+          break;
+        }
+        case ".": {
+          regex += String.raw`\.`;
+          index += 1;
+          break;
+        }
+        case "?": {
+          regex += "[^/]";
+          index += 1;
+          break;
+        }
+        default: {
+          regex += char;
+          index += 1;
+        }
+      }
+    }
+  }
+  regex += "$";
+  return new RegExp(regex);
+};
+const matchesPattern = (path, pattern) => patternToRegex(pattern).test(path);
+const shouldLog = (path, include, exclude) => {
+  if (exclude?.some((pattern) => matchesPattern(path, pattern))) {
+    return false;
+  }
+  if (!include?.length) {
+    return true;
+  }
+  return include.some((pattern) => matchesPattern(path, pattern));
+};
+const getServiceForPath = (path, routes) => {
+  if (!routes) {
+    return void 0;
+  }
+  for (const [pattern, config] of Object.entries(routes)) {
+    if (matchesPattern(path, pattern)) {
+      return config.service;
+    }
+  }
+  return void 0;
+};
+
+const createMiddlewareLogger = (options, request) => {
+  const { exclude, include, pail, routes, service } = options;
+  const { headers, method, path, requestId } = request;
+  if (!shouldLog(path, include, exclude)) {
+    const noopLogger = new WideEvent({ autoEmit: false, name: `${method} ${path}`, pail });
+    return {
+      finish: () => {
+      },
+      logger: noopLogger,
+      skipped: true
+    };
+  }
+  const routeService = getServiceForPath(path, routes) ?? service;
+  const logger = new WideEvent({
+    name: `${method} ${path}`,
+    pail,
+    service: routeService
+  });
+  logger.set({
+    method,
+    path,
+    requestId,
+    ...headers ? { headers } : {}
+  });
+  const finish = (finishOptions) => {
+    logger.finish(finishOptions);
+  };
+  return {
+    finish,
+    logger,
+    skipped: false
+  };
+};
+
+const SENSITIVE_HEADERS = /* @__PURE__ */ new Set(["authorization", "cookie", "proxy-authorization", "set-cookie", "x-api-key", "x-auth-token"]);
+const extractSafeHeaders = (headers) => {
+  const safe = {};
+  headers.forEach((value, key) => {
+    if (!SENSITIVE_HEADERS.has(key.toLowerCase())) {
+      safe[key.toLowerCase()] = value;
+    }
+  });
+  return safe;
+};
+const extractSafeNodeHeaders = (headers) => {
+  const safe = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (!SENSITIVE_HEADERS.has(key.toLowerCase()) && value !== void 0) {
+      safe[key.toLowerCase()] = Array.isArray(value) ? value.join(", ") : value;
+    }
+  }
+  return safe;
+};
+
+export { extractSafeHeaders as a, createMiddlewareLogger as c, extractSafeNodeHeaders as e };

package/dist/packem_shared/pailMiddleware-Ci88geIF.js

@@ -0,0 +1,24 @@
+const GLOB_STRIP_RE = /\*+/g;
+const pailMiddleware = (NextResponseClass, options) => {
+  const { exclude, include } = options ?? {};
+  return (request) => {
+    const path = request.nextUrl.pathname;
+    if (exclude?.some((p) => path.startsWith(p.replaceAll(GLOB_STRIP_RE, "")))) {
+      return NextResponseClass.next();
+    }
+    if (include?.length && !include.some((p) => path.startsWith(p.replaceAll(GLOB_STRIP_RE, "")))) {
+      return NextResponseClass.next();
+    }
+    const requestId = request.headers.get("x-request-id") ?? crypto.randomUUID();
+    const requestHeaders = new Headers(request.headers);
+    requestHeaders.set("x-request-id", requestId);
+    requestHeaders.set("x-pail-start", String(Date.now()));
+    const response = NextResponseClass.next({
+      request: { headers: requestHeaders }
+    });
+    response.headers.set("x-request-id", requestId);
+    return response;
+  };
+};
+
+export { pailMiddleware };

package/dist/packem_shared/storage-D0vqz8OX.js

@@ -0,0 +1,36 @@
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+const {
+  AsyncLocalStorage
+} = __cjs_getBuiltinModule("node:async_hooks");
+
+const createLoggerStorage = (contextHint) => {
+  const storage = new AsyncLocalStorage();
+  const useLogger = () => {
+    const logger = storage.getStore();
+    if (!logger) {
+      throw new Error(`[pail] useLogger() called outside of ${contextHint}`);
+    }
+    return logger;
+  };
+  return { storage, useLogger };
+};
+
+export { createLoggerStorage as c };

package/dist/packem_shared/useLogger-D0rU3lcX.js

@@ -0,0 +1,33 @@
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+const {
+  AsyncLocalStorage
+} = __cjs_getBuiltinModule("node:async_hooks");
+
+const pailStorage = new AsyncLocalStorage();
+const useLogger = () => {
+  const logger = pailStorage.getStore();
+  if (!logger) {
+    throw new Error("[pail] useLogger() called outside of withPail() context. Wrap your route handler or server action with withPail().");
+  }
+  return logger;
+};
+
+export { pailStorage, useLogger };

package/dist/processor/environment-processor.d.ts

@@ -0,0 +1,124 @@
+import type { Meta, Processor } from "../types.d.ts";
+/**
+ * Detected environment information.
+ *
+ * Contains runtime environment details that are automatically detected
+ * from environment variables and process information.
+ */
+interface EnvironmentInfo {
+    /** Git commit hash or short SHA */
+    commit?: string;
+    /** Runtime environment (e.g., "production", "development", "test") */
+    environment?: string;
+    /** Hostname of the machine */
+    hostname?: string;
+    /** Process ID */
+    pid?: number;
+    /** Cloud region (e.g., "us-east-1") */
+    region?: string;
+    /** Application/service name */
+    service?: string;
+    /** Application version */
+    version?: string;
+}
+/**
+ * Environment processor configuration options.
+ */
+interface EnvironmentProcessorOptions {
+    /**
+     * Whether to include the hostname. Defaults to false.
+     */
+    includeHostname?: boolean;
+    /**
+     * Whether to include the process ID. Defaults to false.
+     */
+    includePid?: boolean;
+    /**
+     * Static environment info to use instead of or in addition to auto-detection.
+     * Values provided here take precedence over auto-detected values.
+     */
+    overrides?: Partial<EnvironmentInfo>;
+}
+/**
+ * Detects the runtime environment from environment variables.
+ *
+ * Checks common environment variable patterns used by various hosting
+ * platforms (Vercel, AWS, GCP, Heroku, Railway, Fly.io, Render, etc.)
+ * to automatically determine service name, version, environment, region,
+ * and commit hash.
+ * @returns Detected environment information
+ */
+declare const detectEnvironment: () => EnvironmentInfo;
+/**
+ * Environment Enrichment Processor.
+ *
+ * Inspired by evlog's automatic environment detection, this processor
+ * enriches log metadata with runtime environment information. It auto-detects
+ * details like service name, version, environment, region, and commit hash
+ * from common environment variables used by popular hosting platforms.
+ *
+ * The detected info is added to the log's context, making it easier to
+ * correlate logs across services and deployments in production.
+ * @template L - The log level type
+ * @example
+ * ```typescript
+ * import { createPail } from "@visulima/pail";
+ * import EnvironmentProcessor from "@visulima/pail/processor/environment";
+ *
+ * const logger = createPail({
+ *   processors: [
+ *     new EnvironmentProcessor({
+ *       overrides: { service: "my-api" },
+ *       includePid: true,
+ *     }),
+ *   ],
+ * });
+ *
+ * logger.info("Server started");
+ * // Log metadata will include: { __env: { service: "my-api", environment: "production", ... } }
+ * ```
+ * @example
+ * ```typescript
+ * // With static configuration only (no auto-detection)
+ * new EnvironmentProcessor({
+ *   overrides: {
+ *     service: "payment-service",
+ *     version: "2.1.0",
+ *     environment: "staging",
+ *   },
+ * });
+ * ```
+ */
+declare class EnvironmentProcessor<L extends string = string> implements Processor<L> {
+    #private;
+    /**
+     * Creates a new EnvironmentProcessor instance.
+     *
+     * Auto-detects environment information on construction and merges
+     * with any provided overrides. Undefined values in overrides are
+     * filtered out so they don't overwrite detected values.
+     * @param options Processor configuration options
+     */
+    constructor(options?: EnvironmentProcessorOptions);
+    /**
+     * Processes log metadata to add environment information.
+     *
+     * Adds a `__env` property to the meta containing detected and
+     * configured environment details. Each call receives a shallow
+     * clone of the environment info to prevent cross-record mutation.
+     * @param meta The log metadata to process
+     * @returns The processed metadata with environment info added
+     */
+    process(meta: Meta<L>): Meta<L>;
+    /**
+     * Returns the detected environment information.
+     *
+     * Useful for inspecting what environment details were auto-detected.
+     * Returns a shallow clone to prevent external mutation.
+     * @returns The environment information object
+     */
+    getEnvironmentInfo(): Readonly<EnvironmentInfo>;
+}
+export { detectEnvironment };
+export default EnvironmentProcessor;
+export type { EnvironmentInfo, EnvironmentProcessorOptions };