@luonghaminhvy/songma-std 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luong Ha Minh Vy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# songma-std - Thư Viện Tiện Ích Mở Rộng Chuẩn SongMa
+
+Gói thư viện tiện ích chuẩn mở rộng cung cấp các công cụ thiết yếu: Ngày Tháng, Mã Hóa/UUID, Kiểm Tra Định Dạng Việt Nam và Xử Lý Bảng CSV cho ngôn ngữ lập trình SongMa (.smjs / .smts).
+
+---
+
+## Cài đặt & Sử dụng
+
+Trong tệp SongMa (`.smjs` / `.smts`):
+
+```vietlang
+dùng {
+    tinh_khoang_cach_ngay,
+    tao_uuid,
+    la_so_dien_thoai_vn,
+    la_email_hop_le,
+    doc_csv
+} từ "songma-std";
+
+// 1. Sinh UUID v4
+biến ma_dinh_danh = tao_uuid();
+in("UUID: " + ma_dinh_danh);
+
+// 2. Kiểm tra định dạng số điện thoại Việt Nam
+nếu (la_so_dien_thoai_vn("0912345678")) {
+    in("Số điện thoại hợp lệ!");
+}
+
+// 3. Đọc dữ liệu bảng CSV
+biến danh_sach = doc_csv("ten,gia\nAo thun,150000\nQuan jean,350000");
+in(danh_sach[0].ten); // "Ao thun"
+```
+
+---
+
+## Danh sách Modules
+
+- **`ngay_thang`**: Xử lý tính toán khoảng cách ngày, kiểm tra năm nhuận, lấy tên thứ trong tuần.
+- **`ma_hoa`**: Sinh UUID ngẫu nhiên v4, mã hóa và giải mã Base64 URL-safe.
+- **`kiem_tra`**: Kiểm tra số điện thoại di động Việt Nam, email, căn cước công dân (CCCD 12 số).
+- **`bang_du_lieu`**: Phân tích cú pháp chuỗi CSV thành mảng đối tượng và ngược lại.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@luonghaminhvy/songma-std",
+  "version": "0.5.0",
+  "description": "Thư viện Tiện ích Chuẩn Mở Rộng cho Hệ sinh thái Ngôn ngữ Lập trình SongMa (.smjs / .smts / .smjx / .smtx)",
+  "main": "src/index.sm",
+  "module": "src/index.sm",
+  "types": "src/index.d.ts",
+  "keywords": [
+    "songma",
+    "std",
+    "standard-library",
+    "vietnamese",
+    "utils",
+    "date-time",
+    "crypto",
+    "csv",
+    "validator"
+  ],
+  "author": "Luong Ha Minh Vy",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LuongHaMinhVy/SongMa.git"
+  },
+  "homepage": "https://github.com/LuongHaMinhVy/SongMa",
+  "scripts": {
+    "test": "sm test test/",
+    "check": "sm check src/"
+  }
+}

package/src/bang_du_lieu.sm

