nv-date-y7 1.0.1 → 1.0.2

package/README.md

@@ -0,0 +1,207 @@
+# nv-date-y7
+
+High-performance date-string ↔ timestamp converter  
+Zero `Date.parse` dependency.  
+Pure JS — no bindings, no native addons, no C/C++.  
+Pure arithmetic civil calendar implementation.
+
+Designed for:
+
+- ultra-high fixed-length date-string throughput
+- especially suitable for debug / trace logging
+- zero allocation (buffer reuse)
+- predictable fixed-width string format
+- no locale ambiguity
+- UTC only
+
+90% code is generated BY free AI(CHAT-GPT) 
+
+
+
+---
+
+## Why?
+
+Native:
+
+    new Date(iso).getTime()
+
+is:
+
+- slow in debug/test enviroment , massive random date-string inserted
+- allocates
+- involves internal parsing
+- unpredictable for extended years
+
+nv-date-y7 uses a pure civil calendar algorithm  (no built-in date parsing involved)
+
+
+---
+
+# Format Overview
+
+## 1. Y7 format (20 chars)
+
+Fixed width: 20 chars
+
+    <3 pad or sign><YYYY or ±YYYYYY><MM><DD><hh><mm><ss><sss>
+
+Examples:
+
+    "   20240213123456789"
+    "+01234501010000000000"
+    "-00000101010000000000"
+
+- 4-digit years use 3 leading spaces
+- extended years use sign + 6 digits
+- always UTC
+
+---
+
+## 2. ISO format (27 chars)
+
+Fixed width: 27 chars
+
+    <pad or sign>YYYY-MM-DDThh:mm:ss.sssZ
+
+Example:
+
+    "   2024-02-13T11:22:33.123Z"
+
+---
+
+# Installation
+
+    npm install nv-date-y7
+
+---
+
+# Usage
+
+## Default export
+
+    const y7 = require("nv-date-y7");
+
+    y7();                  // now → y7
+    y7(Date.now());
+    y7("2024-02-13");
+
+---
+
+## Y7 API
+
+    const {
+      mts_to_y7,
+      y7_to_mts,
+      dt_to_y7,
+      y7_to_dt
+    } = require("nv-date-y7");
+
+### Convert timestamp → y7
+
+    mts_to_y7(Date.now());
+
+### Convert y7 → timestamp
+
+    y7_to_mts("   20240213123456789");
+
+### Date helpers
+
+    dt_to_y7(new Date());
+    y7_to_dt("   20240213123456789");
+
+---
+
+## ISO API
+
+    const {
+      mts_to_iso,
+      iso_to_mts
+    } = require("nv-date-y7");
+
+### timestamp → ISO
+
+    mts_to_iso(Date.now());
+
+### ISO → timestamp
+
+    iso_to_mts("   2024-02-13T11:22:33.123Z");
+
+---
+
+# Custom ISO-like format
+
+You can customize separators:
+
+    const { to_str } = require("nv-date-y7");
+
+    to_str(Date.now(), {
+      "-": "/",
+      "T": " ",
+      ":": ".",
+      ".": ",",
+      "Z": ""
+    });
+
+Example output:
+
+    "   2024/02/13 11.22.33,123"
+
+---
+
+# Performance
+
+Example benchmark (Node 20):
+
+    builtin_new_date     34.583 sec 2891582 ops/sec
+    iso_to_mts           19.680 sec 5081377 ops/sec
+
+Y7 decode:
+
+    y7_to_mts     1.316 sec 15192186 ops/sec
+
+~2× faster than native ISO parsing  
+~5×–7× faster in optimized paths  
+
+---
+
+# Range
+
+Supports:
+
+- ±100,000,000 days
+- ±6 digit years
+- full proleptic Gregorian calendar
+- UTC only
+
+Range check enforced:
+
+    MIN6 = -100000000 days
+    MAX6 = +100000000 days
+
+---
+
+
+# When to use this?
+
+- High-frequency logging  
+- LogStore needing sortable fixed strings  
+- Performance critical services  
+- Deterministic UTC-only systems  
+
+---
+
+# When NOT to use this?
+
+- Local time formatting  
+- Timezone conversions  
+- Human-friendly display formatting  
+
+This is a machine format, not UI format.
+
+---
+
+# License
+
+ANY
+

