@elysiumjs/hermes 0.1.1 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @elysiumjs/hermes
+
+## 0.3.0
+
+### Minor Changes
+
+- Add HTTP transport for remote log shipping.
+- Add `@Logged` decorator for automatic method-level logging.
+- Implement lazy DI registration and logger factory pattern.
+- Export new types and improve overall logging API.

package/README.md

@@ -11,9 +11,9 @@ bun add @elysiumjs/hermes
 ## Usage
 
 ```ts
-import { LoggerService } from '@elysiumjs/hermes';
+import { HermesLogger } from '@elysiumjs/hermes';
 
-const logger = LoggerService.make('my-logger');
+const logger = HermesLogger.make('my-logger');
 
 logger.info('Hello world!');
 logger.error('Something went wrong!');

package/dist/index.js

@@ -0,0 +1,2 @@
+// @bun
+var V=import.meta.require;import{Service as S}from"@elysiumjs/core";import{Service as G}from"@elysiumjs/core";import E from"pino";var Y={level:"info",format:"json"};class C{pino;config;static make(f){return G.get(C)?.child({name:f})??new C({name:f})}constructor(f={}){this.config={...Y,...f},this.pino=this.createPinoInstance()}createPinoInstance(){let f={level:this.config.level,name:this.config.name};if(this.config.format==="pretty")return E(f,E.transport({target:"pino-pretty"}));return E(f)}trace(f,O){this.pino.trace(O??{},f)}debug(f,O){this.pino.debug(O??{},f)}info(f,O){this.pino.info(O??{},f)}warn(f,O){this.pino.warn(O??{},f)}error(f,O){this.pino.error(O??{},f)}fatal(f,O){this.pino.fatal(O??{},f)}child(f){let O=Object.create(this);return O.pino=this.pino.child(f),O}}class b{options;buffer=[];flushTimer;maxBufferSize;constructor(f){this.options=f;this.options.batchSize??=100,this.options.flushInterval??=5000,this.maxBufferSize=this.options.maxBufferSize??1e4,this.flushTimer=setInterval(()=>this.flush(),this.options.flushInterval)}write(f){if(this.buffer.length>=this.maxBufferSize)this.buffer.shift();if(this.buffer.push(f),this.buffer.length>=this.options.batchSize)this.flush()}async flush(){if(this.buffer.length===0)return;let f=this.buffer.splice(0);try{await fetch(this.options.url,{method:"POST",headers:{"Content-Type":"application/json",...this.options.headers},body:JSON.stringify({logs:f})})}catch{let O=this.maxBufferSize-this.buffer.length;if(O>0)this.buffer.unshift(...f.slice(0,O))}}async close(){if(this.flushTimer)clearInterval(this.flushTimer);await this.flush()}}import{ConsoleLogger as q}from"@elysiumjs/core";function J(f={}){return function(O,D,F){let L=F.value,I=`${O.constructor.name}.${String(D)}`;return F.value=async function(...T){let W=this.logger??N(),U=Date.now();if(f.includeArgs)W.debug(`[${I}] Entry`,{args:T});try{let w=await L.apply(this,T);if(f.includeResult||f.includeTiming){let A=Date.now()-U;W[f.level??"debug"](`[${I}] Exit`,{...f.includeResult&&{result:w},...f.includeTiming&&{duration:`${A}ms`}})}return w}catch(w){let A=Date.now()-U;throw W.error(`[${I}] Error`,{error:w instanceof Error?w.message:w,duration:`${A}ms`}),w}},F}}function N(){try{let{Service:f}=V("@elysiumjs/core");return f.get("logger")??new q}catch{return new q}}var R=null,B=()=>{if(!R){let O=S.get("elysium.app")?.getConfig("elysium:hermes");R=new C(O??{})}return R};S.registerLazy(C.name,B);S.registerLazy("logger",B);export{J as Logged,b as HttpTransport,C as HermesLogger};

package/index.ts

@@ -12,6 +12,4 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import './src/services/pino.factory';
-
-export { LoggerService } from './src/services/logger.service.ts';
+export * from './src/index';

package/package.json

@@ -1,18 +1,31 @@
 {
-	"name": "@elysiumjs/hermes",
-	"version": "0.1.1",
-	"module": "index.ts",
-	"type": "module",
-	"devDependencies": {
-		"@ianvs/prettier-plugin-sort-imports": "^4.4.1",
-		"@types/bun": "latest",
-		"type-fest": "^4.41.0"
-	},
-	"peerDependencies": {
-		"@elysiumjs/core": "latest",
-		"typescript": "^5.8.3"
-	},
-	"dependencies": {
-		"pino": "^9.6.0"
-	}
+  "name": "@elysiumjs/hermes",
+  "version": "0.3.1",
+  "type": "module",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": [
+    "./src/index.ts"
+  ],
+  "scripts": {
+    "format": "prettier --write \"./src/**/*.ts\"",
+    "clean": "rimraf dist",
+    "build:js": "bun build ./src/index.ts --outdir ./dist --target bun --packages external --root ./src --minify",
+    "build:ts": "tsc",
+    "build": "bun run clean && bun run build:js && bun run build:ts",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "pino": "^10.0.0",
+    "pino-pretty": "^13.0.0"
+  },
+  "devDependencies": {
+    "@elysiumjs/core": "0.6.1"
+  },
+  "peerDependencies": {
+    "@elysiumjs/core": "^0.6.1"
+  }
 }

package/src/decorators/logged.ts

@@ -0,0 +1,86 @@
+// Copyright (c) 2026-present Workbud Technologies Inc. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { LoggerInterface } from '@elysiumjs/core';
+import type { LogLevel } from '../types';
+
+import { ConsoleLogger } from '@elysiumjs/core';
+
+export interface LoggedOptions {
+	level?: LogLevel;
+	includeArgs?: boolean;
+	includeResult?: boolean;
+	includeTiming?: boolean;
+}
+
+/**
+ * Decorator that logs method entry/exit with optional timing.
+ *
+ * Logger is resolved at CALL TIME (not decorator definition time)
+ * to avoid capturing a stale logger reference.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export function Logged(options: LoggedOptions = {}): MethodDecorator {
+	return function (
+		target: object,
+		propertyKey: string | symbol,
+		descriptor: TypedPropertyDescriptor<any>
+	) {
+		const original = descriptor.value;
+		const methodName = `${target.constructor.name}.${String(propertyKey)}`;
+
+		descriptor.value = async function (...args: any[]) {
+			const logger: LoggerInterface = (this as any).logger ?? getServiceLogger();
+
+			const startTime = Date.now();
+
+			if (options.includeArgs) {
+				logger.debug(`[${methodName}] Entry`, { args });
+			}
+
+			try {
+				const result = await original.apply(this, args);
+
+				if (options.includeResult || options.includeTiming) {
+					const duration = Date.now() - startTime;
+					logger[options.level ?? 'debug'](`[${methodName}] Exit`, {
+						...(options.includeResult && { result }),
+						...(options.includeTiming && { duration: `${duration}ms` })
+					});
+				}
+
+				return result;
+			} catch (error) {
+				const duration = Date.now() - startTime;
+				logger.error(`[${methodName}] Error`, {
+					error: error instanceof Error ? error.message : error,
+					duration: `${duration}ms`
+				});
+				throw error;
+			}
+		};
+
+		return descriptor;
+	};
+}
+
+function getServiceLogger(): LoggerInterface {
+	try {
+		const { Service } = require('@elysiumjs/core');
+		return Service.get('logger') ?? new ConsoleLogger();
+	} catch {
+		return new ConsoleLogger();
+	}
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+// Copyright (c) 2026-present Workbud Technologies Inc. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { HermesConfig } from './types';
+
+import { Application, Service } from '@elysiumjs/core';
+
+import { HermesLogger } from './services/logger.service';
+
+// Lazy singleton resolver: reads config from Application on first access.
+let hermesInstance: HermesLogger | null = null;
+const hermesResolver = () => {
+	if (!hermesInstance) {
+		const app = Service.get<Application>('elysium.app');
+		const config = app?.getConfig<Partial<HermesConfig>>('elysium:hermes');
+		hermesInstance = new HermesLogger(config ?? {});
+	}
+	return hermesInstance;
+};
+
+Service.registerLazy(HermesLogger.name, hermesResolver);
+Service.registerLazy('logger', hermesResolver);
+
+export { HermesLogger } from './services/logger.service';
+export { HttpTransport } from './transports/http.transport';
+export type { HttpTransportOptions } from './transports/http.transport';
+export { Logged } from './decorators/logged';
+export type { LoggedOptions } from './decorators/logged';
+export type { HermesConfig, LogLevel, LogFormat, TransportConfig } from './types';

package/src/services/logger.service.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2025-present Workbud Technologies Inc. All rights reserved.
+// Copyright (c) 2026-present Workbud Technologies Inc. All rights reserved.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -12,52 +12,74 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import type { Logger } from 'pino';
+import type { LoggerInterface } from '@elysiumjs/core';
+import type { Logger as PinoLogger } from 'pino';
+import type { HermesConfig } from '../types';
 
-import { Service, ServiceScope } from '@elysiumjs/core';
+import { Service } from '@elysiumjs/core';
 import pino from 'pino';
 
-@Service.register({ scope: ServiceScope.SINGLETON })
-export class LoggerService {
-	readonly #pino: Logger;
+import { DEFAULT_CONFIG } from '../types';
 
-	public constructor(@Service.inject('elysium.hermes.pino') pino: pino.Logger) {
-		this.#pino = pino;
+/**
+ * Production-ready logger implementation wrapping Pino.
+ * Implements `LoggerInterface` from `@elysiumjs/core`.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export class HermesLogger implements LoggerInterface {
+	private pino: PinoLogger;
+	private config: HermesConfig;
+
+	public static make(name: string): HermesLogger {
+		return Service.get(HermesLogger)?.child({ name }) ?? new HermesLogger({ name });
 	}
 
-	public static make(name: string) {
-		return new LoggerService(pino({ name }));
+	constructor(config: Partial<HermesConfig> = {}) {
+		this.config = { ...DEFAULT_CONFIG, ...config };
+		this.pino = this.createPinoInstance();
 	}
 
-	public info(message: string, details?: Record<string, unknown>) {
-		if (details) {
-			this.#pino.info(details, message);
-		} else {
-			this.#pino.info(message);
+	private createPinoInstance(): PinoLogger {
+		const options: pino.LoggerOptions = {
+			level: this.config.level,
+			name: this.config.name
+		};
+
+		if (this.config.format === 'pretty') {
+			return pino(options, pino.transport({ target: 'pino-pretty' }));
 		}
+
+		return pino(options);
 	}
 
-	public error(message: string, details?: Record<string, unknown>) {
-		if (details) {
-			this.#pino.error(details, message);
-		} else {
-			this.#pino.error(message);
-		}
+	public trace(msg: string, ctx?: Record<string, unknown>): void {
+		this.pino.trace(ctx ?? {}, msg);
 	}
 
-	public warn(message: string, details?: Record<string, unknown>) {
-		if (details) {
-			this.#pino.error(details, message);
-		} else {
-			this.#pino.warn(message);
-		}
+	public debug(msg: string, ctx?: Record<string, unknown>): void {
+		this.pino.debug(ctx ?? {}, msg);
 	}
 
-	public debug(message: string, details?: Record<string, unknown>) {
-		if (details) {
-			this.#pino.error(details, message);
-		} else {
-			this.#pino.debug(message);
-		}
+	public info(msg: string, ctx?: Record<string, unknown>): void {
+		this.pino.info(ctx ?? {}, msg);
+	}
+
+	public warn(msg: string, ctx?: Record<string, unknown>): void {
+		this.pino.warn(ctx ?? {}, msg);
+	}
+
+	public error(msg: string, ctx?: Record<string, unknown>): void {
+		this.pino.error(ctx ?? {}, msg);
+	}
+
+	public fatal(msg: string, ctx?: Record<string, unknown>): void {
+		this.pino.fatal(ctx ?? {}, msg);
+	}
+
+	public child(ctx: Record<string, unknown>): HermesLogger {
+		const child = Object.create(this) as HermesLogger;
+		child.pino = this.pino.child(ctx);
+		return child;
 	}
 }

package/src/transports/http.transport.ts

@@ -0,0 +1,79 @@
+// Copyright (c) 2026-present Workbud Technologies Inc. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+export interface HttpTransportOptions {
+	url: string;
+	headers?: Record<string, string>;
+	batchSize?: number;
+	flushInterval?: number;
+	maxBufferSize?: number;
+}
+
+/**
+ * HTTP transport for batching and sending logs to a remote endpoint.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export class HttpTransport {
+	private buffer: string[] = [];
+	private flushTimer?: ReturnType<typeof setInterval>;
+	private maxBufferSize: number;
+
+	constructor(private options: HttpTransportOptions) {
+		this.options.batchSize ??= 100;
+		this.options.flushInterval ??= 5000;
+		this.maxBufferSize = this.options.maxBufferSize ?? 10_000;
+
+		this.flushTimer = setInterval(() => this.flush(), this.options.flushInterval);
+	}
+
+	public write(formatted: string): void {
+		if (this.buffer.length >= this.maxBufferSize) {
+			this.buffer.shift();
+		}
+
+		this.buffer.push(formatted);
+
+		if (this.buffer.length >= this.options.batchSize!) {
+			this.flush();
+		}
+	}
+
+	public async flush(): Promise<void> {
+		if (this.buffer.length === 0) return;
+
+		const batch = this.buffer.splice(0);
+
+		try {
+			await fetch(this.options.url, {
+				method: 'POST',
+				headers: {
+					'Content-Type': 'application/json',
+					...this.options.headers
+				},
+				body: JSON.stringify({ logs: batch })
+			});
+		} catch {
+			const space = this.maxBufferSize - this.buffer.length;
+			if (space > 0) {
+				this.buffer.unshift(...batch.slice(0, space));
+			}
+		}
+	}
+
+	public async close(): Promise<void> {
+		if (this.flushTimer) clearInterval(this.flushTimer);
+		await this.flush();
+	}
+}

package/src/{services/pino.factory.ts → types.ts}

@@ -1,4 +1,4 @@
-// Copyright (c) 2025-present Workbud Technologies Inc. All rights reserved.
+// Copyright (c) 2026-present Workbud Technologies Inc. All rights reserved.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -12,9 +12,23 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import { Service } from '@elysiumjs/core';
-import pino from 'pino';
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
 
-const pinoFactory = () => pino();
+export type LogFormat = 'json' | 'pretty' | 'logfmt';
 
-Service.factory('elysium.hermes.pino', pinoFactory);
+export interface TransportConfig {
+	type: 'console' | 'file' | 'http';
+	options?: Record<string, unknown>;
+}
+
+export interface HermesConfig {
+	name?: string;
+	level: LogLevel;
+	format: LogFormat;
+	transports?: TransportConfig[];
+}
+
+export const DEFAULT_CONFIG: HermesConfig = {
+	level: 'info',
+	format: 'json'
+};