plslog 1.0.0 → 1.1.0

package/dist/index.d.mts

@@ -1,34 +1,179 @@
 type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
+type FilterMode = 'redact' | 'hide' | 'type' | 'length';
+type FilterFieldPredicate = (key: string, value: any, path: string[]) => boolean;
+type FilterFieldConfig = string | RegExp | FilterFieldPredicate;
+interface DedupConfig {
+    enabled: boolean;
+    flushInterval?: number;
+}
+interface DedupEntry {
+    key: string;
+    level: LogLevel;
+    message: string;
+    args: unknown[];
+    count: number;
+    firstTimestamp: number;
+    lastTimestamp: number;
+    flushTimeoutId?: number;
+    filterOptions?: LogFilterOptions;
+}
+interface LogFilterOptions {
+    pick?: string[];
+    omit?: FilterFieldConfig[];
+    filterMode?: FilterMode;
+    filterReplacement?: string;
+}
+interface ErrorSerializationConfig {
+    includeStack?: boolean;
+    stackFrameLimit?: number;
+    includeCause?: boolean;
+    maxCauseDepth?: number;
+    sanitizeStack?: boolean;
+    sanitizePatterns?: RegExp[];
+}
+interface FormatterOptions extends LogFilterOptions {
+    maxDepth?: number;
+    filterFields?: FilterFieldConfig[];
+    globalFilterMode?: FilterMode;
+    globalFilterReplacement?: string;
+    errorConfig?: ErrorSerializationConfig;
+}
 interface LoggerOptions {
     namespace?: string;
     level?: LogLevel;
     maxDepth?: number;
+    dedup?: Partial<DedupConfig>;
+    context?: Record<string, unknown>;
 }
 type GlobalConfig = {
     namespaces?: string;
     level?: LogLevel;
     activeLevels?: LogLevel[];
     maxDepth?: number;
+    dedup?: Partial<DedupConfig>;
+    filterFields?: FilterFieldConfig[];
+    filterMode?: FilterMode;
+    filterReplacement?: string;
+    errorSerialization?: ErrorSerializationConfig;
 };
+interface ConditionContext {
+    namespace: string;
+    level: LogLevel;
+    [key: string]: unknown;
+}
+type Condition = boolean | ((ctx: ConditionContext) => boolean);
 
 declare class Logger {
     private _namespace;
     private _level;
     private _maxDepth;
+    private _dedupConfig;
+    private _dedupBuffer;
+    private _tempFilterOptions;
+    private _context;
+    private _tempConditions;
     constructor(options?: LoggerOptions);
     debug(message: string, ...args: unknown[]): this;
     info(message: string, ...args: unknown[]): this;
     warn(message: string, ...args: unknown[]): this;
     error(message: string, ...args: unknown[]): this;
+    /**
+     * Assert that a condition is truthy. Logs an error if the condition is falsy.
+     * Similar to console.assert() but integrates with plslog's features.
+     * Uses JavaScript truthiness - falsy values: false, 0, '', null, undefined, NaN
+     *
+     * @param condition - The condition to assert (uses JavaScript truthiness)
+     * @param message - Error message to log if assertion fails
+     * @param args - Additional arguments to log
+     * @returns this for chaining
+     *
+     * @example
+     * logger.assert(user !== null, 'User should not be null', user);
+     * logger.assert(count > 0, 'Count must be positive', { count });
+     * logger.assert(data, 'Data is required'); // Checks if data is truthy
+     */
+    assert(condition: unknown, message: string, ...args: unknown[]): this;
     setLevel(level: LogLevel): void;
+    /**
+     * Set the namespace for this logger instance
+     * Returns this for method chaining
+     *
+     * @param namespace - The namespace string (e.g., 'service:api', 'component')
+     * @returns this for chaining
+     *
+     * @example
+     * const log = logger().namespace('service:api');
+     * log.debug('Message'); // Logs with namespace 'service:api'
+     *
+     * // Can also be called after instantiation
+     * const log2 = logger();
+     * log2.namespace('component').debug('Message');
+     */
+    namespace(namespace: string): this;
     maxDepth(maxDepth: number): this;
+    /**
+     * Pick only specific fields to log (whitelist approach)
+     * Supports dot notation for nested fields: 'user.name', 'user.email'
+     * Supports wildcards: 'user.*' matches all fields under user
+     */
+    pick(fields: string[]): this;
+    /**
+     * Omit specific fields from logging (blacklist approach)
+     * Supports strings, regex patterns, and predicate functions
+     */
+    omit(fields: FilterFieldConfig[]): this;
+    /**
+     * Set filter mode for per-log filtering
+     * - 'redact': Replace with custom string (default: '***REDACTED***')
+     * - 'hide': Remove field completely
+     * - 'type': Show type info like '[string]', '[Array(3)]'
+     * - 'length': Show length info like '[8 chars]', '[3 items]'
+     */
+    filterMode(mode: FilterMode, replacement?: string): this;
+    once(enabled?: boolean): this;
+    flushDedup(): this;
+    /**
+     * Execute log only if condition is true
+     * Supports boolean values or predicate functions
+     * Multiple when() calls are AND-ed together
+     *
+     * @example
+     * // Boolean condition
+     * logger.when(isDev).debug('Dev only');
+     *
+     * // Predicate with context
+     * logger.when(ctx => ctx.namespace === 'auth').debug('Auth log');
+     *
+     * // Chaining (both must be true)
+     * logger
+     *   .when(ctx => ctx.level === 'debug')
+     *   .when(isDevMode)
+     *   .debug('Conditional');
+     */
+    when(condition: Condition): this;
+    /**
+     * Execute log only if condition is false (inverse of when)
+     * Supports boolean values or predicate functions
+     *
+     * @example
+     * // Boolean condition
+     * logger.unless(isProd).debug('Not in production');
+     *
+     * // Predicate with context
+     * logger.unless(ctx => ctx.level === 'error').info('Non-error log');
+     */
+    unless(condition: Condition): this;
     private getLevelPriority;
     private log;
+    private logWithDedup;
+    private flushDedupEntry;
+    private formatTimestamp;
+    private logImmediate;
 }
 type Plslog = {
-    (options?: LoggerOptions): Logger;
+    (options?: LoggerOptions | string): Logger;
     configure(options: GlobalConfig): void;
 };
 declare const plslog: Plslog;
 
