@glion/util-timestamp 0.14.1

package/LICENSE

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

@@ -0,0 +1,258 @@
+# @glion/util-timestamp
+
+An immutable, high-performance HL7v2 timestamp utility with precision tracking. Parses, formats, and converts HL7v2 TS (Time Stamp) values while preserving precision for lossless round-tripping.
+
+## Features
+
+- **Precision tracking** - 7 levels from year to millisecond, never loses or adds detail
+- **Lossless round-trip** - `Timestamp.parse(str).toString() === str` for all valid inputs
+- **High performance** - No regex, no intermediate arrays, pre-computed lookup tables
+- **Type safe** - Full TypeScript support with const enums and union types
+- **Zero dependencies** - Pure computation, no runtime dependencies
+
+## Installation
+
+```bash
+npm install @glion/util-timestamp
+```
+
+## Quick Start
+
+```typescript
+import { Timestamp, Precision } from "@glion/util-timestamp";
+
+// Parse an HL7v2 timestamp string
+const ts = Timestamp.parse("20260307143045-0500");
+ts.precision; // "second"
+ts.toDate(); // Date representing 2026-03-07T19:30:45.000Z
+ts.toString(); // "20260307143045-0500"
+
+// Create from a JavaScript Date
+const ts2 = Timestamp.from(new Date(), { precision: "day" });
+ts2.toString(); // "20260307"
+
+// Current time
+const now = Timestamp.now({ precision: "second", timezone: true });
+now.toString(); // "20260307143045+0000"
+```
+
+## API Reference
+
+### `Timestamp.parse(value: string): Timestamp`
+
+Parses an HL7v2 timestamp string into a `Timestamp` instance.
+
+Accepts the full HL7v2 TS format: `YYYY[MM[DD[HH[MM[SS[.S[S[S[S]]]]]]]]][+/-ZZZZ]`
+
+```typescript
+Timestamp.parse("2026"); // year precision
+Timestamp.parse("202603"); // month precision
+Timestamp.parse("20260307"); // day precision
+Timestamp.parse("2026030714"); // hour precision
+Timestamp.parse("202603071430"); // minute precision
+Timestamp.parse("20260307143045"); // second precision
+Timestamp.parse("20260307143045.1234"); // millisecond precision (4-digit fractional)
+Timestamp.parse("20260307143045-0500"); // with timezone offset
+Timestamp.parse("20260307143045.12+0000"); // fractional + timezone
+```
+
+**Throws:** `TypeError` if the string is not a valid HL7v2 timestamp.
+
+### `Timestamp.from(date: Date, options?: TimestampOptions): Timestamp`
+
+Creates a `Timestamp` from a JavaScript `Date` object.
+
+```typescript
+const date = new Date(2026, 2, 7, 14, 30, 45, 123);
+
+Timestamp.from(date).toString(); // "20260307143045"
+Timestamp.from(date, { precision: "day" }).toString(); // "20260307"
+Timestamp.from(date, { precision: "millisecond" }).toString(); // "20260307143045.123"
+Timestamp.from(date, { timezone: true }).toString(); // "20260307143045+0000"
+```
+
+**Throws:** `TypeError` if the `Date` is invalid (`NaN`).
+
+### `Timestamp.now(options?: TimestampOptions): Timestamp`
+
+Creates a `Timestamp` for the current time.
+
+```typescript
+Timestamp.now().toString(); // "20260307143045"
+Timestamp.now({ precision: "day" }).toString(); // "20260307"
+Timestamp.now({ precision: "minute" }).toString(); // "202603071430"
+Timestamp.now({ timezone: true }).toString(); // "20260307143045+0000"
+```
+
+### Instance Properties
+
+#### `precision: Precision`
+
+The precision level of the timestamp. One of: `"year"`, `"month"`, `"day"`, `"hour"`, `"minute"`, `"second"`, `"millisecond"`.
+
+### Instance Methods
+
+#### `toString(): string`
+
+Formats the timestamp as an HL7v2 string, respecting the precision level.
+
+```typescript
+Timestamp.parse("20260307").toString(); // "20260307" (not "20260307000000")
+```
+
+#### `toDate(): Date`
+
+Returns a copy of the underlying `Date` object. Each call returns a new copy to preserve immutability.
+
+### `TimestampOptions`
+
+```typescript
+interface TimestampOptions {
+  /** Precision level for formatting. Default: "second" */
+  precision?: Precision;
+
+  /** Include local timezone offset. Only applies at "hour" precision or finer. Default: false */
+  timezone?: boolean;
+}
+```
+
+### `Precision`
+
+```typescript
+import { Precision } from "@glion/util-timestamp";
+
+Precision.Year; // "year"        → YYYY
+Precision.Month; // "month"       → YYYYMM
+Precision.Day; // "day"         → YYYYMMDD
+Precision.Hour; // "hour"        → YYYYMMDDHH
+Precision.Minute; // "minute"      → YYYYMMDDHHmm
+Precision.Second; // "second"      → YYYYMMDDHHmmss
+Precision.Millisecond; // "millisecond" → YYYYMMDDHHmmss.SSSS
+```
+
+## Precision Tracking
+
+Precision is a first-class concept. The timestamp remembers exactly how much detail was provided, so formatting never inflates or truncates:
+
+```typescript
+// Parsing preserves precision
+Timestamp.parse("20260307").toString(); // "20260307" — not "20260307000000"
+Timestamp.parse("202603071430").toString(); // "202603071430" — not "20260307143000"
+
+// Fractional seconds are preserved exactly (even 4-digit)
+Timestamp.parse("20260307143045.1234").toString(); // "20260307143045.1234"
+
+// from() uses the requested precision
+Timestamp.from(date, { precision: "day" }).toString(); // "20260307"
+Timestamp.from(date, { precision: "minute" }).toString(); // "202603071430"
+```
+
+## Timezone Management
+
+Timezone information is embedded directly in the `Date` object — not stored as separate public metadata. This ensures that `toDate()` always returns the correct absolute moment, and `toString()` always reproduces the original timezone for lossless round-tripping.
+
+### Correct Absolute Moments
+
+When an HL7v2 timestamp includes a timezone offset (`+/-ZZZZ`), the offset is applied during parsing to construct a `Date` with the correct UTC instant:
+
+```typescript
+// 14:30:45 in UTC-5 → Date stores 19:30:45 UTC
+const ts = Timestamp.parse("20260307143045-0500");
+ts.toDate().toISOString(); // "2026-03-07T19:30:45.000Z"
+
+// 14:30:45 in UTC+5:30 → Date stores 09:00:45 UTC
+const ts2 = Timestamp.parse("20260307143045+0530");
+ts2.toDate().toISOString(); // "2026-03-07T09:00:45.000Z"
+
+// Midnight in UTC+5:30 → previous day in UTC
+const ts3 = Timestamp.parse("20260101000000+0530");
+ts3.toDate().toISOString(); // "2025-12-31T18:30:00.000Z"
+```
+
+### Lossless Round-Trip with Timezone
+
+Parsed timestamps with timezone offsets round-trip exactly, regardless of the server's timezone:
+
+```typescript
+// On ANY server (UTC, EST, PST, IST):
+Timestamp.parse("20260307143045-0500").toString(); // "20260307143045-0500"
+Timestamp.parse("20260307143045+0530").toString(); // "20260307143045+0530"
+Timestamp.parse("20261231235959.999-0800").toString(); // "20261231235959.999-0800"
+```
+
+The timezone offset is stored internally and used by `toString()` to reconstruct the original local time components from UTC. No public `timezoneOffset` property is exposed — this prevents the data integrity risk of consumers calling `toDate()` and forgetting to account for a separate offset.
+
+### Creating Timestamps with Timezone
+
+When using `from()` or `now()` with `{ timezone: true }`, the runtime's local timezone offset is captured at creation time:
+
+```typescript
+const ts = Timestamp.from(new Date(), { timezone: true });
+ts.toString(); // "20260307143045-0500" (on a UTC-5 server)
+```
+
+### Without Timezone
+
+Timestamps without a timezone offset are treated as local time — no UTC conversion is applied:
+
+```typescript
+const ts = Timestamp.parse("20260307143045");
+// Date is constructed with new Date(2026, 2, 7, 14, 30, 45) — local time
+```
+
+### Precision Gate
+
+Timezone is only included at `"hour"` precision or finer. Coarser precisions (`"year"`, `"month"`, `"day"`) never carry a timezone suffix:
+
+```typescript
+Timestamp.from(date, { precision: "day", timezone: true }).toString();
+// "20260307" — no timezone (day precision is too coarse)
+
+Timestamp.from(date, { precision: "hour", timezone: true }).toString();
+// "2026030714-0500" — timezone included
+```
+
+## Performance
+
+Optimized for high-throughput streaming processors handling 100K+ messages per second:
+
+- **No regex** — manual character-based parsing via `codePointAt` arithmetic
+- **No intermediate arrays** — direct string concatenation in `toString()`
+- **Pre-computed lookup table** — zero-padded strings for 0-99
+- **O(1) precision lookups** — `Map` instead of `Array.indexOf()`
+- **Zero allocations in hot paths** — no substring extraction or `Number()` conversions
+
+## Error Handling
+
+All invalid input throws `TypeError` with a descriptive message:
+
+```typescript
+Timestamp.parse(""); // TypeError: Invalid HL7v2 timestamp: ""
+Timestamp.parse("not-a-timestamp"); // TypeError: Invalid HL7v2 timestamp: "not-a-timestamp"
+Timestamp.parse("20263"); // TypeError: Invalid HL7v2 timestamp: "20263"
+Timestamp.from(new Date("invalid")); // TypeError: Invalid Date provided to Timestamp.from
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide][github-contributing] for more details.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Code of Conduct
+
+To ensure a welcoming and positive environment, we have a [Code of Conduct][github-code-of-conduct] that all contributors and participants are expected to adhere to.
+
+## License
+
+Copyright 2025 Rethink Health, SUARL. All rights reserved.
+
+This program is licensed to you under the terms of the [MIT License](https://opensource.org/licenses/MIT). This program is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the [LICENSE][github-license] file for details.
+
+[github-code-of-conduct]: https://github.com/rethinkhealth/glion/blob/main/CODE_OF_CONDUCT.md
+[github-license]: https://github.com/rethinkhealth/glion/blob/main/LICENSE
+[github-contributing]: https://github.com/rethinkhealth/glion/blob/main/CONTRIBUTING.md

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Precision } from "./precision";
+export { Timestamp } from "./timestamp";
+export type { TimestampOptions } from "./timestamp";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,324 @@
+//#region src/precision.ts
+/**
+* HL7v2 timestamp precision levels.
+*
+* Controls how much of the timestamp is included when formatting.
+* Precision is progressive — higher precision includes all lower levels.
+*
+* | Precision     | Format                | Example               |
+* | ------------- | --------------------- | --------------------- |
+* | `Year`        | `YYYY`                | `2026`                |
+* | `Month`       | `YYYYMM`              | `202603`              |
+* | `Day`         | `YYYYMMDD`            | `20260307`            |
+* | `Hour`        | `YYYYMMDDHH`          | `2026030714`          |
+* | `Minute`      | `YYYYMMDDHHmm`        | `202603071430`        |
+* | `Second`      | `YYYYMMDDHHmmss`      | `20260307143000`      |
+* | `Millisecond` | `YYYYMMDDHHmmss.SSSS` | `20260307143000.1234` |
+*/
+const Precision = {
+	Year: "year",
+	Month: "month",
+	Day: "day",
+	Hour: "hour",
+	Minute: "minute",
+	Second: "second",
+	Millisecond: "millisecond"
+};
+//#endregion
+//#region src/timestamp.ts
+const PAD2_TABLE = Array.from({ length: 100 }, (_, i) => i < 10 ? `0${i}` : `${i}`);
+function pad2(n) {
+	return PAD2_TABLE[n] ?? String(n);
+}
+const PRECISION_INDEX = new Map([
+	["year", 0],
+	["month", 1],
+	["day", 2],
+	["hour", 3],
+	["minute", 4],
+	["second", 5],
+	["millisecond", 6]
+]);
+/** Minimum precision index that supports a timezone offset (hour = 3). */
+const MIN_TIMEZONE_PRECISION = 3;
+const PRECISION_BY_LENGTH = new Map([
+	[4, "year"],
+	[6, "month"],
+	[8, "day"],
+	[10, "hour"],
+	[12, "minute"],
+	[14, "second"]
+]);
+function formatOffset(offsetMinutes) {
+	const sign = offsetMinutes <= 0 ? "+" : "-";
+	const abs = Math.abs(offsetMinutes);
+	const hours = Math.floor(abs / 60);
+	const minutes = abs % 60;
+	return `${sign}${pad2(hours)}${pad2(minutes)}`;
+}
+/** Get the code point at offset, returning 0 for out-of-bounds. */
+function code(s, offset) {
+	return s.codePointAt(offset) ?? 0;
+}
+/** Extract a 2-digit number from a string at the given offset. */
+function digits2(s, offset) {
+	return (code(s, offset) - 48) * 10 + (code(s, offset + 1) - 48);
+}
+/** Extract a 4-digit number from a string at the given offset. */
+function digits4(s, offset) {
+	return (code(s, offset) - 48) * 1e3 + (code(s, offset + 1) - 48) * 100 + (code(s, offset + 2) - 48) * 10 + (code(s, offset + 3) - 48);
+}
+/** Check if a character at the given offset is an ASCII digit. */
+function isDigit(s, offset) {
+	const cp = code(s, offset);
+	return cp >= 48 && cp <= 57;
+}
+function validateDigits(value, end) {
+	for (let i = 0; i < end; i += 1) if (!isDigit(value, i)) return false;
+	return true;
+}
+/**
+* An immutable HL7v2 timestamp value with precision tracking.
+*
+* Represents the HL7v2 TS (Time Stamp) data type:
+* `YYYY[MM[DD[HH[MM[SS[.S[S[S[S]]]]]]]]][+/-ZZZZ]`
+*
+* Tracks precision so that round-tripping is lossless:
+* `Timestamp.parse("20260307").toString()` returns `"20260307"`, not
+* `"20260307000000"`.
+*
+* Performance characteristics (optimized for high-throughput streaming):
+* - `toString()`: Direct string concatenation, no intermediate arrays
+* - `parse()`: Manual character extraction, no regex or match arrays
+* - Constant-time precision lookups via Map
+* - Pre-computed pad table eliminates padStart overhead
+*
+* @example
+*   ```typescript
+*   // From a Date
+*   Timestamp.from(new Date(), { precision: "day" }).toString(); // "20260307"
+*
+*   // Parse an HL7v2 string (timezone is applied to the Date)
+*   const ts = Timestamp.parse("20260307143000-0500");
+*   ts.precision; // "second"
+*   ts.toDate(); // Date representing 2026-03-07T19:30:00Z
+*
+*   // Current time
+*   Timestamp.now().toString(); // "20260307143045"
+*   ```;
+*/
+var Timestamp = class Timestamp {
+	#date;
+	precision;
+	/**
+	* Timezone offset in minutes (getTimezoneOffset convention).
+	* Set when the timestamp carries timezone information — either from parsing
+	* a string with a +/-ZZZZ suffix, or from creating via from()/now() with
+	* timezone: true.
+	*
+	* When set, toString() uses UTC getters + this offset to derive the local
+	* time components, ensuring correct formatting regardless of server timezone.
+	* When undefined, toString() uses local getters (no timezone suffix).
+	*/
+	#offset;
+	/** Raw fractional seconds string from parsing, for lossless round-trip. */
+	#fractionalRaw;
+	constructor(date, precision, offset, fractionalRaw) {
+		this.#date = date;
+		this.precision = precision;
+		this.#offset = offset;
+		this.#fractionalRaw = fractionalRaw;
+	}
+	/**
+	* Create a Timestamp from a JavaScript Date.
+	*
+	* @param date - A valid Date object
+	* @param options - Precision and timezone options
+	* @throws {TypeError} If the Date is invalid
+	*/
+	static from(date, options) {
+		if (Number.isNaN(date.getTime())) throw new TypeError("Invalid Date provided to Timestamp.from");
+		const precision = options?.precision ?? "second";
+		const precisionIndex = PRECISION_INDEX.get(precision) ?? 5;
+		const includeTimezone = (options?.timezone ?? false) && precisionIndex >= MIN_TIMEZONE_PRECISION;
+		const copy = new Date(date);
+		return new Timestamp(copy, precision, includeTimezone ? copy.getTimezoneOffset() : void 0);
+	}
+	/**
+	* Parse an HL7v2 timestamp string into a Timestamp.
+	*
+	* Uses manual character-based extraction instead of regex to avoid
+	* match array allocation and Number() conversions. In benchmarks this
+	* is ~2-3x faster than regex-based parsing for the common case.
+	*
+	* @param value - An HL7v2 TS-formatted string
+	* @throws {TypeError} If the string is not a valid HL7v2 timestamp
+	*/
+	static parse(value) {
+		const len = value.length;
+		if (len < 4) throw new TypeError(`Invalid HL7v2 timestamp: "${value}"`);
+		let coreEnd = len;
+		let dotPos = -1;
+		let tzPos = -1;
+		for (let i = 0; i < len; i += 1) {
+			const ch = value.codePointAt(i);
+			if (ch === 46) {
+				dotPos = i;
+				coreEnd = i;
+				break;
+			}
+			if ((ch === 43 || ch === 45) && i >= 4) {
+				tzPos = i;
+				coreEnd = i;
+				break;
+			}
+		}
+		if (dotPos >= 0) for (let i = dotPos + 1; i < len; i += 1) {
+			const ch = value.codePointAt(i);
+			if (ch === 43 || ch === 45) {
+				tzPos = i;
+				break;
+			}
+		}
+		if (coreEnd < 4 || coreEnd > 14 || coreEnd % 2 !== 0) throw new TypeError(`Invalid HL7v2 timestamp: "${value}"`);
+		if (!validateDigits(value, coreEnd)) throw new TypeError(`Invalid HL7v2 timestamp: "${value}"`);
+		const year = digits4(value, 0);
+		const month = coreEnd >= 6 ? digits2(value, 4) - 1 : 0;
+		const day = coreEnd >= 8 ? digits2(value, 6) : 1;
+		const hour = coreEnd >= 10 ? digits2(value, 8) : 0;
+		const minute = coreEnd >= 12 ? digits2(value, 10) : 0;
+		const second = coreEnd >= 14 ? digits2(value, 12) : 0;
+		let ms = 0;
+		let fractionalRaw;
+		if (dotPos >= 0) {
+			const fracEnd = tzPos >= 0 ? tzPos : len;
+			fractionalRaw = value.slice(dotPos, fracEnd);
+			const fracDigits = fracEnd - dotPos - 1;
+			if (fracDigits < 1 || fracDigits > 4) throw new TypeError(`Invalid HL7v2 timestamp: "${value}"`);
+			for (let i = dotPos + 1; i < fracEnd; i += 1) if (!isDigit(value, i)) throw new TypeError(`Invalid HL7v2 timestamp: "${value}"`);
+			const d0 = fracDigits >= 1 ? code(value, dotPos + 1) - 48 : 0;
+			const d1 = fracDigits >= 2 ? code(value, dotPos + 2) - 48 : 0;
+			const d2 = fracDigits >= 3 ? code(value, dotPos + 3) - 48 : 0;
+			ms = d0 * 100 + d1 * 10 + d2;
+		}
+		let parsedOffset = 0;
+		const hasTimezone = tzPos >= 0;
+		if (hasTimezone) {
+			if (len - tzPos !== 5) throw new TypeError(`Invalid HL7v2 timestamp: "${value}"`);
+			for (let i = tzPos + 1; i < len; i += 1) if (!isDigit(value, i)) throw new TypeError(`Invalid HL7v2 timestamp: "${value}"`);
+			const tzSign = value.codePointAt(tzPos) === 43 ? -1 : 1;
+			const tzHours = digits2(value, tzPos + 1);
+			const tzMinutes = digits2(value, tzPos + 3);
+			parsedOffset = tzSign * (tzHours * 60 + tzMinutes) || 0;
+		}
+		const precision = fractionalRaw ? "millisecond" : PRECISION_BY_LENGTH.get(coreEnd) ?? "year";
+		let date;
+		if (hasTimezone) {
+			const utcMs = Date.UTC(year, month, day, hour, minute, second, ms) + parsedOffset * 6e4;
+			date = new Date(utcMs);
+			if (year < 100) date.setUTCFullYear(year);
+		} else {
+			date = new Date(year, month, day, hour, minute, second, ms);
+			date.setFullYear(year);
+		}
+		return new Timestamp(date, precision, hasTimezone ? parsedOffset : void 0, fractionalRaw);
+	}
+	/**
+	* Create a Timestamp for the current time.
+	*
+	* Performance: Skips the defensive Date copy in from() since we own the
+	* Date object — it was just created and no external reference exists.
+	*
+	* @param options - Precision and timezone options
+	*/
+	static now(options) {
+		const date = /* @__PURE__ */ new Date();
+		const precision = options?.precision ?? "second";
+		const precisionIndex = PRECISION_INDEX.get(precision) ?? 5;
+		return new Timestamp(date, precision, (options?.timezone ?? false) && precisionIndex >= MIN_TIMEZONE_PRECISION ? date.getTimezoneOffset() : void 0);
+	}
+	/**
+	* Return a copy of the underlying Date object.
+	*/
+	toDate() {
+		return new Date(this.#date);
+	}
+	/**
+	* Format as an HL7v2 timestamp string, respecting the precision level.
+	*
+	* Performance: Uses direct string concatenation instead of array.join().
+	* V8 optimizes template literal concatenation into a single allocation,
+	* while the array approach required: 1 array + 6 strings + slice + join
+	* = ~9 allocations per call. This approach: 1 string concatenation.
+	*/
+	toString() {
+		const d = this.#date;
+		let yyyy;
+		let mm;
+		let dd;
+		let hh;
+		let min;
+		let ss;
+		if (this.#offset === void 0) {
+			const y = d.getFullYear();
+			yyyy = y >= 1e3 ? String(y) : String(y).padStart(4, "0");
+			mm = pad2(d.getMonth() + 1);
+			dd = pad2(d.getDate());
+			hh = pad2(d.getHours());
+			min = pad2(d.getMinutes());
+			ss = pad2(d.getSeconds());
+		} else {
+			const local = /* @__PURE__ */ new Date(d.getTime() - this.#offset * 6e4);
+			const y = local.getUTCFullYear();
+			yyyy = y >= 1e3 ? String(y) : String(y).padStart(4, "0");
+			mm = pad2(local.getUTCMonth() + 1);
+			dd = pad2(local.getUTCDate());
+			hh = pad2(local.getUTCHours());
+			min = pad2(local.getUTCMinutes());
+			ss = pad2(local.getUTCSeconds());
+		}
+		let result;
+		switch (this.precision) {
+			case "year":
+				result = yyyy;
+				break;
+			case "month":
+				result = `${yyyy}${mm}`;
+				break;
+			case "day":
+				result = `${yyyy}${mm}${dd}`;
+				break;
+			case "hour":
+				result = `${yyyy}${mm}${dd}${hh}`;
+				break;
+			case "minute":
+				result = `${yyyy}${mm}${dd}${hh}${min}`;
+				break;
+			case "second":
+				result = `${yyyy}${mm}${dd}${hh}${min}${ss}`;
+				break;
+			case "millisecond": {
+				const base = `${yyyy}${mm}${dd}${hh}${min}${ss}`;
+				if (this.#fractionalRaw) result = `${base}${this.#fractionalRaw}`;
+				else {
+					const msVal = d.getMilliseconds();
+					if (msVal === 0) result = `${base}.0`;
+					else if (msVal % 100 === 0) result = `${base}.${msVal / 100}`;
+					else if (msVal % 10 === 0) result = `${base}.${pad2(msVal / 10)}`;
+					else result = `${base}.${String(msVal).padStart(3, "0")}`;
+				}
+				break;
+			}
+			default: {
+				const _exhaustive = this.precision;
+				throw new TypeError(`Unknown precision: ${_exhaustive}`);
+			}
+		}
+		if (this.#offset !== void 0) result += formatOffset(this.#offset);
+		return result;
+	}
+};
+//#endregion
+export { Precision, Timestamp };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["#date","#offset","#fractionalRaw"],"sources":["../src/precision.ts","../src/timestamp.ts"],"sourcesContent":["/**\n * HL7v2 timestamp precision levels.\n *\n * Controls how much of the timestamp is included when formatting.\n * Precision is progressive — higher precision includes all lower levels.\n *\n * | Precision     | Format                | Example               |\n * | ------------- | --------------------- | --------------------- |\n * | `Year`        | `YYYY`                | `2026`                |\n * | `Month`       | `YYYYMM`              | `202603`              |\n * | `Day`         | `YYYYMMDD`            | `20260307`            |\n * | `Hour`        | `YYYYMMDDHH`          | `2026030714`          |\n * | `Minute`      | `YYYYMMDDHHmm`        | `202603071430`        |\n * | `Second`      | `YYYYMMDDHHmmss`      | `20260307143000`      |\n * | `Millisecond` | `YYYYMMDDHHmmss.SSSS` | `20260307143000.1234` |\n */\n// oxlint-disable-next-line sort-keys\nexport const Precision = {\n  Year: \"year\",\n  Month: \"month\",\n  Day: \"day\",\n  Hour: \"hour\",\n  Minute: \"minute\",\n  Second: \"second\",\n  Millisecond: \"millisecond\",\n} as const;\n\nexport type Precision = (typeof Precision)[keyof typeof Precision];\n","import type { Precision } from \"./precision\";\n\n/**\n * Options for creating a Timestamp from a Date.\n */\nexport interface TimestampOptions {\n  /**\n   * Precision level for formatting.\n   *\n   * @default \"second\"\n   */\n  precision?: Precision;\n\n  /**\n   * Whether to include the local timezone offset in the output.\n   * Only applies when precision is `\"hour\"` or finer.\n   * Uses `Date.getTimezoneOffset()` to auto-detect the offset.\n   *\n   * @default false\n   */\n  timezone?: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Performance: Pre-computed lookup table for 0-99 → zero-padded strings.\n// Avoids String(n).padStart(2, \"0\") which allocates a new string + calls\n// padStart on every invocation. In a streaming processor handling 100K+ msg/s,\n// this eliminates ~6 padStart calls per toString() invocation.\n// ---------------------------------------------------------------------------\nconst PAD2_TABLE: string[] = Array.from({ length: 100 }, (_, i) =>\n  i < 10 ? `0${i}` : `${i}`\n);\n\nfunction pad2(n: number): string {\n  return PAD2_TABLE[n] ?? String(n);\n}\n\n// ---------------------------------------------------------------------------\n// Performance: O(1) precision index lookup via Map instead of Array.indexOf().\n// Array.indexOf() does a linear scan on every call. With 7 elements the scan\n// is short, but this is called in both from() and toString() — two linear\n// scans per message. A Map lookup is constant-time.\n// ---------------------------------------------------------------------------\nconst PRECISION_INDEX = new Map<Precision, number>([\n  [\"year\", 0],\n  [\"month\", 1],\n  [\"day\", 2],\n  [\"hour\", 3],\n  [\"minute\", 4],\n  [\"second\", 5],\n  [\"millisecond\", 6],\n]);\n\n/** Minimum precision index that supports a timezone offset (hour = 3). */\nconst MIN_TIMEZONE_PRECISION = 3;\n\n// ---------------------------------------------------------------------------\n// Performance: Precision detection from string length instead of regex.\n// HL7v2 timestamps have a fixed structure where length directly maps to\n// precision. This avoids regex compilation, match array allocation, and\n// group iteration — replacing it with a single Map lookup.\n// ---------------------------------------------------------------------------\nconst PRECISION_BY_LENGTH = new Map<number, Precision>([\n  [4, \"year\"],\n  [6, \"month\"],\n  [8, \"day\"],\n  [10, \"hour\"],\n  [12, \"minute\"],\n  [14, \"second\"],\n]);\n\nfunction formatOffset(offsetMinutes: number): string {\n  const sign = offsetMinutes <= 0 ? \"+\" : \"-\";\n  const abs = Math.abs(offsetMinutes);\n  const hours = Math.floor(abs / 60);\n  const minutes = abs % 60;\n  return `${sign}${pad2(hours)}${pad2(minutes)}`;\n}\n\n// ---------------------------------------------------------------------------\n// Performance: Manual character-based digit extraction instead of regex.\n// charCodeAt(i) - 48 converts ASCII '0'-'9' to 0-9 without allocating\n// substrings or calling Number(). This avoids the regex match array\n// (9 capture groups) and 6 Number() conversions per parse() call.\n// ---------------------------------------------------------------------------\n\n/** Get the code point at offset, returning 0 for out-of-bounds. */\nfunction code(s: string, offset: number): number {\n  return s.codePointAt(offset) ?? 0;\n}\n\n/** Extract a 2-digit number from a string at the given offset. */\nfunction digits2(s: string, offset: number): number {\n  return (code(s, offset) - 48) * 10 + (code(s, offset + 1) - 48);\n}\n\n/** Extract a 4-digit number from a string at the given offset. */\nfunction digits4(s: string, offset: number): number {\n  return (\n    (code(s, offset) - 48) * 1000 +\n    (code(s, offset + 1) - 48) * 100 +\n    (code(s, offset + 2) - 48) * 10 +\n    (code(s, offset + 3) - 48)\n  );\n}\n\n/** Check if a character at the given offset is an ASCII digit. */\nfunction isDigit(s: string, offset: number): boolean {\n  const cp = code(s, offset);\n  return cp >= 48 && cp <= 57;\n}\n\n// ---------------------------------------------------------------------------\n// Performance: Validate the core numeric portion without regex.\n// Only checks that all characters up to the fractional/timezone boundary\n// are ASCII digits and that the total length is a valid even number.\n// This replaces the HL7V2_TS_PATTERN regex which allocated a match array\n// with 8 capture groups on every call.\n// ---------------------------------------------------------------------------\n\nfunction validateDigits(value: string, end: number): boolean {\n  for (let i = 0; i < end; i += 1) {\n    if (!isDigit(value, i)) {\n      return false;\n    }\n  }\n  return true;\n}\n\n/**\n * An immutable HL7v2 timestamp value with precision tracking.\n *\n * Represents the HL7v2 TS (Time Stamp) data type:\n * `YYYY[MM[DD[HH[MM[SS[.S[S[S[S]]]]]]]]][+/-ZZZZ]`\n *\n * Tracks precision so that round-tripping is lossless:\n * `Timestamp.parse(\"20260307\").toString()` returns `\"20260307\"`, not\n * `\"20260307000000\"`.\n *\n * Performance characteristics (optimized for high-throughput streaming):\n * - `toString()`: Direct string concatenation, no intermediate arrays\n * - `parse()`: Manual character extraction, no regex or match arrays\n * - Constant-time precision lookups via Map\n * - Pre-computed pad table eliminates padStart overhead\n *\n * @example\n *   ```typescript\n *   // From a Date\n *   Timestamp.from(new Date(), { precision: \"day\" }).toString(); // \"20260307\"\n *\n *   // Parse an HL7v2 string (timezone is applied to the Date)\n *   const ts = Timestamp.parse(\"20260307143000-0500\");\n *   ts.precision; // \"second\"\n *   ts.toDate(); // Date representing 2026-03-07T19:30:00Z\n *\n *   // Current time\n *   Timestamp.now().toString(); // \"20260307143045\"\n *   ```;\n */\nexport class Timestamp {\n  readonly #date: Date;\n  readonly precision: Precision;\n\n  /**\n   * Timezone offset in minutes (getTimezoneOffset convention).\n   * Set when the timestamp carries timezone information — either from parsing\n   * a string with a +/-ZZZZ suffix, or from creating via from()/now() with\n   * timezone: true.\n   *\n   * When set, toString() uses UTC getters + this offset to derive the local\n   * time components, ensuring correct formatting regardless of server timezone.\n   * When undefined, toString() uses local getters (no timezone suffix).\n   */\n  readonly #offset?: number;\n\n  /** Raw fractional seconds string from parsing, for lossless round-trip. */\n  readonly #fractionalRaw?: string;\n\n  private constructor(\n    date: Date,\n    precision: Precision,\n    offset?: number,\n    fractionalRaw?: string\n  ) {\n    this.#date = date;\n    this.precision = precision;\n    this.#offset = offset;\n    this.#fractionalRaw = fractionalRaw;\n  }\n\n  /**\n   * Create a Timestamp from a JavaScript Date.\n   *\n   * @param date - A valid Date object\n   * @param options - Precision and timezone options\n   * @throws {TypeError} If the Date is invalid\n   */\n  static from(date: Date, options?: TimestampOptions): Timestamp {\n    if (Number.isNaN(date.getTime())) {\n      throw new TypeError(\"Invalid Date provided to Timestamp.from\");\n    }\n    const precision = options?.precision ?? \"second\";\n    // Performance: O(1) Map lookup instead of Array.indexOf()\n    const precisionIndex = PRECISION_INDEX.get(precision) ?? 5;\n    const includeTimezone =\n      (options?.timezone ?? false) && precisionIndex >= MIN_TIMEZONE_PRECISION;\n\n    // Defensive copy — caller may mutate the original Date\n    const copy = new Date(date);\n    return new Timestamp(\n      copy,\n      precision,\n      includeTimezone ? copy.getTimezoneOffset() : undefined\n    );\n  }\n\n  /**\n   * Parse an HL7v2 timestamp string into a Timestamp.\n   *\n   * Uses manual character-based extraction instead of regex to avoid\n   * match array allocation and Number() conversions. In benchmarks this\n   * is ~2-3x faster than regex-based parsing for the common case.\n   *\n   * @param value - An HL7v2 TS-formatted string\n   * @throws {TypeError} If the string is not a valid HL7v2 timestamp\n   */\n  // oxlint-disable-next-line complexity\n  static parse(value: string): Timestamp {\n    const len = value.length;\n    if (len < 4) {\n      throw new TypeError(`Invalid HL7v2 timestamp: \"${value}\"`);\n    }\n\n    // -----------------------------------------------------------------------\n    // Find where the core digit portion ends. It can be followed by:\n    //   - '.' for fractional seconds\n    //   - '+' or '-' for timezone offset\n    //   - end of string\n    // -----------------------------------------------------------------------\n    let coreEnd = len;\n    let dotPos = -1;\n    let tzPos = -1;\n\n    for (let i = 0; i < len; i += 1) {\n      const ch = value.codePointAt(i);\n      if (ch === 46) {\n        // '.'\n        dotPos = i;\n        coreEnd = i;\n        break;\n      }\n      if ((ch === 43 || ch === 45) && i >= 4) {\n        // '+' or '-', but not at start\n        tzPos = i;\n        coreEnd = i;\n        break;\n      }\n    }\n\n    // If we found a dot, look for timezone after it\n    if (dotPos >= 0) {\n      for (let i = dotPos + 1; i < len; i += 1) {\n        const ch = value.codePointAt(i);\n        if (ch === 43 || ch === 45) {\n          // '+' or '-'\n          tzPos = i;\n          break;\n        }\n      }\n    }\n\n    // Validate: core digits must be even-length (pairs: YYYY MM DD HH mm ss)\n    // and between 4 and 14 characters\n    if (coreEnd < 4 || coreEnd > 14 || coreEnd % 2 !== 0) {\n      throw new TypeError(`Invalid HL7v2 timestamp: \"${value}\"`);\n    }\n\n    // Validate all core characters are digits\n    if (!validateDigits(value, coreEnd)) {\n      throw new TypeError(`Invalid HL7v2 timestamp: \"${value}\"`);\n    }\n\n    // -----------------------------------------------------------------------\n    // Extract date/time components via direct charCodeAt arithmetic.\n    // digits4/digits2 convert ASCII chars to numbers without substring\n    // allocation or Number() parsing.\n    // -----------------------------------------------------------------------\n    const year = digits4(value, 0);\n    const month = coreEnd >= 6 ? digits2(value, 4) - 1 : 0;\n    const day = coreEnd >= 8 ? digits2(value, 6) : 1;\n    const hour = coreEnd >= 10 ? digits2(value, 8) : 0;\n    const minute = coreEnd >= 12 ? digits2(value, 10) : 0;\n    const second = coreEnd >= 14 ? digits2(value, 12) : 0;\n\n    // -----------------------------------------------------------------------\n    // Fractional seconds: preserve the raw string (e.g., \".1234\") for\n    // lossless round-trip. JS Date only holds 3 digits of ms precision,\n    // but HL7v2 allows 4 — storing the raw string lets toString() reproduce\n    // the original exactly.\n    // -----------------------------------------------------------------------\n    let ms = 0;\n    let fractionalRaw: string | undefined;\n    if (dotPos >= 0) {\n      const fracEnd = tzPos >= 0 ? tzPos : len;\n      fractionalRaw = value.slice(dotPos, fracEnd);\n      const fracDigits = fracEnd - dotPos - 1;\n\n      // Validate fractional digits: 1-4 digits after the dot\n      if (fracDigits < 1 || fracDigits > 4) {\n        throw new TypeError(`Invalid HL7v2 timestamp: \"${value}\"`);\n      }\n      // Validate fractional portion (digits after the dot)\n      for (let i = dotPos + 1; i < fracEnd; i += 1) {\n        if (!isDigit(value, i)) {\n          throw new TypeError(`Invalid HL7v2 timestamp: \"${value}\"`);\n        }\n      }\n\n      // Convert fractional digits to ms (pad or truncate to 3 digits)\n      const d0 = fracDigits >= 1 ? code(value, dotPos + 1) - 48 : 0;\n      const d1 = fracDigits >= 2 ? code(value, dotPos + 2) - 48 : 0;\n      const d2 = fracDigits >= 3 ? code(value, dotPos + 3) - 48 : 0;\n      ms = d0 * 100 + d1 * 10 + d2;\n    }\n\n    // -----------------------------------------------------------------------\n    // Timezone offset: parse the +/-HHMM suffix.\n    // Convention follows Date.getTimezoneOffset(): +0530 → -330 minutes.\n    // When present, we construct the Date using UTC so it represents the\n    // correct absolute moment in time.\n    // -----------------------------------------------------------------------\n    let parsedOffset = 0;\n    const hasTimezone = tzPos >= 0;\n    if (hasTimezone) {\n      const remaining = len - tzPos;\n      if (remaining !== 5) {\n        throw new TypeError(`Invalid HL7v2 timestamp: \"${value}\"`);\n      }\n      // Validate the 4 timezone digits after the sign\n      for (let i = tzPos + 1; i < len; i += 1) {\n        if (!isDigit(value, i)) {\n          throw new TypeError(`Invalid HL7v2 timestamp: \"${value}\"`);\n        }\n      }\n      const tzSign = value.codePointAt(tzPos) === 43 ? -1 : 1; // '+' → -1\n      const tzHours = digits2(value, tzPos + 1);\n      const tzMinutes = digits2(value, tzPos + 3);\n      // `|| 0` normalises -0 to 0 (e.g. \"+0000\" → sign=-1, total=0 → -0)\n      parsedOffset = tzSign * (tzHours * 60 + tzMinutes) || 0;\n    }\n\n    // -----------------------------------------------------------------------\n    // Precision detection: O(1) Map lookup based on core digit length.\n    // No regex group counting needed.\n    // -----------------------------------------------------------------------\n    const precision: Precision = fractionalRaw\n      ? \"millisecond\"\n      : (PRECISION_BY_LENGTH.get(coreEnd) ?? \"year\");\n\n    let date: Date;\n    if (hasTimezone) {\n      // Construct from UTC: the parsed components represent local time at the\n      // given offset. Convert to UTC so the Date carries the correct instant.\n      // UTC = localTime + offset (getTimezoneOffset convention)\n      const utcMs =\n        Date.UTC(year, month, day, hour, minute, second, ms) +\n        parsedOffset * 60_000;\n      date = new Date(utcMs);\n      // Fix: Date.UTC treats years 0-99 as 1900-1999\n      if (year < 100) {\n        date.setUTCFullYear(year);\n      }\n    } else {\n      // No timezone: treat components as local time\n      date = new Date(year, month, day, hour, minute, second, ms);\n      // Fix: JS Date treats years 0-99 as 1900-1999\n      date.setFullYear(year);\n    }\n\n    return new Timestamp(\n      date,\n      precision,\n      hasTimezone ? parsedOffset : undefined,\n      fractionalRaw\n    );\n  }\n\n  /**\n   * Create a Timestamp for the current time.\n   *\n   * Performance: Skips the defensive Date copy in from() since we own the\n   * Date object — it was just created and no external reference exists.\n   *\n   * @param options - Precision and timezone options\n   */\n  static now(options?: TimestampOptions): Timestamp {\n    const date = new Date();\n    const precision = options?.precision ?? \"second\";\n    const precisionIndex = PRECISION_INDEX.get(precision) ?? 5;\n    const includeTimezone =\n      (options?.timezone ?? false) && precisionIndex >= MIN_TIMEZONE_PRECISION;\n\n    // No defensive copy needed — we just created this Date, no one else holds a reference\n    return new Timestamp(\n      date,\n      precision,\n      includeTimezone ? date.getTimezoneOffset() : undefined\n    );\n  }\n\n  /**\n   * Return a copy of the underlying Date object.\n   */\n  toDate(): Date {\n    return new Date(this.#date);\n  }\n\n  /**\n   * Format as an HL7v2 timestamp string, respecting the precision level.\n   *\n   * Performance: Uses direct string concatenation instead of array.join().\n   * V8 optimizes template literal concatenation into a single allocation,\n   * while the array approach required: 1 array + 6 strings + slice + join\n   * = ~9 allocations per call. This approach: 1 string concatenation.\n   */\n  toString(): string {\n    const d = this.#date;\n    // When the Date was constructed from UTC (via parse() with timezone),\n    // use UTC getters + the stored offset to reconstruct the sender's local\n    // time components. This enables lossless round-trip regardless of server TZ.\n    // When the Date was constructed locally (from/now), local getters are correct.\n    let yyyy: string;\n    let mm: string;\n    let dd: string;\n    let hh: string;\n    let min: string;\n    let ss: string;\n    if (this.#offset === undefined) {\n      // No timezone: use local getters directly\n      const y = d.getFullYear();\n      yyyy = y >= 1000 ? String(y) : String(y).padStart(4, \"0\");\n      mm = pad2(d.getMonth() + 1);\n      dd = pad2(d.getDate());\n      hh = pad2(d.getHours());\n      min = pad2(d.getMinutes());\n      ss = pad2(d.getSeconds());\n    } else {\n      // Reconstruct the local time at the stored offset from UTC\n      const local = new Date(d.getTime() - this.#offset * 60_000);\n      const y = local.getUTCFullYear();\n      yyyy = y >= 1000 ? String(y) : String(y).padStart(4, \"0\");\n      mm = pad2(local.getUTCMonth() + 1);\n      dd = pad2(local.getUTCDate());\n      hh = pad2(local.getUTCHours());\n      min = pad2(local.getUTCMinutes());\n      ss = pad2(local.getUTCSeconds());\n    }\n\n    let result: string;\n\n    switch (this.precision) {\n      case \"year\": {\n        result = yyyy;\n        break;\n      }\n      case \"month\": {\n        result = `${yyyy}${mm}`;\n        break;\n      }\n      case \"day\": {\n        result = `${yyyy}${mm}${dd}`;\n        break;\n      }\n      case \"hour\": {\n        result = `${yyyy}${mm}${dd}${hh}`;\n        break;\n      }\n      case \"minute\": {\n        result = `${yyyy}${mm}${dd}${hh}${min}`;\n        break;\n      }\n      case \"second\": {\n        result = `${yyyy}${mm}${dd}${hh}${min}${ss}`;\n        break;\n      }\n      case \"millisecond\": {\n        const base = `${yyyy}${mm}${dd}${hh}${min}${ss}`;\n        if (this.#fractionalRaw) {\n          // Parsed timestamps: use the raw string for lossless round-trip\n          result = `${base}${this.#fractionalRaw}`;\n        } else {\n          // Created from Date: derive fractional from Date.getMilliseconds().\n          // Manual trailing-zero trim instead of regex replace(/0+$/, \"\").\n          const msVal = d.getMilliseconds();\n          if (msVal === 0) {\n            result = `${base}.0`;\n          } else if (msVal % 100 === 0) {\n            result = `${base}.${msVal / 100}`;\n          } else if (msVal % 10 === 0) {\n            result = `${base}.${pad2(msVal / 10)}`;\n          } else {\n            result = `${base}.${String(msVal).padStart(3, \"0\")}`;\n          }\n        }\n        break;\n      }\n      default: {\n        // Exhaustive check: if a new precision is added, this will surface\n        // a TypeScript error (\"Type 'x' is not assignable to type 'never'\").\n        const _exhaustive: never = this.precision;\n        throw new TypeError(`Unknown precision: ${_exhaustive}`);\n      }\n    }\n\n    if (this.#offset !== undefined) {\n      result += formatOffset(this.#offset);\n    }\n\n    return result;\n  }\n}\n"],"mappings":"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"}

