@raubjo/architect-core 0.1.0 → 0.1.2

package/src/container/adapters/builtin.ts

@@ -0,0 +1,347 @@
+import type {
+    ContainerClass,
+    ContainerBindToSyntax,
+    ContainerConcrete,
+    ContainerContract,
+    ContainerFactory,
+    ContainerIdentifier,
+} from "@/container/contract";
+
+const INJECT_TOKENS_METADATA_KEY = "ioc:inject.tokens";
+
+type Scope = "singleton" | "transient";
+
+type BindingRecord<T = unknown> =
+    | {
+          kind: "constant";
+          value: T;
+      }
+    | {
+          kind: "class";
+          concrete: ContainerClass<T>;
+          scope: Scope;
+          cached?: T;
+      }
+    | {
+          kind: "factory";
+          concrete: ContainerFactory<T>;
+          scope: Scope;
+          cached?: T;
+      };
+
+type MetadataReflect = typeof Reflect & {
+    defineMetadata?: (key: string, value: unknown, target: object) => void;
+    getMetadata?: (key: string, target: object) => unknown;
+};
+
+const metadataReflect = Reflect as MetadataReflect;
+
+function isClassConcrete<T>(
+    value: ContainerConcrete<T>,
+): value is ContainerClass<T> {
+    return (
+        typeof value === "function" &&
+        Object.prototype.hasOwnProperty.call(value, "prototype")
+    );
+}
+
+function isFactoryConcrete<T>(
+    value: ContainerConcrete<T>,
+): value is ContainerFactory<T> {
+    return typeof value === "function" && !isClassConcrete(value);
+}
+
+function readInjectTokens(target: object): Map<number, ContainerIdentifier> {
+    const metadata = metadataReflect.getMetadata?.(
+        INJECT_TOKENS_METADATA_KEY,
+        target,
+    ) as Record<number, ContainerIdentifier> | undefined;
+
+    const tokens = new Map<number, ContainerIdentifier>();
+    if (!metadata) {
+        return tokens;
+    }
+
+    for (const [index, identifier] of Object.entries(metadata)) {
+        tokens.set(Number(index), identifier);
+    }
+
+    return tokens;
+}
+
+class BuiltinBindingFluent<T> {
+    protected record: BindingRecord<T> | null = null;
+
+    constructor(
+        protected readonly container: BuiltinContainer,
+        protected readonly identifier: ContainerIdentifier<T>,
+    ) {}
+
+    to(concrete: ContainerClass<T>): {
+        inSingletonScope: () => void;
+        inTransientScope: () => void;
+    } {
+        this.record = { kind: "class", concrete, scope: "singleton" };
+        this.container.setRecord(this.identifier, this.record);
+
+        return {
+            inSingletonScope: () => {
+                if (this.record && this.record.kind !== "constant") {
+                    this.record.scope = "singleton";
+                }
+            },
+            inTransientScope: () => {
+                if (this.record && this.record.kind !== "constant") {
+                    this.record.scope = "transient";
+                    delete this.record.cached;
+                }
+            },
+        };
+    }
+
+    toDynamicValue(
+        concrete: (context: { container: ContainerContract }) => T,
+    ): { inSingletonScope: () => void; inTransientScope: () => void } {
+        this.record = {
+            kind: "factory",
+            concrete: () => concrete({ container: this.container }),
+            scope: "singleton",
+        };
+        this.container.setRecord(this.identifier, this.record);
+
+        return {
+            inSingletonScope: () => {
+                if (this.record && this.record.kind !== "constant") {
+                    this.record.scope = "singleton";
+                }
+            },
+            inTransientScope: () => {
+                if (this.record && this.record.kind !== "constant") {
+                    this.record.scope = "transient";
+                    delete this.record.cached;
+                }
+            },
+        };
+    }
+
+    toConstantValue(value: T): void {
+        this.record = { kind: "constant", value };
+        this.container.setRecord(this.identifier, this.record);
+    }
+}
+
+export function inject(identifier: ContainerIdentifier): ParameterDecorator {
+    return (target, _propertyKey, parameterIndex) => {
+        const existing =
+            (metadataReflect.getMetadata?.(
+                INJECT_TOKENS_METADATA_KEY,
+                target,
+            ) as Record<number, ContainerIdentifier> | undefined) ?? {};
+        existing[parameterIndex] = identifier;
+        metadataReflect.defineMetadata?.(
+            INJECT_TOKENS_METADATA_KEY,
+            existing,
+            target,
+        );
+    };
+}
+
+export default class BuiltinContainer implements ContainerContract {
+    protected bindings = new Map<ContainerIdentifier, BindingRecord>();
+    protected resolving = new Set<ContainerIdentifier>();
+
+    bind<T>(identifier: ContainerIdentifier<T>): ContainerBindToSyntax<T> {
+        if (this.bindings.has(identifier)) {
+            throw new Error(
+                `Cannot bind [${String(identifier)}] because it is already bound.`,
+            );
+        }
+
+        return new BuiltinBindingFluent<T>(this, identifier);
+    }
+
+    singleton<T>(
+        identifier: ContainerIdentifier<T>,
+        concrete: ContainerConcrete<T>,
+    ): this {
+        this.removeIfBound(identifier);
+
+        if (isClassConcrete(concrete)) {
+            this.bindings.set(identifier, {
+                kind: "class",
+                concrete,
+                scope: "singleton",
+            });
+            return this;
+        }
+
+        if (isFactoryConcrete(concrete)) {
+            this.bindings.set(identifier, {
+                kind: "factory",
+                concrete,
+                scope: "singleton",
+            });
+            return this;
+        }
+
+        this.bindings.set(identifier, {
+            kind: "constant",
+            value: concrete as T,
+        });
+        return this;
+    }
+
+    transient<T>(
+        identifier: ContainerIdentifier<T>,
+        concrete: ContainerConcrete<T>,
+    ): this {
+        this.removeIfBound(identifier);
+
+        if (isClassConcrete(concrete)) {
+            this.bindings.set(identifier, {
+                kind: "class",
+                concrete,
+                scope: "transient",
+            });
+            return this;
+        }
+
+        if (isFactoryConcrete(concrete)) {
+            this.bindings.set(identifier, {
+                kind: "factory",
+                concrete,
+                scope: "transient",
+            });
+            return this;
+        }
+
+        this.bindings.set(identifier, {
+            kind: "factory",
+            concrete: () => concrete as T,
+            scope: "transient",
+        });
+        return this;
+    }
+
+    instance<T>(identifier: ContainerIdentifier<T>, value: T): this {
+        this.removeIfBound(identifier);
+        this.bindings.set(identifier, { kind: "constant", value });
+        return this;
+    }
+
+    make<T>(identifier: ContainerIdentifier<T>): T {
+        const record = this.bindings.get(identifier);
+        if (record) {
+            return this.resolveRecord(record, identifier) as T;
+        }
+
+        if (typeof identifier === "function") {
+            return this.resolveClass(identifier as ContainerClass<T>);
+        }
+
+        throw new Error(
+            `Container binding [${String(identifier)}] is not registered.`,
+        );
+    }
+
+    get<T>(identifier: ContainerIdentifier<T>): T {
+        return this.make(identifier);
+    }
+
+    bound(identifier: ContainerIdentifier): boolean {
+        return this.bindings.has(identifier);
+    }
+
+    has(identifier: ContainerIdentifier): boolean {
+        return this.bound(identifier);
+    }
+
+    unbind(identifier: ContainerIdentifier): void {
+        this.bindings.delete(identifier);
+    }
+
+    unbindAll(): void {
+        this.bindings.clear();
+        this.resolving.clear();
+    }
+
+    flush(): void {
+        this.unbindAll();
+    }
+
+    getRawContainer(): unknown {
+        return this.bindings;
+    }
+
+    setRecord<T>(
+        identifier: ContainerIdentifier<T>,
+        record: BindingRecord<T>,
+    ): void {
+        this.bindings.set(identifier, record as BindingRecord);
+    }
+
+    protected removeIfBound(identifier: ContainerIdentifier): void {
+        this.bindings.delete(identifier);
+    }
+
+    protected resolveRecord<T>(
+        record: BindingRecord<T>,
+        identifier: ContainerIdentifier,
+    ): T {
+        if (record.kind === "constant") {
+            return record.value;
+        }
+
+        if (
+            record.scope === "singleton" &&
+            "cached" in record &&
+            typeof record.cached !== "undefined"
+        ) {
+            return record.cached;
+        }
+
+        const resolved =
+            record.kind === "class" ?
+                this.resolveClass(record.concrete)
+            :   record.concrete(this);
+
+        if (record.scope === "singleton") {
+            record.cached = resolved;
+        }
+
+        return resolved;
+    }
+
+    protected resolveClass<T>(concrete: ContainerClass<T>): T {
+        if (this.resolving.has(concrete)) {
+            throw new Error(
+                `Circular dependency detected while resolving [${concrete.name || "anonymous"}].`,
+            );
+        }
+
+        this.resolving.add(concrete);
+
+        try {
+            const paramTypes =
+                (metadataReflect.getMetadata?.(
+                    "design:paramtypes",
+                    concrete,
+                ) as Array<ContainerIdentifier | undefined> | undefined) ?? [];
+            const injectTokens = readInjectTokens(concrete);
+            const args = paramTypes.map((designType, index) => {
+                const token = injectTokens.get(index) ?? designType;
+                if (!token) {
+                    throw new Error(
+                        `Cannot resolve parameter #${index} for [${concrete.name || "anonymous"}].`,
+                    );
+                }
+
+                return this.make(token);
+            });
+
+            return new concrete(...args);
+        } finally {
+            this.resolving.delete(concrete);
+        }
+    }
+}

