discord-timestamp-kit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fazal
+
+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

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# discord-timestamp-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Make Discord timestamp codes like `<t:1798765200:F>`, which every reader sees in their own time zone. The kit also converts a date and time in any IANA time zone to Unix seconds without DST bugs, accepts Unix input in seconds or milliseconds, and decodes Discord snowflake IDs into the moment they were created. It is pure TypeScript with zero dependencies and no DOM, so it runs in browsers, Workers, Deno, Bun and Node 22+.
+
+Powers https://discordtimestampgen.com. If you'd rather not bundle a library, the same engine is also a free JSON API: https://discordtimestampgen.com/developers
+
+## Use
+
+```
+npm install discord-timestamp-kit
+```
+
+### Make a `<t:unix:F>` code
+
+```ts
+import { buildTimestampCode, DISCORD_FORMATS } from 'discord-timestamp-kit';
+
+buildTimestampCode(1798765200, 'F');   // '<t:1798765200:F>'
+
+for (const f of DISCORD_FORMATS) {
+  console.log(f.code, f.label, buildTimestampCode(1798765200, f.code));
+}
+// t Short Time       <t:1798765200:t>
+// T Long Time        <t:1798765200:T>
+// d Short Date       <t:1798765200:d>
+// D Long Date        <t:1798765200:D>
+// f Short Date/Time  <t:1798765200:f>
+// F Long Date/Time   <t:1798765200:F>
+// R Relative Time    <t:1798765200:R>
+```
+
+### Convert a local date and time in a time zone to Unix
+
+```ts
+import { dateTimeToUnixInTz, buildTimestampCode } from 'discord-timestamp-kit';
+
+// 8 PM on New Year's Eve in New York
+const unix = dateTimeToUnixInTz('2026-12-31', '20:00', 'America/New_York'); // 1798765200
+buildTimestampCode(unix!, 'R');   // '<t:1798765200:R>'
+```
+
+The inputs use the same `YYYY-MM-DD` and `HH:mm` strings that `<input type="date">` and `<input type="time">` produce. The time-zone offset is sampled twice, the second time at the instant being returned, so times in the hours around a DST change don't come out an hour off. Pass `'UTC'` for UTC. Leave the zone out to use the runtime's own zone. The function returns `null` for blank or malformed input. An unknown zone name falls back to the runtime's zone.
+
+### Parse a pasted Unix timestamp (seconds or milliseconds)
+
+```ts
+import { parseUnixInput } from 'discord-timestamp-kit';
+
+parseUnixInput('1798765200');      // { unix: 1798765200, wasMs: false }
+parseUnixInput('1798765200000');   // { unix: 1798765200, wasMs: true }
+parseUnixInput('12.5');            // null (integers only)
+```
+
+Any value of 100,000,000,000 or more is treated as milliseconds. In seconds, that would be a date in the year 5138.
+
+### Decode a Discord snowflake
+
+```ts
+import { decodeSnowflake } from 'discord-timestamp-kit';
+
+const s = decodeSnowflake('175928847299117063');
+// { unixMs: 1462015105796, unixSeconds: 1462015105, workerId: 1, processId: 0, increment: 7 }
+new Date(s!.unixMs).toISOString();   // '2016-04-30T11:18:25.796Z'
+```
+
+Message, user, channel and server IDs are all snowflakes. The bit math uses BigInt, so IDs above `Number.MAX_SAFE_INTEGER` decode exactly. Pass the ID as a string.
+
+### Preview what Discord will show
+
+```ts
+import { renderDiscordPreview } from 'discord-timestamp-kit';
+
+renderDiscordPreview(1798765200, 'F');                 // e.g. 'Thursday, December 31, 2026 8:00 PM'
+renderDiscordPreview(1798765200, 'R', 1798758000);     // 'in 2 hours'
+```
+
+The preview uses Discord's en-US layout, in the runtime's local time zone. The `R` format takes an optional "now", in Unix seconds.
+
+## API
+
+| Export | What it does |
+|---|---|
+| `DISCORD_FORMATS` | The 7 format codes (`t T d D f F R`) with label, description and example |
+| `buildTimestampCode(unix, code)` | Returns `<t:unix:code>` |
+| `dateTimeToUnixInTz(date, time, timeZone?)` | Converts a wall-clock date and time in an IANA zone to Unix seconds, DST-safe |
+| `parseUnixInput(raw)` | Parses an integer string in seconds or milliseconds, or returns `null` |
+| `decodeSnowflake(raw)` | Returns `{ unixMs, unixSeconds, workerId, processId, increment }`, or `null` |
+| `renderDiscordPreview(unix, code, now?)` | Returns the text Discord's English client would show |
+
+Types: `DiscordFormat`, `DiscordFormatCode`, `DecodedSnowflake`.
+
+## Tests
+
+```
+npm test   # 23 engine checks: DST boundaries in New York, London and Sydney, half-hour offsets, ms detection, Discord's documented snowflake example
+```
+
+## License
+
+MIT

