@bariskuran/base 0.0.0-stage → 0.0.1

package/src/libs/getTimeDiff/_dS.jsx

@@ -0,0 +1,345 @@
+import Ds from "../DesignSystem";
+import { SYS } from "../../constants/SYS";
+import { getTimeDiff } from ".";
+import { Flex } from "../Flex";
+import { Typo } from "../Typo";
+import { Button } from "../Button";
+import { baseDate } from "../baseDate";
+
+const fixedEpoch = 1700000000000;
+const fixedLater = fixedEpoch + 36 * 60 * 60 * 1000;
+
+const X = () => {
+    const { outputButtonProps, Output } = Ds.useOutputViewer();
+
+    return (
+        <Ds.page
+            title="getTimeDiff()"
+            releasedOn="1.0.0"
+            description={
+                <>
+                    <Typo.p>
+                        Calculates the difference between two given dates in all units, returning
+                        both total and breakdown values.
+                    </Typo.p>
+                    <Typo.p>The order of the dates does not matter.</Typo.p>
+                    <Typo.p>
+                        Dates can be provided as a Date(), a baseDate object, a timestamp number,
+                        purely numeric timestamp strings, or other date strings that{" "}
+                        <Button.string to="/design-system/baseDate" label="baseDate()" /> can parse.
+                    </Typo.p>
+                    <Typo.p>
+                        <b>breakdown</b> (year, month, day, hour, …) is counted on the <b>UTC</b>{" "}
+                        calendar between the two instants, not on your local wall-clock calendar.
+                        For labels in a chosen timezone, use 'time1.date' / 'time2.date' (from{" "}
+                        <Button.string to="/design-system/baseDate" label="baseDate()" />
+                        ). ts and tsDiff are always plain epoch milliseconds (timezone-agnostic).
+                    </Typo.p>
+                </>
+            }
+        >
+            <Ds.block
+                title="Basic usage"
+                description="getTimeDiff basicly compares two dates and returns the difference in different units and breakdowns."
+                code={`import { getTimeDiff } from "${SYS.basePath}";
+
+                        getTimeDiff("1700000000000", 1700000000000 + 3600000);
+                        getTimeDiff({ initial: "28/03/1982" });
+                        getTimeDiff(new Date(1700000000000));
+`}
+                example={
+                    <Flex.column gap={10} padding={10} full>
+                        <Flex gap={10} full wrap>
+                            <Button.plain
+                                label="ts"
+                                {...outputButtonProps({
+                                    path: "block1",
+                                    activeLabel: "ts",
+                                    fn: getTimeDiff("1700000000000", 1700000000000 + 3600000),
+                                })}
+                            />
+                            <Button.plain
+                                label="baseDate obj to now"
+                                {...outputButtonProps({
+                                    path: "block1",
+                                    activeLabel: "baseDate",
+                                    fn: getTimeDiff({ initial: "28/03/1982" }),
+                                })}
+                            />
+                            <Button.plain
+                                label="Date() to now"
+                                {...outputButtonProps({
+                                    path: "block1",
+                                    activeLabel: "Date",
+                                    fn: getTimeDiff(new Date(1700000000000)),
+                                })}
+                            />
+                        </Flex>
+                        <Output path="block1" />
+                    </Flex.column>
+                }
+            />
+            <Ds.block
+                title="ts, Date and baseDate equality comparison"
+                code={`import { getTimeDiff } from "${SYS.basePath}";
+
+                        const msValue = 1000 * 60 * 60 * 26 + 3500;
+
+                        const a = Date.now();
+                        const c = a + msValue;
+                        const d = baseDate({
+                            initial: a,
+                            calc: { millisecond: msValue },
+                            format: "timestamp",
+                        });
+
+                        const r1 = getTimeDiff(a, c);
+                        const r2 = getTimeDiff(new Date(a), new Date(c));
+                        const r3 = getTimeDiff(String(a), String(c));
+                        const r4 = getTimeDiff(a, d);
+
+                        // r1, r2, r3, r4 → same tsDiff
+`}
+                example={
+                    <Flex.column gap={10} padding={10} full>
+                        <Flex gap={10}>
+                            <Button.plain
+                                label="equality comparison"
+                                {...outputButtonProps({
+                                    path: "primitives",
+                                    activeLabel: "r1",
+                                    fn: () => {
+                                        const GAP = 1000 * 60 * 60 * 26 + 3500;
+
+                                        const a = Date.now();
+                                        const c = a + GAP;
+                                        const d = baseDate({
+                                            initial: a,
+                                            calc: { millisecond: GAP },
+                                            format: "timestamp",
+                                        });
+
+                                        const r1 = getTimeDiff(a, c).tsDiff;
+                                        const r2 = getTimeDiff(new Date(a), new Date(c)).tsDiff;
+                                        const r3 = getTimeDiff(String(a), String(c)).tsDiff;
+                                        const r4 = getTimeDiff(a, d).tsDiff;
+
+                                        return {
+                                            r1,
+                                            r2,
+                                            r3,
+                                            r4,
+                                            equal: r1 === r2 && r2 === r3 && r3 === r4,
+                                        };
+                                    },
+                                })}
+                            />
+                        </Flex>
+                        <Output path="primitives" />
+                    </Flex.column>
+                }
+            />
+            <Ds.block
+                title="Usage with a single argument"
+                description="The single argument is compared to 'now'."
+                code={`import { getTimeDiff } from "${SYS.basePath}";
+
+                        getTimeDiff(Date.now() - 3600000);
+                        getTimeDiff({ initial: "01/01/2020" });`}
+                example={
+                    <Flex.column gap={10} padding={10} full>
+                        <Flex gap={10} wrap>
+                            <Button.plain
+                                label="single ms"
+                                {...outputButtonProps({
+                                    path: "one-argument",
+                                    activeLabel: "ms",
+                                    fn: () => getTimeDiff(fixedEpoch - 3600000),
+                                })}
+                            />
+                            <Button.plain
+                                label="single object (past date)"
+                                {...outputButtonProps({
+                                    path: "one-argument",
+                                    activeLabel: "object",
+                                    fn: () =>
+                                        getTimeDiff({
+                                            calc: { hour: -1 },
+                                        }),
+                                })}
+                            />
+                        </Flex>
+                        <Output path="one-argument" />
+                    </Flex.column>
+                }
+            />
+            <Ds.block
+                title="baseDate-style objects"
+                description="Example: both sides as objects. Optional format controls time1.date / time2.date strings."
+                code={`import { getTimeDiff } from "${SYS.basePath}";
+
+                        getTimeDiff(
+                            {
+                                initial: 1700000000000,
+                                format: "|DD|/|MM|/|YYYY| |HH|:|NN|",
+                            },
+                            {
+                                initial: 1700086400000,
+                                format: "|YY|/|MM|/|DD|",
+                            },
+                        );
+
+                        getTimeDiff(
+                            { initial: "10/03/2024", calc: { day: 5 } },
+                            { initial: "20/03/2024" },
+                        );`}
+                example={
+                    <Flex.column gap={10} padding={10} full>
+                        <Flex gap={10} wrap>
+                            <Button.plain
+                                label="two objects + display formats"
+                                {...outputButtonProps({
+                                    path: "baseDate-objects",
+                                    activeLabel: "formats",
+                                    fn: () =>
+                                        getTimeDiff(
+                                            {
+                                                initial: 1700000000000,
+                                                format: "|DD|/|MM|/|YYYY| |HH|:|NN|",
+                                            },
+                                            {
+                                                initial: 1700086400000,
+                                                format: "|YY|/|MM|/|DD|",
+                                            },
+                                        ),
+                                })}
+                            />
+                            <Button.plain
+                                label="calc on initial"
+                                {...outputButtonProps({
+                                    path: "baseDate-objects",
+                                    activeLabel: "calc",
+                                    fn: () =>
+                                        getTimeDiff(
+                                            {
+                                                initial: "10/03/2024",
+                                                calc: { day: 5 },
+                                            },
+                                            { initial: "20/03/2024" },
+                                        ),
+                                })}
+                            />
+                        </Flex>
+                        <Output path="baseDate-objects" />
+                    </Flex.column>
+                }
+            />
+            <Ds.block
+                title="in (fractional) vs breakdown (calendar)"
+                description="in spreads |tsDiff| across averaged units (e.g. inYears uses 365.25-day years). breakdown walks the UTC calendar from the earlier instant: full years, then months (never ≥12 before years roll), then days in month, then clock fields — not the local (IANA) calendar. Zeros omitted."
+                code={`import { getTimeDiff } from "${SYS.basePath}";
+
+                        const a = 1700000000000;
+                        const b = a + 36 * 60 * 60 * 1000;
+                        getTimeDiff(a, b);`}
+                example={
+                    <Flex.column gap={10} padding={10} full>
+                        <Button.plain
+                            label="exactly 36h apart (fixed ms)"
+                            {...outputButtonProps({
+                                path: "fractional-breakdown",
+                                activeLabel: "36h",
+                                fn: () => getTimeDiff(fixedEpoch, fixedLater),
+                            })}
+                        />
+                        <Output path="fractional-breakdown" />
+                    </Flex.column>
+                }
+            />
+            <Ds.block
+                title="time1 / time2 & atTimeline"
+                description="tsDiff = |time2.ts − time1.ts| (always ≥ 0). Each side includes atTimeline: position of that instant relative to the other (inPast / inFuture / sameInstant)."
+                code={`import { getTimeDiff } from "${SYS.basePath}";
+
+                        getTimeDiff(1000, 2000);
+                        getTimeDiff(2000, 1000);
+                        getTimeDiff(42, 42);`}
+                example={
+                    <Flex.column gap={10} padding={10} full>
+                        <Flex gap={10} wrap>
+                            <Button.plain
+                                label="time1 before time2"
+                                {...outputButtonProps({
+                                    path: "timeline",
+                                    activeLabel: "before",
+                                    fn: () => getTimeDiff(1000, 2000),
+                                })}
+                            />
+                            <Button.plain
+                                label="time1 after time2"
+                                {...outputButtonProps({
+                                    path: "timeline",
+                                    activeLabel: "after",
+                                    fn: () => getTimeDiff(2000, 1000),
+                                })}
+                            />
+                            <Button.plain
+                                label="same instant"
+                                {...outputButtonProps({
+                                    path: "timeline",
+                                    activeLabel: "same",
+                                    fn: () => getTimeDiff(42, 42),
+                                })}
+                            />
+                        </Flex>
+                        <Output path="timeline" />
+                    </Flex.column>
+                }
+            />
+            <Ds.api
+                args="const diff = getTimeDiff(time1, time2);"
+                props={{
+                    time1: {
+                        description:
+                            "Unix ms, numeric string (ms, validated with isNumber then coerced), Date, or plain object for baseDate (optional format only affects returned date string).",
+                        type: "number | string | Date | object",
+                        required: true,
+                    },
+                    time2: {
+                        description: "Same shapes as time1. If omitted, the other side is 'now'.",
+                        type: "number | string | Date | object",
+                    },
+                }}
+                returnProps={{
+                    time1: {
+                        description:
+                            "First argument snapshot: ts, dateObj, date (baseDate-formatted), atTimeline vs time2.",
+                        type: "object",
+                    },
+                    time2: {
+                        description:
+                            "Second argument snapshot (or now): ts, dateObj, date, atTimeline vs time1.",
+                        type: "object",
+                    },
+                    tsDiff: {
+                        description:
+                            "Non-negative milliseconds: |time2.ts − time1.ts|. Order: see time1/time2 atTimeline.",
+                        type: "number",
+                    },
+                    in: {
+                        description:
+                            "Scaled |tsDiff| (inYears = 365.25d year). Half-up: |x|≥1 or (0<|x|<1 with first fractional digit ≠0) → 2 fixed decimals; if fractional part starts with 0 before first non-zero → 2 significant digits (e.g. 0.0000012). inMilliseconds integer. Omits zeros.",
+                        type: "object",
+                    },
+                    breakdown: {
+                        description:
+                            "UTC calendar slice: year, month (0–11 added steps), day, hour, minute, second, millisecond from earlier ts toward later. Omits zeros.",
+                        type: "object",
+                    },
+                }}
+            />
+        </Ds.page>
+    );
+};
+
+export default X;

