@socketsecurity/lib 0.0.0 → 1.0.1

package/dist/fs.d.ts

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview File system utilities with cross-platform path handling.
+ * Provides enhanced fs operations, glob matching, and directory traversal functions.
+ */
+import type { Abortable } from 'node:events';
+import type { ObjectEncodingOptions, OpenMode, PathLike } from 'node:fs';
+import type { JsonReviver } from './json';
+import { type Remap } from './objects';
+// Type definitions
+export type BufferEncoding = 'ascii' | 'utf8' | 'utf-8' | 'utf16le' | 'ucs2' | 'ucs-2' | 'base64' | 'base64url' | 'latin1' | 'binary' | 'hex';
+export type JsonContent = unknown;
+export interface FindUpOptions {
+    cwd?: string;
+    onlyDirectories?: boolean;
+    onlyFiles?: boolean;
+    signal?: AbortSignal;
+}
+export interface FindUpSyncOptions {
+    cwd?: string;
+    stopAt?: string;
+    onlyDirectories?: boolean;
+    onlyFiles?: boolean;
+}
+export interface IsDirEmptyOptions {
+    ignore?: string[] | readonly string[] | undefined;
+}
+export interface ReadOptions extends Abortable {
+    encoding?: BufferEncoding | string;
+    flag?: string;
+}
+export interface ReadDirOptions {
+    ignore?: string[] | readonly string[] | undefined;
+    includeEmpty?: boolean | undefined;
+    sort?: boolean | undefined;
+}
+export type ReadFileOptions = Remap<ObjectEncodingOptions & Abortable & {
+    flag?: OpenMode | undefined;
+}> | BufferEncoding | null;
+export type ReadJsonOptions = Remap<ReadFileOptions & {
+    throws?: boolean | undefined;
+    reviver?: Parameters<typeof JSON.parse>[1];
+}>;
+export interface RemoveOptions {
+    force?: boolean;
+    maxRetries?: number;
+    recursive?: boolean;
+    retryDelay?: number;
+    signal?: AbortSignal;
+}
+export interface SafeReadOptions extends ReadOptions {
+    defaultValue?: unknown;
+}
+export interface WriteOptions extends Abortable {
+    encoding?: BufferEncoding | string;
+    mode?: number;
+    flag?: string;
+}
+export interface WriteJsonOptions extends WriteOptions {
+    EOL?: string | undefined;
+    finalEOL?: boolean | undefined;
+    replacer?: JsonReviver | undefined;
+    spaces?: number | string | undefined;
+}
+/**
+ * Find a file or directory by traversing up parent directories.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function findUp(name: string | string[] | readonly string[], options?: FindUpOptions | undefined): Promise<string | undefined>;
+/**
+ * Synchronously find a file or directory by traversing up parent directories.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function findUpSync(name: string | string[] | readonly string[], options?: FindUpSyncOptions | undefined): string;
+/**
+ * Check if a path is a directory asynchronously.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function isDir(filepath: PathLike): Promise<boolean>;
+/**
+ * Check if a path is a directory synchronously.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function isDirSync(filepath: PathLike): boolean;
+/**
+ * Check if a directory is empty synchronously.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function isDirEmptySync(dirname: PathLike, options?: IsDirEmptyOptions | undefined): boolean;
+/**
+ * Check if a path is a symbolic link synchronously.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function isSymLinkSync(filepath: PathLike): boolean;
+/**
+ * Read directory names asynchronously with filtering and sorting.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function readDirNames(dirname: PathLike, options?: ReadDirOptions | undefined): Promise<string[]>;
+/**
+ * Read directory names synchronously with filtering and sorting.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function readDirNamesSync(dirname: PathLike, options?: ReadDirOptions): string[];
+/**
+ * Read a file as binary data asynchronously.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function readFileBinary(filepath: PathLike, options?: ReadFileOptions | undefined): Promise<Buffer<ArrayBufferLike>>;
+/**
+ * Read a file as UTF-8 text asynchronously.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function readFileUtf8(filepath: PathLike, options?: ReadFileOptions | undefined): Promise<string>;
+/**
+ * Read a file as binary data synchronously.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function readFileBinarySync(filepath: PathLike, options?: ReadFileOptions | undefined): string | NonSharedBuffer;
+/**
+ * Read a file as UTF-8 text synchronously.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function readFileUtf8Sync(filepath: PathLike, options?: ReadFileOptions | undefined): string | NonSharedBuffer;
+/**
+ * Read and parse a JSON file asynchronously.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function readJson(filepath: PathLike, options?: ReadJsonOptions | string | undefined): Promise<import("./json").JsonValue>;
+/**
+ * Read and parse a JSON file synchronously.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function readJsonSync(filepath: PathLike, options?: ReadJsonOptions | string | undefined): import("./json").JsonValue;
+/**
+ * Safely delete a file or directory asynchronously with built-in protections.
+ * Uses `del` for safer deletion that prevents removing cwd and above by default.
+ * Automatically uses force: true for temp directory, cacache, and ~/.socket subdirectories.
+ * @throws {Error} When attempting to delete protected paths without force option.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function safeDelete(filepath: PathLike | PathLike[], options?: RemoveOptions | undefined): Promise<void>;
+/**
+ * Safely delete a file or directory synchronously with built-in protections.
+ * Uses `del` for safer deletion that prevents removing cwd and above by default.
+ * Automatically uses force: true for temp directory, cacache, and ~/.socket subdirectories.
+ * @throws {Error} When attempting to delete protected paths without force option.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function safeDeleteSync(filepath: PathLike | PathLike[], options?: RemoveOptions | undefined): void;
+/**
+ * Safely read a file asynchronously, returning undefined on error.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function safeReadFile(filepath: PathLike, options?: SafeReadOptions | undefined): Promise<Buffer<ArrayBufferLike>>;
+/**
+ * Safely get file stats asynchronously, returning undefined on error.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function safeStats(filepath: PathLike): Promise<import("fs").Stats>;
+/**
+ * Safely get file stats synchronously, returning undefined on error.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function safeStatsSync(filepath: PathLike, options?: ReadFileOptions | undefined): import("fs").BigIntStats | import("fs").Stats;
+/**
+ * Safely read a file synchronously, returning undefined on error.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function safeReadFileSync(filepath: PathLike, options?: SafeReadOptions | undefined): string | NonSharedBuffer;
+/**
+ * Generate a unique filepath by adding number suffix if the path exists.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function uniqueSync(filepath: PathLike): string;
+/**
+ * Write JSON content to a file asynchronously with formatting.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function writeJson(filepath: PathLike, jsonContent: unknown, options?: WriteJsonOptions | string): Promise<void>;
+/**
+ * Write JSON content to a file synchronously with formatting.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function writeJsonSync(filepath: PathLike, jsonContent: unknown, options?: WriteJsonOptions | string | undefined): void;