@saolabs/client 1.0.0

package/src/core/services/HttpService.ts

@@ -0,0 +1,235 @@
+/**
+ * HttpService — Fetch-based HTTP client.
+ *
+ * Features:
+ *   - Base URL, default headers, timeout
+ *   - Request/response/error interceptors (chainable)
+ *   - Auto-cancel duplicate in-flight requests (same method + URL)
+ *   - Convenience: get, post, put, patch, delete
+ *
+ * Register via DI:
+ *   app.singleton('http', () => {
+ *       const http = new HttpService();
+ *       http.setBaseUrl('/api');
+ *       return http;
+ *   });
+ */
+
+// ─── Types ──────────────────────────────────────────────────────
+
+export interface HttpRequestConfig extends RequestInit {
+    headers?: Record<string, string>;
+    timeout?: number;
+    [key: string]: any;
+}
+
+export interface HttpResponse<T = any> {
+    status: boolean;
+    statusCode: number;
+    data: T;
+    headers: Headers;
+}
+
+export interface HttpInterceptor {
+    request?: (config: HttpRequestConfig) => HttpRequestConfig | Promise<HttpRequestConfig>;
+    response?: <T = any>(response: HttpResponse<T>) => HttpResponse<T> | Promise<HttpResponse<T>>;
+    error?: (error: Error) => Error | Promise<Error>;
+}
+
+// ─── HttpService ────────────────────────────────────────────────
+
+export class HttpService {
+    private static instances: Map<string, HttpService> = new Map();
+    static getInstance(key: string = 'default'): HttpService {
+        if (!HttpService.instances.has(key)) {
+            HttpService.instances.set(key, new HttpService());
+        }
+        return HttpService.instances.get(key)!;
+    }
+    static instance(key: string = 'default'): HttpService {
+        return HttpService.getInstance(key);
+    }
+    static removeInstance(key: string = 'default'): void {
+        HttpService.instances.delete(key);
+    }
+    
+    private baseUrl: string = '';
+    private timeout: number = 10000;
+    private defaultHeaders: Record<string, string> = {};
+    private interceptors: HttpInterceptor[] = [];
+    private pending = new Map<string, AbortController>();
+
+    // ─── Config ─────────────────────────────────────────────────
+
+    setBaseUrl(url: string): this {
+        this.baseUrl = url.endsWith('/') ? url.slice(0, -1) : url;
+        return this;
+    }
+
+    setTimeout(ms: number): this {
+        this.timeout = ms;
+        return this;
+    }
+
+    setDefaultHeaders(headers: Record<string, string>): this {
+        Object.assign(this.defaultHeaders, headers);
+        return this;
+    }
+
+    setHeader(name: string, value: string): this {
+        this.defaultHeaders[name] = value;
+        return this;
+    }
+
+    removeHeader(name: string): this {
+        delete this.defaultHeaders[name];
+        return this;
+    }
+
+    /** Add interceptor. Returns unregister function. */
+    addInterceptor(interceptor: HttpInterceptor): () => void {
+        this.interceptors.push(interceptor);
+        return () => {
+            const idx = this.interceptors.indexOf(interceptor);
+            if (idx !== -1) this.interceptors.splice(idx, 1);
+        };
+    }
+
+    // ─── Core Request ───────────────────────────────────────────
+
+    async request<T = any>(
+        method: string,
+        url: string,
+        data: any = null,
+        options: HttpRequestConfig = {},
+    ): Promise<HttpResponse<T>> {
+        // Build full URL
+        let fullUrl = url.startsWith('http') ? url : `${this.baseUrl}${url}`;
+
+        // Cancel duplicate in-flight request
+        const requestKey = `${method.toUpperCase()}:${fullUrl}`;
+        this.pending.get(requestKey)?.abort();
+
+        const controller = new AbortController();
+        this.pending.set(requestKey, controller);
+
+        // Build config
+        let config: HttpRequestConfig = {
+            method: method.toUpperCase(),
+            headers: { ...this.defaultHeaders, ...options.headers },
+            signal: options.signal ?? controller.signal,
+            ...options,
+        };
+
+        // Apply request interceptors
+        for (const i of this.interceptors) {
+            if (i.request) config = await i.request(config);
+        }
+
+        // Body for POST/PUT/PATCH
+        if (data && ['POST', 'PUT', 'PATCH'].includes(config.method!)) {
+            const ct = (config.headers as Record<string, string>)?.['Content-Type'];
+            if (data instanceof FormData) {
+                config.body = data;
+                delete (config.headers as Record<string, string>)['Content-Type'];
+            } else if (ct === 'application/json' || !ct) {
+                (config.headers as Record<string, string>)['Content-Type'] = 'application/json';
+                config.body = JSON.stringify(data);
+            } else {
+                config.body = data;
+            }
+        }
+
+        // Query params for GET
+        if (data && config.method === 'GET' && typeof data === 'object') {
+            const urlObj = new URL(fullUrl, window.location.origin);
+            for (const [key, value] of Object.entries(data)) {
+                urlObj.searchParams.append(key, String(value));
+            }
+            fullUrl = urlObj.toString();
+        }
+
+        try {
+            const timeoutId = setTimeout(() => controller.abort(), options.timeout ?? this.timeout);
+            const raw = await fetch(fullUrl, config);
+            clearTimeout(timeoutId);
+
+            const responseData = await raw.json().catch(() => ({}));
+
+            let response: HttpResponse<T> = {
+                status: raw.ok,
+                statusCode: raw.status,
+                data: responseData,
+                headers: raw.headers,
+            };
+
+            // Apply response interceptors
+            for (const i of this.interceptors) {
+                if (i.response) response = await i.response(response);
+            }
+
+            this.pending.delete(requestKey);
+
+            if (!raw.ok) {
+                throw Object.assign(new Error(`HTTP ${raw.status} ${raw.statusText}`), { response });
+            }
+
+            return response;
+        } catch (err) {
+            this.pending.delete(requestKey);
+
+            let error = err as Error;
+            for (const i of this.interceptors) {
+                if (i.error) error = await i.error(error);
+            }
+
+            if (error.name === 'AbortError') {
+                throw new Error('Request cancelled');
+            }
+            throw error;
+        }
+    }
+
+    // ─── Convenience ────────────────────────────────────────────
+
+    get<T = any>(url: string, params?: any, options?: HttpRequestConfig) {
+        return this.request<T>('GET', url, params, options);
+    }
+
+    post<T = any>(url: string, data?: any, options?: HttpRequestConfig) {
+        return this.request<T>('POST', url, data, options);
+    }
+
+    put<T = any>(url: string, data?: any, options?: HttpRequestConfig) {
+        return this.request<T>('PUT', url, data, options);
+    }
+
+    patch<T = any>(url: string, data?: any, options?: HttpRequestConfig) {
+        return this.request<T>('PATCH', url, data, options);
+    }
+
+    delete<T = any>(url: string, options?: HttpRequestConfig) {
+        return this.request<T>('DELETE', url, null, options);
+    }
+
+    // ─── Cancellation ───────────────────────────────────────────
+
+    /** Cancel all pending requests */
+    cancelAll(): void {
+        this.pending.forEach((c) => c.abort());
+        this.pending.clear();
+    }
+
+    /** Cancel a specific pending request */
+    cancel(url: string, method: string = 'GET'): void {
+        const key = `${method.toUpperCase()}:${url}`;
+        this.pending.get(key)?.abort();
+        this.pending.delete(key);
+    }
+
+    /** Destroy — cancel all + clear interceptors */
+    destroy(): void {
+        this.cancelAll();
+        this.interceptors = [];
+    }
+}

