{"id":44724678,"url":"https://github.com/pjlamb12/ngx-circuit","last_synced_at":"2026-04-17T10:33:16.125Z","repository":{"id":338175647,"uuid":"1156789957","full_name":"pjlamb12/ngx-circuit","owner":"pjlamb12","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-15T01:20:36.000Z","size":556,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-15T03:14:07.261Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pjlamb12.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-13T03:49:39.000Z","updated_at":"2026-04-15T01:16:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pjlamb12/ngx-circuit","commit_stats":null,"previous_names":["pjlamb12/ngx-circuit"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pjlamb12/ngx-circuit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjlamb12%2Fngx-circuit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjlamb12%2Fngx-circuit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjlamb12%2Fngx-circuit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjlamb12%2Fngx-circuit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pjlamb12","download_url":"https://codeload.github.com/pjlamb12/ngx-circuit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjlamb12%2Fngx-circuit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31925504,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-17T10:19:20.377Z","status":"ssl_error","status_checked_at":"2026-04-17T10:19:18.682Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-15T17:00:26.109Z","updated_at":"2026-04-17T10:33:16.112Z","avatar_url":"https://github.com/pjlamb12.png","language":"TypeScript","funding_links":[],"categories":["Architecture and Advanced Topics"],"sub_categories":["Feature Flags"],"readme":"# ngx-circuit\n\nA powerful, type-safe feature flag library for Angular applications. `ngx-circuit` allows you to manage feature toggles with ease, supporting various strategies like boolean flags, time-based activation, percentage rollouts, user groups, environment contexts, and more.\n\n## Features\n\n- **Flexible Configuration**: Load flags from a static object or an HTTP endpoint.\n- **Advanced Flag Types**: Support for Boolean, Time-based, Percentage, Group, Environment, Device, and Composite flags.\n- **Type-Safe**: Built with TypeScript for excellent developer experience.\n- **Structural Directive**: Conditionally render templates using `*cktCircuit`.\n- **Route Guard**: Protect routes using `circuitGuard`.\n- **Reactive Service**: `CircuitService` uses Signals for reactive state management.\n- **Context Awareness**: Inject user/session context for advanced flag evaluation.\n\n## Installation\n\nInstall via npm:\n\n```bash\nnpm install ngx-circuit\n```\n\n## Configuration\n\n### 1. Providing Configuration\n\nYou can provide the configuration using `provideCircuitConfig` in your application config. The configuration can be a simple **static object** (ideal for key-value pairs or demo purposes) or a **URL** to load the configuration from a JSON file or API endpoint.\n\n**Option A: Static Object**\n\n```typescript\nimport { ApplicationConfig } from '@angular/core';\nimport { provideCircuitConfig } from 'ngx-circuit';\n\nexport const appConfig: ApplicationConfig = {\n  providers: [\n    provideCircuitConfig({\n      featureA: true,\n      featureB: false,\n    }),\n  ],\n};\n```\n\n**Option B: HTTP endpoint (Remote Configuration)**\n\nLoad configuration from a remote JSON file or API.\n\n```typescript\nimport { ApplicationConfig } from '@angular/core';\nimport { provideHttpClient } from '@angular/common/http';\nimport { provideRemoteCircuitConfig } from 'ngx-circuit';\n\nexport const appConfig: ApplicationConfig = {\n  providers: [\n    provideHttpClient(),\n    provideRemoteCircuitConfig('https://api.example.com/flags', {\n      apiKey: 'your-api-key', // Optional: value sent in x-api-key header\n    }),\n  ],\n};\n```\n\n### 2. Providing Context (Optional)\n\nFor advanced flags like Percentage, Group, or Device, you need to provide context about the current user/session.\n\n```typescript\nimport { ApplicationConfig } from '@angular/core';\nimport { provideCircuitConfig, provideCircuitContext } from 'ngx-circuit';\n\nexport const appConfig: ApplicationConfig = {\n  providers: [\n    provideCircuitConfig({ ... }),\n    provideCircuitContext({\n      userId: 'user-123',\n      sessionId: 'session-abc',\n      groups: ['beta-testers', 'admin'],\n      environment: 'production',\n      platform: 'mobile'\n    })\n    // Or providing a factory function:\n    // provideCircuitContext(() =\u003e ({ userId: localStorage.getItem('userId') }))\n  ],\n};\n```\n\n## Usage\n\n### 1. CircuitService\n\nInject `CircuitService` to check feature flags programmatically.\n\n```typescript\nimport { Component, inject } from '@angular/core';\nimport { CircuitService } from 'ngx-circuit';\n\n@Component({ ... })\nexport class MyComponent {\n  private circuit = inject(CircuitService);\n\n  checkFeature() {\n    if (this.circuit.isEnabled('newFeature')) {\n      // feature logic\n    }\n  }\n}\n```\n\n### 2. Structural Directive (\\*cktCircuit)\n\nConditionally render elements in your template.\n\n```html\n\u003cdiv *cktCircuit=\"'featureA'\"\u003eFeature A is enabled!\u003c/div\u003e\n\n\u003cdiv *cktCircuit=\"'featureB'; else fallback\"\u003eFeature B is enabled!\u003c/div\u003e\n\n\u003cng-template #fallback\u003e Feature B is disabled. \u003c/ng-template\u003e\n```\n\n### 3. Route Guard (circuitGuard)\n\nProtect routes based on feature flags.\n\n```typescript\nimport { Routes } from '@angular/router';\nimport { circuitGuard } from 'ngx-circuit';\n\nexport const routes: Routes = [\n  {\n    path: 'new-feature',\n    canActivate: [circuitGuard],\n    data: {\n      circuit: 'featureA', // Feature flag to check\n      circuitRedirectUrl: '/home', // Optional redirect if disabled\n    },\n    loadComponent: () =\u003e import('./...').then((m) =\u003e m.NewFeatureComponent),\n  },\n];\n```\n\n## Advanced Usage\n\n### 1. URL Overrides\n\nYou can override feature flags via URL query parameters for testing/QA. This must be explicitly enabled.\n\n```typescript\nproviders: [provideCircuitConfig(config, { enableUrlOverrides: true })];\n```\n\nThen append `?circuit=flagName:true,otherFlag:false` to your URL.\n\n### 2. Analytics Integration\n\nTrack when feature flags are evaluated to support A/B testing analytics.\n\n1. Implement `CircuitTracker`:\n\n```typescript\n@Injectable()\nexport class MyAnalyticsTracker implements CircuitTracker {\n  track(feature: string, enabled: boolean): void {\n    console.log(`Feature ${feature} evaluated to ${enabled}`);\n    // Send to Google Analytics, Mixpanel, etc.\n  }\n}\n```\n\n2. Provide it in your app config:\n\n```typescript\nproviders: [provideCircuitTracker(MyAnalyticsTracker)];\n```\n\n## Advanced Flag Types\n\nDefine complex rules in your configuration object.\n\n```typescript\nimport { CircuitType } from 'ngx-circuit';\n\nconst config = {\n  // Simple Boolean\n  basicFlag: true,\n\n  // Time-based: specific date range\n  promoFeature: {\n    type: CircuitType.TimeBased,\n    startDate: '2023-12-01',\n    endDate: '2023-12-31',\n  },\n\n  // Percentage Rollout: 20% of users\n  betaTest: {\n    type: CircuitType.Percentage,\n    percentage: 20,\n  },\n\n  // User Group\n  adminOnly: {\n    type: CircuitType.Group,\n    groups: ['admin'],\n  },\n\n  // Environment Specific\n  devTools: {\n    type: CircuitType.Environment,\n    environments: ['development', 'staging'],\n  },\n\n  // Device Specific\n  mobileView: {\n    type: CircuitType.Device,\n    devices: ['mobile', 'tablet'],\n  },\n\n  // Composite: ALL conditions must be met\n  complexFeature: {\n    type: CircuitType.Composite,\n    conditions: [\n      { type: CircuitType.Group, groups: ['beta-testers'] },\n      { type: CircuitType.TimeBased, startDate: '2024-01-01' },\n    ],\n  },\n};\n```\n\n## Circuit Breaker Management Dashboard\n\nThis repository includes a full-stack application for managing your feature flags (`circuit-breaker` frontend and `circuit-breaker-api` backend). You can self-host these applications to provide a management interface for your feature flags.\n\n### 1. Backend (`circuit-breaker-api`)\n\nA NestJS application that provides the API for managing flags, environments, and projects.\n\n**Requirements:**\n\n- PostgreSQL Database\n\n**Environment Variables:**\nCreate a `.env` file or set the following environment variables:\n\n```bash\nDB_HOST=localhost\nDB_PORT=5432\nDB_USERNAME=postgres\nDB_PASSWORD=password\nDB_NAME=circuit_breaker\n```\n\n**Running the API:**\n\n```bash\n# Development\nnpx nx serve circuit-breaker-api\n\n# Production Build\nnpx nx build circuit-breaker-api\n\n# Run Production Build\nnode dist/apps/circuit-breaker-api/main.js\n```\n\n### 2. Frontend (`circuit-breaker`)\n\nAn Angular application that provides the UI for the dashboard.\n\n**Configuration:**\nThe frontend loads its configuration from `assets/config.json`. You can modify this file to point to your API instance.\n\n```json\n{\n  \"apiBaseUrl\": \"http://localhost:3000/api\"\n}\n```\n\n**Running the Frontend:**\n\n```bash\n# Development\nnpx nx serve circuit-breaker\n\n# Production Build\nnpx nx build circuit-breaker\n```\n\n**Deployment:**\nThe build artifacts will be stored in the `dist/apps/circuit-breaker` directory. You can serve the static files from `dist/apps/circuit-breaker/browser` using any web server (e.g., Nginx, Apache, or a static file hosting service).\n\n### 3. Docker Support\n\nA `docker-compose.yml` file is included to quickly spin up a PostgreSQL database for local development.\n\n```bash\ndocker-compose up -d\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpjlamb12%2Fngx-circuit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpjlamb12%2Fngx-circuit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpjlamb12%2Fngx-circuit/lists"}