{"_id":"@molecule/app-logger","_rev":"3-d55d855904bc2602800bfad99e99dc68","name":"@molecule/app-logger","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@molecule/app-logger","version":"1.0.0","keywords":["molecule","logger","logging","console","debug"],"license":"Apache-2.0","_id":"@molecule/app-logger@1.0.0","maintainers":[{"name":"vialoh","email":"npm@vialoh.me"}],"homepage":"https://github.com/molecule-dev/molecule/tree/main/packages/app/core/logger","bugs":{"url":"https://github.com/molecule-dev/molecule/issues"},"dist":{"shasum":"ac6bed9d0183272346aba17b2155ec1afb42cae3","tarball":"https://registry.npmjs.org/@molecule/app-logger/-/app-logger-1.0.0.tgz","fileCount":22,"integrity":"sha512-b9TajnPUS6WcE+LIiUC576VlCFCgisTZX+/vDyQTGTXGNvf/XjcUX/L80bCcyztio0WTis/1D5c+oJ4xLmE70w==","signatures":[{"sig":"MEUCIQCPbNnDfDysUCyl8tfaT9oLg2iNlRVND4I1e4ozC+TIVgIgNN1ANsUG0m58bwd5tCIQ3E40kXGKkka013R12m4EMj0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":47246},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"92623e72a527ca467963169420f4cf07533e4699","scripts":{"test":"vitest run","build":"tsc","test:watch":"vitest"},"_npmUser":{"name":"vialoh","email":"npm@vialoh.me"},"repository":{"url":"git+https://github.com/molecule-dev/molecule.git","type":"git","directory":"packages/app/core/logger"},"_npmVersion":"11.12.1","description":"Frontend logging interface for molecule.dev","directories":{},"_nodeVersion":"25.9.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"4.1.10","typescript":"6.0.3","@types/node":"26.1.2","@molecule/app-bond":"1.0.0"},"peerDependencies":{"@molecule/app-bond":"^1.0.0"},"_npmOperationalInternal":{"tmp":"tmp/app-logger_1.0.0_1785796141697_0.9133553676249782","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@molecule/app-logger","version":"1.0.1","keywords":["molecule","logger","logging","console","debug"],"license":"Apache-2.0","_id":"@molecule/app-logger@1.0.1","maintainers":[{"name":"vialoh","email":"npm@vialoh.me"}],"homepage":"https://github.com/molecule-dev/molecule/tree/main/packages/app/core/logger","bugs":{"url":"https://github.com/molecule-dev/molecule/issues"},"dist":{"shasum":"71e926f4d1bbdc9352a688d8112041fc61f7e792","tarball":"https://registry.npmjs.org/@molecule/app-logger/-/app-logger-1.0.1.tgz","fileCount":23,"integrity":"sha512-1qHUqIXP0kd5zyFSvmmYsyCl2KLG6xhsAVCsN7XNNJ8YmB4EIyfV0HD9O1dvx/YsxG1t6nqtmfGW51nZFZjNtg==","signatures":[{"sig":"MEYCIQDHfiYbFAOadx1Ya/ievj6MQvvwl8HucPj6JTmjoX9KNQIhAM1v2wm6+rFdmLwtMOPpOHLcHXHagoeG8dzs6df/Qq/B","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@molecule%2fapp-logger@1.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":58446},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"8621216fd4c8c9abe863e4e4f41efd2bc866fb09","scripts":{"test":"vitest run","build":"tsc","test:watch":"vitest"},"_npmUser":{"name":"vialoh","email":"npm@vialoh.me"},"repository":{"url":"git+https://github.com/molecule-dev/molecule.git","type":"git","directory":"packages/app/core/logger"},"_npmVersion":"12.0.2","description":"Frontend logging interface for molecule.dev","directories":{},"_nodeVersion":"22.23.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"4.1.10","typescript":"6.0.3","@types/node":"26.1.2","@molecule/app-bond":"1.0.1"},"peerDependencies":{"@molecule/app-bond":"^1.0.1"},"_npmOperationalInternal":{"tmp":"tmp/app-logger_1.0.1_1785827255206_0.3600496258793173","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"_id":"@molecule/app-logger@1.0.2","bugs":{"url":"https://github.com/molecule-dev/molecule/issues"},"dist":{"shasum":"c769f171ae9ab43dc3d595cfd3c8b99df0844674","tarball":"https://registry.npmjs.org/@molecule/app-logger/-/app-logger-1.0.2.tgz","fileCount":23,"integrity":"sha512-/zr5YjuTSpq8xj7GgL7fe0/6UkeGCqmaSIHl1ZTqlUGq5s03KCexnmk4xUmy4S77ZCHGG7xokx4HIPWguDbIHQ==","signatures":[{"sig":"MEUCIEe7KuEFoA0J7gkHg7J/fIdbMmUDV7xIiFtCjetalh0qAiEApZZntvtu0CFUaRv0AmKivjpbDfJt1uLHZsGpWGkKqtw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAm9rcYxy06b7uC9Rg63r3oemAjSRwORV9m26mBMtJxxAiBJq8g1iF70Nby8XEdD9OLiVBGkmMKx9cib4dIVnzSTrg=="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@molecule%2fapp-logger@1.0.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":58415},"main":"dist/index.js","name":"@molecule/app-logger","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"41bbb7d6c46b04d052a6b333e1b18e76ed007d23","license":"Apache-2.0","scripts":{"test":"vitest run","build":"tsc","test:watch":"vitest"},"version":"1.0.2","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:2f943bf4-9dbf-4dc5-809f-d788ee56ded7"}},"homepage":"https://www.molecule.dev/packages/app-logger","keywords":["molecule","logger","logging","console","debug"],"repository":{"url":"git+https://github.com/molecule-dev/molecule.git","type":"git","directory":"packages/app/core/logger"},"_npmVersion":"12.0.2","description":"Frontend logging interface for molecule.dev","directories":{},"maintainers":[{"name":"vialoh","email":"npm@vialoh.me"}],"_nodeVersion":"22.23.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"4.1.11","typescript":"6.0.3","@types/node":"26.1.2","@molecule/app-bond":"1.0.2"},"peerDependencies":{"@molecule/app-bond":"^1.0.1"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/app-logger_1.0.2_1789914526249_0.7757000938491703"}}},"time":{"created":"2026-08-03T22:29:01.508Z","modified":"2026-09-20T14:28:46.650Z","1.0.0":"2026-08-03T22:29:01.841Z","1.0.1":"2026-08-04T07:07:35.341Z","1.0.2":"2026-09-20T14:28:46.348Z"},"bugs":{"url":"https://github.com/molecule-dev/molecule/issues"},"license":"Apache-2.0","homepage":"https://www.molecule.dev/packages/app-logger","keywords":["molecule","logger","logging","console","debug"],"repository":{"url":"git+https://github.com/molecule-dev/molecule.git","type":"git","directory":"packages/app/core/logger"},"description":"Frontend logging interface for molecule.dev","maintainers":[{"name":"vialoh","email":"npm@vialoh.me"}],"readme":"<!--\nAUTO-GENERATED — DO NOT EDIT THIS FILE.\nGenerated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.\nEdits here are overwritten on the next commit (molecule's pre-commit hook regenerates).\nTo change this document, edit the module-level JSDoc in src/index.ts.\nGenerated: 2026-08-04T01:52:03.789Z\n-->\n\n# @molecule/app-logger\n\n> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.\n> It is written to be read by coding agents as much as by people, and is generated from this\n> package's source — edit `src/index.ts` JSDoc, not this file.\n\nFrontend logging interface for molecule.dev.\n\nProvides a unified logging API that can be backed by different\nimplementations (console, loglevel, remote logging, etc.). Works with ZERO\nwiring: on first use a console-backed provider is auto-bonded (level\n`'debug'` in development, `'info'` otherwise) — call {@link setProvider}\nonly to swap in a custom provider.\n\n## Quick Start\n\n```typescript\nimport { createLogger, error, warn } from '@molecule/app-logger'\n\nwarn('cache miss', { key }) // root logger — no setup needed\nerror(err) // error() accepts an Error directly\n\nconst log = createLogger('sync') // named/namespaced logger\nlog.debug('starting', { count })\n```\n\n## Type\n\n`core`\n\n## Installation\n\n```bash\nnpm install @molecule/app-logger @molecule/app-bond\n```\n\n## API\n\n### Interfaces\n\n#### `LogEntry`\n\nStructured log entry passed to transports, containing the level, message, timestamp, and optional context.\n\n```typescript\ninterface LogEntry {\n  /**\n   * Log level.\n   */\n  level: Exclude<LogLevel, 'silent'>\n\n  /**\n   * Log message.\n   */\n  message: string\n\n  /**\n   * Additional arguments.\n   */\n  args: unknown[]\n\n  /**\n   * Timestamp.\n   */\n  timestamp: Date\n\n  /**\n   * Logger name/namespace.\n   */\n  logger?: string\n\n  /**\n   * Additional context.\n   */\n  context?: Record<string, unknown>\n}\n```\n\n#### `Logger`\n\nLogger instance with leveled logging methods, child logger creation,\nand transport management.\n\n```typescript\ninterface Logger {\n  /**\n   * Logs a trace message.\n   */\n  trace(message: string, ...args: unknown[]): void\n\n  /**\n   * Logs a debug message.\n   */\n  debug(message: string, ...args: unknown[]): void\n\n  /**\n   * Logs an info message.\n   */\n  info(message: string, ...args: unknown[]): void\n\n  /**\n   * Logs a warning message.\n   */\n  warn(message: string, ...args: unknown[]): void\n\n  /**\n   * Logs an error message.\n   */\n  error(message: string | Error, ...args: unknown[]): void\n\n  /**\n   * Sets the log level.\n   */\n  setLevel(level: LogLevel): void\n\n  /**\n   * Gets the current log level.\n   */\n  getLevel(): LogLevel\n\n  /**\n   * Creates a child logger with a namespace.\n   */\n  child(name: string, context?: Record<string, unknown>): Logger\n\n  /**\n   * Adds additional context to the logger.\n   */\n  withContext(context: Record<string, unknown>): Logger\n\n  /**\n   * Adds a transport.\n   */\n  addTransport(transport: LogTransport): () => void\n\n  /**\n   * Removes a transport.\n   */\n  removeTransport(transport: LogTransport): void\n}\n```\n\n#### `LoggerConfig`\n\nConfiguration for creating a logger instance.\n\n```typescript\ninterface LoggerConfig {\n  /**\n   * Minimum log level.\n   */\n  level?: LogLevel\n\n  /**\n   * Logger name/namespace.\n   */\n  name?: string\n\n  /**\n   * Additional transports (remote logging, file, etc.).\n   */\n  transports?: LogTransport[]\n\n  /**\n   * Whether to include timestamps in console output.\n   */\n  timestamps?: boolean\n\n  /**\n   * Custom log format function.\n   */\n  format?: (entry: LogEntry) => string\n\n  /**\n   * Default context to include with all logs.\n   */\n  context?: Record<string, unknown>\n}\n```\n\n#### `LoggerProvider`\n\nLogger provider interface that all logger bond packages must implement.\nCreates and manages logger instances and global log configuration.\n\n```typescript\ninterface LoggerProvider {\n  /**\n   * Gets a logger by name, or the root logger if no name given.\n   */\n  getLogger(name?: string): Logger\n\n  /**\n   * Creates a named logger.\n   */\n  createLogger(nameOrConfig: string | LoggerConfig, config?: LoggerConfig): Logger\n\n  /**\n   * Sets the global log level.\n   */\n  setLevel(level: LogLevel): void\n\n  /**\n   * Gets the global log level.\n   */\n  getLevel(): LogLevel\n\n  /**\n   * Adds a global transport.\n   */\n  addTransport(transport: LogTransport): () => void\n\n  /**\n   * Enables logging.\n   */\n  enable(): void\n\n  /**\n   * Disables logging.\n   */\n  disable(): void\n\n  /**\n   * Checks if logging is enabled.\n   *\n   * @returns `true` if logging is currently enabled.\n   */\n  isEnabled(): boolean\n}\n```\n\n### Types\n\n#### `LogLevel`\n\nAvailable log severity levels, ordered from most verbose (trace) to silent.\n\n```typescript\ntype LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent'\n```\n\n#### `LogTransport`\n\nLog transport function. Receives each log entry for custom\nprocessing (e.g. remote logging, file output, error tracking).\n\n```typescript\ntype LogTransport = (entry: LogEntry) => void\n```\n\n### Functions\n\n#### `createConsoleLogger(config)`\n\nCreates a console-based logger that outputs to `console.*` methods\nand dispatches entries to registered transports.\n\n```typescript\nfunction createConsoleLogger(config?: LoggerConfig): Logger\n```\n\n- `config` — Logger configuration (level, name, transports, format).\n\n**Returns:** A `Logger` instance backed by the browser/Node console.\n\n#### `createConsoleLoggerProvider(defaultLevel)`\n\nCreates a console-based logger provider with configurable log level,\nnamed child loggers, and pluggable transports.\n\n```typescript\nfunction createConsoleLoggerProvider(defaultLevel?: LogLevel): LoggerProvider\n```\n\n- `defaultLevel` — The initial global log level (defaults to `'info'`).\n\n**Returns:** A `LoggerProvider` backed by console output.\n\n#### `createLogger(nameOrConfig, config)`\n\nCreates a named logger with optional configuration via the bonded provider.\n\n```typescript\nfunction createLogger(nameOrConfig: string | LoggerConfig, config?: LoggerConfig): Logger\n```\n\n- `nameOrConfig` — The logger name string, or a full `LoggerConfig` object.\n- `config` — Optional configuration when the first argument is a name string.\n\n**Returns:** A new named logger instance.\n\n#### `createRemoteTransport(options)`\n\nCreates a remote logging transport that batches log entries and\nsends them to a remote endpoint via HTTP POST.\n\n```typescript\nfunction createRemoteTransport(options: {\n  url: string\n  minLevel?: LogLevel\n  batchSize?: number\n  flushInterval?: number\n  headers?: Record<string, string>\n}): LogTransport\n```\n\n- `options` — Transport configuration.\n- `options.url` — The remote endpoint URL to POST log batches to.\n- `options.minLevel` — Minimum log level to send (default: `'warn'`).\n- `options.batchSize` — Number of entries to buffer before flushing (default: 10).\n- `options.flushInterval` — Milliseconds between automatic flushes (default: 5000).\n- `options.headers` — Additional HTTP headers for the POST request.\n\n**Returns:** A `LogTransport` function that buffers and sends entries.\n\n#### `debug(message, args)`\n\nLogs a debug-level message via the root logger.\n\n```typescript\nfunction debug(message: string, args?: unknown[]): void\n```\n\n- `message` — The log message string.\n- `args` — Additional arguments to include in the log entry.\n\n**Returns:** Nothing.\n\n#### `defaultFormat(entry)`\n\nDefault log format: `\"ISO_TIMESTAMP LEVEL[name]: message\"`.\n\n```typescript\nfunction defaultFormat(entry: LogEntry): string\n```\n\n- `entry` — The log entry to format.\n\n**Returns:** The formatted log string.\n\n#### `error(message, args)`\n\nLogs an error-level message via the root logger.\n\n```typescript\nfunction error(message: string | Error, args?: unknown[]): void\n```\n\n- `message` — The error message string or Error object.\n- `args` — Additional arguments to include in the log entry.\n\n**Returns:** Nothing.\n\n#### `getLevel()`\n\nReturns the current global log level from the bonded provider.\n\n```typescript\nfunction getLevel(): LogLevel\n```\n\n**Returns:** The active log level.\n\n#### `getLogger(name)`\n\nRetrieves a logger by name from the bonded provider. Returns the root\nlogger if no name is given.\n\n```typescript\nfunction getLogger(name?: string): Logger\n```\n\n- `name` — Optional logger name for scoped logging.\n\n**Returns:** The named or root logger.\n\n#### `getProvider()`\n\nRetrieves the bonded logger provider. If none is bonded, automatically\ncreates and bonds a console-based provider with log level auto-detected\nfrom `NODE_ENV` (`'debug'` in development, `'info'` otherwise).\n\n```typescript\nfunction getProvider(): LoggerProvider\n```\n\n**Returns:** The active logger provider.\n\n#### `info(message, args)`\n\nLogs an info-level message via the root logger.\n\n```typescript\nfunction info(message: string, args?: unknown[]): void\n```\n\n- `message` — The log message string.\n- `args` — Additional arguments to include in the log entry.\n\n**Returns:** Nothing.\n\n#### `setLevel(level)`\n\nSets the global log level on the bonded provider, affecting all loggers.\n\n```typescript\nfunction setLevel(level: LogLevel): void\n```\n\n- `level` — The log level to set (`'trace'`, `'debug'`, `'info'`, `'warn'`, `'error'`, or `'silent'`).\n\n**Returns:** Nothing.\n\n#### `setProvider(provider)`\n\nRegisters a logger provider as the active singleton.\n\n```typescript\nfunction setProvider(provider: LoggerProvider): void\n```\n\n- `provider` — The logger provider implementation to bond.\n\n#### `trace(message, args)`\n\nLogs a trace-level message via the root logger.\n\n```typescript\nfunction trace(message: string, args?: unknown[]): void\n```\n\n- `message` — The log message string.\n- `args` — Additional arguments to include in the log entry.\n\n**Returns:** Nothing.\n\n#### `warn(message, args)`\n\nLogs a warn-level message via the root logger.\n\n```typescript\nfunction warn(message: string, args?: unknown[]): void\n```\n\n- `message` — The log message string.\n- `args` — Additional arguments to include in the log entry.\n\n**Returns:** Nothing.\n\n### Constants\n\n#### `LOG_LEVEL_PRIORITY`\n\nLog level priority (lower = more verbose).\n\n```typescript\nconst LOG_LEVEL_PRIORITY: Record<LogLevel, number>\n```\n\n## Injection Notes\n\n### Requirements\n\nPeer dependencies:\n\n- `@molecule/app-bond` ^1.0.1\n\n### Runtime Dependencies\n\n- `@molecule/app-bond`\n\n- **Log through this API, never bare `console.log`** — levels, namespaces,\n  and transports (remote error tracking) only apply to entries that flow\n  through the logger. Every caught error is logged WITH the error object\n  attached (or re-thrown) — never swallowed silently.\n- **`getLogger('name')` does NOT create a logger** — it returns the ROOT\n  logger unless `createLogger('name')` registered that name first. Create\n  named loggers explicitly.\n- **Never log secrets, tokens, or PII.** Entries reach the browser console\n  and every registered transport — {@link createRemoteTransport} batches\n  them to a remote HTTP endpoint, so a logged credential leaves the device.\n- Remote delivery is best-effort by design (a failing transport is dropped\n  silently to avoid log-failure recursion) — don't rely on transports for\n  audit-grade trails.\n","readmeFilename":"README.md"}