Kiến Trúc

Mọi lời gọi đi theo một đường: client → source → transport → nguồn dữ liệu, còn phần tính toán là hàm thuần nằm riêng.

Client

vn là client mặc định; createClient() tạo client riêng với cấu hình của bạn. Handle như vn.stock('FPT') được tạo đồng bộ và không gọi mạng; lần dùng đầu mới kiểm tra mã có trong danh mục.

import { createClient } from "vnstock-js";

const vn = createClient({
  proxy: "/api/vnstock", // chỉ cần trên trình duyệt
  timeout: 10000,
  retries: 2,
  preload: true,         // tải sẵn danh mục mã và lịch nghỉ
});

Source

Source VCI gọi API của VietCap và đổi kết quả sang dạng chung của thư viện: Bar cho nến, Quote cho bảng giá, mọi số tiền về đồng, thời gian về giờ Việt Nam.

Transport

Transport bọc fetch có sẵn của môi trường:

• Thử lại với backoff khi lỗi mạng, timeout hoặc lỗi 5xx.
• Nhận diện bị giới hạn tần suất (HTTP 429) và trang chặn của Cloudflare, báo lỗi rõ ràng thay vì trả dữ liệu rác.
• Khi client có proxy, viết lại URL sang proxy của bạn.

Header phiên của VietCap chỉ được gắn phía server; trình duyệt luôn đi qua proxy.

Storage

Danh mục mã, lịch nghỉ và tỷ số quý được tải lười từ GitHub ở lần dùng đầu, rồi cache trong một Storage:

interface Storage {
  get(key: string): Promise<string | null>;
  set(key: string, value: string): Promise<void>;
  remove(key: string): Promise<void>;
}

memoryStorage() là mặc định. fileStorage() của vnstock-js/node lưu ở ~/.vnstock-js giữa các lần chạy. Trên trình duyệt có thể tự viết một Storage trên IndexedDB. Danh mục đầu tư (vn.portfolio.save()) và lịch sử khối ngoại cũng đi qua Storage.

Core không dùng fs, nên chạy được trên serverless và edge mà không cần cấu hình gì.

Compute và indicators

Gộp nến, chỉ báo, pattern, định giá danh mục, backtest và tìm phiên tương tự là hàm thuần trên Bar[], không gọi mạng. Chỉ báo được xuất riêng ở vnstock-js/indicators nên dùng được cả trong trình duyệt.

Realtime

watch() dùng chung một kết nối WebSocket tới SSI cho mọi watcher của một client, tự kết nối lại khi rớt. Ở chế độ poll, nó hỏi bảng giá định kỳ thay vì giữ WebSocket.

Lịch sử khối ngoại

VietCap chỉ cho xem khối ngoại của phiên hiện tại. Repo vnstock-js có một workflow chạy mỗi ngày sau 15:30, ghi lại khối ngoại của từng mã vào data/foreign và gộp theo tháng. foreign('3mo') đọc các file tháng này qua raw GitHub và cache trong Storage.