hanzio 1.2.0 → 2.0.0

package/src/string/index.ts

@@ -1,3 +1,5 @@
+import type { Result } from '../promise'
+
 export type JsonValue =
 	| string
 	| number
@@ -8,18 +10,44 @@ export type JsonValue =
 export type JsonObject = { [key: string]: JsonValue | undefined }
 export type JsonArray = Array<JsonValue | undefined>
 
+/**
+ * Parses the first number-like token in a string. Only a `-` directly before
+ * the digits is a sign, so `'2024-01-05'` gives `2024`. Whitespace and the
+ * separator that isn't `decimalSeparator` are treated as thousands separators:
+ * `'1,234.56'` gives `1234.56`, and `'1.234,56'` with `decimalSeparator: ','`
+ * gives `1234.56`.
+ */
 export function extractNumber(
-	value: string | null | undefined
+	value: string | null | undefined,
+	options: { decimalSeparator?: '.' | ',' } = {}
 ): number | undefined {
-	if (!value?.trim()) return undefined
-
-	const cleanedValue = value.replace(/[^\d.,-]/g, '')
-	if (!cleanedValue) return undefined
+	const { decimalSeparator = '.' } = options
+	const decimal = decimalSeparator === '.' ? '\\.' : ','
+	const thousands = decimalSeparator === '.' ? ',' : '\\.'
+	// First number-like token. A thousands separator (or whitespace) only counts
+	// when exactly three digits follow it, so '12,5' reads as 12, not 125.
+	const token = value?.match(
+		new RegExp(
+			`-?(?:\\d+(?:(?:${thousands}|\\s)\\d{3}(?!\\d))*(?:${decimal}\\d+)?|${decimal}\\d+)`
+		)
+	)?.[0]
+	if (!token) return undefined
 
-	const parsedNumber = Number.parseFloat(cleanedValue)
+	const parsedNumber = Number.parseFloat(
+		token
+			.replace(/\s/g, '')
+			.replaceAll(decimalSeparator === '.' ? ',' : '.', '')
+			.replace(decimalSeparator, '.')
+	)
 	return Number.isNaN(parsedNumber) ? undefined : parsedNumber
 }
 
