@wow-two-beta/ui-vue 0.0.2

package/dist/foundation/crypto/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/foundation/crypto/WebCrypto.ts","../../../src/foundation/crypto/Encoding.ts","../../../src/foundation/crypto/Digest.ts","../../../src/foundation/crypto/Random.ts","../../../src/foundation/crypto/TimingSafeEqual.ts","../../../src/foundation/crypto/HashObject.ts"],"sourcesContent":["// Web Crypto resolution + capability probes — the single place this slice reads the ambient\n// `globalThis.crypto`. Isolated for two reasons.\n//\n// 1. The two capabilities fail INDEPENDENTLY, so they must be probed separately. `crypto.getRandomValues`\n//    is available in every modern runtime, secure context or not; `crypto.subtle` is available ONLY in a\n//    secure context (https, localhost, or a file/extension origin) and is `undefined` on a plain `http://`\n//    page served from a LAN IP — a setup that looks fine in dev and breaks on a staging box. Collapsing\n//    both into one \"crypto available\" flag would report random-byte generation as broken whenever digests\n//    are, and vice versa.\n// 2. The global is read at CALL time, never cached at module scope. Caching would freeze an `undefined`\n//    captured during SSR/hydration into the module for the page's lifetime, and would block a test from\n//    stubbing `globalThis.crypto` to exercise a failure path.\n//\n// SSR contract for the whole slice, stated once here and echoed on each consumer: the pure helpers\n// (`Encoding`, `timingSafeEqual`) never touch this file and run anywhere — SSR, workers, insecure origins.\n// The digest and random helpers THROW at the call site when their capability is missing, rather than\n// returning a sentinel: a silently unhashed value or a non-random \"random\" byte is a security defect that\n// a fallback would hide, so failing loudly is the only safe default. Callers that must branch instead of\n// catch use `isCryptoAvailable()` / `isSubtleAvailable()`.\n\n/** Reads the ambient Web Crypto object, or `undefined` when the runtime has none (older SSR hosts, sandboxes). */\nfunction resolveCrypto(): Crypto | undefined {\n  // Widened through an optional-property view: `globalThis.crypto` is typed non-optional by lib.dom, so a\n  // direct `=== undefined` check would be a TS2367 \"no overlap\" error even though it is exactly the case\n  // this function exists to handle.\n  return (globalThis as { crypto?: Crypto }).crypto;\n}\n\n/** Reads the ambient `SubtleCrypto`, or `undefined` when absent — no Web Crypto at all, or an insecure context. */\nfunction resolveSubtle(): SubtleCrypto | undefined {\n  const source = resolveCrypto();\n  if (source === undefined) return undefined;\n\n  // Same widening rationale as `resolveCrypto`: `Crypto.subtle` is typed non-optional but is genuinely\n  // absent outside a secure context.\n  return (source as { subtle?: SubtleCrypto }).subtle;\n}\n\n/**\n * Reports whether `crypto.getRandomValues` can be called — i.e. whether {@link randomBytes} and\n * {@link randomString} will succeed. True in every browser and in Node 19+, including insecure contexts.\n */\nexport function isCryptoAvailable(): boolean {\n  return typeof resolveCrypto()?.getRandomValues === 'function';\n}\n\n/**\n * Reports whether `crypto.subtle` can be called — i.e. whether the digest helpers will succeed. False\n * outside a **secure context** (plain `http://` on a non-localhost host) even when {@link isCryptoAvailable}\n * is true. Probe this before offering a hash-dependent feature rather than catching the throw.\n */\nexport function isSubtleAvailable(): boolean {\n  return typeof resolveSubtle()?.digest === 'function';\n}\n\n/** Returns the ambient `Crypto`, throwing a diagnostic `Error` when unavailable. Internal — not exported from the barrel. */\nexport function requireCrypto(): Crypto {\n  const source = resolveCrypto();\n  if (source === undefined || typeof source.getRandomValues !== 'function') {\n    throw new Error(\n      'Web Crypto is unavailable: `globalThis.crypto.getRandomValues` is not a function. This runtime ' +\n        'cannot produce cryptographically secure bytes — guard the call with `isCryptoAvailable()`.',\n    );\n  }\n\n  return source;\n}\n\n/** Returns the ambient `SubtleCrypto`, throwing a diagnostic `Error` when unavailable. Internal — not exported from the barrel. */\nexport function requireSubtle(): SubtleCrypto {\n  const subtle = resolveSubtle();\n  if (subtle === undefined || typeof subtle.digest !== 'function') {\n    throw new Error(\n      'Web Crypto `subtle` is unavailable: `globalThis.crypto.subtle` is undefined. `crypto.subtle` is ' +\n        'exposed only in a secure context (https, localhost, or a file/extension origin) — an `http://` ' +\n        'page on a LAN host has `crypto.getRandomValues` but no `subtle`. Guard with `isSubtleAvailable()`.',\n    );\n  }\n\n  return subtle;\n}\n","// Byte <-> text codecs: hex, base64, base64url, UTF-8. Pure and synchronous, touching no Web Crypto at\n// all — so every helper here runs under SSR, in a worker, and on an insecure origin, unlike the digest and\n// random helpers. This is the slice's floor: a digest returns bytes, and bytes are unreadable until one of\n// these renders them (ETag header, cache key, checksum shown to a user).\n//\n// Decisions worth stating:\n//  - Decoders are STRICT — malformed input throws a `TypeError`, never a best-effort result. A digest that\n//    silently mis-decodes compares unequal forever and the bug surfaces far from its cause; a throw is\n//    found on the first run. Both `hexToBytes` and `base64ToBytes` validate the full string shape BEFORE\n//    any conversion, so a partial result is never produced.\n//  - base64url is a first-class pair, not a `.replace()` applied to base64 output at each call site. JWT\n//    segments, URL query values, and filename-safe keys all need `-_` and no `=`, and the padding handling\n//    is exactly where the hand-rolled version goes wrong.\n//  - `btoa`/`atob` do the base64 work rather than a hand-rolled table: both are present in every runtime we\n//    target (browsers, Node 16+, workers, Deno/Bun) and are far faster than a JS loop. Their leniency is\n//    what the validation above wraps — by the time they are called the input is known-good.\n//  - `bytesToBase64` chunks its input. `String.fromCharCode(...bytes)` on a multi-MB array overflows the\n//    argument stack (`RangeError: Maximum call stack size exceeded`) — a bug that only appears on large\n//    files, i.e. in production.\n//  - `bytesToUtf8` is LENIENT: invalid sequences become U+FFFD, `TextDecoder`'s default. That matches what\n//    a caller rendering a payload expects. It also makes UTF-8 a lossy round-trip for arbitrary binary by\n//    definition — hash bytes must go through hex or base64, never through this.\n\n/** Precomputed byte -> 2-char lowercase hex, so `bytesToHex` is a table lookup rather than a per-byte `toString(16).padStart`. */\nconst HEX_BY_BYTE = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, '0'));\n\n/** Matches an even-length run of hex digits (either case), including the empty string. */\nconst HEX_STRING = /^(?:[0-9a-fA-F]{2})*$/;\n\n/**\n * Matches canonical standard base64: whole 4-char groups, then an optional 2- or 3-char tail with correct\n * padding. Rejects a lone trailing char (`{4}n+1` is not a reachable length), over-padding (`YQ===`), and\n * any character outside the standard alphabet — including whitespace and the base64url `-_`.\n */\nconst BASE64_STRING = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}(?:==)?|[A-Za-z0-9+/]{3}=?)?$/;\n\n/** The base64url counterpart of {@link BASE64_STRING} — `-_` in place of `+/`. Padding is tolerated on input though never emitted. */\nconst BASE64URL_STRING = /^(?:[A-Za-z0-9_-]{4})*(?:[A-Za-z0-9_-]{2}(?:==)?|[A-Za-z0-9_-]{3}=?)?$/;\n\n/** Largest slice fed to `String.fromCharCode(...)` at once — keeps the spread well under the engine argument limit. */\nconst FROM_CHAR_CODE_CHUNK = 0x8000;\n\n/** Shared UTF-8 encoder. `TextEncoder` is part of the Encoding standard, present in every target runtime (including SSR), so module-scope construction is safe. */\nconst UTF8_ENCODER = new TextEncoder();\n\n/** Shared UTF-8 decoder, lenient by default — see the file header on why `fatal` is not set. */\nconst UTF8_DECODER = new TextDecoder();\n\n/**\n * Renders bytes as a lowercase hex string (2 chars per byte, no separator) — the canonical way to show a\n * digest, an ETag, or a checksum. Inverse of {@link hexToBytes}.\n */\nexport function bytesToHex(bytes: Uint8Array): string {\n  let hex = '';\n  for (const byte of bytes) hex += HEX_BY_BYTE[byte]!;\n  return hex;\n}\n\n/**\n * Parses a hex string into bytes, accepting either case. **Throws a `TypeError`** when the input has an odd\n * length or contains a non-hex character — a half-parsed digest is never returned. Inverse of\n * {@link bytesToHex}.\n */\nexport function hexToBytes(hex: string): Uint8Array {\n  if (!HEX_STRING.test(hex)) {\n    throw new TypeError(\n      `hexToBytes: expected an even-length string of hex digits, got \"${hex}\" (length ${hex.length}).`,\n    );\n  }\n\n  const bytes = new Uint8Array(hex.length / 2);\n  for (let i = 0; i < bytes.length; i++) {\n    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);\n  }\n\n  return bytes;\n}\n\n/**\n * Encodes bytes as standard, padded base64 (`+`, `/`, `=`). Safe for arbitrarily large inputs — the source\n * is walked in chunks. Inverse of {@link base64ToBytes}; for URL or JWT contexts use\n * {@link bytesToBase64Url}.\n */\nexport function bytesToBase64(bytes: Uint8Array): string {\n  let binary = '';\n  for (let offset = 0; offset < bytes.length; offset += FROM_CHAR_CODE_CHUNK) {\n    binary += String.fromCharCode(...bytes.subarray(offset, offset + FROM_CHAR_CODE_CHUNK));\n  }\n\n  return btoa(binary);\n}\n\n/**\n * Decodes standard base64 into bytes. Padding may be present or omitted, but the string must otherwise be\n * canonical: **throws a `TypeError`** on any character outside `A-Za-z0-9+/=` (whitespace and the base64url\n * `-_` included), on over-padding, and on an impossible length. Inverse of {@link bytesToBase64}.\n */\nexport function base64ToBytes(base64: string): Uint8Array {\n  if (!BASE64_STRING.test(base64)) {\n    throw new TypeError(\n      `base64ToBytes: expected a canonical standard-base64 string (alphabet A-Za-z0-9+/ with optional ` +\n        `= padding), got \"${base64}\".`,\n    );\n  }\n\n  const binary = atob(base64);\n  const bytes = new Uint8Array(binary.length);\n  for (let i = 0; i < bytes.length; i++) bytes[i] = binary.charCodeAt(i);\n\n  return bytes;\n}\n\n/**\n * Encodes bytes as **unpadded** base64url (RFC 4648 §5) — `-_` in place of `+/`, no `=`. This is the form a\n * JWT segment, a URL query value, and a filename-safe cache key all require. Inverse of\n * {@link base64UrlToBytes}.\n */\nexport function bytesToBase64Url(bytes: Uint8Array): string {\n  return bytesToBase64(bytes).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');\n}\n\n/**\n * Decodes base64url into bytes, tolerating the padding that {@link bytesToBase64Url} never emits (some\n * producers add it). **Throws a `TypeError`** on any character outside `A-Za-z0-9-_=` — notably on the\n * standard-base64 `+` and `/`, which signal that {@link base64ToBytes} was the intended decoder.\n */\nexport function base64UrlToBytes(base64Url: string): Uint8Array {\n  if (!BASE64URL_STRING.test(base64Url)) {\n    throw new TypeError(\n      `base64UrlToBytes: expected a base64url string (alphabet A-Za-z0-9-_ with optional = padding), got ` +\n        `\"${base64Url}\".`,\n    );\n  }\n\n  const standard = base64Url.replace(/-/g, '+').replace(/_/g, '/');\n\n  // Re-pad to a 4-char boundary: `atob` accepts unpadded input, but re-padding keeps this on the exact\n  // path `base64ToBytes` validates rather than relying on that leniency.\n  const padding = standard.length % 4 === 0 ? '' : '='.repeat(4 - (standard.length % 4));\n\n  return base64ToBytes(standard + padding);\n}\n\n/** Encodes a string to its UTF-8 bytes — the normalization every digest of a string goes through. Inverse of {@link bytesToUtf8}. */\nexport function utf8ToBytes(text: string): Uint8Array {\n  return UTF8_ENCODER.encode(text);\n}\n\n/**\n * Decodes UTF-8 bytes back to a string. **Lenient**: an invalid sequence becomes U+FFFD rather than\n * throwing, so this is lossy for arbitrary binary — render digest bytes with {@link bytesToHex} or\n * {@link bytesToBase64} instead. Inverse of {@link utf8ToBytes} for any real text.\n */\nexport function bytesToUtf8(bytes: Uint8Array): string {\n  return UTF8_DECODER.decode(bytes);\n}\n","// Cryptographic digests over `crypto.subtle`. Async and non-negotiably so — `SubtleCrypto.digest` returns a\n// promise, and there is no synchronous hash in the platform. A caller that needs a hash inside a render pass\n// must compute it in an effect and hold the result in state; do not go looking for a sync variant.\n//\n// Decisions worth stating:\n//  - The input type is widened to `string | ArrayBuffer | Uint8Array` and normalized here, because every\n//    call site otherwise repeats the same `new TextEncoder().encode(...)` line and they eventually disagree\n//    about encoding. Strings are always UTF-8 — the only encoding that makes a digest reproducible across a\n//    JS client and a .NET backend computing the same hash.\n//  - Bytes are returned, not hex. A digest's natural type is bytes: `timingSafeEqual` consumes them\n//    directly, and the caller picks the rendering (`bytesToHex` for an ETag, `bytesToBase64` for a\n//    `Content-Digest` header). `sha256Hex` exists because hex is the common case and chaining two calls for\n//    it is noise.\n//  - SHA-1 is exposed despite being broken for signatures. It is still the correct tool for a non-adversarial\n//    checksum and, more to the point, for interoperating with systems that already speak it (git object ids,\n//    legacy ETags). Its JSDoc says so; picking it for anything security-bearing is the call site's error.\n//  - `crypto.subtle` is absent outside a secure context, so every function here throws at the call site when\n//    it is missing — see `WebCrypto.ts` for the full contract and `isSubtleAvailable()` for the probe.\n\nimport { bytesToHex, utf8ToBytes } from './Encoding';\nimport { requireSubtle } from './WebCrypto';\n\n/** Accepted digest input: a UTF-8-encoded string, a raw `ArrayBuffer`, or an existing byte view. */\nexport type BinaryInput = string | ArrayBuffer | Uint8Array;\n\n/** A hash algorithm `crypto.subtle.digest` implements. SHA-256 is the default choice; SHA-1 is checksum/interop only. */\nexport type DigestAlgorithm = 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512';\n\n/** Normalizes any {@link BinaryInput} to bytes; strings become UTF-8. Internal — not exported from the barrel. */\nexport function toBytes(data: BinaryInput): Uint8Array {\n  if (typeof data === 'string') return utf8ToBytes(data);\n  if (data instanceof Uint8Array) return data;\n  return new Uint8Array(data);\n}\n\n/**\n * Hashes `data` with the named algorithm and resolves to the raw digest bytes — the general form the named\n * helpers below wrap. **Throws** synchronously when `crypto.subtle` is unavailable (insecure context).\n */\nexport async function digest(algorithm: DigestAlgorithm, data: BinaryInput): Promise<Uint8Array> {\n  const subtle = requireSubtle();\n\n  // TS 5.7 made `Uint8Array` generic over its backing buffer and narrowed `BufferSource` to\n  // `ArrayBufferView<ArrayBuffer>`, which excludes the `SharedArrayBuffer`-backed views the default\n  // `Uint8Array<ArrayBufferLike>` still admits. `subtle.digest` reads any byte view at runtime, so this\n  // widens the static type without changing behaviour — and without narrowing what callers may pass in.\n  const hashed = await subtle.digest(algorithm, toBytes(data) as BufferSource);\n\n  return new Uint8Array(hashed);\n}\n\n/** Computes the SHA-256 digest of `data` (32 bytes) — the default hash for cache keys, ETags, and content addressing. */\nexport function sha256(data: BinaryInput): Promise<Uint8Array> {\n  return digest('SHA-256', data);\n}\n\n/**\n * Computes the SHA-1 digest of `data` (20 bytes). **Not collision-resistant** — use it only for\n * non-adversarial checksums or to interoperate with a system that already speaks SHA-1 (git, legacy ETags).\n * Reach for {@link sha256} everywhere else.\n */\nexport function sha1(data: BinaryInput): Promise<Uint8Array> {\n  return digest('SHA-1', data);\n}\n\n/** Computes the SHA-384 digest of `data` (48 bytes) — the truncated SHA-512 variant used by subresource integrity. */\nexport function sha384(data: BinaryInput): Promise<Uint8Array> {\n  return digest('SHA-384', data);\n}\n\n/** Computes the SHA-512 digest of `data` (64 bytes) — wider margin than SHA-256, and faster on 64-bit hardware. */\nexport function sha512(data: BinaryInput): Promise<Uint8Array> {\n  return digest('SHA-512', data);\n}\n\n/** Computes the SHA-256 digest of `data` as a lowercase 64-char hex string — the ready-to-print form for an ETag or cache key. */\nexport async function sha256Hex(data: BinaryInput): Promise<string> {\n  return bytesToHex(await sha256(data));\n}\n","// Cryptographically secure randomness over `crypto.getRandomValues`. Available in insecure contexts too, so\n// this works where the digest helpers do not — see `WebCrypto.ts` for the split.\n//\n// The one non-obvious thing in this file is **modulo-bias rejection sampling**, and it is the reason\n// `randomString` exists at all rather than being a two-line snippet at each call site. The naive form\n//\n//     alphabet[randomByte % alphabet.length]\n//\n// is skewed. A byte is uniform over 0..255 — 256 values. With a 62-char alphabet, 256 = 4x62 + 8, so the\n// residues 0..7 are each reachable from 5 bytes while residues 8..61 are reachable from only 4. The first\n// 8 characters of the alphabet come up ~25% more often than the rest. That is invisible in a smoke test and\n// measurable by an attacker over enough samples, which is precisely the wrong failure shape for a token.\n//\n// The fix: discard every byte at or above the largest multiple of the alphabet size that fits in 256\n// (`rejectionLimit`), and only then take the modulo. For 62 that limit is 248, so bytes 248..255 are thrown\n// away and the remaining 248 map 4-to-1 onto 62 characters — exactly uniform. The cost is a re-draw for\n// ~3% of bytes, which is why the generator over-draws and loops instead of asking for exactly `length`.\n//\n// `randomStringFrom` takes its byte source as a parameter so the rejection path is testable with a\n// deterministic stream. It is exported from the file but deliberately absent from the barrel — the\n// \"internal\" signal in this repo is absence from `index.ts`, not a naming prefix.\n//\n// Note the scope boundary: this slice does NOT generate identifiers. `foundation/identifiers` owns UUID\n// generation (`Guid.createV4` / `Guid.createV7`) and should be used for entity ids — `randomString` is for\n// opaque tokens, nonces, and suffixes where a UUID's structure would be meaningless.\n\nimport { requireCrypto } from './WebCrypto';\n\n/**\n * Default alphabet: URL-safe base62 (`A-Z`, `a-z`, `0-9`). No `+/=~`, so a generated string is safe in a\n * path segment, a query value, a filename, and an HTML attribute without escaping.\n */\nexport const URL_SAFE_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';\n\n/** `getRandomValues` rejects a view longer than 65536 bytes, so larger requests are filled in passes. */\nconst MAX_BYTES_PER_CALL = 65_536;\n\n/**\n * Returns the exclusive upper bound for an unbiased byte: the largest multiple of `size` that fits in 256.\n * Bytes at or above it must be discarded — see the file header. Internal — not exported from the barrel.\n */\nexport function rejectionLimit(size: number): number {\n  return 256 - (256 % size);\n}\n\n/**\n * Fills `length` cryptographically secure random bytes. Requests above the platform's 65536-byte per-call\n * ceiling are filled in successive passes. **Throws** a `RangeError` on a negative or non-integer length,\n * and an `Error` when Web Crypto is unavailable — never falls back to `Math.random`.\n */\nexport function randomBytes(length: number): Uint8Array {\n  if (!Number.isInteger(length) || length < 0) {\n    throw new RangeError(`randomBytes: length must be a non-negative integer, got ${length}.`);\n  }\n\n  const source = requireCrypto();\n  const bytes = new Uint8Array(length);\n\n  for (let offset = 0; offset < length; offset += MAX_BYTES_PER_CALL) {\n    // `subarray` is a view over the same buffer, so each pass fills `bytes` in place.\n    source.getRandomValues(bytes.subarray(offset, Math.min(offset + MAX_BYTES_PER_CALL, length)));\n  }\n\n  return bytes;\n}\n\n/**\n * Builds a random string of `length` characters from `chars` using the byte stream `nextBytes`, discarding\n * biased bytes (see the file header). The injected source is what makes rejection testable. Internal — not\n * exported from the barrel; call {@link randomString} instead.\n */\nexport function randomStringFrom(\n  length: number,\n  chars: readonly string[],\n  nextBytes: (count: number) => Uint8Array,\n): string {\n  if (!Number.isInteger(length) || length < 0) {\n    throw new RangeError(`randomStringFrom: length must be a non-negative integer, got ${length}.`);\n  }\n\n  if (chars.length === 0 || chars.length > 256) {\n    throw new RangeError(\n      `randomStringFrom: alphabet must hold 1..256 characters, got ${chars.length}. A larger alphabet ` +\n        `cannot be sampled unbiasedly from a single byte.`,\n    );\n  }\n\n  if (length === 0) return '';\n\n  const size = chars.length;\n  const limit = rejectionLimit(size);\n  const picked: string[] = [];\n\n  while (picked.length < length) {\n    const needed = length - picked.length;\n\n    // Over-draw by the expected rejection rate plus a floor, so the common case is a single draw.\n    const bytes = nextBytes(needed + Math.ceil(needed / 4) + 8);\n    if (bytes.length === 0) {\n      throw new RangeError('randomStringFrom: the byte source returned no bytes.');\n    }\n\n    for (const byte of bytes) {\n      if (byte >= limit) continue; // Biased residue — discard rather than fold it in.\n      picked.push(chars[byte % size]!);\n      if (picked.length === length) break;\n    }\n  }\n\n  return picked.join('');\n}\n\n/**\n * Generates a random string of `length` characters, drawn uniformly from `alphabet` (default\n * {@link URL_SAFE_ALPHABET}) with rejection sampling — no modulo bias. Use it for opaque tokens, nonces, and\n * collision-resistant suffixes; use `Guid` from `foundation/identifiers` for entity identifiers.\n *\n * The alphabet is split by code point, so an emoji or astral-plane character counts as one character and is\n * never torn into surrogate halves. It must hold 1..256 code points; duplicated characters skew the result\n * proportionally and are the caller's responsibility.\n */\nexport function randomString(length: number, alphabet: string = URL_SAFE_ALPHABET): string {\n  return randomStringFrom(length, [...alphabet], randomBytes);\n}\n","// Constant-time byte comparison. Exists because `a === b` on a secret is a side channel: the engine's string\n// or array compare returns at the first differing byte, so how long the comparison took reveals how many\n// leading bytes matched. An attacker who can submit guesses and time the response recovers a token one byte\n// at a time — linear work instead of exponential.\n//\n// The fix is to look at every byte regardless: XOR each pair, OR the differences together, and decide once\n// at the end. No branch depends on the data.\n//\n// Length is folded into the same accumulator rather than checked up front with an early `return false`. An\n// early length check is a second, coarser side channel: it separates \"wrong length\" from \"right length,\n// wrong content\" by timing. Seeding the accumulator with `a.length ^ b.length` and walking to the longer of\n// the two collapses both outcomes onto the same path. (The loop bound still tracks the longer input — an\n// input's length is public in essentially every protocol, its *contents* are not.)\n//\n// HONEST LIMITATION, stated because this is security code: JavaScript cannot guarantee constant time. A JIT\n// may deoptimize, bounds checks and `?? 0` are engine-dependent, GC can pause mid-loop, and the runtime is\n// free to reorder. This is a best-effort mitigation that removes the *obvious* early-exit leak, not a\n// hardware guarantee like a constant-time assembly routine. High-value secrets should be compared\n// server-side (Node's `crypto.timingSafeEqual`, .NET's `CryptographicOperations.FixedTimeEquals`), not here.\n\n/**\n * Compares two byte arrays in (best-effort) constant time — no early exit on the first mismatch, and no\n * separate fast path for a length mismatch. Returns true only when both length and every byte match.\n *\n * Use it whenever one side is secret: a digest, an HMAC, a CSRF or session token, a signed URL parameter.\n * For plain non-secret data `===` on the hex form is fine and faster.\n *\n * To compare strings, encode both with `utf8ToBytes` first — a `string` overload is deliberately absent\n * because the encoding step's own timing would need the same care and hiding it here would suggest a\n * guarantee this cannot make. See the file header on what JS can and cannot promise.\n */\nexport function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean {\n  // Seeded with the length difference so a wrong-length input takes the same path as a wrong-content one.\n  let difference = a.length ^ b.length;\n\n  const span = Math.max(a.length, b.length);\n  for (let i = 0; i < span; i++) {\n    // `?? 0` covers the tail of the shorter array; under `noUncheckedIndexedAccess` it is also the honest\n    // type for an indexed read, so the guard and the type narrowing are the same expression.\n    difference |= (a[i] ?? 0) ^ (b[i] ?? 0);\n  }\n\n  return difference === 0;\n}\n","// Stable content hashing for arbitrary values — the \"cache key from a params object\" primitive.\n//\n// `JSON.stringify` is not usable for this directly: it emits keys in insertion order, so `{a:1,b:2}` and\n// `{b:2,a:1}` produce different strings and therefore different keys. Two call sites that build the same\n// query with their properties written in a different order then miss each other's cache entry forever. The\n// bug is invisible locally (one call site, one order) and shows up as a mysteriously low hit rate.\n//\n// So the value is rewritten into a canonical form first — object keys sorted at every depth, array order\n// preserved (order is semantic in an array, incidental in an object) — and only then stringified and\n// hashed.\n//\n// Behaviours that follow from delegating to `JSON.stringify`, documented rather than papered over:\n//  - `toJSON()` is honoured before sorting, so a `Date`/`Temporal` value canonicalizes to its ISO string\n//    instead of collapsing to `{}` the way a blind `Object.keys` walk would leave it.\n//  - `undefined`, functions, and symbol values disappear from objects; `Map`/`Set` hash as `{}`. Feed\n//    plain data, or map those types yourself before hashing.\n//  - A circular reference throws a `TypeError`. The same object appearing twice in a DAG is fine — only a\n//    true cycle is rejected — because the guard is unwound on the way back out.\n//\n// `hashObject` is async and needs `crypto.subtle` (see `WebCrypto.ts`). `stableStringify` is pure and works\n// anywhere, and is exported in its own right: it is often all a caller needs for an in-memory `Map` key,\n// where the digest is pure overhead.\n\nimport { sha256Hex } from './Digest';\n\n/** Recursively canonicalizes a value: `toJSON` first, arrays in order, object keys sorted. `seen` rejects cycles. */\nfunction canonicalize(value: unknown, seen: WeakSet<object>): unknown {\n  if (value === null || typeof value !== 'object') return value;\n\n  // Checked before the object is registered, so a `toJSON` that returns its own receiver terminates here\n  // rather than recursing forever.\n  if (seen.has(value)) {\n    throw new TypeError('stableStringify: circular reference — a value cannot contain itself.');\n  }\n\n  seen.add(value);\n\n  const canonical = canonicalizeObject(value, seen);\n\n  // Unwound so a repeated (but non-cyclic) reference stays legal.\n  seen.delete(value);\n\n  return canonical;\n}\n\n/** Canonicalizes the object cases of {@link canonicalize}, with `value` already registered in `seen`. */\nfunction canonicalizeObject(value: object, seen: WeakSet<object>): unknown {\n  const serializable = value as { toJSON?: () => unknown };\n  if (typeof serializable.toJSON === 'function') {\n    return canonicalize(serializable.toJSON(), seen);\n  }\n\n  if (Array.isArray(value)) {\n    return value.map((item: unknown) => canonicalize(item, seen));\n  }\n\n  const record = value as Record<string, unknown>;\n\n  return Object.fromEntries(\n    Object.keys(record)\n      .sort()\n      .map((key): [string, unknown] => [key, canonicalize(record[key], seen)]),\n  );\n}\n\n/**\n * Serializes `value` to JSON with object keys sorted at every depth, so two structurally equal values\n * always produce the same string regardless of property insertion order. Array order is preserved.\n *\n * Pure and synchronous — usable under SSR and as an in-memory `Map` key without hashing. Returns the\n * literal `'undefined'` for an input `JSON.stringify` would drop entirely (`undefined`, a function, a\n * symbol), so the result is always a string. **Throws a `TypeError`** on a circular reference.\n */\nexport function stableStringify(value: unknown): string {\n  return JSON.stringify(canonicalize(value, new WeakSet())) ?? 'undefined';\n}\n\n/**\n * Hashes any JSON-serializable value to a lowercase 64-char SHA-256 hex string, order-independently:\n * `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` produce the same hash at any nesting depth. The canonical cache key\n * for a params object, a filter set, or a request body.\n *\n * Async and requires a secure context — see {@link stableStringify} for the pure, sync alternative, and\n * `isSubtleAvailable()` to probe before calling.\n */\nexport function hashObject(value: unknown): Promise<string> {\n  return sha256Hex(stableStringify(value));\n}\n"],"names":[],"mappings":"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"}