package/dist/precision.d.ts

@@ -0,0 +1,27 @@
+/**
+ * HL7v2 timestamp precision levels.
+ *
+ * Controls how much of the timestamp is included when formatting.
+ * Precision is progressive — higher precision includes all lower levels.
+ *
+ * | Precision     | Format                | Example               |
+ * | ------------- | --------------------- | --------------------- |
+ * | `Year`        | `YYYY`                | `2026`                |
+ * | `Month`       | `YYYYMM`              | `202603`              |
+ * | `Day`         | `YYYYMMDD`            | `20260307`            |
+ * | `Hour`        | `YYYYMMDDHH`          | `2026030714`          |
+ * | `Minute`      | `YYYYMMDDHHmm`        | `202603071430`        |
+ * | `Second`      | `YYYYMMDDHHmmss`      | `20260307143000`      |
+ * | `Millisecond` | `YYYYMMDDHHmmss.SSSS` | `20260307143000.1234` |
+ */
+export declare const Precision: {
+    readonly Year: "year";
+    readonly Month: "month";
+    readonly Day: "day";
+    readonly Hour: "hour";
+    readonly Minute: "minute";
+    readonly Second: "second";
+    readonly Millisecond: "millisecond";
+};
+export type Precision = (typeof Precision)[keyof typeof Precision];
+//# sourceMappingURL=precision.d.ts.map

