@composed-di/instrumentation-core 0.6.0-alpha

package/dist/redactingInstrumentation.d.ts

@@ -0,0 +1,120 @@
+import type { DisposeContext, EventSpan, InitializeContext, MethodCallContext, ServiceInstrumentation } from './serviceInstrumentation';
+import type { ServiceKey } from '@composed-di/core';
+/**
+ * The placeholder that replaces a redacted value when no custom
+ * transform is given for it.
+ */
+export declare const REDACTED_VALUE = "[REDACTED]";
+/**
+ * Custom masking for one included property, narrowed to the exact
+ * method named when {@link RedactionRuleBuilder.redact} is called.
+ * Omitting a side fully blanks it with {@link REDACTED_VALUE}; providing
+ * one lets you report a partial mask instead (e.g. the last 4 digits of
+ * a card number) — both always return a `string`, the masked
+ * representation to report in place of the real value.
+ */
+export type Mask<T, K extends Extract<keyof T, string>> = T[K] extends (...args: infer A) => infer R ? {
+    maskArgs?: (...args: A) => string;
+    maskResult?: (result: R) => string;
+} : never;
+/**
+ * Marks a service — or specific properties of it — as sensitive, so the
+ * values flowing through its events are redacted. Returned by
+ * {@link RedactionRuleBuilder.build}, which is the only way to construct
+ * one — the `redactAll`/per-property merge logic lives entirely inside
+ * `maskArgs`/`maskResult`, so callers never need to know how a rule
+ * reached its decision, only what to do with it.
+ */
+export interface RedactionRule<T> {
+    readonly key: ServiceKey<T>;
+    /**
+     * The args to report for a call to `functionName`: unchanged if not
+     * redacted, otherwise blanked or run through a custom `maskArgs`.
+     */
+    maskArgs(functionName: string, args: readonly unknown[]): readonly unknown[];
+    /**
+     * The value to report for a success outcome: unchanged if not
+     * redacted, otherwise blanked or run through a custom `maskResult`.
+     * Omit `functionName` to ask about the initialize result (the service
+     * instance itself), which only the rule's `redactAll` default touches.
+     */
+    maskResult(functionName: string | undefined, result: unknown): unknown;
+}
+/**
+ * Fluent, single-key rule builder returned by {@link redactionRule}.
+ * `redactAll`, `redact`, and `exclude` all merge into the same rule —
+ * call them in any combination, in any order; the more specific
+ * per-property calls (`redact`/`exclude`) always win over the blanket
+ * `redactAll` default for the properties they name.
+ *
+ * @example
+ * ```ts
+ * const rules = [
+ *   redactionRule(SecretClientKey)
+ *     .redactAll()
+ *     .build(), // whole service is sensitive
+ *   redactionRule(BillingKey)
+ *     .redactAll()
+ *     .redact('chargeCard', { maskResult: (card) => `card ending in ${card.number.slice(-4)}` })
+ *     .exclude('ping') // redact everything except this, with one custom mask
+ *     .build(),
+ *   redactionRule(VaultKey)
+ *     .redact('getSecret')
+ *     .build(), // only this call, nothing else
+ * ];
+ * ```
+ */
+export declare class RedactionRuleBuilder<T> {
+    private readonly key;
+    private redactAllFlag;
+    private hasRedact;
+    private readonly overrides;
+    constructor(key: ServiceKey<T>);
+    /** Redacts every property, plus the initialize result, by default. */
+    redactAll(): this;
+    /**
+     * Marks one property (method) as redacted, with optional custom
+     * masking. Call repeatedly for several properties. Overrides
+     * `redactAll`/`exclude` for this specific property.
+     */
+    redact<K extends Extract<keyof T, string>>(name: K, mask?: Mask<T, K>): this;
+    /**
+     * Marks one or more properties as explicitly NOT redacted, overriding
+     * `redactAll` for just these.
+     */
+    exclude(...names: Extract<keyof T, string>[]): this;
+    build(): RedactionRule<any>;
+}
+export declare function redactionRule<T>(key: ServiceKey<T>): RedactionRuleBuilder<T>;
+/**
+ * A ServiceInstrumentation decorator that redacts sensitive values before
+ * they reach the wrapped instrumentation. Works with any implementation via
+ * delegation: arguments in MethodCallContext and success values in
+ * EventOutcome are replaced (wholesale, or via a custom transform)
+ * before the delegate ever sees them — whatever it captures or exports
+ * is already scrubbed.
+ *
+ * Failure outcomes are passed through unchanged so error reporting keeps
+ * working; keep secrets out of error messages at the throwing site.
+ *
+ * @example
+ * ```ts
+ * const instrumentation = new RedactingInstrumentation(
+ *   new OTELInstrumentation({ captureArguments: true, captureResults: true }),
+ *   [
+ *     redactionRule(SecretClientKey).redactAll().build(), // whole service is sensitive
+ *     redactionRule(VaultKey).redact('getSecret').build(), // only this call
+ *     redactionRule(HealthKey).redactAll().exclude('ping').build(), // everything but this call
+ *   ],
+ * );
+ * ```
+ */
+export declare class RedactingInstrumentation implements ServiceInstrumentation {
+    private readonly delegate;
+    private readonly rules;
+    constructor(delegate: ServiceInstrumentation, rules: readonly RedactionRule<any>[]);
+    onInitialize(context: InitializeContext): EventSpan | void;
+    onDispose(context: DisposeContext): EventSpan | void;
+    onMethodCall(context: MethodCallContext): EventSpan | void;
+}
+//# sourceMappingURL=redactingInstrumentation.d.ts.map

