@raubjo/architect-core 0.1.0

package/src/foundation/application.ts

@@ -0,0 +1,207 @@
+import CacheManager from "../cache/manager";
+import { Container } from "inversify";
+import appConfig from "../config/app";
+import { cloneConfigItems } from "../config/clone";
+import { registerGlobalEnv } from "../config/env";
+import ConfigRepository, { type ConfigItems } from "../config/repository";
+import { FileSystem } from "../filesystem/filesystem";
+import LocalAdapter, { __localAdapterTesting } from "../filesystem/adapters/local";
+import ReactRenderer from "../rendering/adapters/react";
+import type { RendererAdapter, RootComponent } from "../rendering/renderer";
+import StorageManager from "../storage/manager";
+import ServiceProvider, {
+  type Cleanup,
+  type ServiceProviderContext,
+} from "../support/service-provider";
+import { registerGlobalStr } from "../support/str";
+import Facade from "../support/facades/facade";
+
+type StartupHandler = (context: ServiceProviderContext) => void | Cleanup;
+type ServiceRegistrar = (context: ServiceProviderContext) => void | Cleanup;
+
+registerGlobalEnv();
+registerGlobalStr();
+
+export const __applicationTesting = {
+  ...__localAdapterTesting,
+};
+
+export class Application {
+  protected static container: Container | null = null;
+  protected static configCache = new Map<string, ConfigItems>();
+  protected static fileSystem = new FileSystem(new LocalAdapter());
+
+  protected providers: ServiceProvider[];
+  protected serviceRegistrars: ServiceRegistrar[];
+  protected startupHandlers: StartupHandler[];
+  protected rootElementId: string;
+  protected RootComponent: RootComponent | null;
+  protected renderer: RendererAdapter | null;
+  protected basePath: string;
+
+  constructor(basePath = "./") {
+    this.basePath = basePath;
+    this.providers = this.getDefaultProviders();
+    this.serviceRegistrars = [];
+    this.startupHandlers = [];
+    this.rootElementId = "root";
+    this.RootComponent = null;
+    this.renderer = null;
+  }
+
+  protected getDefaultProviders(): ServiceProvider[] {
+    return [];
+  }
+
+  protected static getCachedConfigItems(basePath: string): ConfigItems {
+    const cacheKey = __localAdapterTesting.normalizeBasePath(basePath) || ".";
+
+    if (!Application.configCache.has(cacheKey)) {
+      const loaded = {
+        app: appConfig,
+        ...Application.fileSystem.loadConfigItems(basePath),
+      };
+      Application.configCache.set(cacheKey, loaded);
+    }
+
+    // Give each application instance its own mutable repository data.
+    return cloneConfigItems(Application.configCache.get(cacheKey) as ConfigItems);
+  }
+
+  static clearConfigCache(basePath?: string): void {
+    if (typeof basePath === "string") {
+      const cacheKey = __localAdapterTesting.normalizeBasePath(basePath) || ".";
+      Application.configCache.delete(cacheKey);
+      return;
+    }
+
+    Application.configCache.clear();
+  }
+
+  static configure(basePath = "./") {
+    return new Application(basePath);
+  }
+
+  static make<T>(identifier: Parameters<Container["get"]>[0]): T {
+    if (!Application.container) {
+      throw new Error("Application container is not available. Call run() first.");
+    }
+
+    return Application.container.get<T>(identifier);
+  }
+
+  withProviders(providers: ServiceProvider[]) {
+    this.providers.push(...providers);
+    return this;
+  }
+
+  withServices(registerServices: ServiceRegistrar) {
+    this.serviceRegistrars.push(registerServices);
+    return this;
+  }
+
+  withStartup(startupHandler: StartupHandler) {
+    this.startupHandlers.push(startupHandler);
+    return this;
+  }
+
+  withRoot(RootComponent: RootComponent, options: { rootElementId?: string } = {}) {
+    this.RootComponent = RootComponent;
+    this.rootElementId = options.rootElementId ?? this.rootElementId;
+    return this;
+  }
+
+  withRenderer(renderer: RendererAdapter) {
+    this.renderer = renderer;
+    return this;
+  }
+
+  run() {
+    const container = new Container({ defaultScope: "Singleton" });
+    Application.container = container;
+    Facade.clearResolvedInstances();
+    const context = { container };
+    const cleanupTasks: Cleanup[] = [];
+    const configRepository = new ConfigRepository(
+      Application.getCachedConfigItems(this.basePath),
+    );
+    const storageManager = StorageManager.fromConfig(configRepository);
+    const cacheManager = CacheManager.fromConfig(configRepository);
+
+    container.bind("config").toConstantValue(configRepository);
+    container.bind(ConfigRepository).toConstantValue(configRepository);
+    container.bind("storage").toConstantValue(storageManager);
+    container.bind(StorageManager).toConstantValue(storageManager);
+    container.bind("cache").toConstantValue(cacheManager);
+    container.bind(CacheManager).toConstantValue(cacheManager);
+
+    for (const provider of this.providers) {
+      if (typeof provider.register === "function") {
+        const cleanup = provider.register(context);
+        if (typeof cleanup === "function") {
+          cleanupTasks.push(cleanup);
+        }
+      }
+    }
+
+    for (const registerServices of this.serviceRegistrars) {
+      const cleanup = registerServices(context);
+      if (typeof cleanup === "function") {
+        cleanupTasks.push(cleanup);
+      }
+    }
+
+    for (const provider of this.providers) {
+      if (typeof provider.boot === "function") {
+        const cleanup = provider.boot(context);
+        if (typeof cleanup === "function") {
+          cleanupTasks.push(cleanup);
+        }
+      }
+    }
+
+    for (const startupHandler of this.startupHandlers) {
+      const cleanup = startupHandler(context);
+      if (typeof cleanup === "function") {
+        cleanupTasks.push(cleanup);
+      }
+    }
+
+    let rendererCleanup: Cleanup = () => {};
+    if (this.renderer) {
+      if (!this.RootComponent) {
+        throw new Error("Root component is required when using a custom renderer.");
+      }
+      rendererCleanup = this.renderer.render({
+        ...context,
+        RootComponent: this.RootComponent,
+        rootElementId: this.rootElementId,
+      }) ?? rendererCleanup;
+    } else if (this.RootComponent) {
+      rendererCleanup = new ReactRenderer().render({
+        ...context,
+        RootComponent: this.RootComponent,
+        rootElementId: this.rootElementId,
+      });
+    }
+
+    const stop: Cleanup = () => {
+      rendererCleanup();
+      for (const cleanup of cleanupTasks.reverse()) {
+        cleanup();
+      }
+      Facade.clearResolvedInstances();
+      container.unbindAll();
+      if (Application.container === container) {
+        Application.container = null;
+      }
+    };
+
+    window.addEventListener("beforeunload", stop, { once: true });
+
+    return {
+      container,
+      stop,
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/// <reference path="./config/env.global.d.ts" />
+
+export { Application } from "./foundation/application";
+export { default as ServiceProvider } from "./support/service-provider";
+export { DeferrableServiceProvider } from "./support/service-provider";
+export type { Cleanup, ServiceProviderContext } from "./support/service-provider";
+export { default as ConfigServiceProvider } from "./support/providers/config-service-provider";
+
+export { ApplicationProvider, useService } from "./runtimes/react";
+export type {
+  RendererAdapter,
+  RendererContext,
+  RootComponent,
+} from "./rendering/renderer";
+export { default as ReactRenderer } from "./rendering/adapters/react";
+export { default as ConfigRepository } from "./config/repository";
+export { env } from "./config/env";
+export { default as Str } from "./support/str";
+export { default as ConfigFacade } from "./support/facades/config";
+export { default as Config } from "./support/facades/config";
+export { default as CacheManager } from "./cache/manager";
+export type { CacheStore } from "./cache/cache";
+export { default as CacheFacade } from "./support/facades/cache";
+export { default as Cache } from "./support/facades/cache";
+export { default as StorageManager } from "./storage/manager";
+export { default as StorageFacade } from "./support/facades/storage";
+export { default as Storage } from "./support/facades/storage";
+export type { StorageAdapter } from "./storage/storage";
+export { default as MemoryStorageAdapter } from "./storage/adapters/memory";
+export { default as LocalStorageAdapter } from "./storage/adapters/local-storage";
+export { default as IndexedDbAdapter } from "./storage/adapters/indexed-db";
+export { FileSystem } from "./filesystem/filesystem";
+export { default as LocalAdapter } from "./filesystem/adapters/local";

package/src/rendering/adapters/react.tsx

@@ -0,0 +1,27 @@
+import ReactDOM from "react-dom/client";
+import { createElement } from "react";
+import { ApplicationProvider } from "../../runtimes/react";
+import type { RendererAdapter, RendererContext } from "../renderer";
+import type { Cleanup } from "../../support/service-provider";
+
+export default class ReactRenderer implements RendererAdapter {
+  constructor() {}
+
+  render({ RootComponent, container, rootElementId }: RendererContext): Cleanup {
+    const mountNode = document.getElementById(rootElementId);
+    if (!mountNode) {
+      throw new Error(`Missing mount node #${rootElementId}.`);
+    }
+
+    const root = ReactDOM.createRoot(mountNode);
+    root.render(
+      createElement(
+        ApplicationProvider,
+        { container },
+        createElement(RootComponent),
+      ),
+    );
+
+    return () => root.unmount();
+  }
+}

package/src/rendering/renderer.ts

@@ -0,0 +1,13 @@
+import type { Cleanup, ServiceProviderContext } from "../support/service-provider";
+import type { ReactElement } from "react";
+
+export type RootComponent = () => ReactElement | null;
+
+export type RendererContext = ServiceProviderContext & {
+  RootComponent: RootComponent;
+  rootElementId: string;
+};
+
+export interface RendererAdapter {
+  render(context: RendererContext): void | Cleanup;
+}

package/src/runtimes/react.tsx

@@ -0,0 +1,22 @@
+import { createContext, useContext, type ReactNode } from "react";
+import type { Container } from "inversify";
+
+const ContainerContext = createContext<Container | null>(null);
+
+type ApplicationProviderProps = {
+  container: Container;
+  children?: ReactNode;
+};
+
+export function ApplicationProvider({ container, children }: ApplicationProviderProps) {
+  return <ContainerContext.Provider value={container}>{children}</ContainerContext.Provider>;
+}
+
+export function useService<T>(identifier: Parameters<Container["get"]>[0]): T {
+  const container = useContext(ContainerContext);
+  if (!container) {
+    throw new Error("Application container is not available in React context.");
+  }
+
+  return container.get<T>(identifier);
+}

package/src/storage/adapters/indexed-db.ts

@@ -0,0 +1,180 @@
+import MemoryStorageAdapter from "./memory";
+import type { StorageAdapter } from "../storage";
+
+type OpenFactory = Pick<IDBFactory, "open">;
+
+export default class IndexedDbAdapter implements StorageAdapter {
+  protected fallback: StorageAdapter;
+  protected name: string;
+  protected factory: OpenFactory | null;
+  protected dbPromise: Promise<IDBDatabase> | null;
+
+  constructor(
+    options: {
+      factory?: OpenFactory | null;
+      name?: string;
+      fallback?: StorageAdapter;
+    } = {},
+  ) {
+    this.factory = options.factory ?? (globalThis.indexedDB ?? null);
+    this.name = options.name ?? "ioc-storage";
+    this.fallback = options.fallback ?? new MemoryStorageAdapter();
+    this.dbPromise = null;
+  }
+
+  protected req<T>(request: IDBRequest<T>): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error ?? new Error("IndexedDB request failed."));
+    });
+  }
+
+  protected openDb(): Promise<IDBDatabase> {
+    if (this.dbPromise) {
+      return this.dbPromise;
+    }
+
+    if (!this.factory) {
+      return Promise.reject(new Error("IndexedDB is not available."));
+    }
+
+    this.dbPromise = new Promise<IDBDatabase>((resolve, reject) => {
+      const request = this.factory?.open(this.name, 1);
+      if (!request) {
+        reject(new Error("IndexedDB open request could not be created."));
+        return;
+      }
+
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains("kv")) {
+          db.createObjectStore("kv");
+        }
+      };
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () =>
+        reject(request.error ?? new Error("IndexedDB database could not be opened."));
+    });
+
+    return this.dbPromise;
+  }
+
+  protected async withStore<T>(
+    mode: IDBTransactionMode,
+    action: (store: IDBObjectStore) => Promise<T>,
+  ): Promise<T> {
+    try {
+      const db = await this.openDb();
+      const tx = db.transaction("kv", mode);
+      const store = tx.objectStore("kv");
+      return await action(store);
+    } catch (_error) {
+      return actionFallback(this.fallback, mode, action);
+    }
+  }
+
+  async get<T = unknown>(key: string): Promise<T | null> {
+    return this.withStore("readonly", async (store) => {
+      const value = await this.req<unknown>(store.get(key));
+      return value === undefined ? null : (value as T);
+    });
+  }
+
+  async set<T = unknown>(key: string, value: T): Promise<void> {
+    await this.withStore("readwrite", async (store) => {
+      await this.req(store.put(value, key));
+      return undefined;
+    });
+  }
+
+  async has(key: string): Promise<boolean> {
+    return this.withStore("readonly", async (store) => {
+      const count = await this.req<number>(store.count(key));
+      return count > 0;
+    });
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.withStore("readwrite", async (store) => {
+      await this.req(store.delete(key));
+      return undefined;
+    });
+  }
+
+  async clear(): Promise<void> {
+    await this.withStore("readwrite", async (store) => {
+      await this.req(store.clear());
+      return undefined;
+    });
+  }
+
+  async keys(): Promise<string[]> {
+    return this.withStore("readonly", async (store) => {
+      const keys = await this.req<Array<IDBValidKey>>(store.getAllKeys());
+      const normalized: string[] = [];
+      for (const key of keys) {
+        normalized.push(String(key));
+      }
+
+      return normalized;
+    });
+  }
+}
+
+async function actionFallback<T>(
+  fallback: StorageAdapter,
+  mode: IDBTransactionMode,
+  action: (store: IDBObjectStore) => Promise<T>,
+): Promise<T> {
+  // Keep call sites small: map IDB actions to the same short storage contract.
+  if (mode === "readonly") {
+    const store = createReadonlyProxy(fallback);
+    return action(store as unknown as IDBObjectStore);
+  }
+
+  const store = createReadWriteProxy(fallback);
+  return action(store as unknown as IDBObjectStore);
+}
+
+function createReadonlyProxy(fallback: StorageAdapter): Partial<IDBObjectStore> {
+  return {
+    get: (key: IDBValidKey) => wrapPromiseRequest(fallback.get(String(key))),
+    count: (key?: IDBValidKey | IDBKeyRange) =>
+      wrapPromiseRequest(
+        fallback.has(String(key as IDBValidKey)).then((exists) => (exists ? 1 : 0)),
+      ),
+    getAllKeys: () =>
+      wrapPromiseRequest(fallback.keys().then((keys) => keys as Array<IDBValidKey>)),
+  };
+}
+
+function createReadWriteProxy(fallback: StorageAdapter): Partial<IDBObjectStore> {
+  return {
+    ...createReadonlyProxy(fallback),
+    put: (value: unknown, key?: IDBValidKey) =>
+      wrapPromiseRequest(fallback.set(String(key as IDBValidKey), value)),
+    delete: (key: IDBValidKey | IDBKeyRange) =>
+      wrapPromiseRequest(fallback.delete(String(key as IDBValidKey))),
+    clear: () => wrapPromiseRequest(fallback.clear()),
+  };
+}
+
+function wrapPromiseRequest<T>(promise: Promise<T>): IDBRequest<T> {
+  const request: Partial<IDBRequest<T>> = {
+    onsuccess: null,
+    onerror: null,
+  };
+
+  promise.then(
+    (result) => {
+      request.result = result;
+      request.onsuccess?.call(request as IDBRequest<T>, new Event("success"));
+    },
+    (error) => {
+      request.error = error as DOMException;
+      request.onerror?.call(request as IDBRequest<T>, new Event("error"));
+    },
+  );
+
+  return request as IDBRequest<T>;
+}