package/dist/precision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"precision.d.ts","sourceRoot":"","sources":["../src/precision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,SAAS;;;;;;;;CAQZ,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC"}

package/dist/timestamp.d.ts

@@ -0,0 +1,97 @@
+import type { Precision } from "./precision";
+/**
+ * Options for creating a Timestamp from a Date.
+ */
+export interface TimestampOptions {
+    /**
+     * Precision level for formatting.
+     *
+     * @default "second"
+     */
+    precision?: Precision;
+    /**
+     * Whether to include the local timezone offset in the output.
+     * Only applies when precision is `"hour"` or finer.
+     * Uses `Date.getTimezoneOffset()` to auto-detect the offset.
+     *
+     * @default false
+     */
+    timezone?: boolean;
+}
+/**
+ * An immutable HL7v2 timestamp value with precision tracking.
+ *
+ * Represents the HL7v2 TS (Time Stamp) data type:
+ * `YYYY[MM[DD[HH[MM[SS[.S[S[S[S]]]]]]]]][+/-ZZZZ]`
+ *
+ * Tracks precision so that round-tripping is lossless:
+ * `Timestamp.parse("20260307").toString()` returns `"20260307"`, not
+ * `"20260307000000"`.
+ *
+ * Performance characteristics (optimized for high-throughput streaming):
+ * - `toString()`: Direct string concatenation, no intermediate arrays
+ * - `parse()`: Manual character extraction, no regex or match arrays
+ * - Constant-time precision lookups via Map
+ * - Pre-computed pad table eliminates padStart overhead
+ *
+ * @example
+ *   ```typescript
+ *   // From a Date
+ *   Timestamp.from(new Date(), { precision: "day" }).toString(); // "20260307"
+ *
+ *   // Parse an HL7v2 string (timezone is applied to the Date)
+ *   const ts = Timestamp.parse("20260307143000-0500");
+ *   ts.precision; // "second"
+ *   ts.toDate(); // Date representing 2026-03-07T19:30:00Z
+ *
+ *   // Current time
+ *   Timestamp.now().toString(); // "20260307143045"
+ *   ```;
+ */
+export declare class Timestamp {
+    #private;
+    readonly precision: Precision;
+    private constructor();
+    /**
+     * Create a Timestamp from a JavaScript Date.
+     *
+     * @param date - A valid Date object
+     * @param options - Precision and timezone options
+     * @throws {TypeError} If the Date is invalid
+     */
+    static from(date: Date, options?: TimestampOptions): Timestamp;
+    /**
+     * Parse an HL7v2 timestamp string into a Timestamp.
+     *
+     * Uses manual character-based extraction instead of regex to avoid
+     * match array allocation and Number() conversions. In benchmarks this
+     * is ~2-3x faster than regex-based parsing for the common case.
+     *
+     * @param value - An HL7v2 TS-formatted string
+     * @throws {TypeError} If the string is not a valid HL7v2 timestamp
+     */
+    static parse(value: string): Timestamp;
+    /**
+     * Create a Timestamp for the current time.
+     *
+     * Performance: Skips the defensive Date copy in from() since we own the
+     * Date object — it was just created and no external reference exists.
+     *
+     * @param options - Precision and timezone options
+     */
+    static now(options?: TimestampOptions): Timestamp;
+    /**
+     * Return a copy of the underlying Date object.
+     */
+    toDate(): Date;
+    /**
+     * Format as an HL7v2 timestamp string, respecting the precision level.
+     *
+     * Performance: Uses direct string concatenation instead of array.join().
+     * V8 optimizes template literal concatenation into a single allocation,
+     * while the array approach required: 1 array + 6 strings + slice + join
+     * = ~9 allocations per call. This approach: 1 string concatenation.
+     */
+    toString(): string;
+}
+//# sourceMappingURL=timestamp.d.ts.map