package/src/container/adapters/inversify.ts

@@ -0,0 +1,123 @@
+import { Container, type BindToFluentSyntax, type Newable } from "inversify";
+import type {
+    ContainerBindToSyntax,
+    ContainerConcrete,
+    ContainerContract,
+    ContainerFactory,
+    ContainerIdentifier,
+} from "@/container/contract";
+
+function isClassConcrete<T>(value: ContainerConcrete<T>): value is Newable<T> {
+    return (
+        typeof value === "function" &&
+        Object.prototype.hasOwnProperty.call(value, "prototype")
+    );
+}
+
+function isFactoryConcrete<T>(
+    value: ContainerConcrete<T>,
+): value is ContainerFactory<T> {
+    return typeof value === "function" && !isClassConcrete(value);
+}
+
+export default class InversifyContainer implements ContainerContract {
+    protected container: Container;
+
+    constructor(container = new Container({ defaultScope: "Singleton" })) {
+        this.container = container;
+    }
+
+    bind<T>(identifier: ContainerIdentifier<T>): ContainerBindToSyntax<T> {
+        return this.container.bind<T>(
+            identifier,
+        ) as unknown as BindToFluentSyntax<T> & ContainerBindToSyntax<T>;
+    }
+
+    singleton<T>(
+        identifier: ContainerIdentifier<T>,
+        concrete: ContainerConcrete<T>,
+    ): this {
+        this.removeIfBound(identifier);
+
+        const binding = this.container.bind(identifier);
+        if (isClassConcrete(concrete)) {
+            binding.to(concrete).inSingletonScope();
+            return this;
+        }
+
+        if (isFactoryConcrete(concrete)) {
+            binding.toDynamicValue(() => concrete(this)).inSingletonScope();
+            return this;
+        }
+
+        binding.toConstantValue(concrete as T);
+        return this;
+    }
+
+    transient<T>(
+        identifier: ContainerIdentifier<T>,
+        concrete: ContainerConcrete<T>,
+    ): this {
+        this.removeIfBound(identifier);
+
+        const binding = this.container.bind(identifier);
+        if (isClassConcrete(concrete)) {
+            binding.to(concrete).inTransientScope();
+            return this;
+        }
+
+        if (isFactoryConcrete(concrete)) {
+            binding.toDynamicValue(() => concrete(this)).inTransientScope();
+            return this;
+        }
+
+        binding.toDynamicValue(() => concrete as T).inTransientScope();
+        return this;
+    }
+
+    instance<T>(identifier: ContainerIdentifier<T>, value: T): this {
+        this.removeIfBound(identifier);
+        this.container.bind(identifier).toConstantValue(value);
+        return this;
+    }
+
+    make<T>(identifier: ContainerIdentifier<T>): T {
+        return this.container.get<T>(identifier);
+    }
+
+    get<T>(identifier: ContainerIdentifier<T>): T {
+        return this.make<T>(identifier);
+    }
+
+    bound(identifier: ContainerIdentifier): boolean {
+        return this.container.isBound(identifier);
+    }
+
+    has(identifier: ContainerIdentifier): boolean {
+        return this.bound(identifier);
+    }
+
+    unbind(identifier: ContainerIdentifier): void {
+        if (this.container.isBound(identifier)) {
+            this.container.unbind(identifier);
+        }
+    }
+
+    unbindAll(): void {
+        this.container.unbindAll();
+    }
+
+    flush(): void {
+        this.unbindAll();
+    }
+
+    getRawContainer(): unknown {
+        return this.container;
+    }
+
+    protected removeIfBound(identifier: ContainerIdentifier): void {
+        if (this.container.isBound(identifier)) {
+            this.container.unbind(identifier);
+        }
+    }
+}

