{"_id":"@bernierllc/validators-retry-topology","name":"@bernierllc/validators-retry-topology","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.3":{"name":"@bernierllc/validators-retry-topology","version":"0.1.3","description":"Retry topology validation - loops, backoff, dead-letter policy, and circuit breaker validation","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","dev":"tsc --watch","test":"jest","test:run":"jest","test:coverage":"jest --coverage","lint":"eslint src --ext .ts","lint:fix":"eslint src --ext .ts --fix","clean":"rm -rf dist"},"keywords":["validation","validators","retry","topology","backoff","circuit-breaker","dead-letter","workflow","reliability"],"author":{"name":"Bernier LLC"},"license":"UNLICENSED","private":false,"dependencies":{"@bernierllc/validators-core":"^0.1.1","@bernierllc/retry-policy":"^0.1.3"},"peerDependencies":{},"devDependencies":{"@types/jest":"^29.5.0","@types/node":"^18.15.0","@typescript-eslint/eslint-plugin":"^5.57.0","@typescript-eslint/parser":"^5.57.0","eslint":"^8.37.0","jest":"^29.5.0","ts-jest":"^29.0.5","typescript":"^5.0.0"},"repository":{"type":"git","url":"git+https://github.com/bernierllc/tools.git","directory":"packages/validators/validators-retry-topology"},"publishConfig":{"access":"public"},"_id":"@bernierllc/validators-retry-topology@0.1.3","gitHead":"76d69d487488b6209814e45f12a830a06ff802b1","bugs":{"url":"https://github.com/bernierllc/tools/issues"},"homepage":"https://github.com/bernierllc/tools#readme","_nodeVersion":"24.4.1","_npmVersion":"11.4.2","dist":{"integrity":"sha512-XH2BKbu8i9m1CUl5KVUV1Va0P5FHIxTDnGIUbMibWUVVsfxcTe27Ihn//VNQrrkDkv3PuuBkjTLc2KT/tPKSfg==","shasum":"36ee2f0737f34e7222717ac19d834dcb38720754","tarball":"https://registry.npmjs.org/@bernierllc/validators-retry-topology/-/validators-retry-topology-0.1.3.tgz","fileCount":10,"unpackedSize":39218,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIG3WWvQoyfolZ5RuJYMegrmi0zyJIycNJkUvBUBnsKNFAiEA6Tn08o3DQm93oF3BZoB4pv1oMCf5YIDAeSomAXRLn+8="}]},"_npmUser":{"name":"mkbernier","email":"mkbernier@gmail.com"},"directories":{},"maintainers":[{"name":"alikhan410","email":"mczeyo@gmail.com"},{"name":"mkbernier","email":"mkbernier@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/validators-retry-topology_0.1.3_1760227924223_0.816398731979016"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-12T00:12:04.094Z","0.1.3":"2025-10-12T00:12:04.403Z","modified":"2025-10-12T00:12:04.794Z"},"maintainers":[{"name":"alikhan410","email":"mczeyo@gmail.com"},{"name":"mkbernier","email":"mkbernier@gmail.com"}],"description":"Retry topology validation - loops, backoff, dead-letter policy, and circuit breaker validation","homepage":"https://github.com/bernierllc/tools#readme","keywords":["validation","validators","retry","topology","backoff","circuit-breaker","dead-letter","workflow","reliability"],"repository":{"type":"git","url":"git+https://github.com/bernierllc/tools.git","directory":"packages/validators/validators-retry-topology"},"author":{"name":"Bernier LLC"},"bugs":{"url":"https://github.com/bernierllc/tools/issues"},"license":"UNLICENSED","readme":"# @bernierllc/validators-retry-topology\n\nRetry topology validation - loops, backoff, dead-letter policy, and circuit breaker validation for reliable systems.\n\n## Installation\n\n```bash\nnpm install @bernierllc/validators-retry-topology\n```\n\n## Overview\n\nThis package provides validators for retry configurations to ensure reliable and fault-tolerant systems. It validates:\n\n- **Infinite retry loop detection** - Ensures retry configurations have finite limits\n- **Backoff strategy validation** - Validates exponential backoff and delay configurations\n- **Max retry limits** - Ensures reasonable retry counts\n- **Dead letter queue requirements** - Enforces DLQ for high retry scenarios\n- **Circuit breaker validation** - Validates fault tolerance configurations\n- **Timeout validation** - Ensures reasonable timeout configurations\n\nPart of the BernierLLC validators ecosystem following MECE architecture principles.\n\n## Quick Start\n\n```typescript\nimport { validateRetryTopology } from '@bernierllc/validators-retry-topology';\n\nconst config = {\n  maxRetries: 3,\n  initialDelayMs: 1000,\n  maxDelayMs: 30000,\n  backoffFactor: 2,\n  jitter: true\n};\n\nconst problems = await validateRetryTopology(config);\n\nif (problems.length > 0) {\n  console.error('Validation errors:', problems);\n}\n```\n\n## API Reference\n\n### validateRetryTopology(config, options?)\n\nValidates a retry topology configuration and returns an array of problems found.\n\n**Parameters:**\n- `config: RetryTopologyConfig` - The retry configuration to validate\n- `options?: RetryTopologyValidationOptions` - Optional validation options\n\n**Returns:** `Promise<Problem[]>` - Array of validation problems\n\n### Configuration Types\n\n#### RetryTopologyConfig\n\n```typescript\ninterface RetryTopologyConfig {\n  maxRetries?: number;\n  initialDelayMs?: number;\n  maxDelayMs?: number;\n  backoffFactor?: number;\n  jitter?: boolean;\n  backoff?: BackoffConfig;\n  deadLetterQueue?: DeadLetterQueueConfig;\n  circuitBreaker?: CircuitBreakerConfig;\n  timeoutMs?: number;\n  totalTimeoutMs?: number;\n}\n```\n\n#### DeadLetterQueueConfig\n\n```typescript\ninterface DeadLetterQueueConfig {\n  enabled: boolean;\n  maxSize?: number;\n  handler?: string;\n  ttl?: number;\n}\n```\n\n#### CircuitBreakerConfig\n\n```typescript\ninterface CircuitBreakerConfig {\n  enabled: boolean;\n  failureThreshold: number;\n  failureWindowMs: number;\n  recoveryTimeoutMs: number;\n  successThreshold?: number;\n}\n```\n\n#### RetryTopologyValidationOptions\n\n```typescript\ninterface RetryTopologyValidationOptions {\n  maxAllowedRetries?: number; // Default: 10\n  minInitialDelayMs?: number; // Default: 100\n  maxTotalTimeoutMs?: number; // Default: 300000 (5 minutes)\n  requireDeadLetterQueue?: boolean; // Default: true\n  deadLetterQueueThreshold?: number; // Default: 5\n  requireCircuitBreaker?: boolean; // Default: true\n}\n```\n\n## Validation Rules\n\n### no-infinite-retries\n\nEnsures retry configurations have a finite maximum retry count.\n\n```typescript\n// Invalid - no maxRetries\nconst config = { initialDelayMs: 1000 };\n\n// Invalid - infinite retries\nconst config = { maxRetries: Infinity };\n\n// Valid\nconst config = { maxRetries: 3 };\n```\n\n### valid-backoff\n\nValidates backoff strategy configuration with reasonable delays.\n\n```typescript\n// Invalid - maxDelayMs < initialDelayMs\nconst config = {\n  initialDelayMs: 1000,\n  maxDelayMs: 500\n};\n\n// Valid\nconst config = {\n  initialDelayMs: 1000,\n  maxDelayMs: 30000,\n  backoffFactor: 2\n};\n```\n\n### reasonable-max-retries\n\nEnsures maxRetries is set to a reasonable value.\n\n```typescript\n// Warning - too many retries\nconst config = { maxRetries: 15 };\n\n// Valid\nconst config = { maxRetries: 5 };\n```\n\n### require-dead-letter-queue\n\nEnforces dead letter queue configuration for high retry counts.\n\n```typescript\n// Warning - high retries without DLQ\nconst config = { maxRetries: 8 };\n\n// Valid - high retries with DLQ\nconst config = {\n  maxRetries: 8,\n  deadLetterQueue: {\n    enabled: true,\n    handler: 'handleDeadLetter'\n  }\n};\n```\n\n### valid-circuit-breaker\n\nValidates circuit breaker configuration.\n\n```typescript\n// Invalid - zero threshold\nconst config = {\n  circuitBreaker: {\n    enabled: true,\n    failureThreshold: 0,\n    failureWindowMs: 60000,\n    recoveryTimeoutMs: 30000\n  }\n};\n\n// Valid\nconst config = {\n  circuitBreaker: {\n    enabled: true,\n    failureThreshold: 5,\n    failureWindowMs: 60000,\n    recoveryTimeoutMs: 30000\n  }\n};\n```\n\n### reasonable-total-timeout\n\nEnsures total timeout across all retries is reasonable.\n\n```typescript\n// Warning - timeout too high\nconst config = {\n  totalTimeoutMs: 400000 // > 5 minutes\n};\n\n// Valid\nconst config = {\n  timeoutMs: 5000,\n  totalTimeoutMs: 60000\n};\n```\n\n## Usage Examples\n\n### API Request Retry Configuration\n\n```typescript\nimport { validateRetryTopology } from '@bernierllc/validators-retry-topology';\n\nconst apiRetryConfig = {\n  maxRetries: 3,\n  initialDelayMs: 1000,\n  maxDelayMs: 30000,\n  backoffFactor: 2,\n  jitter: true,\n  timeoutMs: 5000,\n  circuitBreaker: {\n    enabled: true,\n    failureThreshold: 5,\n    failureWindowMs: 60000,\n    recoveryTimeoutMs: 30000,\n    successThreshold: 2\n  }\n};\n\nconst problems = await validateRetryTopology(apiRetryConfig);\nconsole.log('Validation results:', problems);\n```\n\n### Message Queue Retry Configuration\n\n```typescript\nconst queueRetryConfig = {\n  maxRetries: 5,\n  initialDelayMs: 500,\n  maxDelayMs: 60000,\n  backoffFactor: 2,\n  deadLetterQueue: {\n    enabled: true,\n    handler: 'processDeadLetterMessage',\n    maxSize: 10000,\n    ttl: 604800 // 7 days\n  }\n};\n\nconst problems = await validateRetryTopology(queueRetryConfig);\n```\n\n### Database Connection Retry Configuration\n\n```typescript\nconst dbRetryConfig = {\n  maxRetries: 10,\n  initialDelayMs: 2000,\n  maxDelayMs: 120000,\n  backoffFactor: 1.5,\n  jitter: true,\n  timeoutMs: 10000,\n  totalTimeoutMs: 300000,\n  circuitBreaker: {\n    enabled: true,\n    failureThreshold: 3,\n    failureWindowMs: 30000,\n    recoveryTimeoutMs: 60000\n  },\n  deadLetterQueue: {\n    enabled: true,\n    handler: 'notifyDatabaseFailure'\n  }\n};\n\nconst problems = await validateRetryTopology(dbRetryConfig);\n```\n\n### Custom Validation Options\n\n```typescript\nconst config = {\n  maxRetries: 4,\n  initialDelayMs: 1000\n};\n\nconst problems = await validateRetryTopology(config, {\n  maxAllowedRetries: 3,\n  deadLetterQueueThreshold: 3,\n  requireDeadLetterQueue: true\n});\n```\n\n### Using Individual Rules\n\n```typescript\nimport {\n  noInfiniteRetries,\n  validBackoffStrategy,\n  requireDeadLetterQueue\n} from '@bernierllc/validators-retry-topology';\nimport { createRuleContext } from '@bernierllc/validators-core';\n\nconst config = { maxRetries: 3 };\nconst context = createRuleContext('test', {}, defaultUtils);\n\nconst validator = noInfiniteRetries.create(context);\nvalidator(config);\n```\n\n### Using the Primitive Validator\n\n```typescript\nimport { retryTopologyValidator } from '@bernierllc/validators-retry-topology';\nimport { createRuleContext } from '@bernierllc/validators-core';\n\nconst config = {\n  maxRetries: 3,\n  initialDelayMs: 1000\n};\n\nconst context = createRuleContext('retry-topology', {}, defaultUtils);\nconst problems = await retryTopologyValidator.validate(config, context);\n```\n\n## Integration with Other Packages\n\n### With @bernierllc/retry-policy\n\n```typescript\nimport { validateRetryTopology } from '@bernierllc/validators-retry-topology';\nimport { RetryPolicy } from '@bernierllc/retry-policy';\n\nconst config = {\n  maxRetries: 3,\n  initialDelayMs: 1000,\n  backoffFactor: 2\n};\n\n// Validate before creating policy\nconst problems = await validateRetryTopology(config);\nif (problems.length === 0) {\n  const policy = new RetryPolicy(config);\n  // Use policy...\n}\n```\n\n### In CI/CD Pipelines\n\n```typescript\nimport { validateRetryTopology } from '@bernierllc/validators-retry-topology';\nimport * as fs from 'fs';\n\nconst config = JSON.parse(fs.readFileSync('retry-config.json', 'utf-8'));\nconst problems = await validateRetryTopology(config);\n\nif (problems.some(p => p.severity === 'error')) {\n  console.error('Retry configuration validation failed');\n  process.exit(1);\n}\n```\n\n## Best Practices\n\n1. **Always set maxRetries** - Prevent infinite retry loops\n2. **Use exponential backoff** - Set backoffFactor >= 2 for effective backoff\n3. **Add jitter** - Reduce thundering herd problems\n4. **Configure DLQ for high retries** - maxRetries >= 5 should have DLQ\n5. **Use circuit breakers** - Protect downstream services\n6. **Set reasonable timeouts** - Prevent resource exhaustion\n7. **Validate in CI** - Catch configuration issues early\n\n## Integration Status\n\n### Logger Integration\n**Status**: Not applicable\n\nThis package provides pure validation functions with no side effects. @bernierllc/logger integration is not applicable as validators don't perform logging - they return structured Problem objects that consumers can log as needed.\n\n### Docs-Suite Integration\n**Status**: Ready\n\nComplete TypeDoc documentation available. All types and functions are fully documented with examples.\n\n### NeverHub Integration\n**Status**: Not applicable\n\nAs a primitive validator following MECE principles, this package has no runtime dependencies or service discovery needs. @bernierllc/neverhub-adapter integration is not applicable - validators are pure functions that operate on configuration objects.\n\n## Dependencies\n\n- `@bernierllc/validators-core` - Core validation framework\n- `@bernierllc/retry-policy` - Retry configuration types\n\n## Quality Standards\n\n- 90%+ test coverage with real retry configurations\n- Zero linting errors\n- Strict TypeScript mode enabled\n- Comprehensive edge case handling\n\n## Security\n\nThis package performs validation only and does not execute any retry logic. It has no external network dependencies and processes only configuration objects. No sensitive data is stored or transmitted.\n\n**Security Considerations:**\n- Pure validation functions with no side effects\n- No external API calls or network requests\n- No file system access\n- No execution of user-provided code\n- Type-safe TypeScript implementation\n- Regular dependency audits with `npm audit`\n\nFor security issues, please contact: security@bernierllc.com\n\n## License\n\nCopyright (c) 2025 Bernier LLC. All rights reserved.\n\n## See Also\n\n- [@bernierllc/validators-core](../validators-core) - Core validation framework\n- [@bernierllc/retry-policy](../../core/retry-policy) - Retry policy implementation\n- [@bernierllc/validators-workflow-sla](../validators-workflow-sla) - Workflow SLA validation\n","readmeFilename":"README.md","_rev":"1-6a232ac642671767975e0df834bdc8bc"}