@raubjo/architect-core 0.1.0

package/src/support/facades/cache.ts

@@ -0,0 +1,46 @@
+import type CacheManager from "../../cache/manager";
+import type { CacheStore } from "../../cache/cache";
+import Facade from "./facade";
+
+export default class Cache extends Facade {
+  private constructor() {
+    super();
+  }
+
+  protected static getFacadeAccessor(): string {
+    return "cache";
+  }
+
+  static store(name?: string): CacheStore {
+    return this.resolveFacadeInstance<CacheManager>().store(name);
+  }
+
+  static use(name: string): Cache {
+    this.resolveFacadeInstance<CacheManager>().use(name);
+    return this;
+  }
+
+  static get<T = unknown>(key: string): Promise<T | null> {
+    return this.resolveFacadeInstance<CacheManager>().get<T>(key);
+  }
+
+  static set<T = unknown>(key: string, value: T): Promise<void> {
+    return this.resolveFacadeInstance<CacheManager>().set<T>(key, value);
+  }
+
+  static has(key: string): Promise<boolean> {
+    return this.resolveFacadeInstance<CacheManager>().has(key);
+  }
+
+  static delete(key: string): Promise<void> {
+    return this.resolveFacadeInstance<CacheManager>().delete(key);
+  }
+
+  static clear(): Promise<void> {
+    return this.resolveFacadeInstance<CacheManager>().clear();
+  }
+
+  static keys(): Promise<string[]> {
+    return this.resolveFacadeInstance<CacheManager>().keys();
+  }
+}

package/src/support/facades/config.ts

@@ -0,0 +1,67 @@
+import type ConfigRepository from "../../config/repository";
+import type { ConfigDefaults, ConfigItems } from "../../config/repository";
+import Facade from "./facade";
+
+export default class Config extends Facade {
+  private constructor() {
+    super();
+  }
+
+  protected static getFacadeAccessor(): string {
+    return "config";
+  }
+
+  static has(key: string | string[]): boolean {
+    return this.resolveFacadeInstance<ConfigRepository>().has(key);
+  }
+
+  static get<T = unknown>(
+    key: string | string[],
+    defaultValue: T | (() => T) | null = null,
+  ): T | Record<string, unknown> | null {
+    return this.resolveFacadeInstance<ConfigRepository>().get<T>(key, defaultValue);
+  }
+
+  static getMany(keys: string[] | ConfigDefaults): Record<string, unknown> {
+    return this.resolveFacadeInstance<ConfigRepository>().getMany(keys);
+  }
+
+  static string(key: string, defaultValue: string | (() => string) | null = null): string {
+    return this.resolveFacadeInstance<ConfigRepository>().string(key, defaultValue);
+  }
+
+  static integer(key: string, defaultValue: number | (() => number) | null = null): number {
+    return this.resolveFacadeInstance<ConfigRepository>().integer(key, defaultValue);
+  }
+
+  static float(key: string, defaultValue: number | (() => number) | null = null): number {
+    return this.resolveFacadeInstance<ConfigRepository>().float(key, defaultValue);
+  }
+
+  static boolean(
+    key: string,
+    defaultValue: boolean | (() => boolean) | null = null,
+  ): boolean {
+    return this.resolveFacadeInstance<ConfigRepository>().boolean(key, defaultValue);
+  }
+
+  static array<T = unknown>(key: string, defaultValue: T[] | (() => T[]) | null = null): T[] {
+    return this.resolveFacadeInstance<ConfigRepository>().array<T>(key, defaultValue);
+  }
+
+  static set(key: string | ConfigItems, value: unknown = null): void {
+    this.resolveFacadeInstance<ConfigRepository>().set(key, value);
+  }
+
+  static prepend(key: string, value: unknown): void {
+    this.resolveFacadeInstance<ConfigRepository>().prepend(key, value);
+  }
+
+  static push(key: string, value: unknown): void {
+    this.resolveFacadeInstance<ConfigRepository>().push(key, value);
+  }
+
+  static all(): ConfigItems {
+    return this.resolveFacadeInstance<ConfigRepository>().all();
+  }
+}

package/src/support/facades/facade.ts