package/src/container/contract.ts

@@ -0,0 +1,58 @@
+export type ContainerFactory<T> = (container: ContainerContract) => T;
+export type ContainerClass<T> = new (...args: any[]) => T;
+export type ContainerIdentifier<T = unknown> =
+    | string
+    | symbol
+    | ContainerClass<T>;
+export type ContainerConcrete<T> = ContainerClass<T> | ContainerFactory<T> | T;
+
+export interface ContainerScopeSyntax {
+    /** Set singleton scope for this binding. */
+    inSingletonScope(): void;
+    /** Set transient scope for this binding. */
+    inTransientScope(): void;
+}
+
+export interface ContainerBindToSyntax<T> {
+    /** Bind an identifier to a concrete class. */
+    to(concrete: ContainerClass<T>): ContainerScopeSyntax;
+    /** Bind an identifier to a dynamic factory callback. */
+    toDynamicValue(
+        concrete: (context: { container: ContainerContract }) => T,
+    ): ContainerScopeSyntax;
+    /** Bind an identifier to a constant shared value. */
+    toConstantValue(value: T): void;
+}
+
+export interface ContainerContract {
+    /** Register a binding fluent definition for an identifier. */
+    bind<T>(identifier: ContainerIdentifier<T>): ContainerBindToSyntax<T>;
+    /** Register a singleton binding using a class, factory, or value concrete. */
+    singleton<T>(
+        identifier: ContainerIdentifier<T>,
+        concrete: ContainerConcrete<T>,
+    ): this;
+    /** Register a transient binding using a class, factory, or value concrete. */
+    transient<T>(
+        identifier: ContainerIdentifier<T>,
+        concrete: ContainerConcrete<T>,
+    ): this;
+    /** Register an existing instance as a shared binding. */
+    instance<T>(identifier: ContainerIdentifier<T>, value: T): this;
+    /** Resolve an instance from the container. */
+    make<T>(identifier: ContainerIdentifier<T>): T;
+    /** Compatibility alias for make(). */
+    get<T>(identifier: ContainerIdentifier<T>): T;
+    /** Determine if an identifier is currently bound. */
+    bound(identifier: ContainerIdentifier): boolean;
+    /** Alias for bound(). */
+    has(identifier: ContainerIdentifier): boolean;
+    /** Remove a specific binding by identifier. */
+    unbind(identifier: ContainerIdentifier): void;
+    /** Remove all bindings from the container. */
+    unbindAll(): void;
+    /** Clear all bindings. */
+    flush(): void;
+    /** Expose the underlying container for advanced use. */
+    getRawContainer(): unknown;
+}