package/src/storage/adapters/local-storage.ts

@@ -0,0 +1,46 @@
+import type { StorageAdapter } from "../storage";
+
+export default class LocalStorageAdapter implements StorageAdapter {
+  protected storage: Storage;
+
+  constructor(storage: Storage = window.localStorage) {
+    this.storage = storage;
+  }
+
+  async get<T = unknown>(key: string): Promise<T | null> {
+    const value = this.storage.getItem(key);
+    if (value === null) {
+      return null;
+    }
+
+    return JSON.parse(value) as T;
+  }
+
+  async set<T = unknown>(key: string, value: T): Promise<void> {
+    this.storage.setItem(key, JSON.stringify(value));
+  }
+
+  async has(key: string): Promise<boolean> {
+    return this.storage.getItem(key) !== null;
+  }
+
+  async delete(key: string): Promise<void> {
+    this.storage.removeItem(key);
+  }
+
+  async clear(): Promise<void> {
+    this.storage.clear();
+  }
+
+  async keys(): Promise<string[]> {
+    const keys: string[] = [];
+    for (let i = 0; i < this.storage.length; i += 1) {
+      const key = this.storage.key(i);
+      if (key !== null) {
+        keys.push(key);
+      }
+    }
+
+    return keys;
+  }
+}

package/src/storage/adapters/memory.ts

