CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-builder-util

Various utilities for electron-builder ecosystem including process execution, file operations, architecture handling, and cross-platform building support.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Builder Util

Builder Util provides essential utilities for the electron-builder ecosystem, offering comprehensive helper functions and abstractions for cross-platform desktop application building. It includes utilities for process execution, file system operations, architecture handling, logging, async task management, and various string and object manipulation functions.

Package Information

  • Package Name: builder-util
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install builder-util

Core Imports

import { 
  exec, spawn, doSpawn, spawnAndWrite, executeAppBuilder,
  copyFile, copyDir, exists, walk,
  Arch, archFromString, getArchSuffix,
  log, debug, DebugLogger,
  AsyncTaskManager,
  deepAssign, serializeToYaml,
  isEmptyOrSpaces, isPullRequest, isEnvTrue,
  use, isTokenCharValid, addValue, replaceDefault,
  getPlatformIconFileName, removePassword
} from "builder-util";

For CommonJS:

const { 
  exec, spawn, doSpawn, spawnAndWrite, executeAppBuilder,
  copyFile, copyDir, exists, walk,
  Arch, archFromString, getArchSuffix,
  log, debug, DebugLogger,
  AsyncTaskManager, deepAssign, serializeToYaml,
  isEmptyOrSpaces, isPullRequest, isEnvTrue
} = require("builder-util");

Basic Usage

import { exec, copyDir, log, Arch, archFromString } from "builder-util";

// Execute commands with enhanced logging
const result = await exec("ls", ["-la"], { cwd: "/tmp" });
console.log(result);

// Copy directories with advanced options
await copyDir("/source/path", "/dest/path", {
  filter: (file, stat) => !file.includes("node_modules"),
  isUseHardLink: () => true
});

// Architecture handling
const arch = archFromString("x64");
const suffix = getArchSuffix(arch);

// Structured logging
log.info({ operation: "build" }, "Starting build process");

Architecture

Builder Util is organized around several key functional areas:

  • Process Management: Cross-platform process execution and spawning with comprehensive logging
  • File Operations: Advanced file system operations with hard link support, filtering, and transformations
  • Architecture Support: Cross-platform architecture detection, conversion, and naming utilities
  • Logging System: Structured logging with debug capabilities and message transformation
  • Async Operations: Task management, promise utilities, and concurrent execution support
  • Data Processing: YAML serialization, deep object merging, filename sanitization
  • Security: Password removal from command strings with hashing
  • 7-Zip Integration: Archive operation utilities with executable path management

Capabilities

Process Execution

Core process execution and spawning functionality for running external commands with enhanced logging, error handling, and cross-platform support.

function exec(
  file: string, 
  args?: Array<string> | null, 
  options?: ExecFileOptions, 
  isLogOutIfDebug?: boolean
): Promise<string>;

function spawn(
  command: string, 
  args?: Array<string> | null, 
  options?: SpawnOptions, 
  extraOptions?: ExtraSpawnOptions
): Promise<any>;

function executeAppBuilder(
  args: Array<string>,
  childProcessConsumer?: (childProcess: ChildProcess) => void,
  extraOptions?: SpawnOptions,
  maxRetries?: number
): Promise<string>;

function doSpawn(
  command: string, 
  args: Array<string>, 
  options?: SpawnOptions, 
  extraOptions?: ExtraSpawnOptions
): ChildProcess;

function spawnAndWrite(
  command: string, 
  args: Array<string>, 
  data: string, 
  options?: SpawnOptions
): Promise<any>;

interface ExtraSpawnOptions {
  isPipeInput?: boolean;
}

Process Execution

File System Operations

Advanced file system utilities with hard link support, filtering, transformation capabilities, and cross-platform file operations.

const MAX_FILE_REQUESTS = 8;
const DO_NOT_USE_HARD_LINKS: (file: string) => boolean;
const USE_HARD_LINKS: (file: string) => boolean;

function copyFile(src: string, dest: string, isEnsureDir?: boolean): Promise<any>;