+/**
+ * A stable, short, non-cryptographic hash key (32-bit, 8 hex chars) for
+ * JSON-like input. Object key order and query-string parameter order don't
+ * matter. Collisions become likely above ~10k distinct inputs; use `sha256Id`
+ * where that matters.
+ */
 export function generateId(input: JsonValue | undefined): string {
 	const data = normalizeIdInput(input)
 	let hash = 0
@@ -33,32 +61,234 @@ export function generateId(input: JsonValue | undefined): string {
 	return Math.abs(hash).toString(16).padStart(8, '0')
 }
 
-export function slugify(value: string): string {
-	const source =
-		'àáâäæãåāăąçćčđďèéêëēėęěğǵḧîïíīįìłḿñńǹňôöòóœøōõṕŕřßśšşșťțûüùúūǘůűųẃẍÿýžźż·/_,:;'
-	const replacement =
-		'aaaaaaaaaacccddeeeeeeeegghiiiiiilmnnnnooooooooprrsssssttuuuuuuuuuwxyyzzz------'
-	const specialCharacterPattern = new RegExp(source.split('').join('|'), 'g')
+/** Like `generateId`, but a SHA-256 hex digest truncated to `length` chars. */
+export async function sha256Id(
+	input: JsonValue | undefined,
+	length = 16
+): Promise<string> {
+	const digest = await crypto.subtle.digest(
+		'SHA-256',
+		new TextEncoder().encode(normalizeIdInput(input))
+	)
+	return Array.from(new Uint8Array(digest), (byte) =>
+		byte.toString(16).padStart(2, '0')
+	)
+		.join('')
+		.slice(0, length)
+}
+
+// Letters that NFKD doesn't split into a base letter plus a combining mark.
+const UNDECOMPOSED_LETTERS: Record<string, string> = {
+	æ: 'ae',
+	Æ: 'AE',
+	ø: 'o',
+	Ø: 'O',
+	œ: 'oe',
+	Œ: 'OE',
+	ß: 'ss',
+	ẞ: 'SS',
+	đ: 'd',
+	Đ: 'D',
+	ł: 'l',
+	Ł: 'L',
+	þ: 'th',
+	Þ: 'TH',
+	ð: 'd',
+	Ð: 'D'
+}
 
+/** Removes accents and spells out letters like `æ`, `ø` and `ß` in ASCII. */
+function stripAccents(value: string): string {
 	return value
-		.toString()
-		.toLowerCase()
-		.replace(/\s+/g, '-')
-		.replace(specialCharacterPattern, (character) =>
-			replacement.charAt(source.indexOf(character))
+		.normalize('NFKD')
+		.replace(/\p{M}/gu, '')
+		.replace(
+			/[æøœßđłþðÆØŒẞĐŁÞÐ]/g,
+			(letter) => UNDECOMPOSED_LETTERS[letter] ?? ''
 		)
-		.replace(/&/g, '-and-')
-		.replace(/[^\w-]+/g, '')
-		.replace(/--+/g, '-')
-		.replace(/^-+/, '')
-		.replace(/-+$/, '')
+}
+
+export type SlugifyOptions = {
+	/** Placed between words (default `'-'`). */
+	separator?: string
+	/** Default `true`. */
+	lowercase?: boolean
+	/** Cuts the slug to at most this many characters, without a trailing separator. */
+	maxLength?: number
+}
+
+/**
+ * Turns text into a URL slug: strips accents, turns `&` into `and`, splits
+ * words on whitespace and `-_/,:;·`, and drops every other non-ASCII-alphanumeric
+ * character.
+ */
+export function slugify(value: string, options: SlugifyOptions = {}): string {
+	const { separator = '-', lowercase = true, maxLength } = options
+	const slug = stripAccents(value)
+		.replace(/&/g, ' and ')
+		.replace(/[\s\-_/,:;·]+/g, ' ')
+		.replace(/[^a-zA-Z0-9 ]/g, '')
+		.trim()
+		.split(/ +/)
+		.join(separator)
+	const cased = lowercase ? slug.toLowerCase() : slug
+
+	if (maxLength === undefined || cased.length <= maxLength) return cased
+	// Words are alphanumeric, so anything non-alphanumeric at the end is
+	// (part of) a separator.
+	return cased.slice(0, maxLength).replace(/[^a-zA-Z0-9]+$/, '')
+}
+
+/**
+ * JSON.stringify with sorted object keys, so `{ a, b }` and `{ b, a }` produce
+ * the same string. Also encodes values JSON drops or rejects: `bigint`,
+ * `Map` and `Set`. Use it for cache and dedupe keys.
+ */
+export function stableStringify(value: unknown): string {
+	return (
+		JSON.stringify(value, (_key, item: unknown) => {
+			if (typeof item === 'bigint') return `${item}n`
+			if (item instanceof Map) return { $map: [...item.entries()] }
+			if (item instanceof Set) return { $set: [...item] }
+			if (item && typeof item === 'object' && !Array.isArray(item)) {
+				const record = item as Record<string, unknown>
+				return Object.fromEntries(
+					Object.keys(record)
+						.sort()
+						.map((key) => [key, record[key]])
+				)
+			}
+			return item
+		}) ?? 'undefined'
+	)
+}
+
+/**
+ * Cuts text to at most `maxLength` user-visible characters, ellipsis included.
+ * Never splits an emoji or accented letter, and drops whitespace before the
+ * ellipsis. With `wordBoundary`, cuts at the last space unless that would leave
+ * nothing.
+ */
+export function truncate(
+	text: string,
+	maxLength: number,
+	options: { ellipsis?: string; wordBoundary?: boolean } = {}
+): string {
+	const { ellipsis = '…', wordBoundary = false } = options
+	const characters = graphemes(text)
+	if (characters.length <= maxLength) return text
+
+	const ellipsisCharacters = graphemes(ellipsis)
+	const room = maxLength - ellipsisCharacters.length
+	if (room <= 0) return ellipsisCharacters.slice(0, maxLength).join('')
+
+	let cut = characters.slice(0, room).join('')
+	if (wordBoundary && !/^\s/.test(characters[room] ?? '')) {
+		const lastSpace = cut.search(/\s\S*$/)
+		if (lastSpace > 0) cut = cut.slice(0, lastSpace)
+	}
+	return cut.trimEnd() + ellipsis
+}
+
+/** Collapses every whitespace run (NBSP and newlines included) to one space and trims. */
+export function normalizeWhitespace(text: string): string {
+	return text.replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * Escapes text for literal use in a `RegExp`. `-` becomes `\x2d` so the result
+ * is also valid with the `u` and `v` flags.
+ */
+export function escapeRegExp(text: string): string {
+	return text.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&').replace(/-/g, '\\x2d')
+}
+
+/** Lowercases and strips accents, so `'Ærø Café'` becomes `'aero cafe'`. */
+export function foldForSearch(text: string): string {
+	return stripAccents(text).toLowerCase()
+}
+
+/**
+ * True when every whitespace-separated query term appears in at least one
+ * field, ignoring case and accents. An empty query matches everything.
+ */
+export function matchesSearch(
+	query: string,
+	...fields: (string | null | undefined)[]
+): boolean {
+	const haystack = foldForSearch(fields.filter(Boolean).join('\n'))
+	return foldForSearch(query)
+		.split(/\s+/)
+		.every((term) => haystack.includes(term))
+}
+
+const HAS_LETTER = /\p{L}/u
+
+/**
+ * Up to `max` (default 2) uppercase letters for an avatar, or `''` when the
+ * value has no letters (phone numbers, `'—'`). One word gives its first
+ * letters (`'Ada'` → `'AD'`), several give first and last (`'Hans Kristoffer
+ * Hansen'` → `'HH'`). An email is read as its local part without the `+tag`:
+ * `'ada.lovelace+news@x.com'` → `'AL'`.
+ */
+export function initials(
+	name: string | null | undefined,
+	options: { max?: number } = {}
+): string {
+	const { max = 2 } = options
+	const trimmed = name?.trim() ?? ''
+	const source = /^[^\s@]+@[^\s@]+$/.test(trimmed)
+		? (trimmed.split('@')[0] ?? '').replace(/\+.*$/, '').replace(/[._-]+/g, ' ')
+		: trimmed
+	const words = source.split(/\s+/).filter((word) => HAS_LETTER.test(word))
+	const first = words[0]
+	if (!first) return ''
+	if (words.length === 1) return fromFirstLetter(first, max).toUpperCase()
+
+	// Keep the last word (the surname) when there are more words than letters.
+	const head = words.slice(0, Math.max(1, max - 1))
+	const picked =
+		words.length > max ? [...head, words.at(-1) ?? first].slice(0, max) : words
+	return picked
+		.map((word) => fromFirstLetter(word, 1))
+		.join('')
+		.toUpperCase()
+}
+
+/** `JSON.parse` that returns a `Result` instead of throwing. */
+export function safeJsonParse<T = unknown>(
+	text: string
+): Result<T, SyntaxError> {
+	try {
+		return { ok: true, data: JSON.parse(text) as T, error: null }
+	} catch (error) {
+		return { ok: false, data: null, error: error as SyntaxError }
+	}
+}
+
+// `count` characters from the word's first letter, so brackets around a name
+// are skipped but digits after it are kept (`'R2D2'` → `'R2'`).
+function fromFirstLetter(word: string, count: number): string {
+	const characters = graphemes(word)
+	const start = characters.findIndex((character) => HAS_LETTER.test(character))
+	if (start === -1) return ''
+	return characters.slice(start, start + count).join('')
+}
+
+let segmenter: Intl.Segmenter | undefined
+
+// Grapheme clusters when `Intl.Segmenter` exists, otherwise code points.
+function graphemes(text: string): string[] {
+	if (typeof Intl === 'undefined' || !('Segmenter' in Intl)) return [...text]
+	segmenter ??= new Intl.Segmenter()
+	return Array.from(segmenter.segment(text), ({ segment }) => segment)
 }
 
 function normalizeIdInput(input: JsonValue | undefined): string {
 	if (input === undefined) return 'undefined'
 	if (input === null) return 'null'
 	if (typeof input === 'string') {
-		return decodeURIComponent(input).split('&').sort().join('&')
+		return safeDecodeURIComponent(input).split('&').sort().join('&')
 	}
 	if (typeof input === 'number' || typeof input === 'boolean') {
 		return input.toString()
@@ -84,3 +314,11 @@ function sortJsonValue(value: JsonValue | undefined): JsonValue | null {
 
 	return value
 }
+
+function safeDecodeURIComponent(value: string): string {
+	try {
+		return decodeURIComponent(value)
+	} catch {
+		return value
+	}
+}

package/src/typedswitch/index.ts

@@ -109,23 +109,41 @@ export type PartialStringSwitchCases<T extends string, R> = {
 // Object input mode types
 // ═══════════════════════════════════════════════════════════════════════════
 
-/** Cases for object input with custom key - all cases required */
-export type ObjectSwitchCases<T, K extends keyof T, R> = T[K] extends string
-	? {
-			[V in T[K]]: (value: Extract<T, Record<K, V>>) => R | Promise<R>
-		}
+/** Discriminant values supported in object mode. Cases are keyed by `${value}`. */
+type Discriminant = string | number | boolean
+
+/** Discriminant values of `V` whose case key (`${value}`) is in `Keys` */
+type ValuesForKeys<V, Keys> = V extends Discriminant
+	? `${V}` extends `${Keys & (string | number)}`
+		? V
+		: never
 	: never
 
+type ObjectCases<T, K extends keyof T, R> = {
+	[V in Extract<T[K], Discriminant> as `${V}`]: (
+		value: Extract<T, Record<K, V>>
+	) => R
+}
+
+type PartialObjectCases<T, K extends keyof T, R> = {
+	[V in Extract<T[K], Discriminant> as `${V}`]?: (
+		value: Extract<T, Record<K, V>>
+	) => R
+}
+
+/** Cases for object input with custom key - all cases required */
+export type ObjectSwitchCases<
+	T,
+	K extends keyof T,
+	R
+> = T[K] extends Discriminant ? ObjectCases<T, K, R | Promise<R>> : never
+
 /** Partial cases for object input with custom key (when default is provided) */
 export type PartialObjectSwitchCases<
 	T,
 	K extends keyof T,
 	R
-> = T[K] extends string
-	? {
-			[V in T[K]]?: (value: Extract<T, Record<K, V>>) => R | Promise<R>
-		}
-	: never
+> = T[K] extends Discriminant ? PartialObjectCases<T, K, R | Promise<R>> : never
 
 type Handler = (value: unknown) => unknown
 type CasesRecord = Record<string, Handler | undefined>
@@ -156,8 +174,7 @@ export function typedSwitch<
 export function typedSwitch<
 	T extends object,
 	K extends keyof T,
-	TKey extends T[K] & string,
-	Cases extends { [V in TKey]: (value: Extract<T, Record<K, V>>) => unknown }
+	Cases extends ObjectCases<T, K, unknown>
 >(value: T, key: K, cases: Cases): RawCasesReturnType<Cases>
 
 // Object input with key - partial cases allowed (with default)
@@ -165,10 +182,9 @@ export function typedSwitch<
 export function typedSwitch<
 	T extends object,
 	K extends keyof T,
-	TKey extends T[K] & string,
-	Cases extends { [V in TKey]?: (value: Extract<T, Record<K, V>>) => unknown },
+	Cases extends PartialObjectCases<T, K, unknown>,
 	DefaultCase extends (
-		value: Exclude<T, Record<K, HandledCaseKeys<Cases> & string>>
+		value: Exclude<T, Record<K, ValuesForKeys<T[K], HandledCaseKeys<Cases>>>>
 	) => unknown
 >(
 	value: T,
@@ -204,13 +220,7 @@ export function typedSwitch<
 	Constraint,
 	T extends Record<string, unknown> = Record<string, unknown>,
 	K extends keyof T = keyof T
->(
-	value: T,
-	key: K,
-	cases: {
-		[V in T[K] & string]: (value: Extract<T, Record<K, V>>) => Constraint
-	}
-): Constraint
+>(value: T, key: K, cases: ObjectCases<T, K, Constraint>): Constraint
 export function typedSwitch<
 	Constraint,
 	T extends Record<string, unknown> = Record<string, unknown>,
@@ -218,11 +228,7 @@ export function typedSwitch<
 >(
 	value: T,
 	key: K,
-	cases: {
-		[V in T[K] & string]: (
-			value: Extract<T, Record<K, V>>
-		) => Constraint | Promise<Constraint>
-	}
+	cases: ObjectCases<T, K, Constraint | Promise<Constraint>>
 ): Constraint | Promise<Constraint>
 
 // Object input with key - partial cases allowed with return constraint (with default)
@@ -233,9 +239,7 @@ export function typedSwitch<
 >(
 	value: T,
 	key: K,
-	cases: {
-		[V in T[K] & string]?: (value: Extract<T, Record<K, V>>) => Constraint
-	},
+	cases: PartialObjectCases<T, K, Constraint>,
 	defaultCase: (value: T) => Constraint
 ): Constraint
 export function typedSwitch<
@@ -245,11 +249,7 @@ export function typedSwitch<
 >(
 	value: T,
 	key: K,
-	cases: {
-		[V in T[K] & string]?: (
-			value: Extract<T, Record<K, V>>
-		) => Constraint | Promise<Constraint>
-	},
+	cases: PartialObjectCases<T, K, Constraint | Promise<Constraint>>,
 	defaultCase: (value: T) => Constraint | Promise<Constraint>
 ): Constraint | Promise<Constraint>
 
@@ -282,13 +282,17 @@ export function typedSwitch(
 		const discriminantValue = (value as Record<string, unknown>)[
 			discriminantKey
 		]
-		if (typeof discriminantValue !== 'string') {
+		if (
+			typeof discriminantValue !== 'string' &&
+			typeof discriminantValue !== 'number' &&
+			typeof discriminantValue !== 'boolean'
+		) {
 			throw new Error(
-				`Invalid discriminant value for key "${discriminantKey}": expected string, received ${typeof discriminantValue}`
+				`Invalid discriminant value for key "${discriminantKey}": expected string, number or boolean, received ${typeof discriminantValue}`
 			)
 		}
 
-		key = discriminantValue
+		key = String(discriminantValue)
 		cases = casesOrDefault as CasesRecord
 		defaultHandler = defaultCase
 	}
@@ -318,3 +322,19 @@ export function typedSwitch(
 		`Unhandled case: ${key}${contextSuffix}.${availableCasesSuffix}`
 	)
 }
+
+/**
+ * Exhaustiveness helper for regular `switch` statements. Place it in the
+ * `default` branch: it only type-checks when every case has been handled, and
+ * throws if an unexpected value reaches it at runtime.
+ *
+ * @example
+ * switch (status) {
+ *   case 'success': return 1
+ *   case 'error': return 0
+ *   default: return assertNever(status)
+ * }
+ */
+export function assertNever(value: never, message?: string): never {
+	throw new Error(message ?? `Unexpected value: ${String(value)}`)
+}

package/src/types/index.ts

@@ -0,0 +1,14 @@
+export type MaybePromise<T> = T | Promise<T>
+
+/** Union of an object type's values. */
+export type ValueOf<T> = T[keyof T]
+
+/** Union of an array or tuple's element types. */
+export type ElementOf<T extends readonly unknown[]> = T[number]
+
+export type NonEmptyArray<T> = [T, ...T[]]
+
+/** Flattens intersections into one object type so hovers stay readable. */
+export type Simplify<T> = { [K in keyof T]: T[K] } & {}
+
+export type Nullable<T> = T | null | undefined

package/src/url/index.ts

@@ -1,5 +1,150 @@
-export function getDomainFaviconUrl(domain: string, size = 128): string {
+export type UrlQueryValue = string | number | boolean | null | undefined
+export type UrlQueryParams = Record<
+	string,
+	UrlQueryValue | readonly UrlQueryValue[]
+>
+
+/**
+ * Serializes query params. Arrays repeat the key (`a=1&a=2`); `null` and
+ * `undefined` are skipped. Returns the string without a leading `?`.
+ */
+export function buildQueryString(
+	params: UrlQueryParams,
+	options: { encode?: boolean } = {}
+): string {
+	const pairs: [string, string][] = []
+	for (const [key, value] of Object.entries(params)) {
+		const values = Array.isArray(value) ? value : [value]
+		for (const item of values) {
+			if (item != null) pairs.push([key, String(item)])
+		}
+	}
+
+	if (options.encode === false) {
+		return pairs.map(([key, value]) => `${key}=${value}`).join('&')
+	}
+	return new URLSearchParams(pairs).toString()
+}
+
+/**
+ * Replaces `:name` placeholders with encoded values. Throws when a placeholder
+ * has no value. Only `:` followed by a letter or `_` counts, so ports like
+ * `:8080` are left alone.
+ */
+export function replacePathParams(
+	path: string,
+	params: Record<string, string | number | boolean | undefined> = {}
+): string {
+	return path.replace(/:([A-Za-z_]\w*)/g, (_, key: string) => {
+		const value = params[key]
+		if (value === undefined) {
+			throw new Error(`Missing required path parameter: ${key}`)
+		}
+		return encodeURIComponent(String(value))
+	})
+}
+
+/** Joins base and path with exactly one `/`, fills `:params`, appends query. */
+export function buildUrl(
+	base: string,
+	path = '',
+	options: {
+		params?: Record<string, string | number | boolean | undefined>
+		query?: UrlQueryParams
+	} = {}
+): string {
+	const joined = path
+		? `${trimTrailingSlash(base)}/${path.replace(/^\/+/, '')}`
+		: base
+	const url = replacePathParams(joined, options.params)
+	const query = options.query ? buildQueryString(options.query) : ''
+	if (!query) return url
+	return `${url}${url.includes('?') ? '&' : '?'}${query}`
+}
+
+/**
+ * Normalizes a domain or URL to its origin: adds `https://` when no scheme is
+ * given and strips any path, query or trailing slash.
+ */
+export function normalizeDomain(input: string): string {
+	const trimmed = input.trim()
+	const withScheme = /^[a-z][a-z\d+.-]*:\/\//i.test(trimmed)
+		? trimmed
+		: `https://${trimmed}`
+	return new URL(withScheme).origin
+}
+
+/** Accepts a bare domain (`example.com`) or a full URL. */
+export function getDomainFaviconUrl(domainOrUrl: string, size = 128): string {
+	let domain = domainOrUrl
+	try {
+		if (/^[a-z][a-z\d+.-]*:\/\//i.test(domainOrUrl)) {
+			domain = new URL(domainOrUrl).hostname
+		}
+	} catch {
+		// Not a URL; use the input as-is.
+	}
 	return `https://www.google.com/s2/favicons?domain=${encodeURIComponent(
 		domain
 	)}&sz=${size}`
 }
+
+/** Removes trailing slashes: `'https://x.com/a/'` → `'https://x.com/a'`. */
+export function trimTrailingSlash(url: string): string {
+	return url.replace(/\/+$/, '')
+}
+
+/** Prefixes `/` unless the path already starts with one. */
+export function ensureLeadingSlash(path: string): string {
+	return path.startsWith('/') ? path : `/${path}`
+}
+
+type MailtoRecipients = string | readonly string[]
+
+/**
+ * Builds a `mailto:` link. Spaces become `%20` (not `+`, which mail clients
+ * show literally) and body line breaks become `%0D%0A`.
+ */
+export function buildMailto(options: {
+	to?: MailtoRecipients
+	cc?: MailtoRecipients
+	bcc?: MailtoRecipients
+	subject?: string
+	body?: string
+}): string {
+	const { to, cc, bcc, subject, body } = options
+	const headers = Object.entries({
+		cc: cc && recipients(cc),
+		bcc: bcc && recipients(bcc),
+		subject: subject && encodeURIComponent(subject),
+		body: body && encodeURIComponent(body.replace(/\r?\n/g, '\r\n'))
+	})
+		.filter(([, value]) => value)
+		.map(([key, value]) => `${key}=${value}`)
+		.join('&')
+	return `mailto:${to ? recipients(to) : ''}${headers ? `?${headers}` : ''}`
+}
+
+function recipients(value: MailtoRecipients): string {
+	return (typeof value === 'string' ? [value] : value)
+		.map((address) => encodeURIComponent(address.trim()).replace(/%40/g, '@'))
+		.join(',')
+}
+
+/**
+ * Milliseconds to wait from a `Retry-After` header: delta-seconds (fractions
+ * allowed) or an HTTP date relative to `now`. Past dates and negative values
+ * give `0`; a missing or invalid value gives `undefined`.
+ */
+export function parseRetryAfter(
+	value: string | null | undefined,
+	now = Date.now()
+): number | undefined {
+	const trimmed = value?.trim()
+	if (!trimmed) return undefined
+	if (/^-?\d*\.?\d+$/.test(trimmed)) {
+		return Math.max(0, Number(trimmed) * 1000)
+	}
+	const date = Date.parse(trimmed)
+	return Number.isNaN(date) ? undefined : Math.max(0, date - now)
+}