@elysiumjs/argus 0.2.0 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @elysiumjs/argus
 
+## 0.2.3
+
+### Patch Changes
+
+- [`04773f2`](https://github.com/na2axl/elysiumjs/commit/04773f2acd4ab1c762a80ee903715d90f1c08e21) Thanks [@na2axl](https://github.com/na2axl)! - Ship the type declarations. The packages pointed `types` at `dist/index.d.ts` but their build never wrote it, so TypeScript projects got no types for them.
+- Updated dependencies [[`04773f2`](https://github.com/na2axl/elysiumjs/commit/04773f2acd4ab1c762a80ee903715d90f1c08e21)]:
+  - @elysiumjs/hermes@0.4.3
+
+## 0.2.2
+
+### Patch Changes
+
+- Updated dependencies [[`68a0cdd`](https://github.com/na2axl/elysiumjs/commit/68a0cdd8b2e4a003d6e0af2d78985623cae40428), [`2c49acd`](https://github.com/na2axl/elysiumjs/commit/2c49acd3b552aa43765d70339fa216961499e1b5), [`76ba0ff`](https://github.com/na2axl/elysiumjs/commit/76ba0ff18f3c196cebc2189426328f67cb699f46), [`4ebf029`](https://github.com/na2axl/elysiumjs/commit/4ebf029611e6d753a4f1bfdbe247a75d954d9ded), [`bacce71`](https://github.com/na2axl/elysiumjs/commit/bacce7146f667a1a46bf474dc0344fb0111ae12a)]:
+  - @elysiumjs/core@0.10.0
+  - @elysiumjs/hermes@0.4.2
+
+## 0.2.1
+
+### Patch Changes
+
+- Updated dependencies [[`5fef4a7`](https://github.com/na2axl/elysiumjs/commit/5fef4a7199f502fc4fe035299e7670739459a108)]:
+  - @elysiumjs/core@0.9.0
+  - @elysiumjs/hermes@0.4.1
+
 ## 0.2.0
 
 ### Minor Changes

package/dist/argus.module.d.ts

@@ -0,0 +1,34 @@
+import type { TracingConfig } from './types';
+import { Module } from '@elysiumjs/core';
+declare const ArgusModule_base: (abstract new () => {
+    readonly config: TracingConfig;
+    onInit(): Promise<void> | void;
+    onDestroy(): Promise<void> | void;
+    onServe(_app: import("elysia").default<any>): Promise<void> | void;
+}) & {
+    readonly config: string;
+    with(config: Partial<TracingConfig> | (() => Partial<TracingConfig> | Promise<Partial<TracingConfig>>)): import("@elysiumjs/core").ConfiguredModule<TracingConfig>;
+    resolveConfig(input?: Partial<TracingConfig> | undefined): TracingConfig;
+    register<TConfig_1 = any>(props?: import("@elysiumjs/core").ModuleProps<TConfig_1>): (target: import("@elysiumjs/core").ModuleClass) => void;
+    configurable<TConfig extends object>(options?: {
+        defaults?: Partial<TConfig>;
+        required?: (keyof TConfig)[];
+    }): any;
+};
+/**
+ * Configurable module that starts the {@link ArgusSDK} on init, installs the request-span
+ * plugin on the root app when serving, and shuts the SDK down on destroy.
+ *
+ * If the SDK was already initialised (e.g. by a preload), the module leaves it running and
+ * does not shut it down.
+ *
+ * `serviceName` has no sensible default and is required.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class ArgusModule extends ArgusModule_base {
+    #private;
+    onInit(): void;
+    onServe(app: Parameters<Module['onServe']>[0]): void;
+    onDestroy(): Promise<void>;
+}
+export {};

package/dist/correlation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Enriches a log context object with `traceId` and `spanId` from the
+ * active OpenTelemetry span.
+ *
+ * Use this in Hermes log calls to correlate logs with traces:
+ *
+ * @example
+ * ```typescript
+ * import { withTraceContext } from '@elysiumjs/argus';
+ *
+ * logger.info('Processing request', withTraceContext({ userId: '123' }));
+ * // Output: { msg: "Processing request", userId: "123", traceId: "abc...", spanId: "def..." }
+ * ```
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param ctx The base context to enrich.
+ * @returns The context with `traceId` and `spanId` injected if an active span exists.
+ */
+export declare function withTraceContext(ctx?: Record<string, unknown>): Record<string, unknown>;

package/dist/decorators/traced.d.ts

@@ -0,0 +1,23 @@
+import type { SpanOptions } from '@opentelemetry/api';
+/**
+ * Decorator that wraps a method in an OpenTelemetry span.
+ *
+ * Creates a child span for each method invocation, recording success
+ * or error status. Exceptions are recorded on the span before re-throwing.
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @Traced('user.findById')
+ *   async findById(id: string) {
+ *     return db.query('SELECT * FROM users WHERE id = $1', [id]);
+ *   }
+ * }
+ * ```
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param name Optional span name. Defaults to `ClassName.methodName`.
+ * @param options Optional OpenTelemetry span options.
+ * @returns A method decorator.
+ */
+export declare function Traced(name?: string, options?: SpanOptions): MethodDecorator;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { TracingConfig } from './types';
+export { ArgusSDK } from './sdk';
+export { Traced } from './decorators/traced';
+export { withTraceContext } from './correlation';
+export { argusPlugin } from './plugin';
+export { ArgusModule } from './argus.module';

package/dist/plugin.d.ts

@@ -0,0 +1,40 @@
+import { Elysia } from 'elysia';
+/**
+ * Elysia plugin that creates OpenTelemetry request spans.
+ *
+ * Each HTTP request gets a span with method, path, and status information.
+ * Errors (5xx) are recorded as error spans.
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @returns An Elysia plugin instance.
+ */
+export declare const argusPlugin: () => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {
+        readonly __argusSpan: import("@opentelemetry/api").Span;
+    };
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/sdk.d.ts

@@ -0,0 +1,56 @@
+import type { TracingConfig } from './types';
+/**
+ * ArgusSDK initializes OpenTelemetry for the Elysium framework.
+ *
+ * CRITICAL: For full auto-instrumentation this MUST be called before any
+ * application code runs (e.g. from a `--preload` file). Auto-instrumentation
+ * patches modules at import time; modules imported before OTel is initialized
+ * won't be instrumented. `ArgusModule` initialises the SDK in `onInit`, which
+ * only covers modules loaded afterwards; when the SDK was already initialised
+ * (e.g. by a preload), the module detects it with {@link ArgusSDK.isInitialized}
+ * and leaves it alone.
+ *
+ * @example
+ * ```typescript
+ * // src/instrument.ts (loaded FIRST via --preload or entrypoint)
+ * import { ArgusSDK } from '@elysiumjs/argus';
+ *
+ * ArgusSDK.initialize({
+ *   enabled: true,
+ *   serviceName: 'my-api',
+ *   exporter: 'otlp-http',
+ *   endpoint: 'http://localhost:4318/v1/traces'
+ * });
+ * ```
+ *
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class ArgusSDK {
+    private static instance;
+    private sdk;
+    private constructor();
+    /**
+     * Whether {@link ArgusSDK.initialize} has already been called.
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    static isInitialized(): boolean;
+    /**
+     * Initializes the OpenTelemetry SDK.
+     * Can only be called once — subsequent calls are ignored with a warning.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param config The tracing configuration.
+     */
+    static initialize(config: TracingConfig): void;
+    /**
+     * Creates the appropriate trace exporter based on the config.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param config The tracing configuration.
+     * @returns A span exporter instance.
+     */
+    private static createExporter;
+    /**
+     * Shuts down the OpenTelemetry SDK gracefully.
+     * @author Axel Nana <axel.nana@workbud.com>
+     */
+    static shutdown(): Promise<void>;
+}

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Configuration for the Argus telemetry SDK.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface TracingConfig {
+    /**
+     * Whether tracing is enabled.
+     */
+    enabled: boolean;
+    /**
+     * The service name reported in spans.
+     */
+    serviceName: string;
+    /**
+     * The exporter to use. Only `otlp-http` and `console` are supported.
+     * gRPC is not supported on Bun.
+     */
+    exporter: 'otlp-http' | 'console';
+    /**
+     * The OTLP endpoint URL.
+     * @default 'http://localhost:4318/v1/traces'
+     */
+    endpoint?: string;
+    /**
+     * Sampling rate between 0.0 and 1.0.
+     * @default 1.0
+     */
+    samplingRate?: number;
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@elysiumjs/argus",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "license": "Apache-2.0",
   "description": "OpenTelemetry telemetry package for the Elysium.js framework.",
   "private": false,
   "author": "Workbud Technologies Inc.",
   "repository": {
     "type": "git",
-    "url": "https://github.com/workbud/elysium"
+    "url": "git+https://github.com/na2axl/elysiumjs.git",
+    "directory": "@elysiumjs/argus"
   },
   "keywords": [
     "elysium",
@@ -19,11 +20,18 @@
     "typescript",
     "bun"
   ],
-  "homepage": "https://github.com/workbud/elysium",
-  "module": "index.ts",
+  "homepage": "https://github.com/na2axl/elysiumjs/tree/main/@elysiumjs/argus#readme",
+  "bugs": {
+    "url": "https://github.com/na2axl/elysiumjs/issues"
+  },
+  "module": "dist/index.js",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
   "sideEffects": false,
   "scripts": {
     "format": "prettier --write \"./src/**/*.ts\"",
@@ -45,12 +53,12 @@
     "@opentelemetry/semantic-conventions": "^1.43.0"
   },
   "devDependencies": {
-    "@elysiumjs/core": "0.8.0",
-    "@elysiumjs/hermes": "0.4.0"
+    "@elysiumjs/core": "0.10.0",
+    "@elysiumjs/hermes": "0.4.3"
   },
   "peerDependencies": {
-    "@elysiumjs/core": "^0.8.0",
-    "@elysiumjs/hermes": "^0.4.0"
+    "@elysiumjs/core": "^0.10.0",
+    "@elysiumjs/hermes": "^0.4.3"
   },
   "peerDependenciesMeta": {
     "@elysiumjs/hermes": {

package/.turbo/turbo-build.log

@@ -1,8 +0,0 @@
-$ bun run clean && bun run build:js && bun run build:ts
-$ rimraf dist
-$ bun build ./src/index.ts --outdir ./dist --target bun -e @elysiumjs/* -e @opentelemetry/* --root ./src --minify-syntax --minify-whitespace
-Bundled 327 modules in 60ms
-
-  index.js  0.56 MB  (entry point)
-
-$ tsc

package/index.ts

@@ -1,15 +0,0 @@
-// 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 * from './src/index';

package/src/argus.module.ts

@@ -1,55 +0,0 @@
-// 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 { TracingConfig } from './types';
-
-import { Module } from '@elysiumjs/core';
-
-import { argusPlugin } from './plugin';
-import { ArgusSDK } from './sdk';
-
-/**
- * Configurable module that starts the {@link ArgusSDK} on init, installs the request-span
- * plugin on the root app when serving, and shuts the SDK down on destroy.
- *
- * If the SDK was already initialised (e.g. by a preload), the module leaves it running and
- * does not shut it down.
- *
- * `serviceName` has no sensible default and is required.
- * @author Axel Nana <axel.nana@workbud.com>
- */
-@Module.register({})
-export class ArgusModule extends Module.configurable<TracingConfig>({
-	defaults: { enabled: true, exporter: 'console' },
-	required: ['serviceName']
-}) {
-	#started = false;
-
-	public override onInit(): void {
-		// A preload (or anything else) already owns the SDK: leave it alone.
-		if (ArgusSDK.isInitialized()) return;
-		ArgusSDK.initialize(this.config);
-		this.#started = true;
-	}
-
-	public override onServe(app: Parameters<Module['onServe']>[0]): void {
-		app.use(argusPlugin());
-	}
-
-	public override async onDestroy(): Promise<void> {
-		if (!this.#started) return;
-		this.#started = false;
-		await ArgusSDK.shutdown();
-	}
-}

package/src/correlation.ts

@@ -1,45 +0,0 @@
-// 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 { trace } from '@opentelemetry/api';
-
-/**
- * Enriches a log context object with `traceId` and `spanId` from the
- * active OpenTelemetry span.
- *
- * Use this in Hermes log calls to correlate logs with traces:
- *
- * @example
- * ```typescript
- * import { withTraceContext } from '@elysiumjs/argus';
- *
- * logger.info('Processing request', withTraceContext({ userId: '123' }));
- * // Output: { msg: "Processing request", userId: "123", traceId: "abc...", spanId: "def..." }
- * ```
- *
- * @author Axel Nana <axel.nana@workbud.com>
- * @param ctx The base context to enrich.
- * @returns The context with `traceId` and `spanId` injected if an active span exists.
- */
-export function withTraceContext(ctx: Record<string, unknown> = {}): Record<string, unknown> {
-	const span = trace.getActiveSpan();
-	if (!span) return ctx;
-
-	const spanCtx = span.spanContext();
-	return {
-		...ctx,
-		traceId: spanCtx.traceId,
-		spanId: spanCtx.spanId
-	};
-}

package/src/decorators/traced.ts

@@ -1,72 +0,0 @@
-// 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 { SpanOptions } from '@opentelemetry/api';
-
-import { SpanStatusCode, trace } from '@opentelemetry/api';
-
-/**
- * Decorator that wraps a method in an OpenTelemetry span.
- *
- * Creates a child span for each method invocation, recording success
- * or error status. Exceptions are recorded on the span before re-throwing.
- *
- * @example
- * ```typescript
- * class UserService {
- *   @Traced('user.findById')
- *   async findById(id: string) {
- *     return db.query('SELECT * FROM users WHERE id = $1', [id]);
- *   }
- * }
- * ```
- *
- * @author Axel Nana <axel.nana@workbud.com>
- * @param name Optional span name. Defaults to `ClassName.methodName`.
- * @param options Optional OpenTelemetry span options.
- * @returns A method decorator.
- */
-export function Traced(name?: string, options?: SpanOptions): MethodDecorator {
-	return function (
-		target: object,
-		propertyKey: string | symbol,
-		descriptor: TypedPropertyDescriptor<any>
-	) {
-		const original = descriptor.value;
-		const spanName = name ?? `${target.constructor.name}.${String(propertyKey)}`;
-
-		descriptor.value = async function (...args: any[]) {
-			const tracer = trace.getTracer('@elysiumjs/argus');
-
-			return tracer.startActiveSpan(spanName, options ?? {}, async (span) => {
-				try {
-					const result = await original.apply(this, args);
-					span.setStatus({ code: SpanStatusCode.OK });
-					return result;
-				} catch (error) {
-					span.setStatus({
-						code: SpanStatusCode.ERROR,
-						message: error instanceof Error ? error.message : 'Unknown error'
-					});
-					span.recordException(error as Error);
-					throw error;
-				} finally {
-					span.end();
-				}
-			});
-		};
-
-		return descriptor;
-	};
-}

package/src/index.ts

@@ -1,21 +0,0 @@
-// 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 type { TracingConfig } from './types';
-
-export { ArgusSDK } from './sdk';
-export { Traced } from './decorators/traced';
-export { withTraceContext } from './correlation';
-export { argusPlugin } from './plugin';
-export { ArgusModule } from './argus.module';

package/src/plugin.ts

@@ -1,62 +0,0 @@
-// 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 { SpanStatusCode, trace } from '@opentelemetry/api';
-import { Elysia } from 'elysia';
-
-/**
- * Elysia plugin that creates OpenTelemetry request spans.
- *
- * Each HTTP request gets a span with method, path, and status information.
- * Errors (5xx) are recorded as error spans.
- *
- * @author Axel Nana <axel.nana@workbud.com>
- * @returns An Elysia plugin instance.
- */
-export const argusPlugin = () => {
-	const tracer = trace.getTracer('@elysiumjs/argus');
-
-	return new Elysia({ name: '@elysiumjs/argus' })
-		.derive(({ request }) => {
-			const url = new URL(request.url);
-			const span = tracer.startSpan(`${request.method} ${url.pathname}`, {
-				attributes: {
-					'http.method': request.method,
-					'http.url': request.url,
-					'http.target': url.pathname
-				}
-			});
-
-			return { __argusSpan: span };
-		})
-		.onAfterResponse(({ __argusSpan, request }) => {
-			if (__argusSpan) {
-				__argusSpan.setStatus({ code: SpanStatusCode.OK });
-				__argusSpan.setAttribute('http.method', request.method);
-				__argusSpan.end();
-			}
-		})
-		.onError(({ __argusSpan, error }) => {
-			if (__argusSpan) {
-				__argusSpan.setStatus({
-					code: SpanStatusCode.ERROR,
-					message: error instanceof Error ? error.message : 'Unknown error'
-				});
-				if (error instanceof Error) {
-					__argusSpan.recordException(error);
-				}
-				__argusSpan.end();
-			}
-		});
-};