snowrange

Tiny utilities for snowflake time ranges.

Build time ranges, filter IDs, and sort snowflakes without unsafe number conversions.

import { discord } from "snowrange";

discord.between("2026-01-01", "2026-02-01");
// { gte: "1456074443980800000", lt: "1467308467814400000" }

discord.day("2026-06-28");
// { gte: "1520579484057600000", lt: "1520941871923200000" }

discord.contains(discord.day("2026-06-28"), "1520760677994594304");
// true

messages.sort((a, b) => discord.compare(a.id, b.id));
// chronological order

const range = discord.between("2026-01-01", "2026-02-01");

await db.messages.findMany({
  where: {
    id: {
      gte: BigInt(range.gte),
      lt: BigInt(range.lt),
    },
  },
});

Use numeric or BigInt database columns for range queries. For string IDs in memory, use contains and compare.

API

Ranges

discord.min("2026-06-28T12:00:00.001Z");
// "1520760677994594304"

discord.max("2026-06-28T12:00:00.001Z");
// "1520760677998788607"

discord.at("2026-06-28T12:00:00.001Z");
// { gte: "1520760677994594304", lte: "1520760677998788607" }

discord.between("2026-01-01", "2026-02-01");
// { gte: "1456074443980800000", lt: "1467308467814400000" }

discord.before("2026-01-01");
// { lt: "1456074443980800000" }

discord.after("2026-01-01");
// { gte: "1456074443980800000" }

discord.day("2026-06-28");
// { gte: "1520579484057600000", lt: "1520941871923200000" }

discord.contains(discord.day("2026-06-28"), "1520760677994594304");
// true or false

messages.sort((a, b) => discord.compare(a.id, b.id));
// chronological order

Ranges are half-open: gte <= id < lt. This avoids overlap between adjacent windows. Snowflakes are returned as strings so large IDs stay precise.

Timestamps

discord.timestamp("1520760677994594304");
// 1782648000001

discord.date("1520760677994594304");
// Date

Presets

import { discord, twitter } from "snowrange";

Custom Layouts

Use snowrange for custom epochs or bit layouts:

import { snowrange } from "snowrange";

const custom = snowrange({
  epoch: 1420070400000n,
  bits: 22n,
});

bits is the number of lower non-timestamp bits. Discord and Twitter use 22.