package/dist/redactingInstrumentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redactingInstrumentation.d.ts","sourceRoot":"","sources":["../src/redactingInstrumentation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EAEd,SAAS,EACT,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACvB,MAAM,0BAA0B,CAAA;AACjC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnD;;;GAGG;AACH,eAAO,MAAM,cAAc,eAAe,CAAA;AAE1C;;;;;;;GAOG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CACrE,GAAG,IAAI,EAAE,MAAM,CAAC,KACb,MAAM,CAAC,GACR;IACE,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,MAAM,CAAA;IACjC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAA;CACnC,GACD,KAAK,CAAA;AAeT;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;IAE3B;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,OAAO,EAAE,CAAA;IAE5E;;;;;OAKG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAA;CACvE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,oBAAoB,CAAC,CAAC;IAKrB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAJhC,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuC;gBAEpC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;IAE/C,sEAAsE;IACtE,SAAS,IAAI,IAAI;IAMjB;;;;OAIG;IACH,MAAM,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI;IAM5E;;;OAGG;IACH,OAAO,CAAC,GAAG,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,GAAG,IAAI;IAOnD,KAAK,IAAI,aAAa,CAAC,GAAG,CAAC;CA0C5B;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAE5E;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,wBAAyB,YAAW,sBAAsB;IAEnE,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,QAAQ,EAAE,sBAAsB,EAChC,KAAK,EAAE,SAAS,aAAa,CAAC,GAAG,CAAC,EAAE;IAGvD,YAAY,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI;IAK1D,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI;IAKpD,YAAY,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI;CAY3D"}