package/TEST/check.js

@@ -0,0 +1,182 @@
+const DAY = 86400000;
+const MIN6 = -DAY * 100000000;
+const MAX6 =  DAY * 100000000 + 1;
+
+const MIN4 = -DAY * 719528;
+const MAX4 =  DAY * 2932897;
+
+const pad = (n, w) => String(n).padStart(w, "0");
+
+
+const civil_from_days = (z) => {
+    z += 719468;
+
+    const era = Math.floor(z / 146097);
+    const doe = z - era * 146097;
+    const yoe = Math.floor((doe - Math.floor(doe/1460) + Math.floor(doe/36524) - Math.floor(doe/146096)) / 365);
+    let y = yoe + era * 400;
+
+    const doy = doe - (365*yoe + Math.floor(yoe/4) - Math.floor(yoe/100));
+    const mp = Math.floor((5*doy + 2)/153);
+
+    const d = doy - Math.floor((153*mp+2)/5) + 1;
+    const m = mp + (mp < 10 ? 3 : -9);
+
+    y += (m <= 2);
+
+    return [y, m, d];
+};
+
+const days_from_civil = (y, m, d) => {
+    y -= m <= 2 ? 1 : 0;
+    const era = Math.floor(y / 400);
+    const yoe = y - era * 400;
+    const doy = Math.floor((153*(m + (m>2?-3:9)) + 2)/5) + d - 1;
+    const doe = yoe*365 + Math.floor(yoe/4) - Math.floor(yoe/100) + doy;
+    return era*146097 + doe - 719468;
+};
+
+const mts_to_y7 = (mts = Date.now()) => {
+    if (mts < MIN6 || mts >= MAX6)
+        throw new RangeError("Out of supported range");
+
+    const days = Math.floor(mts / DAY);
+    let msDay = mts - days * DAY;
+
+    if (msDay < 0) {
+        msDay += DAY;
+    }
+
+    const [y, m, d] = civil_from_days(days);
+
+    let ypart;
+    if (mts >= MIN4 && mts < MAX4) {
+        ypart = "   " + pad(y,4);
+    } else if (mts >= MAX4) {
+        ypart = "+" + pad(y,6);
+    } else {
+        ypart = "-" + pad(-y,6);
+    }
+
+    const hh = Math.floor(msDay / 3600000);
+    msDay -= hh*3600000;
+
+    const mm = Math.floor(msDay / 60000);
+    msDay -= mm*60000;
+
+    const ss = Math.floor(msDay / 1000);
+    const sss = msDay - ss*1000;
+
+    return ypart +
+        pad(m,2) +
+        pad(d,2) +
+        pad(hh,2) +
+        pad(mm,2) +
+        pad(ss,2) +
+        pad(sss,3);
+};
+
+
+
+const mts_to_y7_b = (mts=Date.now()) => {
+    if (mts < MIN6 || mts >= MAX6)
+        throw new RangeError("Out of supported range");
+
+    const d = new Date(mts);
+    const y = d.getUTCFullYear();
+
+    let ypart;
+
+    if (mts >= MIN4 && mts < MAX4) {
+        // 四位年
+        ypart = "   " + pad(y, 4);
+    } else if (mts >= MAX4) {
+        // 正六位
+        ypart = "+" + pad(y, 6);
+    } else {
+        // 负六位
+        ypart = "-" + pad(-y, 6);
+    }
+
+    const MM   = pad(d.getUTCMonth() + 1, 2);
+    const DD   = pad(d.getUTCDate(), 2);
+    const hh   = pad(d.getUTCHours(), 2);
+    const mm   = pad(d.getUTCMinutes(), 2);
+    const ss   = pad(d.getUTCSeconds(), 2);
+    const sss  = pad(d.getUTCMilliseconds(), 3);
+
+    return ypart + MM + DD + hh + mm + ss + sss;
+};
+
+const points = [
+    MIN6,
+    MIN6 + 1,
+    MIN4 - 1,
+    MIN4,
+    MIN4 + 1,
+    -1,
+    0,
+    1,
+    MAX4 - 1,
+    MAX4,
+    MAX4 + 1,
+    MAX6 - 1
+];
+
+for (const mts of points) {
+    if (mts_to_y7(mts) !== mts_to_y7_b(mts)) {
+        console.log("Mismatch:", mts,
+            new Date(mts),
+            mts_to_y7(mts),
+            mts_to_y7_b(mts));
+    }
+}
+console.log(points,"PASS")
+
+for (let i = 0; i < 1_000_000; i++) {
+    const mts = Math.floor(
+        MIN6 + Math.random() * (MAX6 - MIN6)
+    );
+
+    if (mts_to_y7(mts) !== mts_to_y7_b(mts)) {
+        console.log("Mismatch:", mts,
+            new Date(mts),
+            mts_to_y7(mts),
+            mts_to_y7_b(mts));
+        break;
+    }
+}
+
+console.log("random","PASS")
+
+const CYCLE = 146097 * DAY; // 400年
+
+for (let mts = -CYCLE; mts < CYCLE; mts += 1234567) {
+    if (mts_to_y7(mts) !== mts_to_y7_b(mts)) {
+        console.log("Mismatch:", mts,
+            new Date(mts),
+            mts_to_y7(mts),
+            mts_to_y7_b(mts));
+        break;
+    }
+}
+
+console.log("circle","PASS")
+
+
+let ok = true;
+
+for (let i = 0; i < 5_000_000; i++) {
+    const mts = (Math.random() * 2**52 | 0) - 2**51;
+
+    const a = mts_to_y7(mts);
+    const b = mts_to_y7_b(mts);
+
+    if (a !== b) {
+        console.log("Mismatch:", mts, new Date(mts), a, b);
+        ok = false;
+        break;
+    }
+}
+
+if (ok) console.log("All good.");

