katagami 3.0.2 → 4.0.0

package/dist/container/index.d.ts

@@ -1,5 +1,84 @@
-import { type ContainerInternals, INTERNALS } from '../internal.js';
+import { type Callable, type EntrypointFactory } from '../entrypoint/index.js';
+import { type ContainerInternals, INTERNALS, type REGISTRATION_STATE } from '../internal.js';
+import { type AnyMetadataEntry, type AnyMetadataKey, type MetadataKeyOf, type MetadataReader, type RegistrationArguments } from '../metadata/index.js';
 import type { AbstractConstructor, Resolver } from '../resolver/index.js';
+import { type ContainerPolicy, type RequiredMetadata } from './policy.js';
+export type RegisteredTokens<C> = C extends {
+    readonly [REGISTRATION_STATE]: infer S;
+} ? S extends {
+    readonly untracked: true;
+} ? never : S extends {
+    readonly token: infer K;
+} ? K : never : never;
+export interface RegistrationState {
+    readonly token: unknown;
+    readonly metadata: AnyMetadataKey;
+    readonly callable: Callable | never;
+}
+type State<K, E extends readonly AnyMetadataEntry[], F = never> = {
+    readonly token: K;
+    readonly metadata: MetadataKeyOf<E[number]>;
+    readonly callable: F;
+};
+type Replace<S, K, N> = (unknown extends S ? UntrackedState : Exclude<S, {
+    readonly token: K;
+}>) | N;
+type UntrackedState<K = unknown> = {
+    readonly token: K;
+    readonly metadata: never;
+    readonly callable: never;
+    readonly untracked: true;
+};
+type SourceState<S, K> = unknown extends S ? UntrackedState<K> : S extends {
+    readonly untracked: true;
+} ? UntrackedState<K> : S;
+type SourceTokens<S, K> = unknown extends S ? K : S extends {
+    readonly untracked: true;
+} ? K : S extends {
+    readonly token: infer Token;
+} ? Token : never;
+type Append<S, K, E extends readonly AnyMetadataEntry[], F = never> = unknown extends S ? [MetadataKeyOf<E[number]> | F] extends [never] ? unknown : UntrackedState | State<K, E, F> : Replace<S, K, {
+    readonly token: K;
+    readonly metadata: [Extract<S, {
+        readonly token: K;
+    }>] extends [never] ? MetadataKeyOf<E[number]> : Extract<Extract<S, {
+        readonly token: K;
+    }> extends {
+        readonly metadata: infer M;
+    } ? M : never, MetadataKeyOf<E[number]>>;
+    readonly callable: F;
+}>;
+type TrackedState<S> = S extends {
+    readonly metadata: infer M;
+    readonly callable: infer F;
+} ? [M | F] extends [never] ? never : S : never;
+type Merge<S, K, N> = unknown extends S ? [TrackedState<N>] extends [never] ? unknown : Replace<S, K, N> : Replace<S, K, N>;
+type MissingMetadata<R, S> = unknown extends S ? R : S extends {
+    readonly metadata: infer M;
+} ? Exclude<R, M> : never;
+/**
+ * Create a new DI container that follows a shared policy.
+ *
+ * Containers created with the same policy object share its settings and the origins it observes.
+ * Every registration must carry the policy's `requiredMetadata`, and `use()` accepts only modules
+ * with the same policy or without one. Declare the policy with `satisfies ContainerPolicy` to keep
+ * its concrete types.
+ *
+ * @param options `policy`: the shared policy object
+ */
+export declare function createContainer<const P extends ContainerPolicy>(options: {
+    readonly policy: P;
+}): Container<Record<never, never>, never, never, Record<never, never>, never, never, RequiredMetadata<P>, never>;
+/**
+ * Create a new DI container that follows a shared policy, with predeclared token type maps.
+ *
+ * @template T PropertyKey-based token type map (defined via interface, order-independent)
+ * @template ScopedT PropertyKey-based token type map for scoped registrations
+ * @param options `policy`: the shared policy object
+ */
+export declare function createContainer<T, ScopedT, const P extends ContainerPolicy>(options: {
+    readonly policy: P;
+}): Container<T, never, never, ScopedT, never, never, RequiredMetadata<P>, never>;
 /**
  * Create a new DI container.
  *
@@ -14,7 +93,9 @@ import type { AbstractConstructor, Resolver } from '../resolver/index.js';
  *   .registerTransient(GenerateTextUseCase, r => new GenerateTextUseCase(r.resolve(TextGenerationService)));
  * ```
  */