package/dist/redactingInstrumentation.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedactingInstrumentation = exports.RedactionRuleBuilder = exports.REDACTED_VALUE = void 0;
+exports.redactionRule = redactionRule;
+/**
+ * The placeholder that replaces a redacted value when no custom
+ * transform is given for it.
+ */
+exports.REDACTED_VALUE = '[REDACTED]';
+/**
+ * Fluent, single-key rule builder returned by {@link redactionRule}.
+ * `redactAll`, `redact`, and `exclude` all merge into the same rule —
+ * call them in any combination, in any order; the more specific
+ * per-property calls (`redact`/`exclude`) always win over the blanket
+ * `redactAll` default for the properties they name.
+ *
+ * @example
+ * ```ts
+ * const rules = [
+ *   redactionRule(SecretClientKey)
+ *     .redactAll()
+ *     .build(), // whole service is sensitive
+ *   redactionRule(BillingKey)
+ *     .redactAll()
+ *     .redact('chargeCard', { maskResult: (card) => `card ending in ${card.number.slice(-4)}` })
+ *     .exclude('ping') // redact everything except this, with one custom mask
+ *     .build(),
+ *   redactionRule(VaultKey)
+ *     .redact('getSecret')
+ *     .build(), // only this call, nothing else
+ * ];
+ * ```
+ */
+class RedactionRuleBuilder {
+    constructor(key) {
+        this.key = key;
+        this.redactAllFlag = false;
+        this.hasRedact = false;
+        this.overrides = {};
+    }
+    /** Redacts every property, plus the initialize result, by default. */
+    redactAll() {
+        this.redactAllFlag = true;
+        this.hasRedact = true;
+        return this;
+    }
+    /**
+     * Marks one property (method) as redacted, with optional custom
+     * masking. Call repeatedly for several properties. Overrides
+     * `redactAll`/`exclude` for this specific property.
+     */
+    redact(name, mask) {
+        this.overrides[name] = Object.assign({ redacted: true }, mask);
+        this.hasRedact = true;
+        return this;
+    }
+    /**
+     * Marks one or more properties as explicitly NOT redacted, overriding
+     * `redactAll` for just these.
+     */
+    exclude(...names) {
+        for (const name of names) {
+            this.overrides[name] = { redacted: false };
+        }
+        return this;
+    }
+    build() {
+        // `exclude` alone never redacts anything — at least one call to
+        // `redactAll`/`redact` is required for this rule to have any effect.
+        if (!this.hasRedact) {
+            throw new Error(`redactionRule(${this.key.name}) has no effect: call .redactAll() and/or .redact(...) ` +
+                'before .build() — .exclude() alone never redacts anything.');
+        }
+        const redactAllFlag = this.redactAllFlag;
+        const overrides = this.overrides;
+        return {
+            key: this.key,
+            maskArgs(functionName, args) {
+                const override = overrides[functionName];
+                const redacted = override ? override.redacted : redactAllFlag;
+                if (!redacted) {
+                    return args;
+                }
+                return (override === null || override === void 0 ? void 0 : override.maskArgs)
+                    ? // A custom mask reports one string for the whole call,
+                        // rather than a value per argument.
+                        [override.maskArgs(...args)]
+                    : // Replace each argument rather than the whole array, so the
+                        // delegate still sees the call's arity.
+                        args.map(() => exports.REDACTED_VALUE);
+            },
+            maskResult(functionName, result) {
+                const override = functionName === undefined ? undefined : overrides[functionName];
+                const redacted = override ? override.redacted : redactAllFlag;
+                if (!redacted) {
+                    return result;
+                }
+                return (override === null || override === void 0 ? void 0 : override.maskResult)
+                    ? override.maskResult(result)
+                    : exports.REDACTED_VALUE;
+            },
+        };
+    }
+}
+exports.RedactionRuleBuilder = RedactionRuleBuilder;
+function redactionRule(key) {
+    return new RedactionRuleBuilder(key);
+}
+/**
+ * A ServiceInstrumentation decorator that redacts sensitive values before
+ * they reach the wrapped instrumentation. Works with any implementation via
+ * delegation: arguments in MethodCallContext and success values in
+ * EventOutcome are replaced (wholesale, or via a custom transform)
+ * before the delegate ever sees them — whatever it captures or exports
+ * is already scrubbed.
+ *
+ * Failure outcomes are passed through unchanged so error reporting keeps
+ * working; keep secrets out of error messages at the throwing site.
+ *
+ * @example
+ * ```ts
+ * const instrumentation = new RedactingInstrumentation(
+ *   new OTELInstrumentation({ captureArguments: true, captureResults: true }),
+ *   [
+ *     redactionRule(SecretClientKey).redactAll().build(), // whole service is sensitive
+ *     redactionRule(VaultKey).redact('getSecret').build(), // only this call
+ *     redactionRule(HealthKey).redactAll().exclude('ping').build(), // everything but this call
+ *   ],
+ * );
+ * ```
+ */
+class RedactingInstrumentation {
+    constructor(delegate, rules) {
+        this.delegate = delegate;
+        this.rules = rules;
+    }
+    onInitialize(context) {
+        var _a, _b;
+        const rule = this.rules.find((r) => r.key === context.key);
+        return redactSpan((_b = (_a = this.delegate).onInitialize) === null || _b === void 0 ? void 0 : _b.call(_a, context), rule);
+    }
+    onDispose(context) {
+        var _a, _b;
+        // Dispose carries no arguments and no result value; nothing to redact.
+        return (_b = (_a = this.delegate).onDispose) === null || _b === void 0 ? void 0 : _b.call(_a, context);
+    }
+    onMethodCall(context) {
+        var _a, _b;
+        const rule = this.rules.find((r) => r.key === context.key);
+        const span = (_b = (_a = this.delegate).onMethodCall) === null || _b === void 0 ? void 0 : _b.call(_a, rule
+            ? Object.assign(Object.assign({}, context), { args: rule.maskArgs(context.functionName, context.args) }) : context);
+        return redactSpan(span, rule, context.functionName);
+    }
+}
+exports.RedactingInstrumentation = RedactingInstrumentation;
+/**
+ * Wraps the delegate's EventSpan so success values are redacted before
+ * `end` sees them, by delegating to the rule's `maskResult`. `run` (and
+ * any future fields) pass through untouched. `functionName` is omitted
+ * for the initialize result (the instance itself).
+ */
+function redactSpan(span, rule, functionName) {
+    if (!rule || !span) {
+        return span;
+    }
+    const end = span.end.bind(span);
+    return Object.assign(Object.assign({}, span), { end: (outcome) => end(outcome.type === 'success'
+            ? {
+                type: 'success',
+                value: rule.maskResult(functionName, outcome.value),
+            }
+            : outcome) });
+}
+//# sourceMappingURL=redactingInstrumentation.js.map

