@saolabs/client 1.0.0

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@saolabs/client",
+  "version": "1.0.0",
+  "description": "Saola Client - Modern TypeScript Framework for Laravel. Reactive SPAs with TypeScript-first approach.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./plugins": {
+      "types": "./dist/plugins.d.ts",
+      "import": "./dist/plugins.js",
+      "require": "./dist/plugins.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "require": "./dist/core/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "index.ts",
+    "plugins.ts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "publish-dry-run": "npm publish --dry-run",
+    "test": "echo \"No tests specified yet\""
+  },
+  "keywords": [
+    "typescript",
+    "framework",
+    "laravel",
+    "spa",
+    "reactive",
+    "frontend"
+  ],
+  "author": "Saola Labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saolabs/saola-client.git"
+  },
+  "bugs": {
+    "url": "https://github.com/saolabs/saola-client/issues"
+  },
+  "homepage": "https://github.com/saolabs/saola-client#readme",
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "directories": {
+    "doc": "docs"
+  },
+  "dependencies": {
+    "undici-types": "^6.21.0"
+  },
+  "type": "commonjs"
+}

package/plugins.ts

@@ -0,0 +1,77 @@
+/**
+ * OneView Plugins
+ * Extension system for OneView framework
+ */
+
+export interface PluginOptions {
+  [key: string]: unknown;
+}
+
+export interface Plugin {
+  name: string;
+  install(options?: PluginOptions): void;
+}
+
+class PluginManager {
+  private plugins: Map<string, Plugin> = new Map();
+  private installed: Set<string> = new Set();
+
+  /**
+   * Register a plugin
+   */
+  register(plugin: Plugin): this {
+    if (this.plugins.has(plugin.name)) {
+      console.warn(`Plugin "${plugin.name}" is already registered`);
+      return this;
+    }
+    this.plugins.set(plugin.name, plugin);
+    return this;
+  }
+
+  /**
+   * Install a registered plugin
+   */
+  install(name: string, options?: PluginOptions): this {
+    const plugin = this.plugins.get(name);
+    if (!plugin) {
+      throw new Error(`Plugin "${name}" is not registered`);
+    }
+    
+    if (this.installed.has(name)) {
+      console.warn(`Plugin "${name}" is already installed`);
+      return this;
+    }
+
+    plugin.install(options);
+    this.installed.add(name);
+    return this;
+  }
+
+  /**
+   * Check if a plugin is installed
+   */
+  isInstalled(name: string): boolean {
+    return this.installed.has(name);
+  }
+
+  /**
+   * Get all registered plugins
+   */
+  getPlugins(): Plugin[] {
+    return Array.from(this.plugins.values());
+  }
+}
+
+export const pluginManager = new PluginManager();
+
+/**
+ * Create a plugin
+ */
+export function createPlugin(name: string, install: (options?: PluginOptions) => void): Plugin {
+  return {
+    name,
+    install
+  };
+}
+
+export default pluginManager;

package/src/core/app/Application.ts

