@raubjo/architect 0.5.1

package/src/events/bus.ts

@@ -0,0 +1,174 @@
+export type {
+    EventClass,
+    EventIdentifier,
+    Listener,
+    ListenerObject,
+    Unsubscribe,
+    WildcardListener,
+} from "./types"
+
+import type { EventClass, EventIdentifier, Listener, ListenerObject, Unsubscribe, WildcardListener } from "./types"
+
+export interface EventSubscriber {
+    subscribe(bus: Bus): Record<string, Listener | string> | void
+}
+
+export class Bus {
+    protected listeners = new Map<string, Listener[]>()
+    protected wildcardListeners: WildcardListener[] = []
+    protected pushedEvents = new Map<string, Record<string, unknown>[]>()
+
+    listen<T>(
+        event: EventIdentifier<T> | Array<EventIdentifier<T>>,
+        listener: Listener<T> | ListenerObject<T>,
+    ): Unsubscribe {
+        const events = Array.isArray(event) ? event : [event]
+        const normalized = this.normalizeListener(listener) as Listener
+        const unsubscribers: Unsubscribe[] = []
+
+        for (const ev of events) {
+            const name = this.resolveEventName(ev)
+
+            if (name === "*") {
+                const wl: WildcardListener = (_name, data) => void normalized(data as T)
+                this.wildcardListeners.push(wl)
+                unsubscribers.push(() => {
+                    const idx = this.wildcardListeners.indexOf(wl)
+                    if (idx !== -1) this.wildcardListeners.splice(idx, 1)
+                })
+                continue
+            }
+
+            const current = this.listeners.get(name) ?? []
+            current.push(normalized)
+            this.listeners.set(name, current)
+
+            unsubscribers.push(() => {
+                const all = this.listeners.get(name) ?? []
+                const updated = all.filter((l) => l !== normalized)
+                if (updated.length === 0) {
+                    this.listeners.delete(name)
+                } else {
+                    this.listeners.set(name, updated)
+                }
+            })
+        }
+
+        return () => {
+            unsubscribers.forEach((fn) => {
+                fn()
+            })
+        }
+    }
+
+    once<T>(event: EventIdentifier<T>, listener: Listener<T> | ListenerObject<T>): Unsubscribe {
+        const normalized = this.normalizeListener(listener)
+        let unsubscribe!: Unsubscribe
+
+        const wrapped: Listener<T> = async (data: T) => {
+            unsubscribe()
+            return normalized(data)
+        }
+
+        unsubscribe = this.listen(event, wrapped)
+        return unsubscribe
+    }
+
+    subscribe(subscriber: EventSubscriber | (new () => EventSubscriber)): void {
+        const instance = typeof subscriber === "function" ? new subscriber() : subscriber
+        const mappings = instance.subscribe(this)
+
+        if (!mappings) return
+
+        for (const [event, handler] of Object.entries(mappings)) {
+            const listener =
+                typeof handler === "string"
+                    ? (data: unknown) => (instance as unknown as Record<string, Listener>)[handler]?.(data)
+                    : (handler as Listener)
+            this.listen(event, listener)
+        }
+    }
+
+    async dispatch<T>(event: T | string, payload?: unknown): Promise<void> {
+        const [name, data] = this.parseEventAndPayload(event, payload)
+
+        for (const wl of [...this.wildcardListeners]) {
+            await wl(name, data)
+        }
+
+        const listeners = [...(this.listeners.get(name) ?? [])]
+        for (const listener of listeners) {
+            await listener(data)
+        }
+    }
+
+    fire<T>(event: T | string, payload?: unknown): Promise<void> {
+        return this.dispatch(event, payload)
+    }
+
+    async until<T>(event: T | string, payload?: unknown): Promise<unknown> {
+        const [name, data] = this.parseEventAndPayload(event, payload)
+
+        const listeners = [...(this.listeners.get(name) ?? [])]
+        for (const listener of listeners) {
+            const result = await listener(data)
+            if (result !== null && result !== false && result !== undefined) {
+                return result
+            }
+        }
+        return null
+    }
+
+    push(event: string, payload: Record<string, unknown> = {}): void {
+        const queued = this.pushedEvents.get(event) ?? []
+        queued.push(payload)
+        this.pushedEvents.set(event, queued)
+    }
+
+    async flush(event: string): Promise<void> {
+        const queued = [...(this.pushedEvents.get(event) ?? [])]
+        this.pushedEvents.delete(event)
+        for (const payload of queued) {
+            await this.dispatch(event, payload)
+        }
+    }
+
+    forget(event: EventIdentifier): void {
+        this.listeners.delete(this.resolveEventName(event))
+    }
+
+    forgetPushed(): void {
+        this.pushedEvents.clear()
+    }
+
+    hasListeners(event: EventIdentifier): boolean {
+        const name = this.resolveEventName(event)
+        return (this.listeners.get(name)?.length ?? 0) > 0 || this.wildcardListeners.length > 0
+    }
+
+    protected resolveEventName(event: unknown): string {
+        if (typeof event === "string") return event
+        if (typeof event === "function") {
+            // EventClass passed directly — prefer static label (minification-safe)
+            if ("label" in event && typeof event.label === "string") return event.label as string
+            return (event as EventClass).name
+        }
+        // Event instance — read label/name from its constructor
+        const ctor = (event as object)?.constructor
+        if (ctor && "label" in ctor && typeof (ctor as { label: unknown }).label === "string") {
+            return (ctor as { label: string }).label
+        }
+        return ctor?.name ?? ""
+    }
+
+    protected parseEventAndPayload<T>(event: T | string, payload?: unknown): [string, unknown] {
+        const name = this.resolveEventName(event)
+        const data = typeof event === "string" ? (payload ?? {}) : event
+        return [name, data]
+    }
+
+    protected normalizeListener<T>(listener: Listener<T> | ListenerObject<T>): Listener<T> {
+        if (typeof listener === "function") return listener
+        return (event: T) => listener.handle(event)
+    }
+}