package/dist/redactingInstrumentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redactingInstrumentation.js","sourceRoot":"","sources":["../src/redactingInstrumentation.ts"],"names":[],"mappings":";;;AAgLA,sCAEC;AAxKD;;;GAGG;AACU,QAAA,cAAc,GAAG,YAAY,CAAA;AA0D1C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAa,oBAAoB;IAK/B,YAA6B,GAAkB;QAAlB,QAAG,GAAH,GAAG,CAAe;QAJvC,kBAAa,GAAG,KAAK,CAAA;QACrB,cAAS,GAAG,KAAK,CAAA;QACR,cAAS,GAAqC,EAAE,CAAA;IAEf,CAAC;IAEnD,sEAAsE;IACtE,SAAS;QACP,IAAI,CAAC,aAAa,GAAG,IAAI,CAAA;QACzB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAA;QACrB,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAqC,IAAO,EAAE,IAAiB;QACnE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,mBAAK,QAAQ,EAAE,IAAI,IAAK,IAAI,CAAE,CAAA;QAClD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAA;QACrB,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,GAAG,KAAiC;QAC1C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAA;QAC5C,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,KAAK;QACH,gEAAgE;QAChE,qEAAqE;QACrE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,iBAAiB,IAAI,CAAC,GAAG,CAAC,IAAI,yDAAyD;gBACrF,4DAA4D,CAC/D,CAAA;QACH,CAAC;QAED,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,CAAA;QACxC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAA;QAEhC,OAAO;YACL,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,QAAQ,CAAC,YAAY,EAAE,IAAI;gBACzB,MAAM,QAAQ,GAAG,SAAS,CAAC,YAAY,CAAC,CAAA;gBACxC,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAA;gBAC7D,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACd,OAAO,IAAI,CAAA;gBACb,CAAC;gBACD,OAAO,CAAA,QAAQ,aAAR,QAAQ,uBAAR,QAAQ,CAAE,QAAQ;oBACvB,CAAC,CAAC,uDAAuD;wBACvD,oCAAoC;wBACpC,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC;oBAC9B,CAAC,CAAC,4DAA4D;wBAC5D,wCAAwC;wBACxC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,sBAAc,CAAC,CAAA;YACpC,CAAC;YACD,UAAU,CAAC,YAAY,EAAE,MAAM;gBAC7B,MAAM,QAAQ,GACZ,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,CAAA;gBAClE,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAA;gBAC7D,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACd,OAAO,MAAM,CAAA;gBACf,CAAC;gBACD,OAAO,CAAA,QAAQ,aAAR,QAAQ,uBAAR,QAAQ,CAAE,UAAU;oBACzB,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC;oBAC7B,CAAC,CAAC,sBAAc,CAAA;YACpB,CAAC;SACoB,CAAA;IACzB,CAAC;CACF;AA9ED,oDA8EC;AAED,SAAgB,aAAa,CAAI,GAAkB;IACjD,OAAO,IAAI,oBAAoB,CAAC,GAAG,CAAC,CAAA;AACtC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAa,wBAAwB;IACnC,YACmB,QAAgC,EAChC,KAAoC;QADpC,aAAQ,GAAR,QAAQ,CAAwB;QAChC,UAAK,GAAL,KAAK,CAA+B;IACpD,CAAC;IAEJ,YAAY,CAAC,OAA0B;;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;QAC1D,OAAO,UAAU,CAAC,MAAA,MAAA,IAAI,CAAC,QAAQ,EAAC,YAAY,mDAAG,OAAO,CAAC,EAAE,IAAI,CAAC,CAAA;IAChE,CAAC;IAED,SAAS,CAAC,OAAuB;;QAC/B,uEAAuE;QACvE,OAAO,MAAA,MAAA,IAAI,CAAC,QAAQ,EAAC,SAAS,mDAAG,OAAO,CAAC,CAAA;IAC3C,CAAC;IAED,YAAY,CAAC,OAA0B;;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;QAC1D,MAAM,IAAI,GAAG,MAAA,MAAA,IAAI,CAAC,QAAQ,EAAC,YAAY,mDACrC,IAAI;YACF,CAAC,iCACM,OAAO,KACV,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,IAE3D,CAAC,CAAC,OAAO,CACZ,CAAA;QACD,OAAO,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;IACrD,CAAC;CACF;AA5BD,4DA4BC;AAED;;;;;GAKG;AACH,SAAS,UAAU,CACjB,IAAsB,EACtB,IAAoC,EACpC,YAAqB;IAErB,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,OAAO,IAAI,CAAA;IACb,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC/B,uCACK,IAAI,KACP,GAAG,EAAE,CAAC,OAAqB,EAAE,EAAE,CAC7B,GAAG,CACD,OAAO,CAAC,IAAI,KAAK,SAAS;YACxB,CAAC,CAAC;gBACE,IAAI,EAAE,SAAS;gBACf,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,YAAY,EAAE,OAAO,CAAC,KAAK,CAAC;aACpD;YACH,CAAC,CAAC,OAAO,CACZ,IACJ;AACH,CAAC"}