@@ -0,0 +1,42 @@
+import { Application } from "../../foundation/application";
+
+export default abstract class Facade {
+  protected static resolvedInstance = new Map<Parameters<typeof Application.make>[0], unknown>();
+
+  protected constructor() {}
+
+  protected static getFacadeAccessor(): Parameters<typeof Application.make>[0] {
+    throw new Error("Facade does not implement getFacadeAccessor().");
+  }
+
+  static clearResolvedInstance(name: Parameters<typeof Application.make>[0]): void {
+    this.resolvedInstance.delete(name);
+  }
+
+  static clearResolvedInstances(): void {
+    this.resolvedInstance.clear();
+  }
+
+  protected static resolveFacadeInstance<T>(): T {
+    const accessor = this.getFacadeAccessor();
+
+    if (this.resolvedInstance.has(accessor)) {
+      return this.resolvedInstance.get(accessor) as T;
+    }
+
+    const instance = Application.make<T>(accessor);
+    this.resolvedInstance.set(accessor, instance);
+
+    return instance;
+  }
+
+  protected static callFacadeMethod<T = unknown>(method: string, ...args: unknown[]): T {
+    const instance = this.resolveFacadeInstance<Record<string, (...a: unknown[]) => unknown>>();
+    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 T;
+  }
+}

package/src/support/facades/storage.ts

@@ -0,0 +1,46 @@
+import type StorageManager from "../../storage/manager";
+import type { StorageAdapter } from "../../storage/storage";
+import Facade from "./facade";
+
+export default class Storage extends Facade {
+  private constructor() {
+    super();
+  }
+
+  protected static getFacadeAccessor(): string {
+    return "storage";
+  }
+
+  static drv(name?: string): StorageAdapter {
+    return this.resolveFacadeInstance<StorageManager>().drv(name);
+  }
+
+  static use(name: string): Storage {
+    this.resolveFacadeInstance<StorageManager>().use(name);
+    return this;
+  }
+
+  static get<T = unknown>(key: string): Promise<T | null> {
+    return this.resolveFacadeInstance<StorageManager>().get<T>(key);
+  }
+
+  static set<T = unknown>(key: string, value: T): Promise<void> {
+    return this.resolveFacadeInstance<StorageManager>().set<T>(key, value);
+  }
+
+  static has(key: string): Promise<boolean> {
+    return this.resolveFacadeInstance<StorageManager>().has(key);
+  }
+
+  static delete(key: string): Promise<void> {
+    return this.resolveFacadeInstance<StorageManager>().delete(key);
+  }
+
+  static clear(): Promise<void> {
+    return this.resolveFacadeInstance<StorageManager>().clear();
+  }
+
+  static keys(): Promise<string[]> {
+    return this.resolveFacadeInstance<StorageManager>().keys();
+  }
+}

package/src/support/providers/config-service-provider.ts

@@ -0,0 +1,19 @@
+import appConfig from "../../config/app";
+import ConfigRepository, { type ConfigItems } from "../../config/repository";
+import ServiceProvider, { type ServiceProviderContext } from "../service-provider";
+
+export default class ConfigServiceProvider extends ServiceProvider {
+  protected items: ConfigItems;
+
+  constructor(items: ConfigItems = { app: appConfig }) {
+    super();
+    this.items = items;
+  }
+
+  register({ container }: ServiceProviderContext): void {
+    const repository = new ConfigRepository(this.items);
+
+    container.bind("config").toConstantValue(repository);
+    container.bind(ConfigRepository).toConstantValue(repository);
+  }
+}

package/src/support/service-provider.ts

@@ -0,0 +1,25 @@
+import type { Container } from "inversify";
+
+export type Cleanup = () => void;
+
+export type ServiceProviderContext = {
+  container: Container;
+};
+
+export default class ServiceProvider {
+  constructor() {}
+
+  register(_context: ServiceProviderContext): void | Cleanup {}
+
+  boot(_context: ServiceProviderContext): void | Cleanup {}
+}
+
+export class DeferrableServiceProvider extends ServiceProvider {
+  constructor() {
+    super();
+  }
+
+  provides(): Array<string> {
+    return [];
+  }
+}

package/src/support/str.ts

