@justscale/core 0.1.0

package/dist/core/container-reflection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-reflection.d.ts","sourceRoot":"","sources":["../../src/core/container-reflection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,WAAW,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,QAAQ,CAAC,kBAAkB,CAAC,CAAC;IAEnE;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAEvD;;;;OAIG;IACH,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;CAC3D;;AAED;;;;;;;;;;;;;;GAcG;AACH,8BAAsB,iBAAkB,SAAQ,sBAAwD;CAAG;AAE3G;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IACxD,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACxE,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;CAChF,GAAG,mBAAmB,CAgCtB"}

package/dist/core/container-reflection.js

@@ -0,0 +1,60 @@
+/**
+ * AbstractContainer - queryable reflection of the current scope.
+ *
+ * Inject to introspect what the scope contains (controllers, services).
+ * Each scope binds its own instance; sub-apps each get their own.
+ * Transport-agnostic: protocols filter by reading their own metadata off
+ * each controller instance.
+ */
+import { defineAbstract } from './service.js';
+/**
+ * Abstract DI token for scope reflection. Tools inject this:
+ *
+ * @example
+ * ```ts
+ * class ApiDocService extends defineService({
+ *   inject: { container: AbstractContainer },
+ *   factory: ({ container }) => ({
+ *     routes: () => [...container.controllers()],
+ *   }),
+ * }) {}
+ * ```
+ *
+ * Each compiled scope binds its own concrete implementation.
+ */
+export class AbstractContainer extends defineAbstract('AbstractContainer') {
+}
+/**
+ * @internal Build a concrete ContainerReflection over a resolved app's
+ * controllers and DI container.
+ */
+export function createContainerReflection(args) {
+    const { controllers, resolve, resolveAll } = args;
+    return {
+        *controllers(where) {
+            for (const c of controllers) {
+                if (where?.hasGuards !== undefined) {
+                    const anyGuard = c.routes.some((r) => r.steps?.some((s) => s.type === 'guard'));
+                    if (where.hasGuards !== anyGuard)
+                        continue;
+                }
+                yield c;
+            }
+        },
+        async get(token) {
+            try {
+                return await resolve(token);
+            }
+            catch {
+                return undefined;
+            }
+        },
+        async all(token) {
+            if (resolveAll)
+                return resolveAll(token);
+            const one = await this.get(token);
+            return one === undefined ? [] : [one];
+        },
+    };
+}
+//# sourceMappingURL=container-reflection.js.map

