gracefulerrors 0.1.0

package/dist/types-CsPmpcbL.d.cts

@@ -0,0 +1,149 @@
+type SystemErrorCode = 'GRACEFULERRORS_UNKNOWN' | 'GRACEFULERRORS_UNHANDLED';
+interface AppError<TCode extends string = string, TField extends string = string> {
+    code: TCode | SystemErrorCode;
+    status?: number;
+    message?: string;
+    context?: {
+        field?: TField;
+        [key: string]: unknown;
+    };
+    raw?: unknown;
+}
+type SuppressionDecision = {
+    suppress: true;
+    reason: string;
+};
+type TransformResult<TCode extends string = string, TField extends string = string> = AppError<TCode, TField> | SuppressionDecision | null;
+type TransformContext = {
+    raw: unknown;
+};
+type UIOptions = {
+    ui: 'toast';
+    uiOptions?: {
+        position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'top-center' | 'bottom-center';
+        severity?: 'info' | 'warning' | 'error' | 'success';
+        icon?: string;
+        duration?: number;
+    };
+} | {
+    ui: 'modal';
+    uiOptions?: {
+        dismissible?: boolean;
+        size?: 'sm' | 'md' | 'lg';
+    };
+} | {
+    ui: 'inline';
+    uiOptions?: Record<string, unknown>;
+} | {
+    ui: 'silent';
+    uiOptions?: never;
+};
+type UIAction = 'toast' | 'modal' | 'inline' | 'silent';
+type ErrorRegistryEntry<TCode extends string = string> = {
+    message?: string | ((error: AppError<TCode>) => string);
+    ttl?: number;
+} & UIOptions;
+type ErrorRegistryEntryFull<TCode extends string = string> = ErrorRegistryEntry<TCode>;
+type ErrorRegistry<TCode extends string = string> = {
+    [K in TCode]?: ErrorRegistryEntry<TCode>;
+};
+type RenderIntent<TCode extends string = string> = {
+    ui: UIAction;
+    error: AppError<TCode>;
+    entry: ErrorRegistryEntryFull<TCode>;
+};
+interface RendererAdapter {
+    render<TCode extends string = string>(intent: RenderIntent<TCode>, lifecycle: {
+        onDismiss?: () => void;
+    }): void;
+    clear(code: string): void;
+    clearAll(): void;
+}
+interface ErrorEngine<TCode extends string = string> {
+    handle(raw: unknown): HandleResult<TCode>;
+    clear(code: TCode): void;
+    clearAll(): void;
+    subscribe(listener: StateListener<TCode>): () => void;
+}
+interface HandleResult<TCode extends string = string> {
+    handled: boolean;
+    error: AppError<TCode>;
+    uiAction: UIAction | null;
+}
+type RoutingStrategy<TCode extends string = string, TField extends string = string> = (error: AppError<TCode, TField>, registryEntry: ErrorRegistryEntryFull<TCode> | undefined, context: {
+    activeCount: number;
+    queueLength: number;
+}) => UIAction | null;
+type ErrorState = 'ACTIVE' | 'QUEUED' | 'EXPIRED' | 'DROPPED';
+interface ErrorSlot<TCode extends string = string> {
+    error: AppError<TCode>;
+    state: ErrorState;
+    fingerprint: string;
+    expiresAt?: number;
+}
+type StateListener<TCode extends string = string> = (event: {
+    type: 'ERROR_ADDED';
+    error: AppError<TCode>;
+    action: UIAction;
+} | {
+    type: 'ERROR_CLEARED';
+    code: TCode;
+} | {
+    type: 'ALL_CLEARED';
+}) => void;
+interface ErrorStateManager<TCode extends string = string> {
+    canHandle(fingerprint: string): boolean;
+    enqueue(slot: ErrorSlot<TCode> & {
+        _pendingAction?: UIAction;
+        ttl?: number;
+    }): 'active' | 'queued' | 'rejected';
+    release(code: TCode): void;
+    getActiveSlots(): ErrorSlot<TCode>[];
+    getQueueLength(): number;
+    clearAll(): void;
+    subscribe(listener: StateListener<TCode>): () => void;
+}
+interface UIRouter<TCode extends string = string, TField extends string = string> {
+    route(error: AppError<TCode, TField>, registry: ErrorRegistry<TCode>, config: Pick<ErrorEngineConfig<TCode, TField>, 'fallback' | 'requireRegistry' | 'allowFallback' | 'routingStrategy'> & {
+        routingContext?: {
+            activeCount: number;
+            queueLength: number;
+        };
+    }): UIAction | null;
+}
+type Normalizer<TCode extends string = string, TField extends string = string> = (raw: unknown, current: AppError<TCode, TField> | null) => AppError<TCode, TField> | null;
+interface ErrorEngineConfig<TCode extends string = string, TField extends string = string> {
+    registry: ErrorRegistry<TCode>;
+    requireRegistry?: boolean;
+    allowFallback?: boolean;
+    fallback?: {
+        ui: 'toast' | 'modal' | 'silent';
+        message?: string;
+    };
+    normalizers?: Normalizer<TCode, TField>[];
+    normalizer?: Normalizer<TCode, TField>;
+    fingerprint?: (error: AppError<TCode, TField>) => string;
+    dedupeWindow?: number;
+    maxConcurrent?: number;
+    maxQueue?: number;
+    aggregation?: boolean | {
+        enabled: boolean;
+        window?: number;
+    };
+    routingStrategy?: RoutingStrategy<TCode, TField>;
+    transform?: (error: AppError<TCode, TField>, context: TransformContext) => TransformResult<TCode, TField>;
+    onError?: (raw: unknown) => void;
+    onNormalized?: (error: AppError<TCode, TField>) => void;
+    onSuppressed?: (error: AppError<TCode, TField>, reason: string) => void;
+    onRouted?: (error: AppError<TCode, TField>, action: UIAction) => void;
+    onFallback?: (error: AppError<TCode, TField>) => void;
+    onErrorAsync?: (error: AppError<TCode, TField>) => Promise<void>;
+    onDropped?: (error: AppError<TCode, TField>, reason: 'dedupe' | 'ttl_expired' | 'queue_overflow') => void;
+    debug?: boolean | {
+        trace?: boolean;
+    };
+    modalDismissTimeoutMs?: number;
+    renderer?: RendererAdapter;
+}
+
+export type { AppError as A, ErrorEngineConfig as E, HandleResult as H, Normalizer as N, RenderIntent as R, StateListener as S, TransformContext as T, UIAction as U, ErrorEngine as a, ErrorRegistry as b, ErrorRegistryEntry as c, ErrorRegistryEntryFull as d, RendererAdapter as e, RoutingStrategy as f, TransformResult as g, UIOptions as h, ErrorStateManager as i, UIRouter as j, ErrorSlot as k, ErrorState as l };

