Polyglot Logger (Node.js / TypeScript)

Idiomatic Node/TypeScript bindings (@polyglot/logger) for the Polyglot native structured logger.

Part of the Polyglot modular monorepo — see polyglot-go for the core Go implementation and other language bindings.

Quick Start

import { Logger, Level } from "@polyglot/logger";

const log = new Logger({
  service: "checkout-api",
  environment: "prod",
  filePath: "/var/log/checkout.log",
});

log.setFields({ traceId: "abc" });
log.info("checkout started", { cartId: "c-1" });
log.logSimple(Level.ERROR, "payment declined");
console.log(log.stats());
log.close();

Features

• ✅ Auto-initialization: Place polyglot.yaml in project root, logger auto-discovers & loads it
• ✅ Bundled binaries: Pre-compiled native libraries for Windows/macOS/Linux included in npm package
• ✅ Zero config: Works immediately after npm install without manual setup
• ✅ Thread-safe: Concurrent log/flush/stats/setFields calls safe on one instance
• ✅ TypeScript: Full type definitions included

Installation

npm install @polyglot/logger

All native binaries (.so, .dll, .dylib) are bundled in the npm package. No separate compilation needed.

Building from Source

To build from the core repository with all language bindings:

git clone --recurse-submodules https://github.com/kishankumarhs/Polyglot.git
cd Polyglot

# Build native library and all bindings
make build-native
cd bindings/node && npm install && npm run build

Configuration

Place a polyglot.yaml in your project root:

service: checkout-api
environment: prod
logging:
  level: info
  async: true
file:
  enabled: true
  path: /var/log/checkout.log

On first import, the logger auto-discovers this config and initializes automatically.

Alternatively, set environment variables:

• POLYGLOT_CONFIG_PATH=/path/to/polyglot.yaml
• POLYGLOT_CONFIG_FILE=/path/to/config.json

Documentation

| Resource | Description | | --------------------------------------------------- | ------------------------------------- | | Node.js API | Language-specific API reference | | User Guide | Logging concepts, fields, async modes | | Configuration | Full schema & examples | | Getting Started | Build & run first log | | Architecture | Design & internals | | Repositories Overview | How all 4 repos work together |

Thread Safety

A single logger instance is safe for concurrent calls to:

• log() / logSimple()
• flush()
• stats()
• setFields()
• reloadConfig()

Only close() should be called by a single thread (one owner of the logger lifecycle).

Native Library Auto-Discovery

The binding automatically discovers the native library:

1. Checks for bundled binary in node_modules/@polyglot/logger/bin/
2. Falls back to POLYGLOT_LOGGER_LIB environment variable (if set)
3. If neither found: error with helpful message

Troubleshooting

"native library not found"

• Ensure package installed with binaries: npm ls @polyglot/logger
• Check if node_modules/@polyglot/logger/bin/ contains .so/.dll/.dylib
• Set POLYGLOT_LOGGER_LIB=/path/to/liblogger.so explicitly

"polyglot.yaml not found"

• Create polyglot.yaml in your project root
• Or set POLYGLOT_CONFIG_PATH environment variable
• Logger will use safe defaults if neither found

TypeScript compilation errors

• Ensure tsconfig.json includes "skipLibCheck": true
• Generated types are in node_modules/@polyglot/logger/dist/*.d.ts

Version Management

This binding is independently versioned. Each release:

• Includes latest C ABI from polyglot-go
• Pre-compiled native binaries for all platforms
• TypeScript definitions and source maps

Check polyglot-go releases to see which core version this binding is based on.

Repository Links

• This repo (Node bindings): https://github.com/kishankumarhs/polyglot-node
• Core (Go logger): https://github.com/kishankumarhs/Polyglot
• Python bindings: https://github.com/kishankumarhs/polyglot-py
• .NET bindings: https://github.com/kishankumarhs/polyglot-csharp

Contributing

To contribute to Node.js bindings:

# Clone core with all submodules
git clone --recurse-submodules https://github.com/kishankumarhs/Polyglot.git
cd Polyglot/bindings/node

# Make changes
vim src/index.ts

# Test
npm test

# Commit and push to polyglot-node
git add src/
git commit -m "fix: description"
git push origin main

# Update core submodule reference
cd ../..
git add bindings/node
git commit -m "chore: bump node binding"
git push origin main

License

MIT — see LICENSE in this repository