package/dist/foundation/datetime/Arithmetic.d.ts

@@ -0,0 +1,31 @@
+/** Adds `amount` calendar days (may be negative); preserves wall-clock time across a DST boundary. */
+export declare function addDays(date: Date, amount: number): Date;
+/** Subtracts `amount` calendar days; preserves wall-clock time across a DST boundary. */
+export declare function subDays(date: Date, amount: number): Date;
+/** Adds `amount` weeks (7 calendar days each); preserves wall-clock time across a DST boundary. */
+export declare function addWeeks(date: Date, amount: number): Date;
+/** Subtracts `amount` weeks (7 calendar days each). */
+export declare function subWeeks(date: Date, amount: number): Date;
+/**
+ * Adds `amount` calendar months, clamping the day-of-month to the target month's length —
+ * Jan 31 + 1 = Feb 28 (Feb 29 in a leap year), Mar 31 - 1 = Feb 28. Time-of-day is preserved.
+ */
+export declare function addMonths(date: Date, amount: number): Date;
+/** Subtracts `amount` calendar months, clamping the day-of-month to the target month's length. */
+export declare function subMonths(date: Date, amount: number): Date;
+/** Adds `amount` calendar years, clamping Feb 29 to Feb 28 when the target year isn't a leap year. */
+export declare function addYears(date: Date, amount: number): Date;
+/** Subtracts `amount` calendar years, clamping Feb 29 to Feb 28 when the target year isn't a leap year. */
+export declare function subYears(date: Date, amount: number): Date;
+/** Adds `amount` hours of elapsed time; wall-clock time shifts across a DST boundary. */
+export declare function addHours(date: Date, amount: number): Date;
+/** Subtracts `amount` hours of elapsed time; wall-clock time shifts across a DST boundary. */
+export declare function subHours(date: Date, amount: number): Date;
+/** Adds `amount` minutes of elapsed time. */
+export declare function addMinutes(date: Date, amount: number): Date;
+/** Subtracts `amount` minutes of elapsed time. */
+export declare function subMinutes(date: Date, amount: number): Date;
+/** Adds `amount` seconds of elapsed time. */
+export declare function addSeconds(date: Date, amount: number): Date;
+/** Subtracts `amount` seconds of elapsed time. */
+export declare function subSeconds(date: Date, amount: number): Date;

