stain 1.0.0 → 1.3.0

package/dist/types.d.cts

@@ -0,0 +1,116 @@
+/**                                                                       @about
+@file: types.ts
+
+import type {
+  EmptyObject,
+  StrNum,
+  TupleN,
+  ColorSpace,
+  StyleKeys,
+  XtermKeysFactory,
+  AnsiCodeTuple,
+  StyleState,
+  StainBase,
+  StainAnsi,
+  StainXterm,
+} from './types.ts'
+
+***                                                                           */
+/**
+ * empty object utility type for representing no keys
+ */
+export type EmptyObject = Record<never, never>;
+/**
+ * string or number shorthand
+ */
+export type StrNum = string | number;
+/**
+ * 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]>;
+/**
+ * color support level
+ * @default 2
+ * @see {@link https://nodejs.org/api/cli.html#force_color1-2-3|Node.js FORCE_COLOR docs}
+ */
+export type ColorSpace = 0 | 1 | 2;
+/**
+ * Style state keys
+ *   fg=foreground; bg=background;
+ *   ft=font; ue=underline; ie=inverse; re=reset;
+ *   pr=previous (internal state)
+ */
+export type StyleKeys = 'fg' | 'bg' | 'ft' | 'ue' | 'ie' | 're' | 'pr';
+/**
+ * Generate xterms: x0 to x255
+ */
+export type XtermKeysFactory<N extends number, Acc extends string[] = []> = Acc['length'] extends N ? Acc[number] : XtermKeysFactory<N, [...Acc, `x${Acc['length']}`]>;
+/**
+ * tuple describing ansi on and off codes with optional flag for custom or xterm usage
+ * @typedef {readonly [number, number, number?]} AnsiCodeTuple
+ * on index 0 is the open code
+ * off index 1 is the close code
+ * isCustom index 2 indicates xterm or custom when truthy
+ */
+export type AnsiCodeTuple = [on: number, off: number, isCustom?: number];
+/**
+ * partial style state map for assembling ansi sequences
+ * keys may include fg bg ft ue ie re pr
+ */
+export type StyleState = Partial<Record<StyleKeys, AnsiCodeTuple>>;
+/**
+ * base named colors supported by ansi
+ */
+export type StainBase = 'black' | 'blue' | 'cyan' | 'green' | 'purple' | 'red' | 'white' | 'yellow';
+/**
+ * named ansi colors including intense variants prefixed with i (ired for bright red)
+ */
+export type StainAnsi = StainBase | `i${StainBase}`;
+/**
+ * xterm color keys generated as x0..x255
+ */
+export type StainXterm = XtermKeysFactory<256>;
+/**
+ * chainable stain api type
+ * callable to format input into a string and exposes chainable style and color properties
+ * includes bg bold dim normal reset underline inverse and color names
+ * includes xterm colors when enabled and custom colors from options
+ * @template C extends Record<string, number> custom color map type
+ * @template X extends boolean whether xterm is enabled
+ */
+export type Stain<C extends Record<string, number> = EmptyObject, X extends boolean = false> = ((...args: any[]) => string) & {
+    bg: Stain<C, X>;
+    bold: Stain<C, X>;
+    dim: Stain<C, X>;
+    normal: Stain<C, X>;
+    reset: Stain<C, X>;
+    underline: Stain<C, X>;
+    inverse: Stain<C, X>;
+} & {
+    [K in StainAnsi]: Stain<C, X>;
+} & (X extends true ? {
+    [K in StainXterm]: Stain<C, X>;
+} : EmptyObject) & (keyof C extends never ? EmptyObject : {
+    [K in keyof C]: Stain<C, X>;
+});
+/**
+ * options for creating a stain instance
+ * @template C extends Record<string, number> custom color map type
+ * @property {(...args: any[]) => string} [format] custom formatter for args to string
+ * @property {boolean} [noColor] disable color output
+ * @property {boolean} [xterm] enable xterm 256 color support
+ * @property {C} [colors] custom color name to code map
+ * @property {boolean} [simpleEscape] use faster simpler escape without nested handling
+ * @property {ColorSpace} [colorSpace] force color space, used primarly for testing
+ */
+export type StainOpts<C extends Record<string, number> = EmptyObject> = {
+    format?: (...args: any[]) => string;
+    noColor?: boolean;
+    xterm?: boolean;
+    colors?: C;
+    simpleEscape?: boolean;
+    colorSpace?: ColorSpace;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.mts

@@ -0,0 +1,116 @@
+/**                                                                       @about
+@file: types.ts
+
+import type {
+  EmptyObject,
+  StrNum,
+  TupleN,
+  ColorSpace,
+  StyleKeys,
+  XtermKeysFactory,
+  AnsiCodeTuple,
+  StyleState,
+  StainBase,
+  StainAnsi,
+  StainXterm,
+} from './types.ts'
+
+***                                                                           */
+/**
+ * empty object utility type for representing no keys
+ */
+export type EmptyObject = Record<never, never>;
+/**
+ * string or number shorthand
+ */
+export type StrNum = string | number;
+/**
+ * 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]>;
+/**
+ * color support level
+ * @default 2
+ * @see {@link https://nodejs.org/api/cli.html#force_color1-2-3|Node.js FORCE_COLOR docs}
+ */
+export type ColorSpace = 0 | 1 | 2;
+/**
+ * Style state keys
+ *   fg=foreground; bg=background;
+ *   ft=font; ue=underline; ie=inverse; re=reset;
+ *   pr=previous (internal state)
+ */
+export type StyleKeys = 'fg' | 'bg' | 'ft' | 'ue' | 'ie' | 're' | 'pr';
+/**
+ * Generate xterms: x0 to x255
+ */
+export type XtermKeysFactory<N extends number, Acc extends string[] = []> = Acc['length'] extends N ? Acc[number] : XtermKeysFactory<N, [...Acc, `x${Acc['length']}`]>;
+/**
+ * tuple describing ansi on and off codes with optional flag for custom or xterm usage
+ * @typedef {readonly [number, number, number?]} AnsiCodeTuple
+ * on index 0 is the open code
+ * off index 1 is the close code
+ * isCustom index 2 indicates xterm or custom when truthy
+ */
+export type AnsiCodeTuple = [on: number, off: number, isCustom?: number];
+/**
+ * partial style state map for assembling ansi sequences
+ * keys may include fg bg ft ue ie re pr
+ */
+export type StyleState = Partial<Record<StyleKeys, AnsiCodeTuple>>;
+/**
+ * base named colors supported by ansi
+ */
+export type StainBase = 'black' | 'blue' | 'cyan' | 'green' | 'purple' | 'red' | 'white' | 'yellow';
+/**
+ * named ansi colors including intense variants prefixed with i (ired for bright red)
+ */
+export type StainAnsi = StainBase | `i${StainBase}`;
+/**
+ * xterm color keys generated as x0..x255
+ */
+export type StainXterm = XtermKeysFactory<256>;
+/**
+ * chainable stain api type
+ * callable to format input into a string and exposes chainable style and color properties
+ * includes bg bold dim normal reset underline inverse and color names
+ * includes xterm colors when enabled and custom colors from options
+ * @template C extends Record<string, number> custom color map type
+ * @template X extends boolean whether xterm is enabled
+ */
+export type Stain<C extends Record<string, number> = EmptyObject, X extends boolean = false> = ((...args: any[]) => string) & {
+    bg: Stain<C, X>;
+    bold: Stain<C, X>;
+    dim: Stain<C, X>;
+    normal: Stain<C, X>;
+    reset: Stain<C, X>;
+    underline: Stain<C, X>;
+    inverse: Stain<C, X>;
+} & {
+    [K in StainAnsi]: Stain<C, X>;
+} & (X extends true ? {
+    [K in StainXterm]: Stain<C, X>;
+} : EmptyObject) & (keyof C extends never ? EmptyObject : {
+    [K in keyof C]: Stain<C, X>;
+});
+/**
+ * options for creating a stain instance
+ * @template C extends Record<string, number> custom color map type
+ * @property {(...args: any[]) => string} [format] custom formatter for args to string
+ * @property {boolean} [noColor] disable color output
+ * @property {boolean} [xterm] enable xterm 256 color support
+ * @property {C} [colors] custom color name to code map
+ * @property {boolean} [simpleEscape] use faster simpler escape without nested handling
+ * @property {ColorSpace} [colorSpace] force color space, used primarly for testing
+ */
+export type StainOpts<C extends Record<string, number> = EmptyObject> = {
+    format?: (...args: any[]) => string;
+    noColor?: boolean;
+    xterm?: boolean;
+    colors?: C;
+    simpleEscape?: boolean;
+    colorSpace?: ColorSpace;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts

@@ -0,0 +1,116 @@
+/**                                                                       @about
+@file: types.ts
+
+import type {
+  EmptyObject,
+  StrNum,
+  TupleN,
+  ColorSpace,
+  StyleKeys,
+  XtermKeysFactory,
+  AnsiCodeTuple,
+  StyleState,
+  StainBase,
+  StainAnsi,
+  StainXterm,
+} from './types.ts'
+
+***                                                                           */
+/**
+ * empty object utility type for representing no keys
+ */
+export type EmptyObject = Record<never, never>;
+/**
+ * string or number shorthand
+ */
+export type StrNum = string | number;
+/**
+ * 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]>;
+/**
+ * color support level
+ * @default 2
+ * @see {@link https://nodejs.org/api/cli.html#force_color1-2-3|Node.js FORCE_COLOR docs}
+ */
+export type ColorSpace = 0 | 1 | 2;
+/**
+ * Style state keys
+ *   fg=foreground; bg=background;
+ *   ft=font; ue=underline; ie=inverse; re=reset;
+ *   pr=previous (internal state)
+ */
+export type StyleKeys = 'fg' | 'bg' | 'ft' | 'ue' | 'ie' | 're' | 'pr';
+/**
+ * Generate xterms: x0 to x255
+ */
+export type XtermKeysFactory<N extends number, Acc extends string[] = []> = Acc['length'] extends N ? Acc[number] : XtermKeysFactory<N, [...Acc, `x${Acc['length']}`]>;
+/**
+ * tuple describing ansi on and off codes with optional flag for custom or xterm usage
+ * @typedef {readonly [number, number, number?]} AnsiCodeTuple
+ * on index 0 is the open code
+ * off index 1 is the close code
+ * isCustom index 2 indicates xterm or custom when truthy
+ */
+export type AnsiCodeTuple = [on: number, off: number, isCustom?: number];
+/**
+ * partial style state map for assembling ansi sequences
+ * keys may include fg bg ft ue ie re pr
+ */
+export type StyleState = Partial<Record<StyleKeys, AnsiCodeTuple>>;
+/**
+ * base named colors supported by ansi
+ */
+export type StainBase = 'black' | 'blue' | 'cyan' | 'green' | 'purple' | 'red' | 'white' | 'yellow';
+/**
+ * named ansi colors including intense variants prefixed with i (ired for bright red)
+ */
+export type StainAnsi = StainBase | `i${StainBase}`;
+/**
+ * xterm color keys generated as x0..x255
+ */
+export type StainXterm = XtermKeysFactory<256>;
+/**
+ * chainable stain api type
+ * callable to format input into a string and exposes chainable style and color properties
+ * includes bg bold dim normal reset underline inverse and color names
+ * includes xterm colors when enabled and custom colors from options
+ * @template C extends Record<string, number> custom color map type
+ * @template X extends boolean whether xterm is enabled
+ */
+export type Stain<C extends Record<string, number> = EmptyObject, X extends boolean = false> = ((...args: any[]) => string) & {
+    bg: Stain<C, X>;
+    bold: Stain<C, X>;
+    dim: Stain<C, X>;
+    normal: Stain<C, X>;
+    reset: Stain<C, X>;
+    underline: Stain<C, X>;
+    inverse: Stain<C, X>;
+} & {
+    [K in StainAnsi]: Stain<C, X>;
+} & (X extends true ? {
+    [K in StainXterm]: Stain<C, X>;
+} : EmptyObject) & (keyof C extends never ? EmptyObject : {
+    [K in keyof C]: Stain<C, X>;
+});
+/**
+ * options for creating a stain instance
+ * @template C extends Record<string, number> custom color map type
+ * @property {(...args: any[]) => string} [format] custom formatter for args to string
+ * @property {boolean} [noColor] disable color output
+ * @property {boolean} [xterm] enable xterm 256 color support
+ * @property {C} [colors] custom color name to code map
+ * @property {boolean} [simpleEscape] use faster simpler escape without nested handling
+ * @property {ColorSpace} [colorSpace] force color space, used primarly for testing
+ */
+export type StainOpts<C extends Record<string, number> = EmptyObject> = {
+    format?: (...args: any[]) => string;
+    noColor?: boolean;
+    xterm?: boolean;
+    colors?: C;
+    simpleEscape?: boolean;
+    colorSpace?: ColorSpace;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/utils.d.cts

@@ -0,0 +1,19 @@
+import type { ColorSpace } from './types.ts';
+/**
+ * converts an XTerm 8bit (256-color) index to the best 4bit value
+ * @param  {number} n       - xterm index
+ * @param  {0 | 1} [isBg=0] - if bg
+ * @return {number}
+ */
+export declare const xtermTo4Bit: (n: number, isBg?: 0 | 1) => number;
+/**
+ * get basic binary 0 color space
+ * 0=no-color, 1=16, 2=256
+ * @implements nodejs.org/api/cli.html#force_color1-2-3
+ * @param  {string[]} argv           - argv cli/arguments
+ * @param  {NodeJS.ProcessEnv} env   - ENV variables
+ * @param  {typeof globalThis} gthis - globalThis
+ * @return {ColorSpace}
+ */
+export declare const getColorSpace: (argv?: string[], env?: NodeJS.ProcessEnv, gthis?: typeof globalThis) => ColorSpace;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.mts

@@ -0,0 +1,19 @@
+import type { ColorSpace } from './types.ts';
+/**
+ * converts an XTerm 8bit (256-color) index to the best 4bit value
+ * @param  {number} n       - xterm index
+ * @param  {0 | 1} [isBg=0] - if bg
+ * @return {number}
+ */
+export declare const xtermTo4Bit: (n: number, isBg?: 0 | 1) => number;
+/**
+ * get basic binary 0 color space
+ * 0=no-color, 1=16, 2=256
+ * @implements nodejs.org/api/cli.html#force_color1-2-3
+ * @param  {string[]} argv           - argv cli/arguments
+ * @param  {NodeJS.ProcessEnv} env   - ENV variables
+ * @param  {typeof globalThis} gthis - globalThis
+ * @return {ColorSpace}
+ */
+export declare const getColorSpace: (argv?: string[], env?: NodeJS.ProcessEnv, gthis?: typeof globalThis) => ColorSpace;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts

@@ -0,0 +1,19 @@
+import type { ColorSpace } from './types.ts';
+/**
+ * converts an XTerm 8bit (256-color) index to the best 4bit value
+ * @param  {number} n       - xterm index
+ * @param  {0 | 1} [isBg=0] - if bg
+ * @return {number}
+ */
+export declare const xtermTo4Bit: (n: number, isBg?: 0 | 1) => number;
+/**
+ * get basic binary 0 color space
+ * 0=no-color, 1=16, 2=256
+ * @implements nodejs.org/api/cli.html#force_color1-2-3
+ * @param  {string[]} argv           - argv cli/arguments
+ * @param  {NodeJS.ProcessEnv} env   - ENV variables
+ * @param  {typeof globalThis} gthis - globalThis
+ * @return {ColorSpace}
+ */
+export declare const getColorSpace: (argv?: string[], env?: NodeJS.ProcessEnv, gthis?: typeof globalThis) => ColorSpace;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,UAAU,EACX,MAAM,YAAY,CAAC;AA6BpB;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,GAAG,MAAM,EAAE,OAAM,CAAC,GAAG,CAAK,KAAG,MAsBxD,CAAC;AAGF;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,MAAM,EAAE,EACf,MAAM,MAAM,CAAC,UAAU,EACvB,QAAQ,OAAO,UAAU,KACxB,UAiDF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stain",
-  "version": "1.0.0",
+  "version": "1.3.0",
   "description": "Fluent, flexible, and fast ANSI styling that adds color to your terminal",
   "homepage": "https://github.com/fetchTe/stain",
   "license": "MIT",