pushduck
Version:
The fastest way to add file uploads to any web application. Enterprise security, edge-ready. Works with 16+ frameworks and 5+ storage providers. No heavy AWS SDK required.
236 lines (234 loc) • 9.77 kB
TypeScript
import { AWSProviderConfig, BaseProviderConfig, CloudflareR2Config, DeleteByPrefixResult, DeleteError, DeleteFilesResult, DigitalOceanSpacesConfig, FileInfo, FileInfoResult, FileKeyOptions, FileValidationResult, GetRoute, GoogleCloudStorageConfig, InferRouteInput, InferRouteMetadata, InferRouteOutput, InferRouterRoutes, InferS3Input, InferS3Output, ListFilesOptions, ListFilesResult, MinIOConfig, PaginatedListOptions, PresignedUrlOptions, PresignedUrlResult, ProgressCallback, ProviderConfig, ProviderType, S3ArraySchema, S3FileConstraints, S3FileSchema, S3ImageSchema, S3LifecycleContext, S3LifecycleHook, S3Middleware, S3MiddlewareContext, S3ObjectSchema, S3Route, S3RouteContext, S3Router, S3RouterDefinition, S3Schema, StorageInstance, UploadConfig, UploadConfigBuilder, UploadInitResult, UploadProgress, ValidationRules, createProvider, createS3Client, createS3RouterWithConfig, createStorage, createUploadConfig, getProviderEndpoint, resetS3Client, validateProviderConfig } from "./index-GOfQFW5v.js";
//#region src/core/types/errors.d.ts
/**
* Comprehensive error types for pushduck
*
* Provides structured error handling with specific error codes and context
*/
type PushduckErrorCode = "CONFIG_INVALID" | "CONFIG_MISSING" | "PROVIDER_UNSUPPORTED" | "PROVIDER_CONFIG_INVALID" | "S3_CONNECTION_FAILED" | "S3_BUCKET_NOT_FOUND" | "S3_ACCESS_DENIED" | "S3_INVALID_CREDENTIALS" | "FILE_NOT_FOUND" | "FILE_TOO_LARGE" | "FILE_TYPE_NOT_ALLOWED" | "FILE_VALIDATION_FAILED" | "UPLOAD_FAILED" | "DOWNLOAD_FAILED" | "PRESIGNED_URL_FAILED" | "NETWORK_ERROR" | "TIMEOUT_ERROR" | "UNKNOWN_ERROR";
interface PushduckErrorContext {
operation?: string;
provider?: string;
bucket?: string;
key?: string;
statusCode?: number;
originalError?: Error;
[key: string]: any;
}
declare class PushduckError extends Error {
readonly code: PushduckErrorCode;
readonly context: PushduckErrorContext;
readonly timestamp: Date;
constructor(code: PushduckErrorCode, message: string, context?: PushduckErrorContext);
/**
* Create a user-friendly error message
*/
getUserMessage(): string;
/**
* Get debugging information
*/
getDebugInfo(): Record<string, any>;
/**
* Convert to JSON for logging/serialization
*/
toJSON(): Record<string, any>;
}
declare const createConfigError: (message: string, context?: PushduckErrorContext) => PushduckError;
declare const createS3Error: (message: string, context?: PushduckErrorContext) => PushduckError;
declare const createFileError: (code: PushduckErrorCode, message: string, context?: PushduckErrorContext) => PushduckError;
declare const createNetworkError: (message: string, context?: PushduckErrorContext) => PushduckError;
declare const isPushduckError: (error: unknown) => error is PushduckError;
declare const isConfigError: (error: unknown) => error is PushduckError;
declare const isS3Error: (error: unknown) => error is PushduckError;
declare const isFileError: (error: unknown) => error is PushduckError;
type PushduckResult<T> = {
success: true;
data: T;
} | {
success: false;
error: PushduckError;
};
declare const wrapAsync: <T>(operation: () => Promise<T>, errorCode: PushduckErrorCode, context?: PushduckErrorContext) => Promise<PushduckResult<T>>;
//#endregion
//#region src/core/utils/metrics.d.ts
/**
* Performance monitoring and metrics for pushduck
*
* Tracks operation performance, file sizes, and success rates
*/
interface OperationMetrics {
operation: string;
startTime: number;
endTime?: number;
duration?: number;
success: boolean;
fileSize?: number;
provider?: string;
errorCode?: string;
metadata?: Record<string, any>;
}
interface AggregatedMetrics {
totalOperations: number;
successfulOperations: number;
failedOperations: number;
successRate: number;
averageDuration: number;
totalDataTransferred: number;
operationsByType: Record<string, number>;
errorsByCode: Record<string, number>;
providerUsage: Record<string, number>;
}
declare class MetricsCollector {
private metrics;
private maxMetricsHistory;
private isEnabled;
constructor(options?: {
enabled?: boolean;
});
/**
* Start tracking an operation
*/
startOperation(operation: string, metadata?: Record<string, any>): string;
/**
* End tracking an operation
*/
endOperation(operationId: string, success: boolean, options?: {
fileSize?: number;
provider?: string;
errorCode?: string;
metadata?: Record<string, any>;
}): void;
/**
* Record a simple operation (start and end together)
*/
recordOperation(operation: string, duration: number, success: boolean, options?: {
fileSize?: number;
provider?: string;
errorCode?: string;
metadata?: Record<string, any>;
}): void;
/**
* Get aggregated metrics
*/
getAggregatedMetrics(timeWindow?: number): AggregatedMetrics;
/**
* Get raw metrics (for debugging)
*/
getRawMetrics(): OperationMetrics[];
/**
* Clear all metrics
*/
clearMetrics(): void;
/**
* Get performance summary
*/
getPerformanceSummary(): string;
private trimMetricsHistory;
private formatBytes;
/**
* Enable or disable metrics collection
*/
setEnabled(enabled: boolean): void;
/**
* Check if metrics collection is enabled
*/
isMetricsEnabled(): boolean;
}
declare const metrics: MetricsCollector;
declare const startOperation: (operation: string, metadata?: Record<string, any>) => string;
declare const endOperation: (operationId: string, success: boolean, options?: Parameters<typeof metrics.endOperation>[2]) => void;
declare const recordOperation: (operation: string, duration: number, success: boolean, options?: Parameters<typeof metrics.recordOperation>[3]) => void;
declare function trackOperation(operationName: string): <T extends (...args: any[]) => Promise<any>>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T>;
//#endregion
//#region src/core/utils/health-check.d.ts
interface HealthCheckResult {
status: "healthy" | "warning" | "error";
checks: HealthCheck[];
summary: {
total: number;
passed: number;
warnings: number;
failures: number;
};
timestamp: Date;
}
interface HealthCheck {
name: string;
status: "pass" | "warn" | "fail";
message: string;
details?: any;
duration?: number;
}
declare class HealthChecker {
private checks;
/**
* Run all health checks
*/
runHealthChecks(config?: UploadConfig): Promise<HealthCheckResult>;
/**
* Check configuration validity
*/
private checkConfiguration;
/**
* Check environment and dependencies
*/
private checkEnvironment;
/**
* Check S3 connectivity
*/
private checkConnectivity;
/**
* Check performance metrics
*/
private checkPerformance;
/**
* Validate provider-specific configuration
*/
private validateProviderConfig;
private addCheck;
private updateCheckDuration;
private calculateSummary;
private determineOverallStatus;
/**
* Get a formatted health report
*/
getHealthReport(result: HealthCheckResult): string;
}
declare const healthChecker: HealthChecker;
declare const runHealthCheck: (config?: UploadConfig) => Promise<HealthCheckResult>;
declare const getHealthReport: (result: HealthCheckResult) => string;
//#endregion
//#region src/core/utils/logger.d.ts
/**
* Logging utility for pushduck
*
* Provides structured logging with different levels and optional debug mode
*/
type LogLevel = "debug" | "info" | "warn" | "error";
interface LogContext {
operation?: string;
provider?: string;
key?: string;
bucket?: string;
[key: string]: any;
}
declare class Logger {
private isDebugMode;
constructor(options?: {
debug?: boolean;
});
setDebugMode(enabled: boolean): void;
private formatMessage;
private getLogPrefix;
debug(message: string, context?: LogContext): void;
info(message: string, context?: LogContext): void;
warn(message: string, context?: LogContext): void;
error(message: string, error?: Error | unknown, context?: LogContext): void;
s3Operation(operation: string, details: LogContext): void;
configInit(provider: string, details: LogContext): void;
presignedUrl(key: string, details: LogContext): void;
fileOperation(operation: string, key: string, details?: LogContext): void;
}
declare const logger: Logger;
//#endregion
export { AWSProviderConfig, AggregatedMetrics, BaseProviderConfig, CloudflareR2Config, DeleteByPrefixResult, DeleteError, DeleteFilesResult, DigitalOceanSpacesConfig, FileInfo, FileInfoResult, FileKeyOptions, FileValidationResult, GetRoute, GoogleCloudStorageConfig, HealthCheck, HealthCheckResult, InferRouteInput, InferRouteMetadata, InferRouteOutput, InferRouterRoutes, InferS3Input, InferS3Output, ListFilesOptions, ListFilesResult, LogLevel, MinIOConfig, OperationMetrics, PaginatedListOptions, PresignedUrlOptions, PresignedUrlResult, ProgressCallback, ProviderConfig, ProviderType, PushduckError, PushduckErrorCode, PushduckErrorContext, PushduckResult, S3ArraySchema, S3FileConstraints, S3FileSchema, S3ImageSchema, S3LifecycleContext, S3LifecycleHook, S3Middleware, S3MiddlewareContext, S3ObjectSchema, S3Route, S3RouteContext, S3Router, S3RouterDefinition, S3Schema, StorageInstance, UploadConfigBuilder, UploadInitResult, UploadProgress, ValidationRules, createConfigError, createFileError, createNetworkError, createProvider, createS3Client, createS3Error, createS3RouterWithConfig, createStorage, createUploadConfig, endOperation, getHealthReport, getProviderEndpoint, healthChecker, isConfigError, isFileError, isPushduckError, isS3Error, logger, metrics, recordOperation, resetS3Client, runHealthCheck, startOperation, trackOperation, validateProviderConfig, wrapAsync };