@raubjo/architect 0.5.1

package/package.json

@@ -0,0 +1,121 @@
+{
+    "name": "@raubjo/architect",
+    "version": "0.5.1",
+    "private": false,
+    "license": "MIT",
+    "type": "module",
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "test": "bun test",
+        "test:coverage": "bun test --coverage --coverage-reporter=lcov --coverage-dir=coverage && node scripts/lcov-to-istanbul.js",
+        "fallow": "npm run test:coverage && npx fallow health --coverage coverage/coverage-final.json",
+        "fix": "biome check --fix ./src/**/* && fallow fix",
+        "sandcastle": "bun .sandcastle/main.ts",
+        "version:major": "npm verison major",
+        "version:minor": "npm verison minor",
+        "version:patch": "npm verison patch",
+        "release": "npm publish",
+        "prepare": "bun husky"
+    },
+    "exports": {
+        ".": "./src/index.ts",
+        "./react": "./src/react.ts",
+        "./solid": "./src/solid.ts",
+        "./svelte": "./src/svelte.ts",
+        "./vue": "./src/vue.ts",
+        "./application": "./src/foundation/application.ts",
+        "./container/contract": "./src/container/contract.ts",
+        "./container/adapters/builtin": "./src/container/adapters/builtin.ts",
+        "./config/env": "./src/config/env.ts",
+        "./config/repository": "./src/config/repository.ts",
+        "./cache/manager": "./src/cache/manager.ts",
+        "./cache/cache": "./src/cache/cache.ts",
+        "./cache/provider": "./src/cache/provider.ts",
+        "./facades/cache": "./src/support/facades/cache.ts",
+        "./facades/event": "./src/support/facades/event.ts",
+        "./facades/log": "./src/support/facades/log.ts",
+        "./log/contract": "./src/log/contract.ts",
+        "./log/manager": "./src/log/manager.ts",
+        "./log/provider": "./src/log/provider.ts",
+        "./log/drivers/console": "./src/log/drivers/console.ts",
+        "./log/drivers/null": "./src/log/drivers/null.ts",
+        "./log/drivers/stack": "./src/log/drivers/stack.ts",
+        "./config/provider": "./src/config/provider.ts",
+        "./events/bus": "./src/events/bus.ts",
+        "./events/concerns/dispatchable": "./src/events/concerns/dispatchable.ts",
+        "./events/provider": "./src/events/provider.ts",
+        "./store/manager": "./src/store/manager.ts",
+        "./store/adapters/contract": "./src/store/adapters/contract.ts",
+        "./store/store": "./src/store/store.ts",
+        "./store/adapters/memory": "./src/store/adapters/memory.ts",
+        "./store/adapters/local-storage": "./src/store/adapters/local-storage.ts",
+        "./store/adapters/indexed-db": "./src/store/adapters/indexed-db.ts",
+        "./store/provider": "./src/store/provider.ts",
+        "./facades/store": "./src/support/facades/store.ts",
+        "./filesystem/filesystem": "./src/filesystem/filesystem.ts",
+        "./filesystem/local-adapter": "./src/filesystem/adapters/local.ts",
+        "./renderers/contract": "./src/renderers/contract.ts",
+        "./renderers/react": "./src/renderers/adapters/react.tsx",
+        "./renderers/solid": "./src/renderers/adapters/solid.tsx",
+        "./renderers/svelte": "./src/renderers/adapters/svelte.ts",
+        "./renderers/vue": "./src/renderers/adapters/vue.ts",
+        "./support/facades": "./src/support/facades/index.ts",
+        "./facades/config": "./src/support/facades/config.ts",
+        "./runtimes/react": "./src/runtimes/react.tsx",
+        "./runtimes/solid": "./src/runtimes/solid.tsx",
+        "./runtimes/svelte": "./src/runtimes/svelte.ts",
+        "./runtimes/vue": "./src/runtimes/vue.ts",
+        "./str": "./src/support/str.ts",
+        "./arr": "./src/support/arr.ts",
+        "./collection": "./src/support/collection.ts",
+        "./lazy-collection": "./src/support/lazy-collection.ts",
+        "./fluent": "./src/support/fluent.ts",
+        "./num": "./src/support/num.ts",
+        "./pipeline": "./src/support/pipeline.ts",
+        "./service-provider": "./src/support/service-provider.ts",
+        "./manager": "./src/support/manager.ts",
+        "./facade": "./src/support/facades/facade.ts"
+    },
+    "peerDependencies": {
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0",
+        "reflect-metadata": "^0.2.2",
+        "solid-js": "^1.9.0",
+        "svelte": "",
+        "vue": "^3.0.0"
+    },
+    "peerDependenciesMeta": {
+        "react": {
+            "optional": true
+        },
+        "react-dom": {
+            "optional": true
+        },
+        "solid-js": {
+            "optional": true
+        },
+        "svelte": {
+            "optional": true
+        },
+        "vue": {
+            "optional": true
+        },
+        "reflect-metadata": {
+            "optional": false
+        }
+    },
+    "devDependencies": {
+        "@types/react": "^19.2.14",
+        "@types/react-dom": "^19.2.3",
+        "bun-types": "^1.3.13",
+        "fallow": "^2.67.0",
+        "husky": "^9.1.7",
+        "solid-js": "^1.9.12",
+        "vue": "^3.5.34"
+    },
+    "trustedDependencies": [
+        "@fallow-cli/fallow-cov"
+    ]
+}