@@ -0,0 +1,410 @@
+/**
+ * Application — DI Container + App Lifecycle.
+ *
+ * Tương tự Laravel Service Container:
+ *   - bind / singleton / instance  → đăng ký service
+ *   - make / resolve               → lấy service
+ *   - alias                        → tên tắt
+ *   - register / boot              → service providers
+ *
+ * Khác với core Application (hardcode services), bản này hoàn toàn DI-driven:
+ * mọi service (Router, ViewManager, Store...) đều được đăng ký qua providers.
+ *
+ * @example
+ * const app = new Application();
+ *
+ * // Đăng ký trực tiếp
+ * app.singleton('markerRegistry', MarkerRegistry);
+ * app.instance('config', { debug: true });
+ *
+ * // Đăng ký qua provider
+ * app.register({
+ *     register(app) { app.singleton('router', () => new Router(app)); },
+ *     boot(app) { app.make('router').start(); }
+ * });
+ *
+ * app.boot();
+ * const router = app.make('router');
+ */
+
+import type { ApplicationInterface, ServiceKey, ServiceFactory, ServiceBinding } from '../contracts/ApplicationInterface';
+import type { ServiceProviderInterface } from '../contracts/ServiceProviderInterface';
+import type { ViewManagerInterface, RouterInterface } from '../contracts/utils';
+import type { HelperInterface } from '../contracts/HelperInterface';
+import type { EventServiceInterface } from '../contracts/EventServiceInterface';
+import type { HttpServiceInterface } from '../contracts/HttpServiceInterface';
+import type { StoreServiceInterface } from '../contracts/StoreServiceInterface';
+import type { StorageServiceInterface } from '../contracts/StorageServiceInterface';
+import type { LoggerServiceInterface } from '../contracts/LoggerServiceInterface';
+import { APIClientInterface } from '../contracts/ApiInterface';
+import { OneObjectType, OOTEnum } from '../types/utils';
+
+// ─── Application ────────────────────────────────────────────────
+
+export class Application implements ApplicationInterface {
+    readonly oneType: OneObjectType = OOTEnum.APPLICATION;
+    // Service properties — set during bootstrap via App.set()
+    declare isInitialized: boolean;
+    declare isStarted: boolean;
+    declare View: ViewManagerInterface;
+    declare Router: RouterInterface;
+    declare Helper: HelperInterface;
+    declare Events: EventServiceInterface;
+    declare Http: HttpServiceInterface;
+    declare API: APIClientInterface;
+    declare Store: StoreServiceInterface;
+    declare Storage: StorageServiceInterface;
+    declare Logger: LoggerServiceInterface;
+
+    /** Factory bindings — mỗi lần make() gọi factory tạo instance mới */
+    private bindings = new Map<ServiceKey, ServiceFactory<any>>();
+
+    /** Singleton instances — tạo một lần, reuse */
+    private singletons = new Map<ServiceKey, any>();
+
+    /** Aliases — tên tắt trỏ về key gốc */
+    private aliases = new Map<string | symbol, ServiceKey>();
+
+    /** Service providers đã đăng ký */
+    private providers: ServiceProviderInterface[] = [];
+
+    /** Đã boot chưa */
+    private booted = false;
+
+    private ownProperties: string[] = [
+        'bindings',
+        'singletons',
+        'aliases',
+        'providers',
+        'booted',
+        'ownProperties',
+        'transient',
+        'bind',
+        'singleton',
+        'instance',
+        'alias',
+        'make',
+        'resolve',
+        'has',
+        'bound',
+        'register',
+        'boot',
+        'isBooted',
+        'flush',
+        'destroy',
+        'getBindings',
+        'getSingletons',
+        '__store',
+    ]; // Để track dynamic properties nếu cần
+
+    __store: Map<string, { isOverridable: boolean, value: any }> = new Map(); // Store cho dynamic properties nếu cần
+
+    [key: string]: any; // Cho phép dynamic properties nếu cần
+
+    constructor() { }
+
+    // ─── Transient (factory — instance mới mỗi lần) ───────────
+
+    /**
+     * Đăng ký transient service.
+     * Mỗi lần make() trả về instance mới (không cache).
+     *
+     * @example
+     * app.transient('request', (app) => new Request(app.make('config')));
+     * app.transient(Database, Database); // class shorthand
+     */
+    transient<T>(key: ServiceKey<T>, value: ServiceBinding<T>): this {
+        this.bindings.set(key, (app) => {
+            if (typeof value === 'function' && value.prototype) {
+                return new (value as new (...args: any[]) => T)();
+            }
+            return (value as ServiceFactory<T>)(app);
+        });
+        return this;
+    }
+
+    bind<T>(key: ServiceKey<T>, value: ServiceBinding<T>): this {
+        return this.transient(key, value);
+    }
+
+    // ─── Singleton (instance duy nhất) ──────────────────────────
+
+    /**
+     * Đăng ký singleton — tạo một lần, reuse mãi mãi.
+     *
+     * @example
+     * app.singleton('store', StoreService);           // class
+     * app.singleton('config', (app) => loadConfig()); // factory
+     * app.singleton(StoreService);                    // class, tự tạo
+     * app.singleton('store', existingInstance);        // instance sẵn
+     */
+    singleton<T>(key: ServiceKey<T>, value?: ServiceBinding<T> | T): this {
+        // singleton(MyClass) — không có value, key là class
+        if (value === undefined) {
+            if (typeof key === 'function') {
+                this.singletons.set(key, new (key as new (...args: any[]) => T)());
+                return this;
+            }
+            throw new Error(`[Application] Singleton requires a value for key: ${String(key)}`);
+        }
+
+        // value là instance sẵn (object, không phải function)
+        if (value !== null && typeof value === 'object') {
+            this.singletons.set(key, value);
+            return this;
+        }
+
+        // value là class hoặc factory — lazy init
+        this.bindings.set(key, (app) => {
+            if (!this.singletons.has(key)) {
+                const isClass = typeof value === 'function' && (value as any).prototype;
+                const instance = isClass
+                    ? new (value as new (...args: any[]) => T)()
+                    : (value as ServiceFactory<T>)(app);
+                this.singletons.set(key, instance);
+            }
+            return this.singletons.get(key);
+        });
+        return this;
+    }
+
+    // ─── Instance (đăng ký instance sẵn) ────────────────────────
+
+    /**
+     * Đăng ký instance đã tạo sẵn.
+     * Shortcut cho singleton khi đã có instance.
+     *
+     * @example
+     * app.instance('config', { debug: true, api_url: '/api' });
+     */
+    instance<T>(key: ServiceKey<T>, value: T): this {
+        this.singletons.set(key, value);
+        return this;
+    }
+
+    // ─── Alias ──────────────────────────────────────────────────
+
+    /**
+     * Tạo tên tắt cho service.
+     *
+     * @example
+     * app.singleton('email.service', EmailService);
+     * app.alias('mailer', 'email.service');
+     * app.make('mailer') === app.make('email.service') // true
+     */
+    alias(alias: string | symbol, key: ServiceKey): this {
+        this.aliases.set(alias, key);
+        return this;
+    }
+
+    // ─── Resolve ────────────────────────────────────────────────
+
+    /**
+     * Lấy service instance. Shortcut cho resolve().
+     *
+     * @example
+     * const router = app.make<Router>('router');
+     */
+    make<T>(key: ServiceKey<T>, defaultValue?: T): T {
+        return this.resolve(key, defaultValue);
+    }
+
+    /**
+     * Resolve service instance.
+     *
+     * Thứ tự tìm:
+     *   1. Alias → resolve key gốc
+     *   2. Singleton đã tạo → reuse
+     *   3. Binding (factory) → gọi factory
+     *   4. Key là class → auto-instantiate + cache
+     *   5. defaultValue → trả về
+     *   6. Throw error
+     */
+    resolve<T>(key: ServiceKey<T>, defaultValue?: T): T {
+        // 1. Resolve alias
+        let resolved: ServiceKey<T> = key;
+        if ((typeof key === 'string' || typeof key === 'symbol') && this.aliases.has(key)) {
+            resolved = this.aliases.get(key)! as ServiceKey<T>;
+        }
+
+        // 2. Singleton đã có
+        if (this.singletons.has(resolved)) {
+            return this.singletons.get(resolved);
+        }
+
+        // 3. Binding factory
+        const factory = this.bindings.get(resolved);
+        if (factory) {
+            return factory(this);
+        }
+
+        // 4. Auto-instantiate class
+        if (typeof resolved === 'function') {
+            if (resolved.prototype) {
+                const inst = new (resolved as new (...args: any[]) => T)();
+                this.singletons.set(resolved, inst);
+                return inst;
+            }
+            return (resolved as Function)(this);
+        }
+
+        // 5. Default value
+        if (defaultValue !== undefined) {
+            return defaultValue;
+        }
+
+        // 6. Not found
+        throw new Error(`[Application] Cannot resolve: ${String(key)}`);
+    }
+
+    // ─── Query ──────────────────────────────────────────────────
+
+    /** Kiểm tra service đã đăng ký chưa */
+    has(key: ServiceKey): boolean {
+        const aliased = (typeof key === 'string' || typeof key === 'symbol') && this.aliases.has(key);
+        return this.bindings.has(key) || this.singletons.has(key) || aliased
+            || (typeof key === 'string' && this.__store.has(key));
+    }
+
+    /** Alias cho has() */
+    bound(key: ServiceKey): boolean {
+        return this.has(key);
+    }
+
+    // ─── Service Providers ──────────────────────────────────────
+
+    /**
+     * Đăng ký service provider.
+     * register() được gọi ngay, boot() gọi khi app.boot().
+     *
+     * @example
+     * app.register({
+     *     register(app) { app.singleton('db', Database); },
+     *     boot(app) { app.make('db').connect(); }
+     * });
+     */
+    register(provider: ServiceProviderInterface): this {
+        this.providers.push(provider);
+        if (typeof (provider as any).initApplication === 'function') {
+            (provider as any).initApplication();
+        }
+        provider.register();
+        return this;
+    }
+
+    /**
+     * Boot tất cả providers.
+     * Gọi boot() của mỗi provider theo thứ tự đăng ký.
+     * Chỉ chạy một lần.
+     */
+    boot(): void {
+        if (this.booted) return;
+
+        for (const provider of this.providers) {
+            if (typeof provider.boot === 'function') {
+                provider.boot();
+            }
+        }
+
+        this.booted = true;
+    }
+
+    /** Đã boot chưa */
+    get isBooted(): boolean {
+        return this.booted;
+    }
+
+    // ─── Cleanup ────────────────────────────────────────────────
+
+    /** Xóa toàn bộ bindings, singletons, aliases, __store. Reset container. */
+    flush(): void {
+        this.bindings.clear();
+        this.singletons.clear();
+        this.aliases.clear();
+        this.__store.clear();
+        this.providers = [];
+        this.booted = false;
+    }
+
+    /** Destroy app — flush + cleanup */
+    destroy(): void {
+        this.flush();
+    }
+
+    // ─── Introspection (debug) ──────────────────────────────────
+
+    getBindings(): Map<ServiceKey, ServiceFactory<any>> {
+        return this.bindings;
+    }
+
+    getSingletons(): Map<ServiceKey, any> {
+        return this.singletons;
+    }
+
+
+    set<T = any>(name: string, value: T, isOne: boolean = false): void {
+        if (this.ownProperties.includes(name)) {
+            return; // Không cho ghi đè lên thuộc tính có sẵn
+        }
+        if (this.__store.has(name) && this.__store.get(name)?.isOverridable === false) {
+            return; // Không cho ghi đè lên thuộc tính không thể override
+        }
+        this.__store.set(name, { value, isOverridable: !isOne });
+        this.singletons.set(name, value); // Sync → DI container
+        Object.defineProperty(this, name, {
+            get: () => this.__store.get(name)?.value,
+            set: (newValue) => {
+                if (this.__store.has(name) && this.__store.get(name)?.isOverridable === false) {
+                    return; // Không cho ghi đè nếu isOverridable là false
+                }
+                this.__store.set(name, { value: newValue, isOverridable: !isOne });
+                this.singletons.set(name, newValue); // Sync → DI container
+            },
+            configurable: isOne ? false : true,
+            enumerable: false,
+        });
+    }
+
+    get<T = any>(name: string): T {
+        if (this.ownProperties.includes(name)) {
+            return (this as any)[name]; // Trả về thuộc tính có sẵn
+        }
+        // Check __store first (registered via set())
+        if (this.__store.has(name)) {
+            return this.__store.get(name)?.value;
+        }
+        // Fall back to DI container (registered via singleton/instance/bind)
+        if (this.singletons.has(name) || this.bindings.has(name) || this.aliases.has(name)) {
+            return this.resolve(name);
+        }
+        return undefined as T;
+    }
+
+    setMethod(name: string, method: Function, isOne: boolean = false): void {
+        if (this.ownProperties.includes(name)) {
+            return; // Không cho ghi đè lên thuộc tính có sẵn
+        }
+        if (this.__store.has(name) && this.__store.get(name)?.isOverridable === false) {
+            return; // Không cho ghi đè lên thuộc tính không thể override
+        }
+        this.__store.set(name, { value: method, isOverridable: !isOne });
+        (this as any)[name] = (...args: any[]) => {
+            const fn = this.get(name);
+            if (typeof fn === 'function') {
+                if (typeof fn.bind === 'function') {
+                    return fn.bind(this)(...args);
+                }
+                return fn.apply(this, args);
+            }
+            throw new Error(`[Application] Method ${name} is not a function`);
+        };
+        if (isOne) {
+            Object.defineProperty(this, name, {
+                configurable: false,
+                writable: false,
+            });
+        }
+    }
+
+    // ─── Singleton App Instance ─────────────────────────────────────
+}