package/src/libs/getTimeDiff/index.js

@@ -0,0 +1,245 @@
+import { baseDate } from "../baseDate";
+
+const looksLikeNumericTimestampString = (s) => /^-?\d+(\.\d+)?$/.test(s);
+
+const SECOND = 1000;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+const YEAR = 365.25 * DAY;
+
+const omitZeroNumericProps = (obj) => {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (typeof v === "number" && Number.isFinite(v) && v !== 0) out[k] = v;
+    }
+    return out;
+};
+
+const roundHalfUpDecimals = (x, decimals) => {
+    if (!Number.isFinite(x)) return x;
+    const p = 10 ** decimals;
+    const sign = x < 0 ? -1 : 1;
+    const ax = Math.abs(x);
+    return sign * (Math.round(ax * p) / p);
+};
+
+const firstFractionalDigitIsZero = (ax) => {
+    const s = ax.toFixed(18).replace(/\.?0+$/, "");
+    const parts = s.split(".");
+    if (parts.length < 2) return false;
+    return parts[1][0] === "0";
+};
+
+const roundSignificantDigits = (x, n) => {
+    if (!Number.isFinite(x) || x === 0) return x;
+    const sign = x < 0 ? -1 : 1;
+    const ax = Math.abs(x);
+    const p = 10 ** (n - Math.ceil(Math.log10(ax)));
+    return sign * (Math.round(ax * p) / p);
+};
+
+const IN_FIXED_DECIMALS = 2;
+
+const roundInField = (key, raw) => {
+    if (key === "inMilliseconds") {
+        return Math.round(raw);
+    }
+    const ax = Math.abs(raw);
+    if (!Number.isFinite(ax) || ax === 0) {
+        return raw;
+    }
+
+    if (ax >= 1) {
+        return roundHalfUpDecimals(raw, IN_FIXED_DECIMALS);
+    }
+
+    if (!firstFractionalDigitIsZero(ax)) {
+        return roundHalfUpDecimals(raw, IN_FIXED_DECIMALS);
+    }
+
+    return roundSignificantDigits(raw, 2);
+};
+
+const buildIn = (absMs) => {
+    const raw = {
+        inYears: absMs / YEAR,
+        inDays: absMs / DAY,
+        inHours: absMs / HOUR,
+        inMinutes: absMs / MINUTE,
+        inSeconds: absMs / SECOND,
+        inMilliseconds: absMs,
+    };
+    const out = {};
+    for (const [key, val] of Object.entries(raw)) {
+        out[key] = roundInField(key, val);
+    }
+    return out;
+};
+
+const timelineRel = (selfTs, otherTs) => {
+    if (selfTs < otherTs) return "inPast";
+    if (selfTs > otherTs) return "inFuture";
+    return "sameInstant";
+};
+
+const resolveSide = (arg) => {
+    if (arg instanceof Date) {
+        const ts = arg.getTime();
+        if (!Number.isFinite(ts)) throw new Error("getTimeDiff: invalid Date");
+        const dateObj = arg;
+        const date = baseDate({ initial: ts });
+        return { ts, dateObj, date };
+    }
+
+    if (typeof arg === "string") {
+        const s = arg.trim();
+        if (s === "") throw new Error("getTimeDiff: empty string");
+
+        if (looksLikeNumericTimestampString(s)) {
+            const n = Number(s);
+            if (!Number.isFinite(n)) throw new Error("getTimeDiff: invalid numeric string");
+            const dateObj = new Date(n);
+            const date = baseDate({ initial: n });
+            return { ts: n, dateObj, date };
+        }
+
+        return resolveSide({ initial: s });
+    }
+
+    if (typeof arg === "number") {
+        if (!Number.isFinite(arg)) throw new Error("getTimeDiff: invalid number");
+        const dateObj = new Date(arg);
+        const date = baseDate({ initial: arg });
+        return { ts: arg, dateObj, date };
+    }
+
+    if (arg && typeof arg === "object") {
+        const opts = { ...arg };
+        const displayFormat =
+            typeof opts.format === "string" && opts.format.trim() ? opts.format.trim() : null;
+        delete opts.format;
+
+        const tsVal = baseDate({ ...opts, format: "timestamp" });
+        const ts = typeof tsVal === "number" ? tsVal : Number(tsVal);
+        if (!Number.isFinite(ts)) throw new Error("getTimeDiff: could not resolve timestamp");
+
+        const dateObj = new Date(ts);
+        const date = displayFormat
+            ? baseDate({ ...opts, format: displayFormat })
+            : baseDate(opts);
+
+        return { ts, dateObj, date };
+    }
+
+    throw new Error("getTimeDiff: unsupported input type");
+};
+
+const addYearsUTC = (ts, deltaYears) => {
+    const d = new Date(ts);
+    d.setUTCFullYear(d.getUTCFullYear() + deltaYears);
+    return d.getTime();
+};
+
+const addMonthsUTC = (ts, deltaMonths) => {
+    const d = new Date(ts);
+    const day = d.getUTCDate();
+    d.setUTCMonth(d.getUTCMonth() + deltaMonths);
+    if (d.getUTCDate() < day) {
+        d.setUTCDate(0);
+    }
+    return d.getTime();
+};
+
+const addDaysUTC = (ts, deltaDays) => {
+    const d = new Date(ts);
+    d.setUTCDate(d.getUTCDate() + deltaDays);
+    return d.getTime();
+};
+
+const breakdownCalendarUTC = (minTs, maxTs) => {
+    const endTime = maxTs;
+    let cursor = minTs;
+
+    let year = 0;
+    while (true) {
+        const next = addYearsUTC(cursor, 1);
+        if (next > endTime) break;
+        cursor = next;
+        year++;
+    }
+
+    let month = 0;
+    while (true) {
+        const next = addMonthsUTC(cursor, 1);
+        if (next > endTime) break;
+        cursor = next;
+        month++;
+    }
+
+    let day = 0;
+    while (true) {
+        const next = addDaysUTC(cursor, 1);
+        if (next > endTime) break;
+        cursor = next;
+        day++;
+    }
+
+    let hour = 0;
+    while (true) {
+        const next = cursor + HOUR;
+        if (next > endTime) break;
+        cursor = next;
+        hour++;
+    }
+
+    let minute = 0;
+    while (true) {
+        const next = cursor + MINUTE;
+        if (next > endTime) break;
+        cursor = next;
+        minute++;
+    }
+
+    let second = 0;
+    while (true) {
+        const next = cursor + SECOND;
+        if (next > endTime) break;
+        cursor = next;
+        second++;
+    }
+
+    const millisecond = endTime - cursor;
+
+    return { year, month, day, hour, minute, second, millisecond };
+};
+
+export const getTimeDiff = (time1, time2) => {
+    const r1 = resolveSide(time1);
+    const r2 = time2 === undefined ? resolveSide(Date.now()) : resolveSide(time2);
+
+    const absMs = Math.abs(r2.ts - r1.ts);
+
+    const lo = Math.min(r1.ts, r2.ts);
+    const hi = Math.max(r1.ts, r2.ts);
+    const br = breakdownCalendarUTC(lo, hi);
+
+    return {
+        time1: {
+            ts: r1.ts,
+            dateObj: r1.dateObj,
+            date: r1.date,
+            atTimeline: timelineRel(r1.ts, r2.ts),
+        },
+        time2: {
+            ts: r2.ts,
+            dateObj: r2.dateObj,
+            date: r2.date,
+            atTimeline: timelineRel(r2.ts, r1.ts),
+        },
+        tsDiff: absMs,
+        in: omitZeroNumericProps(buildIn(absMs)),
+        breakdown: omitZeroNumericProps(br),
+    };
+};

