kaven-utils/src/base/Interfaces.d.ts

Utils for Node.js.

/********************************************************************
 * @author:      Kaven
 * @email:       kaven@wuwenkai.com
 * @website:     http://blog.kaven.xyz
 * @file:        [Kaven-Utils] /src/base/Interfaces.ts
 * @create:      2018-11-06 15:20:27.145
 * @modify:      2026-03-12 14:22:09.452
 * @version:     6.1.3
 * @times:       158
 * @lines:       359
 * @copyright:   Copyright © 2018-2026 Kaven. All Rights Reserved.
 * @description: [description]
 * @license:     [license]
 ********************************************************************/
import { HttpStatusCode, IHostPort, ILoggable, ITimeSpan, LogLevel, TIpAddressType } from "kaven-basic";
import { ExecOptions, SpawnOptionsWithoutStdio } from "node:child_process";
import { RequestOptions } from "node:http";
import { HttpOrHttpsServer } from "./Types.js";
export interface IExternalIpRule {
    url: string;
    type?: TIpAddressType;
    rule?: (data: string) => string;
    regex?: {
        pattern: string;
        flags?: string;
        resultIndex?: number;
    };
}
export interface IDigestAuthenticationResponse {
    username?: string;
    realm?: string;
    nonce?: string;
    uri?: string;
    algorithm?: string;
    response?: string;
    opaque?: string;
    qop?: string;
    nc?: string;
    cnonce?: string;
    [index: string]: string | undefined;
}
export interface IStartServerOptions extends ILoggable {
    beforeListen?: (s: HttpOrHttpsServer) => Promise<void>;
    hostname?: string;
    enableHttps?: boolean;
    sslCertFile?: string;
    sslKeyFile?: string;
    handleSignals?: boolean;
    disposeBeforeShutdown?: () => Promise<void>;
    mode?: string;
}
export interface ICopyEntry {
    src: string | string[];
    dest: string;
    override?: boolean;
}
export interface ICopyConfig {
    entries: ICopyEntry[];
    override?: boolean;
}
export interface IArchiveOptions {
    password?: string;
    notRecurseSubdirectories?: boolean;
    overwriteFile?: boolean;
    /**
     * Sets level of compression. Default: `5`
     */
    compressionLevel?: 0 | 1 | 3 | 5 | 7 | 9;
    /**
     * Specifies the type of archive. It can be: *, #, 7z, xz, split, zip, gzip, bzip2, tar, ....
     */
    archiveType?: string;
}
export interface IArchiveExtractOptions {
    outputDirectory?: string;
    password?: string;
}
export interface IHttpHeader {
    name: string;
    value: string;
}
export interface IHttpAuthorizationInfo {
    authorization?: string;
    method?: string;
    ip?: string;
}
export interface IGeneratedFile {
    Path: string;
    GetContent(force?: boolean): Promise<string>;
    Delete(): Promise<boolean>;
    CopyTo(dest: string): Promise<boolean>;
    MoveTo(dest: string): Promise<boolean>;
}
export interface IGeneratedCertificateFiles {
    CaKey?: IGeneratedFile;
    CaCert?: IGeneratedFile;
    ServerKey?: IGeneratedFile;
    ServerReq?: IGeneratedFile;
    ServerCert?: IGeneratedFile;
    ClientKey?: IGeneratedFile;
    ClientReq?: IGeneratedFile;
    ClientCert?: IGeneratedFile;
    Delete(): Promise<void>;
    Save(file: string): Promise<void>;
}
export interface ICertificateSubject {
    C?: string;
    ST?: string;
    L?: string;
    O?: string;
    OU?: string;
    CN?: string;
}
export interface ICertificate {
    caKey?: string;
    caCert?: string;
    serverKey?: string;
    serverReq?: string;
    serverCert?: string;
    clientKey?: string;
    clientReq?: string;
    clientCert?: string;
}
export interface ICertificateCreationOptions extends ICertificate, ILoggable {
    /**
     * the size of the private key to generate in bits. This must be the last option specified. The default is 2048.
     */
    size?: number;
    days?: number;
    certGenerateDir?: string;
    caSubj?: ICertificateSubject;
    serverSubj?: ICertificateSubject;
    clientSubj?: ICertificateSubject;
    openssl?: string;
}
export interface IStartTlsProxyServerOptions extends ICertificateCreationOptions, IHostPort {
    certJsonFile?: string;
    validClients?: string[];
}
export interface IStartTlsProxyClientOptions {
    cert?: IGeneratedCertificateFiles;
    tlsServer?: IHostPort;
    httpListen?: IHostPort;
    checkCertCn?: boolean;
    validServers?: string[];
}
export interface IFileLoggerOptions {
    Levels?: LogLevel[];
    ResetSizeInBytes?: number;
    ResetInterval?: number | ITimeSpan;
    StripAnsi?: boolean;
}
export interface IHttpServerLoggerOptions {
    dateTime?: boolean;
    useRemoteAddr?: boolean;
}
export interface IProxyConfig {
    SERVER: boolean;
    SERVER_HOST: string;
    SERVER_PORT: number;
    SERVER_CERT_GENERATE_DIR: string;
    SERVER_CERT_JSON_FILE: string;
    SERVER_VALID_CLIENTS: string[];
    CLIENT: boolean;
    CLIENT_CONNECT_HOST: string;
    CLIENT_CONNECT_PORT: number;
    CLIENT_HTTP_HOST: string;
    CLIENT_HTTP_PORT: number;
    CLIENT_CERT_JSON_FILE: string;
    CLIENT_CHECK_CERT_CN: boolean;
    CLIENT_VALID_SERVERS: string[];
}
/**
 * @since 5.0.4
 * @version 2025-10-13
 */
