@visulima/pail 4.0.0-alpha.11 → 4.0.0-alpha.12

package/dist/packem_shared/create-middleware-logger.d-DheMh8q4.d.ts

@@ -0,0 +1,47 @@
+import { P as PailBrowserImpl } from "./wide-event.d-B-t8ZnhI.js";
+import { D as DefaultLogTypes, e as LoggerFunction } from "./types.d-BeLumqgD.js";
+/**
+* Route configuration for a specific path pattern.
+*/
+interface RouteConfig {
+  /** Override the service name for requests matching this route. */
+  service?: string;
+}
+/**
+* A pail instance with dynamically generated log methods.
+*/
+type PailLike<T extends string = string> = PailBrowserImpl<T> & Record<DefaultLogTypes | T, LoggerFunction>;
+/**
+* Base options shared by all framework middleware adapters.
+* @template T - Custom logger type names from the pail instance
+*/
+interface PailMiddlewareOptions<T extends string = string> {
+  /**
+  * Glob patterns for paths to exclude from logging.
+  * Exclusions take precedence over inclusions.
+  * @example ["/health", "/api/_internal/**"]
+  */
+  exclude?: string[];
+  /**
+  * Glob patterns for paths to include in logging.
+  * If not set, all non-excluded paths are logged.
+  * @example ["/api/**"]
+  */
+  include?: string[];
+  /**
+  * The pail logger instance to use for wide event emission.
+  */
+  pail: PailLike<T>;
+  /**
+  * Route-specific configuration. Maps glob patterns to config.
+  * First matching route wins.
+  * @example { "/api/auth/**": { service: "auth-service" } }
+  */
+  routes?: Record<string, RouteConfig>;
+  /**
+  * Default service name for all wide events.
+  * Can be overridden per-route via `routes`.
+  */
+  service?: string;
+}
+export { PailMiddlewareOptions as P };

package/dist/packem_shared/{index-Bx3-C0j9.js → index-6cG1Kp0t.js}

@@ -330,7 +330,7 @@ const parseCss = (cssString) => {
   }
   return css;
 };