function copyDir(
  src: string, 
  destination: string, 
  options?: CopyDirOptions
): Promise<any>;

function copyOrLinkFile(
  src: string, 
  dest: string, 
  stats?: Stats | null, 
  isUseHardLink?: boolean, 
  exDevErrorHandler?: (() => boolean) | null
): Promise<any>;

function exists(file: string): Promise<boolean>;

function statOrNull(file: string): Promise<Stats | null>;

function unlinkIfExists(file: string): Promise<void>;

function walk(
  initialDirPath: string, 
  filter?: Filter | null, 
  consumer?: FileConsumer
): Promise<Array<string>>;

function dirSize(dirPath: string): Promise<number>;

type AfterCopyFileTransformer = (file: string) => Promise<boolean>;
type FileTransformer = (file: string) => Promise<null | string | Buffer | CopyFileTransformer> | null | string | Buffer | CopyFileTransformer;

class CopyFileTransformer {
  constructor(afterCopyTransformer: AfterCopyFileTransformer);
}

class FileCopier {
  isUseHardLink: boolean;
  constructor(isUseHardLinkFunction?: ((file: string) => boolean) | null, transformer?: FileTransformer | null);
  copy(src: string, dest: string, stat: Stats | undefined): Promise<void>;
}

interface CopyDirOptions {
  filter?: Filter | null;
  transformer?: FileTransformer | null;
  isUseHardLink?: ((file: string) => boolean) | null;
}

interface Link {
  readonly link: string;
  readonly file: string;
}

File System Operations

Architecture Handling

Cross-platform architecture detection, conversion, and naming utilities for handling different CPU architectures and platform-specific requirements.

enum Arch {
  ia32,
  x64,
  armv7l,
  arm64,
  universal
}

type ArchType = "x64" | "ia32" | "armv7l" | "arm64" | "universal";

function archFromString(name: string): Arch;
function defaultArchFromString(name?: string): Arch;
function getArchSuffix(arch: Arch, defaultArch?: string): string;
function toLinuxArchString(arch: Arch, targetName: string): string;
function getArchCliNames(): Array<string>;
function getArtifactArchName(arch: Arch, ext: string): string;

Architecture Handling

Logging and Debugging

Structured logging system with debug capabilities, message transformation, and key-value data collection for comprehensive application monitoring.

class Logger {
  readonly isDebugEnabled: boolean;
  messageTransformer: (message: string, level: LogLevel) => string;
  
  constructor(stream: WritableStream);
  filePath(file: string): string;
  info(messageOrFields: Fields | null | string, message?: string): void;
  error(messageOrFields: Fields | null | string, message?: string): void;
  warn(messageOrFields: Fields | null | string, message?: string): void;
  debug(fields: Fields | null, message: string): void;
  log(message: string): void;
  
  static createMessage(
    message: string, 
    fields: Fields | null, 
    level: LogLevel, 
    color: (it: string) => string, 
    messagePadding?: number
  ): string;
}

class DebugLogger {
  readonly data: Map<string, any>;
  
  constructor(isEnabled?: boolean);
  add(key: string, value: any): void;
  save(file: string): Promise<void>;
}

const debug: Debugger;
const log: Logger;
const PADDING = 2;

function setPrinter(value: ((message: string) => void) | null): void;

type LogLevel = "info" | "warn" | "debug" | "notice" | "error";

Logging and Debugging

Async Task Management

Concurrent task execution with cancellation support, promise utilities, and error aggregation for managing complex asynchronous workflows.

class AsyncTaskManager {
  readonly tasks: Array<Promise<any>>;
  
  constructor(cancellationToken: CancellationToken);
  add(task: () => Promise<any>): void;
  addTask(promise: Promise<any>): void;
  cancelTasks(): void;
  awaitTasks(): Promise<Array<any>>;
}

function executeFinally<T>(
  promise: Promise<T>, 
  task: (isErrorOccurred: boolean) => Promise<any>
): Promise<T>;