package/dist/foundation/datetime/Boundaries.d.ts

@@ -0,0 +1,24 @@
+/** Day index a week starts on: `0` Sunday … `6` Saturday. */
+export type WeekStartsOn = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** Returns the first instant of `date`'s local day (00:00:00.000). */
+export declare function startOfDay(date: Date): Date;
+/** Returns the last instant of `date`'s local day (23:59:59.999). */
+export declare function endOfDay(date: Date): Date;
+/**
+ * Returns the first instant of `date`'s week. `weekStartsOn` defaults to `1` (Monday, ISO-8601);
+ * pass `0` for a Sunday-first (US) calendar.
+ */
+export declare function startOfWeek(date: Date, weekStartsOn?: WeekStartsOn): Date;
+/**
+ * Returns the last instant of `date`'s week (day 7 at 23:59:59.999). `weekStartsOn` defaults to `1`
+ * (Monday, ISO-8601); pass `0` for a Sunday-first (US) calendar.
+ */
+export declare function endOfWeek(date: Date, weekStartsOn?: WeekStartsOn): Date;
+/** Returns the first instant of the 1st of `date`'s month. */
+export declare function startOfMonth(date: Date): Date;
+/** Returns the last instant of the last day of `date`'s month (28th-31st at 23:59:59.999). */
+export declare function endOfMonth(date: Date): Date;
+/** Returns the first instant of Jan 1 of `date`'s year. */
+export declare function startOfYear(date: Date): Date;
+/** Returns the last instant of Dec 31 of `date`'s year. */
+export declare function endOfYear(date: Date): Date;