package/dist/core/container-reflection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-reflection.js","sourceRoot":"","sources":["../../src/core/container-reflection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAwC9C;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAgB,iBAAkB,SAAQ,cAAc,CAAsB,mBAAmB,CAAC;CAAG;AAE3G;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAIzC;IACC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IAElD,OAAO;QACL,CAAC,WAAW,CAAC,KAAK;YAChB,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;gBAC5B,IAAI,KAAK,EAAE,SAAS,KAAK,SAAS,EAAE,CAAC;oBACnC,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAClC,CAA4D,CAAC,KAAK,EAAE,IAAI,CACvE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAC1B,CACF,CAAC;oBACF,IAAI,KAAK,CAAC,SAAS,KAAK,QAAQ;wBAAE,SAAS;gBAC7C,CAAC;gBACD,MAAM,CAAC,CAAC;YACV,CAAC;QACH,CAAC;QAED,KAAK,CAAC,GAAG,CAAI,KAAsB;YACjC,IAAI,CAAC;gBACH,OAAO,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;YAC9B,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,SAAS,CAAC;YACnB,CAAC;QACH,CAAC;QAED,KAAK,CAAC,GAAG,CAAI,KAAsB;YACjC,IAAI,UAAU;gBAAE,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC;YACzC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAClC,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACxC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/core/context.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Request Context System
+ *
+ * Provides async context propagation for DI container access and request
+ * chain tracing. Uses AsyncLocalStorage for automatic propagation.
+ */
+import type { Container } from './service.js';
+import { type ObservabilityContext } from './logger.js';
+/**
+ * Get the current DI container from async context.
+ * Returns undefined if no container is in context.
+ *
+ * @example
+ * ```typescript
+ * const container = getContainer()
+ * if (container) {
+ *   const userService = await container.resolve(UserService)
+ * }
+ * ```
+ */
+export declare function getContainer(): Container | undefined;
+/**
+ * Get the current DI container, throwing if none is in context.
+ * Use this when you require a container to be present.
+ *
+ * @throws Error if no container is in context
+ *
+ * @example
+ * ```typescript
+ * const container = requireContainer()
+ * const userService = await container.resolve(UserService)
+ * ```
+ */
+export declare function requireContainer(): Container;
+/**
+ * Run a function with a DI container in async context.
+ * The container is available via getContainer() in the entire async tree.
+ *
+ * @example
+ * ```typescript
+ * runWithContainer(container, async () => {
+ *   // getContainer() returns container here
+ *   await processRequest()
+ * })
+ * ```
+ */
+export declare function runWithContainer<T>(container: Container, fn: () => T): T;
+/**
+ * Type of request/handler that initiated the context.
+ */
+export type RequestType = 'http' | 'ws' | 'cli' | 'event' | 'process' | 'scheduled' | 'internal';
+/**
+ * Context about the current request in the chain.
+ * Forms a linked list back to the originating request.
+ */
+export interface RequestContext {
+    /** Short unique identifier for this request */
+    id: string;
+    /** Type of request handler */
+    type: RequestType;
+    /** Name of the route/handler/process */
+    name: string;
+    /** Parent request context (for chain tracing) */
+    parent?: RequestContext;
+    /** When this request started */
+    startedAt: Date;
+    /** Additional metadata (route params, user info, etc.) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Minimal principal shape for access control evaluation.
+ * Kept in core so both permission package (writer) and HTTP serializer (reader)
+ * can use it without circular dependencies.
+ */
+export interface AccessPrincipal {
+    readonly type: abstract new (...args: any[]) => any;
+    readonly ref: {
+        readonly identifier: string;
+    };
+}
+/** Get the resolved principals for the current request (for field-level access filtering). */
+export declare function getAccessPrincipals(): AccessPrincipal[] | undefined;
+/** Run a function with resolved principals in context (set by permission guards). */
+export declare function runWithPrincipals<T>(principals: AccessPrincipal[], fn: () => T): T;
+/**
+ * Set principals for the current async context (no callback needed).
+ * Used by permission guards to make principals available for the rest of the request.
+ */
+export declare function enterWithPrincipals(principals: AccessPrincipal[]): void;
+/**
+ * Get the current request context.
+ * Returns undefined if not within a request scope.
+ *
+ * @example
+ * ```typescript
+ * const ctx = getRequestContext()
+ * if (ctx) {
+ *   console.log(`Request ${ctx.id} (${ctx.type}): ${ctx.name}`)
+ * }
+ * ```
+ */
+export declare function getRequestContext(): RequestContext | undefined;
+/**
+ * Get the full request chain from current to origin.
+ * Useful for debugging and distributed tracing.
+ *
+ * @example
+ * ```typescript
+ * const chain = getRequestChain()
+ * // [current, parent, grandparent, ...]
+ * console.log('Request chain:', chain.map(c => `${c.type}:${c.name}`).join(' -> '))
+ * // "event:order.created -> http:POST /orders"
+ * ```
+ */
+export declare function getRequestChain(): RequestContext[];
+/**
+ * Run a function within a new request context.
+ * Automatically links to parent context if one exists.
+ */
+export declare function runWithRequestContext<T>(type: RequestType, name: string, fn: () => T, metadata?: Record<string, unknown>): T;
+/**
+ * Options for running code in a full request scope.
+ */
+export interface RequestScopeOptions {
+    /** DI container for the request */
+    container: Container;
+    /** Type of request/handler */
+    type: RequestType;
+    /** Name of the route/handler */
+    name: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Observability context overrides */
+    observability?: ObservabilityContext;
+}
+/**
+ * Run a function in a full request scope with container context,
+ * request chain tracking, and observability instrumentation.
+ */
+export declare function runInFullRequestScope<T>(options: RequestScopeOptions, fn: () => Promise<T>): Promise<T>;
+/**
+ * Synchronous version of runInFullRequestScope.
+ * Use for synchronous handlers (rare).
+ */
+export declare function runInFullRequestScopeSync<T>(options: RequestScopeOptions, fn: () => T): T;
+//# sourceMappingURL=context.d.ts.map

package/dist/core/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAmC,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAQzF;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,IAAI,SAAS,GAAG,SAAS,CAEpD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,IAAI,SAAS,CAM5C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAExE;AAMD;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,IAAI,GAAG,KAAK,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC;AAEjG;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAA;IACV,8BAA8B;IAC9B,IAAI,EAAE,WAAW,CAAA;IACjB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,iDAAiD;IACjD,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,gCAAgC;IAChC,SAAS,EAAE,IAAI,CAAA;IACf,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAQD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;IACpD,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAID,8FAA8F;AAC9F,wBAAgB,mBAAmB,IAAI,eAAe,EAAE,GAAG,SAAS,CAEnE;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,UAAU,EAAE,eAAe,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAElF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,IAAI,CAEvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,IAAI,cAAc,EAAE,CAQlD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,CAAC,EACX,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,CAAC,CAWH;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,SAAS,EAAE,SAAS,CAAA;IACpB,8BAA8B;IAC9B,IAAI,EAAE,WAAW,CAAA;IACjB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,sCAAsC;IACtC,aAAa,CAAC,EAAE,oBAAoB,CAAA;CACrC;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,OAAO,EAAE,mBAAmB,EAC5B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAoBZ;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EACzC,OAAO,EAAE,mBAAmB,EAC5B,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAIH"}

package/dist/core/context.js

@@ -0,0 +1,155 @@
+/**
+ * Request Context System
+ *
+ * Provides async context propagation for DI container access and request
+ * chain tracing. Uses AsyncLocalStorage for automatic propagation.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { runInScopeAsync } from './logger.js';
+// ============================================================================
+// Container Context
+// ============================================================================
+const containerContext = new AsyncLocalStorage();
+/**
+ * Get the current DI container from async context.
+ * Returns undefined if no container is in context.
+ *
+ * @example
+ * ```typescript
+ * const container = getContainer()
+ * if (container) {
+ *   const userService = await container.resolve(UserService)
+ * }
+ * ```
+ */
+export function getContainer() {
+    return containerContext.getStore();
+}
+/**
+ * Get the current DI container, throwing if none is in context.
+ * Use this when you require a container to be present.
+ *
+ * @throws Error if no container is in context
+ *
+ * @example
+ * ```typescript
+ * const container = requireContainer()
+ * const userService = await container.resolve(UserService)
+ * ```
+ */
+export function requireContainer() {
+    const container = getContainer();
+    if (!container) {
+        throw new Error('No container in context. Ensure code runs within request scope.');
+    }
+    return container;
+}
+/**
+ * Run a function with a DI container in async context.
+ * The container is available via getContainer() in the entire async tree.
+ *
+ * @example
+ * ```typescript
+ * runWithContainer(container, async () => {
+ *   // getContainer() returns container here
+ *   await processRequest()
+ * })
+ * ```
+ */
+export function runWithContainer(container, fn) {
+    return containerContext.run(container, fn);
+}
+const requestContext = new AsyncLocalStorage();
+const principalContext = new AsyncLocalStorage();
+/** Get the resolved principals for the current request (for field-level access filtering). */
+export function getAccessPrincipals() {
+    return principalContext.getStore();
+}
+/** Run a function with resolved principals in context (set by permission guards). */
+export function runWithPrincipals(principals, fn) {
+    return principalContext.run(principals, fn);
+}
+/**
+ * Set principals for the current async context (no callback needed).
+ * Used by permission guards to make principals available for the rest of the request.
+ */
+export function enterWithPrincipals(principals) {
+    principalContext.enterWith(principals);
+}
+/**
+ * Get the current request context.
+ * Returns undefined if not within a request scope.
+ *
+ * @example
+ * ```typescript
+ * const ctx = getRequestContext()
+ * if (ctx) {
+ *   console.log(`Request ${ctx.id} (${ctx.type}): ${ctx.name}`)
+ * }
+ * ```
+ */
+export function getRequestContext() {
+    return requestContext.getStore();
+}
+/**
+ * Get the full request chain from current to origin.
+ * Useful for debugging and distributed tracing.
+ *
+ * @example
+ * ```typescript
+ * const chain = getRequestChain()
+ * // [current, parent, grandparent, ...]
+ * console.log('Request chain:', chain.map(c => `${c.type}:${c.name}`).join(' -> '))
+ * // "event:order.created -> http:POST /orders"
+ * ```
+ */
+export function getRequestChain() {
+    const chain = [];
+    let current = getRequestContext();
+    while (current) {
+        chain.push(current);
+        current = current.parent;
+    }
+    return chain;
+}
+/**
+ * Run a function within a new request context.
+ * Automatically links to parent context if one exists.
+ */
+export function runWithRequestContext(type, name, fn, metadata) {
+    const parent = getRequestContext();
+    const ctx = {
+        id: crypto.randomUUID().slice(0, 8),
+        type,
+        name,
+        parent,
+        startedAt: new Date(),
+        metadata,
+    };
+    return requestContext.run(ctx, fn);
+}
+/**
+ * Run a function in a full request scope with container context,
+ * request chain tracking, and observability instrumentation.
+ */
+export async function runInFullRequestScope(options, fn) {
+    const requestId = crypto.randomUUID().slice(0, 8);
+    const scopeInfo = {
+        type: options.type === 'http' ? 'request' : 'handler',
+        name: options.name,
+        attributes: options.metadata,
+    };
+    const observabilityCtx = {
+        requestId,
+        ...options.observability,
+    };
+    return runWithContainer(options.container, () => runWithRequestContext(options.type, options.name, () => runInScopeAsync(scopeInfo, observabilityCtx, fn), options.metadata));
+}
+/**
+ * Synchronous version of runInFullRequestScope.
+ * Use for synchronous handlers (rare).
+ */
+export function runInFullRequestScopeSync(options, fn) {
+    return runWithContainer(options.container, () => runWithRequestContext(options.type, options.name, fn, options.metadata));
+}
+//# sourceMappingURL=context.js.map

package/dist/core/context.js.map

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

package/dist/core/contribution.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Contribution pattern - multi-implementation tokens.
+ *
+ * `defineContribution<T>` creates an abstract DI token that accepts multiple
+ * implementations. The framework provides a default aggregator that collects
+ * contributions via `register(t: T)` and exposes the aggregated interface
+ * defined by the `aggregate` function.
+ *
+ * `createContribution(Token, { inject, factory })` creates a self-registering
+ * contribution service. When added to the app, it injects the default
+ * aggregator, calls its `register()` method with the factory output, and
+ * returns the impl.
+ *
+ * @example
+ * ```typescript
+ * // 1. Declare the multi-impl token
+ * abstract class AbstractPrincipalProvider extends defineContribution<PrincipalProvider>(
+ *   'AbstractPrincipalProvider',
+ *   {
+ *     aggregate: (contribs) => ({
+ *       async resolve(ctx) {
+ *         const lists = await Promise.all(contribs.map((c) => c.resolve(ctx)));
+ *         return lists.flat();
+ *       },
+ *     }),
+ *   },
+ * ) {}
+ *
+ * // 2. Create independent contributions
+ * export const AuthResolver = createContribution(AbstractPrincipalProvider, {
+ *   inject: { users: UserRepository },
+ *   factory: ({ users }) => ({
+ *     async resolve(ctx) { / * ... * / return []; },
+ *   }),
+ * });
+ *
+ * // 3. Add them to the app - default aggregator is auto-registered
+ * JustScale()
+ *   .add(AuthResolver)
+ *   .add(DomainResolver)
+ *   .build();
+ * ```
+ */
+import { type AbstractClass, type ServiceDef, type ServiceFactory, type ServiceToken, type ResolvedDeps } from './service.js';
+/** Marks an abstract class as a contribution token (vs a single-impl abstract). */
+export declare const CONTRIBUTION_MARKER: unique symbol;
+/**
+ * On a contribution-marked abstract class, holds the default aggregating
+ * service def. The builder registers this once when it sees any contribution
+ * referencing the token (see `justscale.ts` processComponent).
+ */
+export declare const CONTRIBUTION_DEFAULT: unique symbol;
+/**
+ * On a service def created via `createContribution()`, points to the parent
+ * contribution token. The builder uses this to auto-register the default
+ * aggregator.
+ */
+export declare const CONTRIBUTES_TO: unique symbol;
+/**
+ * @internal Registry interface the default aggregator implements.
+ * Never exposed on the public abstract token's type.
+ */
+interface ContributionRegistry<T> {
+    register(contribution: T): void;
+}
+/**
+ * A contribution-kind abstract class. Same as `AbstractClass<T>` plus a
+ * brand symbol so `createContribution()` can type-check its argument.
+ */
+export type ContributionAbstractClass<T> = AbstractClass<T> & {
+    readonly [CONTRIBUTION_MARKER]: true;
+};
+/**
+ * Define an abstract DI token that accepts multiple contributions.
+ *
+ * Returns an abstract class you extend with `abstract class X extends ...`
+ * (same shape as `defineAbstract`). The difference:
+ * - `defineAbstract` is a SINGLE-impl token - bind one via `bindService`.
+ * - `defineContribution` is a MULTI-impl token - add contributions via
+ *   `createContribution(X, { ... })`. The framework auto-wires a default
+ *   aggregator that calls the `aggregate` function with all registered
+ *   contributions.
+ *
+ * @param name Human-readable name for debugging and error messages.
+ * @param opts `aggregate` - builds the aggregated interface from the list
+ *   of registered contributions. Called lazily (every time the aggregated
+ *   interface is used, OR cached - see note below).
+ *
+ * @example
+ * ```typescript
+ * abstract class AbstractPrincipalProvider extends defineContribution<PrincipalProvider>(
+ *   'AbstractPrincipalProvider',
+ *   {
+ *     aggregate: (contribs) => ({
+ *       async resolve(ctx) {
+ *         const lists = await Promise.all(contribs.map((c) => c.resolve(ctx)));
+ *         return lists.flat();
+ *       },
+ *     }),
+ *   },
+ * ) {}
+ * ```
+ */
+export declare function defineContribution<T>(name: string, opts: {
+    aggregate: (contributions: readonly T[]) => T;
+}): ContributionAbstractClass<T>;
+/**
+ * Type guard: is this a contribution-kind abstract class?
+ */
+export declare function isContributionToken(value: unknown): value is ContributionAbstractClass<unknown>;
+/**
+ * Retrieve the default aggregating service for a contribution token.
+ * Used by the builder to auto-register the default once.
+ */
+export declare function getContributionDefault<T>(token: ContributionAbstractClass<T>): ServiceDef<T & ContributionRegistry<T>, {}>;
+/**
+ * Create a self-registering contribution to a multi-impl token.
+ *
+ * Returns a `ServiceDef` that, when resolved, injects the contribution token
+ * (resolving to the default aggregator), calls the user's `factory` to build
+ * the contribution, registers it with the aggregator via `.register()`, and
+ * returns the contribution.
+ *
+ * @example
+ * ```typescript
+ * export const AuthResolver = createContribution(AbstractPrincipalProvider, {
+ *   inject: { users: UserRepository },
+ *   factory: ({ users }) => ({
+ *     async resolve(ctx) {
+ *       if (!ctx.user) return [];
+ *       return [{ type: User, ref: User.ref(ctx.user) }];
+ *     },
+ *   }),
+ * });
+ * ```
+ */
+export declare function createContribution<T, const TDeps extends Record<string, ServiceToken>>(token: ContributionAbstractClass<T>, config: {
+    inject: TDeps;
+    factory: ServiceFactory<ResolvedDeps<TDeps>, T>;
+}): ServiceDef<T, TDeps>;
+/**
+ * Type guard: is this service def a contribution?
+ */
+export declare function isContribution(value: unknown): value is ServiceDef<unknown, any> & {
+    [CONTRIBUTES_TO]: ContributionAbstractClass<unknown>;
+};
+/**
+ * Get the contribution parent token from a contribution service def.
+ */
+export declare function getContributionParent<T>(def: ServiceDef<T, any>): ContributionAbstractClass<T> | undefined;
+export {};
+//# sourceMappingURL=contribution.d.ts.map

package/dist/core/contribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contribution.d.ts","sourceRoot":"","sources":["../../src/core/contribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,YAAY,EAGlB,MAAM,cAAc,CAAC;AAMtB,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,eAAyC,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,eAA0C,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,cAAc,eAAoC,CAAC;AAMhE;;;GAGG;AACH,UAAU,oBAAoB,CAAC,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,CAAC,GAAG,IAAI,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,MAAM,yBAAyB,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,GAAG;IAC5D,QAAQ,CAAC,CAAC,mBAAmB,CAAC,EAAE,IAAI,CAAC;CACtC,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,SAAS,EAAE,CAAC,aAAa,EAAE,SAAS,CAAC,EAAE,KAAK,CAAC,CAAA;CAAE,GACtD,yBAAyB,CAAC,CAAC,CAAC,CAgC9B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,yBAAyB,CAAC,OAAO,CAAC,CAM/F;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,KAAK,EAAE,yBAAyB,CAAC,CAAC,CAAC,GAClC,UAAU,CAAC,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAI7C;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAChC,CAAC,EACD,KAAK,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAEhD,KAAK,EAAE,yBAAyB,CAAC,CAAC,CAAC,EACnC,MAAM,EAAE;IACN,MAAM,EAAE,KAAK,CAAC;IACd,OAAO,EAAE,cAAc,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;CACjD,GACA,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,CAgDtB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,GAAG;IAClF,CAAC,cAAc,CAAC,EAAE,yBAAyB,CAAC,OAAO,CAAC,CAAC;CACtD,CAOA;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,GAAG,EAAE,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,GACtB,yBAAyB,CAAC,CAAC,CAAC,GAAG,SAAS,CAE1C"}