package/src/container/runtime.ts

@@ -0,0 +1,149 @@
+import BuiltinContainer from "./adapters/builtin";
+import type { ContainerContract } from "./contract";
+
+export type ContainerAdapter = "auto" | "builtin" | "inversify";
+
+export type ContainerRuntimeOptions = {
+    adapter?: ContainerAdapter;
+    factory?: (() => ContainerContract) | null;
+};
+
+export type ResolvedContainerRuntimeOptions = {
+    adapter: ContainerAdapter;
+    factory: (() => ContainerContract) | null;
+};
+
+type PackageJsonLike = {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+};
+
+type ContainerFactoryRegistry = {
+    inversify?: () => ContainerContract;
+};
+
+type GlobLoader = (
+    pattern: string | string[],
+    options?: { eager?: boolean },
+) => Record<string, unknown>;
+
+export function mergeContainerRuntimeOptions(
+    options: ContainerRuntimeOptions = {},
+): ResolvedContainerRuntimeOptions {
+    return {
+        adapter: options.adapter ?? "auto",
+        factory: options.factory ?? null,
+    };
+}
+
+export function readPackageJsonCandidates(): PackageJsonLike[] {
+    const testValue = (
+        globalThis as {
+            __iocPackageJsonForTests?:
+                | PackageJsonLike
+                | PackageJsonLike[]
+                | (() => PackageJsonLike | PackageJsonLike[]);
+        }
+    ).__iocPackageJsonForTests;
+
+    if (typeof testValue === "function") {
+        const value = testValue();
+        return Array.isArray(value) ? value : [value];
+    }
+    if (testValue) {
+        return Array.isArray(testValue) ? testValue : [testValue];
+    }
+
+    const viteGlob = (
+        import.meta as ImportMeta & {
+            glob?: GlobLoader;
+        }
+    ).glob;
+    const testGlob = (
+        globalThis as {
+            __iocPackageJsonGlobForTests?: GlobLoader;
+        }
+    ).__iocPackageJsonGlobForTests;
+    const glob =
+        typeof viteGlob === "function" ? viteGlob
+        : typeof testGlob === "function" ? testGlob
+        : null;
+    if (!glob) {
+        return [];
+    }
+
+    const modules = glob("/package.json", { eager: true });
+    return Object.values(modules)
+        .map((value) => {
+            if (
+                value &&
+                typeof value === "object" &&
+                "default" in (value as Record<string, unknown>)
+            ) {
+                return (value as { default: unknown })
+                    .default as PackageJsonLike;
+            }
+            return value as PackageJsonLike;
+        })
+        .filter((value) => Boolean(value && typeof value === "object"));
+}
+
+export function packageJsonHasDependency(
+    packageJson: PackageJsonLike,
+    dependency: string,
+): boolean {
+    return Boolean(
+        packageJson.dependencies?.[dependency] ||
+        packageJson.devDependencies?.[dependency] ||
+        packageJson.peerDependencies?.[dependency],
+    );
+}
+
+export function readContainerFactoryRegistry(): ContainerFactoryRegistry {
+    return (
+        (
+            globalThis as {
+                __iocContainerFactoryRegistry?: ContainerFactoryRegistry;
+            }
+        ).__iocContainerFactoryRegistry ?? {}
+    );
+}
+
+export function hasInversifyDependency(): boolean {
+    const packageJsonCandidates = readPackageJsonCandidates();
+    return packageJsonCandidates.some((packageJson) =>
+        packageJsonHasDependency(packageJson, "inversify"),
+    );
+}
+
+export function createRuntimeContainer(
+    options: ResolvedContainerRuntimeOptions,
+): ContainerContract {
+    if (typeof options.factory === "function") {
+        return options.factory();
+    }
+
+    if (options.adapter === "builtin") {
+        return new BuiltinContainer();
+    }
+
+    const inversifyFactory = readContainerFactoryRegistry().inversify;
+    const shouldUseInversify =
+        options.adapter === "inversify" ||
+        (options.adapter === "auto" && hasInversifyDependency());
+
+    if (shouldUseInversify) {
+        if (typeof inversifyFactory === "function") {
+            return inversifyFactory();
+        }
+
+        if (options.adapter === "inversify") {
+            throw new Error(
+                "Inversify adapter is not registered. Provide container.factory or register __iocContainerFactoryRegistry.inversify.",
+            );
+        }
+    }
+
+    return new BuiltinContainer();
+}