{"_id":"@asafarim/shared-logging","name":"@asafarim/shared-logging","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@asafarim/shared-logging","description":"A lightweight, environment-agnostic logging utility shared across all ASafariM applications.","version":"1.0.0","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc -p tsconfig.json"},"dependencies":{},"devDependencies":{"typescript":"^5.0.0","@types/node":"^20.0.0"},"keywords":["logging","shared","library"],"author":{"name":"Asafarim"},"license":"MIT","homepage":"https://github.com/AliSafari-IT/asafarim-dot-be/tree/main-dev/libs/shared-logging","repository":{"type":"git","url":"git+https://github.com/AliSafari-IT/asafarim-dot-be.git#main-dev"},"bugs":{"url":"https://github.com/AliSafari-IT/asafarim-dot-be/issues"},"funding":{"url":"https://github.com/sponsors/AliSafari-IT"},"private":false,"publishConfig":{"access":"public"},"packageManager":"pnpm@10.24.0","_id":"@asafarim/shared-logging@1.0.0","gitHead":"ad7174be8d7977d975c2184582a2d78e4c025fe8","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-CeSOym9Jq42tBjnjfurMK9wYjgU6IOMegEVgMAxk7QDD/s7DFucwKKU8QzbOc68NGS16HMVYJLMStH1l4cxcoQ==","shasum":"d265a414f74753f935c27100f5cd85bd22a52110","tarball":"https://registry.npmjs.org/@asafarim/shared-logging/-/shared-logging-1.0.0.tgz","fileCount":20,"unpackedSize":23917,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIC31ly25j9hWBYEDA2QiEpj4iT/DiIbNrIo0YvbifWOeAiBx1R82jMfz687PypyE7f/4hPrziYwc/CB9WwfTD2mcnA=="}]},"_npmUser":{"name":"asafarim.be","email":"asafarim.it@gmail.com"},"directories":{},"maintainers":[{"name":"asafarim.be","email":"asafarim.it@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/shared-logging_1.0.0_1765026910623_0.7156035971166461"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-06T13:15:10.514Z","1.0.0":"2025-12-06T13:15:10.784Z","modified":"2025-12-06T13:15:11.031Z"},"maintainers":[{"name":"asafarim.be","email":"asafarim.it@gmail.com"}],"description":"A lightweight, environment-agnostic logging utility shared across all ASafariM applications.","homepage":"https://github.com/AliSafari-IT/asafarim-dot-be/tree/main-dev/libs/shared-logging","keywords":["logging","shared","library"],"repository":{"type":"git","url":"git+https://github.com/AliSafari-IT/asafarim-dot-be.git#main-dev"},"author":{"name":"Asafarim"},"bugs":{"url":"https://github.com/AliSafari-IT/asafarim-dot-be/issues"},"license":"MIT","readme":"# 📘 **@asafarim/shared-logging — README.md**\r\n\r\nA lightweight, environment-agnostic logging utility shared across all ASafariM applications.\r\n\r\nThis package provides a **unified logging API** that works in:\r\n\r\n* Browser (React UI apps)\r\n* Node.js scripts and services\r\n* TestRunner\r\n* Future workers/CLI tools\r\n\r\nIt standardizes logging across the entire monorepo but **does not depend on Node-specific libraries** (like Winston).\r\nThis ensures maximum compatibility and keeps the library small and portable.\r\n\r\n---\r\n\r\n## 🚀 Features\r\n\r\n* Uniform log levels (`debug`, `info`, `warn`, `error`)\r\n* Environment-aware output:\r\n\r\n  * Browser → readable `console.log` output\r\n  * Node → structured JSON logs\r\n* Optional metadata object\r\n* Extendable by backend apps (e.g., TestRunner wraps it with Winston)\r\n* Zero external dependencies\r\n* Fully TypeScript typed\r\n\r\n---\r\n\r\n## 📦 Installation (monorepo workspace)\r\n\r\n```sh\r\npnpm add @asafarim/shared-logging\r\n```\r\n\r\nOr automatically linked when used via:\r\n\r\n```json\r\n\"@asafarim/shared-logging\": \"workspace:*\"\r\n```\r\n\r\n---\r\n\r\n# 📚 Usage\r\n\r\n---\r\n\r\n## 1. React UI (Browser)\r\n\r\n```ts\r\nimport { createLogger } from \"@asafarim/shared-logging\";\r\n\r\nconst logger = createLogger(\"projects-ui\", \"info\");\r\n\r\nlogger.info(\"Project page loaded\");\r\nlogger.debug(\"Fetching projects...\", { search: \"all\" });\r\nlogger.error(\"Failed to fetch project\", { status: 500 });\r\n```\r\n\r\n**Output example (browser):**\r\n\r\n```\r\n[2025-01-10T09:12:34.123Z] [INFO] Project page loaded\r\n```\r\n\r\n---\r\n\r\n## 2. Node Services (TestRunner, workers)\r\n\r\nBasic usage:\r\n\r\n```ts\r\nimport { createLogger } from \"@asafarim/shared-logging\";\r\n\r\nconst logger = createLogger(\"testrunner\", \"debug\");\r\n\r\nlogger.info(\"Starting test run\", { runId });\r\nlogger.debug(\"Fixture loaded\", { path: file });\r\nlogger.error(\"Test failed\", { error });\r\n```\r\n\r\n**Output example (Node JSON):**\r\n\r\n```json\r\n{\r\n  \"timestamp\": \"2025-01-10T09:12:34.123Z\",\r\n  \"level\": \"info\",\r\n  \"message\": \"Starting test run\",\r\n  \"context\": {\r\n    \"app\": \"testrunner\",\r\n    \"environment\": \"development\"\r\n  },\r\n  \"meta\": {\r\n    \"runId\": \"abc123\"\r\n  }\r\n}\r\n```\r\n\r\n---\r\n\r\n## 3. Extending shared logging with Winston (Recommended for TestRunner)\r\n\r\nIn TestRunner you can enhance logging:\r\n\r\n```ts\r\nimport { createLogger } from \"@asafarim/shared-logging\";\r\nimport * as winston from \"winston\";\r\n\r\nconst base = createLogger(\"testrunner\");\r\n\r\nconst win = winston.createLogger({\r\n  transports: [new winston.transports.Console()],\r\n});\r\n\r\nexport const logger = {\r\n  info(msg: string, meta?: any) {\r\n    base.info(msg, meta);\r\n    win.info(msg, meta);\r\n  },\r\n  error(msg: string, meta?: any) {\r\n    base.error(msg, meta);\r\n    win.error(msg, meta);\r\n  },\r\n  warn(msg: string, meta?: any) {\r\n    base.warn(msg, meta);\r\n    win.warn(msg, meta);\r\n  },\r\n  debug(msg: string, meta?: any) {\r\n    base.debug(msg, meta);\r\n    win.debug(msg, meta);\r\n  }\r\n};\r\n```\r\n\r\nThis keeps:\r\n\r\n* shared-logging → universal logging\r\n* winston → advanced Node-only features\r\n\r\n---\r\n\r\n## 4. .NET APIs (Serilog integration)\r\n\r\nThe shared logger does **not** replace Serilog.\r\nInstead, .NET APIs use a shared Serilog extension:\r\n\r\n```csharp\r\nbuilder.AddSharedSerilog(\"identity-api\");\r\napp.UseRequestLoggingWithCorrelation();\r\n```\r\n\r\nAnd inside controllers:\r\n\r\n```csharp\r\nSharedLogger.Info(\"User logged in\", new { userId });\r\nSharedLogger.Error(\"Login failed\", ex);\r\n```\r\n\r\n---\r\n\r\n# 🧱 API Reference\r\n\r\n---\r\n\r\n## `createLogger(appName: string, level?: LogLevel)`\r\n\r\nCreates a logger with default context.\r\n\r\n### **Parameters:**\r\n\r\n* `appName` → Name of the consuming app (projects-ui, testrunner, auth-ui, etc.)\r\n* `level` → Minimum log level (`debug`, `info`, `warn`, `error`)\r\n\r\n### **Returns:**\r\n\r\n```ts\r\nlogger.info(message, meta?)\r\nlogger.debug(message, meta?)\r\nlogger.warn(message, meta?)\r\nlogger.error(message, meta?)\r\n```\r\n\r\n---\r\n\r\n## 📌 Log Level Priority\r\n\r\n| Level   | Description                        |\r\n| ------- | ---------------------------------- |\r\n| `debug` | Developer details, verbose output  |\r\n| `info`  | Normal operation logs              |\r\n| `warn`  | Something unexpected but not fatal |\r\n| `error` | Errors and exceptions              |\r\n\r\n---\r\n\r\n# 🎯 Design Philosophy\r\n\r\n**Shared logging SHOULD NOT depend on:**\r\n\r\n* Winston\r\n* Pino\r\n* Serilog\r\n* Browser-specific APIs\r\n* Node-only APIs\r\n\r\nThis keeps the library:\r\n\r\n✔ portable\r\n✔ dependency-free\r\n✔ compatible with React, Node, .NET\r\n✔ safe for future microservices\r\n\r\nAny advanced logging backend (e.g. Winston) lives **inside the app**, not inside the shared library.\r\n\r\n---\r\n\r\n# 🛠 Roadmap\r\n\r\n* [ ] Correlation ID support (browser + Node)\r\n* [ ] Structured error normalization\r\n* [ ] Optional remote log collector adapter (Grafana Loki / ELK)\r\n* [ ] Shared log types for distributed tracing\r\n\r\n---\r\n\r\n# ❤️ Contributing\r\n\r\nAll monorepo apps should rely on this logger to guarantee:\r\n\r\n* unified log formatting\r\n* easy filtering in future log dashboards\r\n* consistent debugging experience\r\n\r\nTo contribute:\r\n\r\n```sh\r\ncd libs/shared-logging\r\npnpm build\r\n```\r\n","readmeFilename":"README.md","_rev":"1-013b888789301b82920ca30c69b87459"}