@visulima/pail 4.0.0-alpha.5 → 4.0.0-alpha.7

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

@@ -0,0 +1,111 @@
+import type { Meta, Processor } from "../types.d.ts";
+/**
+ * Head sampling configuration.
+ *
+ * Controls random sampling rates per log level. Each key is a log level name
+ * and the value is the percentage (0-100) of logs at that level to keep.
+ * Levels not listed default to 100 (keep all).
+ * @example
+ * ```typescript
+ * const headSampling: HeadSamplingConfig = {
+ *   debug: 0,      // Drop all debug logs
+ *   informational: 10,  // Keep 10% of info logs
+ *   warning: 50,   // Keep 50% of warning logs
+ *   error: 100,    // Keep all error logs
+ * };
+ * ```
+ */
+type HeadSamplingConfig = Partial<Record<string, number>>;
+/**
+ * Tail sampling condition function.
+ *
+ * A function that receives the log metadata and returns true if the log
+ * should be force-kept regardless of head sampling. This allows keeping
+ * important logs based on their content (e.g., errors, slow operations).
+ * @template L - The log level type
+ */
+type TailSamplingCondition<L extends string = string> = (meta: Readonly<Meta<L>>) => boolean;
+/**
+ * Sampling processor configuration options.
+ */
+interface SamplingProcessorOptions<L extends string = string> {
+    /**
+     * Head sampling rates per log level.
+     *
+     * A map of log level to sampling percentage (0-100).
+     * Levels not specified default to 100 (keep all).
+     * Set to 0 to drop all logs at that level.
+     */
+    head?: HeadSamplingConfig;
+    /**
+     * Tail sampling conditions.
+     *
+     * An array of condition functions that can force-keep a log entry
+     * even if it was dropped by head sampling. If any condition returns true,
+     * the log is kept.
+     */
+    tail?: TailSamplingCondition<L>[];
+}
+/**
+ * Sampling Processor.
+ *
+ * Inspired by evlog's production sampling strategy, this processor implements
+ * both head sampling (random per-level) and tail sampling (force-keep based
+ * on conditions) to control log volume in production environments.
+ *
+ * **Head sampling** randomly drops a percentage of logs per level. This is
+ * evaluated first and provides broad volume control.
+ *
+ * **Tail sampling** can override head sampling to force-keep important logs
+ * based on their content. For example, you might drop 90% of info logs but
+ * force-keep any that contain error information or relate to slow operations.
+ *
+ * When a log is dropped by sampling, the processor sets a `__dropped: true`
+ * boolean flag on the meta object. Reporters should check for this flag and
+ * skip entries where `__dropped` is `true`.
+ * @template L - The log level type
+ * @example
+ * ```typescript
+ * import { createPail } from "@visulima/pail";
+ * import SamplingProcessor from "@visulima/pail/processor/sampling";
+ *
+ * const logger = createPail({
+ *   processors: [
+ *     new SamplingProcessor({
+ *       head: {
+ *         debug: 0,         // Drop all debug logs
+ *         informational: 10, // Keep 10% of info logs
+ *         warning: 50,      // Keep 50% of warnings
+ *         error: 100,       // Keep all errors
+ *       },
+ *       tail: [
+ *         // Force-keep logs with errors regardless of head sampling
+ *         (meta) => meta.error !== undefined,
+ *         // Force-keep logs from critical scopes
+ *         (meta) => meta.scope?.includes("payment") ?? false,
+ *       ],
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare class SamplingProcessor<L extends string = string> implements Processor<L> {
+    #private;
+    /**
+     * Creates a new SamplingProcessor instance.
+     * @param options Sampling configuration options
+     */
+    constructor(options?: SamplingProcessorOptions<L>);
+    /**
+     * Processes log metadata to apply sampling rules.
+     *
+     * First evaluates head sampling (random per-level), then checks tail
+     * sampling conditions. If a log is dropped, the meta is marked with
+     * `__dropped: true` so reporters can skip it.
+     * @param meta The log metadata to process
+     * @returns The processed metadata, potentially marked as dropped
+     */
+    process(meta: Meta<L>): Meta<L>;
+}
+export default SamplingProcessor;
+export type { HeadSamplingConfig, SamplingProcessorOptions, TailSamplingCondition };

