nsole/dist/types.d.cts

A drop-in isomorphic console.* replacement that's pretty, small, fast, and flexible

/**                                                                       @about
@desc: ptag types/utils

import type {
  ColorSpace,
  ConsoleCanStyleU,
  ConsoleMayStyleU,
  ConsoleNotStyleU,
  ConsoleStyleU,
  DefinitionCSS,
  DefinitionDL,
  DefinitionMethod,
  Definitions,
  DefinitionsD,
  DefinitionsDP,
  DefinitionsP,
  DefinitionStruc,
  EnvKeyValMap,
  GetEnvVal,
  LogFn,
  LogLevel,
  MergePrimary,
  PluginFn,
  PtagHandler,
  PtagInstance,
  PtagInstanceN,
  RgbaTuple,
  TupleN,
  UnionOmit,
} from 'ptag/types';

***                                                                           */
/**
 * transforms object type to union of its function key names
 * @template T - source object type with function properties
 */
type ToFnUnion<T> = {
    [K in keyof T]: K extends string ? T[K] extends (...args: any[]) => any ? K : never : never;
}[keyof T];
/**
 * excludes union members assignable to U (opposite of Extract)
 * @template T - source union type
 * @template U - union type to exclude
 */
export type UnionOmit<T, U> = T extends U ? never : T;
/**
 * helper to make tuple of N elements of type T
 * @template N - tuple length (number literal type)
 * @template T - element type (default: string)
 */
export type TupleN<N extends number, T = string, Acc extends T[] = []> = Acc['length'] extends N ? Acc : TupleN<N, T, [...Acc, T]>;
/**
 * merges Secondary type into Primary with property precedence
 * @template Primary - main type with priority properties
 * @template Secondary - secondary type to merge in
 */
export type MergePrimary<Primary, Secondary> = {
    [K in (keyof Primary) | (keyof Secondary)]: K extends keyof Primary ? Primary[K] : K extends keyof Secondary ? Secondary[K] : never;
};
/**
 * log visibility threshold (-1=bypass, 0-5=verbosity)
 * @ptag param:2
 * @default 5
 */
export type LogLevel = -1 | 0 | 1 | 2 | 3 | 4 | 5;
/**
 * color support level with cache control (negative=disable caching)
 * @NOTE negatives == positive, but a neg disables caching to force a plugin to always re-run
 * @ptag param:5
 * @default 3
 * @see {@link https://nodejs.org/api/cli.html#force_color1-2-3|Node.js FORCE_COLOR docs}
 */
export type ColorSpace = -4 | -3 | -2 | -1 | 0 | 1 | 2 | 3;
/** RGBA color values tuple [red, green, blue, alpha] (0-255) */
export type RgbaTuple = TupleN<4, number>;
/**
 * extended Console interface including a custom 'check' method
 * @see {@link https://console.spec.whatwg.org/#console-namespace}
 * @see {@link https://developer.mozilla.org/docs/Web/API/console}
 */
interface ConsoleX extends Console {
    /** ptag check default; uses console.log {@link https://developer.mozilla.org/docs/Web/API/console/log_static} */
    check(...data: any[]): void;
}
/** style-safe console methods */
export type ConsoleCanStyleU = 'debug' | 'check' | 'error' | 'info' | 'log' | 'warn';
/** style-possible but not recommended console methods */
export type ConsoleMayStyleU = 'group' | 'groupEnd' | 'groupCollapsed' | 'time' | 'timeEnd' | 'timeLog' | 'trace';
/**
 * @type {union} all console methods
 */
type ConsoleKeyUnion = ToFnUnion<ConsoleX>;
/**
 * @type {union} all styleable console methods
 */
export type ConsoleStyleU = ToFnUnion<Pick<ConsoleX, ConsoleCanStyleU> & Pick<ConsoleX, ConsoleMayStyleU>>;
/**
 * @type {union} all non-style-able console methods (due to their nature/implementation)
 */
export type ConsoleNotStyleU = ToFnUnion<Omit<ConsoleX, ConsoleCanStyleU | ConsoleMayStyleU>>;
/**
 * console log function signature
 * @param {...unknown[]} args - arguments passed to the log function
 */
export type LogFn = (...args: unknown[]) => void;
/**
 * log method definition structure
 * @example {myKoolLogMethod: [5, 'TooKool4Skl', '#ff0', '#00f', 'error']}
 */
export type DefinitionMethod = [
    /** 0: minimum log level where this style applies */
    level: number,
    /** 1: TAG/symbol prepended to the log message */
    tag: string,
    /** 2: main/bg color; css ref: ^^^|^ (^=if fg is undefined) */
    bg: string,
    /** 3: explicit/fg color; css ref: ^^|^ (^=if defined) */
    fg?: string,
    /** 4: console method to use; defaults to 'log' if key not in console */
    consoleMethod?: ConsoleKeyUnion
];
/**
 * _dl - delimiter definition structure; {delimiter:1}{TAG}{delimiter:2}{ID}{delimiter:3}
 * @example [':', ':', ':']
 */