package/src/core/bootstrap/app.ts

@@ -0,0 +1,58 @@
+import { ApplicationInterface } from "../contracts/ApplicationInterface";
+import { app } from "../hellpers/app";
+import { Router } from "../routers";
+import { buildDefaultProviders, resolveProviderOrder } from "./providers";
+
+const App: ApplicationInterface = app<ApplicationInterface>();
+
+// ⚠️ Flags PHẢI dùng isOne=false để có thể cập nhật sau init/start
+App.set<boolean>('isInitialized', false);
+App.set<boolean>('isStarted', false);
+
+/**
+ * Khởi tạo app — đăng ký + boot tất cả providers theo dependency order.
+ *
+ * @example
+ * App.init({
+ *     view: { container: '#app', registry: {...} },
+ *     router: { mode: 'history', routes: [...] },
+ *     api: { endpoint: '/api' },
+ *     providers: [{ name: 'analytics', dependsOn: ['core'], register(app) {...} }]
+ * });
+ */
+App.setMethod('init', function (config: Record<string, any> = {}) {
+    if (App.isInitialized) {
+        console.warn('[Bootstrap] App already initialized.');
+        return;
+    }
+
+    const providers = resolveProviderOrder(buildDefaultProviders(config));
+    for (const provider of providers) {
+        App.register(provider);
+    }
+
+    App.boot();
+    App.isInitialized = true;
+}, true);
+
+/**
+ * Start app — init nếu chưa, rồi start Router.
+ *
+ * @example
+ * App.start(); // init với config mặc định
+ * App.start({ view: { container: '#app' } }); // init với config tùy chỉnh
+ */
+App.setMethod('start', function (config?: Record<string, any>) {
+    if (App.isStarted) {
+        console.warn('[Bootstrap] App already started.');
+        return;
+    }
+    if (!App.isInitialized) {
+        App.init(config || {});
+    }
+
+    App.get<Router>('Router').start();
+    App.isStarted = true;
+}, true);
+
+export default App;