package/dist/discordTimestamp.d.ts

@@ -0,0 +1,49 @@
+export type DiscordFormatCode = 't' | 'T' | 'd' | 'D' | 'f' | 'F' | 'R';
+export interface DiscordFormat {
+    code: DiscordFormatCode;
+    label: string;
+    description: string;
+    example: string;
+}
+export declare const DISCORD_FORMATS: DiscordFormat[];
+export declare function buildTimestampCode(unixSeconds: number, code: DiscordFormatCode): string;
+/**
+ * Parses a raw Unix timestamp typed or pasted by a user (or sent to the API), accepting
+ * either seconds or milliseconds and normalizing to whole seconds. Returns null for
+ * anything that isn't a plain integer.
+ */
+export declare function parseUnixInput(raw: string): {
+    unix: number;
+    wasMs: boolean;
+} | null;
+export interface DecodedSnowflake {
+    unixMs: number;
+    unixSeconds: number;
+    workerId: number;
+    processId: number;
+    increment: number;
+}
+/**
+ * Decodes a Discord snowflake (a message, user, channel, or server ID) into the moment it
+ * was created plus its packed internal fields. Snowflakes exceed JS's safe integer range,
+ * so the bit math runs in BigInt; only the final (much smaller) millisecond timestamp is
+ * converted back to a regular number.
+ */
+export declare function decodeSnowflake(raw: string): DecodedSnowflake | null;
+/**
+ * Renders the preview text exactly as Discord's client would, given the viewer's
+ * clock is `nowSeconds` (only relevant for the 'R' relative format).
+ */
+export declare function renderDiscordPreview(unixSeconds: number, code: DiscordFormatCode, nowSeconds?: number): string;
+/** Builds a unix-seconds timestamp from local date/time input field values in a specific IANA timeZone. */
+export declare function dateTimeToUnixInTz(dateValue: string, timeValue: string, timeZone?: string): number | null;
+/** Builds a unix-seconds timestamp from local date/time input field values (legacy wrapper). */
+export declare function localDateTimeToUnix(dateValue: string, timeValue: string): number | null;
+export declare function nowLocalDateValue(timeZone?: string): string;
+export declare function nowLocalTimeValue(timeZone?: string): string;
+export interface TimezoneOption {
+    value: string;
+    label: string;
+    group: string;
+}
+export declare const POPULAR_TIMEZONES: TimezoneOption[];

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { DISCORD_FORMATS, buildTimestampCode, renderDiscordPreview, dateTimeToUnixInTz, parseUnixInput, decodeSnowflake, } from './discordTimestamp.js';
+export type { DiscordFormat, DiscordFormatCode, DecodedSnowflake } from './discordTimestamp.js';

package/dist/index.js