package/dist/foundation/datetime/Comparison.d.ts

@@ -0,0 +1,43 @@
+import { WeekStartsOn } from './Boundaries';
+/** Tunes whether a range test counts its bounds. */
+export interface BetweenOptions {
+    /** Count `start`/`end` themselves as inside the range. Defaults to `true`. */
+    readonly inclusive?: boolean;
+}
+/** True when both dates fall on the same local calendar day. */
+export declare function isSameDay(a: Date, b: Date): boolean;
+/**
+ * True when both dates fall in the same week. `weekStartsOn` defaults to `1` (Monday, ISO-8601) and
+ * must match the value used elsewhere in the same calendar — Dec 31 and Jan 1 can share a week.
+ */
+export declare function isSameWeek(a: Date, b: Date, weekStartsOn?: WeekStartsOn): boolean;
+/** True when both dates fall in the same month of the same year. */
+export declare function isSameMonth(a: Date, b: Date): boolean;
+/** True when both dates fall in the same calendar year. */
+export declare function isSameYear(a: Date, b: Date): boolean;
+/** True when `date` is strictly earlier than `other` (millisecond precision). */
+export declare function isBefore(date: Date, other: Date): boolean;
+/** True when `date` is strictly later than `other` (millisecond precision). */
+export declare function isAfter(date: Date, other: Date): boolean;
+/**
+ * True when `date` falls in `[start, end]` — bounds included by default, excluded with
+ * `{ inclusive: false }`. Returns `false` for a reversed range (`start` after `end`) and for any
+ * invalid input; the bounds are never swapped for you.
+ */
+export declare function isBetween(date: Date, start: Date, end: Date, options?: BetweenOptions): boolean;
+/** True when `date` falls on the same local day as `now` (defaults to the current clock; inject for tests). */
+export declare function isToday(date: Date, now?: Date): boolean;
+/** True when `date` is strictly before `now` (defaults to the current clock; inject for tests). */
+export declare function isPast(date: Date, now?: Date): boolean;
+/** True when `date` is strictly after `now` (defaults to the current clock; inject for tests). */
+export declare function isFuture(date: Date, now?: Date): boolean;
+/** Returns a copy of the earliest of the given dates. Invalid dates are ignored unless all of them are. */
+export declare function minDate(first: Date, ...rest: readonly Date[]): Date;
+/** Returns a copy of the latest of the given dates. Invalid dates are ignored unless all of them are. */
+export declare function maxDate(first: Date, ...rest: readonly Date[]): Date;
+/**
+ * Returns a copy of `date` pulled inside `[min, max]`. Either bound may be omitted or `null` to leave
+ * that side open. Bounds are applied low-then-high, so a caller-inverted pair (`min` after `max`)
+ * resolves to `max`.
+ */
+export declare function clampDate(date: Date, min?: Date | null, max?: Date | null): Date;