package/src/core/bootstrap/providers/ApiServiceProvider.ts

@@ -0,0 +1,18 @@
+import { APIClientInterface } from "../../contracts/ApiInterface";
+import { ApiClient } from "../../hellpers/ApiClient";
+import { PROVIDER_NAMES } from "./provider-order";
+import { ServiceProvider } from "./ServiceProvider";
+
+export class ApiServiceProvider extends ServiceProvider {
+    readonly name = PROVIDER_NAMES.API;
+    readonly dependsOn = [PROVIDER_NAMES.CORE];
+    static config: Record<string, any> = {};
+
+    register(): void {
+        this.app.set<APIClientInterface>("API", new ApiClient(), true);
+    }
+
+    boot(): void {
+        this.app.get<APIClientInterface>("API").init(ApiServiceProvider.config);
+    }
+}

package/src/core/bootstrap/providers/CoreServiceProvider.ts

@@ -0,0 +1,19 @@
+import { app } from "../../hellpers/app";
+import { EventService } from "../../services/EventService";
+import { HttpService } from "../../services/HttpService";
+import { MarkerService } from "../../services/MarkerService";
+import { StoreService } from "../../services/StoreService";
+import { PROVIDER_NAMES } from "./provider-order";
+import { ServiceProvider } from "./ServiceProvider";
+
+export class CoreServiceProvider extends ServiceProvider {
+    readonly name = PROVIDER_NAMES.CORE;
+
+    register(): void {
+        this.app.set<MarkerService>("Marker", app<MarkerService>(MarkerService), true);
+        this.app.set<StoreService>("Store", StoreService.instance(), true);
+        this.app.set<StoreService>("Storage", StoreService.instance(), true);
+        this.app.set<EventService>("Event", EventService.instance(), true);
+        this.app.set<HttpService>("Http", HttpService.instance(), true);
+    }
+}