package/src/events/concerns/dispatchable.ts

@@ -0,0 +1,10 @@
+import { Event } from "../../support/facades/event"
+
+export abstract class Dispatchable {
+    static dispatch<TThis extends new (...args: any[]) => Dispatchable>(
+        this: TThis,
+        ...args: ConstructorParameters<TThis>
+    ): Promise<void> {
+        return Event.dispatch(new this(...args)) as Promise<void>
+    }
+}

package/src/events/provider.ts

@@ -0,0 +1,9 @@
+import type { ServiceProviderContext } from "../support/service-provider"
+import ServiceProvider from "../support/service-provider"
+import { Bus } from "./bus"
+
+export class EventsProvider extends ServiceProvider {
+    register({ container }: ServiceProviderContext) {
+        container.singleton("events", (_c) => new Bus())
+    }
+}

package/src/events/types.ts

@@ -0,0 +1,9 @@
+export type EventClass<T = unknown> = new (...args: any[]) => T
+export type EventIdentifier<T = unknown> = string | EventClass<T>
+export type Listener<T = unknown> = (event: T) => void | boolean | Promise<void | boolean>
+export type WildcardListener = (eventName: string, data: unknown) => void | Promise<void>
+export type Unsubscribe = () => void
+
+export interface ListenerObject<T = unknown> {
+    handle(event: T): void | boolean | Promise<void | boolean>
+}

package/src/foundation/application.ts