package/src/cache/cache.ts

@@ -0,0 +1,46 @@
+import type { Adapter } from "../store/adapters/contract"
+import type { Contract } from "./contract"
+
+type Envelope<T> = { v: T; e: number | null }
+
+export class Cache implements Contract {
+    constructor(protected readonly adapter: Adapter) {}
+
+    async get(key: string): Promise<unknown>
+    async get<T>(key: string): Promise<T | null>
+    async get<T = unknown>(key: string): Promise<T | null> {
+        const raw = await this.adapter.get<Envelope<T>>(key)
+        if (raw === null) return null
+        if (raw.e !== null && Date.now() >= raw.e) return null
+        return raw.v
+    }
+
+    async set<T = unknown>(key: string, value: T, ttl?: number | null): Promise<void> {
+        const e = typeof ttl === "number" ? Date.now() + ttl * 1000 : null
+        return this.adapter.set<Envelope<T>>(key, { v: value, e })
+    }
+
+    async has(key: string): Promise<boolean> {
+        return (await this.get(key)) !== null
+    }
+
+    async delete(key: string): Promise<void> {
+        return this.adapter.delete(key)
+    }
+
+    async clear(): Promise<void> {
+        return this.adapter.clear()
+    }
+
+    async keys(): Promise<string[]> {
+        const allKeys = await this.adapter.keys()
+        const now = Date.now()
+        const results = await Promise.all(
+            allKeys.map(async (k) => {
+                const raw = await this.adapter.get<Envelope<unknown>>(k)
+                return raw !== null && (raw.e === null || now < raw.e) ? k : null
+            }),
+        )
+        return results.filter((k): k is string => k !== null)
+    }
+}

package/src/cache/contract.ts

@@ -0,0 +1,9 @@
+export interface Contract {
+    get(key: string): Promise<unknown>
+    get<T>(key: string): Promise<T | null>
+    set<T = unknown>(key: string, value: T, ttl?: number | null): Promise<void>
+    has(key: string): Promise<boolean>
+    delete(key: string): Promise<void>
+    clear(): Promise<void>
+    keys(): Promise<string[]>
+}

package/src/cache/manager.ts