@@ -0,0 +1,61 @@
+// ========================================================
+// Module: Xử lý Bảng Dữ Liệu & Tệp Tin CSV (Table & CSV)
+// ========================================================
+
+// Phân tích chuỗi CSV thành mảng các đối tượng
+hàm doc_csv(chuoi_csv) {
+    nếu (!chuoi_csv) {
+        trả [];
+    }
+
+    biến cac_dong = tách(cắt_khoảng_trắng(chuoi_csv), "\n");
+    nếu (độ_dài(cac_dong) < 2) {
+        trả [];
+    }
+
+    biến tieu_de = tách(cắt_khoảng_trắng(cac_dong[0]), ",");
+    biến ket_qua = [];
+
+    lặp (biến i = 1; i < độ_dài(cac_dong); i++) {
+        biến dong = cắt_khoảng_trắng(cac_dong[i]);
+        nếu (độ_dài(dong) == 0) {
+            tiếp;
+        }
+
+        biến cac_cot = tách(dong, ",");
+        biến doi_tuong = {};
+
+        lặp (biến j = 0; j < độ_dài(tieu_de); j++) {
+            biến khoa = cắt_khoảng_trắng(tieu_de[j]);
+            biến gia_tri = (j < độ_dài(cac_cot)) ? cắt_khoảng_trắng(cac_cot[j]) : "";
+            doi_tuong[khoa] = gia_tri;
+        }
+
+        ket_qua.push(doi_tuong);
+    }
+
+    trả ket_qua;
+}
+
+// Chuyển danh sách đối tượng thành chuỗi CSV
+hàm tao_csv(danh_sach, danh_sach_cot) {
+    nếu (!danh_sach || độ_dài(danh_sach) == 0) {
+        trả "";
+    }
+
+    biến hang_dau = nối(danh_sach_cot, ",");
+    biến cac_hang = [hang_dau];
+
+    mỗi (item trong danh_sach) {
+        biến cac_gia_tri = [];
+        mỗi (cot trong danh_sach_cot) {
+            biến val = item[cot] ?? "";
+            cac_gia_tri.push(val);
+        }
+        cac_hang.push(nối(cac_gia_tri, ","));
+    }
+
+    trả nối(cac_hang, "\n");
+}
+
+xuất { doc_csv, tao_csv };

package/src/index.sm

@@ -0,0 +1,24 @@
+// ========================================================
+// Thư Viện Tiện Ích Mở Rộng Chuẩn SongMa Standard Library
+// ========================================================
+
+dùng { CAC_THU, tinh_khoang_cach_ngay, la_nam_nhuan, lay_ten_thu } từ "./ngay_thang.smjs";
+dùng { tao_uuid, ma_hoa_base64_url, giai_ma_base64_url } từ "./ma_hoa.smjs";
+dùng { la_so_dien_thoai_vn, la_email_hop_le, la_cccd_hop_le, la_chuoi_rong } từ "./kiem_tra.smjs";
+dùng { doc_csv, tao_csv } từ "./bang_du_lieu.smjs";
+
+xuất {
+    CAC_THU,
+    tinh_khoang_cach_ngay,
+    la_nam_nhuan,
+    lay_ten_thu,
+    tao_uuid,
+    ma_hoa_base64_url,
+    giai_ma_base64_url,
+    la_so_dien_thoai_vn,
+    la_email_hop_le,
+    la_cccd_hop_le,
+    la_chuoi_rong,
+    doc_csv,
+    tao_csv
+};

package/src/kiem_tra.sm

