filewisee 0.1.0

package/dist/relative.js

@@ -0,0 +1,60 @@
+import { MS_PER_DAY, MS_PER_HOUR, MS_PER_MINUTE, MS_PER_SECOND, MS_PER_WEEK, } from "./constants.js";
+import { diffInMilliseconds } from "./diff.js";
+// Ordered ascending: the first threshold whose limit exceeds the absolute
+// distance wins.
+const THRESHOLDS = [
+    { limit: MS_PER_MINUTE, divisor: MS_PER_SECOND, unit: 'second' },
+    { limit: MS_PER_HOUR, divisor: MS_PER_MINUTE, unit: 'minute' },
+    { limit: MS_PER_DAY, divisor: MS_PER_HOUR, unit: 'hour' },
+    { limit: MS_PER_WEEK, divisor: MS_PER_DAY, unit: 'day' },
+    { limit: MS_PER_DAY * 30, divisor: MS_PER_WEEK, unit: 'week' },
+    { limit: MS_PER_DAY * 365, divisor: MS_PER_DAY * 30, unit: 'month' },
+    { limit: Infinity, divisor: MS_PER_DAY * 365, unit: 'year' },
+];
+/**
+ * Human-friendly relative time, localised via the platform `Intl` API.
+ *
+ * @param input  The date to describe.
+ * @param base   The reference point (default: now).
+ * @param locale BCP-47 locale tag(s) for `Intl.RelativeTimeFormat` (default: runtime).
+ *
+ * @example
+ * formatRelative(addDays(new Date(), -3)) // "3 days ago"
+ * formatRelative(addHours(new Date(), 2)) // "in 2 hours"
+ */
+export function formatRelative(input, base = new Date(), locale) {
+    const deltaMs = diffInMilliseconds(input, base);
+    const abs = Math.abs(deltaMs);
+    const { divisor, unit } = THRESHOLDS.find((t) => abs < t.limit) ?? THRESHOLDS.at(-1);
+    const value = Math.round(deltaMs / divisor);
+    const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+    return rtf.format(value, unit);
+}
+/** Alias for {@link formatRelative} reading the other way: time from `base` to `input`. */
+export const fromNow = (input, locale) => formatRelative(input, new Date(), locale);
+/**
+ * Formats a millisecond duration compactly, largest unit first.
+ *
+ * @param ms      Duration in milliseconds (sign is ignored).
+ * @param maxUnits How many units to show (default `2`), e.g. `"1h 30m"`.
+ *
+ * @example formatDuration(90_061_000) // "1d 1h" (maxUnits: 2)
+ */
+export function formatDuration(ms, maxUnits = 2) {
+    let rest = Math.abs(Math.trunc(ms));
+    const units = [
+        ['d', MS_PER_DAY], ['h', MS_PER_HOUR], ['m', MS_PER_MINUTE], ['s', MS_PER_SECOND],
+    ];
+    const parts = [];
+    for (const [label, size] of units) {
+        if (parts.length >= maxUnits)
+            break;
+        const value = Math.floor(rest / size);
+        if (value > 0 || (parts.length === 0 && label === 's')) {
+            parts.push(`${value}${label}`);
+            rest -= value * size;
+        }
+    }
+    return parts.length ? parts.join(' ') : '0s';
+}
+//# sourceMappingURL=relative.js.map