package/dist/foundation/datetime/Difference.d.ts

@@ -0,0 +1,28 @@
+/** Signed whole SECONDS from `from` to `to`, truncated toward zero. Positive when `to` is later. */
+export declare function differenceInSeconds(from: Date, to: Date): number;
+/** Signed whole MINUTES from `from` to `to`, truncated toward zero. Positive when `to` is later. */
+export declare function differenceInMinutes(from: Date, to: Date): number;
+/** Signed whole HOURS of elapsed time from `from` to `to`, truncated toward zero. Positive when `to` is later. */
+export declare function differenceInHours(from: Date, to: Date): number;
+/**
+ * Signed CALENDAR days from `from` to `to`. Both endpoints are snapped to local start-of-day first, so
+ * the result counts date boundaries crossed rather than 24-hour blocks, and a DST transition never
+ * produces an off-by-one. Positive when `to` is later.
+ */
+export declare function differenceInDays(from: Date, to: Date): number;
+/**
+ * Signed whole WEEKS from `from` to `to`, derived from {@link differenceInDays} and truncated toward
+ * zero — 13 calendar days apart is 1 week. Positive when `to` is later.
+ */
+export declare function differenceInWeeks(from: Date, to: Date): number;
+/**
+ * Signed whole calendar MONTHS from `from` to `to`, truncated toward zero — a partial trailing month is
+ * dropped, so Jan 15 → Feb 14 is 0. Agrees with `addMonths` clamping (Jan 31 → Feb 28 is 1). Positive
+ * when `to` is later.
+ */
+export declare function differenceInMonths(from: Date, to: Date): number;
+/**
+ * Signed whole calendar YEARS from `from` to `to`, derived from {@link differenceInMonths} and truncated
+ * toward zero — the usual "age in years" calculation. Positive when `to` is later.
+ */
+export declare function differenceInYears(from: Date, to: Date): number;

