@elysiumjs/argus 0.1.1 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # @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
+
+- [`8ac91ab`](https://github.com/na2axl/elysiumjs/commit/8ac91ab676b1119b4eecf0ddb3fd0a3e84017cac) Thanks [@na2axl](https://github.com/na2axl)! - Upgrade dependencies to their latest major versions: wampy 8, zod 4, commander 15, @casl/ability 7, OpenTelemetry SDK 2 (sdk-node 0.300, resources 3), @sentry/bun 11. Generated projects now use TypeScript 7.
+
+  Breaking in `@elysiumjs/mnemosyne-drizzle`: it now requires drizzle-orm 1.0 (release candidate) and generated projects use drizzle-kit 1.0. `ColumnsWithTable` is no longer re-exported. `migration:generate` writes 1.0 migration folders (`<timestamp>_<name>/migration.sql`), and `migration:run` tracks those by folder name while still running flat `*.sql` files. Existing projects can upgrade their migrations folder with `drizzle-kit up`: `migration:run` recognises the moved migrations as already applied and renames their records. The `make:model` stub now generates a `pgTable` and a `DrizzleModel` built from it.
+
+  Breaking in `@elysiumjs/core`: the deprecated `@elysiajs/swagger` plugin is replaced by `@elysiajs/openapi`, and the app option `swagger` is renamed `openapi` (typed `ElysiaOpenAPIConfig | false`). Without a `path`, the docs now live at `/openapi` instead of `/swagger`. The UI options `scalarConfig` and `swaggerOptions` are now `scalar` and `swagger`. Elysia stays on 1.4 (now `^1.4.30`) until Elysia 2 and its OpenAPI plugin are stable.
+
+  Also in `@elysiumjs/core`: the WAMP `onChallenge` callback must return a string (or a promise of one); `null` is no longer accepted. `onError` now receives the error and `onReconnectSuccess` receives wampy's details object. `WampClient` is now wampy's own `Wampy` type. `onOpen` is called by Elysium once the connection is established, since wampy 8 no longer has that callback.
+
+- [`07236b3`](https://github.com/na2axl/elysiumjs/commit/07236b386c2506590d74e8753ce847c1e184b3ee) Thanks [@na2axl](https://github.com/na2axl)! - Introduce the module system. Modules are now the only way to register anything in an Elysium.js app. This is a breaking change with no compatibility layer.
+
+  Breaking changes:
+
+  - `@Module.register()` takes `imports`, `services`, `exports`, `controllers`, `commands`, `jobs`, `prefix` and `env`. Services are private to their module unless exported (or global). The `beforeRegister` and `afterRegister` hooks are replaced by `onInit`, `onServe` and `onDestroy`.
+  - Configurable modules are bound with `with()`, for example `HermesModule.with({ level: 'debug' })`. `with()` accepts an object or a function.
+  - Decorators only record metadata. Importing a file no longer registers commands, services or event wiring, and the side-effect imports of the packages are removed. List commands, jobs and services in the module that owns them.
+  - `@Application.register()` no longer takes `database`, `redis`, `wamp` or `'elysium:hermes'`/`'elysium:cerberus'` keys. Use `DrizzleModule`, `RedisModule`, `WampModule`, `HermesModule` and `CerberusModule`. Package plugins are replaced by modules: add `SentryModule` instead of the `plugin()` function. `plugins` still accepts plain Elysia plugin factories.
+  - Constructing an `Application` no longer runs it. Use `await App.start()`; `Application.testing()` boots a module graph for tests. The `styx` binary loads `src/app.ts` (or `index.ts`) and starts the exported application, so a project entry no longer needs to import commands.
+  - The job system of core (`Job`, `Worker`, `WorkerPool`, `commandWork`) is removed. `@elysiumjs/heracles` is the only job system: extend its `Job`, list jobs in a module's `jobs`, declare queues with `HeraclesModule.with({ queues })`, and dispatch with `Heracles.dispatch()`.
+  - `@elysiumjs/styx` ships `StyxModule`, active in development only. The `migration:generate` and `migration:run` commands move to `DrizzleModule` and are available in production.
+  - `@elysiumjs/mnemosyne` ships `MnemosyneModule` for its caches (`redis: false` or `memory: false` opts out). `DrizzleModule` imports it.
+  - New modules: `HephaestusModule`, `ArgusModule` (`serviceName` is required), `SentryModule` (needs a `dsn` or `SENTRY_DSN`) and `CerberusModule` (`getSubject` is required).
+  - Module and service code throws typed errors (for example `InvalidModuleConfigError`) instead of exiting the process. `Application.run()` prints them and exits; command `run()` methods may still exit, and package plugin factories are unchanged.
+  - `Application.register` merges subclass props over the parent's (own props, then own metadata, then parent, then defaults), and concatenates `modules` parent first. Previously defaults and parent values won, so `openapi` could not be enabled.
+  - `Heracles.dispatch` starts a stopped queue on first use, so producers no longer start queues. `Queue.start()` is idempotent.
+  - `create-elysium` generates apps that use modules, and adds Sentry and Hephaestus to the `modules` list.
+  - `@Event.on`/`@Event.once` method listeners on classes in a loaded module's `services` or `controllers` are wired by the kernel and run in their module's context. Jobs, commands and middlewares are not wired, and an instance listener on a class that is not a service throws `EventListenerNotSupportedError`. Listeners on classes not listed in a loaded module no longer fire.
+  - New typed errors: `CircularDependencyError` (services that depend on each other, in sync and async resolution), `DuplicateModuleNameError` (two different module classes sharing a name; module scopes and config tokens are name based) and `EventListenerNotSupportedError`.
+  - Lazy boot contract: a CLI command initialises only its own module and that module's imports. Sync helpers such as `Database.getConnection()` work when the owning module's `onInit` is synchronous; otherwise they throw `ServiceNotReadyError` naming the module. Use `await Service.resolve()` or set `static boot = true` on the command.
+
+### Patch Changes
+
+- Updated dependencies [[`8ac91ab`](https://github.com/na2axl/elysiumjs/commit/8ac91ab676b1119b4eecf0ddb3fd0a3e84017cac), [`3625883`](https://github.com/na2axl/elysiumjs/commit/3625883dba92f1596e7444ee52f9399d8e9b049f), [`07236b3`](https://github.com/na2axl/elysiumjs/commit/07236b386c2506590d74e8753ce847c1e184b3ee)]:
+  - @elysiumjs/core@0.8.0
+  - @elysiumjs/hermes@0.4.0
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -0,0 +1,9 @@
+# @elysiumjs/argus
+
+OpenTelemetry tracing for Elysium.
+
+## ArgusModule and preloading
+
+`ArgusModule.with({ serviceName: 'my-api' })` starts the SDK in `onInit` and installs request spans on the root app. OTel auto-instrumentation only covers modules loaded after `onInit`.
+
+For full auto-instrumentation, keep a preload file that calls `ArgusSDK.initialize(...)` before application code is imported. The module detects the already-initialised SDK, leaves it running and does not shut it down.

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';