export interface IExecuteSoapActionOptions extends ILoggable {
    url: string;
    serviceType: string;
    /**
     * eg: GetExternalIPAddress
     */
    action: string;
    /**
     * eg: NewExternalIPAddress
     */
    actionResultName?: string;
}
/**
 * @since 5.0.4
 * @version 2025-10-13
 */
export interface IGetExternalIpOptions extends ILoggable {
    rules?: IExternalIpRule[];
    ipv6?: boolean;
    ignoreCache?: boolean;
    ignoreBuiltInRules?: boolean;
}
/**
 * @since 5.2.0
 * @version 2023-12-02
 */
export interface ICommand {
    command: string;
    options?: IExecuteOptions;
}
/**
 * @since 5.0.5
 * @version 2025-10-14
 */
export interface IContinuousIntegrationForDocumentsOptions extends ILoggable {
    sourceDocumentFileOrDirectory: string;
    sourceVersionFile: string;
    targetRootDirectory: string;
    targetDirectoryName: string;
    updateReadmeFile?: boolean;
    readmeFileName?: string;
    readmeFileTableLine?: string;
    gitCommit?: boolean;
    targetRepositoryDirectory?: string;
    variables?: NodeJS.Dict<string>;
    commands?: ICommand[];
}
/**
 * @since 5.0.7
 * @version 2023-11-25
 */
export interface IExecuteOptions extends ILoggable {
    execOptions?: ExecOptions;
    spawn?: boolean;
    spawnArgs?: string[];
    spawnOptions?: SpawnOptionsWithoutStdio;
    /**
     * cp936
     * @see https://www.npmjs.com/package/iconv-lite#supported-encodings
     */
    decoderEncoding?: string;
    autoDetectDecoderEncoding?: boolean;
    console?: boolean;
    stdout?: NodeJS.WritableStream;
    stderr?: NodeJS.WritableStream;
    resolveNonZeroExitCodes?: boolean;
    suppressingInteractiveInput?: boolean;
}
export interface IMinifyFileOptions extends ILoggable {
    src: string | string[];
    deleteSourceMap?: boolean;
    setSourceMappingURL?: boolean;
    deleteTypeScriptDeclarationFile?: boolean;
    includeNodeModules?: boolean;
    terserOptions?: object;
}
export interface IMinifyCssOptions extends ILoggable {
    src: string | string[];
    includeNodeModules?: boolean;
}
export interface ICheckRefererOptions extends ILoggable {
    allowEmpty?: boolean;
    redirectTo?: string;
    status?: HttpStatusCode;
    allowPrivateIP?: boolean;
}
export interface IMongoDBBackupOptions extends ILoggable {
    databaseName?: string;
    host?: string;
    databaseUser?: string;
    databasePassword?: string;
}
export interface IFindAndReplaceInFilesOptions extends ILoggable {
    conditions?: [string, string][];
    newStrMethod?: (str: string) => string;
    extensions?: string[];
}
export interface IDeleteFilesByExtensionOptions extends ILoggable {
    caseSensitive?: boolean;
    ignoreFolderNames?: string[];
}
export interface IDownloadFileOptions extends ILoggable {
    http?: RequestOptions;
}
export interface IFileEnumerateOptions extends ILoggable {
    topDirectoryOnly?: boolean;
    ignoreDirectoryNames?: string[];
}
export interface ICopyFileOptions extends ILoggable {
    overwrite?: boolean;
    throwOnError?: boolean;
}