package/src/core/services/LoggerService.ts

@@ -0,0 +1,139 @@
+/**
+ * LoggerService — Configurable console logger with log history.
+ *
+ * Features:
+ *   - Log levels: debug < info < warn < error
+ *   - Enable/disable toggle
+ *   - Stored log history (for debug tools, remote reporting)
+ *   - Prefix formatting
+ *
+ * Register via DI:
+ *   app.singleton('logger', () => new LoggerService({ level: 'info', enabled: true }));
+ */
+
+// ─── Types ──────────────────────────────────────────────────────
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+
+export interface LoggerConfig {
+    /** Minimum log level to output (default: 'info') */
+    level?: LogLevel;
+    /** Enable/disable console output (default: true) */
+    enabled?: boolean;
+    /** Prefix for all log messages (default: '') */
+    prefix?: string;
+    /** Max history entries (0 = unlimited, default: 500) */
+    maxHistory?: number;
+}
+
+interface LogEntry {
+    level: LogLevel;
+    timestamp: number;
+    args: any[];
+}
+
+// ─── Log Level Priority ─────────────────────────────────────────
+
+const LEVEL_PRIORITY: Record<LogLevel, number> = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+
+// ─── LoggerService ──────────────────────────────────────────────
+
+export class LoggerService {
+    private config: Required<LoggerConfig>;
+    private history: LogEntry[] = [];
+
+    constructor(config: LoggerConfig = {}) {
+        this.config = {
+            level: config.level ?? 'info',
+            enabled: config.enabled ?? true,
+            prefix: config.prefix ?? '',
+            maxHistory: config.maxHistory ?? 500,
+        };
+    }
+
+    // ─── Config ─────────────────────────────────────────────────
+
+    setConfig(config: Partial<LoggerConfig>): void {
+        Object.assign(this.config, config);
+    }
+
+    getConfig(): Readonly<Required<LoggerConfig>> {
+        return this.config;
+    }
+
+    enable(): void { this.config.enabled = true; }
+    disable(): void { this.config.enabled = false; }
+
+    setLevel(level: LogLevel): void { this.config.level = level; }
+    setPrefix(prefix: string): void { this.config.prefix = prefix; }
+
+    // ─── Log Methods ────────────────────────────────────────────
+
+    debug(...args: any[]): void { this.write('debug', args); }
+    info(...args: any[]): void { this.write('info', args); }
+    log(...args: any[]): void { this.write('info', args); }
+    warn(...args: any[]): void { this.write('warn', args); }
+    error(...args: any[]): void { this.write('error', args); }
+
+    // ─── History ────────────────────────────────────────────────
+
+    /** Get all stored log entries */
+    getHistory(): readonly LogEntry[] {
+        return this.history;
+    }
+
+    /** Get history filtered by level */
+    getHistoryByLevel(level: LogLevel): LogEntry[] {
+        return this.history.filter((e) => e.level === level);
+    }
+
+    /** Clear log history */
+    clearHistory(): void {
+        this.history = [];
+    }
+
+    // ─── Lifecycle ──────────────────────────────────────────────
+
+    destroy(): void {
+        this.history = [];
+    }
+
+    // ─── Private ────────────────────────────────────────────────
+
+    private write(level: LogLevel, args: any[]): void {
+        // Always store in history
+        this.addToHistory(level, args);
+
+        // Check if should output to console
+        if (!this.config.enabled) return;
+        if (LEVEL_PRIORITY[level] < LEVEL_PRIORITY[this.config.level]) return;
+
+        const prefix = this.config.prefix ? `[${this.config.prefix}]` : '';
+        const method = level === 'debug' ? 'debug' : level === 'info' ? 'log' : level;
+
+        if (prefix) {
+            (console as any)[method](prefix, ...args);
+        } else {
+            (console as any)[method](...args);
+        }
+    }
+
+    private addToHistory(level: LogLevel, args: any[]): void {
+        this.history.push({ level, timestamp: Date.now(), args });
+
+        // Trim if over max
+        if (this.config.maxHistory > 0 && this.history.length > this.config.maxHistory) {
+            this.history = this.history.slice(-this.config.maxHistory);
+        }
+    }
+}
+
+
+export const logger = new LoggerService();
+export default logger;