function printErrorAndExit(error: Error): void;

function orNullIfFileNotExist<T>(promise: Promise<T>): Promise<T | null>;

function orIfFileNotExist<T>(promise: Promise<T>, fallbackValue: T): Promise<T>;

Async Task Management

Data Processing Utilities

Data transformation, serialization, and manipulation utilities including YAML processing, deep object merging, and filename sanitization.

function serializeToYaml(
  object: any, 
  skipInvalid?: boolean, 
  noRefs?: boolean
): string;

function deepAssign<T>(target: T, ...objects: any[]): T;

function sanitizeFileName(s: string, normalizeNfd?: boolean): string;

function getCompleteExtname(filename: string): string;

Data Processing

Utility Functions

General-purpose utility functions for string validation, environment detection, and data manipulation.

function use<T, R>(value: T | Nullish, task: (value: T) => R): R | null;

function isEmptyOrSpaces(s: string | Nullish): s is "" | Nullish;

function isTokenCharValid(token: string): boolean;

function isEnvTrue(value: string | Nullish): boolean;

function isPullRequest(): boolean;

function addValue<K, T>(map: Map<K, Array<T>>, key: K, value: T): void;

function replaceDefault(
  inList: Array<string> | Nullish, 
  defaultList: Array<string>
): Array<string>;

function getPlatformIconFileName(
  value: string | Nullish, 
  isMac: boolean
): string | null | undefined;

function removePassword(input: string): string;

function getPath7za(): Promise<string>;

function getPath7x(): Promise<string>;

const debug7z: Debugger;

Re-exported APIs

Builder Util re-exports useful functions from related packages for convenience.

// From builder-util-runtime
function safeStringifyJson(value: any): string;
function retry<T>(task: () => Promise<T>, options?: RetryOptions): Promise<T>;
function asArray<T>(value: T | Array<T>): Array<T>;

// From temp-file  
class TmpDir {
  constructor(name: string);
  getTempFile(suffix: string): Promise<string>;
  cleanup(): Promise<void>;
}

HTTP Execution

HTTP client functionality with proxy support for secure network operations in electron-builder processes.

class NodeHttpExecutor extends HttpExecutor<ClientRequest> {
  createRequest(options: any, callback: (response: any) => void): ClientRequest;
}

const httpExecutor = NodeHttpExecutor;

Filename Utilities

Filename sanitization and extension utilities for cross-platform file operations.

function sanitizeFileName(s: string, normalizeNfd?: boolean): string;
function getCompleteExtname(filename: string): string;

Error Handling

Builder Util provides specialized error classes for different failure scenarios:

class ExecError extends Error {
  readonly exitCode: number;
  alreadyLogged: boolean;
  static readonly code = "ERR_ELECTRON_BUILDER_CANNOT_EXECUTE";
  
  constructor(command: string, exitCode: number, out: string, errorOut: string, code?: string);
}

class InvalidConfigurationError extends Error {
  constructor(message: string, code?: string);
}

class NestedError extends Error {
  constructor(errors: Error[], message?: string);
}

Common Types

type Nullish = null | undefined;

interface Fields {
  [index: string]: any;
}

interface ExtraSpawnOptions {
  isPipeInput?: boolean;
}

type Filter = (file: string, stat: FilterStats) => boolean;

interface FilterStats extends Stats {
  moduleName?: string;
  moduleRootPath?: string;
  moduleFullFilePath?: string;
  relativeLink?: string;
  linkRelativeToFile?: string;
}

interface FileConsumer {
  consume(file: string, fileStat: Stats, parent: string, siblingNames: Array<string>): any;
  isIncludeDir?: boolean;
}

// Note: CancellationToken is from builder-util-runtime dependency
interface CancellationToken {
  readonly cancelled: boolean;
  onCancel(callback: () => void): void;
}

docs

architecture.md

async-tasks.md

data-processing.md

file-system.md

index.md

logging.md

process-execution.md

tile.json