package/dist/redaction.d.ts

@@ -0,0 +1,91 @@
+import type { ServiceKey } from '@composed-di/core';
+/**
+ * The placeholder that replaces a redacted value when no custom
+ * transform is given for it.
+ */
+export declare const REDACTED_VALUE = "[REDACTED]";
+/**
+ * Custom masking for one included property, narrowed to the exact
+ * method named when {@link RedactionRuleBuilder.redact} is called.
+ * Omitting a side fully blanks it with {@link REDACTED_VALUE}; providing
+ * one lets you report a partial mask instead (e.g. the last 4 digits of
+ * a card number) — both always return a `string`, the masked
+ * representation to report in place of the real value.
+ */
+export type Mask<T, K extends Extract<keyof T, string>> = T[K] extends (...args: infer A) => infer R ? {
+    maskArgs?: (...args: A) => string;
+    maskResult?: (result: R) => string;
+} : never;
+/**
+ * Marks a service — or specific properties of it — as sensitive, so the
+ * values flowing through its events are redacted. Passed to
+ * {@link instrument} via InstrumentOptions.redactionRules and applied
+ * centrally, after the capture flags: values a rule matches are scrubbed
+ * before the instrumentation ever sees them, and when capture is off
+ * there is nothing to redact. Returned by
+ * {@link RedactionRuleBuilder.build}, which is the only way to construct
+ * one — the `redactAll`/per-property merge logic lives entirely inside
+ * `maskArgs`/`maskResult`, so callers never need to know how a rule
+ * reached its decision, only what to do with it.
+ */
+export interface RedactionRule<T> {
+    readonly key: ServiceKey<T>;
+    /**
+     * The args to report for a call to `functionName`: unchanged if not
+     * redacted, otherwise blanked or run through a custom `maskArgs`.
+     */
+    maskArgs(functionName: string, args: readonly unknown[]): readonly unknown[];
+    /**
+     * The value to report for a method call's success outcome: unchanged
+     * if not redacted, otherwise blanked or run through a custom
+     * `maskResult`.
+     */
+    maskResult(functionName: string, result: unknown): unknown;
+}
+/**
+ * Fluent, single-key rule builder returned by {@link redactionRule}.
+ * `redactAll`, `redact`, and `exclude` all merge into the same rule —
+ * call them in any combination, in any order; the more specific
+ * per-property calls (`redact`/`exclude`) always win over the blanket
+ * `redactAll` default for the properties they name.
+ *
+ * @example
+ * ```ts
+ * const rules = [
+ *   redactionRule(SecretClientKey)
+ *     .redactAll()
+ *     .build(), // whole service is sensitive
+ *   redactionRule(BillingKey)
+ *     .redactAll()
+ *     .redact('chargeCard', { maskResult: (card) => `card ending in ${card.number.slice(-4)}` })
+ *     .exclude('ping') // redact everything except this, with one custom mask
+ *     .build(),
+ *   redactionRule(VaultKey)
+ *     .redact('getSecret')
+ *     .build(), // only this call, nothing else
+ * ];
+ * ```
+ */
+export declare class RedactionRuleBuilder<T> {
+    private readonly key;
+    private redactAllFlag;
+    private hasRedact;
+    private readonly overrides;
+    constructor(key: ServiceKey<T>);
+    /** Redacts every property by default. */
+    redactAll(): this;
+    /**
+     * Marks one property (method) as redacted, with optional custom
+     * masking. Call repeatedly for several properties. Overrides
+     * `redactAll`/`exclude` for this specific property.
+     */
+    redact<K extends Extract<keyof T, string>>(name: K, mask?: Mask<T, K>): this;
+    /**
+     * Marks one or more properties as explicitly NOT redacted, overriding
+     * `redactAll` for just these.
+     */
+    exclude(...names: Extract<keyof T, string>[]): this;
+    build(): RedactionRule<any>;
+}
+export declare function redactionRule<T>(key: ServiceKey<T>): RedactionRuleBuilder<T>;
+//# sourceMappingURL=redaction.d.ts.map