package/dist/foundation/datetime/Internals.d.ts

@@ -0,0 +1,12 @@
+/** Milliseconds in one second. */
+export declare const MS_PER_SECOND = 1000;
+/** Milliseconds in one minute. */
+export declare const MS_PER_MINUTE = 60000;
+/** Milliseconds in one hour. */
+export declare const MS_PER_HOUR = 3600000;
+/** Milliseconds in one 24-hour period (nominal — a DST day is 23 or 25 hours). */
+export declare const MS_PER_DAY = 86400000;
+/** Copies a `Date` by timestamp. An invalid input yields an equally-invalid copy (`NaN` time). */
+export declare function cloneDate(date: Date): Date;
+/** Returns the length in days of `monthIndex` (0-11) in `year`, leap years included. */
+export declare function daysInMonth(year: number, monthIndex: number): number;

package/dist/foundation/datetime/Interval.d.ts

@@ -0,0 +1,38 @@
+/** A date range with inclusive bounds. A reversed range (`start` after `end`) is treated as empty. */
+export interface DateInterval {
+    /** Lower bound of the range. */
+    readonly start: Date;
+    /** Upper bound of the range. */
+    readonly end: Date;
+}
+/** Tunes whether an overlap test counts a shared endpoint. */
+export interface OverlapOptions {
+    /**
+     * Treat both ranges as closed `[start, end]`, so ranges that merely touch at an endpoint count as
+     * overlapping. Defaults to `false` (half-open `[start, end)` — touching ranges do not overlap).
+     */
+    readonly inclusive?: boolean;
+}
+/**
+ * Returns one `Date` per calendar day from `start` to `end`, both ends INCLUSIVE, each snapped to local
+ * start-of-day. Returns `[]` when the range is reversed or either bound is invalid.
+ *
+ * Day stepping is calendar-based (not `+24h`), so a DST transition inside the range neither duplicates
+ * nor skips a day.
+ */
+export declare function eachDayOfInterval(start: Date, end: Date): Date[];
+/**
+ * True when `date` falls inside `interval`, bounds INCLUSIVE. Returns `false` for a reversed interval or
+ * any invalid date. Compares at millisecond precision — pass day boundaries
+ * (`startOfDay`/`endOfDay`) when a whole-day test is meant.
+ */
+export declare function isWithinInterval(date: Date, interval: DateInterval): boolean;
+/**
+ * True when ranges `a` and `b` share any time. Half-open by default, so ranges that only touch at an
+ * endpoint do NOT overlap; pass `{ inclusive: true }` to count a shared endpoint as an overlap.
+ * Returns `false` when either range is reversed or holds an invalid date.
+ *
+ * A zero-length range (`start` equal to `end`) never overlaps anything under the default half-open
+ * semantics; it does under `{ inclusive: true }`.
+ */
+export declare function overlaps(a: DateInterval, b: DateInterval, options?: OverlapOptions): boolean;