package/src/core/services/MarkerRegistry.ts

@@ -0,0 +1,239 @@
+/**
+ * MarkerRegistry — singleton service that manages DOM comment marker metadata.
+ * 
+ * In the new element-based system, Reactive/Block/Fragment all use 
+ * comment nodes (<!--reactive-start-->, <!--block:content-end-->) as markers.
+ * 
+ * MarkerRegistry provides:
+ *   1. Tag shortcuts: 'reactive' → 'r', 'block' → 'b', etc.
+ *      → Keeps DOM comments short: <!--r:abc123--> instead of <!--reactive:abc123-->
+ *   2. Registry records: maps marker IDs to metadata (tag type, attributes, owner viewId, etc.)
+ *      → Enables lookup: given a comment node, find what element/view it belongs to
+ *   3. Query API: find records by tag, by viewId, by custom attributes
+ * 
+ * Used by:
+ *   - Reactive, Block, Fragment — to register their markers on creation
+ *   - ViewController — to query/manage markers for its view
+ *   - Compiler — to know tag shortcut mappings for generated code
+ *   - DevTools (future) — to inspect/debug the element tree via markers
+ */
+
+import { MarkerRegistryRecord } from "../contracts/MarkerInterface";
+
+
+export class MarkerRegistryService {
+    static class: string = 'MarkerRegistryService';
+    /** Tag name → short abbreviation (for compact DOM comments) */
+    private shortcuts: Record<string, string> = {
+        view:         'v',
+        component:    'c',
+        layout:       'l',
+        template:     't',
+        block:        'b',
+        reactive:     'r',
+        section:      's',
+        fragment:     'frg',
+        blockoutlet:  'bo',
+        for:          'fo',
+        forin:        'fi',
+        foreach:      'fe',
+        while:        'wh',
+        if:           'if',
+        switch:       'sw',
+        include:      'inc',
+        echo:         'e',
+        echoescaped:  'ee',
+        yield:        'y',
+        slot:         'st',
+        useblock:     'ub',
+        extend:       'ex',
+        style:        'sty',
+        script:       'sc',
+    };
+
+    /** Reverse lookup: shortcut → full tag name */
+    private reverseShortcuts: Record<string, string> = {};
+
+    /** All registered marker records, keyed by composite key (e.g. 'r:abc123') */
+    private records: Map<string, MarkerRegistryRecord> = new Map();
+
+    /** Delimiter between tag shortcut and ID in keys */
+    private delimiter: string = ':';
+
+    /** Auto-increment counter for generating unique IDs */
+    private counter: number = 0;
+
+    constructor() {
+        this.buildReverseShortcuts();
+    }
+
+    // ─── Tag Shortcuts ──────────────────────────────────────────
+
+    /** Get short abbreviation for a tag name */
+    shortcut(tag: string): string {
+        return this.shortcuts[tag] ?? tag;
+    }
+
+    /** Get full tag name from a shortcut */
+    fullTag(shortcut: string): string {
+        return this.reverseShortcuts[shortcut] ?? shortcut;
+    }
+
+    /** Register a custom tag shortcut */
+    registerShortcut(tag: string, short: string): void {
+        this.shortcuts[tag] = short;
+        this.reverseShortcuts[short] = tag;
+    }
+
+    // ─── Record Management ──────────────────────────────────────
+
+    /**
+     * Register a marker record.
+     * 
+     * @param tag        Full tag name (e.g. 'reactive', 'block')
+     * @param id         Optional specific ID. Auto-generated if omitted.
+     * @param attributes Optional metadata.
+     * @returns The composite key (e.g. 'r:m0')
+     */
+    register(tag: string, id?: string, attributes: Record<string, any> = {}): string {
+        const resolvedId = id ?? this.generateId();
+        const key = this.makeKey(tag, resolvedId);
+
+        const existing = this.records.get(key);
+        if (existing) {
+            existing.attributes = { ...existing.attributes, ...attributes };
+            return key;
+        }
+
+        this.records.set(key, {
+            tag,
+            registryID: resolvedId,
+            attributes,
+        });
+
+        return key;
+    }
+
+    /** Register + create the opening Comment node */
+    createMarkerStart(tag: string, id?: string): Comment {
+        return document.createComment(this.openComment(tag, id ?? ''));
+    }
+
+    createMarkerEnd(tag: string, id?: string): Comment {
+        return document.createComment(this.closeComment(tag, id));
+    }
+
+
+    /** Get a record by composite key (e.g. 'r:abc123') */
+    get(key: string): MarkerRegistryRecord | null {
+        return this.records.get(key) ?? null;
+    }
+
+    /** Get a record by tag + id */
+    getByTagAndId(tag: string, id: string): MarkerRegistryRecord | null {
+        return this.records.get(this.makeKey(tag, id)) ?? null;
+    }
+
+    /** Check if a record exists */
+    has(key: string): boolean {
+        return this.records.has(key);
+    }
+
+    /** Remove a record */
+    remove(key: string): boolean {
+        return this.records.delete(key);
+    }
+
+    /** Get all records for a specific tag type */
+    getByTag(tag: string): MarkerRegistryRecord[] {
+        const short = this.shortcut(tag);
+        const results: MarkerRegistryRecord[] = [];
+        for (const [key, record] of this.records) {
+            if (key.startsWith(short + this.delimiter) || record.tag === tag) {
+                results.push(record);
+            }
+        }
+        return results;
+    }
+
+    /** Get all records */
+    all(): Map<string, MarkerRegistryRecord> {
+        return this.records;
+    }
+
+    /** Clear all records */
+    clear(): void {
+        this.records.clear();
+        this.counter = 0;
+    }
+
+    /** Total number of registered markers */
+    get size(): number {
+        return this.records.size;
+    }
+
+    // ─── Comment Node Helpers ───────────────────────────────────
+
+    /**
+     * Create a comment string for a marker (open).
+     * e.g. 'r:abc123' for <!--r:abc123-->
+     */
+    openComment(tag: string, id?: string): string {
+        return `${this.shortcut(tag)}${id ? this.delimiter + id : ''}`;
+    }
+
+    /**
+     * Create a comment string for a closing marker.
+     * e.g. '/r:abc123' for <!--/r:abc123-->
+     */
+    closeComment(tag: string, id?: string): string {
+        return `/${this.shortcut(tag)}${id ? this.delimiter + id : ''}`;
+    }
+
+    /**
+     * Parse a comment node's text to extract tag and id.
+     * '  r:abc123  ' → { tag: 'reactive', id: 'abc123', isClose: false }
+     * ' /r:abc123 '  → { tag: 'reactive', id: 'abc123', isClose: true }
+     */
+    parseComment(text: string): { tag: string; id: string; isClose: boolean } | null {
+        const trimmed = text.trim();
+        if (!trimmed) return null;
+
+        const isClose = trimmed.startsWith('/');
+        const content = isClose ? trimmed.slice(1) : trimmed;
+        const delimIdx = content.indexOf(this.delimiter);
+
+        if (delimIdx === -1) return null;
+
+        const shortTag = content.slice(0, delimIdx);
+        const id = content.slice(delimIdx + 1);
+
+        return {
+            tag: this.fullTag(shortTag),
+            id,
+            isClose,
+        };
+    }
+
+    // ─── Private ────────────────────────────────────────────────
+
+    private makeKey(tag: string, id?: string): string {
+        return `${this.shortcut(tag)}${id ? this.delimiter + id : ''}`;
+    }
+
+    private generateId(): string {
+        return `m${(this.counter++).toString(36)}`;
+    }
+
+    private buildReverseShortcuts(): void {
+        this.reverseShortcuts = {};
+        for (const [tag, short] of Object.entries(this.shortcuts)) {
+            this.reverseShortcuts[short] = tag;
+        }
+    }
+}
+
+// ─── Singleton ──────────────────────────────────────────────────
+
+export const MarkerRegistry = new MarkerRegistryService();
+export default MarkerRegistry;