@venizia/ignis-kernel 0.2.0-4 → 0.2.0-40

package/dist/cjs/base/events/event-bus.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventBus = void 0;
+const common_1 = require("@venizia/ignis-helpers/common");
+const core_1 = require("@venizia/ignis-helpers/core");
+const constants_1 = require("./common/constants");
+/** In-process, fire-and-forget domain event bus. `TPayloadMap` keys the event names, so a wrong name
+ * or payload shape is a compile error. Delivery is always async. Retry timing is a property of the
+ * handler's own failure mode, not of the event, so `register` may tune it per registration. But
+ * nobody awaits a fire-and-forget dispatch, so an unbounded window would let one event hold a
+ * handler - and whatever it holds open, e.g. a database connection - for an unbounded time with no
+ * one to report it. What the bus guarantees instead: a bounded MAXIMUM time a single dispatch can
+ * occupy, enforced as a hard ceiling at `register()` - see `EventDispatchRetry`. Retry makes
+ * delivery at-least-once: handlers must be idempotent, see `IEventHandler`. */
+class EventBus extends core_1.BaseHelper {
+    constructor(opts) {
+        super({ scope: opts.scope ?? EventBus.name });
+        this.container = opts.container;
+        this.registrationsByName = new Map();
+    }
+    /** The pre-jitter total of every inter-attempt delay `maxAttempts`/`baseDelayMs` would produce -
+     * jitter (always on, see `dispatch`) only ever shrinks a delay, so this is a true upper bound. */
+    static computeTotalWindowMs(opts) {
+        const { maxAttempts, baseDelayMs } = opts;
+        let totalWindowMs = 0;
+        for (let attempt = 1; attempt < maxAttempts; attempt++) {
+            totalWindowMs += core_1.RetryHelper.computeBackoffDelayMs({
+                attempt,
+                backoff: {
+                    strategy: core_1.RetryBackoffStrategies.EXPONENTIAL,
+                    initialDelayMs: baseDelayMs,
+                    jitter: core_1.RetryJitterModes.NONE,
+                },
+            });
+        }
+        return totalWindowMs;
+    }
+    /** Loud rejection, never a silent clamp: a caller who believes a number the bus does not honour is
+     * worse off than one who sees the ceiling at boot. */
+    static assertValidRetry(opts) {
+        const { name, maxAttempts, baseDelayMs } = opts;
+        if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+            throw (0, core_1.getError)({
+                message: `[EventBus][register] retry.maxAttempts must be a positive integer | name: ${name} | Got: ${maxAttempts}`,
+            });
+        }
+        if (!Number.isInteger(baseDelayMs) || baseDelayMs < 1) {
+            throw (0, core_1.getError)({
+                message: `[EventBus][register] retry.baseDelayMs must be a positive integer | name: ${name} | Got: ${baseDelayMs}`,
+            });
+        }
+        if (maxAttempts > constants_1.EventDispatchRetry.MAX_ATTEMPTS_CEILING) {
+            throw (0, core_1.getError)({
+                message: `[EventBus][register] retry.maxAttempts exceeds the ceiling | name: ${name} | Got: ${maxAttempts} | Ceiling: ${constants_1.EventDispatchRetry.MAX_ATTEMPTS_CEILING} | Lower retry.maxAttempts`,
+            });
+        }
+        const totalWindowMs = EventBus.computeTotalWindowMs({ maxAttempts, baseDelayMs });
+        if (totalWindowMs > constants_1.EventDispatchRetry.MAX_TOTAL_WINDOW_MS) {
+            throw (0, core_1.getError)({
+                message: `[EventBus][register] retry window exceeds the ceiling | name: ${name} | Got: ${totalWindowMs}ms | Ceiling: ${constants_1.EventDispatchRetry.MAX_TOTAL_WINDOW_MS}ms | Lower retry.maxAttempts or retry.baseDelayMs`,
+            });
+        }
+    }
+    /**
+     * Turns `handler` into a uniform invoker plus a description for the exhaustion log line.
+     * `BINDING_KEY` resolves through the container INSIDE the returned closure, so every call re-reads
+     * the current binding; `FUNCTION` calls `fn` directly, so the closure IS the resolution - there is
+     * nothing left to re-read on a later attempt. The tag (`handler.type`) is what this switches on,
+     * not which field happens to be present - see `EventHandlerTypes`' doc.
+     */
+    static buildHandlerInvoker(opts) {
+        const { container, handler, name } = opts;
+        if ((0, common_1.isEmpty)({ value: handler })) {
+            throw (0, core_1.getError)({
+                message: `[EventBus][register] Invalid handler | name: ${name} | Got: ${handler}`,
+            });
+        }
+        switch (handler.type) {
+            case constants_1.EventHandlerTypes.BINDING_KEY: {
+                const { key } = handler;
+                if ((0, common_1.isEmpty)({ value: key })) {
+                    throw (0, core_1.getError)({
+                        message: `[EventBus][register] Invalid handler.key | name: ${name} | Got: ${key}`,
+                    });
+                }
+                return {
+                    invokeHandler: ({ event }) => container.get({ key }).handle({ event }),
+                    description: `binding-key:${key}`,
+                };
+            }
+            case constants_1.EventHandlerTypes.FUNCTION: {
+                const { fn } = handler;
+                if (typeof fn !== 'function') {
+                    throw (0, core_1.getError)({
+                        message: `[EventBus][register] Invalid handler.fn | name: ${name} | Expected a function | Got: ${typeof fn}`,
+                    });
+                }
+                return {
+                    invokeHandler: ({ event }) => fn({ event }),
+                    description: `function:${fn.name || 'anonymous'}`,
+                };
+            }
+            default: {
+                throw (0, core_1.getError)({
+                    message: `[EventBus][register] Unknown handler.type | name: ${name} | Expected one of: ${[...constants_1.EventHandlerTypes.SCHEME_SET].join(', ')} | Got: ${handler.type}`,
+                });
+            }
+        }
+    }
+    /**
+     * `retry` is optional and per REGISTRATION, not per publish: the right window belongs to the
+     * handler's own failure mode, and two handlers on the same event name may each pick their own.
+     * Omitting it reproduces today's `EventDispatchRetry` defaults exactly. Both `maxAttempts` and the
+     * total backoff window it implies are bounded - see `EventDispatchRetry` - and exceeding either
+     * throws here, at boot where a human sees it, rather than being silently clamped at dispatch time.
+     */
+    register(opts) {
+        const { name, handler, retry } = opts;
+        if ((0, common_1.isEmpty)({ value: name })) {
+            throw (0, core_1.getError)({
+                message: `[EventBus][register] Invalid registration | name: ${String(name)}`,
+            });
+        }
+        const maxAttempts = retry?.maxAttempts ?? constants_1.EventDispatchRetry.MAX_ATTEMPTS;
+        const baseDelayMs = retry?.baseDelayMs ?? constants_1.EventDispatchRetry.BASE_DELAY_MS;
+        EventBus.assertValidRetry({ name, maxAttempts, baseDelayMs });
+        const { invokeHandler, description } = EventBus.buildHandlerInvoker({
+            container: this.container,
+            handler,
+            name,
+        });
+        const registration = {
+            invokeHandler,
+            description,
+            maxAttempts,
+            baseDelayMs,
+        };
+        const existing = this.registrationsByName.get(name);
+        if (existing) {
+            existing.push(registration);
+            return;
+        }
+        this.registrationsByName.set(name, [registration]);
+    }
+    /**
+     * Never blocks and never throws back to the caller: dispatch runs outside this call's flow via
+     * `queueMicrotask`, and a handler failure is caught and logged where it happens (`dispatch`),
+     * never here.
+     */
+    publish(opts) {
+        const { name, payload, traceId } = opts;
+        const event = {
+            name,
+            payload,
+            occurredAt: new Date().toISOString(),
+            traceId,
+        };
+        const registrations = this.registrationsByName.get(name);
+        if (!registrations?.length) {
+            // A typo is already a compile error, so at runtime this only means nobody is listening yet -
+            // a legitimate state on a fire-and-forget bus, not an incident.
+            this.logger.debug('[publish] No handler registered | name: %s | traceId: %s', name, traceId);
+            return;
+        }
+        for (const registration of registrations) {
+            queueMicrotask(() => {
+                // `dispatch` catches every failure path itself and never rejects - this `.catch` is an
+                // unreachable backstop, kept (and logged) rather than left floating, for the day it isn't.
+                this.dispatch({ event, registration }).catch((error) => {
+                    this.logger.error('[publish] Unexpected dispatch failure | name: %s | Error: %s', event.name, error);
+                });
+            });
+        }
+    }
+    /**
+     * Attempts/backoff come from the registration (`EventDispatchRetry`'s defaults when omitted),
+     * always with full jitter - `RetryJitterModes.FULL` decorrelates a shared-resource pile-up hardest,
+     * so many handlers retrying the same lock do not collide on the same instant a second and third
+     * time. `invokeHandler` already encodes whether that re-resolves (`BINDING_KEY`) or was captured
+     * once (`FUNCTION`) - see `buildHandlerInvoker` - so this method calls it uniformly. A handler that
+     * throws synchronously is caught exactly like one that returns a rejected promise: `execution`
+     * here is itself `async`, and JS converts a synchronous throw inside an async function body into a
+     * rejection of that function's own promise - `RetryHelper.executeWithRetry`'s attempt loop never
+     * sees the difference.
+     *
+     * `RetryHelper.executeWithRetry` is used without its own `logger` - its internal per-attempt/exhaustion
+     * logging knows nothing about the event name or `traceId`, so it cannot be the trace anyone
+     * relies on. The one line below, logged only on final failure, is.
+     */
+    async dispatch(opts) {
+        const { event, registration } = opts;
+        const { invokeHandler, description, maxAttempts, baseDelayMs } = registration;
+        let lastAttempt = 0;
+        try {
+            await core_1.RetryHelper.executeWithRetry({
+                operation: `EventBus.dispatch:${event.name}`,
+                maxAttempts,
+                backoff: {
+                    strategy: core_1.RetryBackoffStrategies.EXPONENTIAL,
+                    initialDelayMs: baseDelayMs,
+                    jitter: core_1.RetryJitterModes.FULL,
+                },
+                execution: async ({ attempt }) => {
+                    lastAttempt = attempt;
+                    await invokeHandler({ event });
+                },
+            });
+        }
+        catch (error) {
+            // The only trace this failure leaves: it is caught here and never reaches the publisher, so
+            // the event name, traceId and attempt count all have to be on this one line.
+            this.logger.error('[dispatch] Handler exhausted retries | name: %s | traceId: %s | attempts: %d | handler: %s | Error: %s', event.name, event.traceId, lastAttempt, description, error);
+        }
+    }
+}
+exports.EventBus = EventBus;
+//# sourceMappingURL=event-bus.js.map