package/dist/redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.d.ts","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnD;;;GAGG;AACH,eAAO,MAAM,cAAc,eAAe,CAAA;AAE1C;;;;;;;GAOG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CACrE,GAAG,IAAI,EAAE,MAAM,CAAC,KACb,MAAM,CAAC,GACR;IACE,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,MAAM,CAAA;IACjC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAA;CACnC,GACD,KAAK,CAAA;AAeT;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;IAE3B;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,OAAO,EAAE,CAAA;IAE5E;;;;OAIG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAA;CAC3D;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,oBAAoB,CAAC,CAAC;IAKrB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAJhC,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuC;gBAEpC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;IAE/C,yCAAyC;IACzC,SAAS,IAAI,IAAI;IAMjB;;;;OAIG;IACH,MAAM,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI;IAM5E;;;OAGG;IACH,OAAO,CAAC,GAAG,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,GAAG,IAAI;IAOnD,KAAK,IAAI,aAAa,CAAC,GAAG,CAAC;CAyC5B;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAE5E"}

package/dist/redaction.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedactionRuleBuilder = exports.REDACTED_VALUE = void 0;
+exports.redactionRule = redactionRule;
+/**
+ * The placeholder that replaces a redacted value when no custom
+ * transform is given for it.
+ */
+exports.REDACTED_VALUE = '[REDACTED]';
+/**
+ * Fluent, single-key rule builder returned by {@link redactionRule}.
+ * `redactAll`, `redact`, and `exclude` all merge into the same rule —
+ * call them in any combination, in any order; the more specific
+ * per-property calls (`redact`/`exclude`) always win over the blanket
+ * `redactAll` default for the properties they name.
+ *
+ * @example
+ * ```ts
+ * const rules = [
+ *   redactionRule(SecretClientKey)
+ *     .redactAll()
+ *     .build(), // whole service is sensitive
+ *   redactionRule(BillingKey)
+ *     .redactAll()
+ *     .redact('chargeCard', { maskResult: (card) => `card ending in ${card.number.slice(-4)}` })
+ *     .exclude('ping') // redact everything except this, with one custom mask
+ *     .build(),
+ *   redactionRule(VaultKey)
+ *     .redact('getSecret')
+ *     .build(), // only this call, nothing else
+ * ];
+ * ```
+ */
+class RedactionRuleBuilder {
+    constructor(key) {
+        this.key = key;
+        this.redactAllFlag = false;
+        this.hasRedact = false;
+        this.overrides = {};
+    }
+    /** Redacts every property by default. */
+    redactAll() {
+        this.redactAllFlag = true;
+        this.hasRedact = true;
+        return this;
+    }
+    /**
+     * Marks one property (method) as redacted, with optional custom
+     * masking. Call repeatedly for several properties. Overrides
+     * `redactAll`/`exclude` for this specific property.
+     */
+    redact(name, mask) {
+        this.overrides[name] = Object.assign({ redacted: true }, mask);
+        this.hasRedact = true;
+        return this;
+    }
+    /**
+     * Marks one or more properties as explicitly NOT redacted, overriding
+     * `redactAll` for just these.
+     */
+    exclude(...names) {
+        for (const name of names) {
+            this.overrides[name] = { redacted: false };
+        }
+        return this;
+    }
+    build() {
+        // `exclude` alone never redacts anything — at least one call to
+        // `redactAll`/`redact` is required for this rule to have any effect.
+        if (!this.hasRedact) {
+            throw new Error(`redactionRule(${this.key.name}) has no effect: call .redactAll() and/or .redact(...) ` +
+                'before .build() — .exclude() alone never redacts anything.');
+        }
+        const redactAllFlag = this.redactAllFlag;
+        const overrides = this.overrides;
+        return {
+            key: this.key,
+            maskArgs(functionName, args) {
+                const override = overrides[functionName];
+                const redacted = override ? override.redacted : redactAllFlag;
+                if (!redacted) {
+                    return args;
+                }
+                return (override === null || override === void 0 ? void 0 : override.maskArgs)
+                    ? // A custom mask reports one string for the whole call,
+                        // rather than a value per argument.
+                        [override.maskArgs(...args)]
+                    : // Replace each argument rather than the whole array, so the
+                        // delegate still sees the call's arity.
+                        args.map(() => exports.REDACTED_VALUE);
+            },
+            maskResult(functionName, result) {
+                const override = overrides[functionName];
+                const redacted = override ? override.redacted : redactAllFlag;
+                if (!redacted) {
+                    return result;
+                }
+                return (override === null || override === void 0 ? void 0 : override.maskResult)
+                    ? override.maskResult(result)
+                    : exports.REDACTED_VALUE;
+            },
+        };
+    }
+}
+exports.RedactionRuleBuilder = RedactionRuleBuilder;
+function redactionRule(key) {
+    return new RedactionRuleBuilder(key);
+}
+//# sourceMappingURL=redaction.js.map