package/dist/relative.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relative.js","sourceRoot":"","sources":["../src/relative.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Anything the library can accept where a date is expected.
+ *
+ * - `Date`   — used as-is (never mutated).
+ * - `number` — milliseconds since the Unix epoch.
+ * - `string` — an ISO-8601 string (or anything the native `Date` can parse).
+ */
+export type DateInput = Date | number | string;
+/** A unit of time, used by diffing, rounding and manipulation helpers. */
+export type TimeUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond';
+/** Day of the week, `0` = Sunday … `6` = Saturday (matches `Date.getDay`). */
+export type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** A half-open or closed interval between two instants. */
+export interface Interval {
+    start: DateInput;
+    end: DateInput;
+}
+/** A calendar/clock breakdown of a duration, as returned by {@link breakdownDuration}. */
+export interface DurationParts {
+    years: number;
+    months: number;
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    milliseconds: number;
+}
+/** Locale strings used by {@link format} and {@link formatRelative}. */
+export interface Locale {
+    months: string[];
+    monthsShort: string[];
+    weekdays: string[];
+    weekdaysShort: string[];
+    /** AM/PM markers, e.g. `['AM', 'PM']`. */
+    meridiem: [string, string];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAA;AAE9C,0EAA0E;AAC1E,MAAM,MAAM,QAAQ,GAChB,MAAM,GACN,SAAS,GACT,OAAO,GACP,MAAM,GACN,KAAK,GACL,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,aAAa,CAAA;AAEjB,8EAA8E;AAC9E,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AAE/C,2DAA2D;AAC3D,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,SAAS,CAAA;IAChB,GAAG,EAAE,SAAS,CAAA;CACf;AAED,0FAA0F;AAC1F,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,wEAAwE;AACxE,MAAM,WAAW,MAAM;IACrB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,0CAA0C;IAC1C,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC3B"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/validate.d.ts

@@ -0,0 +1,33 @@
+import type { DateInput } from './types.ts';
+/**
+ * Returns `true` when the value is a `Date` representing a real instant
+ * (i.e. not an `Invalid Date`).
+ *
+ * @example
+ * isValidDate(new Date())            // true
+ * isValidDate(new Date('nonsense'))  // false
+ * isValidDate('2024-01-01')          // false — not a Date instance
+ */
+export declare function isValidDate(value: unknown): value is Date;
+/**
+ * Normalises any {@link DateInput} into a fresh `Date` instance.
+ *
+ * The input is never mutated — passing a `Date` returns a *copy*, so callers
+ * can safely keep working with the result.
+ *
+ * @throws {TypeError} if the input cannot be interpreted as a valid date.
+ */
+export declare function toDate(input: DateInput): Date;
+/**
+ * Like {@link toDate} but never throws — returns `null` for invalid input.
+ * Useful when validating untrusted data.
+ */
+export declare function tryToDate(input: DateInput): Date | null;
+/** Returns `true` if the given year is a leap year in the Gregorian calendar. */
+export declare function isLeapYear(year: number): boolean;
+/**
+ * Number of days in the given month.
+ * @param month Zero-based month (`0` = January, `11` = December).
+ */
+export declare function daysInMonth(year: number, month: number): number;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3C;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,CAEzD;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAkB7C;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI,CAMvD;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAG/D"}

package/dist/validate.js

@@ -0,0 +1,64 @@
+/**
+ * Returns `true` when the value is a `Date` representing a real instant
+ * (i.e. not an `Invalid Date`).
+ *
+ * @example
+ * isValidDate(new Date())            // true
+ * isValidDate(new Date('nonsense'))  // false
+ * isValidDate('2024-01-01')          // false — not a Date instance
+ */
+export function isValidDate(value) {
+    return value instanceof Date && !Number.isNaN(value.getTime());
+}
+/**
+ * Normalises any {@link DateInput} into a fresh `Date` instance.
+ *
+ * The input is never mutated — passing a `Date` returns a *copy*, so callers
+ * can safely keep working with the result.
+ *
+ * @throws {TypeError} if the input cannot be interpreted as a valid date.
+ */
+export function toDate(input) {
+    let date;
+    if (input instanceof Date) {
+        date = new Date(input.getTime());
+    }
+    else if (typeof input === 'number') {
+        date = new Date(input);
+    }
+    else if (typeof input === 'string') {
+        date = new Date(input);
+    }
+    else {
+        throw new TypeError(`Cannot convert value of type "${typeof input}" to a Date`);
+    }
+    if (Number.isNaN(date.getTime())) {
+        throw new TypeError(`Invalid date input: ${JSON.stringify(input)}`);
+    }
+    return date;
+}
+/**
+ * Like {@link toDate} but never throws — returns `null` for invalid input.
+ * Useful when validating untrusted data.
+ */
+export function tryToDate(input) {
+    try {
+        return toDate(input);
+    }
+    catch {
+        return null;
+    }
+}
+/** Returns `true` if the given year is a leap year in the Gregorian calendar. */
+export function isLeapYear(year) {
+    return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+/**
+ * Number of days in the given month.
+ * @param month Zero-based month (`0` = January, `11` = December).
+ */
+export function daysInMonth(year, month) {
+    // Day 0 of the next month rolls back to the last day of `month`.
+    return new Date(year, month + 1, 0).getDate();
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,KAAK,YAAY,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAA;AAChE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,MAAM,CAAC,KAAgB;IACrC,IAAI,IAAU,CAAA;IACd,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;QAC1B,IAAI,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAA;IAClC,CAAC;SAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACrC,IAAI,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAA;IACxB,CAAC;SAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACrC,IAAI,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAA;IACxB,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,SAAS,CACjB,iCAAiC,OAAO,KAAK,aAAa,CAC3D,CAAA;IACH,CAAC;IAED,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,SAAS,CAAC,uBAAuB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IACrE,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,KAAgB;IACxC,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,GAAG,GAAG,KAAK,CAAC,CAAC,IAAI,IAAI,GAAG,GAAG,KAAK,CAAC,CAAA;AACjE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,KAAa;IACrD,iEAAiE;IACjE,OAAO,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAA;AAC/C,CAAC"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "filewisee",
+  "version": "0.1.0",
+  "description": "Node utility to format date",
+  "keywords": [
+    "date",
+    "time",
+    "datetime"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test \"test/**/*.test.ts\"",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "typescript": "^6.0.3"
+  }
+}