package/dist/foundation/datetime/IsoDate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Narrows `value` to a usable `Date` — a `Date` instance whose time is not `NaN`. Use it before any
+ * op in this slice when the input came from outside (props, storage, a hand-built `new Date(input)`).
+ */
+export declare function isValidDate(value: unknown): value is Date;
+/**
+ * Parses an ISO-8601 `YYYY-MM-DD` or `YYYY-MM-DDTHH:mm[:ss[.sss]][Z|±HH:mm]` string, returning `null`
+ * for any other input — including a well-shaped but impossible date such as `2026-02-30`. Never returns
+ * an `Invalid Date`.
+ *
+ * A date-only string resolves to LOCAL midnight (not UTC midnight, which is what `new Date(string)`
+ * would give). A date-time string keeps standard semantics: with an offset it is that absolute instant,
+ * without one it is local wall-clock.
+ */
+export declare function parseIsoDate(value: string): Date | null;
+/**
+ * Serializes `date` to `YYYY-MM-DD` using its LOCAL calendar fields — the day never shifts by timezone
+ * the way `toISOString().slice(0, 10)` does. Round-trips exactly with {@link parseIsoDate}.
+ *
+ * Throws a `RangeError` on an invalid `Date`, or on a year outside `0000`-`9999` (which ISO-8601 can
+ * only express with the extended `±YYYYYY` form this function does not emit). Guard with
+ * {@link isValidDate} when the input is untrusted.
+ */
+export declare function toIsoDateString(date: Date): string;

package/dist/foundation/datetime/index.d.ts

@@ -0,0 +1,6 @@
+export { addDays, subDays, addWeeks, subWeeks, addMonths, subMonths, addYears, subYears, addHours, subHours, addMinutes, subMinutes, addSeconds, subSeconds, } from './Arithmetic';
+export { startOfDay, endOfDay, startOfWeek, endOfWeek, startOfMonth, endOfMonth, startOfYear, endOfYear, type WeekStartsOn, } from './Boundaries';
+export { isSameDay, isSameWeek, isSameMonth, isSameYear, isBefore, isAfter, isBetween, isToday, isPast, isFuture, minDate, maxDate, clampDate, type BetweenOptions, } from './Comparison';
+export { differenceInSeconds, differenceInMinutes, differenceInHours, differenceInDays, differenceInWeeks, differenceInMonths, differenceInYears, } from './Difference';
+export { eachDayOfInterval, isWithinInterval, overlaps, type DateInterval, type OverlapOptions, } from './Interval';
+export { isValidDate, parseIsoDate, toIsoDateString } from './IsoDate';

package/dist/foundation/datetime/index.js