-export declare function createContainer<T = Record<never, never>, ScopedT = Record<never, never>>(): Container<T, never, never, ScopedT>;
+export declare function createContainer<T = Record<never, never>, ScopedT = Record<never, never>>(): Container<T, never, never, ScopedT, never, never, readonly [], [
+    keyof T | keyof ScopedT
+] extends [never] ? never : unknown>;
 /**
  * Lightweight DI container — registration only.
  *
@@ -29,33 +110,43 @@ export declare function createContainer<T = Record<never, never>, ScopedT = Reco
  * @template ScopedT PropertyKey-based token type map for scoped registrations
  * @template ScopedSync Union of scoped sync class constructors (accumulated via chaining, order-dependent)
  * @template ScopedAsync Union of scoped async class constructors (accumulated via chaining, order-dependent)
+ * @template Required Metadata keys the container's policy requires on every registration
+ * @template Registrations Registration state that tracks metadata and operations per token
  */
-export declare class Container<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, ScopedT = Record<never, never>, ScopedSync extends AbstractConstructor = never, ScopedAsync extends AbstractConstructor = never> {
+export declare class Container<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, ScopedT = Record<never, never>, ScopedSync extends AbstractConstructor = never, ScopedAsync extends AbstractConstructor = never, Required extends readonly AnyMetadataKey[] = readonly [], Registrations = unknown> {
     private readonly registrations;
     private readonly singletonCache;
+    private readonly requiredMetadata;
+    private readonly policy;
     private disposed;
-    /**
-     * Internal state accessor for extension modules (scope, disposable).
-     *
-     * @internal
-     */
-    readonly [INTERNALS]: ContainerInternals;
-    constructor();
+    readonly [REGISTRATION_STATE]: Registrations;
+    readonly [INTERNALS]: ContainerInternals & {
+        readonly kind: 'container';
+    };
+    constructor(options?: {
+        readonly policy: ContainerPolicy<Required>;
+    });
     /**
      * Register a factory function as a singleton for the given token.
      *
      * Creates the instance on the first resolve and returns the cached value thereafter.
      * If the same token is registered multiple times, all factories are accumulated.
      * `resolve()` returns the last registered instance; `resolveAll()` returns all.
+     * Register request-dependent work as scoped instead.
      *
      * @param token Any value to use as a token
-     * @param factory Factory function that receives a resolver and returns an instance
+     * @param factory Factory function that receives a resolver and returns an instance. Wrap it with
+     *   `entrypoint()` to expose the function it returns as an operation.
+     * @param options `metadata`: entries created with metadata keys. Required when the policy declares
+     *   `requiredMetadata`.
      * @returns The container for method chaining
      */
-    registerSingleton<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => Promise<V>): Container<T, Sync, Async | AbstractConstructor<V>, ScopedT, ScopedSync, ScopedAsync>;
-    registerSingleton<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<T, Sync | AbstractConstructor<V>, Async, ScopedT, ScopedSync, ScopedAsync>;
-    registerSingleton<K extends PropertyKey, V>(token: K, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<Record<K, V> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
-    registerSingleton<V>(token: unknown, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+    registerSingleton<K extends PropertyKey, F extends Callable, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: ((resolver: Resolver<T, Sync, Async>) => F) & EntrypointFactory<Resolver<T, Sync, Async>, F>, ...options: RegistrationArguments<Required, E>): Container<Record<K, F> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E, F>>;
+    registerSingleton<K extends PropertyKey, F extends Callable, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: EntrypointFactory<Resolver<T, Sync, Async>, F>, ...options: RegistrationArguments<Required, E>): Container<Record<K, Promise<F>> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E, F>>;
+    registerSingleton<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => Promise<V>, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async | AbstractConstructor<V>, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, AbstractConstructor<V>, E>>;
+    registerSingleton<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => V, ...options: RegistrationArguments<Required, E>): Container<T, Sync | AbstractConstructor<V>, Async, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, AbstractConstructor<V>, E>>;
+    registerSingleton<K extends PropertyKey, V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: (resolver: Resolver<T, Sync, Async>) => V, ...options: RegistrationArguments<Required, E>): Container<Record<K, V> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E>>;
+    registerSingleton<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: unknown, factory: (resolver: Resolver<T, Sync, Async>) => V, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Registrations | State<unknown, E>>;
     /**
      * Register a factory function as transient for the given token.
      *
@@ -64,13 +155,18 @@ export declare class Container<T = Record<never, never>, Sync extends AbstractCo
      * `resolve()` returns the last registered instance; `resolveAll()` returns all.
      *
      * @param token Any value to use as a token
-     * @param factory Factory function that receives a resolver and returns an instance
+     * @param factory Factory function that receives a resolver and returns an instance. Wrap it with
+     *   `entrypoint()` to expose the function it returns as an operation.
+     * @param options `metadata`: entries created with metadata keys. Required when the policy declares
+     *   `requiredMetadata`.
      * @returns The container for method chaining
      */
