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) • 10.3 kB
TypeScript
import { $ as S3ImageSchema, A as createStorage, B as PaginatedListOptions, C as S3RouterDefinition, D as UploadInitResult, E as UploadConfigBuilder, F as FileInfoResult, G as ValidationRules, H as PresignedUrlResult, I as FileKeyOptions, J as InferS3Input, K as createS3Client, L as FileValidationResult, M as DeleteError, N as DeleteFilesResult, O as createUploadConfig, P as FileInfo, Q as S3FileSchema, R as ListFilesOptions, S as S3Router, T as UploadConfig, U as ProgressCallback, V as PresignedUrlOptions, W as UploadProgress, X as S3ArraySchema, Y as InferS3Output, Z as S3FileConstraints, _ as S3LifecycleHook, at as DigitalOceanSpacesConfig, b as S3Route, ct as ProviderConfig, d as GetRoute, dt as getProviderEndpoint, et as S3ObjectSchema, f as InferRouteInput, ft as validateProviderConfig, g as S3LifecycleContext, h as InferRouterRoutes, it as CloudflareR2Config, j as DeleteByPrefixResult, k as StorageInstance, lt as ProviderType, m as InferRouteOutput, nt as AWSProviderConfig, ot as GoogleCloudStorageConfig, p as InferRouteMetadata, q as resetS3Client, rt as BaseProviderConfig, st as MinIOConfig, tt as S3Schema, ut as createProvider, v as S3Middleware, w as createS3RouterWithConfig, x as S3RouteContext, y as S3MiddlewareContext, z as ListFilesResult } from "./index-BmRrcynd.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 { type AWSProviderConfig, type AggregatedMetrics, type BaseProviderConfig, type CloudflareR2Config, type DeleteByPrefixResult, type DeleteError, type DeleteFilesResult, type DigitalOceanSpacesConfig, type FileInfo, type FileInfoResult, type FileKeyOptions, type FileValidationResult, type GetRoute, type GoogleCloudStorageConfig, type HealthCheck, type HealthCheckResult, type InferRouteInput, type InferRouteMetadata, type InferRouteOutput, type InferRouterRoutes, type InferS3Input, type InferS3Output, type ListFilesOptions, type ListFilesResult, type LogLevel, type MinIOConfig, type OperationMetrics, type PaginatedListOptions, type PresignedUrlOptions, type PresignedUrlResult, type ProgressCallback, type ProviderConfig, type ProviderType, PushduckError, type PushduckErrorCode, type PushduckErrorContext, type PushduckResult, S3ArraySchema, type S3FileConstraints, S3FileSchema, S3ImageSchema, type S3LifecycleContext, type S3LifecycleHook, type S3Middleware, type S3MiddlewareContext, S3ObjectSchema, S3Route, type S3RouteContext, type S3Router, type S3RouterDefinition, S3Schema, StorageInstance, type UploadConfigBuilder, type UploadInitResult, type UploadProgress, type 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 };