package/dist/timestamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.d.ts","sourceRoot":"","sources":["../src/timestamp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA4GD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,SAAS;;IAEpB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAiB9B,OAAO;IAYP;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS;IAmB9D;;;;;;;;;OASG;IAEH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS;IAgKtC;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS;IAejD;;OAEG;IACH,MAAM,IAAI,IAAI;IAId;;;;;;;OAOG;IACH,QAAQ,IAAI,MAAM;CA+FnB"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@glion/util-timestamp",
+  "version": "0.14.1",
+  "description": "HL7v2 timestamp parsing, formatting, and conversion with precision tracking",
+  "keywords": [
+    "health",
+    "healthcare",
+    "hl7",
+    "hl7v2",
+    "nodejs",
+    "timestamp",
+    "typescript"
+  ],
+  "homepage": "https://glion.dev",
+  "license": "MIT",
+  "author": {
+    "name": "Melek Somai",
+    "email": "melek@rethinkhealth.io"
+  },
+  "repository": "rethinkhealth/glion.git",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "4.1.2",
+    "tsdown": "0.21.7",
+    "typescript": "^5.9.3",
+    "vitest": "4.1.2",
+    "@glion/testing": "0.0.2",
+    "@glion/tsconfig": "0.0.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsdown && tsc --emitDeclarationOnly",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  }
+}