{"_id":"@abdokouta/react-application","name":"@abdokouta/react-application","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@abdokouta/react-application","version":"0.0.1","description":"Application kernel for orchestrating @abdokouta packages with boot lifecycle, dependency ordering, and cross-package communication","license":"MIT","author":{"name":"Abdelrhman Kouta","email":"abdelrhman@pixielity.com","url":"https://github.com/abdokouta"},"repository":{"type":"git","url":"git+https://github.com/abdokouta/ui.git","directory":"packages/application"},"bugs":{"url":"https://github.com/abdokouta/ui/issues"},"homepage":"https://github.com/abdokouta/ui/tree/main/packages/application#readme","keywords":["application","kernel","bootstrap","orchestration","lifecycle","modules","packages","dependency-injection","react","abdokouta"],"type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","scripts":{"build":"tsup","dev":"tsup --watch","clean":"rm -rf dist node_modules/.cache","typecheck":"tsc --noEmit","lint":"eslint . --max-warnings 0","lint:fix":"eslint . --fix","format":"prettier --write .","format:check":"prettier --check .","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"pnpm run build","release":"pnpm publish --access public --no-git-checks"},"dependencies":{"@abdokouta/react-di":"^2.1.3","reflect-metadata":"^0.2.2"},"peerDependencies":{"react":"^18.0.0 || ^19.0.0"},"peerDependenciesMeta":{"react":{"optional":true}},"devDependencies":{"@eslint/js":"10.0.1","@nesvel/eslint-config":"^1.0.5","@nesvel/prettier-config":"^1.0.3","@nesvel/tsup-config":"^1.0.3","@nesvel/typescript-config":"^1.0.4","@testing-library/jest-dom":"^6.9.1","@testing-library/react":"^16.3.2","@types/node":"^25.5.0","@types/react":"^19.2.14","@vitest/ui":"^4.1.2","inversiland":"^0.6.2","jsdom":"^29.0.1","prettier":"^3.8.1","react":"^19.2.4","tsup":"^8.5.1","typescript":"^6.0.2","typescript-eslint":"^8.58.0","vitest":"^4.1.2"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"engines":{"node":">=18.0.0","pnpm":">=9.0.0"},"sideEffects":false,"_id":"@abdokouta/react-application@0.0.1","gitHead":"84f03582f76c98ff36dacbe9f7473d84c9860824","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-0PRrp0v9GoydTtqXASZLG9wjuuR1jvBkD+GcsHvdLBhbtgR5FN/q1HdUML+U/OThAZl1JnvwGS/HBeJmzWFQYg==","shasum":"aab1bc3ce287acbcb1a43b71d15fe1ebd5a00dd3","tarball":"https://registry.npmjs.org/@abdokouta/react-application/-/react-application-0.0.1.tgz","fileCount":8,"unpackedSize":399910,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD4ncGjFzGZUsV/L+XjG1F/ndDVvPfHi4S/PjUND89weQIgZr3+o0/n3ojTmgCXzbtwlSN6sL9N0Bw0cx7NGcX0ZtM="}]},"_npmUser":{"name":"abdokouta","email":"akouta66@gmail.com"},"directories":{},"maintainers":[{"name":"abdokouta","email":"akouta66@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/react-application_0.0.1_1775087138470_0.21710709316870158"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-01T23:45:38.402Z","0.0.1":"2026-04-01T23:45:38.619Z","modified":"2026-04-01T23:45:38.807Z"},"maintainers":[{"name":"abdokouta","email":"akouta66@gmail.com"}],"description":"Application kernel for orchestrating @abdokouta packages with boot lifecycle, dependency ordering, and cross-package communication","homepage":"https://github.com/abdokouta/ui/tree/main/packages/application#readme","keywords":["application","kernel","bootstrap","orchestration","lifecycle","modules","packages","dependency-injection","react","abdokouta"],"repository":{"type":"git","url":"git+https://github.com/abdokouta/ui.git","directory":"packages/application"},"author":{"name":"Abdelrhman Kouta","email":"abdelrhman@pixielity.com","url":"https://github.com/abdokouta"},"bugs":{"url":"https://github.com/abdokouta/ui/issues"},"license":"MIT","readme":"# @abdokouta/application\n\nApplication kernel for orchestrating @abdokouta packages with boot lifecycle, dependency ordering, and cross-package communication.\n\n## Features\n\n- 🚀 **Fluent Builder API** - Chain package registration with `.use()`\n- 📦 **Automatic Dependency Resolution** - Topological sort ensures correct boot order\n- 🔄 **Lifecycle Hooks** - `onBoot()`, `onReady()`, `onShutdown()` for each package\n- 📡 **Event System** - Monitor boot progress with typed events\n- ⚛️ **React Integration** - Provider and hooks for component access\n- 💉 **DI Container** - Seamless integration with `@abdokouta/react-di`\n\n## Installation\n\n```bash\npnpm add @abdokouta/application\n```\n\n## Quick Start\n\n### 1. Create and Boot the Application\n\n```typescript\n// main.tsx\nimport \"reflect-metadata\";\nimport { Application, ApplicationProvider } from \"@abdokouta/application\";\nimport { AuthPackage } from \"@abdokouta/auth\";\nimport { RefinePackage } from \"@abdokouta/refine\";\n\n// Create and boot BEFORE React renders\nconst app = Application.create({\n  name: \"MNGO Platform\",\n  logLevel: import.meta.env.DEV ? \"debug\" : \"info\",\n})\n  .use(AuthPackage.forRoot({ session: { lockAfterSeconds: 900 } }))\n  .use(RefinePackage.forRoot({ dataProvider: myDataProvider }))\n  .boot();\n\n// Wrap React with the provider\nReactDOM.createRoot(root).render(\n  <ApplicationProvider app={app}>\n    <BrowserRouter>\n      <App />\n    </BrowserRouter>\n  </ApplicationProvider>\n);\n```\n\n### 2. Access in Components\n\n```tsx\nimport { useApplication, usePackage, useBootPhase } from \"@abdokouta/application\";\nimport { useInject } from \"@abdokouta/react-di\";\n\nfunction MyComponent() {\n  // Access the Application\n  const { app } = useApplication();\n\n  // Check boot phase\n  const phase = useBootPhase();\n\n  // Get package info\n  const { isBooted, version } = usePackage(\"@abdokouta/auth\");\n\n  // Inject services (from @abdokouta/react-di)\n  const sessionService = useInject(SessionService);\n\n  return (\n    <div>\n      <p>Phase: {phase}</p>\n      <p>\n        Auth v{version}: {isBooted ? \"Ready\" : \"Loading\"}\n      </p>\n    </div>\n  );\n}\n```\n\n## Creating a Package\n\nPackages can participate in the Application lifecycle by implementing the `IBootable` interface:\n\n```typescript\n// packages/my-package/src/my-package.package.ts\nimport {\n  Package,\n  IBootable,\n  IPackageRegistration,\n  Application,\n} from \"@abdokouta/application\";\nimport { MyModule } from \"./my.module\";\n\n@Package({\n  name: \"@abdokouta/my-package\",\n  version: \"1.0.0\",\n  dependencies: [\"@abdokouta/react-di\"],\n})\nexport class MyPackage implements IBootable {\n  private options: MyOptions;\n\n  constructor(options: MyOptions = {}) {\n    this.options = options;\n  }\n\n  /**\n   * Factory method for registration\n   */\n  static forRoot(options?: MyOptions): IPackageRegistration {\n    return {\n      manifest: {\n        name: \"@abdokouta/my-package\",\n        version: \"1.0.0\",\n        dependencies: [\"@abdokouta/react-di\"],\n        module: MyModule,\n      },\n      dynamicModule: MyModule.forRoot(options),\n      bootable: new MyPackage(options),\n    };\n  }\n\n  /**\n   * Called when the package is being initialized.\n   * Other packages may not be ready yet.\n   */\n  onBoot(app: Application): void {\n    // Register built-in components\n    myRegistry.register(\"default\", DefaultComponent);\n    console.log(\"[MyPackage] Booted\");\n  }\n\n  /**\n   * Called after ALL packages have booted.\n   * Safe to resolve cross-package dependencies.\n   */\n  onReady(app: Application): void {\n    // Access services from other packages\n    const authConfig = app.resolve(AUTH_MODULE_CONFIG);\n    console.log(\"[MyPackage] Ready\");\n  }\n\n  /**\n   * Called when the application is shutting down.\n   */\n  onShutdown(app: Application): void {\n    // Cleanup resources\n    console.log(\"[MyPackage] Shutdown\");\n  }\n}\n```\n\n## API Reference\n\n### Application\n\n#### `Application.create(options?)`\n\nCreates a new Application instance.\n\n```typescript\nconst app = Application.create({\n  name: \"My App\", // Display name for logging\n  version: \"1.0.0\", // App version\n  logLevel: \"debug\", // 'none' | 'info' | 'debug'\n  defaultScope: \"Singleton\", // DI scope\n  strict: true, // Throw on errors\n  bootTimeout: 30000, // Timeout for async operations\n  onError: (error, pkg) => {}, // Error handler\n});\n```\n\n#### `.use(registration)`\n\nRegister a package.\n\n```typescript\napp.use(AuthPackage.forRoot({ ... }));\n```\n\n#### `.on(event, callback)`\n\nSubscribe to lifecycle events.\n\n```typescript\napp.on(\"packageBooted\", ({ manifest, duration }) => {\n  console.log(`${manifest.name} booted in ${duration}ms`);\n});\n```\n\n#### `.boot()`\n\nBoot the application. Must be called before React renders.\n\n```typescript\napp.boot();\n```\n\n#### `.resolve(identifier)`\n\nResolve a service from the DI container.\n\n```typescript\nconst service = app.resolve(MyService);\nconst config = app.resolve(MY_CONFIG_TOKEN);\n```\n\n#### `.shutdown(reason?)`\n\nShutdown the application gracefully.\n\n```typescript\nawait app.shutdown(\"User logged out\");\n```\n\n### Hooks\n\n#### `useApplication()`\n\nAccess the Application instance.\n\n```tsx\nconst { app } = useApplication();\n```\n\n#### `useBootPhase()`\n\nGet the current boot phase.\n\n```tsx\nconst phase = useBootPhase();\n// BootPhase.READY\n```\n\n#### `usePackage(name)`\n\nGet information about a registered package.\n\n```tsx\nconst { isBooted, version, bootDuration } = usePackage(\"@abdokouta/auth\");\n```\n\n### Events\n\n| Event               | Payload                                    | Description                   |\n| ------------------- | ------------------------------------------ | ----------------------------- |\n| `phaseChange`       | `{ from, to, timestamp }`                  | Boot phase changed            |\n| `packageRegistered` | `{ manifest, totalRegistered }`            | Package registered            |\n| `packageBooting`    | `{ manifest, order, total }`               | Package starting to boot      |\n| `packageBooted`     | `{ manifest, duration }`                   | Package finished booting      |\n| `packageFailed`     | `{ manifest, error }`                      | Package failed to boot        |\n| `ready`             | `{ totalPackages, totalDuration }`         | All packages ready            |\n| `shuttingDown`      | `{ reason? }`                              | Shutdown started              |\n| `terminated`        | `{ duration }`                             | Shutdown complete             |\n| `error`             | `{ error, phase, packageName? }`           | Error occurred                |\n\n### Boot Phases\n\n```typescript\nenum BootPhase {\n  IDLE = \"idle\", // Initial state\n  REGISTERING = \"registering\", // Packages being registered\n  RESOLVING = \"resolving\", // Dependency graph being resolved\n  BOOTING = \"booting\", // Packages executing onBoot()\n  READY = \"ready\", // All packages ready\n  SHUTTING_DOWN = \"shutting_down\", // Shutdown in progress\n  TERMINATED = \"terminated\", // Shutdown complete\n}\n```\n\n## Dependency Resolution\n\nThe Application automatically resolves package dependencies using topological sort:\n\n```typescript\n// These can be registered in any order\napp\n  .use(AuthPackage.forRoot()) // depends on: ['@abdokouta/react-di']\n  .use(RefinePackage.forRoot()) // depends on: ['@abdokouta/react-di']\n  .use(TenantPackage.forRoot()) // depends on: ['@abdokouta/auth']\n  .boot();\n\n// Boot order will be:\n// 1. @abdokouta/react-di (no deps)\n// 2. @abdokouta/auth (depends on react-di)\n// 3. @abdokouta/refine (depends on react-di)\n// 4. @abdokouta/tenant (depends on auth)\n```\n\nCircular dependencies are detected and throw an error:\n\n```\nDependencyResolverError: Circular dependency detected: A → B → C → A\n```\n\n## License\n\nMIT © [Abdo Kouta](https://github.com/abdokouta)\n","readmeFilename":"README.md","_rev":"1-24f0db304802310cd90d9d9add38c8d9"}