package/dist/processor/sampling-processor.js

@@ -0,0 +1,59 @@
+class SamplingProcessor {
+  #headRates;
+  #tailConditions;
+  /**
+   * Creates a new SamplingProcessor instance.
+   * @param options Sampling configuration options
+   */
+  constructor(options = {}) {
+    this.#headRates = options.head ?? {};
+    this.#tailConditions = options.tail ?? [];
+  }
+  /**
+   * Processes log metadata to apply sampling rules.
+   *
+   * First evaluates head sampling (random per-level), then checks tail
+   * sampling conditions. If a log is dropped, the meta is marked with
+   * `__dropped: true` so reporters can skip it.
+   * @param meta The log metadata to process
+   * @returns The processed metadata, potentially marked as dropped
+   */
+  process(meta) {
+    const level = meta.type.level;
+    if (this.#shouldDrop(level) && !this.#shouldForceKeep(meta)) {
+      return { ...meta, dropped: true };
+    }
+    return meta;
+  }
+  /**
+   * Evaluates head sampling for the given log level.
+   * @returns true if the log should be dropped
+   */
+  #shouldDrop(level) {
+    const rate = this.#headRates[level];
+    if (rate === void 0) {
+      return false;
+    }
+    if (rate <= 0) {
+      return true;
+    }
+    if (rate >= 100) {
+      return false;
+    }
+    return Math.random() * 100 >= rate;
+  }
+  /**
+   * Evaluates tail sampling conditions.
+   * @returns true if any condition forces keeping the log
+   */
+  #shouldForceKeep(meta) {
+    for (const condition of this.#tailConditions) {
+      if (condition(meta)) {
+        return true;
+      }
+    }
+    return false;
+  }
+}
+
+export { SamplingProcessor as default };

package/dist/reporter/file/json-file-reporter.js