-export { type GlobalConfig, type LogLevel, type LoggerOptions, plslog as default };
+export { type Condition, type ConditionContext, type DedupConfig, type DedupEntry, type ErrorSerializationConfig, type FilterFieldConfig, type FilterFieldPredicate, type FilterMode, type FormatterOptions, type GlobalConfig, type LogFilterOptions, type LogLevel, type LoggerOptions, plslog as default };

package/dist/index.d.ts

@@ -1,34 +1,179 @@
 type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
+type FilterMode = 'redact' | 'hide' | 'type' | 'length';
+type FilterFieldPredicate = (key: string, value: any, path: string[]) => boolean;
+type FilterFieldConfig = string | RegExp | FilterFieldPredicate;
+interface DedupConfig {
+    enabled: boolean;
+    flushInterval?: number;
+}
+interface DedupEntry {
+    key: string;
+    level: LogLevel;
+    message: string;
+    args: unknown[];
+    count: number;
+    firstTimestamp: number;
+    lastTimestamp: number;
+    flushTimeoutId?: number;
+    filterOptions?: LogFilterOptions;
+}
+interface LogFilterOptions {
+    pick?: string[];
+    omit?: FilterFieldConfig[];
+    filterMode?: FilterMode;
+    filterReplacement?: string;
+}
+interface ErrorSerializationConfig {
+    includeStack?: boolean;
+    stackFrameLimit?: number;
+    includeCause?: boolean;
+    maxCauseDepth?: number;
+    sanitizeStack?: boolean;
+    sanitizePatterns?: RegExp[];
+}
+interface FormatterOptions extends LogFilterOptions {
+    maxDepth?: number;
+    filterFields?: FilterFieldConfig[];
+    globalFilterMode?: FilterMode;
+    globalFilterReplacement?: string;
+    errorConfig?: ErrorSerializationConfig;
+}
 interface LoggerOptions {
     namespace?: string;
     level?: LogLevel;
     maxDepth?: number;
+    dedup?: Partial<DedupConfig>;
+    context?: Record<string, unknown>;
 }
 type GlobalConfig = {
     namespaces?: string;
     level?: LogLevel;
     activeLevels?: LogLevel[];
     maxDepth?: number;
+    dedup?: Partial<DedupConfig>;
+    filterFields?: FilterFieldConfig[];
+    filterMode?: FilterMode;
+    filterReplacement?: string;
+    errorSerialization?: ErrorSerializationConfig;
 };
