@nasriya/atomix
Version:
Composable helper functions for building reliable systems
376 lines (375 loc) • 22.9 kB
TypeScript
declare class Atomix {
/**
* Type guard functions for validating and narrowing values at runtime.
* Useful for safely checking primitives, instances, and complex structures.
* @since v1.0.0
*/
readonly valueIs: {
defined(value: unknown): value is NonNullable<unknown>;
instanceOf<T>(value: unknown, constructor: abstract new (...args: any[]) => T): value is T;
instanceOfLoose<T>(value: unknown, constructor: abstract new (...args: any[]) => T): value is T;
readonly number: (value: unknown) => value is number;
readonly negativeNumber: (value: unknown) => boolean;
readonly positiveNumber: (value: unknown) => boolean;
readonly integer: (value: unknown) => boolean;
readonly float: (value: unknown) => boolean;
readonly finite: (value: unknown) => boolean;
readonly NaN: (value: unknown) => value is typeof NaN;
readonly string: (value: unknown) => value is string;
readonly blankString: (value: unknown) => boolean;
readonly emptyString: (value: unknown) => boolean;
readonly notEmptyString: (value: unknown) => boolean;
readonly validString: (value: unknown) => boolean;
readonly alphaString: (value: unknown) => boolean;
readonly alphaNumericString: (value: unknown) => boolean;
readonly uuid: (value: unknown, version?: "v1" | "v4" | "v5") => boolean;
readonly globLike: (pattern: string) => boolean;
readonly object: (value: unknown) => value is object;
readonly freezable: (value: unknown) => value is object;
readonly record: (value: unknown) => value is Record<string, any>;
readonly emptyRecord: (value: unknown) => boolean;
readonly array: (value: unknown) => value is Array<any>;
readonly notEmptyArray: <T extends Array<T>>(value: unknown) => value is import(".").NonEmptyArray<T>;
readonly arrayOf: <T>(itemGuard: (item: unknown) => item is T) => (value: unknown) => value is T[];
readonly arrayOfNumbers: (value: unknown) => value is number[];
readonly arrayOfStrings: (value: unknown) => value is string[];
};
/**
* Utilities for working with core JavaScript data types, organized by type.
* Includes helpers for strings, numbers, arrays, objects, records, and regex.
* @since v1.0.0
*/
readonly dataTypes: Readonly<{
string: {
readonly guard: {
isString(value: unknown): value is string;
isBlank(value: unknown): boolean;
isEmpty(value: unknown): boolean;
isNotEmpty(value: unknown): boolean;
isValidString(value: unknown): boolean;
isAlpha(value: unknown): boolean;
isAlphaNumeric(value: unknown): boolean;
isUUID(value: unknown, version?: "v1" | "v4" | "v5"): boolean;
};
toCamelCase(str: string): string;
toKebabCase(str: string): string;
toSnakeCase(str: string): string;
truncate(str: string, length: number): string;
capitalizeFirstLetter(str: string): string;
reverse(str: string): string;
pad(str: string, maxLength: number, options?: import("./domains/data-types/string/strings-utils").StringPaddingOptions): string;
padStart(str: string, maxLength: number, options?: Omit<import("./domains/data-types/string/strings-utils").StringPaddingOptions, "side">): string;
padEnd(str: string, maxLength: number, options?: Omit<import("./domains/data-types/string/strings-utils").StringPaddingOptions, "side">): string;
removeWhitespace(str: string): string;
countOccurrences(str: string, substr: string): number;
startsWithIgnoreCase(str: string, prefix: string): boolean;
endsWithIgnoreCase(str: string, suffix: string): boolean;
stripHTMLTags(str: string): string;
slugify(str: string): string;
};
number: {
readonly guard: {
isNumber(value: unknown): value is number;
isNegative(value: unknown): boolean;
isPositive(value: unknown): boolean;
isNaN(value: unknown): value is typeof NaN;
isInteger(value: unknown): boolean;
isFinite(value: unknown): boolean;
isFloat(value: unknown): boolean;
};
};
object: {
readonly "__#4@#_helpers": {
smartClone: <T>(input: T, seen?: WeakMap<WeakKey, any>) => T;
};
readonly guard: {
isObject(value: unknown): value is object;
isFreezable(value: unknown): value is object;
};
freeze<T extends import(".").Objects>(obj: T): Readonly<T>;
deepFreeze<T extends import(".").Objects>(obj: T): import(".").DeepReadonly<T>;
stringify<T extends import(".").Objects>(obj: T, spaces?: number): import(".").Stringified<T>;
parse<T>(json: import(".").Stringified<T>): import(".").JSONObject<T>;
smartClone<T>(obj: T): T;
clone<T>(obj: T): T;
};
record: {
readonly guard: {
isRecord(value: unknown): value is Record<string, any>;
isEmpty(value: unknown): boolean;
};
hasOwnProperty<T extends Record<string, any>>(obj: T, prop: keyof T | (string & {})): prop is keyof T;
toMap<K extends string, V>(obj: Record<K, V>): Map<K, V>;
freeze<T extends Record<string, any>>(obj: T): Readonly<T>;
deepFreeze<T extends Record<string, any>>(obj: T): import(".").DeepReadonly<T>;
stringify<T extends Record<string, any>>(obj: T, spaces?: number): import(".").Stringified<T>;
parse<T>(json: import(".").Stringified<T>): import(".").JSONObject<T>;
keys<T extends Record<string, any>>(obj: T): (keyof T)[];
values<T extends Record<string, any>>(obj: T): T[keyof T][];
entries<TObj extends Record<string, any>, TKey extends keyof TObj>(obj: TObj): [TKey, TObj[TKey]][];
};
array: {
readonly guard: {
isArray(value: unknown): value is Array<any>;
isNotEmpty<T extends Array<T>>(value: unknown): value is import(".").NonEmptyArray<T>;
isArrayOf<T>(itemGuard: (item: unknown) => item is T): (value: unknown) => value is T[];
readonly isArrayOfNumbers: (value: unknown) => value is number[];
readonly isArrayOfStrings: (value: unknown) => value is string[];
readonly isArrayOfArrays: (value: unknown) => value is any[][];
};
head<T>(array: T[]): T | undefined;
last<T>(array: T[]): T | undefined;
compact<T>(array: T[]): T[];
unique<T>(array: T[]): T[];
chunk<T>(array: T[], size: number): T[][];
groupBy<T, K extends string | number>(arr: T[], keyFn: (item: T) => K): Record<K, T[]>;
flatten<T>(array: T[], depth?: number): FlatArray<T, 0 | 1 | 2 | -1 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20>[];
deepFlatten<T>(array: T[]): FlatArray<T, 0 | 1 | 2 | -1 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20>[];
difference<T>(a: T[], b: T[]): T[];
intersect<T>(a: T[], b: T[]): T[];
toggleValue<T>(arr: T[], value: T, options?: {
mutable?: boolean;
}): T[];
mapAsync<T, U>(arr: T[], fn: (item: T, index: number) => Promise<U>): Promise<Awaited<U>[]>;
range(start: number, end: number, step?: number): number[];
transpose<T>(matrix: T[][]): T[][];
shuffle<T>(arr: T[]): T[];
};
regex: {
readonly guard: {
isGlobLike(pattern: string): boolean;
};
globToRegExp(glob: string, options?: {
globstar?: boolean;
flags?: string;
}): RegExp;
};
}>;
/**
* Path utilities for working with and manipulating file system paths.
* Compatible with cross-platform path operations.
* @since v1.0.0
*/
readonly path: {
normalizePath(path_: string): string;
sanitizeName(name: string, replacement?: string): string;
isSubPath(childPath: string, parentPath: string): boolean;
getFileNameWithoutExtension(filePath: string): string;
changeExtension(filePath: string, newExt: string): string;
isValidPath(path_: string): boolean;
relativeToCwd(path_: string): string;
isLikelyPath(str: string): boolean;
};
/**
* File system utilities for reading, writing, and checking files/directories.
* Supports both sync and async operations.
* @since v1.0.0
*/
readonly fs: {
readonly promises: {
loadJSON(filePath: string): Promise<Record<string, any> | Array<any>>;
canAccess(filePath: string, options?: import(".").AccessOptions): Promise<boolean>;
};
loadJSONSync(filePath: string): Record<string, any> | Array<any>;
canAccessSync(filePath: string, options?: import(".").AccessOptions): boolean;
};
/**
* HTTP-related utilities for encoding, decoding, and managing request/response bodies.
* Includes support for body codecs and common header handling.
* @since v1.0.0
*/
readonly http: {
readonly "__#5@#_helpers": {
inputValidators: {
sanitizeOptions: (options?: import(".").InputSanitizationOptions) => {
trim: boolean;
allowHTML: boolean;
allowUnicode: boolean;
maxLength: number;
strict: boolean;
allow?: RegExp | undefined;
deny?: RegExp | undefined;
};
sanitizeString: (input: string, options?: import(".").InputSanitizationOptions) => {
trim: boolean;
allowHTML: boolean;
allowUnicode: boolean;
maxLength: number;
strict: boolean;
allow?: RegExp | undefined;
deny?: RegExp | undefined;
};
sanitize: <T extends Record<string, string>>(input: T, options?: import(".").FieldRuleMap<T> | undefined) => { [K in keyof T]: import(".").SanitizedResult<string> | undefined; };
};
sanitizeString: (input: string, opts?: import(".").InputSanitizationOptions) => import(".").SanitizedResult<string>;
};
readonly guard: {
isHTML(value: string): value is string;
isMimeType(value: unknown): value is import(".").Mime;
isExtension(value: unknown): value is import(".").FileExtension;
isValidURL(url: unknown): boolean;
isEmail(value: unknown): value is string;
};
readonly mimes: {
readonly "__#1@#_extensions": import(".").FileExtension[];
readonly "__#1@#_mimes": import(".").Mime[];
readonly "__#1@#_cache": {
extensionToMime: Map<"" | ".webp" | ".aac" | ".abw" | ".arc" | ".avif" | ".avi" | ".azw" | ".bin" | ".bmp" | ".bz" | ".bz2" | ".cda" | ".csh" | ".css" | ".csv" | ".doc" | ".docx" | ".eot" | ".epub" | ".gz" | ".gif" | ".html" | ".htm" | ".ico" | ".ics" | ".jar" | ".jpeg" | ".jpg" | ".js" | ".json" | ".jsonld" | ".mid" | ".midi" | ".mjs" | ".mp3" | ".mp4" | ".mpeg" | ".mpkg" | ".odp" | ".ods" | ".odt" | ".oga" | ".ogv" | ".ogx" | ".opus" | ".otf" | ".png" | ".pdf" | ".php" | ".ppt" | ".pptx" | ".rar" | ".rtf" | ".sh" | ".svg" | ".tar" | ".tiff" | ".tif", "text/plain" | "image/webp" | "audio/aac" | "application/x-abiword" | "application/x-freearc" | "image/avif" | "video/x-msvideo" | "application/vnd.amazon.ebook" | "application/octet-stream" | "image/bmp" | "application/x-bzip" | "application/x-bzip2" | "application/x-cdf" | "application/x-csh" | "text/css" | "text/csv" | "application/msword" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "application/vnd.ms-fontobject" | "application/epub+zip" | "application/gzip" | "image/gif" | "text/html" | "image/vnd.microsoft.icon" | "text/calendar" | "application/java-archive" | "image/jpeg" | "text/javascript" | "application/json" | "application/ld+json" | "audio/midi" | "audio/x-midi" | "audio/mpeg" | "video/mp4" | "video/mpeg" | "application/vnd.apple.installer+xml" | "application/vnd.oasis.opendocument.presentation" | "application/vnd.oasis.opendocument.spreadsheet" | "application/vnd.oasis.opendocument.text" | "audio/ogg" | "video/ogg" | "application/ogg" | "audio/opus" | "font/otf" | "image/png" | "application/pdf" | "application/x-httpd-php" | "application/vnd.ms-powerpoint" | "application/vnd.openxmlformats-officedocument.presentationml.presentation" | "application/vnd.rar" | "application/rtf" | "application/x-sh" | "image/svg+xml" | "application/x-tar" | "image/tiff">;
mimeToExtension: Map<"text/plain" | "image/webp" | "audio/aac" | "application/x-abiword" | "application/x-freearc" | "image/avif" | "video/x-msvideo" | "application/vnd.amazon.ebook" | "application/octet-stream" | "image/bmp" | "application/x-bzip" | "application/x-bzip2" | "application/x-cdf" | "application/x-csh" | "text/css" | "text/csv" | "application/msword" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "application/vnd.ms-fontobject" | "application/epub+zip" | "application/gzip" | "image/gif" | "text/html" | "image/vnd.microsoft.icon" | "text/calendar" | "application/java-archive" | "image/jpeg" | "text/javascript" | "application/json" | "application/ld+json" | "audio/midi" | "audio/x-midi" | "audio/mpeg" | "video/mp4" | "video/mpeg" | "application/vnd.apple.installer+xml" | "application/vnd.oasis.opendocument.presentation" | "application/vnd.oasis.opendocument.spreadsheet" | "application/vnd.oasis.opendocument.text" | "audio/ogg" | "video/ogg" | "application/ogg" | "audio/opus" | "font/otf" | "image/png" | "application/pdf" | "application/x-httpd-php" | "application/vnd.ms-powerpoint" | "application/vnd.openxmlformats-officedocument.presentationml.presentation" | "application/vnd.rar" | "application/rtf" | "application/x-sh" | "image/svg+xml" | "application/x-tar" | "image/tiff", "" | ".webp" | ".aac" | ".abw" | ".arc" | ".avif" | ".avi" | ".azw" | ".bin" | ".bmp" | ".bz" | ".bz2" | ".cda" | ".csh" | ".css" | ".csv" | ".doc" | ".docx" | ".eot" | ".epub" | ".gz" | ".gif" | ".html" | ".htm" | ".ico" | ".ics" | ".jar" | ".jpeg" | ".jpg" | ".js" | ".json" | ".jsonld" | ".mid" | ".midi" | ".mjs" | ".mp3" | ".mp4" | ".mpeg" | ".mpkg" | ".odp" | ".ods" | ".odt" | ".oga" | ".ogv" | ".ogx" | ".opus" | ".otf" | ".png" | ".pdf" | ".php" | ".ppt" | ".pptx" | ".rar" | ".rtf" | ".sh" | ".svg" | ".tar" | ".tiff" | ".tif">;
};
readonly extensions: import(".").FileExtension[];
readonly mimes: import(".").Mime[];
readonly isValid: {
extension: (ext: any) => ext is import(".").FileExtension;
mime: (mime: any) => mime is import(".").Mime;
};
getExtensionByMime(mime: import(".").Mime): import(".").FileExtension | undefined;
getMimeByExtension(ext: import(".").FileExtension): import(".").Mime | undefined;
};
readonly bodyCodec: {
readonly "__#3@#_helpers": {
serialize: <T extends import(".").Serializable>(value: T) => {
type: string;
value?: undefined;
} | {
value: T & {};
type: string;
} | {
value: string;
type: string;
} | {
value: any[];
type: string;
};
deserialize: <T extends import("./domains/http/body-codec").EncodedPayload>(payload: T) => import("./domains/http/body-codec").Serialization[T["type"]]["type"];
stringify: (value: Record<string, any>, seen?: WeakSet<WeakKey>) => string;
};
encode<T extends import(".").Serializable>(value: T): Buffer<ArrayBuffer>;
decode(buffer: Buffer): string | number | boolean | any[] | Record<string, any> | Set<any> | Map<any, any> | Date | null | undefined;
};
btoa(text: string): string;
atob(base64: string): string;
sanitize<T extends Record<string, string>>(input: T, configs?: import(".").FieldRuleMap<T>): import(".").SanitizedResult<T>;
sanitize<T extends string>(input: T, options?: import(".").InputSanitizationOptions): import(".").SanitizedResult<T>;
};
/**
* Network utilities for interacting with local/remote addresses, DNS, ports, and tracing.
* Useful for diagnostics and runtime-aware networking.
* @since v1.0.0
*/
readonly networks: {
readonly local: {
getLocalIPs(): string[];
getHostname(): string;
getMACAddresses(): string[];
getDefaultGateway(): string;
getNetworkCIDRs(): string[];
getLocalNetworkMap(): Map<string, string[]>;
discoverServiceHosts(port: number, options?: import(".").DiscoverHostsOptions): Promise<string[]>;
};
readonly inspect: {
readonly "__#2@#_helpers": {
traceroute: {
parsers: {
parseWindowsTraceroute(lines: string[]): import(".").TracerouteHop[];
parseUnixTraceroute(lines: string[]): import(".").TracerouteHop[];
};
exec: (hostname: string, platform: NodeJS.Platform) => Promise<string>;
prepareLines: (stdout: string) => string[];
parse: (lines: string[], platform: NodeJS.Platform) => import(".").TracerouteHop[];
};
};
isPortOpen(port: number, option?: import(".").PortCheckOptions): Promise<boolean>;
pingHost(hostname: string, timeoutMs?: number): Promise<boolean>;
traceroute(hostname: string): Promise<import(".").TracerouteHop[]>;
};
readonly dns: {
resolve(hostname: string): Promise<string[]>;
resolve(hostname: string, rrtype: "A"): Promise<string[]>;
resolve(hostname: string, rrtype: "AAAA"): Promise<string[]>;
resolve(hostname: string, rrtype: "ANY"): Promise<import("dns").AnyRecord[]>;
resolve(hostname: string, rrtype: "CAA"): Promise<import("dns").CaaRecord[]>;
resolve(hostname: string, rrtype: "CNAME"): Promise<string[]>;
resolve(hostname: string, rrtype: "MX"): Promise<import("dns").MxRecord[]>;
resolve(hostname: string, rrtype: "NAPTR"): Promise<import("dns").NaptrRecord[]>;
resolve(hostname: string, rrtype: "NS"): Promise<string[]>;
resolve(hostname: string, rrtype: "PTR"): Promise<string[]>;
resolve(hostname: string, rrtype: "SOA"): Promise<import("dns").SoaRecord>;
resolve(hostname: string, rrtype: "SRV"): Promise<import("dns").SrvRecord[]>;
resolve(hostname: string, rrtype: "TLSA"): Promise<import("dns").TlsaRecord[]>;
resolve(hostname: string, rrtype: "TXT"): Promise<string[]>;
lookup(hostname: string): Promise<string[]>;
reverseLookup(address: string): Promise<string[]>;
resolveMx(hostname: string): Promise<import("dns").MxRecord[]>;
resolveNs(hostname: string): Promise<string[]>;
resolveTxt(hostname: string): Promise<string[][]>;
getDNSServers(): string[];
isDNSResolvable(domain: string): Promise<boolean>;
};
readonly remote: {
getPublicIP(): Promise<string>;
getGeoLocation(ip?: string): Promise<import(".").IPGeolocation>;
};
isIPv4(ip: string): boolean;
isPrivateIP(ip: string): boolean;
ipToInt(ip: string): number;
intToIp(int: number): string;
getSubnetIPs(ip: string, subnet: number): string[];
isValidPort(port: unknown): boolean;
};
/**
* Environment utilities for determining runtime characteristics,
* such as platform, OS, environment variables, and process metadata.
* @since v1.0.0
*/
readonly runtime: {
getProjectName(): string;
getModuleSystem(): "commonjs" | "module";
loadModule(name: string, options?: {
isFile?: boolean;
}): Promise<any>;
loadFileModule(filePath: string): Promise<any>;
readonly platform: {
isWindows: () => boolean;
isLinux: () => boolean;
isMac: () => boolean;
};
isNode(): boolean;
isBun(): boolean;
isDeno(): boolean;
getRuntimeEngine(): "node" | "bun" | "deno" | "unknown";
};
/**
* General-purpose utility functions and safe wrappers around common JS operations.
* Includes cloning, comparison, type-safe conversions, and more.
* @since v1.0.0
*/
readonly utils: {
generateRandom(length: number, options?: import(".").RandomOptions): string;
sleep(ms: number): Promise<void>;
debounce<T extends (...args: any[]) => any>(fn: T, delay: number): (...args: Parameters<T>) => Promise<ReturnType<T>>;
debounceSync<T extends (...args: any[]) => any>(fn: T, delay: number, options?: {
onDone?: (result: ReturnType<T>) => void;
onError?: (err: unknown) => void;
}): (...args: Parameters<T>) => void;
throttle<T extends (...args: any[]) => any>(fn: T, delay: number): (...args: Parameters<T>) => Promise<ReturnType<T>> | void;
noop(): void;
once<T extends (...args: any[]) => any>(fn: T): (...args: Parameters<T>) => ReturnType<T>;
};
/**
* A collection of higher-level tools such as task queues and background managers.
* Built for coordination, orchestration, and async workflows.
* @since v1.0.2
*/
readonly tools: {
readonly TasksQueue: typeof import("./tools").TasksQueue;
readonly EventEmitter: typeof import("./tools").EventEmitter;
};
}
/**
* @runtimeCompatibility
* Built and tested on Node.js v22.16.x and later.
* Compatibility with earlier Node versions is not guaranteed.
*/
declare const atomix: Atomix;
export default atomix;