@raubjo/architect 0.5.1

package/src/config/repository.ts

@@ -0,0 +1,164 @@
+import type { Contract } from "./contract"
+
+export type ConfigItems = Record<string, unknown>
+export type ConfigDefaults = Record<string | number, unknown>
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function resolveDefault<T>(defaultValue: T | (() => T)): T {
+    return typeof defaultValue === "function" ? (defaultValue as () => T)() : defaultValue
+}
+
+function dataGet(source: unknown, path: string, defaultValue: unknown = null): unknown {
+    if (!path) {
+        return source
+    }
+
+    const segments = path.split(".")
+    let cursor: unknown = source
+
+    for (const segment of segments) {
+        if (!hasDataKey(cursor, segment)) {
+            return resolveDefault(defaultValue)
+        }
+
+        cursor = cursor[segment]
+    }
+
+    return cursor
+}
+
+function hasDataKey(value: unknown, key: string): value is Record<string, unknown> {
+    return isPlainObject(value) && key in value
+}
+
+function dataTraverse(
+    target: Record<string, unknown>,
+    path: string,
+    onCreate: boolean,
+): [Record<string, unknown>, string] | null {
+    const segments = path.split(".")
+    let cursor: Record<string, unknown> = target
+
+    for (let i = 0; i < segments.length - 1; i += 1) {
+        const segment = segments[i]
+
+        if (!isPlainObject(cursor[segment])) {
+            if (!onCreate) return null
+            cursor[segment] = {}
+        }
+
+        cursor = cursor[segment] as Record<string, unknown>
+    }
+
+    return [cursor, segments[segments.length - 1]]
+}
+
+function dataSet(target: Record<string, unknown>, path: string, value: unknown): void {
+    const result = dataTraverse(target, path, true)
+    if (result) result[0][result[1]] = value
+}
+
+function dataForget(target: Record<string, unknown>, path: string): void {
+    const result = dataTraverse(target, path, false)
+    if (result) delete result[0][result[1]]
+}
+
+class ConfigRepository implements Contract {
+    protected items: ConfigItems
+
+    constructor(items: ConfigItems = {}) {
+        this.items = items
+    }
+
+    has(key: string | string[]): boolean {
+        const keys = Array.isArray(key) ? key : [key]
+        for (const configKey of keys) {
+            if (this.get(configKey) == null) {
+                return false
+            }
+        }
+
+        return true
+    }
+
+    get(key: string): unknown
+    get<T>(key: string): T | null
+    get<T>(key: string, defaultValue: T | (() => T)): T
+    get<T>(key: string, defaultValue: T | (() => T) | null): T | null
+    get(key: string[]): Record<string, unknown>
+    get<T = unknown>(
+        key: string | string[],
+        defaultValue: T | (() => T) | null = null,
+    ): T | Record<string, unknown> | null {
+        if (Array.isArray(key)) {
+            return this.getMany(key)
+        }
+
+        return dataGet(this.items, key, defaultValue) as T | null
+    }
+
+    getMany(keys: string[] | ConfigDefaults): Record<string, unknown> {
+        const results: Record<string, unknown> = {}
+
+        if (Array.isArray(keys)) {
+            for (const key of keys) {
+                results[key] = this.get(key)
+            }
+
+            return results
+        }
+
+        for (const [key, defaultValue] of Object.entries(keys)) {
+            results[key] = this.get(key, defaultValue)
+        }
+
+        return results
+    }
+
+    set(key: string | ConfigItems, value: unknown = null): void {
+        const payload = isPlainObject(key) ? key : { [key]: value }
+
+        for (const [configKey, configValue] of Object.entries(payload)) {
+            dataSet(this.items, configKey, configValue)
+        }
+    }
+
+    prepend(key: string, value: unknown): void {
+        const values = this.get<unknown[]>(key, [])
+        this.set(key, [value, ...values])
+    }
+
+    push(key: string, value: unknown): void {
+        const values = this.get<unknown[]>(key, [])
+        values.push(value)
+        this.set(key, values)
+    }
+
+    all(): ConfigItems {
+        return this.items
+    }
+
+    offsetExists(key: string): boolean {
+        return this.has(key)
+    }
+
+    offsetGet(key: string): unknown
+    offsetGet<T>(key: string): T | null
+    offsetGet<T = unknown>(key: string): T | null {
+        return this.get<T>(key) as T | null
+    }
+
+    offsetSet(key: string, value: unknown): void {
+        this.set(key, value)
+    }
+
+    offsetUnset(key: string): void {
+        dataForget(this.items, key)
+    }
+}
+
+export { ConfigRepository }
+export default ConfigRepository

package/src/container/adapters/builtin.ts