+interface ConditionContext {
+    namespace: string;
+    level: LogLevel;
+    [key: string]: unknown;
+}
+type Condition = boolean | ((ctx: ConditionContext) => boolean);
 
 declare class Logger {
     private _namespace;
     private _level;
     private _maxDepth;
+    private _dedupConfig;
+    private _dedupBuffer;
+    private _tempFilterOptions;
+    private _context;
+    private _tempConditions;
     constructor(options?: LoggerOptions);
     debug(message: string, ...args: unknown[]): this;
     info(message: string, ...args: unknown[]): this;
     warn(message: string, ...args: unknown[]): this;
     error(message: string, ...args: unknown[]): this;
+    /**
+     * Assert that a condition is truthy. Logs an error if the condition is falsy.
+     * Similar to console.assert() but integrates with plslog's features.
+     * Uses JavaScript truthiness - falsy values: false, 0, '', null, undefined, NaN
+     *
+     * @param condition - The condition to assert (uses JavaScript truthiness)
+     * @param message - Error message to log if assertion fails
+     * @param args - Additional arguments to log
+     * @returns this for chaining
+     *
+     * @example
+     * logger.assert(user !== null, 'User should not be null', user);
+     * logger.assert(count > 0, 'Count must be positive', { count });
+     * logger.assert(data, 'Data is required'); // Checks if data is truthy
+     */
+    assert(condition: unknown, message: string, ...args: unknown[]): this;
     setLevel(level: LogLevel): void;
+    /**
+     * Set the namespace for this logger instance
+     * Returns this for method chaining
+     *
+     * @param namespace - The namespace string (e.g., 'service:api', 'component')
+     * @returns this for chaining
+     *
+     * @example
+     * const log = logger().namespace('service:api');
+     * log.debug('Message'); // Logs with namespace 'service:api'
+     *
+     * // Can also be called after instantiation
+     * const log2 = logger();
+     * log2.namespace('component').debug('Message');
+     */
+    namespace(namespace: string): this;
     maxDepth(maxDepth: number): this;
+    /**
+     * Pick only specific fields to log (whitelist approach)
+     * Supports dot notation for nested fields: 'user.name', 'user.email'
+     * Supports wildcards: 'user.*' matches all fields under user
+     */
+    pick(fields: string[]): this;
+    /**
+     * Omit specific fields from logging (blacklist approach)
+     * Supports strings, regex patterns, and predicate functions
+     */
+    omit(fields: FilterFieldConfig[]): this;
+    /**
+     * Set filter mode for per-log filtering
+     * - 'redact': Replace with custom string (default: '***REDACTED***')
+     * - 'hide': Remove field completely
+     * - 'type': Show type info like '[string]', '[Array(3)]'
+     * - 'length': Show length info like '[8 chars]', '[3 items]'
+     */
+    filterMode(mode: FilterMode, replacement?: string): this;
+    once(enabled?: boolean): this;
+    flushDedup(): this;
+    /**
+     * Execute log only if condition is true
+     * Supports boolean values or predicate functions
+     * Multiple when() calls are AND-ed together
+     *
+     * @example
+     * // Boolean condition
+     * logger.when(isDev).debug('Dev only');
+     *
+     * // Predicate with context
+     * logger.when(ctx => ctx.namespace === 'auth').debug('Auth log');
+     *
+     * // Chaining (both must be true)
+     * logger
+     *   .when(ctx => ctx.level === 'debug')
+     *   .when(isDevMode)
+     *   .debug('Conditional');
+     */
+    when(condition: Condition): this;
+    /**
+     * Execute log only if condition is false (inverse of when)
+     * Supports boolean values or predicate functions
+     *
+     * @example
+     * // Boolean condition
+     * logger.unless(isProd).debug('Not in production');
+     *
+     * // Predicate with context
+     * logger.unless(ctx => ctx.level === 'error').info('Non-error log');
+     */
+    unless(condition: Condition): this;
     private getLevelPriority;
     private log;
+    private logWithDedup;
+    private flushDedupEntry;
+    private formatTimestamp;
+    private logImmediate;
 }
 type Plslog = {
-    (options?: LoggerOptions): Logger;
+    (options?: LoggerOptions | string): Logger;
     configure(options: GlobalConfig): void;
 };
 declare const plslog: Plslog;
 
-export { type GlobalConfig, type LogLevel, type LoggerOptions, plslog as default };
+export { type Condition, type ConditionContext, type DedupConfig, type DedupEntry, type ErrorSerializationConfig, type FilterFieldConfig, type FilterFieldPredicate, type FilterMode, type FormatterOptions, type GlobalConfig, type LogFilterOptions, type LogLevel, type LoggerOptions, plslog as default };