@chidchanun/bcp 0.3.0 → 0.3.2

package/packages/server/src/container.ts

@@ -0,0 +1,970 @@
+declare const SERVICE_TOKEN_VALUE:
+    unique symbol;
+
+export type ServiceLifetime =
+    | "singleton"
+    | "scoped"
+    | "transient";
+
+export type ServiceScopeState =
+    | "active"
+    | "disposing"
+    | "disposed";
+
+export interface ServiceToken<T = unknown> {
+    readonly id: symbol;
+    readonly description: string;
+    readonly [SERVICE_TOKEN_VALUE]?: T;
+}
+
+export type ServiceTokenValue<TToken> =
+    TToken extends ServiceToken<infer TValue>
+        ? TValue
+        : never;
+
+export type ServiceDependencyValues<
+    TDependencies extends readonly ServiceToken<any>[]
+> = {
+    [TIndex in keyof TDependencies]:
+        ServiceTokenValue<TDependencies[TIndex]>;
+};
+
+export interface ServiceFactoryContext {
+    readonly scope: ServiceScope;
+    resolve<T>(token: ServiceToken<T>): Promise<T>;
+    optional<T>(
+        token: ServiceToken<T>
+    ): Promise<T | undefined>;
+}
+
+export interface ServiceProvider<T = unknown> {
+    readonly token: ServiceToken<T>;
+    readonly lifetime?: ServiceLifetime;
+    readonly dependencies?:
+        readonly ServiceToken<any>[];
+    factory(
+        context: ServiceFactoryContext,
+        dependencies: readonly unknown[]
+    ): T | Promise<T>;
+    dispose?(
+        value: T
+    ): void | Promise<void>;
+}
+
+export interface ServiceProviderOptions<T> {
+    lifetime?: ServiceLifetime;
+    dispose?: (
+        value: T
+    ) => void | Promise<void>;
+}
+
+export interface ServiceScopeOptions {
+    name?: string;
+    overrides?: readonly ServiceProvider<any>[];
+}
+
+export interface ServiceContainerOptions {
+    name?: string;
+    providers?: readonly ServiceProvider<any>[];
+}
+
+export interface ServiceGraphNode {
+    token: ServiceToken<any>;
+    description: string;
+    lifetime: ServiceLifetime;
+    dependencies: string[];
+    overridden: boolean;
+}
+
+export interface ServiceScope {
+    readonly name: string;
+    readonly state: ServiceScopeState;
+    readonly parent: ServiceScope | undefined;
+    has(token: ServiceToken<any>): boolean;
+    resolve<T>(token: ServiceToken<T>): Promise<T>;
+    optional<T>(
+        token: ServiceToken<T>
+    ): Promise<T | undefined>;
+    createScope(
+        options?: ServiceScopeOptions
+    ): ServiceScope;
+    graph(): ServiceGraphNode[];
+    dispose(): Promise<void>;
+}
+
+export interface ServiceContainer
+extends ServiceScope {
+    register<T>(
+        provider: ServiceProvider<T>,
+        options?: {
+            replace?: boolean;
+        }
+    ): ServiceContainer;
+    registerMany(
+        providers:
+            readonly ServiceProvider<any>[]
+    ): ServiceContainer;
+    providers(): ServiceProvider<any>[];
+}
+
+interface ProviderRecord {
+    provider: ServiceProvider<any>;
+    owner: ScopeImpl;
+    overridden: boolean;
+}
+
+interface DisposalRecord {
+    provider: ServiceProvider<any>;
+    value: unknown;
+}
+
+export class ServiceNotFoundError
+extends Error {
+    readonly token: ServiceToken<any>;
+
+    constructor(token: ServiceToken<any>) {
+        super(
+            `BCP Container: service "${token.description}" is not registered.`
+        );
+        this.name = "ServiceNotFoundError";
+        this.token = token;
+    }
+}
+
+export class ServiceResolutionError
+extends Error {
+    readonly token: ServiceToken<any>;
+    readonly cause: unknown;
+
+    constructor(
+        token: ServiceToken<any>,
+        message: string,
+        cause?: unknown
+    ) {
+        super(
+            `BCP Container: could not resolve "${token.description}". ${message}`
+        );
+        this.name = "ServiceResolutionError";
+        this.token = token;
+        this.cause = cause;
+    }
+}
+
+export class ServiceDisposalError
+extends AggregateError {
+    constructor(errors: readonly unknown[]) {
+        super(
+            errors,
+            "BCP Container: one or more services failed to dispose."
+        );
+        this.name = "ServiceDisposalError";
+    }
+}
+
+export function createServiceToken<T>(
+    description: string
+): ServiceToken<T> {
+    const normalized =
+        normalizeName(
+            description,
+            "service token description"
+        );
+
+    return Object.freeze({
+        id: Symbol(normalized),
+        description: normalized,
+    });
+}
+
+export function provideValue<T>(
+    token: ServiceToken<T>,
+    value: T,
+    options: Pick<
+        ServiceProviderOptions<T>,
+        "dispose"
+    > = {}
+): ServiceProvider<T> {
+    assertToken(token);
+
+    return {
+        token,
+        lifetime: "singleton",
+        factory() {
+            return value;
+        },
+        ...(options.dispose
+            ? {
+                dispose: options.dispose,
+            }
+            : {}),
+    };
+}
+
+export function provideFactory<
+    T,
+    TDependencies extends
+        readonly ServiceToken<any>[]
+>(
+    token: ServiceToken<T>,
+    dependencies: TDependencies,
+    factory: (
+        context: ServiceFactoryContext,
+        dependencies:
+            ServiceDependencyValues<TDependencies>
+    ) => T | Promise<T>,
+    options: ServiceProviderOptions<T> = {}
+): ServiceProvider<T> {
+    assertToken(token);
+    assertDependencies(dependencies);
+    const lifetime =
+        normalizeLifetime(
+            options.lifetime
+        );
+
+    return {
+        token,
+        lifetime,
+        dependencies: [
+            ...dependencies,
+        ],
+        factory(
+            context,
+            values
+        ) {
+            return factory(
+                context,
+                values as
+                    ServiceDependencyValues<TDependencies>
+            );
+        },
+        ...(options.dispose
+            ? {
+                dispose: options.dispose,
+            }
+            : {}),
+    };
+}
+
+export function provideClass<
+    T,
+    TDependencies extends
+        readonly ServiceToken<any>[]
+>(
+    token: ServiceToken<T>,
+    dependencies: TDependencies,
+    Constructor: new (
+        ...dependencies:
+            ServiceDependencyValues<TDependencies>
+    ) => T,
+    options: ServiceProviderOptions<T> = {}
+): ServiceProvider<T> {
+    if (typeof Constructor !== "function") {
+        throw new TypeError(
+            "BCP Container: service constructor must be a function."
+        );
+    }
+
+    return provideFactory(
+        token,
+        dependencies,
+        (
+            _context,
+            values
+        ) =>
+            new Constructor(
+                ...values
+            ),
+        options
+    );
+}
+
+export function createServiceContainer(
+    options: ServiceContainerOptions = {}
+): ServiceContainer {
+    const root =
+        new ScopeImpl(
+            normalizeOptionalName(
+                options.name
+            ) ?? "root",
+            undefined
+        );
+    root.root = root;
+
+    const container:
+        ServiceContainer = {
+        get name() {
+            return root.name;
+        },
+        get state() {
+            return root.state;
+        },
+        get parent() {
+            return undefined;
+        },
+        has(token) {
+            return root.has(token);
+        },
+        resolve<T>(token: ServiceToken<T>) {
+            return root.resolve(token);
+        },
+        optional<T>(token: ServiceToken<T>) {
+            return root.optional(token);
+        },
+        createScope(scopeOptions = {}) {
+            return root.createScope(
+                scopeOptions
+            );
+        },
+        graph() {
+            return root.graph();
+        },
+        dispose() {
+            return root.dispose();
+        },
+        register<T>(
+            provider: ServiceProvider<T>,
+            registerOptions: {
+                replace?: boolean;
+            } = {}
+        ) {
+            root.registerProvider(
+                provider,
+                registerOptions.replace === true
+            );
+            return container;
+        },
+        registerMany(providers) {
+            for (const provider of providers) {
+                root.registerProvider(
+                    provider,
+                    false
+                );
+            }
+            return container;
+        },
+        providers() {
+            return Array.from(
+                root.providersMap.values()
+            );
+        },
+    };
+
+    for (
+        const provider
+        of options.providers ?? []
+    ) {
+        root.registerProvider(
+            provider,
+            false
+        );
+    }
+
+    return container;
+}
+
+class ScopeImpl
+implements ServiceScope {
+    root!: ScopeImpl;
+    readonly providersMap =
+        new Map<
+            symbol,
+            ServiceProvider<any>
+        >();
+    readonly overrideProviders =
+        new Map<
+            symbol,
+            ServiceProvider<any>
+        >();
+    readonly singletonCache =
+        new Map<
+            symbol,
+            Promise<unknown>
+        >();
+    readonly scopedCache =
+        new Map<
+            symbol,
+            Promise<unknown>
+        >();
+    readonly disposals:
+        DisposalRecord[] = [];
+    readonly children =
+        new Set<ScopeImpl>();
+    state:
+        ServiceScopeState = "active";
+    private disposePromise:
+        Promise<void> | undefined;
+
+    constructor(
+        readonly name: string,
+        readonly parent: ScopeImpl | undefined
+    ) {
+        if (parent) {
+            this.root = parent.root;
+            parent.children.add(this);
+        }
+    }
+
+    has(token: ServiceToken<any>): boolean {
+        assertToken(token);
+        return this.findProvider(token) !==
+            undefined;
+    }
+
+    resolve<T>(
+        token: ServiceToken<T>
+    ): Promise<T> {
+        return this.resolveWithPath(
+            token,
+            []
+        );
+    }
+
+    async optional<T>(
+        token: ServiceToken<T>
+    ): Promise<T | undefined> {
+        if (!this.has(token)) {
+            return undefined;
+        }
+        return this.resolve(token);
+    }
+
+    createScope(
+        options: ServiceScopeOptions = {}
+    ): ServiceScope {
+        this.assertActive();
+
+        const scope =
+            new ScopeImpl(
+                normalizeOptionalName(
+                    options.name
+                ) ??
+                    `${this.name}:scope-${this.children.size + 1}`,
+                this
+            );
+
+        for (
+            const provider
+            of options.overrides ?? []
+        ) {
+            scope.registerOverride(
+                provider
+            );
+        }
+
+        return scope;
+    }
+
+    graph(): ServiceGraphNode[] {
+        const effective =
+            new Map<
+                symbol,
+                ProviderRecord
+            >();
+
+        let current:
+            ScopeImpl | undefined = this;
+        while (current) {
+            for (
+                const [id, provider]
+                of current.overrideProviders
+            ) {
+                if (!effective.has(id)) {
+                    effective.set(
+                        id,
+                        {
+                            provider,
+                            owner: current,
+                            overridden: true,
+                        }
+                    );
+                }
+            }
+            current = current.parent;
+        }
+
+        for (
+            const [id, provider]
+            of this.root.providersMap
+        ) {
+            if (!effective.has(id)) {
+                effective.set(
+                    id,
+                    {
+                        provider,
+                        owner: this.root,
+                        overridden: false,
+                    }
+                );
+            }
+        }
+
+        return Array.from(
+            effective.values(),
+            record => ({
+                token:
+                    record.provider.token,
+                description:
+                    record.provider.token.description,
+                lifetime:
+                    normalizeLifetime(
+                        record.provider.lifetime
+                    ),
+                dependencies:
+                    (
+                        record.provider.dependencies ?? []
+                    ).map(
+                        dependency =>
+                            dependency.description
+                    ),
+                overridden:
+                    record.overridden,
+            })
+        ).sort(
+            (left, right) =>
+                left.description.localeCompare(
+                    right.description
+                )
+        );
+    }
+
+    dispose(): Promise<void> {
+        if (this.disposePromise) {
+            return this.disposePromise;
+        }
+        if (this.state === "disposed") {
+            return Promise.resolve();
+        }
+
+        this.disposePromise =
+            this.disposeInternal();
+        return this.disposePromise;
+    }
+
+    registerProvider<T>(
+        provider: ServiceProvider<T>,
+        replace: boolean
+    ): void {
+        this.assertActive();
+        if (this.parent) {
+            throw new Error(
+                "BCP Container: providers can only be registered on the root container. Use scope overrides for child scopes."
+            );
+        }
+        validateProvider(provider);
+
+        const id =
+            provider.token.id;
+        if (
+            this.providersMap.has(id) &&
+            !replace
+        ) {
+            throw new Error(
+                `BCP Container: service "${provider.token.description}" is already registered.`
+            );
+        }
+        if (
+            replace &&
+            this.hasResolved(id)
+        ) {
+            throw new Error(
+                `BCP Container: service "${provider.token.description}" cannot be replaced after it has been resolved.`
+            );
+        }
+
+        this.providersMap.set(
+            id,
+            provider
+        );
+    }
+
+    private registerOverride(
+        provider: ServiceProvider<any>
+    ): void {
+        validateProvider(provider);
+        const id =
+            provider.token.id;
+        if (
+            this.overrideProviders.has(id)
+        ) {
+            throw new Error(
+                `BCP Container: scope override for "${provider.token.description}" is already registered.`
+            );
+        }
+        this.overrideProviders.set(
+            id,
+            provider
+        );
+    }
+
+    private async resolveWithPath<T>(
+        token: ServiceToken<T>,
+        path: readonly ServiceToken<any>[]
+    ): Promise<T> {
+        this.assertActive();
+        assertToken(token);
+
+        if (
+            path.some(
+                item =>
+                    item.id === token.id
+            )
+        ) {
+            throw new ServiceResolutionError(
+                token,
+                `Circular dependency detected: ${[
+                    ...path,
+                    token,
+                ].map(
+                    item =>
+                        item.description
+                ).join(" -> ")}.`
+            );
+        }
+
+        const record =
+            this.findProvider(token);
+        if (!record) {
+            throw new ServiceNotFoundError(
+                token
+            );
+        }
+
+        const lifetime =
+            normalizeLifetime(
+                record.provider.lifetime
+            );
+        const cache =
+            lifetime === "singleton"
+                ? record.owner.singletonCache
+                : lifetime === "scoped"
+                    ? this.scopedCache
+                    : undefined;
+        const existing =
+            cache?.get(token.id);
+        if (existing) {
+            return existing as Promise<T>;
+        }
+
+        const resolution =
+            this.instantiate(
+                record.provider as
+                    ServiceProvider<T>,
+                [
+                    ...path,
+                    token,
+                ],
+                lifetime,
+                record.owner
+            );
+
+        cache?.set(
+            token.id,
+            resolution
+        );
+
+        try {
+            return await resolution;
+        } catch (error) {
+            cache?.delete(token.id);
+            if (
+                error instanceof ServiceNotFoundError ||
+                error instanceof ServiceResolutionError
+            ) {
+                throw error;
+            }
+            throw new ServiceResolutionError(
+                token,
+                error instanceof Error
+                    ? error.message
+                    : String(error),
+                error
+            );
+        }
+    }
+
+    private async instantiate<T>(
+        provider: ServiceProvider<T>,
+        path: readonly ServiceToken<any>[],
+        lifetime: ServiceLifetime,
+        providerOwner: ScopeImpl
+    ): Promise<T> {
+        const dependencies =
+            await Promise.all(
+                (
+                    provider.dependencies ?? []
+                ).map(
+                    dependency =>
+                        this.resolveWithPath(
+                            dependency,
+                            path
+                        )
+                )
+            );
+        const context:
+            ServiceFactoryContext = {
+            scope: this,
+            resolve: <TValue>(
+                dependency: ServiceToken<TValue>
+            ) =>
+                this.resolveWithPath(
+                    dependency,
+                    path
+                ),
+            optional: async <TValue>(
+                dependency: ServiceToken<TValue>
+            ) => {
+                if (!this.has(dependency)) {
+                    return undefined;
+                }
+                return this.resolveWithPath(
+                    dependency,
+                    path
+                );
+            },
+        };
+        const value =
+            await provider.factory(
+                context,
+                dependencies
+            );
+
+        if (provider.dispose) {
+            const disposalOwner =
+                lifetime === "singleton"
+                    ? providerOwner
+                    : this;
+            disposalOwner.disposals.push({
+                provider,
+                value,
+            });
+        }
+
+        return value;
+    }
+
+    private findProvider(
+        token: ServiceToken<any>
+    ): ProviderRecord | undefined {
+        let current:
+            ScopeImpl | undefined = this;
+
+        while (current) {
+            const override =
+                current.overrideProviders.get(
+                    token.id
+                );
+            if (override) {
+                return {
+                    provider: override,
+                    owner: current,
+                    overridden: true,
+                };
+            }
+            current = current.parent;
+        }
+
+        const provider =
+            this.root.providersMap.get(
+                token.id
+            );
+        if (!provider) {
+            return undefined;
+        }
+
+        return {
+            provider,
+            owner: this.root,
+            overridden: false,
+        };
+    }
+
+    private async disposeInternal(): Promise<void> {
+        this.state = "disposing";
+        const errors:
+            unknown[] = [];
+
+        for (
+            const child
+            of Array.from(
+                this.children
+            ).reverse()
+        ) {
+            try {
+                await child.dispose();
+            } catch (error) {
+                errors.push(error);
+            }
+        }
+
+        for (
+            const record
+            of [...this.disposals].reverse()
+        ) {
+            if (!record.provider.dispose) {
+                continue;
+            }
+            try {
+                await record.provider.dispose(
+                    record.value
+                );
+            } catch (error) {
+                errors.push(error);
+            }
+        }
+
+        this.disposals.length = 0;
+        this.singletonCache.clear();
+        this.scopedCache.clear();
+        this.children.clear();
+        this.parent?.children.delete(this);
+        this.state = "disposed";
+
+        if (errors.length > 0) {
+            throw new ServiceDisposalError(
+                errors
+            );
+        }
+    }
+
+    private hasResolved(id: symbol): boolean {
+        if (
+            this.singletonCache.has(id) ||
+            this.scopedCache.has(id)
+        ) {
+            return true;
+        }
+        for (const child of this.children) {
+            if (child.hasResolved(id)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private assertActive(): void {
+        if (this.state !== "active") {
+            throw new Error(
+                `BCP Container: scope "${this.name}" is ${this.state}.`
+            );
+        }
+    }
+}
+
+function validateProvider<T>(
+    provider: ServiceProvider<T>
+): void {
+    if (
+        !provider ||
+        typeof provider !== "object"
+    ) {
+        throw new TypeError(
+            "BCP Container: provider must be an object."
+        );
+    }
+    assertToken(provider.token);
+    if (typeof provider.factory !== "function") {
+        throw new TypeError(
+            `BCP Container: provider "${provider.token.description}" must define factory().`
+        );
+    }
+    normalizeLifetime(
+        provider.lifetime
+    );
+    assertDependencies(
+        provider.dependencies ?? []
+    );
+    if (
+        provider.dispose !== undefined &&
+        typeof provider.dispose !== "function"
+    ) {
+        throw new TypeError(
+            `BCP Container: provider "${provider.token.description}" dispose must be a function.`
+        );
+    }
+}
+
+function assertToken(
+    token: ServiceToken<any>
+): void {
+    if (
+        !token ||
+        typeof token !== "object" ||
+        typeof token.id !== "symbol" ||
+        typeof token.description !== "string" ||
+        token.description.trim() === ""
+    ) {
+        throw new TypeError(
+            "BCP Container: invalid service token. Use createServiceToken()."
+        );
+    }
+}
+
+function assertDependencies(
+    dependencies:
+        readonly ServiceToken<any>[]
+): void {
+    if (!Array.isArray(dependencies)) {
+        throw new TypeError(
+            "BCP Container: provider dependencies must be an array."
+        );
+    }
+    for (const dependency of dependencies) {
+        assertToken(dependency);
+    }
+}
+
+function normalizeLifetime(
+    lifetime: ServiceLifetime | undefined
+): ServiceLifetime {
+    const normalized =
+        lifetime ?? "singleton";
+    if (
+        normalized !== "singleton" &&
+        normalized !== "scoped" &&
+        normalized !== "transient"
+    ) {
+        throw new TypeError(
+            "BCP Container: service lifetime must be singleton, scoped or transient."
+        );
+    }
+    return normalized;
+}
+
+function normalizeName(
+    value: unknown,
+    label: string
+): string {
+    if (typeof value !== "string") {
+        throw new TypeError(
+            `BCP Container: ${label} must be a string.`
+        );
+    }
+    const normalized =
+        value.trim();
+    if (!normalized) {
+        throw new TypeError(
+            `BCP Container: ${label} cannot be empty.`
+        );
+    }
+    if (
+        normalized.length > 256 ||
+        /[\r\n]/.test(normalized)
+    ) {
+        throw new TypeError(
+            `BCP Container: ${label} must be at most 256 characters without line breaks.`
+        );
+    }
+    return normalized;
+}
+
+function normalizeOptionalName(
+    value: string | undefined
+): string | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+    return normalizeName(
+        value,
+        "scope name"
+    );
+}