@saolabs/client 1.0.0 → 1.0.2

package/src/core/services/HttpService.ts

@@ -20,6 +20,10 @@
 export interface HttpRequestConfig extends RequestInit {
     headers?: Record<string, string>;
     timeout?: number;
+    /** Default: cancel only an identical method + final URL. */
+    dedupe?: 'cancel-previous' | 'parallel';
+    /** Explicit logical identity, e.g. latest search across different queries. */
+    requestKey?: string;
     [key: string]: any;
 }
 
@@ -57,7 +61,8 @@ export class HttpService {
     private timeout: number = 10000;
     private defaultHeaders: Record<string, string> = {};
     private interceptors: HttpInterceptor[] = [];
-    private pending = new Map<string, AbortController>();
+    private pending = new Map<string, Set<AbortController>>();
+    private activeRequests = new Set<AbortController>();
 
     // ─── Config ─────────────────────────────────────────────────
 
@@ -103,58 +108,84 @@ export class HttpService {
         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,
+        this.activeRequests.add(controller);
+        const detach: (() => void)[] = [];
+        const linked = new Set<AbortSignal>();
+        const linkSignal = (signal?: AbortSignal | null) => {
+            if (!signal || signal === controller.signal || linked.has(signal)) return;
+            linked.add(signal);
+            const abort = () => controller.abort(signal.reason);
+            if (signal.aborted) abort();
+            else {
+                signal.addEventListener('abort', abort, { once: true });
+                detach.push(() => signal.removeEventListener('abort', abort));
+            }
         };
-
-        // 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;
+        linkSignal(options.signal);
+        let requestKey: string | undefined;
+        const timeoutId = setTimeout(() => controller.abort(), options.timeout ?? this.timeout);
+        try {
+            let config: HttpRequestConfig = {
+                ...options,
+                method: (options.method ?? method).toUpperCase(),
+                headers: { ...this.defaultHeaders, ...options.headers },
+                signal: controller.signal,
+            };
+            if (typeof window !== 'undefined') {
+                const revision = (window as any).APP_CONFIGS?.view?.revision;
+                const headers = config.headers as Record<string, string>;
+                if (typeof revision === 'string' && !headers['X-Saola-View-Revision']) {
+                    headers['X-Saola-View-Revision'] = revision;
+                    headers['X-Sao-Response'] ??= 'json';
+                }
             }
-        }
-
-        // 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));
+            controller.signal.throwIfAborted();
+            for (const i of this.interceptors) {
+                if (i.request) config = await i.request(config);
+                linkSignal(config.signal);
+                config.signal = controller.signal;
+                controller.signal.throwIfAborted();
             }
-            fullUrl = urlObj.toString();
-        }
-
-        try {
-            const timeoutId = setTimeout(() => controller.abort(), options.timeout ?? this.timeout);
+            config.method = (config.method ?? method).toUpperCase();
+            if (data !== null && ['POST', 'PUT', 'PATCH'].includes(config.method)) {
+                const ct = config.headers?.['Content-Type'];
+                if (data instanceof FormData) {
+                    config.body = data;
+                    if (config.headers) delete config.headers['Content-Type'];
+                } else if (ct === 'application/json' || !ct) {
+                    config.headers ??= {};
+                    config.headers['Content-Type'] = 'application/json';
+                    config.body = JSON.stringify(data);
+                } else config.body = data;
+            }
+            const urlObj = this.resolveUrl(url);
+            if (data && config.method === 'GET' && typeof data === 'object') {
+                for (const [key, value] of Object.entries(data)) urlObj.searchParams.append(key, String(value));
+            }
+            const fullUrl = urlObj.toString();
+            requestKey = `${config.method}:${config.requestKey ?? fullUrl}`;
+            let group = this.pending.get(requestKey);
+            if (config.dedupe !== 'parallel') {
+                for (const previous of group ?? []) previous.abort();
+            }
+            if (!group) this.pending.set(requestKey, group = new Set());
+            group.add(controller);
             const raw = await fetch(fullUrl, config);
-            clearTimeout(timeoutId);
-
             const responseData = await raw.json().catch(() => ({}));
+            controller.signal.throwIfAborted();
+
+            const viewContext = responseData?.viewContext;
+            const currentContext = typeof window !== 'undefined'
+                ? (window as any).APP_CONFIGS?.view?.systemData?.__context__
+                : null;
+            if (viewContext?.changed === true
+                && (!currentContext || viewContext.context === currentContext)
+                && typeof window !== 'undefined') {
+                window.dispatchEvent(new CustomEvent('saola:view-context', {
+                    detail: viewContext,
+                }));
+            }
 
             let response: HttpResponse<T> = {
                 status: raw.ok,
@@ -168,25 +199,43 @@ export class HttpService {
                 if (i.response) response = await i.response(response);
             }
 
-            this.pending.delete(requestKey);
+            controller.signal.throwIfAborted();
 
             if (!raw.ok) {
-                throw Object.assign(new Error(`HTTP ${raw.status} ${raw.statusText}`), { response });
+                // Ưu tiên message của server (Laravel 422 trả "The email field is
+                // required."): caller nào cũng in `err.message`, mà "HTTP 422
+                // Unprocessable Content" thì người dùng không biết sai ở đâu.
+                // Body đầy đủ (kèm `errors` từng field) vẫn nằm ở `err.response`.
+                const serverMessage = typeof (responseData as any)?.message === 'string'
+                    ? (responseData as any).message.trim()
+                    : '';
+                const message = serverMessage !== ''
+                    ? serverMessage
+                    : `HTTP ${raw.status} ${raw.statusText}`;
+                throw Object.assign(new Error(message), { 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');
+            if (controller.signal.aborted || error.name === 'AbortError') {
+                throw Object.assign(new Error('Request cancelled'), { name: 'AbortError', cause: error });
             }
             throw error;
+        } finally {
+            clearTimeout(timeoutId);
+            for (const off of detach) off();
+            this.activeRequests.delete(controller);
+            if (requestKey !== undefined) {
+                const group = this.pending.get(requestKey);
+                group?.delete(controller);
+                if (group?.size === 0) this.pending.delete(requestKey);
+            }
         }
     }
 
@@ -216,17 +265,29 @@ export class HttpService {
 
     /** Cancel all pending requests */
     cancelAll(): void {
-        this.pending.forEach((c) => c.abort());
+        for (const controller of this.activeRequests) controller.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.cancelKey(this.resolveUrl(url).toString(), method);
+    }
+
+    /** Cancel a logical requestKey (all parallel requests in the group). */
+    cancelKey(identity: string, method: string = 'GET'): void {
+        const key = `${method.toUpperCase()}:${identity}`;
+        for (const controller of this.pending.get(key) ?? []) controller.abort();
         this.pending.delete(key);
     }
 
+    private resolveUrl(url: string): URL {
+        const full = /^(https?:)?\/\//i.test(url) ? url : `${this.baseUrl}${url}`;
+        const resolved = new URL(full, typeof window !== 'undefined' ? window.location.origin : 'http://localhost');
+        resolved.hash = ''; // fragments are never sent to the server
+        return resolved;
+    }
+
     /** Destroy — cancel all + clear interceptors */
     destroy(): void {
         this.cancelAll();

package/src/core/services/MarkerRegistry.ts

@@ -18,12 +18,16 @@
  *   - DevTools (future) — to inspect/debug the element tree via markers
  */
 
-import { MarkerRegistryRecord } from "../contracts/MarkerInterface";
+import { MarkerRegistryInterface, MarkerRegistryRecord } from "../contracts/MarkerInterface.js";
 
 
-export class MarkerRegistryService {
+export class MarkerRegistryService implements MarkerRegistryInterface {
     static class: string = 'MarkerRegistryService';
-    /** Tag name → short abbreviation (for compact DOM comments) */
+    /**
+     * Tag name → short abbreviation (for compact DOM comments).
+     * PHẢI khớp 1-1 với server core/ViewStorageManager::$markerTagShortcut —
+     * lệch shortcut nào thì marker loại đó không claim được khi hydrate.
+     */
     private shortcuts: Record<string, string> = {
         view:         'v',
         component:    'c',
@@ -34,9 +38,12 @@ export class MarkerRegistryService {
         section:      's',
         fragment:     'frg',
         blockoutlet:  'bo',
+        output:       'o',
         for:          'fo',
         forin:        'fi',
         foreach:      'fe',
+        forelse:      'fls',
+        each:         'ea',
         while:        'wh',
         if:           'if',
         switch:       'sw',
@@ -60,6 +67,17 @@ export class MarkerRegistryService {
     /** Delimiter between tag shortcut and ID in keys */
     private delimiter: string = ':';
 
+    /**
+     * Saola marker prefix — format chuẩn (RUNTIME_CONTRACT.md §5.1):
+     *   open:  <!--s:{type}:{id}-s-->
+     *   close: <!--s:{type}:{id}-e-->
+     * Phải khớp server (core ViewStorageManager) để hydration claim đúng.
+     */
+    private prefix: string = 's';
+    /** Hậu tố đánh dấu open/close marker */
+    private openSuffix: string = '-s';
+    private closeSuffix: string = '-e';
+
     /** Auto-increment counter for generating unique IDs */
     private counter: number = 0;
 
@@ -165,6 +183,7 @@ export class MarkerRegistryService {
     clear(): void {
         this.records.clear();
         this.counter = 0;
+        this.index = null;
     }
 
     /** Total number of registered markers */
@@ -172,41 +191,148 @@ export class MarkerRegistryService {
         return this.records.size;
     }
 
+    // ─── Marker Index (O(1) claim khi hydrate) ──────────────────
+
+    /**
+     * Index text-comment → Comment node, dựng 1 lần cho mỗi lượt hydrate.
+     *
+     * Trước đây mỗi element (Reactive/Output/Component/Wrapper/BlockOutlet/Block)
+     * tự tạo TreeWalker quét toàn bộ comment trong parent để tìm đúng 2 chuỗi →
+     * O(số element × số comment). Với 400 row × 5 cột (~4000 marker) đo được
+     * ~210ms chỉ để claim. Index 1 lượt rồi Map.get đưa về O(N) tổng, ~1.5ms.
+     *
+     * null = chưa dựng (lazy — CSR không bao giờ chạm tới).
+     */
+    private index: Map<string, Comment> | null = null;
+
+    /** Đã dựng lại index vì miss trong lượt microtask hiện tại chưa? */
+    private rebuiltOnMiss: boolean = false;
+
+    /** Bỏ index — gọi khi có HTML server MỚI vào DOM (đầu mỗi lượt hydrate). */
+    invalidateIndex(): void {
+        this.index = null;
+    }
+
+    private buildIndex(): Map<string, Comment> {
+        const idx = new Map<string, Comment>();
+        const root = document.body ?? document.documentElement;
+        if (root) {
+            const head = this.prefix + this.delimiter; // "s:"
+            const walker = document.createTreeWalker(root, NodeFilter.SHOW_COMMENT);
+            let node: Comment | null;
+            while ((node = walker.nextNode() as Comment | null)) {
+                const value = (node.nodeValue ?? '').trim();
+                // Giữ node ĐẦU TIÊN theo document order — đúng thứ tự mà
+                // TreeWalker scan cũ trả về.
+                if (value.startsWith(head) && !idx.has(value)) idx.set(value, node);
+            }
+        }
+        this.index = idx;
+        return idx;
+    }
+
+    /**
+     * Claim cặp marker SSR `<!--s:{tag}:{id}-s-->` … `<!--s:{tag}:{id}-e-->`.
+     *
+     * @param scope Nếu truyền, cặp tìm được PHẢI nằm trong scope — không thì
+     *              rơi về scan tuyến tính trong scope (giữ nguyên ngữ nghĩa cũ).
+     * @returns null khi server không render vùng này (partial hydration).
+     */
+    claim(tag: string, id: string, scope?: Element | null): { open: Comment; close: Comment } | null {
+        const openText = this.openComment(tag, id);
+        const closeText = this.closeComment(tag, id);
+
+        let idx = this.index ?? this.buildIndex();
+        let open = idx.get(openText);
+        let close = idx.get(closeText);
+
+        // Miss có HAI nguyên nhân: (a) server không render vùng này — partial
+        // hydration, hợp lệ; (b) index cũ vì HTML server mới vào DOM sau lần
+        // dựng. Không phân biệt được trong O(1), nên dựng lại TỐI ĐA MỘT LẦN
+        // mỗi lượt microtask: burst hydrate đồng bộ chỉ tốn thêm 1 lượt quét,
+        // còn 499 miss thật sau đó vẫn O(1) (không quay lại O(N²)).
+        // Node rời DOM cũng là dấu hiệu index cũ → xử lý cùng nhánh.
+        const stale = (open && !open.isConnected) || (close && !close.isConnected);
+        if (stale || ((!open || !close) && !this.rebuiltOnMiss)) {
+            this.rebuiltOnMiss = true;
+            queueMicrotask(() => { this.rebuiltOnMiss = false; });
+            idx = this.buildIndex();
+            open = idx.get(openText);
+            close = idx.get(closeText);
+        }
+
+        if (!open || !close || !open.isConnected || !close.isConnected) return null;
+
+        if (scope && !(scope.contains(open) && scope.contains(close))) {
+            return this.scanForPair(scope, openText, closeText);
+        }
+        return { open, close };
+    }
+
+    /** Fallback hiếm: quét tuyến tính trong scope (ngữ nghĩa scan cũ). */
+    private scanForPair(scope: Node, openText: string, closeText: string): { open: Comment; close: Comment } | null {
+        const walker = document.createTreeWalker(scope, NodeFilter.SHOW_COMMENT);
+        let openNode: Comment | null = null;
+        let node: Comment | null;
+        while ((node = walker.nextNode() as Comment | null)) {
+            const value = (node.nodeValue ?? '').trim();
+            if (!openNode && value === openText) { openNode = node; continue; }
+            if (openNode && value === closeText) return { open: openNode, close: node };
+        }
+        return null;
+    }
+
     // ─── Comment Node Helpers ───────────────────────────────────
 
     /**
      * Create a comment string for a marker (open).
-     * e.g. 'r:abc123' for <!--r:abc123-->
+     * Format chuẩn: 's:r:abc123-s' cho <!--s:r:abc123-s-->
      */
     openComment(tag: string, id?: string): string {
-        return `${this.shortcut(tag)}${id ? this.delimiter + id : ''}`;
+        const body = id ? `${this.shortcut(tag)}${this.delimiter}${id}` : this.shortcut(tag);
+        return `${this.prefix}${this.delimiter}${body}${this.openSuffix}`;
     }
 
     /**
      * Create a comment string for a closing marker.
-     * e.g. '/r:abc123' for <!--/r:abc123-->
+     * Format chuẩn: 's:r:abc123-e' cho <!--s:r:abc123-e-->
      */
     closeComment(tag: string, id?: string): string {
-        return `/${this.shortcut(tag)}${id ? this.delimiter + id : ''}`;
+        const body = id ? `${this.shortcut(tag)}${this.delimiter}${id}` : this.shortcut(tag);
+        return `${this.prefix}${this.delimiter}${body}${this.closeSuffix}`;
     }
 
     /**
-     * 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 }
+     * Parse a comment node's text to extract tag and id (format chuẩn §5.1).
+     * 's:r:abc123-s' → { tag: 'reactive', id: 'abc123', isClose: false }
+     * 's:r:abc123-e' → { 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);
+        const head = this.prefix + this.delimiter; // "s:"
+        if (!trimmed.startsWith(head)) return null;
+
+        let body = trimmed.slice(head.length); // "r:abc123-s"
+        let isClose: boolean;
+        if (body.endsWith(this.openSuffix)) {
+            isClose = false;
+            body = body.slice(0, -this.openSuffix.length);
+        } else if (body.endsWith(this.closeSuffix)) {
+            isClose = true;
+            body = body.slice(0, -this.closeSuffix.length);
+        } else {
+            return null;
+        }
 
-        if (delimIdx === -1) return null;
+        const delimIdx = body.indexOf(this.delimiter);
+        if (delimIdx === -1) {
+            return { tag: this.fullTag(body), id: '', isClose };
+        }
 
-        const shortTag = content.slice(0, delimIdx);
-        const id = content.slice(delimIdx + 1);
+        const shortTag = body.slice(0, delimIdx);
+        const id = body.slice(delimIdx + 1);
 
         return {
             tag: this.fullTag(shortTag),