package/TEST/perf-iso-to-mts.js

@@ -0,0 +1,84 @@
+const { iso_to_mts, mts_to_iso } = require("../index");
+
+const builtin_new_date = (iso) => (new Date(iso)).getTime();
+
+const SAMPLE_SIZE = 1_000_000;
+const SAMPLES = new Array(SAMPLE_SIZE);
+
+// ===== 生成样本 =====
+// 使用原生 Date 生成标准 ISO
+let mts = -86400000 * 200000;
+for (let i = 0; i < SAMPLE_SIZE; i++) {
+    const d = new Date(mts);
+    SAMPLES[i] = d.toISOString();
+    mts += 1234567;
+}
+
+// ===== 校验 =====
+const check = () => {
+    for (let i = 0; i < 10000; i++) {
+        const iso = SAMPLES[i];
+
+        const a = builtin_new_date(iso);
+        const b = iso_to_mts("   " + iso.slice(0)); // 如果你格式带 3 空格
+
+        if (a !== b) {
+            console.error("Mismatch:");
+            console.log(iso, a, b);
+            process.exit(1);
+        }
+
+        const myIso = mts_to_iso(a).trim();
+        if (myIso !== iso) {
+            console.error("Encode mismatch:");
+            console.log(myIso, iso);
+            process.exit(1);
+        }
+    }
+
+    console.log("check ok");
+};
+
+var recv = 0;
+
+// ===== benchmark =====
+const perf = (ROUNDS) => {
+
+    check();
+
+    const bench = (name, fn) => {
+
+        // 预热
+        for (let i = 0; i < SAMPLE_SIZE; i++) {
+            recv ^= fn(SAMPLES[i]);
+        }
+
+        const t0 = process.hrtime.bigint();
+
+        for (let r = 0; r < ROUNDS; r++) {
+            for (let i = 0; i < SAMPLE_SIZE; i++) {
+                recv ^= fn(SAMPLES[i]);
+            }
+        }
+
+        const t1 = process.hrtime.bigint();
+
+        const sec = Number(t1 - t0) / 1e9;
+        const calls = ROUNDS * SAMPLE_SIZE;
+        const ops = calls / sec;
+
+        console.log(
+            name.padEnd(20),
+            sec.toFixed(3), "sec",
+            ops.toFixed(0), "ops/sec"
+        );
+    };
+
+    bench("builtin_new_date", builtin_new_date);
+    bench("iso_to_mts", iso_to_mts);
+
+    console.log("recv:", recv);
+};
+
+perf(Number(process.argv[2] ?? 100));
+