@@ -0,0 +1,302 @@
+const MS_PER_SECOND = 1e3;
+const MS_PER_MINUTE = 6e4;
+const MS_PER_HOUR = 36e5;
+const MS_PER_DAY = 864e5;
+function cloneDate(date) {
+  return new Date(date.getTime());
+}
+function daysInMonth(year, monthIndex) {
+  const probe = new Date(2e3, 0, 1, 12);
+  probe.setFullYear(year, monthIndex + 1, 0);
+  return probe.getDate();
+}
+function addDays(date, amount) {
+  const result = cloneDate(date);
+  result.setDate(result.getDate() + amount);
+  return result;
+}
+function subDays(date, amount) {
+  return addDays(date, -amount);
+}
+function addWeeks(date, amount) {
+  return addDays(date, amount * 7);
+}
+function subWeeks(date, amount) {
+  return addDays(date, -amount * 7);
+}
+function addMonths(date, amount) {
+  const result = cloneDate(date);
+  const day = result.getDate();
+  result.setDate(1);
+  result.setMonth(result.getMonth() + amount);
+  result.setDate(Math.min(day, daysInMonth(result.getFullYear(), result.getMonth())));
+  return result;
+}
+function subMonths(date, amount) {
+  return addMonths(date, -amount);
+}
+function addYears(date, amount) {
+  return addMonths(date, amount * 12);
+}
+function subYears(date, amount) {
+  return addMonths(date, -amount * 12);
+}
+function addHours(date, amount) {
+  const result = cloneDate(date);
+  result.setTime(result.getTime() + amount * MS_PER_HOUR);
+  return result;
+}
+function subHours(date, amount) {
+  return addHours(date, -amount);
+}
+function addMinutes(date, amount) {
+  const result = cloneDate(date);
+  result.setTime(result.getTime() + amount * MS_PER_MINUTE);
+  return result;
+}
+function subMinutes(date, amount) {
+  return addMinutes(date, -amount);
+}
+function addSeconds(date, amount) {
+  const result = cloneDate(date);
+  result.setTime(result.getTime() + amount * MS_PER_SECOND);
+  return result;
+}
+function subSeconds(date, amount) {
+  return addSeconds(date, -amount);
+}
+function startOfDay(date) {
+  const result = cloneDate(date);
+  result.setHours(0, 0, 0, 0);
+  return result;
+}
+function endOfDay(date) {
+  const result = cloneDate(date);
+  result.setHours(23, 59, 59, 999);
+  return result;
+}
+function startOfWeek(date, weekStartsOn = 1) {
+  const offset = (date.getDay() - weekStartsOn + 7) % 7;
+  return startOfDay(subDays(date, offset));
+}
+function endOfWeek(date, weekStartsOn = 1) {
+  return endOfDay(addDays(startOfWeek(date, weekStartsOn), 6));
+}
+function startOfMonth(date) {
+  const result = cloneDate(date);
+  result.setDate(1);
+  result.setHours(0, 0, 0, 0);
+  return result;
+}
+function endOfMonth(date) {
+  const result = cloneDate(date);
+  result.setMonth(result.getMonth() + 1, 0);
+  result.setHours(23, 59, 59, 999);
+  return result;
+}
+function startOfYear(date) {
+  const result = cloneDate(date);
+  result.setMonth(0, 1);
+  result.setHours(0, 0, 0, 0);
+  return result;
+}
+function endOfYear(date) {
+  const result = cloneDate(date);
+  result.setMonth(11, 31);
+  result.setHours(23, 59, 59, 999);
+  return result;
+}
+const DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+const DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2})?(\.\d{1,9})?(Z|[+-]\d{2}:?\d{2})?$/;
+function isValidDate(value) {
+  return value instanceof Date && !Number.isNaN(value.getTime());
+}
+function parseIsoDate(value) {
+  if (typeof value !== "string") return null;
+  const text = value.trim();
+  if (text === "") return null;
+  const dateOnly = DATE_ONLY.exec(text);
+  if (dateOnly !== null) {
+    const year = Number(dateOnly[1]);
+    const month = Number(dateOnly[2]);
+    const day = Number(dateOnly[3]);
+    const result = new Date(2e3, 0, 1, 12);
+    result.setFullYear(year, month - 1, day);
+    result.setHours(0, 0, 0, 0);
+    if (result.getFullYear() !== year || result.getMonth() !== month - 1 || result.getDate() !== day) {
+      return null;
+    }
+    return result;
+  }
+  if (!DATE_TIME.test(text)) return null;
+  const parsed = new Date(text);
+  return isValidDate(parsed) ? parsed : null;
+}
+function toIsoDateString(date) {
+  if (!isValidDate(date)) {
+    throw new RangeError("toIsoDateString: expected a valid Date, got an invalid one");
+  }
+  const year = date.getFullYear();
+  if (year < 0 || year > 9999) {
+    throw new RangeError(`toIsoDateString: year ${year} is outside the representable range 0000-9999`);
+  }
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${String(year).padStart(4, "0")}-${month}-${day}`;
+}
+function isSameDay(a, b) {
+  return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+}
+function isSameWeek(a, b, weekStartsOn = 1) {
+  return startOfWeek(a, weekStartsOn).getTime() === startOfWeek(b, weekStartsOn).getTime();
+}
+function isSameMonth(a, b) {
+  return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
+}
+function isSameYear(a, b) {
+  return a.getFullYear() === b.getFullYear();
+}
+function isBefore(date, other) {
+  return date.getTime() < other.getTime();
+}
+function isAfter(date, other) {
+  return date.getTime() > other.getTime();
+}
+function isBetween(date, start, end, options) {
+  const value = date.getTime();
+  const from = start.getTime();
+  const to = end.getTime();
+  if (Number.isNaN(value) || Number.isNaN(from) || Number.isNaN(to)) return false;
+  if (from > to) return false;
+  return options?.inclusive === false ? value > from && value < to : value >= from && value <= to;
+}
+function isToday(date, now = /* @__PURE__ */ new Date()) {
+  return isSameDay(date, now);
+}
+function isPast(date, now = /* @__PURE__ */ new Date()) {
+  return isBefore(date, now);
+}
+function isFuture(date, now = /* @__PURE__ */ new Date()) {
+  return isAfter(date, now);
+}
+function select(first, rest, keep) {
+  const candidates = [first, ...rest].filter(isValidDate);
+  let best = candidates.at(0) ?? first;
+  for (const candidate of candidates) {
+    if (keep(candidate.getTime(), best.getTime())) best = candidate;
+  }
+  return cloneDate(best);
+}
+function minDate(first, ...rest) {
+  return select(first, rest, (candidate, best) => candidate < best);
+}
+function maxDate(first, ...rest) {
+  return select(first, rest, (candidate, best) => candidate > best);
+}
+function clampDate(date, min, max) {
+  let result = date;
+  if (min != null && isBefore(result, min)) result = min;
+  if (max != null && isAfter(result, max)) result = max;
+  return cloneDate(result);
+}
+function differenceInSeconds(from, to) {
+  return Math.trunc((to.getTime() - from.getTime()) / MS_PER_SECOND);
+}
+function differenceInMinutes(from, to) {
+  return Math.trunc((to.getTime() - from.getTime()) / MS_PER_MINUTE);
+}
+function differenceInHours(from, to) {
+  return Math.trunc((to.getTime() - from.getTime()) / MS_PER_HOUR);
+}
+function differenceInDays(from, to) {
+  return Math.round((startOfDay(to).getTime() - startOfDay(from).getTime()) / MS_PER_DAY);
+}
+function differenceInWeeks(from, to) {
+  return Math.trunc(differenceInDays(from, to) / 7);
+}
+function differenceInMonths(from, to) {
+  const target = to.getTime();
+  let months = (to.getFullYear() - from.getFullYear()) * 12 + (to.getMonth() - from.getMonth());
+  if (Number.isNaN(months) || Number.isNaN(target)) return NaN;
+  if (months > 0 && addMonths(from, months).getTime() > target) months -= 1;
+  else if (months < 0 && addMonths(from, months).getTime() < target) months += 1;
+  return months;
+}
+function differenceInYears(from, to) {
+  return Math.trunc(differenceInMonths(from, to) / 12);
+}
+function eachDayOfInterval(start, end) {
+  const last = startOfDay(end).getTime();
+  const days = [];
+  let cursor = startOfDay(start);
+  while (cursor.getTime() <= last) {
+    days.push(cursor);
+    cursor = addDays(cursor, 1);
+  }
+  return days;
+}
+function isWithinInterval(date, interval) {
+  return isBetween(date, interval.start, interval.end);
+}
+function overlaps(a, b, options) {
+  const aStart = a.start.getTime();
+  const aEnd = a.end.getTime();
+  const bStart = b.start.getTime();
+  const bEnd = b.end.getTime();
+  if (Number.isNaN(aStart) || Number.isNaN(aEnd) || Number.isNaN(bStart) || Number.isNaN(bEnd)) return false;
+  if (aStart > aEnd || bStart > bEnd) return false;
+  if (options?.inclusive === true) return aStart <= bEnd && bStart <= aEnd;
+  if (aStart === aEnd || bStart === bEnd) return false;
+  return aStart < bEnd && bStart < aEnd;
+}
+export {
+  addDays,
+  addHours,
+  addMinutes,
+  addMonths,
+  addSeconds,
+  addWeeks,
+  addYears,
+  clampDate,
+  differenceInDays,
+  differenceInHours,
+  differenceInMinutes,
+  differenceInMonths,
+  differenceInSeconds,
+  differenceInWeeks,
+  differenceInYears,
+  eachDayOfInterval,
+  endOfDay,
+  endOfMonth,
+  endOfWeek,
+  endOfYear,
+  isAfter,
+  isBefore,
+  isBetween,
+  isFuture,
+  isPast,
+  isSameDay,
+  isSameMonth,
+  isSameWeek,
+  isSameYear,
+  isToday,
+  isValidDate,
+  isWithinInterval,
+  maxDate,
+  minDate,
+  overlaps,
+  parseIsoDate,
+  startOfDay,
+  startOfMonth,
+  startOfWeek,
+  startOfYear,
+  subDays,
+  subHours,
+  subMinutes,
+  subMonths,
+  subSeconds,
+  subWeeks,
+  subYears,
+  toIsoDateString
+};
+//# sourceMappingURL=index.js.map