@@ -1,4 +1,4 @@
-import { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-DWRpTtGw.js';
+import { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-CGKHS8_M.js';
 
 class SafeStreamHandler {
   #ready = true;

package/dist/reporter/http/abstract-http-reporter.js

@@ -20,7 +20,7 @@ const __cjs_getBuiltinModule = (module) => {
 const {
   Buffer
 } = __cjs_getBuiltinModule("node:buffer");
-import { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-DWRpTtGw.js';
+import { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-CGKHS8_M.js';
 const {
   gzipSync
 } = __cjs_getBuiltinModule("node:zlib");

package/dist/reporter/http/http-reporter.edge-light.js

@@ -36,7 +36,7 @@ const ErrorProto = Object.create(
   {},
   {
     cause: {
-      enumerable: true,
+      enumerable: false,
       value: void 0,
       writable: true
     },
@@ -46,32 +46,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) => {
@@ -82,7 +105,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;
@@ -97,11 +120,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);
@@ -115,7 +141,7 @@ const serializeValue = (value, seen, depth, options) => {
   }
 };
 const _serialize = (error, options, seen, depth) => {
-  seen.push(error);
+  seen.add(error);
   if (options.maxDepth === 0) {
     return {};
   }
@@ -123,31 +149,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) {
@@ -166,7 +248,7 @@ const serialize = (error, options = {}) => _serialize(
     maxDepth: options.maxDepth ?? Number.POSITIVE_INFINITY,
     useToJSON: options.useToJSON ?? false
   },
-  [],
+  /* @__PURE__ */ new Set(),
   0
 );
 

package/dist/reporter/json/index.browser.js

@@ -1,2 +1,2 @@
-export { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-BaZ33PlE.js';
-export { default as JsonReporter } from '../../packem_shared/JsonReporter-BRw4skd5.js';
+export { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-DDjDkciI.js';
+export { default as JsonReporter } from '../../packem_shared/JsonReporter-p_BXg6Sj.js';

package/dist/reporter/json/index.js

@@ -1,2 +1,2 @@
-export { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-DWRpTtGw.js';
-export { default as JsonReporter } from '../../packem_shared/JsonReporter-BV5lMnJX.js';
+export { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-CGKHS8_M.js';
+export { default as JsonReporter } from '../../packem_shared/JsonReporter-B3XX8GHN.js';

package/dist/reporter/pretty/index.js

@@ -1 +1 @@
-export { PrettyReporter } from '../../packem_shared/PrettyReporter-DLQtmATi.js';
+export { PrettyReporter } from '../../packem_shared/PrettyReporter-CvBn-hxP.js';

package/dist/reporter/simple/simple-reporter.server.js

@@ -8,10 +8,11 @@ const {
   stdout,
   stderr
 } = __cjs_getProcess;
-import colorize, { red, greenBright, cyan, green, grey, bold, white, bgGrey, underline } from '@visulima/colorize';
-import { A as AbstractPrettyReporter, d as defaultInspectorConfig, b as writeStream, t as terminalSize, c as getLongestBadge, g as getLongestLabel, e as getStringWidth, f as formatLabel, a as EMPTY_SYMBOL, i as inspect, w as wordWrap, r as renderError, W as WrapMode } from '../../packem_shared/abstract-pretty-reporter-DckLMlGF.js';
+import colorize, { red, greenBright, cyan, green, grey, bold, bgGrey, underline, white } from '@visulima/colorize';
+import { A as AbstractPrettyReporter, d as defaultInspectorConfig, b as writeStream, t as terminalSize, c as getLongestBadge, g as getLongestLabel, e as getStringWidth, f as formatLabel, a as EMPTY_SYMBOL, i as inspect, w as wordWrap, r as renderError, W as WrapMode } from '../../packem_shared/abstract-pretty-reporter-jU8WL_6c.js';
 
-const pailFileFilter = (line) => !/[\\/]pail[\\/]dist/.test(line);
+const PAIL_DIST_REGEX = /[\\/]pail[\\/]dist/;
+const pailFileFilter = (line) => !PAIL_DIST_REGEX.test(line);
 class SimpleReporter extends AbstractPrettyReporter {
   #stdout;
   #stderr;

package/dist/spinner.js

@@ -1663,6 +1663,38 @@ var dwarfFortress = {
 		" ██████£££  "
 	]
 };
+var fish = {
+	interval: 80,
+	frames: [
+		"~~~~~~~~~~~~~~~~~~~~",
+		"> ~~~~~~~~~~~~~~~~~~",
+		"º> ~~~~~~~~~~~~~~~~~",
+		"(º> ~~~~~~~~~~~~~~~~",
+		"((º> ~~~~~~~~~~~~~~~",
+		"<((º> ~~~~~~~~~~~~~~",
+		"><((º> ~~~~~~~~~~~~~",
+		" ><((º> ~~~~~~~~~~~~",
+		"~ ><((º> ~~~~~~~~~~~",
+		"~~ <>((º> ~~~~~~~~~~",
+		"~~~ ><((º> ~~~~~~~~~",
+		"~~~~ <>((º> ~~~~~~~~",
+		"~~~~~ ><((º> ~~~~~~~",
+		"~~~~~~ <>((º> ~~~~~~",
+		"~~~~~~~ ><((º> ~~~~~",
+		"~~~~~~~~ <>((º> ~~~~",
+		"~~~~~~~~~ ><((º> ~~~",
+		"~~~~~~~~~~ <>((º> ~~",
+		"~~~~~~~~~~~ ><((º> ~",
+		"~~~~~~~~~~~~ <>((º> ",
+		"~~~~~~~~~~~~~ ><((º>",
+		"~~~~~~~~~~~~~~ <>((º",
+		"~~~~~~~~~~~~~~~ ><((",
+		"~~~~~~~~~~~~~~~~ <>(",
+		"~~~~~~~~~~~~~~~~~ ><",
+		"~~~~~~~~~~~~~~~~~~ <",
+		"~~~~~~~~~~~~~~~~~~~~"
+	]
+};
 const spinners = {
 	dots: dots,
 	dots2: dots2,
@@ -1752,7 +1784,8 @@ const spinners = {
 	orangeBluePulse: orangeBluePulse,
 	timeTravel: timeTravel,
 	aesthetic: aesthetic,
-	dwarfFortress: dwarfFortress
+	dwarfFortress: dwarfFortress,
+	fish: fish
 };
 
 const DEFAULT_ICONS = {