Lịch Sử Phiên Bản

1.3.1

Bản vá cho CLI sau khi release 1.3.0.

Sửa

• history --range 7d giờ trả đúng ~7 phiên (trước đây trả ~365 phiên do VCI API bỏ qua start khi countBack mặc định lớn). Handler tự tính countBack theo khoảng ngày và filter lại kết quả.
• Hiển thị giá: làm tròn tối đa 2 chữ số thập phân, cắt số 0 cuối. Không còn 56.291760000000004k.
• symbols --exchange HOSE giờ hoạt động (trước đây trả rỗng vì data lưu HSX). Directory.getByExchange tự map HOSE → HSX.
• symbols mặc định trả đầy đủ (trước đây tự cắt ở 50). --limit N chỉ áp dụng khi user chỉ định.
• vnstock -v cho --version (trước đây dùng -V hoa mặc định của commander). Version đọc từ package.json thay vì hardcode. --verbose ở sub-command bỏ alias -v để tránh xung đột.

Thêm

• Header cho history và symbols: ví dụ VCB 2026-04-07 → 2026-04-14 (5 phiên) và HOSE (702 mã).
• docs/local-test.md — hướng dẫn npm link, watch mode, npm pack, debug CLI trước khi release.
• npm run dev — tsc --watch để auto rebuild khi sửa code.

1.3.0

Breaking

• await init() bắt buộc trước khi dùng symbol lookup hoặc calendar API. Symbol và holiday data không còn bundle trong package — fetch runtime từ raw GitHub để luôn mới.

  import { init } from "vnstock-js";
  
  await init();   // gọi 1 lần lúc khởi động app
  

  init() nhận options: symbolsUrl, holidaysUrl, ttl, force, cacheDir, noCache, timeout.

Tính năng mới

• Remote data module — symbols/holidays fetch từ raw.githubusercontent.com/ttqteo/vnstock-js/master/data/*.json
• Disk cache tại ~/.vnstock-js/cache/, TTL mặc định 24h
• Offline fallback — fetch fail thì dùng cache cũ
• NotInitializedError và DataUnavailableError error types
• CLI tool — cài npm i -g vnstock-js hoặc npx vnstock-js <command>:
  • vnstock quote <SYMBOL> — snapshot 1 mã
  • vnstock history <SYMBOL> [--from 7d|1w|1m|1y] [--range 7d] [--limit N] — OHLCV
  • vnstock search <QUERY> — tìm mã theo tên/ticker
  • vnstock symbols [--exchange HOSE|HNX|UPCOM] — liệt kê mã
  • Flags chung: --json, --csv, --no-color, -v, --verbose. Non-TTY auto plain text.

Realtime hardening

• Sửa: unsubscribe() giờ gửi unsub message cho server. Message routing phân biệt quote/JSON/plain text. Loại bỏ WebSocket ping() vô nghĩa (browser không còn reset oan ~40s).
• Dead-man's switch thay heartbeat: reconnect nếu không nhận message nào trong deadManTimeout (mặc định 60s).
• Breaking (minor): bỏ RealtimeClientOptions.heartbeatInterval và heartbeatTimeout, thay bằng deadManTimeout?: number.

Thay đổi

• data/*.json không còn bundle trong npm package.

1.2.0 (03-04-2026)

Tính năng mới

• Symbol Directory -- danh sách ~3300 mã offline với search theo tên/mã/ngành, relevance ranking, VN30 boost
• Market Calendar -- isTradeDay, nextTradeDay, prevTradeDay, holidays, giờ giao dịch sàn HOSE
• Rate limit auto-wait -- gặp HTTP 429 tự động chờ theo Retry-After header rồi retry

API mới

• stock.search(query, { limit }) -- tìm mã cổ phiếu offline
• listing.search(), listing.getBySymbol(), listing.getByExchange(), listing.getByIndustry(), listing.allLocal()
• market.calendar.isTradeDay(date), nextTradeDay(date), prevTradeDay(date), holidays(year), session()

Nội bộ

• fetchWithRetry hỗ trợ rateLimitWait option (mặc định 5s)
• Thêm SymbolInfo, TradingSession types
• Thêm script npm run update-symbols
• Bundle data/symbols.json và data/holidays.json trong npm package

1.1.0 (03-04-2026)

Tính năng mới

• Error taxonomy -- 6 custom error classes: VnstockError, NetworkError, RateLimitError, ApiError, InvalidSymbolError, InvalidParameterError, ParseError
• Realtime v2 -- RealtimeClient dùng EventEmitter pattern, auto-reconnect với exponential backoff, heartbeat, subscribe queue
• Adapter pattern -- StockDataAdapter interface + VciAdapter, chuẩn bị cho multi-source sau này
• FinancialStatement typing -- thêm 7 optional typed fields (revenue, grossProfit, netIncome, totalAssets, totalEquity, totalDebt, operatingCashFlow)

Thay đổi breaking

• Realtime API cũ (VnstockRealtime.connect/subscribe/parseData) thay bằng realtime.create() + RealtimeClient event emitter
• realtime giờ là top-level export, không còn trên Vnstock class hay stock object

Nội bộ

• Pipeline fetchWithRetry wrap axios errors thành custom error classes
• Tất cả validation dùng InvalidParameterError thay vì throw new Error
• Core modules (quote, trading, listing, financial, company) gọi qua adapter thay vì trực tiếp URL

1.0.1 (02-04-2026)

• Xóa dependency xlsx (2 CVE: Prototype Pollution + ReDoS)
• Chuyển sang VCB JSON API thay vì parse Excel
• Sửa RSI type signature (period giờ optional)
• Thêm request timeout 15 giây
• Bổ sung fields thiếu trong ScreenResult
• Bỏ duplicate QuoteHistory type
• Sửa mapping index WebSocket SSI realtime data

1.0.0 (02-04-2026)

Breaking changes so với v0.5.x. Refactor toàn bộ kiến trúc.

Kiến trúc mới

• Pipeline architecture -- Request Pipeline (fetch + retry) -> Transform Pipeline (parse, clean, rename, normalize, shape)
• Tất cả output chuẩn hóa: Array of Objects, camelCase, giá chia 1000, ISO dates
• Retry tự động 2 lần với exponential backoff cho lỗi 5xx/timeout

Tính năng mới

• Sàng lọc cổ phiếu (stock.screening) -- lọc theo PE, ROE, vốn hóa
• Chỉ báo kỹ thuật -- SMA, EMA, RSI (pure functions)
• Company mở rộng -- affiliates, analysisReports, insiderDeals
• TypeScript interfaces đầy đủ cho tất cả output

Thay đổi breaking

• Output format thay đổi hoàn toàn (giá chia 1000, field names đổi)
• stock.price() -> stock.quote()
• stock.company() giờ là factory method trả về Company instance
• VnstockTypes trỏ sang normalized types
• Realtime parseData() trả về RealtimeQuote với field names mới

0.5.1

• Sửa lỗi nhỏ

0.5.0

• Thêm realtime WebSocket từ SSI
• Đổi stock.price -> stock.quote
• Thêm trading.topGainers, trading.topLosers

0.4.x

• Thêm giá vàng SJC
• Sửa lỗi Company
• Tái cấu trúc codebase

0.3.x

• Bỏ hỗ trợ TCBS
• Thêm giá vàng GiaVang.net

0.2.0

• Hỗ trợ VCI: listing, báo cáo tài chính
• Thêm tỷ giá VCB

0.1.0

• Phiên bản đầu tiên
• Giá giao dịch, lịch sử giá từ VCI và TCBS
• Giá vàng Việt Nam