@@ -0,0 +1,323 @@
+import type {
+    ContainerBindToSyntax,
+    ContainerClass,
+    ContainerConcrete,
+    ContainerFactory,
+    ContainerIdentifier,
+} from "../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.hasOwn(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
+}
+
+function readConstructorParamTypes(target: object): Array<ContainerIdentifier | undefined> {
+    return (
+        (metadataReflect.getMetadata?.("design:paramtypes", target) as
+            | Array<ContainerIdentifier | undefined>
+            | undefined) ?? []
+    )
+}
+
+class BuiltinBindingFluent<T> {
+    protected record: BindingRecord<T> | null = null
+
+    constructor(
+        protected readonly container: BuiltinContainer,
+        protected readonly identifier: ContainerIdentifier<T>,
+    ) {}
+
+    to(concrete: ContainerConcrete<T>): {
+        inSingletonScope: () => void
+        inTransientScope: () => void
+    } {
+        if (isClassConcrete(concrete)) {
+            this.record = { kind: "class", concrete, scope: "singleton" }
+        } else if (isFactoryConcrete(concrete)) {
+            this.record = { kind: "factory", concrete, scope: "singleton" }
+        } else {
+            this.record = { kind: "constant", value: concrete as T }
+        }
+
+        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>
+    bind<T>(identifier: ContainerIdentifier<T>, concrete: ContainerConcrete<T>): this
+    bind<T>(identifier: ContainerIdentifier<T>, concrete?: ContainerConcrete<T>): ContainerBindToSyntax<T> | this {
+        if (typeof concrete !== "undefined") {
+            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
+        }
+
+        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
+    }
+
+    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 (this.hasCachedSingleton(record)) {
+            return record.cached
+        }
+
+        const resolved = this.resolveConcrete(record)
+
+        if (record.scope === "singleton") {
+            record.cached = resolved
+        }
+
+        return resolved
+    }
+
+    protected resolveConcrete<T>(record: Exclude<BindingRecord<T>, { kind: "constant" }>): T {
+        if (record.kind === "class") {
+            return this.resolveClass(record.concrete)
+        }
+
+        return record.concrete(this)
+    }
+
+    protected hasCachedSingleton<T>(record: BindingRecord<T>): record is BindingRecord<T> & { cached: T } {
+        return (
+            record.kind !== "constant" &&
+            record.scope === "singleton" &&
+            "cached" in record &&
+            typeof record.cached !== "undefined"
+        )
+    }
+
+    protected resolveClass<T>(concrete: ContainerClass<T>): T {
+        this.assertNotResolving(concrete)
+        this.resolving.add(concrete)
+
+        try {
+            const paramTypes = readConstructorParamTypes(concrete)
+            const injectTokens = readInjectTokens(concrete)
+            const args = paramTypes.map((designType, index) =>
+                this.resolveParameter(concrete, injectTokens, designType, index),
+            )
+
+            return new concrete(...args)
+        } finally {
+            this.resolving.delete(concrete)
+        }
+    }
+
+    protected assertNotResolving(concrete: ContainerClass<unknown>): void {
+        if (this.resolving.has(concrete)) {
+            throw new Error(`Circular dependency detected while resolving [${concrete.name || "anonymous"}].`)
+        }
+    }
+
+    protected resolveParameter(
+        concrete: ContainerClass<unknown>,
+        injectTokens: Map<number, ContainerIdentifier>,
+        designType: ContainerIdentifier | undefined,
+        index: number,
+    ): unknown {
+        const token = injectTokens.get(index) ?? designType
+        if (!token) {
+            throw new Error(`Cannot resolve parameter #${index} for [${concrete.name || "anonymous"}].`)
+        }
+
+        return this.make(token)
+    }
+}

package/src/container/contract.ts

@@ -0,0 +1,43 @@
+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 class, factory, or value concrete. */
+    to(concrete: ContainerConcrete<T>): ContainerScopeSyntax
+    /** Bind an identifier to a constant shared value. */
+    toConstantValue(value: T): void
+}
+
+export interface ContainerContract {
+    /** Register a singleton binding using a class, factory, or value concrete. */
+    singleton<T>(identifier: ContainerIdentifier<T>, concrete: ContainerConcrete<T>): this
+    /** Register a binding using a class, factory, or value concrete. */
+    bind<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,29 @@
+import BuiltinContainer from "./adapters/builtin"
+import type { ContainerContract } from "./contract"
+
+export type ContainerAdapter = "builtin"
+
+export type ContainerRuntimeOptions = {
+    adapter?: ContainerAdapter
+    factory?: (() => ContainerContract) | null
+}
+
+export type ResolvedContainerRuntimeOptions = {
+    adapter: ContainerAdapter
+    factory: (() => ContainerContract) | null
+}
+
+export function mergeContainerRuntimeOptions(options: ContainerRuntimeOptions = {}): ResolvedContainerRuntimeOptions {
+    return {
+        adapter: options.adapter ?? "builtin",
+        factory: options.factory ?? null,
+    }
+}
+
+export function createRuntimeContainer(options: ResolvedContainerRuntimeOptions): ContainerContract {
+    if (typeof options.factory === "function") {
+        return options.factory()
+    }
+
+    return new BuiltinContainer()
+}