@@ -0,0 +1,136 @@
+import { createConfig } from "../config/discovery"
+import { registerGlobalEnv } from "../config/env"
+import { ConfigProvider } from "../config/provider"
+import type ConfigRepository from "../config/repository"
+import type { ConfigItems } from "../config/repository"
+import type { ContainerContract, ContainerIdentifier } from "../container/contract"
+import {
+    type ContainerRuntimeOptions,
+    createRuntimeContainer,
+    mergeContainerRuntimeOptions,
+} from "../container/runtime"
+import { clearFacadeCache } from "../support/facades/facade"
+import type ServiceProvider from "../support/service-provider"
+import type { Cleanup, ServiceProviderContext } from "../support/service-provider"
+import { getCurrentApplicationContainer, setCurrentApplicationContainer } from "./current-application"
+
+type ApplicationRunContext = ServiceProviderContext & {
+    cleanupTasks: Cleanup[]
+}
+
+export type ApplicationConfigureOptions = {
+    basePath?: string
+    container?: ContainerRuntimeOptions
+    config?: ConfigItems
+}
+
+type ApplicationResolvedOptions = {
+    basePath: string
+    container: ReturnType<typeof mergeContainerRuntimeOptions>
+    config: ConfigItems
+}
+
+registerGlobalEnv()
+
+function mergeConfigureOptions(options: ApplicationConfigureOptions = {}): ApplicationResolvedOptions {
+    return {
+        basePath: options.basePath ?? "./",
+        container: mergeContainerRuntimeOptions(options.container),
+        config: options.config ?? {},
+    }
+}
+
+export class Application {
+    protected providers: ServiceProvider[]
+    protected options: ApplicationResolvedOptions
+
+    constructor(options: ApplicationResolvedOptions) {
+        this.options = options
+        this.providers = []
+    }
+
+    protected getConfigItems(): ConfigRepository {
+        return createConfig(this.options.basePath, this.options.config)
+    }
+
+    static clearConfigCache(_basePath?: string): void {}
+
+    static configure(basePath?: string): Application
+    static configure(options?: ApplicationConfigureOptions): Application
+    static configure(basePathOrOptions: string | ApplicationConfigureOptions = "./") {
+        if (typeof basePathOrOptions === "string") {
+            return new Application(mergeConfigureOptions({ basePath: basePathOrOptions }))
+        }
+
+        return new Application(mergeConfigureOptions(basePathOrOptions))
+    }
+
+    static make<T>(identifier: ContainerIdentifier<T>): T {
+        const container = getCurrentApplicationContainer()
+        if (!container) {
+            throw new Error("Application container is not available. Call run() first.")
+        }
+
+        return container.make<T>(identifier)
+    }
+
+    withProviders(providers: ServiceProvider[]) {
+        this.providers.push(...providers)
+        return this
+    }
+
+    protected createContainer(): ContainerContract {
+        return createRuntimeContainer(this.options.container)
+    }
+
+    protected rememberCleanup(cleanupTasks: Cleanup[], cleanup: void | Cleanup): void {
+        if (typeof cleanup === "function") {
+            cleanupTasks.push(cleanup)
+        }
+    }
+
+    protected createStopHandler(container: ContainerContract, cleanupTasks: Cleanup[]): Cleanup {
+        const stop: Cleanup = () => {
+            for (const cleanup of cleanupTasks.reverse()) {
+                cleanup()
+            }
+
+            clearFacadeCache()
+
+            container.flush()
+
+            if (getCurrentApplicationContainer() === container) {
+                setCurrentApplicationContainer(null)
+            }
+        }
+
+        return stop
+    }
+
+    run() {
+        const container = this.createContainer()
+
+        setCurrentApplicationContainer(container)
+        clearFacadeCache()
+
+        const providers = [new ConfigProvider(this.getConfigItems()), ...this.providers]
+        const context: ApplicationRunContext = { container, cleanupTasks: [] }
+
+        for (const provider of providers) {
+            this.rememberCleanup(context.cleanupTasks, provider.register(context))
+        }
+
+        for (const provider of providers) {
+            this.rememberCleanup(context.cleanupTasks, provider.boot(context))
+        }
+
+        const stop = this.createStopHandler(container, context.cleanupTasks)
+
+        window.addEventListener("beforeunload", stop, { once: true })
+
+        return {
+            container,
+            stop,
+        }
+    }
+}

package/src/foundation/current-application.ts