@@ -0,0 +1,188 @@
+// src/discordTimestamp.ts
+var DISCORD_FORMATS = [
+  { code: "t", label: "Short Time", description: "Hours and minutes", example: "9:01 PM" },
+  { code: "T", label: "Long Time", description: "Hours, minutes and seconds", example: "9:01:00 PM" },
+  { code: "d", label: "Short Date", description: "Numeric date", example: "11/28/2018" },
+  { code: "D", label: "Long Date", description: "Full month name", example: "November 28, 2018" },
+  {
+    code: "f",
+    label: "Short Date/Time",
+    description: "Discord's default when you paste a timestamp",
+    example: "November 28, 2018 9:01 PM"
+  },
+  {
+    code: "F",
+    label: "Long Date/Time",
+    description: "Includes the day of the week",
+    example: "Wednesday, November 28, 2018 9:01 PM"
+  },
+  {
+    code: "R",
+    label: "Relative Time",
+    description: "Counts up or down automatically",
+    example: "3 years ago"
+  }
+];
+function buildTimestampCode(unixSeconds, code) {
+  return `<t:${unixSeconds}:${code}>`;
+}
+var MS_THRESHOLD = 1e11;
+function parseUnixInput(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed || !/^-?\d+$/.test(trimmed)) return null;
+  const value = Number(trimmed);
+  if (!Number.isSafeInteger(value)) return null;
+  const wasMs = Math.abs(value) >= MS_THRESHOLD;
+  return { unix: wasMs ? Math.floor(value / 1e3) : value, wasMs };
+}
+var DISCORD_EPOCH_MS = 1420070400000n;
+function decodeSnowflake(raw) {
+  const trimmed = raw.trim();
+  if (!/^\d{1,20}$/.test(trimmed)) return null;
+  let id;
+  try {
+    id = BigInt(trimmed);
+  } catch {
+    return null;
+  }
+  const timestampMs = (id >> 22n) + DISCORD_EPOCH_MS;
+  if (timestampMs < 0n) return null;
+  const unixMs = Number(timestampMs);
+  if (!Number.isSafeInteger(unixMs)) return null;
+  return {
+    unixMs,
+    unixSeconds: Math.floor(unixMs / 1e3),
+    workerId: Number((id & 0x3e0000n) >> 17n),
+    processId: Number((id & 0x1f000n) >> 12n),
+    increment: Number(id & 0xfffn)
+  };
+}
+var DAY_NAMES = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+var MONTH_NAMES = [
+  "January",
+  "February",
+  "March",
+  "April",
+  "May",
+  "June",
+  "July",
+  "August",
+  "September",
+  "October",
+  "November",
+  "December"
+];
+function pad(n) {
+  return n.toString().padStart(2, "0");
+}
+function formatTime(d, withSeconds) {
+  let hours = d.getHours();
+  const minutes = pad(d.getMinutes());
+  const seconds = pad(d.getSeconds());
+  const suffix = hours >= 12 ? "PM" : "AM";
+  hours = hours % 12;
+  if (hours === 0) hours = 12;
+  return withSeconds ? `${hours}:${minutes}:${seconds} ${suffix}` : `${hours}:${minutes} ${suffix}`;
+}
+function formatRelative(unixSeconds, nowSeconds) {
+  const diff = unixSeconds - nowSeconds;
+  const abs = Math.abs(diff);
+  const future = diff > 0;
+  const units = [
+    [31536e3, "year"],
+    [2592e3, "month"],
+    [604800, "week"],
+    [86400, "day"],
+    [3600, "hour"],
+    [60, "minute"],
+    [1, "second"]
+  ];
+  if (abs < 1) return "now";
+  for (const [secondsPer, name] of units) {
+    const value = Math.floor(abs / secondsPer);
+    if (value >= 1) {
+      const plural = value === 1 ? name : `${name}s`;
+      return future ? `in ${value} ${plural}` : `${value} ${plural} ago`;
+    }
+  }
+  return "now";
+}
+function renderDiscordPreview(unixSeconds, code, nowSeconds = Math.floor(Date.now() / 1e3)) {
+  const d = new Date(unixSeconds * 1e3);
+  switch (code) {
+    case "t":
+      return formatTime(d, false);
+    case "T":
+      return formatTime(d, true);
+    case "d":
+      return `${pad(d.getMonth() + 1)}/${pad(d.getDate())}/${d.getFullYear()}`;
+    case "D":
+      return `${MONTH_NAMES[d.getMonth()]} ${d.getDate()}, ${d.getFullYear()}`;
+    case "f":
+      return `${MONTH_NAMES[d.getMonth()]} ${d.getDate()}, ${d.getFullYear()} ${formatTime(d, false)}`;
+    case "F":
+      return `${DAY_NAMES[d.getDay()]}, ${MONTH_NAMES[d.getMonth()]} ${d.getDate()}, ${d.getFullYear()} ${formatTime(d, false)}`;
+    case "R":
+      return formatRelative(unixSeconds, nowSeconds);
+    default:
+      return "";
+  }
+}
+function dateTimeToUnixInTz(dateValue, timeValue, timeZone) {
+  if (!dateValue || !timeValue) return null;
+  const [y, m, d] = dateValue.split("-").map(Number);
+  const [h, min] = timeValue.split(":").map(Number);
+  if ([y, m, d, h, min].some((n) => Number.isNaN(n))) return null;
+  if (!timeZone || timeZone === "UTC") {
+    if (timeZone === "UTC") {
+      return Math.floor(Date.UTC(y, m - 1, d, h, min, 0) / 1e3);
+    }
+    const date = new Date(y, m - 1, d, h, min, 0, 0);
+    return Math.floor(date.getTime() / 1e3);
+  }
+  try {
+    const utcGuess = Date.UTC(y, m - 1, d, h, min, 0);
+    const formatter = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      year: "numeric",
+      month: "numeric",
+      day: "numeric",
+      hour: "numeric",
+      minute: "numeric",
+      second: "numeric",
+      hour12: false
+    });
+    const offsetAt = (instant) => {
+      const parts = formatter.formatToParts(new Date(instant));
+      let py = 0, pm = 0, pd = 0, ph = 0, pmin = 0, ps = 0;
+      for (const p of parts) {
+        if (p.type === "year") py = parseInt(p.value, 10);
+        else if (p.type === "month") pm = parseInt(p.value, 10);
+        else if (p.type === "day") pd = parseInt(p.value, 10);
+        else if (p.type === "hour") {
+          let val = parseInt(p.value, 10);
+          if (val === 24) val = 0;
+          ph = val;
+        } else if (p.type === "minute") pmin = parseInt(p.value, 10);
+        else if (p.type === "second") ps = parseInt(p.value, 10);
+      }
+      return Date.UTC(py, pm - 1, pd, ph, pmin, ps) - instant;
+    };
+    const offset1 = offsetAt(utcGuess);
+    let actualUtc = utcGuess - offset1;
+    const offset2 = offsetAt(actualUtc);
+    if (offset2 !== offset1) actualUtc = utcGuess - offset2;
+    return Math.floor(actualUtc / 1e3);
+  } catch {
+    const date = new Date(y, m - 1, d, h, min, 0, 0);
+    return Math.floor(date.getTime() / 1e3);
+  }
+}
+export {
+  DISCORD_FORMATS,
+  buildTimestampCode,
+  dateTimeToUnixInTz,
+  decodeSnowflake,
+  parseUnixInput,
+  renderDiscordPreview
+};

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "discord-timestamp-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Make Discord <t:unix:F> timestamp codes, convert a local date and time in any IANA time zone to Unix (DST-safe), parse seconds or milliseconds, and decode Discord snowflake IDs. Zero dependencies.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && esbuild src/index.ts --bundle --format=esm --platform=neutral --target=es2022 --outfile=dist/index.js && tsc -p .",
+    "prepublishOnly": "npm run build && npm test",
+    "test": "tsx test/run.ts"
+  },
+  "keywords": [
+    "discord",
+    "timestamp",
+    "discord-timestamp",
+    "unix",
+    "snowflake",
+    "timezone"
+  ],
+  "homepage": "https://discordtimestampgen.com",
+  "license": "MIT",
+  "author": "Fazal (https://github.com/fazal-bhinder)",
+  "devDependencies": {
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "esbuild": "^0.28.2"
+  },
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fazal-bhinder/discord-timestamp-kit.git"
+  },
+  "bugs": "https://github.com/fazal-bhinder/discord-timestamp-kit/issues",
+  "sideEffects": false
+}