package/dist/redaction.js.map

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

package/dist/serviceInstrumentation.d.ts

@@ -0,0 +1,151 @@
+import type { ServiceKey } from '@composed-di/core';
+/**
+ * A handle representing a single in-flight operation (initialization,
+ * disposal, or method call), returned by a ServiceInstrumentation when the
+ * operation starts.
+ *
+ * `end` is invoked exactly once when the operation finishes, so
+ * implementations can close over per-call state (a start time, a span
+ * handle, a correlation id) without any bookkeeping to pair concurrent
+ * start/finish events.
+ */
+export interface EventSpan {
+    /**
+     * Wrapper around the operation itself. The instrumented factory invokes
+     * the operation as `run(() => operation())`, so the instrumentation can
+     * establish ambient state that the operation body and its async
+     * continuations inherit — this is what lets spans of nested service
+     * calls form a parent-child hierarchy.
+     *
+     * Implementations must invoke `fn` exactly once, synchronously, and
+     * return its result unchanged (for async operations, the promise itself).
+     * `end` is still delivered separately when the operation finishes.
+     *
+     * @param fn - A thunk that performs the operation.
+     * @return The value returned by `fn`.
+     */
+    run<T>(fn: () => T): T;
+    /**
+     * Invoked exactly once when the operation finishes, whether it succeeded
+     * or failed. For methods that return a promise, this fires when the
+     * promise settles, not when the method returns. On failure, the error is
+     * rethrown to the caller after this is invoked.
+     *
+     * Whether to retain or log the outcome is the implementation's choice;
+     * values are passed by reference, so implementations must not mutate them.
+     *
+     * @param outcome - How the operation finished, and its value or error.
+     * @return void
+     */
+    end(outcome: EventOutcome): void;
+}
+/**
+ * How an operation finished, delivered to EventSpan.end: `success` may
+ * carry the return or resolved value of a method call (initialize and
+ * dispose outcomes never carry one); `failure` carries the error that was
+ * thrown or rejected.
+ *
+ * Whether `value` is present is decided by {@link instrument}, not by the
+ * implementation: it is absent unless result capture is enabled in the
+ * InstrumentOptions, and holds the redacted value when a redaction rule
+ * matches. Implementations must record the value exactly when it is
+ * present (`'value' in outcome` — a captured `undefined` return is
+ * delivered as a present `value: undefined`) and must not record any
+ * result when it is absent.
+ */
+export type EventOutcome = {
+    type: 'success';
+    value?: unknown;
+} | {
+    type: 'failure';
+    error: unknown;
+};
+/**
+ * Context of a service initialization, delivered to onInitialize.
+ * Future fields are added here rather than as extra parameters.
+ */
+export interface InitializeContext {
+    /**
+     * The unique identifier of the service that is being initialized.
+     */
+    key: ServiceKey<unknown>;
+}
+/**
+ * Context of a service disposal, delivered to onDispose.
+ * Future fields are added here rather than as extra parameters.
+ */
+export interface DisposeContext {
+    /**
+     * The unique identifier of the service that is being disposed.
+     */
+    key: ServiceKey<unknown>;
+}
+/**
+ * Context of a method invocation, delivered to onMethodCall.
+ * Future fields are added here rather than as extra parameters.
+ */
+export interface MethodCallContext {
+    /**
+     * The unique identifier of the service the method belongs to.
+     */
+    key: ServiceKey<unknown>;
+    /**
+     * The name of the class implementing the service (the instance's
+     * constructor name), which may differ from `key.name`. Undefined for
+     * services that are not instances of a named class, such as plain
+     * object literals.
+     */
+    className?: string;
+    /**
+     * The name of the method that is being called.
+     */
+    functionName: string;
+    /**
+     * The arguments to report for this call, passed by reference;
+     * implementations must not mutate them.
+     *
+     * Whether they are present is decided by {@link instrument}, not by the
+     * implementation: absent unless argument capture is enabled in the
+     * InstrumentOptions, and already redacted when a redaction rule matches.
+     * Implementations must record the arguments exactly when present and
+     * must not record any arguments when absent.
+     */
+    args?: readonly unknown[];
+}
+/**
+ * Interface for instrumenting services wrapped by {@link instrument}.
+ * Implement this interface to observe lifecycle events and method calls
+ * of the instrumented services.
+ *
+ * Instrumentation is strictly observational: implementations see every
+ * operation but must never alter it — see the EventSpan contract.
+ *
+ * Each method is invoked when the corresponding operation starts and may
+ * return an EventSpan that is notified when that operation finishes.
+ * Returning nothing opts out of completion tracking for that call.
+ */
+export interface ServiceInstrumentation {
+    /**
+     * Invoked at the start of the initialization process for a specific service.
+     *
+     * @param context - Context of the initialization, including the service key.
+     * @return An EventSpan notified when initialization finishes, or void.
+     */
+    onInitialize?(context: InitializeContext): EventSpan | void;
+    /**
+     * Invoked when the disposal process for a service starts.
+     *
+     * @param context - Context of the disposal, including the service key.
+     * @return An EventSpan notified when disposal finishes, or void.
+     */
+    onDispose?(context: DisposeContext): EventSpan | void;
+    /**
+     * Invoked when a method call starts on a service instance.
+     *
+     * @param context - Context of the invocation, including the service key,
+     * the method name, and its arguments.
+     * @return An EventSpan notified when the call finishes, or void.
+     */
+    onMethodCall?(context: MethodCallContext): EventSpan | void;
+}
+//# sourceMappingURL=serviceInstrumentation.d.ts.map