@@ -0,0 +1,20 @@
+import type { ContainerContract, ContainerIdentifier } from "../container/contract"
+
+let currentContainer: ContainerContract | null = null
+
+export function setCurrentApplicationContainer(container: ContainerContract | null): void {
+    currentContainer = container
+}
+
+export function getCurrentApplicationContainer(): ContainerContract | null {
+    return currentContainer
+}
+
+export function makeFromCurrentApplication<T>(identifier: ContainerIdentifier<T>): T {
+    const container = getCurrentApplicationContainer()
+    if (!container) {
+        throw new Error("Application container is not available. Call run() first.")
+    }
+
+    return container.make<T>(identifier)
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+/// <reference path="./config/env.global.d.ts" />
+
+export type { Contract as CacheStore } from "./cache/contract"
+export { default as CacheManager } from "./cache/manager"
+export { CacheProvider } from "./cache/provider"
+export { createConfig } from "./config/discovery"
+export { env } from "./config/env"
+export { ConfigProvider } from "./config/provider"
+export { default as ConfigRepository } from "./config/repository"
+export { default as BuiltinContainer, inject } from "./container/adapters/builtin"
+export type {
+    ContainerClass,
+    ContainerConcrete,
+    ContainerContract,
+    ContainerFactory,
+    ContainerIdentifier,
+} from "./container/contract"
+export type {
+    EventIdentifier,
+    EventSubscriber,
+    Listener,
+    ListenerObject,
+    Unsubscribe,
+    WildcardListener,
+} from "./events/bus"
+export { Bus } from "./events/bus"
+export { Dispatchable } from "./events/concerns/dispatchable"
+export { EventsProvider } from "./events/provider"
+export type { ApplicationConfigureOptions } from "./foundation/application"
+export { Application } from "./foundation/application"
+export type { Contract as LogContract } from "./log/contract"
+export { default as LogManager } from "./log/manager"
+export { LogProvider } from "./log/provider"
+export type { default as Contract, RendererContext, RootComponent } from "./renderers/contract"
+export type { Adapter as StoreAdapter } from "./store/adapters/contract"
+export { default as IndexedDbAdapter } from "./store/adapters/indexed-db"
+export { default as LocalStorageAdapter } from "./store/adapters/local-storage"
+export { default as MemoryStoreAdapter } from "./store/adapters/memory"
+export { default as StoreManager } from "./store/manager"
+export { StoreProvider } from "./store/provider"
+export { Arr } from "./support/arr"
+export { Collection } from "./support/collection"
+export { Fluent } from "./support/fluent"
+export { registerGlobalHelpers } from "./support/globals"
+export { LazyCollection } from "./support/lazy-collection"
+export { default as Manager } from "./support/manager"
+export { Num } from "./support/num"
+export { send } from "./support/pipeline"
+export type { Cleanup, ServiceProviderContext } from "./support/service-provider"
+export { DeferrableServiceProvider, default as ServiceProvider } from "./support/service-provider"
+export { Str } from "./support/str"
+
+import { CacheProvider } from "./cache/provider"
+import { LogProvider } from "./log/provider"
+import { StoreProvider } from "./store/provider"
+import type ServiceProvider from "./support/service-provider"
+
+export const defaultProviders: ServiceProvider[] = [new StoreProvider(), new CacheProvider(), new LogProvider()]

package/src/log/contract.ts

@@ -0,0 +1,21 @@
+export interface Contract {
+    /**
+     * Log a debug-level message for detailed diagnostic information.
+     */
+    debug(message: string, context?: Record<string, unknown>): void
+
+    /**
+     * Log an informational message about normal application flow.
+     */
+    info(message: string, context?: Record<string, unknown>): void
+
+    /**
+     * Log a warning about a recoverable or unexpected condition.
+     */
+    warn(message: string, context?: Record<string, unknown>): void
+
+    /**
+     * Log an error indicating a failure that requires attention.
+     */
+    error(message: string, context?: Record<string, unknown>): void
+}

package/src/log/drivers/console.ts

@@ -0,0 +1,54 @@
+import type { Contract } from "../contract"
+
+const LEVELS = ["debug", "info", "warn", "error"] as const
+type Level = (typeof LEVELS)[number]
+
+export default class ConsoleLogger implements Contract {
+    protected threshold: number
+
+    constructor(level: Level = "debug") {
+        this.threshold = LEVELS.indexOf(level)
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    debug(message: string, context?: Record<string, unknown>): void {
+        if (this.passes(0)) console.debug(message, ...this.spread(context))
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    info(message: string, context?: Record<string, unknown>): void {
+        if (this.passes(1)) console.info(message, ...this.spread(context))
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    warn(message: string, context?: Record<string, unknown>): void {
+        if (this.passes(2)) console.warn(message, ...this.spread(context))
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    error(message: string, context?: Record<string, unknown>): void {
+        if (this.passes(3)) console.error(message, ...this.spread(context))
+    }
+
+    /**
+     * Returns true if the given numeric level meets or exceeds the configured threshold.
+     */
+    protected passes(level: number): boolean {
+        return level >= this.threshold
+    }
+
+    /**
+     * Returns the context as a single-element array, or an empty array when absent.
+     */
+    protected spread(context?: Record<string, unknown>): unknown[] {
+        return context !== undefined ? [context] : []
+    }
+}

package/src/log/drivers/null.ts

@@ -0,0 +1,23 @@
+import type { Contract } from "../contract"
+
+export default class NullLogger implements Contract {
+    /**
+     * {@inheritDoc}
+     */
+    debug(_message: string, _context?: Record<string, unknown>): void {}
+
+    /**
+     * {@inheritDoc}
+     */
+    info(_message: string, _context?: Record<string, unknown>): void {}
+
+    /**
+     * {@inheritDoc}
+     */
+    warn(_message: string, _context?: Record<string, unknown>): void {}
+
+    /**
+     * {@inheritDoc}
+     */
+    error(_message: string, _context?: Record<string, unknown>): void {}
+}

package/src/log/drivers/stack.ts

@@ -0,0 +1,46 @@
+import type { Contract } from "../contract"
+
+export default class StackLogger implements Contract {
+    constructor(protected drivers: Contract[]) {}
+
+    /**
+     * {@inheritDoc}
+     */
+    debug(message: string, context?: Record<string, unknown>): void {
+        this.dispatch("debug", message, context)
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    info(message: string, context?: Record<string, unknown>): void {
+        this.dispatch("info", message, context)
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    warn(message: string, context?: Record<string, unknown>): void {
+        this.dispatch("warn", message, context)
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    error(message: string, context?: Record<string, unknown>): void {
+        this.dispatch("error", message, context)
+    }
+
+    /**
+     * Forwards the log call to each driver in order, swallowing any individual driver errors.
+     */
+    protected dispatch(level: keyof Contract, message: string, context?: Record<string, unknown>): void {
+        for (const driver of this.drivers) {
+            try {
+                driver[level](message, context)
+            } catch {
+                // swallow — a logging failure must not crash the application
+            }
+        }
+    }
+}

package/src/log/manager.ts

@@ -0,0 +1,76 @@
+import type ConfigRepository from "../config/repository"
+import Manager from "../support/manager"
+import type { Contract } from "./contract"
+import ConsoleLogger from "./drivers/console"
+import NullLogger from "./drivers/null"
+import StackLogger from "./drivers/stack"
+
+export default class LogManager extends Manager<Contract, Contract> implements Contract {
+    /**
+     * {@inheritDoc}
+     */
+    debug(message: string, context?: Record<string, unknown>): void {
+        this.resolve(this.active).debug(message, context)
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    info(message: string, context?: Record<string, unknown>): void {
+        this.resolve(this.active).info(message, context)
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    warn(message: string, context?: Record<string, unknown>): void {
+        this.resolve(this.active).warn(message, context)
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    error(message: string, context?: Record<string, unknown>): void {
+        this.resolve(this.active).error(message, context)
+    }
+
+    /**
+     * Returns the driver as-is; no wrapping is needed for log drivers.
+     */
+    protected createDriver(raw: Contract): Contract {
+        return raw
+    }
+
+    /**
+     * Returns the human-readable driver type label used in error messages.
+     */
+    protected driverType(): string {
+        return "Log driver"
+    }
+
+    /**
+     * Creates a LogManager from the application config, registering the built-in console, null, and stack drivers.
+     */
+    static fromConfig(config: ConfigRepository): LogManager {
+        const active = config.get<string>("logging.default", "console")
+        const manager = new LogManager({}, active, config)
+
+        manager.extend("console", (cfg) => {
+            const level = cfg.get<"debug" | "info" | "warn" | "error">("logging.drivers.console.level", "debug")
+            return new ConsoleLogger(level ?? "debug")
+        })
+
+        manager.extend("null", (_cfg) => new NullLogger())
+
+        manager.extend("stack", (cfg) => {
+            const names = cfg.get<string[]>("logging.drivers.stack.drivers", []) ?? []
+            return new StackLogger(names.map((name) => manager.resolve(name)))
+        })
+
+        // Manager constructor only accepts pre-built drivers for active validation;
+        // re-set after custom creators are registered so the configured name resolves correctly.
+        manager.active = active
+
+        return manager
+    }
+}

package/src/log/provider.ts

@@ -0,0 +1,11 @@
+import type ConfigRepository from "../config/repository"
+import type { ServiceProviderContext } from "../support/service-provider"
+import ServiceProvider from "../support/service-provider"
+import LogManager from "./manager"
+
+export class LogProvider extends ServiceProvider {
+    register({ container }: ServiceProviderContext): void {
+        container.singleton("log", (c) => LogManager.fromConfig(c.make<ConfigRepository>("config")))
+        container.singleton(LogManager, (c) => c.make<LogManager>("log"))
+    }
+}

package/src/react.ts

@@ -0,0 +1,2 @@
+export { default as Renderer } from "./renderers/adapters/react"
+export { ApplicationProvider, ContextProvider, useContainer, useService } from "./runtimes/react"