@rzl-zone/build-tools 0.0.11 → 0.0.12

package/dist/utils/server.d.ts

@@ -2,13 +2,14 @@
 * ========================================================================
 *  @rzl-zone/build-tools
 * ------------------------------------------------------------------------
-*  Version: `0.0.11`
+*  Version: `0.0.12`
 *  Author: `Rizalvin Dwiky <rizalvindwiky1998@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/build-tools`
 * ========================================================================
 */
 
-import { n as PatternOptions, r as defaultPatternOptions, t as PatternConfig } from "../fast-globe-options-DnV58KJc.js";
+import { t as AnyString } from "../extra-CNDyFVA8.js";
+import { n as PatternOptions, r as defaultPatternOptions, t as PatternConfig } from "../fast-globe-options-Dj630IVV.js";
 import _fastGlob from "fast-glob";
 import _fsExtra from "fs-extra";
 type Icons = { readonly [K in keyof typeof emojiIcons]: string };
@@ -81,6 +82,435 @@ declare const emojiIcons: {
 *
 */
 declare const ICONS: Readonly<Icons>;
+/** -------------------------------------------------------------------
+* * ***Determines whether an option value comes from the default configuration
+* or has been explicitly overridden by the user.***
+* -------------------------------------------------------------------
+*
+* This utility is primarily intended for logging and debugging purposes,
+* especially in CLI tools or build pipelines where distinguishing between
+* default and user-provided values is important.
+*
+* The comparison is performed using `Object.is` to ensure accurate detection,
+* including edge cases such as:
+* - `NaN` vs `NaN`.
+* - `-0` vs `+0`.
+*
+* @template T - The type of the option value being compared.
+*
+* @param {unknown} value - The actual value used at runtime.
+* @param {unknown} defaultValue - The default value defined by the tool.
+*
+* @returns
+* A string indicating the source of the value:
+*
+* - `"default"` when `value` is strictly equal to `defaultValue`.
+* - `"overridden"` when the value differs from the default.
+*
+* @example
+* ```ts
+* sourceOf("dist", "dist"); // ➔ "default"
+* sourceOf("dist/types", "dist"); // ➔ "overridden"
+* ```
+*
+* @example
+* ***CLI-style option logging:***
+* ```ts
+* BUILD_LOGGER.OPTIONS(
+*   "outDir",
+*   outDir,
+*   sourceOf(outDir, DEFAULTS.outDir)
+* );
+* ```
+*/
+declare const sourceOf: <T>(value: T, defaultValue: T) => "default" | "overridden";
+/** ----------------------------------------------------------------
+* * ***Deep default source detector.***
+* ----------------------------------------------------------------
+*
+* Determines whether a given value is structurally identical
+* to its default value using deep comparison.
+*
+* Unlike `Object.is`, this utility compares object contents
+* recursively rather than checking reference identity.
+*
+* Intended for configuration systems where option objects
+* may be cloned or reconstructed but still represent the
+* default state.
+*
+* @template T - Value type being compared.
+*
+* @param value - Current runtime value.
+* @param defaultValue - Default reference value.
+*
+* @returns
+* - `"default"` ➔ If values are deeply equal.
+* - `"overridden"` ➔ If values differ.
+*
+* @example
+* ```ts
+* sourceOfIsDeepStrictEqual(
+*   { onlyFiles: true },
+*   { onlyFiles: true }
+* );
+* // "default"
+* ```
+*/
+declare const sourceOfIsDeepStrictEqual: <T>(value: T, defaultValue: T) => "default" | "overridden";
+/** -------------------------------------------------------------------
+* * ***Structured build-time console logger with consistent formatting,
+* icons, and colorized output.***
+* --------------------------------------------------------------------
+*
+* `BUILD_LOGGER` provides a collection of standardized logging helpers
+* intended for **CLI tools, build scripts, and Node.js-based workflows**.
+*
+* - **It ensures:**
+*      - Consistent log structure across different build phases.
+*      - Clear visual distinction between states (start, success, skip, error).
+*      - Emoji or ASCII icon support depending on environment configuration.
+*      - Readable, colorized output via `picocolors`.
+*
+* Emoji usage is controlled via the environment variable:
+*
+* ```
+* FORCE_EMOJI=1
+* ```
+*
+* When disabled, all icons gracefully fall back to ASCII-safe symbols.
+*
+* ---
+*
+* - **Behavior:**
+*      - Uses emoji icons when `FORCE_EMOJI === "1"`.
+*      - Falls back to ASCII symbols otherwise.
+*      - Applies consistent spacing, bulleting, and indentation.
+*      - Formats messages using `picocolors` for visibility.
+*      - Safely extracts error messages from unknown error values.
+*
+* ---
+*
+* - **Available log actions:**
+*      - `SOURCE_OF`:
+*         - See {@link sourceOf | **`sourceOf`**} helpers.
+*
+*      - `OPTIONS({ label, value, source, isRequired })`:
+*         - Logs the options argument function using
+*        {@link sourceOf | **`sourceOf`**} helper.
+*
+*      - `NEW_LINE()`:
+*         - *Inserts an empty line in the console output.*
+*
+*      - `ON_STARTING({ actionName })`:
+*         - *Logs the start of a build or processing action.*
+*
+*      - `ON_FINISH({ actionName, count })`:
+*         - *Logs successful completion with item count.*
+*
+*      - `ON_SKIPPING({ actionName, reasonEndText })`:
+*         - *Logs skipped actions with human-readable reasons.*
+*
+*      - `ON_ERROR({ actionName, error })`:
+*         - *Logs formatted error output with extracted message.*
+*
+*      - `ON_PROCESS_COPY({ actionName, copyFrom, copyTo })`:
+*         - *Logs file copy operations.*
+*
+*      - `ON_PROCESS({ actionName, nameDirect })`:
+*         - *Logs generic processing steps.*
+*
+*      - `ON_PROCESS_REFERENCING({ actionName, referenceFrom, referenceTo })`:
+*         - *Logs reference or linking operations.*
+*
+* ---
+*
+* This logger is intentionally **side-effectful** and writes directly
+* to `console.log` / `console.error`.
+*
+* It is designed for **human-readable output**, not structured logging
+* or machine parsing.
+*/
+declare const BUILD_LOGGER: LoggerBuilder;
+type LoggerBuilder = {
+  SOURCE_OF: typeof sourceOf;
+  OPTIONS(label: string, value: unknown, source: ReturnType<typeof sourceOf> | AnyString, isRequired?: boolean): void;
+  SECTION(title: string, options?: LoggerBuilderSection): void;
+  NEW_LINE(value?: string): void;
+  ON_STARTING: (options: LoggerBuilderOnStarting) => void;
+  ON_FINISH: (options: LoggerBuilderOnFinish) => void;
+  ON_SKIPPING: (options: LoggerBuilderOnSkipping) => void;
+  ON_ERROR: (options: LoggerBuilderOnError) => void;
+  ON_PROCESS: (options: LoggerBuilderOnProcess) => void;
+  ON_PROCESS_COPY: (options: LoggerBuilderOnProcessCopy) => void;
+  ON_PROCESS_COPY_ERROR: (options: LoggerBuilderOnProcessCopyError) => void;
+  ON_PROCESS_REFERENCING: (options: LoggerBuilderOnProcessReferencing) => void;
+};
+type LoggerBuilderSection = {
+  /**
+  * @default ICON.config
+  */
+  icon?: string;
+  /**
+  * @default ""
+  */
+  indent?: string;
+};
+type LoggerBuilderOnStarting = {
+  /** The name of the action being started.
+  *
+  * @default
+  * undefined
+  */
+  actionName: string;
+  /** Connector word used before the action name.
+  *
+  * @default
+  * "to"
+  */
+  textDirectAction?: string;
+};
+type LoggerBuilderOnFinish = {
+  /** The name of the completed action.
+  *
+  * @default
+  * undefined
+  */
+  actionName: string;
+  /** The success text.
+  *
+  * @default
+  * @default "Success"
+  */
+  textSuccess?: string;
+  /** Label for the count unit.
+  *
+  * @default
+  * "file"
+  */
+  typeCount?: string;
+  /** Number of processed items.
+  *
+  * @default
+  * undefined
+  */
+  count: number;
+  /** Progress of processed items (e.g. `2/7`).
+  *
+  * Represents how many items have been processed relative to the total.
+  *
+  * @example
+  * "2/7"
+  */
+  progress?: string;
+};
+type LoggerBuilderOnSkipping = {
+  /** The name of the skipped action.
+  *
+  * @default
+  * undefined
+  */
+  actionName: string;
+  /** Connector word explaining the reason.
+  *
+  * @default
+  * "because"
+  */
+  reasonTitle?: string;
+  /** Short reason phrase.
+  *
+  * @default
+  * "nothing left"
+  */
+  reasonSkipAction?: string;
+  /** Contextual explanation for the skip.
+  *
+  * @default
+  * undefined
+  */
+  reasonEndText: string;
+  /** Type of resource involved.
+  *
+  * @default
+  * "files"
+  */
+  reasonType?: string;
+  /** Connector word before the target.
+  *
+  * @default
+  * "to"
+  */
+  textDirectAction?: string;
+};
+type LoggerBuilderOnError = {
+  /** The name of the action that failed.
+  *
+  * @default
+  * undefined
+  */
+  actionName: string;
+  /** Connector word before the action name.
+  *
+  * @default
+  * "to"
+  */
+  textDirectAction?: string;
+  /** Unknown error object or `Error` instance.
+  *
+  */
+  error: unknown;
+};
+type LoggerBuilderOnProcess = {
+  /** Description of the process.
+  *
+  * @default
+  * undefined
+  */
+  actionName: string;
+  /** Sequence number.
+  *
+  * @default
+  * undefined
+  */
+  count: number;
+  /** Connector word before the target.
+  *
+  * @default
+  * "in"
+  */
+  textDirectFolder?: string;
+  /** Target name or location.
+  *
+  * @default
+  * undefined
+  */
+  nameDirect: string;
+};
+type LoggerBuilderOnProcessCopy = {
+  /** The name of the action being the copy action.
+  *
+  * @default
+  * undefined
+  */
+  actionName: string;
+  /** Sequence number of the process.
+  *
+  * @default
+  * undefined
+  */
+  count: number;
+  /** Connector text before source path.
+  *
+  * @default
+  * "from"
+  */
+  textFrom?: string;
+  /** Source path.
+  *
+  * @default
+  * undefined
+  */
+  copyFrom: string;
+  /** Destination path.
+  *
+  * @default
+  * undefined
+  */
+  copyTo: string;
+  /** Arrow symbol between paths.
+  *
+  * @default
+  * "➔"
+  */
+  textArrow?: string;
+};
+type LoggerBuilderOnProcessCopyError = {
+  /** The name of the action being the error copy action.
+  *
+  * @default
+  * undefined
+  */
+  actionName: string;
+  /** Sequence number of the process.
+  *
+  * @default
+  * undefined
+  */
+  count: number;
+  /** Index number parameter.
+  *
+  * @default
+  * undefined
+  */
+  index?: number;
+  /** Index key name for parameter.
+  *
+  * @default
+  * undefined
+  */
+  indexKey?: string;
+  /** Connector text before source path.
+  *
+  * @default
+  * "from"
+  */
+  textFrom?: string;
+  /** Source path.
+  *
+  * @default
+  * undefined
+  */
+  copyFrom: string;
+  /** The reason error on copying.
+  *
+  * @default
+  * undefined
+  */
+  errorReason: string | Error;
+  /** Connector word explaining the reason.
+  *
+  * @default
+  * "because"
+  */
+  textReason?: string;
+};
+type LoggerBuilderOnProcessReferencing = {
+  /** The name of the action being the referencing action.
+  *
+  * @default
+  * undefined
+  */
+  actionName: string;
+  /** Sequence number.
+  *
+  * @default
+  * undefined
+  */
+  count: number;
+  /** Connector text before source.
+  *
+  * @default
+  * "from"
+  */
+  textFrom?: string;
+  /** Source reference path.
+  *
+  * @default
+  * undefined
+  */
+  referenceFrom: string;
+  /** Target reference path.
+  *
+  * @default
+  * undefined
+  */
+  referenceTo: string;
+  /** Arrow symbol between references.
+  *
+  * @default
+  * "➔"
+  */
+  textArrow?: string;
+};
 /** ----------------------------------------------------------------
 * * ***Node.js–only filesystem utilities (fs-extra).***
 * ----------------------------------------------------------------
@@ -120,5 +550,5 @@ declare const fsExtra: typeof _fsExtra;
 * @environment node
 */
 declare const fastGlob: typeof _fastGlob;
-export { ICONS, type PatternConfig, type PatternOptions, defaultPatternOptions, fastGlob, fsExtra };
+export { BUILD_LOGGER, ICONS, type PatternConfig, type PatternOptions, defaultPatternOptions, fastGlob, fsExtra, sourceOf, sourceOfIsDeepStrictEqual };
 //# sourceMappingURL=server.d.ts.map

package/dist/utils/server.js

@@ -2,11 +2,11 @@
 * ========================================================================
 *  @rzl-zone/build-tools
 * ------------------------------------------------------------------------
-*  Version: `0.0.11`
+*  Version: `0.0.12`
 *  Author: `Rizalvin Dwiky <rizalvindwiky1998@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/build-tools`
 * ========================================================================
 */
 
-import { i as defaultPatternOptions, n as fsExtra, r as ICONS, t as fastGlob } from "../server-Dc93jndm.js";
-export { ICONS, defaultPatternOptions, fastGlob, fsExtra };
+import { a as sourceOfIsDeepStrictEqual, i as sourceOf, n as fsExtra, o as ICONS, r as BUILD_LOGGER, s as defaultPatternOptions, t as fastGlob } from "../server-BsqxhpCl.js";
+export { BUILD_LOGGER, ICONS, defaultPatternOptions, fastGlob, fsExtra, sourceOf, sourceOfIsDeepStrictEqual };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rzl-zone/build-tools",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Toolkit to standardize and improve TypeScript and JavaScript build outputs.",
   "license": "MIT",
   "author": "Rizalvin Dwiky <rizalvindwiky1998@gmail.com>",
@@ -44,6 +44,7 @@
     "dist",
     "README.md",
     "LICENSE.md",
+    "LICENSE",
     "!**/*.test.*"
   ],
   "exports": {
@@ -118,7 +119,7 @@
     "picocolors": "^1.1.1",
     "semver": "^7.7.4",
     "shell-quote": "^1.8.3",
-    "@rzl-zone/node-only": "0.0.9"
+    "@rzl-zone/node-only": "0.0.10"
   },
   "devDependencies": {
     "@types/babel__traverse": "^7.28.0",
@@ -127,9 +128,10 @@
     "eslint": "^9.39.2",
     "rolldown": "^1.0.0-rc.15",
     "terser": "^5.46.1",
-    "tsdown": "0.21.8",
+    "tsdown": "0.22.0",
     "type-fest": "5.5.0",
-    "typescript": "^6.0.2",
+    "typescript": "6.0.3",
+    "unrun": "^0.3.0",
     "@workspace/eslint-config": "0.0.0",
     "@workspace/typescript-config": "0.0.0"
   },