@@ -0,0 +1,77 @@
+// ========================================================
+// Module: Kiểm Tra Định Dạng Dữ Liệu Việt Nam (Validator)
+// ========================================================
+
+// Kiểm tra số điện thoại di động Việt Nam (10 số, đầu 03, 05, 07, 08, 09)
+hàm la_so_dien_thoai_vn(sdt) {
+    nếu (!sdt || độ_dài(sdt) != 10) {
+        trả sai;
+    }
+
+    biến hop_le = bắt_đầu_bằng(sdt, "03")
+        || bắt_đầu_bằng(sdt, "05")
+        || bắt_đầu_bằng(sdt, "07")
+        || bắt_đầu_bằng(sdt, "08")
+        || bắt_đầu_bằng(sdt, "09");
+
+    nếu (!hop_le) {
+        trả sai;
+    }
+
+    // Kiểm tra toàn bộ là chữ số
+    lặp (biến i = 0; i < 10; i++) {
+        biến ky_tu = cắt(sdt, i, i + 1);
+        nếu (ky_tu < "0" || ky_tu > "9") {
+            trả sai;
+        }
+    }
+
+    trả đúng;
+}
+
+// Kiểm tra định dạng email cơ bản
+hàm la_email_hop_le(email) {
+    nếu (!email || độ_dài(email) < 5) {
+        trả sai;
+    }
+
+    nếu (!chứa(email, "@") || !chứa(email, ".")) {
+        trả sai;
+    }
+
+    biến vi_tri_at = tìm(email, "@");
+    biến vi_tri_cham = tìm(email, ".");
+
+    nếu (vi_tri_at <= 0 || vi_tri_cham <= vi_tri_at + 1) {
+        trả sai;
+    }
+
+    trả đúng;
+}
+
+// Kiểm tra số Căn cước công dân (CCCD 12 chữ số)
+hàm la_cccd_hop_le(cccd) {
+    nếu (!cccd || độ_dài(cccd) != 12) {
+        trả sai;
+    }
+
+    lặp (biến i = 0; i < 12; i++) {
+        biến ky_tu = cắt(cccd, i, i + 1);
+        nếu (ky_tu < "0" || ky_tu > "9") {
+            trả sai;
+        }
+    }
+
+    trả đúng;
+}
+
+// Kiểm tra chuỗi rỗng
+hàm la_chuoi_rong(chuoi) {
+    nếu (!chuoi) {
+        trả đúng;
+    }
+    biến cat = cắt_khoảng_trắng(chuoi);
+    trả độ_dài(cat) == 0;
+}
+
+xuất { la_so_dien_thoai_vn, la_email_hop_le, la_cccd_hop_le, la_chuoi_rong };

package/src/ma_hoa.sm

@@ -0,0 +1,43 @@
+// ========================================================
+// Module: Mã Hóa, Băm Dữ Liệu & Tạo Định Danh Ngẫu Nhiên
+// ========================================================
+
+biến HEX_CHARS = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "a", "b", "c", "d", "e", "f"];
+
+hàm sinh_hex_ngau_nhien(do_dai) {
+    biến kq = "";
+    lặp (biến i = 0; i < do_dai; i++) {
+        biến idx = ngẫu_nhiên(0, 15);
+        kq = kq + HEX_CHARS[idx];
+    }
+    trả kq;
+}
+
+// Sinh chuỗi UUID phiên bản 4 chuẩn (VD: "f47ac10b-58cc-4372-a567-0e02b2c3d479")
+hàm tao_uuid() {
+    biến p1 = sinh_hex_ngau_nhien(8);
+    biến p2 = sinh_hex_ngau_nhien(4);
+    biến p3 = "4" + sinh_hex_ngau_nhien(3);
+    biến p4 = "a" + sinh_hex_ngau_nhien(3);
+    biến p5 = sinh_hex_ngau_nhien(12);
+
+    trả p1 + "-" + p2 + "-" + p3 + "-" + p4 + "-" + p5;
+}
+
+// Mã hóa Base64 an toàn cho URL (URL-safe Base64)
+hàm ma_hoa_base64_url(chuoi) {
+    biến goc = mã_hóa_base64(chuoi);
+    biến b1 = thay_thế_tất_cả(goc, "+", "-");
+    biến b2 = thay_thế_tất_cả(b1, "/", "_");
+    biến b3 = thay_thế_tất_cả(b2, "=", "");
+    trả b3;
+}
+
+// Giải mã Base64 URL-safe
+hàm giai_ma_base64_url(chuoi) {
+    biến b1 = thay_thế_tất_cả(chuoi, "-", "+");
+    biến b2 = thay_thế_tất_cả(b1, "_", "/");
+    trả giải_mã_base64(b2);
+}
+
+xuất { tao_uuid, ma_hoa_base64_url, giai_ma_base64_url };

package/src/ngay_thang.sm

