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

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

@@ -0,0 +1,236 @@
+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>>>;
+/**
+* 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;
+}
+/**
+* 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>;
+}
+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>>;
+}
+interface ServerConstructorOptions<T extends string, L extends string> extends ConstructorOptions<T, L> {
+  interactive?: boolean;
+  stderr: NodeJS.WriteStream;
+  stdout: NodeJS.WriteStream;
+}
+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, Reporter as R, ServerConstructorOptions as S, LoggerTypesConfig as a, LoggerFunction as b, DefaultLoggerTypes as c, LoggerConfiguration as d, LoggerTypesAwareReporter as e, StreamAwareReporter as f, ReadonlyMeta as g };