-    registerTransient<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => Promise<V>): Container<T, Sync, Async | AbstractConstructor<V>, ScopedT, ScopedSync, ScopedAsync>;
-    registerTransient<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<T, Sync | AbstractConstructor<V>, Async, ScopedT, ScopedSync, ScopedAsync>;
-    registerTransient<K extends PropertyKey, V>(token: K, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<Record<K, V> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
-    registerTransient<V>(token: unknown, factory: (resolver: Resolver<T, Sync, Async>) => V): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+    registerTransient<K extends PropertyKey, F extends Callable, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: ((resolver: Resolver<T, Sync, Async>) => F) & EntrypointFactory<Resolver<T, Sync, Async>, F>, ...options: RegistrationArguments<Required, E>): Container<Record<K, F> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E, F>>;
+    registerTransient<K extends PropertyKey, F extends Callable, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: EntrypointFactory<Resolver<T, Sync, Async>, F>, ...options: RegistrationArguments<Required, E>): Container<Record<K, Promise<F>> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E, F>>;
+    registerTransient<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => Promise<V>, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async | AbstractConstructor<V>, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, AbstractConstructor<V>, E>>;
+    registerTransient<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T, Sync, Async>) => V, ...options: RegistrationArguments<Required, E>): Container<T, Sync | AbstractConstructor<V>, Async, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, AbstractConstructor<V>, E>>;
+    registerTransient<K extends PropertyKey, V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: (resolver: Resolver<T, Sync, Async>) => V, ...options: RegistrationArguments<Required, E>): Container<Record<K, V> & T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E>>;
+    registerTransient<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: unknown, factory: (resolver: Resolver<T, Sync, Async>) => V, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Registrations | State<unknown, E>>;
     /**
      * Register a factory function as scoped for the given token.
      *
@@ -79,30 +175,41 @@ export declare class Container<T = Record<never, never>, Sync extends AbstractCo
      * Scoped tokens cannot be resolved from the root container — use createScope() first.
      *
      * @param token Any value to use as a token
-     * @param factory Factory function that receives a resolver and returns an instance
+     * @param factory Factory function that receives a resolver and returns an instance. Wrap it with
+     *   `entrypoint()` to expose the function it returns as an operation.
+     * @param options `metadata`: entries created with metadata keys. Required when the policy declares
+     *   `requiredMetadata`.
      * @returns The container for method chaining
      */