package/src/libs/isArray/_dS.jsx

@@ -0,0 +1,68 @@
+import Ds from "../DesignSystem";
+import { SYS } from "../../constants/SYS";
+import { isArray } from ".";
+import { Flex } from "../Flex";
+import { Button } from "../Button";
+
+const X = () => {
+    const { outputButtonProps, Output } = Ds.useOutputViewer();
+
+    return (
+        <Ds.page title="isArray()" releasedOn="1.0.0" description={{ tr: "Dizi değerlerini kontrol eder.", en: "Checks array values." }}>
+            <Ds.block
+                title={{ tr: "Temel kullanım", en: "Basic Usage" }}
+                code={`import { isArray } from "${SYS.basePath}";
+
+                       isArray([]);
+                       isArray({});
+                       isArray(new Date());`}
+                example={
+                    <Flex.column gap={10} padding={10} full>
+                        <Flex gap={10} wrap>
+                            <Button.plain
+                                label="isArray([])"
+                                {...outputButtonProps({
+                                    path: "basic",
+                                    activeLabel: "but1",
+                                    fn: () => isArray([]),
+                                })}
+                            />
+                            <Button.plain
+                                label="isArray({})"
+                                {...outputButtonProps({
+                                    path: "basic",
+                                    activeLabel: "but2",
+                                    fn: () => isArray({}),
+                                })}
+                            />
+                            <Button.plain
+                                label="isArray(new Date())"
+                                {...outputButtonProps({
+                                    path: "basic",
+                                    activeLabel: "but3",
+                                    fn: () => isArray(new Date()),
+                                })}
+                            />
+                        </Flex>
+                        <Output path="basic" />
+                    </Flex.column>
+                }
+            />
+            <Ds.api
+                args="const ok = isArray(v);"
+                props={{
+                    v: {
+                        description: { tr: "Test edilecek değer.", en: "Value to test." },
+                        type: "any",
+                        required: true,
+                    },
+                }}
+                returnProps={{
+                    ok: { description: { tr: "v bir diziyse true.", en: "True when v is an array." }, type: "boolean" },
+                }}
+            />
+        </Ds.page>
+    );
+};
+
+export default X;

package/src/libs/isArray/index.js

@@ -0,0 +1,2 @@
+
+export const isArray = (v) => Array.isArray(v);