package/src/core/bootstrap/providers/HelperServiceProvider.ts

@@ -0,0 +1,12 @@
+import { HelperService } from "../../services/HelperService";
+import { PROVIDER_NAMES } from "./provider-order";
+import { ServiceProvider } from "./ServiceProvider";
+
+export class HelperServiceProvider extends ServiceProvider {
+    readonly name = PROVIDER_NAMES.HELPER;
+    readonly dependsOn = [PROVIDER_NAMES.CORE, PROVIDER_NAMES.ROUTER, PROVIDER_NAMES.VIEW];
+
+    register(): void {
+        this.app.set<HelperService>("Helper", new HelperService(this.app), true);
+    }
+}

package/src/core/bootstrap/providers/RouteServiceProvider.ts

@@ -0,0 +1,17 @@
+import { Router } from "../../routers";
+import { PROVIDER_NAMES } from "./provider-order";
+import { ServiceProvider } from "./ServiceProvider";
+
+export class RouteServiceProvider extends ServiceProvider {
+    readonly name = PROVIDER_NAMES.ROUTER;
+    readonly dependsOn = [PROVIDER_NAMES.VIEW];
+    static config: Record<string, any> = {};
+
+    register(): void {
+        this.app.set<Router>("Router", new Router(this.app), true);
+    }
+
+    boot(): void {
+        this.app.get<Router>("Router").init(RouteServiceProvider.config);
+    }
+}