@raubjo/architect 0.5.1

package/src/support/facades/cache.ts

@@ -0,0 +1,6 @@
+import type CacheManager from "../../cache/manager"
+import { createFacade } from "./facade"
+
+export const Cache = createFacade<CacheManager>("cache")
+
+export default Cache

package/src/support/facades/config.ts

@@ -0,0 +1,6 @@
+import type ConfigRepository from "../../config/repository"
+import { createFacade } from "./facade"
+
+export const Config = createFacade<ConfigRepository>("config")
+
+export default Config

package/src/support/facades/event.ts

@@ -0,0 +1,6 @@
+import type { Bus } from "../../events/bus"
+import { createFacade } from "./facade"
+
+export const Event = createFacade<Bus>("events")
+
+export default Event

package/src/support/facades/facade.ts

@@ -0,0 +1,146 @@
+import { makeFromCurrentApplication } from "../../foundation/current-application"
+
+// Module-level state shared by all facades.
+const macroRegistry = new Map<string, Map<string, (...args: unknown[]) => unknown>>()
+const resolvedInstances = new Map<string, unknown>()
+
+export function clearFacadeCache(): void {
+    resolvedInstances.clear()
+}
+
+export function flushAllMacros(): void {
+    macroRegistry.clear()
+}
+
+function getMacros(accessor: string): Map<string, (...args: unknown[]) => unknown> {
+    let macros = macroRegistry.get(accessor)
+    if (!macros) {
+        macros = new Map()
+        macroRegistry.set(accessor, macros)
+    }
+    return macros
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface FacadeInstance<T = unknown> {
+    getFacadeAccessor(): string
+    macro(name: string, fn: (instance: T, ...args: unknown[]) => unknown): void
+    hasMacro(name: string): boolean
+    flushMacros(): void
+    clearResolvedInstance(name: string): void
+    clearResolvedInstances(): void
+    callFacadeMethod(method: string, ...args: unknown[]): unknown
+    callFacadeMethod<R = unknown>(method: string, ...args: unknown[]): R
+    use(...args: unknown[]): unknown
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [key: string]: any
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createFacade<T = any>(accessor: string): FacadeInstance<T> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let proxy: any
+
+    const facade: Record<string, unknown> = {
+        getFacadeAccessor(): string {
+            return accessor
+        },
+
+        macro(name: string, fn: (instance: T, ...args: unknown[]) => unknown): void {
+            getMacros(accessor).set(name, fn as (...args: unknown[]) => unknown)
+        },
+
+        hasMacro(name: string): boolean {
+            return getMacros(accessor).has(name)
+        },
+
+        flushMacros(): void {
+            getMacros(accessor).clear()
+        },
+
+        clearResolvedInstance(name: string): void {
+            resolvedInstances.delete(name)
+        },
+
+        clearResolvedInstances(): void {
+            resolvedInstances.clear()
+        },
+
+        callFacadeMethod<R = unknown>(method: string, ...args: unknown[]): R {
+            const macro = getMacros(accessor).get(method)
+            if (macro) {
+                const instance = resolveInstance<T>(accessor)
+                return macro(instance, ...args) as R
+            }
+
+            const instance = resolveInstance<Record<string, (...a: unknown[]) => unknown>>(accessor)
+            const callable = instance[method]
+            if (typeof callable !== "function") {
+                throw new Error(`Method [${method}] does not exist on resolved facade instance.`)
+            }
+
+            return callable.apply(instance, args) as R
+        },
+
+        // use() returns the proxy instead of the instance's return value so callers can chain.
+        use(...args: unknown[]): unknown {
+            const instance = resolveInstance<Record<string, (...a: unknown[]) => unknown>>(accessor)
+            if (typeof instance.use === "function") {
+                instance.use(...args)
+            }
+            return proxy
+        },
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    proxy = new Proxy(facade, {
+        get(target, prop) {
+            if (prop in target) {
+                return target[prop as string]
+            }
+
+            const name = String(prop)
+
+            // Macro check (takes precedence over instance methods).
+            const macros = getMacros(accessor)
+            const macro = macros.get(name)
+            if (macro) {
+                return (...args: unknown[]) => {
+                    const instance = resolveInstance<T>(accessor)
+                    return macro(instance, ...args)
+                }
+            }
+
+            const instance = resolveInstance<Record<string, unknown>>(accessor)
+            const value = instance[prop as keyof typeof instance]
+
+            if (typeof value === "function") {
+                return (...args: unknown[]) => {
+                    return (value as (...a: unknown[]) => unknown).apply(instance, args)
+                }
+            }
+
+            return value
+        },
+
+        has(target, prop) {
+            if (prop in target) return true
+            const name = String(prop)
+            if (getMacros(accessor).has(name)) return true
+            const instance = resolveInstance<Record<string, unknown>>(accessor)
+            return name in instance
+        },
+    })
+
+    return proxy as FacadeInstance<T>
+}
+
+function resolveInstance<T>(accessor: string): T {
+    if (resolvedInstances.has(accessor)) {
+        return resolvedInstances.get(accessor) as T
+    }
+
+    const instance = makeFromCurrentApplication<T>(accessor)
+    resolvedInstances.set(accessor, instance)
+    return instance
+}

package/src/support/facades/index.ts

@@ -0,0 +1,5 @@
+export { Cache } from "./cache"
+export { Config } from "./config"
+export { Event } from "./event"
+export { Log } from "./log"
+export { Store } from "./store"

package/src/support/facades/log.ts

@@ -0,0 +1,6 @@
+import type LogManager from "../../log/manager"
+import { createFacade } from "./facade"
+
+export const Log = createFacade<LogManager>("log")
+
+export default Log

package/src/support/facades/store.ts

@@ -0,0 +1,6 @@
+import type StoreManager from "../../store/manager"
+import { createFacade } from "./facade"
+
+export const Store = createFacade<StoreManager>("store")
+
+export default Store

package/src/support/fluent.ts

@@ -0,0 +1,56 @@
+// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: Proxy in constructor handles runtime property access; interface merging is intentional for typed T["key"] access
+export class Fluent<T extends Record<string, unknown> = Record<string, unknown>> {
+    protected attributes: Record<string, unknown>
+
+    constructor(attributes: T = {} as T) {
+        this.attributes = { ...attributes }
+
+        // biome-ignore lint/correctness/noConstructorReturn: Creating a proxy for magic methods: `get()`
+        return new Proxy(this, {
+            get(target, prop, receiver) {
+                if (typeof prop === "string" && !(prop in target)) {
+                    return target.attributes[prop]
+                }
+                return Reflect.get(target, prop, receiver)
+            },
+        }) as Fluent<T>
+    }
+
+    get(key: string): unknown
+    get<V>(key: string): V | null
+    get<V>(key: string, defaultValue: V): V
+    get<V>(key: string, defaultValue: V | null): V | null
+    get<V = unknown>(key: string, defaultValue?: V | null): unknown {
+        const fallback = defaultValue !== undefined ? defaultValue : null
+        const parts = key.split(".")
+        let current: unknown = this.attributes
+        for (const part of parts) {
+            if (current === null || current === undefined || typeof current !== "object") return fallback
+            current = (current as Record<string, unknown>)[part]
+        }
+        return current === undefined ? fallback : current
+    }
+
+    set(key: string, value: unknown): this {
+        const parts = key.split(".")
+        let current = this.attributes
+        for (let i = 0; i < parts.length - 1; i++) {
+            const part = parts[i]
+            if (typeof current[part] !== "object" || current[part] === null) current[part] = {}
+            current = current[part] as Record<string, unknown>
+        }
+        current[parts[parts.length - 1]] = value
+        return this
+    }
+
+    has(key: string): boolean {
+        return this.get(key) !== null
+    }
+
+    toArray(): T {
+        return { ...this.attributes } as T
+    }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface Fluent<T extends Record<string, unknown> = Record<string, unknown>> extends T {}

package/src/support/globals.ts

@@ -0,0 +1,8 @@
+export function registerGlobalHelpers(helpers: Record<string, unknown>): void {
+    const globalScope = globalThis as Record<string, unknown>
+    for (const [key, value] of Object.entries(helpers)) {
+        if (typeof globalScope[key] === "undefined") {
+            globalScope[key] = value
+        }
+    }
+}

package/src/support/lazy-collection.ts

@@ -0,0 +1,341 @@
+import { Collection } from "./collection"
+
+export class LazyCollection<T> implements Iterable<T> {
+    protected constructor(protected readonly source: () => Iterable<T>) {}
+
+    static make<T>(source: (() => Iterable<T>) | Iterable<T>): LazyCollection<T> {
+        if (typeof source === "function") {
+            return new LazyCollection(source as () => Iterable<T>)
+        }
+        const captured = source
+        return new LazyCollection(() => captured)
+    }
+
+    static times<U>(count: number, callback: (n: number) => U): LazyCollection<U> {
+        return new LazyCollection(function* () {
+            for (let i = 1; i <= count; i++) {
+                yield callback(i)
+            }
+        })
+    }
+
+    [Symbol.iterator](): Iterator<T> {
+        return this.source()[Symbol.iterator]()
+    }
+
+    // ── Lazy (return LazyCollection) ──────────────────────────────────────────
+
+    map<U>(callback: (item: T, index: number) => U): LazyCollection<U> {
+        const self = this
+        return new LazyCollection(function* () {
+            let i = 0
+            for (const item of self) {
+                yield callback(item, i++)
+            }
+        })
+    }
+
+    filter(callback?: (item: T, index: number) => boolean): LazyCollection<T> {
+        const self = this
+        return new LazyCollection(function* () {
+            let i = 0
+            for (const item of self) {
+                if (callback ? callback(item, i++) : Boolean(item)) yield item
+                else i++
+            }
+        })
+    }
+
+    reject(callback: (item: T, index: number) => boolean): LazyCollection<T> {
+        return this.filter((item, i) => !callback(item, i))
+    }
+
+    flatMap<U>(callback: (item: T, index: number) => U[]): LazyCollection<U> {
+        const self = this
+        return new LazyCollection(function* () {
+            let i = 0
+            for (const item of self) {
+                yield* callback(item, i++)
+            }
+        })
+    }
+
+    take(count: number): LazyCollection<T> {
+        const self = this
+        return new LazyCollection(function* () {
+            if (count <= 0) return
+            let n = 0
+            const iter = self[Symbol.iterator]()
+            while (n < count) {
+                const { done, value } = iter.next()
+                if (done) break
+                yield value
+                n++
+            }
+        })
+    }
+
+    skip(count: number): LazyCollection<T> {
+        const self = this
+        return new LazyCollection(function* () {
+            let n = 0
+            for (const item of self) {
+                if (n++ < count) continue
+                yield item
+            }
+        })
+    }
+
+    takeUntil(valueOrCallback: T | ((item: T, index: number) => boolean)): LazyCollection<T> {
+        const self = this
+        return new LazyCollection(function* () {
+            let i = 0
+            const iter = self[Symbol.iterator]()
+            while (true) {
+                const { done, value } = iter.next()
+                if (done) break
+                const match =
+                    typeof valueOrCallback === "function"
+                        ? (valueOrCallback as (item: T, index: number) => boolean)(value, i++)
+                        : value === valueOrCallback
+                if (match) break
+                yield value
+            }
+        })
+    }
+
+    takeWhile(callback: (item: T, index: number) => boolean): LazyCollection<T> {
+        return this.takeUntil((item, i) => !callback(item, i))
+    }
+
+    skipUntil(valueOrCallback: T | ((item: T, index: number) => boolean)): LazyCollection<T> {
+        if (typeof valueOrCallback === "function") {
+            return this.skipWhile((item, i) => !valueOrCallback(item, i))
+        }
+        return this.skipWhile((item) => item !== valueOrCallback)
+    }
+
+    skipWhile(callback: (item: T, index: number) => boolean): LazyCollection<T> {
+        const self = this
+        return new LazyCollection(function* () {
+            let skipping = true
+            let i = 0
+            for (const item of self) {
+                if (skipping && callback(item, i++)) continue
+                skipping = false
+                yield item
+            }
+        })
+    }
+
+    tap(callback: (item: T) => void): LazyCollection<T> {
+        const self = this
+        return new LazyCollection(function* () {
+            for (const item of self) {
+                callback(item)
+                yield item
+            }
+        })
+    }
+
+    chunk(size: number): LazyCollection<T[]> {
+        const self = this
+        return new LazyCollection(function* () {
+            let buf: T[] = []
+            for (const item of self) {
+                buf.push(item)
+                if (buf.length === size) {
+                    yield buf
+                    buf = []
+                }
+            }
+            if (buf.length > 0) yield buf
+        })
+    }
+
+    concat(other: Iterable<T>): LazyCollection<T> {
+        const self = this
+        return new LazyCollection(function* () {
+            yield* self
+            yield* other
+        })
+    }
+
+    values(): LazyCollection<T> {
+        return this
+    }
+
+    unique(key?: keyof T | ((item: T) => unknown)): LazyCollection<T> {
+        const self = this
+        return new LazyCollection(function* () {
+            const seen = new Set<unknown>()
+            for (const item of self) {
+                const v = self.extractValue(item, key)
+                if (!seen.has(v)) {
+                    seen.add(v)
+                    yield item
+                }
+            }
+        })
+    }
+
+    pluck<K extends keyof T>(key: K): LazyCollection<T[K]> {
+        return this.map((item) => item[key])
+    }
+
+    // ── Terminal (materialize) ─────────────────────────────────────────────────
+
+    collect(): Collection<T> {
+        return new Collection(this.all())
+    }
+
+    all(): T[] {
+        return [...this]
+    }
+
+    toArray(): T[] {
+        return this.all()
+    }
+
+    count(): number {
+        return this.all().length
+    }
+
+    first(callback?: (item: T, index: number) => boolean): T | null {
+        let i = 0
+        for (const item of this) {
+            if (!callback || callback(item, i++)) return item
+        }
+        return null
+    }
+
+    last(callback?: (item: T, index: number) => boolean): T | null {
+        let result: T | null = null
+        let i = 0
+        for (const item of this) {
+            if (!callback || callback(item, i++)) result = item
+        }
+        return result
+    }
+
+    each(callback: (item: T, index: number) => void): void {
+        let i = 0
+        for (const item of this) {
+            callback(item, i++)
+        }
+    }
+
+    reduce<U>(callback: (carry: U, item: T, index: number) => U, initial: U): U {
+        let acc = initial
+        let i = 0
+        for (const item of this) {
+            acc = callback(acc, item, i++)
+        }
+        return acc
+    }
+
+    sum(key?: keyof T | ((item: T) => number)): number {
+        let total = 0
+        for (const item of this) total += this.extractValue(item, key) as number
+        return total
+    }
+
+    min(key?: keyof T | ((item: T) => number)): T | null {
+        let result: T | null = null
+        let minVal: number | null = null
+        for (const item of this) {
+            const v = this.extractValue(item, key) as number
+            if (minVal === null || v < minVal) {
+                minVal = v
+                result = item
+            }
+        }
+        return result
+    }
+
+    max(key?: keyof T | ((item: T) => number)): T | null {
+        let result: T | null = null
+        let maxVal: number | null = null
+        for (const item of this) {
+            const v = this.extractValue(item, key) as number
+            if (maxVal === null || v > maxVal) {
+                maxVal = v
+                result = item
+            }
+        }
+        return result
+    }
+
+    avg(key?: keyof T | ((item: T) => number)): number {
+        let total = 0
+        let count = 0
+        for (const item of this) {
+            total += this.extractValue(item, key) as number
+            count++
+        }
+        return count === 0 ? 0 : total / count
+    }
+
+    average(key?: keyof T | ((item: T) => number)): number {
+        return this.avg(key)
+    }
+
+    contains(itemOrCallback: T | ((item: T) => boolean)): boolean {
+        const test =
+            typeof itemOrCallback === "function"
+                ? (itemOrCallback as (item: T) => boolean)
+                : (i: T) => i === itemOrCallback
+        for (const item of this) {
+            if (test(item)) return true
+        }
+        return false
+    }
+
+    every(callback: (item: T, index: number) => boolean): boolean {
+        let i = 0
+        for (const item of this) {
+            if (!callback(item, i++)) return false
+        }
+        return true
+    }
+
+    some(callback: (item: T, index: number) => boolean): boolean {
+        let i = 0
+        for (const item of this) {
+            if (callback(item, i++)) return true
+        }
+        return false
+    }
+
+    groupBy<K extends string>(key: keyof T | ((item: T) => K)): Record<string, LazyCollection<T>> {
+        const groups: Record<string, T[]> = {}
+        for (const item of this) {
+            const k = String(this.extractValue(item, key))
+            if (!groups[k]) groups[k] = []
+            groups[k].push(item)
+        }
+        return Object.fromEntries(Object.entries(groups).map(([k, v]) => [k, LazyCollection.make(v)]))
+    }
+
+    toJson(): string {
+        return JSON.stringify(this.all())
+    }
+
+    // ── protected helpers ───────────────────────────────────────────────────────
+
+    protected extractValue(item: T, key?: keyof T | ((item: T) => unknown)): unknown {
+        if (!key) return item
+        return typeof key === "function" ? key(item) : item[key]
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+
+    isEmpty(): boolean {
+        for (const _ of this) return false
+        return true
+    }
+
+    isNotEmpty(): boolean {
+        return !this.isEmpty()
+    }
+}

package/src/support/manager.ts

@@ -0,0 +1,53 @@
+import ConfigRepository from "../config/repository"
+
+export default abstract class Manager<TDriver, TFactory = TDriver> {
+    protected drivers: Record<string, TDriver>
+    protected customCreators: Record<string, (config: ConfigRepository) => TDriver>
+    protected active: string
+    protected config: ConfigRepository
+
+    constructor(
+        drivers: Record<string, TDriver>,
+        active = "default",
+        config: ConfigRepository = new ConfigRepository({}),
+    ) {
+        this.drivers = { ...drivers }
+        this.customCreators = {}
+        this.config = config
+        this.active = active in drivers ? active : this.defaultDriverName()
+    }
+
+    extend(name: string, factory: (config: ConfigRepository) => TFactory): this {
+        this.customCreators[name] = (cfg) => this.createDriver(factory(cfg), cfg)
+        return this
+    }
+
+    use(name: string): this {
+        this.active = this.resolve(name) ? name : this.active
+        return this
+    }
+
+    protected abstract createDriver(raw: TFactory, config: ConfigRepository): TDriver
+
+    protected defaultDriverName(): string {
+        return Object.keys(this.drivers)[0] ?? "default"
+    }
+
+    protected driverType(): string {
+        return "Driver"
+    }
+
+    protected resolve(name: string): TDriver {
+        if (name in this.drivers) {
+            return this.drivers[name]
+        }
+
+        if (name in this.customCreators) {
+            const driver = this.customCreators[name](this.config)
+            this.drivers[name] = driver
+            return driver
+        }
+
+        throw new Error(`${this.driverType()} [${name}] is not defined.`)
+    }
+}