package/dist/cjs/base/events/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../../../src/base/events/event-bus.ts"],"names":[],"mappings":"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"}

package/dist/cjs/base/events/index.d.ts

@@ -0,0 +1,3 @@
+export * from './common';
+export * from './event-bus';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/base/events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/base/events/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC"}

package/dist/cjs/base/events/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./common"), exports);
+__exportStar(require("./event-bus"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/base/events/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/base/events/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,8CAA4B"}

package/dist/cjs/base/index.d.ts

@@ -1,8 +1,10 @@
 export * from './applications';
 export * from './auth';
 export * from './components';
+export * from './configurations';
 export * from './controllers';
 export * from './datasources';
+export * from './events';
 export * from './metadata';
 export * from './middlewares';
 export * from './mixins';

package/dist/cjs/base/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/base/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAM3B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/base/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}

package/dist/cjs/base/index.js

@@ -17,14 +17,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./applications"), exports);
 __exportStar(require("./auth"), exports);
 __exportStar(require("./components"), exports);
+__exportStar(require("./configurations"), exports);
 __exportStar(require("./controllers"), exports);
 __exportStar(require("./datasources"), exports);
+__exportStar(require("./events"), exports);
 __exportStar(require("./metadata"), exports);
-// Deliberately public, not an accidental leak: core's own `base/applications/base.ts` (registers
-// `emojiFavicon`/`notFoundHandler`) and `base/middlewares/request-spy/request-spy.middleware.ts`
-// (reads `REQUEST_ID_KEY`, registers `RequestErrors`) both need these across the package boundary
-// the split introduced - core did not export this barrel before the move, but two of its own files
-// now depend on symbols that only live here.
 __exportStar(require("./middlewares"), exports);
 __exportStar(require("./mixins"), exports);
 __exportStar(require("./models"), exports);

package/dist/cjs/base/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/base/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA+B;AAC/B,yCAAuB;AACvB,+CAA6B;AAC7B,gDAA8B;AAC9B,gDAA8B;AAC9B,6CAA2B;AAC3B,iGAAiG;AACjG,iGAAiG;AACjG,kGAAkG;AAClG,mGAAmG;AACnG,6CAA6C;AAC7C,gDAA8B;AAC9B,2CAAyB;AACzB,2CAAyB;AACzB,8CAA4B;AAC5B,iDAA+B;AAC/B,oDAAkC;AAClC,6CAA2B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/base/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA+B;AAC/B,yCAAuB;AACvB,+CAA6B;AAC7B,mDAAiC;AACjC,gDAA8B;AAC9B,gDAA8B;AAC9B,2CAAyB;AACzB,6CAA2B;AAC3B,gDAA8B;AAC9B,2CAAyB;AACzB,2CAAyB;AACzB,8CAA4B;AAC5B,iDAA+B;AAC/B,oDAAkC;AAClC,6CAA2B"}

package/dist/cjs/base/metadata/index.d.ts

@@ -1,3 +1,4 @@
+export * from './injectable';
 export * from './injectors';
 export * from './persistents';
 export * from './routes';

package/dist/cjs/base/metadata/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/base/metadata/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/base/metadata/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC"}

package/dist/cjs/base/metadata/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./injectable"), exports);
 __exportStar(require("./injectors"), exports);
 __exportStar(require("./persistents"), exports);
 __exportStar(require("./routes"), exports);

package/dist/cjs/base/metadata/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/base/metadata/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B;AAC5B,gDAA8B;AAC9B,2CAAyB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/base/metadata/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B;AAC7B,8CAA4B;AAC5B,gDAA8B;AAC9B,2CAAyB"}

package/dist/cjs/base/metadata/injectable.d.ts

@@ -0,0 +1,16 @@
+import type { IArtifactMetadata, IArtifactRegistrationOptions, TBindingScope } from '../../helpers/inversion';
+/** The root stereotype: marks a class as an artifact the application registers, with its registration defaults. Every other stereotype calls it. */
+export declare const injectable: <ApplicationType = unknown>(opts: IArtifactMetadata<ApplicationType>) => ClassDecorator;
+export declare const service: <ApplicationType = unknown>(opts?: IArtifactRegistrationOptions<ApplicationType>) => ClassDecorator;
+export declare const component: <ApplicationType = unknown>(opts?: IArtifactRegistrationOptions<ApplicationType>) => ClassDecorator;
+export declare const configuration: <ApplicationType = unknown>(opts?: IArtifactRegistrationOptions<ApplicationType>) => ClassDecorator;
+/** Marks a component method as the provider of `key`. `registerArtifacts` binds the key to a lazy provider that resolves the component and calls the method; SINGLETON unless `scope` says otherwise. */
+export declare const provide: (opts: {
+    key: string;
+    scope?: TBindingScope;
+}) => MethodDecorator;
+/** The registration defaults a stereotype forwards to `@injectable`, copied field by field so an absent option stays absent. */
+export declare const pickRegistrationOptions: <ApplicationType = unknown>(opts: {
+    metadata: IArtifactRegistrationOptions<ApplicationType>;
+}) => IArtifactRegistrationOptions<ApplicationType>;
+//# sourceMappingURL=injectable.d.ts.map

package/dist/cjs/base/metadata/injectable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"injectable.d.ts","sourceRoot":"","sources":["../../../../src/base/metadata/injectable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,4BAA4B,EAC5B,aAAa,EACd,MAAM,qBAAqB,CAAC;AAK7B,oJAAoJ;AACpJ,eAAO,MAAM,UAAU,GAAI,eAAe,GAAG,OAAO,EAClD,MAAM,iBAAiB,CAAC,eAAe,CAAC,KACvC,cAoCF,CAAC;AAEF,eAAO,MAAM,OAAO,GAAI,eAAe,GAAG,OAAO,EAC/C,OAAO,4BAA4B,CAAC,eAAe,CAAC,KACnD,cAEF,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,eAAe,GAAG,OAAO,EACjD,OAAO,4BAA4B,CAAC,eAAe,CAAC,KACnD,cAEF,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,eAAe,GAAG,OAAO,EACrD,OAAO,4BAA4B,CAAC,eAAe,CAAC,KACnD,cAEF,CAAC;AACF,yMAAyM;AACzM,eAAO,MAAM,OAAO,GAAI,MAAM;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,aAAa,CAAA;CAAE,KAAG,eAWtE,CAAC;AAEF,gIAAgI;AAChI,eAAO,MAAM,uBAAuB,GAAI,eAAe,GAAG,OAAO,EAAE,MAAM;IACvE,QAAQ,EAAE,4BAA4B,CAAC,eAAe,CAAC,CAAC;CACzD,KAAG,4BAA4B,CAAC,eAAe,CA6B/C,CAAC"}

package/dist/cjs/base/metadata/injectable.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickRegistrationOptions = exports.provide = exports.configuration = exports.component = exports.service = exports.injectable = void 0;
+const bindings_1 = require("../../common/bindings");
+const inversion_1 = require("../../helpers/inversion");
+const core_1 = require("@venizia/ignis-helpers/core");
+/** The root stereotype: marks a class as an artifact the application registers, with its registration defaults. Every other stereotype calls it. */
+const injectable = (opts) => {
+    return target => {
+        if (!inversion_1.ArtifactTypes.isValid(opts.type)) {
+            throw (0, core_1.getError)({
+                message: `[injectable][${target.name}] Invalid artifact type: '${opts.type}' | Expected one of: ${[...inversion_1.ArtifactTypes.SCHEME_SET].join(', ')}`,
+            });
+        }
+        // At import time, so the failure lands where the binding is written, not at boot.
+        if (opts.binding) {
+            bindings_1.BindingNamespaces.assertArtifactNamespace({
+                namespace: opts.binding.namespace,
+                artifact: target.name,
+                caller: 'injectable',
+            });
+        }
+        const registry = inversion_1.MetadataRegistry.getInstance();
+        registry.setArtifactMetadata({ target, metadata: opts });
+        // Discovery happens HERE, at import time. A boot-time filesystem scan cannot see a compiled
+        // single-file binary, and a class exists at run time only because something imported it.
+        registry.addDiscoveredArtifact({ target });
+        // The key this class WOULD get; `registerArtifact` overwrites it with the one actually bound.
+        registry.setBindingKey({
+            target,
+            key: inversion_1.BindingKeys.build(opts.binding ?? {
+                namespace: bindings_1.ArtifactNamespaces.resolve({ type: opts.type }),
+                key: target.name,
+            }),
+            isProvisional: true,
+        });
+    };
+};
+exports.injectable = injectable;
+const service = (opts) => {
+    return (0, exports.injectable)({ type: inversion_1.ArtifactTypes.SERVICE, ...opts });
+};
+exports.service = service;
+const component = (opts) => {
+    return (0, exports.injectable)({ type: inversion_1.ArtifactTypes.COMPONENT, ...opts });
+};
+exports.component = component;
+const configuration = (opts) => {
+    return (0, exports.injectable)({ type: inversion_1.ArtifactTypes.CONFIGURATION, ...opts });
+};
+exports.configuration = configuration;
+/** Marks a component method as the provider of `key`. `registerArtifacts` binds the key to a lazy provider that resolves the component and calls the method; SINGLETON unless `scope` says otherwise. */
+const provide = (opts) => {
+    return (target, propertyKey) => {
+        inversion_1.MetadataRegistry.getInstance().addProvideMetadata({
+            target: target.constructor,
+            metadata: {
+                methodName: propertyKey,
+                key: opts.key,
+                ...(opts.scope ? { scope: opts.scope } : {}),
+            },
+        });
+    };
+};
+exports.provide = provide;
+/** The registration defaults a stereotype forwards to `@injectable`, copied field by field so an absent option stays absent. */
+const pickRegistrationOptions = (opts) => {
+    const { binding, allowOverride, scope, order, when, after } = opts.metadata;
+    const registration = {};
+    if (binding !== undefined) {
+        registration.binding = binding;
+    }
+    if (allowOverride !== undefined) {
+        registration.allowOverride = allowOverride;
+    }
+    if (scope !== undefined) {
+        registration.scope = scope;
+    }
+    if (order !== undefined) {
+        registration.order = order;
+    }
+    if (when !== undefined) {
+        registration.when = when;
+    }
+    if (after !== undefined) {
+        registration.after = after;
+    }
+    return registration;
+};
+exports.pickRegistrationOptions = pickRegistrationOptions;
+//# sourceMappingURL=injectable.js.map

package/dist/cjs/base/metadata/injectable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injectable.js","sourceRoot":"","sources":["../../../../src/base/metadata/injectable.ts"],"names":[],"mappings":"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"}

package/dist/cjs/base/metadata/injectors.d.ts

@@ -1,7 +1,16 @@
-import type { TBindingKey } from '../../helpers/inversion';
-/** Marks a property or constructor parameter for dependency injection. */
-export declare const inject: (opts: {
-    key: TBindingKey;
-    isOptional?: boolean;
-}) => (target: any, propertyName: string | symbol | undefined, parameterIndex?: number) => void;
+import type { TInjectOptions as TCoreInjectOptions } from '@venizia/ignis-inversion';
+/** Distributes over the union, so `key` and `target` stay mutually exclusive - a bare `Omit` collapses the two branches into one shape declaring both. */
+type TWithoutRegistry<T> = T extends unknown ? Omit<T, 'registry'> : never;
+/**
+ * Either a binding key or the class bound under it - never both. The shape is inversion's; the
+ * `registry` member is not, because this wrapper is the one that supplies it.
+ */
+export type TInjectOptions = TWithoutRegistry<TCoreInjectOptions>;
+/**
+ * `@inject`, bound to the kernel's registry. The container reads
+ * `MetadataRegistry.getInstance()` (`helpers/inversion/container.ts`), while inversion's own
+ * `inject` writes to its module-level registry - metadata written there is never read back.
+ */
+export declare const inject: (opts: TInjectOptions) => (target: any, propertyName: string | symbol | undefined, parameterIndex?: number) => void;
+export {};
 //# sourceMappingURL=injectors.d.ts.map

package/dist/cjs/base/metadata/injectors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"injectors.d.ts","sourceRoot":"","sources":["../../../../src/base/metadata/injectors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvD,0EAA0E;AAC1E,eAAO,MAAM,MAAM,GAAI,MAAM;IAAE,GAAG,EAAE,WAAW,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,8FAEtE,CAAC"}
+{"version":3,"file":"injectors.d.ts","sourceRoot":"","sources":["../../../../src/base/metadata/injectors.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,IAAI,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAErF,0JAA0J;AAC1J,KAAK,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,GAAG,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC,GAAG,KAAK,CAAC;AAE3E;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,gBAAgB,CAAC,kBAAkB,CAAC,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,MAAM,GAAI,MAAM,cAAc,8FAS1C,CAAC"}

package/dist/cjs/base/metadata/injectors.js

@@ -3,9 +3,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.inject = void 0;
 const inversion_1 = require("../../helpers/inversion");
 const ignis_inversion_1 = require("@venizia/ignis-inversion");
-/** Marks a property or constructor parameter for dependency injection. */
+/**
+ * `@inject`, bound to the kernel's registry. The container reads
+ * `MetadataRegistry.getInstance()` (`helpers/inversion/container.ts`), while inversion's own
+ * `inject` writes to its module-level registry - metadata written there is never read back.
+ */
 const inject = (opts) => {
-    return (0, ignis_inversion_1.inject)({ ...opts, registry: inversion_1.MetadataRegistry.getInstance() });
+    const registry = inversion_1.MetadataRegistry.getInstance();
+    // Branched, not spread: spreading widens the union back into a shape declaring both members.
+    if (opts.key === undefined) {
+        return (0, ignis_inversion_1.inject)({ target: opts.target, isOptional: opts.isOptional, registry });
+    }
+    return (0, ignis_inversion_1.inject)({ key: opts.key, isOptional: opts.isOptional, registry });
 };
 exports.inject = inject;
 //# sourceMappingURL=injectors.js.map

package/dist/cjs/base/metadata/injectors.js.map

@@ -1 +1 @@
-{"version":3,"file":"injectors.js","sourceRoot":"","sources":["../../../../src/base/metadata/injectors.ts"],"names":[],"mappings":";;;AACA,mDAAuD;AACvD,8DAAgE;AAEhE,0EAA0E;AACnE,MAAM,MAAM,GAAG,CAAC,IAAgD,EAAE,EAAE;IACzE,OAAO,IAAA,wBAAU,EAAC,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,4BAAgB,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;AAC3E,CAAC,CAAC;AAFW,QAAA,MAAM,UAEjB"}
+{"version":3,"file":"injectors.js","sourceRoot":"","sources":["../../../../src/base/metadata/injectors.ts"],"names":[],"mappings":";;;AAAA,mDAAuD;AACvD,8DAAgE;AAYhE;;;;GAIG;AACI,MAAM,MAAM,GAAG,CAAC,IAAoB,EAAE,EAAE;IAC7C,MAAM,QAAQ,GAAG,4BAAgB,CAAC,WAAW,EAAE,CAAC;IAEhD,6FAA6F;IAC7F,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,IAAA,wBAAU,EAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC;IACpF,CAAC;IAED,OAAO,IAAA,wBAAU,EAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC;AAC9E,CAAC,CAAC;AATW,QAAA,MAAM,UASjB"}

package/dist/cjs/base/metadata/persistents.d.ts

@@ -5,6 +5,5 @@ import type { AbstractEntity } from '../models';
 export declare const model: (metadata: IModelMetadata) => ClassDecorator;
 /** Registers a datasource with driver and auto-discovery settings. */
 export declare const datasource: (metadata?: IDataSourceMetadata) => ClassDecorator;
-/** Binds a repository to a model and datasource for schema auto-discovery. */
-export declare const repository: <Model extends AbstractEntity = AbstractEntity, DataSource extends IDataSource = IDataSource>(metadata: IRepositoryMetadata<Model, DataSource>) => ClassDecorator;
+export declare const repository: <Model extends AbstractEntity = AbstractEntity, DataSource extends IDataSource = IDataSource>(metadata?: IRepositoryMetadata<Model, DataSource>) => ClassDecorator;
 //# sourceMappingURL=persistents.d.ts.map

package/dist/cjs/base/metadata/persistents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persistents.d.ts","sourceRoot":"","sources":["../../../../src/base/metadata/persistents.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,mBAAmB,EAEnB,cAAc,EACd,mBAAmB,EAEpB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,oEAAoE;AACpE,eAAO,MAAM,KAAK,GAAI,UAAU,cAAc,KAAG,cA0BhD,CAAC;AAEF,sEAAsE;AACtE,eAAO,MAAM,UAAU,GAAI,WAAW,mBAAmB,KAAG,cAI3D,CAAC;AAiJF,8EAA8E;AAC9E,eAAO,MAAM,UAAU,GACrB,KAAK,SAAS,cAAc,GAAG,cAAc,EAC7C,UAAU,SAAS,WAAW,GAAG,WAAW,EAE5C,UAAU,mBAAmB,CAAC,KAAK,EAAE,UAAU,CAAC,KAC/C,cAaF,CAAC"}
+{"version":3,"file":"persistents.d.ts","sourceRoot":"","sources":["../../../../src/base/metadata/persistents.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,mBAAmB,EAEnB,cAAc,EACd,mBAAmB,EAEpB,MAAM,qBAAqB,CAAC;AAU7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhD,oEAAoE;AACpE,eAAO,MAAM,KAAK,GAAI,UAAU,cAAc,KAAG,cA4BhD,CAAC;AAEF,sEAAsE;AACtE,eAAO,MAAM,UAAU,GAAI,WAAW,mBAAmB,KAAG,cAQ3D,CAAC;AAqMF,eAAO,MAAM,UAAU,GACrB,KAAK,SAAS,cAAc,GAAG,cAAc,EAC7C,UAAU,SAAS,WAAW,GAAG,WAAW,EAE5C,WAAW,mBAAmB,CAAC,KAAK,EAAE,UAAU,CAAC,KAChD,cAeF,CAAC"}

package/dist/cjs/base/metadata/persistents.js

@@ -3,12 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.repository = exports.datasource = exports.model = void 0;
 const bindings_1 = require("../../common/bindings");
 const inversion_1 = require("../../helpers/inversion");
-const core_1 = require("@venizia/ignis-helpers/core");
 const common_1 = require("@venizia/ignis-helpers/common");
+const core_1 = require("@venizia/ignis-helpers/core");
 const datasources_1 = require("../datasources");
+const injectable_1 = require("./injectable");
 /** Registers a model class with its static schema and relations. */
 const model = (metadata) => {
     return target => {
+        (0, injectable_1.injectable)({ type: inversion_1.ArtifactTypes.MODEL, ...(0, injectable_1.pickRegistrationOptions)({ metadata }) })(target);
         const defaultLimit = metadata.settings?.defaultLimit;
         if (defaultLimit !== undefined && (!Number.isInteger(defaultLimit) || defaultLimit <= 0)) {
             throw (0, core_1.getError)({
@@ -35,6 +37,10 @@ exports.model = model;
 /** Registers a datasource with driver and auto-discovery settings. */
 const datasource = (metadata) => {
     return target => {
+        (0, injectable_1.injectable)({
+            type: inversion_1.ArtifactTypes.DATASOURCE,
+            ...(0, injectable_1.pickRegistrationOptions)({ metadata: metadata ?? {} }),
+        })(target);
         inversion_1.MetadataRegistry.getInstance().setDataSourceMetadata({ target, metadata });
     };
 };
@@ -86,11 +92,17 @@ const registerDataSourceInjection = (opts) => {
     const ownInjects = Reflect.getOwnMetadata(inversion_1.MetadataKeys.INJECT, target);
     const injectAtIndex0 = ownInjects?.find(entry => entry?.index === 0);
     if (injectAtIndex0) {
-        const injectKey = injectAtIndex0.key;
+        // `@inject({ target })` carries no key; read the one recorded on the class. The function form
+        // resolves through the same helper the container uses, so both paths read one class.
+        const injectedTarget = injectAtIndex0.target
+            ? (0, inversion_1.resolveInjectTarget)(injectAtIndex0.target)
+            : undefined;
+        const injectKey = injectAtIndex0.key ??
+            (injectedTarget ? registry.getBindingKey({ target: injectedTarget }) : undefined);
         const isDataSourceKey = typeof injectKey === 'string' && injectKey.startsWith(`${bindings_1.BindingNamespaces.DATASOURCE}.`);
         if (!isDataSourceKey) {
             throw (0, core_1.getError)({
-                message: `[@repository][${target.name}] Invalid constructor | First parameter must be a DataSource | Found @inject with key: '${injectKey.toString()}' | Expected key starting with '${bindings_1.BindingNamespaces.DATASOURCE}.'`,
+                message: `[@repository][${target.name}] Invalid constructor | First parameter must be a DataSource | Found @inject with key: '${String(injectKey)}' | Expected key starting with '${bindings_1.BindingNamespaces.DATASOURCE}.'`,
             });
         }
         return;
@@ -130,15 +142,44 @@ const resolveRepositoryMetadata = (opts) => {
     };
 };
 /** Binds a repository to a model and datasource for schema auto-discovery. */
+/** A bare `@repository()` on a subclass reuses the model and datasource its nearest decorated parent declared; the registration options (`binding`, `when`, ...) are never inherited, so the subclass registers under its own name. */
+const inheritRepositoryMetadata = (opts) => {
+    // Own metadata does not exist yet at decoration time, so this read walks the prototype chain.
+    const inherited = opts.registry.getRepositoryMetadata({ target: opts.target });
+    if (!inherited) {
+        throw (0, core_1.getError)({
+            message: `[@repository][${opts.target.name}] No metadata given and no decorated repository above it in the prototype chain | pass { model, dataSource } or decorate the parent`,
+        });
+    }
+    const { model: parentModel, dataSource: parentDataSource, operationScope } = inherited;
+    return { model: parentModel, dataSource: parentDataSource, operationScope };
+};
+const applyRepositoryMetadata = (opts) => {
+    const { metadata, registration, target, registry } = opts;
+    (0, injectable_1.injectable)({
+        type: inversion_1.ArtifactTypes.REPOSITORY,
+        ...(0, injectable_1.pickRegistrationOptions)({ metadata: registration }),
+    })(target);
+    const resolved = resolveRepositoryMetadata({ metadata, target, registry });
+    // `_resolved` is an internal cache field, not part of the public IRepositoryMetadata surface callers author - it is added here, so the merged literal needs the widened local type.
+    registry.setRepositoryMetadata({
+        target,
+        metadata: { ...metadata, _resolved: resolved },
+    });
+};
 const repository = (metadata) => {
     return target => {
         const registry = inversion_1.MetadataRegistry.getInstance();
-        const resolved = resolveRepositoryMetadata({ metadata, target, registry });
-        // `_resolved` is an internal cache field, not part of the public IRepositoryMetadata surface callers author - it is added here, so the merged literal needs the widened local type.
-        registry.setRepositoryMetadata({
-            target,
-            metadata: { ...metadata, _resolved: resolved },
-        });
+        if (!metadata) {
+            applyRepositoryMetadata({
+                metadata: inheritRepositoryMetadata({ target, registry }),
+                registration: {},
+                target,
+                registry,
+            });
+            return;
+        }
+        applyRepositoryMetadata({ metadata, registration: metadata, target, registry });
     };
 };
 exports.repository = repository;