@@ -0,0 +1,38 @@
+// ========================================================
+// Module: Xử lý Thời gian & Ngày Tháng Thuần Việt
+// ========================================================
+
+biến CAC_THU = [
+    "Chủ Nhật",
+    "Thứ Hai",
+    "Thứ Ba",
+    "Thứ Tư",
+    "Thứ Năm",
+    "Thứ Sáu",
+    "Thứ Bảy"
+];
+
+// Tính số ngày chênh lệch giữa hai mốc mili-giây
+hàm tinh_khoang_cach_ngay(moc1, moc2) {
+    biến do_lech = trị_tuyệt_đối(moc2 - moc1);
+    biến mot_ngay = 1000 * 60 * 60 * 24;
+    trả làm_tròn(do_lech / mot_ngay);
+}
+
+// Kiểm tra năm nhuận dương lịch
+hàm la_nam_nhuan(nam) {
+    nếu ((nam % 4 == 0 && nam % 100 != 0) || (nam % 400 == 0)) {
+        trả đúng;
+    }
+    trả sai;
+}
+
+// Lấy tên thứ từ chỉ số (0: Chủ Nhật, 1: Thứ Hai...)
+hàm lay_ten_thu(chi_so) {
+    nếu (chi_so >= 0 && chi_so < 7) {
+        trả CAC_THU[chi_so];
+    }
+    trả "Không xác định";
+}
+
+xuất { CAC_THU, tinh_khoang_cach_ngay, la_nam_nhuan, lay_ten_thu };

package/test/std.test.sm

@@ -0,0 +1,45 @@
+// ========================================================
+// Kiểm thử Thư viện Chuẩn Mở Rộng SongMa Std
+// ========================================================
+
+dùng {
+    la_nam_nhuan,
+    lay_ten_thu,
+    tinh_khoang_cach_ngay,
+    tao_uuid,
+    ma_hoa_base64_url,
+    giai_ma_base64_url,
+    la_so_dien_thoai_vn,
+    la_email_hop_le,
+    la_cccd_hop_le,
+    doc_csv,
+    tao_csv
+} từ "../src/index.smjs";
+
+// 1. Kiểm thử Ngày Tháng
+nếu (!la_nam_nhuan(2024)) { ném "Lỗi: 2024 phải là năm nhuận"; }
+nếu (la_nam_nhuan(2023)) { ném "Lỗi: 2023 không phải năm nhuận"; }
+nếu (lay_ten_thu(1) != "Thứ Hai") { ném "Lỗi: 1 phải là Thứ Hai"; }
+
+// 2. Kiểm thử Mã Hóa & UUID
+biến id = tao_uuid();
+nếu (độ_dài(id) != 36) { ném "Lỗi: Độ dài UUID phải bằng 36"; }
+
+biến text = "Xin chào Sông Mã 2026";
+biến encoded = ma_hoa_base64_url(text);
+biến decoded = giai_ma_base64_url(encoded);
+nếu (decoded != text) { ném "Lỗi: Base64 URL-safe encode/decode không khớp"; }
+
+// 3. Kiểm thử Validator Việt Nam
+nếu (!la_so_dien_thoai_vn("0912345678")) { ném "Lỗi: 0912345678 phải hợp lệ"; }
+nếu (la_so_dien_thoai_vn("0123456789")) { ném "Lỗi: Đầu số 012 không còn hợp lệ"; }
+nếu (!la_email_hop_le("contact@songma.dev")) { ném "Lỗi: Email phải hợp lệ"; }
+nếu (!la_cccd_hop_le("038204012345")) { ném "Lỗi: CCCD 12 số phải hợp lệ"; }
+
+// 4. Kiểm thử Bảng Dữ Liệu CSV
+biến csv_mau = "ten,tuoi,vai_tro\nMinh Vy,20,Admin\nThanh Hoa,22,User";
+biến parsed = doc_csv(csv_mau);
+nếu (độ_dài(parsed) != 2) { ném "Lỗi: Phải parse được 2 dòng dữ liệu"; }
+nếu (parsed[0].ten != "Minh Vy") { ném "Lỗi: Tên dòng 1 phải là Minh Vy"; }
+
+in("[KIỂM THỬ THÀNH CÔNG] Toàn bộ module songma-std hoạt động chính xác!");