@visulima/pail 4.0.2 → 4.1.1

package/dist/packem_shared/types.d-DGHeA2iJ.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 };

package/dist/packem_shared/useLogger-7p55yvvc.js

@@ -0,0 +1 @@
+import{createRequire as s}from"node:module";let i;const n=e=>(i??=s(import.meta.url))(e),o=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,c=e=>{if(typeof o<"u"&&o.versions&&o.versions.node){const[r,t]=o.versions.node.split(".").map(Number);if(r>22||r===22&&t>=3||r===20&&t>=16)return o.getBuiltinModule(e)}return n(e)},{AsyncLocalStorage:a}=c("node:async_hooks"),u=new a,_=()=>{const e=u.getStore();if(!e)throw new Error("[pail] useLogger() called outside of withPail() context. Wrap your route handler or server action with withPail().");return e};export{u as pailStorage,_ as useLogger};