-const cssToAnsi = (css, previousCss = null) => {
+const cssToAnsi = (css, previousCss) => {
   previousCss = previousCss ?? getDefaultCss();
   let ansi = "";
   if (!colorEquals(css.backgroundColor, previousCss.backgroundColor)) {
@@ -507,7 +507,7 @@ const format = (fmt, arguments_ = [], options = {}) => {
   let a = 1 - offset;
   let lastPosition = -1;
   let usedStyle = false;
-  let previousCss = null;
+  let previousCss;
   for (let index = 0; index < fmt.length; ) {
     if (fmt.codePointAt(index) === CHAR_PERCENT && index + 1 < fmt.length) {
       lastPosition = lastPosition > -1 ? lastPosition : 0;

package/dist/packem_shared/types.d-BeLumqgD.d.ts

@@ -0,0 +1,246 @@
+import { AnsiColors } from '@visulima/colorize';
+import { InteractiveManager } from '@visulima/interactive-manager';
+/**
+Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+
+@category Type
+*/
+type Primitive = null | undefined | string | number | boolean | symbol | bigint;
+/**
+Create a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
+
+Currently, when a union type of a primitive type is combined with literal types, TypeScript loses all information about the combined literals. Thus, when such type is used in an IDE with autocompletion, no suggestions are made for the declared literals.
+
+This type is a workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729). It will be removed as soon as it's not needed anymore.
+
+@example
+```
+import type {LiteralUnion} from 'type-fest';
+
+// Before
+
+type Pet = 'dog' | 'cat' | string;
+
+const petWithoutAutocomplete: Pet = '';
+// Start typing in your TypeScript-enabled IDE.
+// You **will not** get auto-completion for `dog` and `cat` literals.
+
+// After
+
+type Pet2 = LiteralUnion<'dog' | 'cat', string>;
+
+const petWithAutoComplete: Pet2 = '';
+// You **will** get auto-completion for `dog` and `cat` literals.
+```
+
+@category Type
+*/
+type LiteralUnion<LiteralType, BaseType extends Primitive> = LiteralType | (BaseType & Record<never, never>);
+/**
+* Global namespace for extending Pail's metadata interface.
+*
+* This global declaration allows other packages and applications to extend
+* the Meta interface with custom properties by declaring additional properties
+* in the VisulimaPail.CustomMeta interface.
+* @example
+* ```typescript
+* declare global {
+*   namespace VisulimaPail {
+*     interface CustomMeta<L> {
+*       userId?: string;
+*       requestId?: string;
+*     }
+*   }
+* }
+* ```
+*/
+declare global {
+  namespace VisulimaPail {
+    interface CustomMeta<L> {}
+  }
+}
+/**
+* Metadata object containing all information about a log entry.
+*
+* This interface defines the structure of metadata that is passed to reporters
+* and processors. It contains all the contextual information about a log message
+* including the message itself, timing information, error details, and more.
+* @template L - The log level type
+*/
+interface Meta<L> extends VisulimaPail.CustomMeta<L> {
+  badge: string | undefined;
+  context: any[] | undefined;
+  date: Date | string;
+  error: Error | undefined;
+  groups: string[];
+  label: string | undefined;
+  message: Primitive | ReadonlyArray<unknown> | Record<PropertyKey, unknown>;
+  prefix: string | undefined;
+  repeated?: number;
+  scope: string[] | undefined;
+  suffix: string | undefined;
+  traceError: Error | undefined;
+  type: {
+    level: ExtendedRfc5424LogLevels | L;
+    name: string;
+  };
+}
+/**
+* Extended RFC 5424 Log Levels.
+*
+* Standard syslog severity levels as defined in RFC 5424, plus additional
+* levels commonly used in modern applications. Each level has a numeric
+* priority where lower numbers indicate higher severity.
+* @see https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1
+*/
+type ExtendedRfc5424LogLevels = "alert" | "critical" | "debug" | "emergency" | "error" | "informational" | "notice" | "trace" | "warning";
+/**
+* Default Log Types.
+*
+* Predefined semantic log types that provide meaningful categorization
+* for different kinds of log messages. Each type has associated styling
+* and log level configuration.
+*/
+type DefaultLogTypes = "alert" | "await" | "complete" | "critical" | "debug" | "emergency" | "error" | "info" | "log" | "notice" | "pending" | "start" | "stop" | "success" | "trace" | "wait" | "warn" | "warning" | "watch";
+/**
+* Logger Function Type.
+*
+* Represents a logging function that can accept either a structured Message object
+* or multiple arguments in the traditional console.log style.
+*/
+interface LoggerFunction {
+  (message: Message): void;
+  (...message: any[]): void;
+}
+/**
+* Logger Configuration.
+*
+* Configuration object that defines how a specific logger type should behave,
+* including its visual appearance and log level.
+* @template L - The log level type
+*/
+interface LoggerConfiguration<L extends string> {
+  badge?: string;
+  color?: AnsiColors;
+  label: string;
+  logLevel: LiteralUnion<ExtendedRfc5424LogLevels, L>;
+}
+/**
+* Logger Types Configuration.
+*
+* A record mapping logger type names to their configurations.
+* @template T - Custom logger type names
+* @template L - Log level types
+*/
+type LoggerTypesConfig<T extends string, L extends string> = Record<T, Partial<LoggerConfiguration<L>>>;
+/**
+* Read-only Metadata.
+*
+* Immutable version of the Meta interface for use in reporters.
+* @template L - The log level type
+*/
+type ReadonlyMeta<L extends string> = Readonly<Meta<L>>;
+/**
+* Reporter Interface.
+*
+* Base interface for all reporters. Reporters are responsible for
+* outputting log messages to various destinations (console, files, etc.).
+* @template L - The log level type
+*/
+interface Reporter<L extends string> {
+  log: (meta: ReadonlyMeta<L>) => void;
+}
+/**
+* Stream-Aware Reporter Interface.
+*
+* Extends Reporter with the ability to work with Node.js streams.
+* Used for server-side reporters that need to write to stdout/stderr.
+* @template L - The log level type
+*/
+interface StreamAwareReporter<L extends string> extends Reporter<L> {
+  /** Set the stderr stream for error output */
+  setStderr: (stderr: NodeJS.WriteStream) => void;
+  /** Set the stdout stream for standard output */
+  setStdout: (stdout: NodeJS.WriteStream) => void;
+}
+/**
+* Logger Types Aware Reporter Interface.
+*
+* Extends Reporter with the ability to receive logger type configurations.
+* Allows reporters to customize their output based on logger types.
+* @template T - Custom logger type names
+* @template L - The log level type
+*/
+interface LoggerTypesAwareReporter<T extends string, L extends string> extends Reporter<L> {
+  /** Set the logger types configuration */
+  setLoggerTypes: (types: LoggerTypesConfig<T, L> & Partial<LoggerTypesConfig<DefaultLogTypes, L>>) => void;
+}
+/**
+* Stringify-Aware Reporter Interface.
+*
+* Extends Reporter with the ability to receive a custom stringify function.
+* Useful for reporters that need to serialize complex objects.
+* @template L - The log level type
+*/
+interface StringifyAwareReporter<L extends string> extends Reporter<L> {
+  /** Set the stringify function for object serialization */
+  setStringify: (stringify: any) => void;
+}
+/**
+* Interactive Stream Reporter Interface.
+*
+* Extends StreamAwareReporter with interactive capabilities for terminal UIs.
+* Supports features like progress bars and dynamic updates.
+* @template L - The log level type
+*/
+interface InteractiveStreamReporter<L extends string> extends StreamAwareReporter<L> {
+  /** Set the interactive manager for handling interactive output */
+  setInteractiveManager: (manager?: InteractiveManager) => void;
+  /** Enable or disable interactive mode */
+  setIsInteractive: (interactive: boolean) => void;
+}
+/**
+* Processor Interface.
+*
+* Base interface for all processors. Processors can modify or enhance
+* log metadata before it reaches reporters.
+* @template L - The log level type
+*/
+interface Processor<L extends string> {
+  /** Process the log metadata */
+  process: (meta: Meta<L>) => Meta<L>;
+}
+/**
+* Stringify-Aware Processor Interface.
+*
+* Extends Processor with the ability to receive a custom stringify function.
+* Useful for processors that need to serialize complex objects.
+* @template L - The log level type
+*/
+interface StringifyAwareProcessor<L extends string> extends Processor<L> {
+  /** Set the stringify function for object serialization */
+  setStringify: (stringify: typeof JSON.stringify) => void;
+}
+interface ConstructorOptions<T extends string, L extends string> {
+  disabled?: boolean;
+  logLevel?: LiteralUnion<ExtendedRfc5424LogLevels, L>;
+  logLevels?: Partial<Record<ExtendedRfc5424LogLevels, number>> & Record<L, number>;
+  messages?: {
+    timerEnd?: string;
+    timerStart?: string;
+  };
+  processors?: Processor<L>[];
+  rawReporter?: Reporter<L>;
+  reporters?: Reporter<L>[];
+  scope?: string[] | string;
+  throttle?: number;
+  throttleMin?: number;
+  types?: LoggerTypesConfig<T, L> & Partial<LoggerTypesConfig<DefaultLogTypes, L>>;
+}
+type Message = {
+  context?: any[];
+  message: any;
+  prefix?: string;
+  suffix?: string;
+};
+export { ConstructorOptions as C, DefaultLogTypes as D, ExtendedRfc5424LogLevels as E, InteractiveStreamReporter as I, LiteralUnion as L, Meta as M, Processor as P, ReadonlyMeta as R, StringifyAwareReporter as S, StreamAwareReporter as a, StringifyAwareProcessor as b, LoggerTypesConfig as c, Reporter as d, LoggerFunction as e, LoggerTypesAwareReporter as f };

package/dist/packem_shared/types.d-C51XNfQz.d.ts

@@ -0,0 +1,194 @@
+import { AnsiColors } from '@visulima/colorize';
+import '@visulima/interactive-manager';
+import { LiteralUnion, Primitive } from 'type-fest';
+/**
+* Global namespace for extending Pail's metadata interface.
+*
+* This global declaration allows other packages and applications to extend
+* the Meta interface with custom properties by declaring additional properties
+* in the VisulimaPail.CustomMeta interface.
+* @example
+* ```typescript
+* declare global {
+*   namespace VisulimaPail {
+*     interface CustomMeta<L> {
+*       userId?: string;
+*       requestId?: string;
+*     }
+*   }
+* }
+* ```
+*/
+declare global {
+  namespace VisulimaPail {
+    interface CustomMeta<L> {}
+  }
+}
+/**
+* Metadata object containing all information about a log entry.
+*
+* This interface defines the structure of metadata that is passed to reporters
+* and processors. It contains all the contextual information about a log message
+* including the message itself, timing information, error details, and more.
+* @template L - The log level type
+*/
+interface Meta<L> extends VisulimaPail.CustomMeta<L> {
+  badge: string | undefined;
+  context: any[] | undefined;
+  date: Date | string;
+  error: Error | undefined;
+  groups: string[];
+  label: string | undefined;
+  message: Primitive | ReadonlyArray<unknown> | Record<PropertyKey, unknown>;
+  prefix: string | undefined;
+  repeated?: number;
+  scope: string[] | undefined;
+  suffix: string | undefined;
+  traceError: Error | undefined;
+  type: {
+    level: ExtendedRfc5424LogLevels | L;
+    name: string;
+  };
+}
+/**
+* Extended RFC 5424 Log Levels.
+*
+* Standard syslog severity levels as defined in RFC 5424, plus additional
+* levels commonly used in modern applications. Each level has a numeric
+* priority where lower numbers indicate higher severity.
+* @see https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1
+*/
+type ExtendedRfc5424LogLevels = "alert" | "critical" | "debug" | "emergency" | "error" | "informational" | "notice" | "trace" | "warning";
+/**
+* Default Log Types.
+*
+* Predefined semantic log types that provide meaningful categorization
+* for different kinds of log messages. Each type has associated styling
+* and log level configuration.
+*/
+type DefaultLogTypes = "alert" | "await" | "complete" | "critical" | "debug" | "emergency" | "error" | "info" | "log" | "notice" | "pending" | "start" | "stop" | "success" | "trace" | "wait" | "warn" | "warning" | "watch";
+/**
+* Logger Function Type.
+*
+* Represents a logging function that can accept either a structured Message object
+* or multiple arguments in the traditional console.log style.
+*/
+interface LoggerFunction {
+  (message: Message): void;
+  (...message: any[]): void;
+}
+/**
+* Logger Configuration.
+*
+* Configuration object that defines how a specific logger type should behave,
+* including its visual appearance and log level.
+* @template L - The log level type
+*/
+interface LoggerConfiguration<L extends string> {
+  badge?: string;
+  color?: AnsiColors;
+  label: string;
+  logLevel: LiteralUnion<ExtendedRfc5424LogLevels, L>;
+}
+/**
+* Logger Types Configuration.
+*
+* A record mapping logger type names to their configurations.
+* @template T - Custom logger type names
+* @template L - Log level types
+*/
+type LoggerTypesConfig<T extends string, L extends string> = Record<T, Partial<LoggerConfiguration<L>>>;
+/**
+* Default Logger Types Configuration.
+*
+* A complete mapping of all default log types to their full configurations.
+* @template L - Log level types
+*/
+type DefaultLoggerTypes<L extends string = string> = Record<DefaultLogTypes, LoggerConfiguration<L>>;
+/**
+* Read-only Metadata.
+*
+* Immutable version of the Meta interface for use in reporters.
+* @template L - The log level type
+*/
+type ReadonlyMeta<L extends string> = Readonly<Meta<L>>;
+/**
+* Reporter Interface.
+*
+* Base interface for all reporters. Reporters are responsible for
+* outputting log messages to various destinations (console, files, etc.).
+* @template L - The log level type
+*/
+interface Reporter<L extends string> {
+  log: (meta: ReadonlyMeta<L>) => void;
+}
+/**
+* Stream-Aware Reporter Interface.
+*
+* Extends Reporter with the ability to work with Node.js streams.
+* Used for server-side reporters that need to write to stdout/stderr.
+* @template L - The log level type
+*/
+interface StreamAwareReporter<L extends string> extends Reporter<L> {
+  /** Set the stderr stream for error output */
+  setStderr: (stderr: NodeJS.WriteStream) => void;
+  /** Set the stdout stream for standard output */
+  setStdout: (stdout: NodeJS.WriteStream) => void;
+}
+/**
+* Logger Types Aware Reporter Interface.
+*
+* Extends Reporter with the ability to receive logger type configurations.
+* Allows reporters to customize their output based on logger types.
+* @template T - Custom logger type names
+* @template L - The log level type
+*/
+interface LoggerTypesAwareReporter<T extends string, L extends string> extends Reporter<L> {
+  /** Set the logger types configuration */
+  setLoggerTypes: (types: LoggerTypesConfig<T, L> & Partial<LoggerTypesConfig<DefaultLogTypes, L>>) => void;
+}
+/**
+* Stringify-Aware Reporter Interface.
+*
+* Extends Reporter with the ability to receive a custom stringify function.
+* Useful for reporters that need to serialize complex objects.
+* @template L - The log level type
+*/
+interface StringifyAwareReporter<L extends string> extends Reporter<L> {
+  /** Set the stringify function for object serialization */
+  setStringify: (stringify: any) => void;
+}
+/**
+* Processor Interface.
+*
+* Base interface for all processors. Processors can modify or enhance
+* log metadata before it reaches reporters.
+* @template L - The log level type
+*/
+interface Processor<L extends string> {
+  /** Process the log metadata */
+  process: (meta: Meta<L>) => Meta<L>;
+}
+interface ConstructorOptions<T extends string, L extends string> {
+  disabled?: boolean;
+  logLevel?: LiteralUnion<ExtendedRfc5424LogLevels, L>;
+  logLevels?: Partial<Record<ExtendedRfc5424LogLevels, number>> & Record<L, number>;
+  messages?: {
+    timerEnd?: string;
+    timerStart?: string;
+  };
+  processors?: Processor<L>[];
+  rawReporter?: Reporter<L>;
+  reporters?: Reporter<L>[];
+  scope?: string[] | string;
+  throttle?: number;
+  throttleMin?: number;
+  types?: LoggerTypesConfig<T, L> & Partial<LoggerTypesConfig<DefaultLogTypes, L>>;
+}
+type Message = {
+  context?: any[];
+  message: any;
+  prefix?: string;
+  suffix?: string;
+};
+export { ConstructorOptions as C, DefaultLogTypes as D, ExtendedRfc5424LogLevels as E, LoggerTypesConfig as L, Meta as M, Processor as P, ReadonlyMeta as R, StringifyAwareReporter as S, LoggerTypesAwareReporter as a, Reporter as b, LoggerFunction as c, DefaultLoggerTypes as d, LoggerConfiguration as e, StreamAwareReporter as f };