@@ -0,0 +1,126 @@
+function splitWords(value: string): string[] {
+  const normalized = value
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[_\-.]+/g, " ")
+    .trim();
+
+  if (!normalized) {
+    return [];
+  }
+
+  return normalized.split(/\s+/);
+}
+
+function normalizeForSlug(value: string): string {
+  return value
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export default class Str {
+  constructor() {}
+
+  static lower(value: string): string {
+    return value.toLowerCase();
+  }
+
+  static upper(value: string): string {
+    return value.toUpperCase();
+  }
+
+  static length(value: string): number {
+    return value.length;
+  }
+
+  static contains(haystack: string, needle: string | string[], ignoreCase = false): boolean {
+    const source = ignoreCase ? haystack.toLowerCase() : haystack;
+    const needles = Array.isArray(needle) ? needle : [needle];
+
+    for (const part of needles) {
+      const target = ignoreCase ? part.toLowerCase() : part;
+      if (source.includes(target)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  static startsWith(haystack: string, needle: string | string[]): boolean {
+    const needles = Array.isArray(needle) ? needle : [needle];
+    for (const part of needles) {
+      if (haystack.startsWith(part)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  static endsWith(haystack: string, needle: string | string[]): boolean {
+    const needles = Array.isArray(needle) ? needle : [needle];
+    for (const part of needles) {
+      if (haystack.endsWith(part)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  static replace(search: string | RegExp, replace: string, subject: string): string {
+    return subject.replace(search, replace);
+  }
+
+  static snake(value: string, separator = "_"): string {
+    const words = splitWords(value).map((word) => word.toLowerCase());
+    return words.join(separator);
+  }
+
+  static kebab(value: string): string {
+    return Str.snake(value, "-");
+  }
+
+  static studly(value: string): string {
+    const words = splitWords(value);
+    let output = "";
+    for (const word of words) {
+      output += word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+    }
+
+    return output;
+  }
+
+  static camel(value: string): string {
+    const studly = Str.studly(value);
+    if (!studly) {
+      return "";
+    }
+
+    return studly.charAt(0).toLowerCase() + studly.slice(1);
+  }
+
+  static slug(value: string, separator = "-"): string {
+    const slugged = normalizeForSlug(value);
+    if (separator === "-") {
+      return slugged;
+    }
+
+    return slugged.replace(/-/g, separator);
+  }
+}
+
+export function registerGlobalStr(): void {
+  const globalScope = globalThis as { Str?: typeof Str };
+  if (typeof globalScope.Str === "undefined") {
+    globalScope.Str = Str;
+  }
+}
+
+export const __strTesting = {
+  normalizeForSlug,
+  splitWords,
+};

package/tests/application.test.ts

@@ -0,0 +1,236 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import ReactDOM from "react-dom/client";
+import ConfigRepository from "../src/config/repository";
+import { __applicationTesting, Application } from "../src/foundation/application";
+import ServiceProvider from "../src/support/service-provider";
+
+describe("Application", () => {
+  afterEach(() => {
+    (globalThis as { window?: unknown; document?: unknown }).window = undefined;
+    (globalThis as { window?: unknown; document?: unknown }).document = undefined;
+    (
+      globalThis as { __iocConfigGlobForTests?: unknown }
+    ).__iocConfigGlobForTests = undefined;
+    Application.clearConfigCache();
+  });
+
+  test("make throws when container is not initialized", () => {
+    expect(() => Application.make("config")).toThrow(
+      "Application container is not available. Call run() first.",
+    );
+  });
+
+  test("run with custom renderer executes lifecycle and cleanup in reverse order", () => {
+    const calls: string[] = [];
+    let beforeUnload: (() => void) | undefined;
+
+    (globalThis as { window: { addEventListener: (event: string, cb: () => void) => void } })
+      .window = {
+      addEventListener: (_event, cb) => {
+        beforeUnload = cb;
+      },
+    };
+
+    class DemoProvider extends ServiceProvider {
+      register({ container }: { container: { bind: (id: string) => { toConstantValue: (v: unknown) => void } } }) {
+        calls.push("provider.register");
+        container.bind("demo").toConstantValue("value");
+        return () => calls.push("provider.register.cleanup");
+      }
+
+      boot() {
+        calls.push("provider.boot");
+        return () => calls.push("provider.boot.cleanup");
+      }
+    }
+
+    const app = Application.configure("./")
+      .withProviders([new DemoProvider()])
+      .withServices(({ container }) => {
+        calls.push("services");
+        container.bind("services.value").toConstantValue(1);
+        return () => calls.push("services.cleanup");
+      })
+      .withStartup(() => {
+        calls.push("startup");
+        return () => calls.push("startup.cleanup");
+      })
+      .withRoot(() => null)
+      .withRenderer({
+        render: () => {
+          calls.push("renderer");
+          return () => calls.push("renderer.cleanup");
+        },
+      });
+
+    const running = app.run();
+    expect(Application.make("demo")).toBe("value");
+    expect(Application.make("storage")).toBeTruthy();
+    expect(Application.make("cache")).toBeTruthy();
+    expect(running.container.get("services.value")).toBe(1);
+    expect(calls).toEqual([
+      "provider.register",
+      "services",
+      "provider.boot",
+      "startup",
+      "renderer",
+    ]);
+
+    expect(typeof beforeUnload).toBe("function");
+    beforeUnload?.();
+
+    expect(calls).toEqual([
+      "provider.register",
+      "services",
+      "provider.boot",
+      "startup",
+      "renderer",
+      "renderer.cleanup",
+      "startup.cleanup",
+      "provider.boot.cleanup",
+      "services.cleanup",
+      "provider.register.cleanup",
+    ]);
+
+    expect(() => Application.make("demo")).toThrow(
+      "Application container is not available. Call run() first.",
+    );
+  });
+
+  test("exposes helper behavior used for config discovery", () => {
+    expect(__applicationTesting.fileNameWithoutExtension("/src/config/app.ts")).toBe("app");
+    expect(__applicationTesting.normalizeBasePath("./")).toBe("");
+    expect(__applicationTesting.normalizeBasePath("./src")).toBe("src");
+    expect(__applicationTesting.isPathInConfigDirectories("/src/config/app.ts", "./")).toBe(
+      true,
+    );
+    expect(
+      __applicationTesting.isPathInConfigDirectories(
+        "/workspace/src/config/app.ts",
+        "/workspace",
+      ),
+    ).toBe(true);
+  });
+
+  test("loads config modules through glob loader and caches by basePath", () => {
+    (
+      globalThis as {
+        __iocConfigGlobForTests?: (
+          pattern: string | string[],
+          options?: { eager?: boolean },
+        ) => Record<string, unknown>;
+      }
+    ).__iocConfigGlobForTests = () => ({
+      "/src/config/app.ts": { default: { name: "From App Config" } },
+      "/src/config/cache.ts": { default: { store: "memory" } },
+      "/other/path/ignored.ts": { default: { nope: true } },
+    });
+
+    (globalThis as { window: { addEventListener: (event: string, cb: () => void) => void } })
+      .window = {
+      addEventListener: () => {},
+    };
+
+    const first = Application.configure("./src").run();
+    const second = Application.configure("./src").run();
+
+    const firstConfig = first.container.get(ConfigRepository);
+    const secondConfig = second.container.get(ConfigRepository);
+
+    expect(firstConfig.get("app")).toEqual({ name: "From App Config" });
+    expect(firstConfig.get("cache")).toEqual({ store: "memory" });
+    expect(firstConfig.get("ignored")).toBeNull();
+    expect(firstConfig.all()).toEqual(secondConfig.all());
+    expect(firstConfig.all()).not.toBe(secondConfig.all());
+
+    // Cached source config should be cloned into each app instance.
+    firstConfig.set("cache.store", "updated");
+    expect(secondConfig.get("cache.store")).toBe("memory");
+
+    first.stop();
+    second.stop();
+  });
+
+  test("renderer requires root component", () => {
+    (globalThis as { window: { addEventListener: (event: string, cb: () => void) => void } })
+      .window = {
+      addEventListener: () => {},
+    };
+
+    const app = Application.configure("./").withRenderer({ render: () => () => {} });
+
+    expect(() => app.run()).toThrow(
+      "Root component is required when using a custom renderer.",
+    );
+  });
+
+  test("default react renderer throws if mount node is missing", () => {
+    (globalThis as { window: { addEventListener: (event: string, cb: () => void) => void } })
+      .window = {
+      addEventListener: () => {},
+    };
+    (globalThis as { document: { getElementById: (id: string) => null } }).document = {
+      getElementById: () => null,
+    };
+
+    const app = Application.configure("./").withRoot(() => null);
+
+    expect(() => app.run()).toThrow("Missing mount node #root.");
+  });
+
+  test("default react renderer mounts and unmounts when stopped", () => {
+    let beforeUnload: (() => void) | undefined;
+    let rendered = 0;
+    let unmounted = 0;
+
+    (globalThis as { window: { addEventListener: (event: string, cb: () => void) => void } })
+      .window = {
+      addEventListener: (_event, cb) => {
+        beforeUnload = cb;
+      },
+    };
+    (globalThis as { document: { getElementById: (id: string) => object | null } }).document = {
+      getElementById: () => ({}),
+    };
+
+    const originalCreateRoot = (ReactDOM as { createRoot: (node: unknown) => unknown }).createRoot;
+    (ReactDOM as { createRoot: (node: unknown) => { render: () => void; unmount: () => void } })
+      .createRoot = () => ({
+      render: () => {
+        rendered += 1;
+      },
+      unmount: () => {
+        unmounted += 1;
+      },
+    });
+
+    try {
+      const running = Application.configure("./").withRoot(() => null).run();
+      expect(rendered).toBe(1);
+      running.stop();
+      expect(unmounted).toBe(1);
+      // Stop twice should still be safe if beforeunload callback also runs.
+      beforeUnload?.();
+      expect(unmounted).toBe(2);
+    } finally {
+      (
+        ReactDOM as { createRoot: (node: unknown) => unknown }
+      ).createRoot = originalCreateRoot;
+    }
+  });
+
+  test("uses fallback no-op renderer cleanup when custom renderer returns nothing", () => {
+    (globalThis as { window: { addEventListener: (event: string, cb: () => void) => void } })
+      .window = {
+      addEventListener: (_event, cb) => {
+        cb();
+      },
+    };
+
+    const app = Application.configure("./")
+      .withRoot(() => null)
+      .withRenderer({ render: () => undefined });
+
+    expect(() => app.run()).not.toThrow();
+  });
+});

package/tests/cache-facade.test.ts

@@ -0,0 +1,45 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { Container } from "inversify";
+import { Application } from "../src/foundation/application";
+import CacheManager from "../src/cache/manager";
+import Cache from "../src/support/facades/cache";
+import Facade from "../src/support/facades/facade";
+import MemoryStorageAdapter from "../src/storage/adapters/memory";
+
+describe("Cache facade", () => {
+  afterEach(() => {
+    Facade.clearResolvedInstances();
+    (Application as unknown as { container: Container | null }).container = null;
+  });
+
+  test("resolves manager and delegates methods", async () => {
+    const manager = new CacheManager({ memory: new MemoryStorageAdapter() }, "memory");
+    const container = new Container();
+    container.bind("cache").toConstantValue(manager);
+    container.bind(CacheManager).toConstantValue(manager);
+    (Application as unknown as { container: Container | null }).container = container;
+
+    await Cache.set("name", "ioc");
+    expect(await Cache.get("name")).toBe("ioc");
+    expect(await Cache.has("name")).toBe(true);
+    expect(await Cache.keys()).toEqual(["name"]);
+    expect(Cache.store()).toBe(manager.store());
+    Cache.use("memory");
+    await Cache.delete("name");
+    expect(await Cache.get("name")).toBeNull();
+    await Cache.set("x", 1);
+    await Cache.clear();
+    expect(await Cache.keys()).toEqual([]);
+  });
+
+  test("uses expected facade accessor", () => {
+    expect((Cache as unknown as { getFacadeAccessor: () => string }).getFacadeAccessor()).toBe(
+      "cache",
+    );
+  });
+
+  test("facade class constructor is defined", () => {
+    const instance = new (Cache as unknown as { new (): object })();
+    expect(instance).toBeTruthy();
+  });
+});