@@ -0,0 +1,35 @@
+import type { StorageAdapter } from "../storage";
+
+export default class MemoryStorageAdapter implements StorageAdapter {
+  protected items = new Map<string, unknown>();
+
+  constructor() {}
+
+  async get<T = unknown>(key: string): Promise<T | null> {
+    if (!this.items.has(key)) {
+      return null;
+    }
+
+    return this.items.get(key) as T;
+  }
+
+  async set<T = unknown>(key: string, value: T): Promise<void> {
+    this.items.set(key, value);
+  }
+
+  async has(key: string): Promise<boolean> {
+    return this.items.has(key);
+  }
+
+  async delete(key: string): Promise<void> {
+    this.items.delete(key);
+  }
+
+  async clear(): Promise<void> {
+    this.items.clear();
+  }
+
+  async keys(): Promise<string[]> {
+    return Array.from(this.items.keys());
+  }
+}

package/src/storage/manager.ts

@@ -0,0 +1,78 @@
+import type ConfigRepository from "../config/repository";
+import IndexedDbAdapter from "./adapters/indexed-db";
+import LocalStorageAdapter from "./adapters/local-storage";
+import MemoryStorageAdapter from "./adapters/memory";
+import type { StorageAdapter } from "./storage";
+
+type DriverName = "memory" | "local" | "indexed";
+
+export default class StorageManager implements StorageAdapter {
+  protected adapters: Record<string, StorageAdapter>;
+  protected active: string;
+
+  constructor(adapters: Record<string, StorageAdapter>, active: string = "memory") {
+    this.adapters = adapters;
+    this.active = active in this.adapters ? active : "memory";
+  }
+
+  static fromConfig(config: ConfigRepository): StorageManager {
+    const adapters = StorageManager.defaultAdapters();
+    const driver = config.string("storage.driver", "memory");
+
+    return new StorageManager(adapters, driver);
+  }
+
+  static defaultAdapters(): Record<DriverName, StorageAdapter> {
+    const memory = new MemoryStorageAdapter();
+    const hasWindow = typeof window !== "undefined";
+    const hasLocal = hasWindow && typeof window.localStorage !== "undefined";
+    const hasIndexed = typeof globalThis.indexedDB !== "undefined";
+
+    return {
+      memory,
+      local: hasLocal ? new LocalStorageAdapter(window.localStorage) : memory,
+      indexed: hasIndexed ? new IndexedDbAdapter() : memory,
+    };
+  }
+
+  drv(name?: string): StorageAdapter {
+    if (typeof name === "string") {
+      if (!(name in this.adapters)) {
+        throw new Error(`Storage driver [${name}] is not defined.`);
+      }
+
+      return this.adapters[name];
+    }
+
+    return this.adapters[this.active];
+  }
+
+  use(name: string): this {
+    this.active = this.drv(name) ? name : this.active;
+    return this;
+  }
+
+  get<T = unknown>(key: string): Promise<T | null> {
+    return this.drv().get<T>(key);
+  }
+
+  set<T = unknown>(key: string, value: T): Promise<void> {
+    return this.drv().set<T>(key, value);
+  }
+
+  has(key: string): Promise<boolean> {
+    return this.drv().has(key);
+  }
+
+  delete(key: string): Promise<void> {
+    return this.drv().delete(key);
+  }
+
+  clear(): Promise<void> {
+    return this.drv().clear();
+  }
+
+  keys(): Promise<string[]> {
+    return this.drv().keys();
+  }
+}

package/src/storage/storage.ts

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