@@ -0,0 +1,110 @@
+import type ConfigRepository from "../config/repository"
+import type { Adapter } from "../store/adapters/contract"
+import IndexedDbAdapter from "../store/adapters/indexed-db"
+import LocalStorageAdapter from "../store/adapters/local-storage"
+import MemoryStoreAdapter from "../store/adapters/memory"
+import Manager from "../support/manager"
+import { Cache } from "./cache"
+import type { Contract } from "./contract"
+
+type StoreConfig = {
+    driver?: string
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+export default class CacheManager extends Manager<Contract, Adapter> implements Adapter {
+    protected createDriver(raw: Adapter): Contract {
+        return new Cache(raw)
+    }
+
+    protected defaultDriverName(): string {
+        return "memory" in this.drivers ? "memory" : super.defaultDriverName()
+    }
+
+    protected driverType(): string {
+        return "Cache store"
+    }
+
+    static fromConfig(config: ConfigRepository): CacheManager {
+        const stores = CacheManager.storesFromConfig(config)
+        const active = config.get<string>("cache.default", "memory")
+
+        return new CacheManager(stores, active, config)
+    }
+
+    protected static storesFromConfig(config: ConfigRepository): Record<string, Contract> {
+        const baseDrivers = CacheManager.defaultDrivers()
+        const configured = config.get<Record<string, unknown>>("cache.stores", {}) ?? {}
+        if (hasNoConfiguredStores(configured)) {
+            return baseDrivers
+        }
+
+        return Object.fromEntries(
+            Object.entries(configured).map(([name, storeConfig]) => {
+                const driver = resolveDriver(storeConfig, name)
+                return [name, baseDrivers[driver] ?? baseDrivers.memory]
+            }),
+        )
+    }
+
+    protected static defaultDrivers(): Record<string, Contract> {
+        const hasWindow = typeof window !== "undefined"
+        const hasLocal = hasWindow && typeof window.localStorage !== "undefined"
+        const hasIndexed = typeof globalThis.indexedDB !== "undefined"
+
+        const rawMemory = new MemoryStoreAdapter()
+        const memory = new Cache(rawMemory)
+
+        return {
+            memory,
+            local: new Cache(hasLocal ? new LocalStorageAdapter(window.localStorage) : rawMemory),
+            indexed: new Cache(hasIndexed ? new IndexedDbAdapter() : rawMemory),
+        }
+    }
+
+    store(name?: string): Contract {
+        return this.resolve(name ?? this.active)
+    }
+
+    get(key: string): Promise<unknown>
+    get<T>(key: string): Promise<T | null>
+    get<T = unknown>(key: string): Promise<T | null> {
+        return this.store().get<T>(key)
+    }
+
+    set<T = unknown>(key: string, value: T, ttl?: number | null): Promise<void> {
+        return this.store().set<T>(key, value, ttl)
+    }
+
+    has(key: string): Promise<boolean> {
+        return this.store().has(key)
+    }
+
+    delete(key: string): Promise<void> {
+        return this.store().delete(key)
+    }
+
+    clear(): Promise<void> {
+        return this.store().clear()
+    }
+
+    keys(): Promise<string[]> {
+        return this.store().keys()
+    }
+}
+
+function hasNoConfiguredStores(value: unknown): boolean {
+    return !isRecord(value) || Object.keys(value).length === 0
+}
+
+function resolveDriver(value: unknown, fallback: string): string {
+    if (!isRecord(value)) {
+        return fallback
+    }
+
+    const storeConfig = value as StoreConfig
+    return typeof storeConfig.driver === "string" ? storeConfig.driver : fallback
+}

package/src/cache/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 CacheManager from "./manager"
+
+export class CacheProvider extends ServiceProvider {
+    register({ container }: ServiceProviderContext) {
+        container.singleton("cache", (c) => CacheManager.fromConfig(c.make<ConfigRepository>("config")))
+        container.singleton(CacheManager, (c) => c.make<CacheManager>("cache"))
+    }
+}

package/src/config/contract.ts

@@ -0,0 +1,63 @@
+/**
+ * Configuration contract defining the interface for configuration management
+ */
+export interface Contract {
+    /**
+     * Determine if a configuration key exists
+     */
+    has(key: string | string[]): boolean
+
+    /**
+     * Get a configuration value by key
+     */
+    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 multiple configuration values
+     */
+    getMany(keys: string[] | Record<string, unknown>): Record<string, unknown>
+
+    /**
+     * Set a configuration value
+     */
+    set(key: string | Record<string, unknown>, value?: unknown): void
+
+    /**
+     * Prepend a value to an array configuration
+     */
+    prepend(key: string, value: unknown): void
+
+    /**
+     * Append a value to an array configuration
+     */
+    push(key: string, value: unknown): void
+
+    /**
+     * Get all configuration items
+     */
+    all(): Record<string, unknown>
+
+    /**
+     * Check if a configuration key exists (offset-style)
+     */
+    offsetExists(key: string): boolean
+
+    /**
+     * Get a configuration value by offset (offset-style)
+     */
+    offsetGet(key: string): unknown
+    offsetGet<T>(key: string): T | null
+
+    /**
+     * Set a configuration value by offset (offset-style)
+     */
+    offsetSet(key: string, value: unknown): void
+
+    /**
+     * Remove a configuration key (offset-style)
+     */
+    offsetUnset(key: string): void
+}

package/src/config/discovery.ts

@@ -0,0 +1,99 @@
+import type { ConfigItems } from "./repository"
+import ConfigRepository from "./repository"
+
+type GlobLoader = (pattern: string | string[], options?: { eager?: boolean }) => Record<string, unknown>
+
+type ConfigModule = { default?: unknown }
+
+export interface ConfigLoader {
+    load(basePath: string, staticItems?: ConfigItems): ConfigItems
+}
+
+function fileNameWithoutExtension(path: string): string {
+    const file = path.split("/").pop() ?? path
+    return file.replace(/\.[^/.]+$/, "")
+}
+
+function loadConfigFromModules(modules: Record<string, unknown>): ConfigItems {
+    const discovered: ConfigItems = {}
+
+    for (const [path, loaded] of Object.entries(modules)) {
+        const key = fileNameWithoutExtension(path)
+        const value = readConfigModuleDefault(loaded)
+        if (key !== "index" && value !== undefined) {
+            discovered[key] = value
+        }
+    }
+
+    return discovered
+}
+
+function readConfigModuleDefault(loaded: unknown): unknown {
+    const module = loaded as ConfigModule
+    return module && "default" in module ? module.default : undefined
+}
+
+function cloneItems(items: ConfigItems): ConfigItems {
+    if (typeof structuredClone === "function") {
+        return structuredClone(items) as ConfigItems
+    }
+    return JSON.parse(JSON.stringify(items)) as ConfigItems
+}
+
+function loadEsmConfigModules(basePath: string): Record<string, unknown> {
+    const glob = resolveConfigGlob()
+    if (!glob) {
+        return {}
+    }
+
+    const modules = glob(configPatternForBasePath(basePath), { eager: true })
+    return modules as Record<string, unknown>
+}
+
+function resolveConfigGlob(): GlobLoader | null {
+    const testGlob = (
+        globalThis as {
+            __iocConfigGlobForTests?: GlobLoader
+        }
+    ).__iocConfigGlobForTests
+
+    const viteGlob = (
+        import.meta as ImportMeta & {
+            glob?: GlobLoader
+        }
+    ).glob
+
+    return typeof testGlob === "function" ? testGlob : typeof viteGlob === "function" ? viteGlob : null
+}
+
+function configPatternForBasePath(basePath: string): string {
+    return basePath.endsWith("/") ? `${basePath}config/**/*.ts` : `${basePath}/config/**/*.ts`
+}
+
+export class EsmConfigLoader implements ConfigLoader {
+    load(basePath: string, staticItems: ConfigItems = {}): ConfigItems {
+        const shouldLoadEsm = Object.keys(staticItems).length === 0
+
+        const esmItems = shouldLoadEsm ? loadConfigFromModules(loadEsmConfigModules(basePath)) : {}
+
+        return { ...esmItems, ...cloneItems(staticItems) }
+    }
+}
+
+function createConfigRepository(
+    basePath: string,
+    staticItems: ConfigItems = {},
+    loader?: ConfigLoader,
+): ConfigRepository {
+    const configLoader = loader ?? new EsmConfigLoader()
+    const items = configLoader.load(basePath, staticItems)
+    return new ConfigRepository(items)
+}
+
+export const ConfigFactory = {
+    create: createConfigRepository,
+}
+
+export function createConfig(basePath: string, staticItems: ConfigItems = {}): ConfigRepository {
+    return ConfigFactory.create(basePath, staticItems)
+}

package/src/config/env.global.d.ts

@@ -0,0 +1,6 @@
+declare global {
+    function env(key: string): import("./env").EnvValue | undefined
+    function env<T>(key: string, defaultValue: T): import("./env").EnvValue | T
+}
+
+export {}

package/src/config/env.ts

@@ -0,0 +1,68 @@
+export type EnvValue = string | number | boolean | null
+type EnvMap = Record<string, EnvValue | undefined>
+const normalizedEnvValues: Record<string, EnvValue> = {
+    "(empty)": "",
+    "(false)": false,
+    "(null)": null,
+    "(true)": true,
+    empty: "",
+    false: false,
+    null: null,
+    true: true,
+}
+
+function normalizeEnvValue(value: EnvValue | undefined): EnvValue | undefined {
+    if (typeof value !== "string") {
+        return value
+    }
+
+    const normalized = value.trim().toLowerCase()
+    return normalized in normalizedEnvValues ? normalizedEnvValues[normalized] : value
+}
+
+function resolveProcessEnv(): EnvMap {
+    const processValue = (globalThis as { process?: { env?: EnvMap } }).process
+
+    if (!processValue?.env) {
+        return {}
+    }
+
+    return processValue.env
+}
+
+function resolveImportMetaEnv(): EnvMap {
+    const testEnv = (
+        globalThis as {
+            __iocImportMetaEnvForTests?: EnvMap
+        }
+    ).__iocImportMetaEnvForTests
+    if (testEnv) {
+        return testEnv
+    }
+
+    const meta = import.meta as ImportMeta & { env?: EnvMap }
+    return meta.env ?? {}
+}
+
+export function env(key: string): EnvValue | undefined
+export function env<T>(key: string, defaultValue: T): EnvValue | T
+export function env<T>(key: string, defaultValue?: T): EnvValue | T | undefined {
+    const importMetaEnv = resolveImportMetaEnv()
+    if (key in importMetaEnv) {
+        return normalizeEnvValue(importMetaEnv[key])
+    }
+
+    const processEnv = resolveProcessEnv()
+    if (key in processEnv) {
+        return normalizeEnvValue(processEnv[key])
+    }
+
+    return defaultValue
+}
+
+export function registerGlobalEnv(): void {
+    const globalScope = globalThis as { env?: typeof env }
+    if (typeof globalScope.env !== "function") {
+        globalScope.env = env
+    }
+}

package/src/config/index.ts

@@ -0,0 +1,5 @@
+export type { Contract as ConfigContract } from "./contract"
+export { createConfig } from "./discovery"
+export { env, registerGlobalEnv } from "./env"
+export type { ConfigItems } from "./repository"
+export { ConfigRepository } from "./repository"

package/src/config/provider.ts

@@ -0,0 +1,17 @@
+import type { ServiceProviderContext } from "../support/service-provider"
+import ServiceProvider from "../support/service-provider"
+import ConfigRepository from "./repository"
+
+export class ConfigProvider extends ServiceProvider {
+    protected readonly repository: ConfigRepository
+
+    constructor(repository: ConfigRepository) {
+        super()
+        this.repository = repository
+    }
+
+    register({ container }: ServiceProviderContext) {
+        container.instance("config", this.repository)
+        container.instance(ConfigRepository, this.repository)
+    }
+}