export type DefinitionDL = [
    first: string,
    middle: string,
    last: string
];
/**
 * _css - styling definition structure
 */
export type DefinitionCSS = [
    /** 0: all delimiters: first, middle, and last */
    delimAll: string,
    /** 1: tag/symbol */
    tag: string,
    /** 2: (id)entifier text */
    id: string,
    /** 3: last delimiter; standard cascading (trumps delimAll) */
    delimLast: string,
    /** 4: applied to all; standard cascading (lowest priority) */
    all?: string
];
/**
 * core configuration structure
 */
export type DefinitionStruc = {
    /** default foreground color */
    _fg: string;
    /** delimiters definition */
    _dl: DefinitionDL;
    /** css style definition */
    _css: DefinitionCSS;
};
/**
 * default/complete definitions structure
 * @template PtagM - Union of custom method names defined by the user
 */
export type Definitions<PtagM extends string = never> = Partial<MergePrimary<DefinitionStruc, DefinitionsP<PtagM>>>;
/**
 * partial definitions structure to merge with defaults; not ideal but it works
 * @template PtagM - Union of custom method names defined by the user
 */
export type DefinitionsP<PtagM extends string = never> = Partial<MergePrimary<DefinitionStruc, Record<PtagM | ConsoleKeyUnion, undefined | [
    level: number,
    tag: string,
    bg: string,
    fg?: string,
    consoleMethod?: ConsoleKeyUnion
]>>>;
/**
 * default definitions structure
 * @template PtagM - Union of custom method names
 */
export type DefinitionsD<PtagM extends string = never> = Record<PtagM, DefinitionMethod> & DefinitionStruc;
/**
 * partial default definitions structure
 * @template PtagM - Union of custom method names
 */
export type DefinitionsDP<PtagM extends string = never> = Partial<Record<PtagM, DefinitionMethod>>;
/**
 * customization plugin function
 * @ptag param:4
 */
export type PluginFn<PtagM extends string> = (def: [
    /** special override return type */
    logLevelOrOverride: number | string | LogFn,
    tag: string,
    bg: string,
    fg?: string,
    consoleMethod?: ConsoleKeyUnion,
    /** @NOTE: css not included in args - rtn only; get value via target; (makes type workable) */
    css?: DefinitionCSS,
    /** @NOTE: delimiters not included in args - rtn only; get value via target; (makes type workable) */
    delimiters?: DefinitionDL
], 
/** name of method being called (e.g: "debug", "error") */
method: PtagM | ConsoleKeyUnion, 
/** resolved ID; with placeholder "{}" replaced and without delimiters */
id: string, 
/** ptag instance (to access _lvl and _style) */
target: PtagInstanceN<PtagM>) => [
    levelOrOverride: number | string | LogFn,
    tag: string,
    bg: string,
    fg?: string,
    consoleMethod?: ConsoleKeyUnion,
    css?: DefinitionCSS,
    delimiters?: DefinitionDL
];
/**
 * environment configuration mapping
 * @template M - custom method names
 */
export type EnvKeyValMap<M extends string = never> = {
    ID: string;
    FG: string;
    FW: string | number;
    LVL: LogLevel;
    PLG: PluginFn<M> | null | undefined;
    CSS: DefinitionCSS;
    DL: TupleN<3>;
    DEF: DefinitionsDP;
    NO_COLOR: boolean;
};
/**
 * ptag instance factory; combines core properties with console/custom log methods
 * @template PtagM - Union of custom method names
 */
export type PtagInstance<PtagM extends string = never> = {
    /** instance (id)entifier text */
    _id: string | null;
    /** current visibility level */
    _lvl: number;
    /** definitions */
    _def: DefinitionsP<PtagM> | null;
} & ConsoleX & Record<UnionOmit<PtagM, '_dl' | '_css' | '_fg'>, LogFn>;
/**
 * ptag non-null instance factory; combines core properties with console/custom log methods
 * @template PtagM - Union of custom method names
 */
export type PtagInstanceN<PtagM extends string = never> = {
    /** instance (id)entifier text */
    _id: string;
    /** current visibility level */
    _lvl: number;
    /** definitions */
    _def: DefinitionsD<PtagM>;
} & ConsoleX & Record<UnionOmit<PtagM, '_dl' | '_css' | '_fg'>, LogFn>;
/**
 * proxy handler for ptag instance
 * @template PtagM - Union of custom method names
 */
export type PtagHandler<PtagM extends string = never> = {
    /** property access handler */
    get(target: PtagInstance<PtagM>, prop: '_id' | '_lvl' | '_def' | ConsoleKeyUnion | PtagM): LogFn | number;
    /** log level update handler */
    set(target: PtagInstance<PtagM>, prop: '_lvl', value: number): boolean;
    /** identifier update handler */
    set(target: PtagInstance<PtagM>, prop: '_id', value: string): boolean;
    /** definitions update handler */
    set(target: PtagInstance<PtagM>, prop: '_def', value: MergePrimary<DefinitionStruc, Partial<Record<PtagM | ConsoleStyleU, DefinitionMethod>>>): boolean;
};
export {};
//# sourceMappingURL=types.d.ts.map