-    registerScoped<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => Promise<V>): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync | AbstractConstructor<V>>;
-    registerScoped<V>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V): Container<T, Sync, Async, ScopedT, ScopedSync | AbstractConstructor<V>, ScopedAsync>;
-    registerScoped<K extends PropertyKey, V>(token: K, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V): Container<T, Sync, Async, Record<K, V> & ScopedT, ScopedSync, ScopedAsync>;
-    registerScoped<V>(token: unknown, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+    registerScoped<K extends PropertyKey, F extends Callable, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: ((resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => F) & EntrypointFactory<Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>, F>, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async, Record<K, F> & ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E, F>>;
+    registerScoped<K extends PropertyKey, F extends Callable, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: EntrypointFactory<Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>, F>, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async, Record<K, Promise<F>> & ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E, F>>;
+    registerScoped<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => Promise<V>, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync | AbstractConstructor<V>, Required, Append<Registrations, AbstractConstructor<V>, E>>;
+    registerScoped<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: AbstractConstructor<V>, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async, ScopedT, ScopedSync | AbstractConstructor<V>, ScopedAsync, Required, Append<Registrations, AbstractConstructor<V>, E>>;
+    registerScoped<K extends PropertyKey, V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: K, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async, Record<K, V> & ScopedT, ScopedSync, ScopedAsync, Required, Append<Registrations, K, E>>;
+    registerScoped<V, const E extends readonly AnyMetadataEntry[] = readonly []>(token: unknown, factory: (resolver: Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>) => V, ...options: RegistrationArguments<Required, E>): Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Registrations | State<unknown, E>>;
+    /**
+     * Read the metadata of the last registration for a token without creating the instance.
+     *
+     * @param token A registered token
+     * @returns A read-only metadata reader
+     * @throws ContainerError if the token is not registered
+     */
+    getMetadata<V>(token: AbstractConstructor<V> & (Sync | Async | ScopedSync | ScopedAsync)): MetadataReader;
+    getMetadata<K extends keyof (T & ScopedT)>(token: K): MetadataReader;
     /**
      * Apply all registrations from another container (module) to this container.
      *
-     * Copies registration entries (factory + lifetime) by replacing existing entries for each token.
+     * Copies registration entries by replacing existing entries for each token.
      * Singleton instance caches are not shared — each container manages its own.
+     * A module with a policy must use this container's policy, and every copied registration must carry
+     * the metadata this container's policy requires; otherwise nothing is copied.
      *
      * @param source A container whose registrations will be copied into this container
      * @returns The container for method chaining
      */
-    use<MT, MSync extends AbstractConstructor, MAsync extends AbstractConstructor, MScopedT, MScopedSync extends AbstractConstructor, MScopedAsync extends AbstractConstructor>(source: Container<MT, MSync, MAsync, MScopedT, MScopedSync, MScopedAsync>): Container<T & MT, Sync | MSync, Async | MAsync, ScopedT & MScopedT, ScopedSync | MScopedSync, ScopedAsync | MScopedAsync>;
-    /**
-     * Add a registration entry. Accumulates registrations for the same token.
-     *
-     * @param token Token
-     * @param factory Factory function
-     * @param lifetime Lifetime of the registration
-     * @returns The container for method chaining
-     */
+    use<MT, MS extends AbstractConstructor, MA extends AbstractConstructor, MST, MSS extends AbstractConstructor, MSA extends AbstractConstructor, MR extends readonly AnyMetadataKey[], State>(source: Container<MT, MS, MA, MST, MSS, MSA, MR, State> & ([MissingMetadata<Required[number], State>] extends [never] ? unknown : {
+        readonly missingRequiredMetadata: never;
+    })): Container<T & MT, Sync | MS, Async | MA, ScopedT & MST, ScopedSync | MSS, ScopedAsync | MSA, Required, Merge<Registrations, SourceTokens<State, keyof MT | keyof MST | MS | MA | MSS | MSA>, SourceState<State, keyof MT | keyof MST | MS | MA | MSS | MSA>>>;
     private addRegistration;
 }
+export {};

package/dist/container/policy.d.cts

@@ -0,0 +1,36 @@
+import { type AnyMetadataKey, type MetadataPair } from '../metadata/index.cjs';
+import type { Registration } from '../resolver/index.cjs';
+import type { RegistrationDescription } from '../scope/index.cjs';
+export interface ReturnEvent {
+    readonly registrations: readonly RegistrationDescription[];
+}
+export type BeforeReturn = (event: ReturnEvent) => void;
+export interface ContainerPolicy<Required extends readonly AnyMetadataKey[] = readonly AnyMetadataKey[]> {
+    readonly name?: string;
+    readonly requiredMetadata?: Required;
+    readonly beforeReturn?: BeforeReturn;
+}
+export type RequiredMetadata<P> = P extends {
+    readonly requiredMetadata: infer R extends readonly AnyMetadataKey[];
+} ? R : readonly [];
+/**
+ * An origin recorded for an instance.
+ *
+ * It holds neither the registration nor its factory. A policy outlives its containers, so holding a
+ * registration would keep every per-request container and its factory closures reachable from the record.
+ */
+interface Origin {
+    readonly description: RegistrationDescription;
+    readonly pairs: readonly MetadataPair[] | undefined;
+}
+export interface PolicyState {
+    readonly definition: ContainerPolicy;
+    readonly name: string | undefined;
+    readonly requiredMetadata: readonly AnyMetadataKey[];
+    readonly beforeReturn: BeforeReturn | undefined;
+    readonly origins: WeakMap<object, Origin[]>;
+}
+export declare function bindPolicy(definition: ContainerPolicy | undefined): PolicyState | undefined;
+export declare function observe(policy: PolicyState | undefined, registration: Registration, token: unknown, value: unknown): void;
+export declare function checkReturn(policy: PolicyState | undefined, value: unknown): void;
+export {};

package/dist/container/policy.d.ts

@@ -0,0 +1,36 @@
+import { type AnyMetadataKey, type MetadataPair } from '../metadata/index.js';
+import type { Registration } from '../resolver/index.js';
+import type { RegistrationDescription } from '../scope/index.js';
+export interface ReturnEvent {
+    readonly registrations: readonly RegistrationDescription[];
+}
+export type BeforeReturn = (event: ReturnEvent) => void;
+export interface ContainerPolicy<Required extends readonly AnyMetadataKey[] = readonly AnyMetadataKey[]> {
+    readonly name?: string;
+    readonly requiredMetadata?: Required;
+    readonly beforeReturn?: BeforeReturn;
+}
+export type RequiredMetadata<P> = P extends {
+    readonly requiredMetadata: infer R extends readonly AnyMetadataKey[];
+} ? R : readonly [];
+/**
+ * An origin recorded for an instance.
+ *
+ * It holds neither the registration nor its factory. A policy outlives its containers, so holding a
+ * registration would keep every per-request container and its factory closures reachable from the record.
+ */
+interface Origin {
+    readonly description: RegistrationDescription;
+    readonly pairs: readonly MetadataPair[] | undefined;
+}
+export interface PolicyState {
+    readonly definition: ContainerPolicy;
+    readonly name: string | undefined;
+    readonly requiredMetadata: readonly AnyMetadataKey[];
+    readonly beforeReturn: BeforeReturn | undefined;
+    readonly origins: WeakMap<object, Origin[]>;
+}
+export declare function bindPolicy(definition: ContainerPolicy | undefined): PolicyState | undefined;
+export declare function observe(policy: PolicyState | undefined, registration: Registration, token: unknown, value: unknown): void;
+export declare function checkReturn(policy: PolicyState | undefined, value: unknown): void;
+export {};

package/dist/disposable/index.cjs

@@ -25,7 +25,25 @@ __export(disposable_exports, {
 module.exports = __toCommonJS(disposable_exports);
 
 // src/internal.ts
-var INTERNALS = /* @__PURE__ */ Symbol.for("katagami.internals.v3");
+var INTERNALS = /* @__PURE__ */ Symbol.for("katagami.internals.v4");
+var CREATIONS = /* @__PURE__ */ Symbol.for("katagami.creations.v4");
+var shared = globalThis;
+if (!shared[CREATIONS]) {
+  Object.defineProperty(shared, CREATIONS, { value: /* @__PURE__ */ new WeakMap() });
+}
+var creations = shared[CREATIONS];
+function settle(creation) {
+  return creation.then(
+    (value) => ({ failed: false, value }),
+    (error) => ({ error, failed: true })
+  );
+}
+var CONSTRUCTING = /* @__PURE__ */ Symbol.for("katagami.constructing.v4");
+var running = globalThis;
+if (!running[CONSTRUCTING]) {
+  Object.defineProperty(running, CONSTRUCTING, { value: [] });
+}
+var constructing = running[CONSTRUCTING];
 
 // src/disposable/index.ts
 function disposable(container) {
@@ -38,11 +56,15 @@ function disposable(container) {
     const instances = [...internals.ownCache.values()].reverse();
     const errors = [];
     for (const instance of instances) {
-      try {
-        let resolved = instance;
-        if (instance instanceof Promise) {
-          resolved = await instance;
+      let resolved = instance;
+      if (instance instanceof Promise) {
+        const creation = await (creations.get(instance) ?? settle(instance));
+        if (creation.failed) {
+          continue;
         }
+        resolved = creation.value;
+      }
+      try {
         if (resolved != null && typeof resolved === "object") {
           if (Symbol.asyncDispose in resolved) {
             await resolved[Symbol.asyncDispose]();

package/dist/disposable/index.d.cts

@@ -1,5 +1,6 @@
 import type { Container } from '../container/index.cjs';
-import { type ContainerInternals, INTERNALS, type TYPE_STATE } from '../internal.cjs';
+import { type ContainerInternals, INTERNALS, type REGISTRATION_STATE, type TYPE_STATE } from '../internal.cjs';
+import type { AnyMetadataKey } from '../metadata/index.cjs';
 import type { AbstractConstructor, Resolver } from '../resolver/index.cjs';
 import type { Scope } from '../scope/index.cjs';
 /**
@@ -16,8 +17,12 @@ import type { Scope } from '../scope/index.cjs';
  * @template ScopedSync Union of scoped sync class constructors
  * @template ScopedAsync Union of scoped async class constructors
  */
-export interface DisposableContainer<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, ScopedT = Record<never, never>, ScopedSync extends AbstractConstructor = never, ScopedAsync extends AbstractConstructor = never> extends AsyncDisposable {
-    readonly [INTERNALS]: ContainerInternals;
+export interface DisposableContainer<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, ScopedT = Record<never, never>, ScopedSync extends AbstractConstructor = never, ScopedAsync extends AbstractConstructor = never, Required extends readonly AnyMetadataKey[] = readonly [], Registrations = unknown> extends AsyncDisposable {
+    readonly [INTERNALS]: ContainerInternals & {
+        readonly kind: 'container';
+    };
+    readonly [REGISTRATION_STATE]: Registrations;
+    readonly requiredMetadataType?: Required;
     readonly [TYPE_STATE]?: {
         readonly kind: 'container';
         readonly registrations: readonly [T, Sync, Async, ScopedT, ScopedSync, ScopedAsync];
@@ -35,8 +40,11 @@ export interface DisposableContainer<T = Record<never, never>, Sync extends Abst
  * @template ScopedSync Union of scoped sync class constructors
  * @template ScopedAsync Union of scoped async class constructors
  */
-export interface DisposableScope<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, ScopedT = Record<never, never>, ScopedSync extends AbstractConstructor = never, ScopedAsync extends AbstractConstructor = never> extends Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>, AsyncDisposable {
-    readonly [INTERNALS]: ContainerInternals;
+export interface DisposableScope<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, ScopedT = Record<never, never>, ScopedSync extends AbstractConstructor = never, ScopedAsync extends AbstractConstructor = never, Registrations = unknown> extends Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>, AsyncDisposable {
+    readonly [INTERNALS]: ContainerInternals & {
+        readonly kind: 'scope';
+    };
+    readonly [REGISTRATION_STATE]: Registrations;
     readonly [TYPE_STATE]?: {
         readonly kind: 'scope';
         readonly registrations: readonly [T, Sync, Async, ScopedT, ScopedSync, ScopedAsync];
@@ -48,6 +56,8 @@ export interface DisposableScope<T = Record<never, never>, Sync extends Abstract
  * Enables `await using` syntax by attaching `[Symbol.asyncDispose]` to the target.
  * Disposes owned instances in reverse creation order (LIFO), calling
  * `[Symbol.asyncDispose]()` or `[Symbol.dispose]()` on each instance that implements them.
+ * A cached asynchronous creation that rejected yields no resolved value to close: it is awaited,
+ * skipped, and its failure is left to the caller that resolved the token.
  *
  * The returned type prevents registration methods from being called on a potentially-disposed container.
  * For scopes, `resolve`, `tryResolve`, `resolveAll`, and `tryResolveAll` remain available.
@@ -65,5 +75,5 @@ export interface DisposableScope<T = Record<never, never>, Sync extends Abstract
  * );
  * ```
  */
-export declare function disposable<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(container: Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): DisposableContainer<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
-export declare function disposable<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(scope: Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): DisposableScope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+export declare function disposable<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, Required extends readonly AnyMetadataKey[], Registrations>(container: Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Registrations>): DisposableContainer<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Registrations>;
+export declare function disposable<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, Registrations>(scope: Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Registrations>): DisposableScope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Registrations>;

package/dist/disposable/index.d.ts

@@ -1,5 +1,6 @@
 import type { Container } from '../container/index.js';
-import { type ContainerInternals, INTERNALS, type TYPE_STATE } from '../internal.js';
+import { type ContainerInternals, INTERNALS, type REGISTRATION_STATE, type TYPE_STATE } from '../internal.js';
+import type { AnyMetadataKey } from '../metadata/index.js';
 import type { AbstractConstructor, Resolver } from '../resolver/index.js';
 import type { Scope } from '../scope/index.js';
 /**
@@ -16,8 +17,12 @@ import type { Scope } from '../scope/index.js';
  * @template ScopedSync Union of scoped sync class constructors
  * @template ScopedAsync Union of scoped async class constructors
  */
-export interface DisposableContainer<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, ScopedT = Record<never, never>, ScopedSync extends AbstractConstructor = never, ScopedAsync extends AbstractConstructor = never> extends AsyncDisposable {
-    readonly [INTERNALS]: ContainerInternals;
+export interface DisposableContainer<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, ScopedT = Record<never, never>, ScopedSync extends AbstractConstructor = never, ScopedAsync extends AbstractConstructor = never, Required extends readonly AnyMetadataKey[] = readonly [], Registrations = unknown> extends AsyncDisposable {
+    readonly [INTERNALS]: ContainerInternals & {
+        readonly kind: 'container';
+    };
+    readonly [REGISTRATION_STATE]: Registrations;
+    readonly requiredMetadataType?: Required;
     readonly [TYPE_STATE]?: {
         readonly kind: 'container';
         readonly registrations: readonly [T, Sync, Async, ScopedT, ScopedSync, ScopedAsync];
@@ -35,8 +40,11 @@ export interface DisposableContainer<T = Record<never, never>, Sync extends Abst
  * @template ScopedSync Union of scoped sync class constructors
  * @template ScopedAsync Union of scoped async class constructors
  */
-export interface DisposableScope<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, ScopedT = Record<never, never>, ScopedSync extends AbstractConstructor = never, ScopedAsync extends AbstractConstructor = never> extends Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>, AsyncDisposable {
-    readonly [INTERNALS]: ContainerInternals;
+export interface DisposableScope<T = Record<never, never>, Sync extends AbstractConstructor = never, Async extends AbstractConstructor = never, ScopedT = Record<never, never>, ScopedSync extends AbstractConstructor = never, ScopedAsync extends AbstractConstructor = never, Registrations = unknown> extends Resolver<T & ScopedT, Sync | ScopedSync, Async | ScopedAsync>, AsyncDisposable {
+    readonly [INTERNALS]: ContainerInternals & {
+        readonly kind: 'scope';
+    };
+    readonly [REGISTRATION_STATE]: Registrations;
     readonly [TYPE_STATE]?: {
         readonly kind: 'scope';
         readonly registrations: readonly [T, Sync, Async, ScopedT, ScopedSync, ScopedAsync];
@@ -48,6 +56,8 @@ export interface DisposableScope<T = Record<never, never>, Sync extends Abstract
  * Enables `await using` syntax by attaching `[Symbol.asyncDispose]` to the target.
  * Disposes owned instances in reverse creation order (LIFO), calling
  * `[Symbol.asyncDispose]()` or `[Symbol.dispose]()` on each instance that implements them.
+ * A cached asynchronous creation that rejected yields no resolved value to close: it is awaited,
+ * skipped, and its failure is left to the caller that resolved the token.
  *
  * The returned type prevents registration methods from being called on a potentially-disposed container.
  * For scopes, `resolve`, `tryResolve`, `resolveAll`, and `tryResolveAll` remain available.
@@ -65,5 +75,5 @@ export interface DisposableScope<T = Record<never, never>, Sync extends Abstract
  * );
  * ```
  */
-export declare function disposable<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(container: Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): DisposableContainer<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
-export declare function disposable<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor>(scope: Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>): DisposableScope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync>;
+export declare function disposable<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, Required extends readonly AnyMetadataKey[], Registrations>(container: Container<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Registrations>): DisposableContainer<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Required, Registrations>;
+export declare function disposable<T, Sync extends AbstractConstructor, Async extends AbstractConstructor, ScopedT, ScopedSync extends AbstractConstructor, ScopedAsync extends AbstractConstructor, Registrations>(scope: Scope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Registrations>): DisposableScope<T, Sync, Async, ScopedT, ScopedSync, ScopedAsync, Registrations>;

package/dist/disposable/index.js

@@ -1,45 +1,6 @@
 import {
-  INTERNALS
-} from "../chunk-J2NYR3SH.js";
-
-// src/disposable/index.ts
-function disposable(container) {
-  const asyncDispose = async () => {
-    const internals = container[INTERNALS];
-    if (internals.isDisposed()) {
-      return;
-    }
-    internals.markDisposed();
-    const instances = [...internals.ownCache.values()].reverse();
-    const errors = [];
-    for (const instance of instances) {
-      try {
-        let resolved = instance;
-        if (instance instanceof Promise) {
-          resolved = await instance;
-        }
-        if (resolved != null && typeof resolved === "object") {
-          if (Symbol.asyncDispose in resolved) {
-            await resolved[Symbol.asyncDispose]();
-          } else if (Symbol.dispose in resolved) {
-            resolved[Symbol.dispose]();
-          }
-        }
-      } catch (error) {
-        errors.push(error);
-      }
-    }
-    internals.ownCache.clear();
-    if (errors.length > 0) {
-      throw new AggregateError(errors, "One or more errors occurred during disposal.");
-    }
-  };
-  Object.defineProperty(container, Symbol.asyncDispose, {
-    configurable: true,
-    value: asyncDispose
-  });
-  return container;
-}
+  disposable
+} from "../chunk-R66WOZUM.js";
 export {
   disposable
 };

package/dist/entrypoint/index.d.cts

@@ -0,0 +1,20 @@
+declare const ENTRYPOINT: unique symbol;
+export type Callable = (...args: never[]) => unknown;
+export type EntrypointFactory<R, F extends Callable> = ((resolver: R) => F | Promise<F>) & {
+    readonly [ENTRYPOINT]: true;
+};
+/**
+ * Mark a factory that returns a function as a public operation.
+ *
+ * An operations scope (`createScope(container, { access: 'operations' })`) exposes only entry points.
+ * Calling the operation it returns resolves the registration and runs the function on each call.
+ *
+ * @param factory Factory function that receives a resolver and returns the operation's function
+ * @returns The same factory, marked as an entry point
+ */
+export declare function entrypoint<R, F extends Callable>(factory: (resolver: R) => F): ((resolver: R) => F) & {
+    readonly [ENTRYPOINT]: true;
+};
+export declare function entrypoint<R, F extends Callable>(factory: (resolver: R) => Promise<F>): EntrypointFactory<R, F>;
+export declare function isEntrypoint(factory: unknown): boolean;
+export {};

package/dist/entrypoint/index.d.ts

@@ -0,0 +1,20 @@
+declare const ENTRYPOINT: unique symbol;
+export type Callable = (...args: never[]) => unknown;
+export type EntrypointFactory<R, F extends Callable> = ((resolver: R) => F | Promise<F>) & {
+    readonly [ENTRYPOINT]: true;
+};
+/**
+ * Mark a factory that returns a function as a public operation.
+ *
+ * An operations scope (`createScope(container, { access: 'operations' })`) exposes only entry points.
+ * Calling the operation it returns resolves the registration and runs the function on each call.
+ *
+ * @param factory Factory function that receives a resolver and returns the operation's function
+ * @returns The same factory, marked as an entry point
+ */
+export declare function entrypoint<R, F extends Callable>(factory: (resolver: R) => F): ((resolver: R) => F) & {
+    readonly [ENTRYPOINT]: true;
+};
+export declare function entrypoint<R, F extends Callable>(factory: (resolver: R) => Promise<F>): EntrypointFactory<R, F>;
+export declare function isEntrypoint(factory: unknown): boolean;
+export {};