package/dist/types-CsPmpcbL.d.ts

@@ -0,0 +1,149 @@
+type SystemErrorCode = 'GRACEFULERRORS_UNKNOWN' | 'GRACEFULERRORS_UNHANDLED';
+interface AppError<TCode extends string = string, TField extends string = string> {
+    code: TCode | SystemErrorCode;
+    status?: number;
+    message?: string;
+    context?: {
+        field?: TField;
+        [key: string]: unknown;
+    };
+    raw?: unknown;
+}
+type SuppressionDecision = {
+    suppress: true;
+    reason: string;
+};
+type TransformResult<TCode extends string = string, TField extends string = string> = AppError<TCode, TField> | SuppressionDecision | null;
+type TransformContext = {
+    raw: unknown;
+};
+type UIOptions = {
+    ui: 'toast';
+    uiOptions?: {
+        position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'top-center' | 'bottom-center';
+        severity?: 'info' | 'warning' | 'error' | 'success';
+        icon?: string;
+        duration?: number;
+    };
+} | {
+    ui: 'modal';
+    uiOptions?: {
+        dismissible?: boolean;
+        size?: 'sm' | 'md' | 'lg';
+    };
+} | {
+    ui: 'inline';
+    uiOptions?: Record<string, unknown>;
+} | {
+    ui: 'silent';
+    uiOptions?: never;
+};
+type UIAction = 'toast' | 'modal' | 'inline' | 'silent';
+type ErrorRegistryEntry<TCode extends string = string> = {
+    message?: string | ((error: AppError<TCode>) => string);
+    ttl?: number;
+} & UIOptions;
+type ErrorRegistryEntryFull<TCode extends string = string> = ErrorRegistryEntry<TCode>;
+type ErrorRegistry<TCode extends string = string> = {
+    [K in TCode]?: ErrorRegistryEntry<TCode>;
+};
+type RenderIntent<TCode extends string = string> = {
+    ui: UIAction;
+    error: AppError<TCode>;
+    entry: ErrorRegistryEntryFull<TCode>;
+};
+interface RendererAdapter {
+    render<TCode extends string = string>(intent: RenderIntent<TCode>, lifecycle: {
+        onDismiss?: () => void;
+    }): void;
+    clear(code: string): void;
+    clearAll(): void;
+}
+interface ErrorEngine<TCode extends string = string> {
+    handle(raw: unknown): HandleResult<TCode>;
+    clear(code: TCode): void;
+    clearAll(): void;
+    subscribe(listener: StateListener<TCode>): () => void;
+}
+interface HandleResult<TCode extends string = string> {
+    handled: boolean;
+    error: AppError<TCode>;
+    uiAction: UIAction | null;
+}
+type RoutingStrategy<TCode extends string = string, TField extends string = string> = (error: AppError<TCode, TField>, registryEntry: ErrorRegistryEntryFull<TCode> | undefined, context: {
+    activeCount: number;
+    queueLength: number;
+}) => UIAction | null;
+type ErrorState = 'ACTIVE' | 'QUEUED' | 'EXPIRED' | 'DROPPED';
+interface ErrorSlot<TCode extends string = string> {
+    error: AppError<TCode>;
+    state: ErrorState;
+    fingerprint: string;
+    expiresAt?: number;
+}
+type StateListener<TCode extends string = string> = (event: {
+    type: 'ERROR_ADDED';
+    error: AppError<TCode>;
+    action: UIAction;
+} | {
+    type: 'ERROR_CLEARED';
+    code: TCode;
+} | {
+    type: 'ALL_CLEARED';
+}) => void;
+interface ErrorStateManager<TCode extends string = string> {
+    canHandle(fingerprint: string): boolean;
+    enqueue(slot: ErrorSlot<TCode> & {
+        _pendingAction?: UIAction;
+        ttl?: number;
+    }): 'active' | 'queued' | 'rejected';
+    release(code: TCode): void;
+    getActiveSlots(): ErrorSlot<TCode>[];
+    getQueueLength(): number;
+    clearAll(): void;
+    subscribe(listener: StateListener<TCode>): () => void;
+}
+interface UIRouter<TCode extends string = string, TField extends string = string> {
+    route(error: AppError<TCode, TField>, registry: ErrorRegistry<TCode>, config: Pick<ErrorEngineConfig<TCode, TField>, 'fallback' | 'requireRegistry' | 'allowFallback' | 'routingStrategy'> & {
+        routingContext?: {
+            activeCount: number;
+            queueLength: number;
+        };
+    }): UIAction | null;
+}
+type Normalizer<TCode extends string = string, TField extends string = string> = (raw: unknown, current: AppError<TCode, TField> | null) => AppError<TCode, TField> | null;
+interface ErrorEngineConfig<TCode extends string = string, TField extends string = string> {
+    registry: ErrorRegistry<TCode>;
+    requireRegistry?: boolean;
+    allowFallback?: boolean;
+    fallback?: {
+        ui: 'toast' | 'modal' | 'silent';
+        message?: string;
+    };
+    normalizers?: Normalizer<TCode, TField>[];
+    normalizer?: Normalizer<TCode, TField>;
+    fingerprint?: (error: AppError<TCode, TField>) => string;
+    dedupeWindow?: number;
+    maxConcurrent?: number;
+    maxQueue?: number;
+    aggregation?: boolean | {
+        enabled: boolean;
+        window?: number;
+    };
+    routingStrategy?: RoutingStrategy<TCode, TField>;
+    transform?: (error: AppError<TCode, TField>, context: TransformContext) => TransformResult<TCode, TField>;
+    onError?: (raw: unknown) => void;
+    onNormalized?: (error: AppError<TCode, TField>) => void;
+    onSuppressed?: (error: AppError<TCode, TField>, reason: string) => void;
+    onRouted?: (error: AppError<TCode, TField>, action: UIAction) => void;
+    onFallback?: (error: AppError<TCode, TField>) => void;
+    onErrorAsync?: (error: AppError<TCode, TField>) => Promise<void>;
+    onDropped?: (error: AppError<TCode, TField>, reason: 'dedupe' | 'ttl_expired' | 'queue_overflow') => void;
+    debug?: boolean | {
+        trace?: boolean;
+    };
+    modalDismissTimeoutMs?: number;
+    renderer?: RendererAdapter;
+}
+
+export type { AppError as A, ErrorEngineConfig as E, HandleResult as H, Normalizer as N, RenderIntent as R, StateListener as S, TransformContext as T, UIAction as U, ErrorEngine as a, ErrorRegistry as b, ErrorRegistryEntry as c, ErrorRegistryEntryFull as d, RendererAdapter as e, RoutingStrategy as f, TransformResult as g, UIOptions as h, ErrorStateManager as i, UIRouter as j, ErrorSlot as k, ErrorState as l };

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "gracefulerrors",
+  "version": "0.1.0",
+  "description": "Transform technical errors into consistent, user-friendly experiences",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.mjs",
+      "require": "./dist/react.cjs"
+    },
+    "./sonner": {
+      "types": "./dist/adapters/sonner.d.ts",
+      "import": "./dist/adapters/sonner.mjs",
+      "require": "./dist/adapters/sonner.cjs"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.mjs",
+      "require": "./dist/internal.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "pretest:types": "npm run build",
+    "test:types": "tsd",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts,.tsx"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "sonner": ">=1"
+  },
+  "peerDependenciesMeta": {
+    "sonner": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "tsd": {
+    "directory": "src/__tests__"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^14.0.0",
+    "@testing-library/user-event": "^14.0.0",
+    "@types/node": "^25.5.2",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "@vitest/coverage-v8": "^1.0.0",
+    "jsdom": "^24.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "sonner": "^1.0.0",
+    "tsd": "^0.31.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}