fix(asn1): preserve raw date bytes for wildcard/partial date decode (#70)

## Summary
This PR fixes BACnet DATE wildcard handling by preserving raw DATE
fields during decode.

I initially suspected the bug was in the encoder, but investigation
showed the write payload was encoded correctly.
The actual issue was in decode/normalization, where partial wildcard
DATE values were being normalized through JS `Date`, causing readback
drift/misinterpretation.

## Root Cause
- Wildcard/partial DATE values (e.g. `17.*.*.*`, `*.*.*.Fri`, `28.*.2021
-> 30.*.2032`) were valid on write.
- On read, decoder/normalization converted these to JS `Date` semantics,
which cannot represent BACnet wildcard bytes faithfully.
- This produced incorrect values when rendering/roundtripping.

## Changes
- Preserve raw DATE byte components (`year`, `month`, `day`, `wday`)
from decoder output.
- Avoid JS Date normalization for wildcard/partial DATE patterns.
- Ensure downstream consumers can prefer `raw` when reconstructing
BACnet DATE patterns.

## Impact
- Fixes incorrect readback of wildcard/partial DATE values.
- Restores roundtrip consistency for scheduler/calendar exception
use-cases.
- No behavior change for fully specified dates.

## Validation
Tested with real-device and gateway flows, including:
- Single date wildcard patterns (`17.*.*.*`, `*.*.*.Friday`, `*.*.*.*`)
- Date range with partial wildcards (`28.*.2021 -> 30.*.2032`)
- Verified write succeeds where device allows pattern
- Verified readback now matches original BACnet wildcard intent

## Compatibility
Backward compatible.
No API break; change is in decode fidelity and normalization behavior.

---------

Co-authored-by: Daniel Lando <daniel.sorridi@gmail.com>

Author: EveGun

src/lib/asn1.ts

@@ -1298,33 +1298,79 @@ export const decodeBitstring = (
 	}
 }
 
-export const decodeDate = (buffer: Buffer, offset: number): Decode<Date> => {
+const isWildcardRawDate = (raw: {
+	year: number
+	month: number
+	day: number
+	wday: number
+}): boolean =>
+	raw.year === 0xff &&
+	raw.month === 0xff &&
+	raw.day === 0xff &&
+	raw.wday === 0xff
+
+const hasPartialWildcardRawDate = (raw: {
+	year: number
+	month: number
+	day: number
+	wday: number
+}): boolean =>
+	!isWildcardRawDate(raw) &&
+	(raw.year === 0xff ||
+		raw.month === 0xff ||
+		raw.day === 0xff ||
+		raw.wday === 0xff)
+
+const isInvalidConcreteRawDate = (raw: {
+	year: number
+	month: number
+	day: number
+}): boolean => raw.month < 1 || raw.month > 12 || raw.day < 1 || raw.day > 31
+
+export const decodeDate = (
+	buffer: Buffer,
+	offset: number,
+): Decode<Date> & {
+	raw: { year: number; month: number; day: number; wday: number }
+} => {
+	const raw = {
+		year: buffer[offset],
+		month: buffer[offset + 1],
+		day: buffer[offset + 2],
+		wday: buffer[offset + 3],
+	}
+
 	let date: Date
-	const year = buffer[offset] + 1900
-	const month = buffer[offset + 1]
-	const day = buffer[offset + 2]
-	const wday = buffer[offset + 3]
 	if (
-		month === 0xff &&
-		day === 0xff &&
-		wday === 0xff &&
-		year - 1900 === 0xff
+		isWildcardRawDate(raw) ||
+		hasPartialWildcardRawDate(raw) ||
+		isInvalidConcreteRawDate(raw)
 	) {
 		date = ZERO_DATE
 	} else {
-		date = new Date(year, month - 1, day)
+		const year = raw.year + 1900
+		const candidate = new Date(year, raw.month - 1, raw.day)
+		const normalized =
+			candidate.getFullYear() === year &&
+			candidate.getMonth() === raw.month - 1 &&
+			candidate.getDate() === raw.day
+		date = normalized ? candidate : ZERO_DATE
 	}
+
 	return {
 		len: 4,
 		value: date,
+		raw,
 	}
 }
 
 const decodeDateSafe = (
 	buffer: Buffer,
 	offset: number,
 	lenValue: number,
-): Decode<Date> => {
+): Decode<Date> & {
+	raw?: { year: number; month: number; day: number; wday: number }
+} => {
 	if (lenValue !== 4) {
 		return {
 			len: lenValue,
@@ -1499,6 +1545,9 @@ const bacappDecodeData = (
 			result = decodeDateSafe(buffer, offset, lenValueType)
 			value.len += result.len
 			value.value = result.value
+			if (result.raw) {
+				value.raw = result.raw
+			}
 			break
 		case ApplicationTag.TIME:
 			result = decodeBacnetTimeSafe(buffer, offset, lenValueType)

src/lib/types.ts

@@ -190,6 +190,7 @@ export interface BACNetAppData<
 > {
 	type: Tag
 	value: Type
+	raw?: unknown
 	encoding?: number
 }
 

test/unit/asn1.spec.ts

@@ -138,6 +138,76 @@ test.describe('bacnet - ASN1 layer', () => {
 		})
 	})
 
+	test.describe('decodeDate', () => {
+		test('should decode full wildcard date to ZERO_DATE and preserve raw', () => {
+			const result = baAsn1.decodeDate(
+				Buffer.from([0xff, 0xff, 0xff, 0xff]),
+				0,
+			)
+			assert.equal(result.len, 4)
+			assert.equal(result.value.getTime(), baAsn1.ZERO_DATE.getTime())
+			assert.deepStrictEqual(result.raw, {
+				year: 0xff,
+				month: 0xff,
+				day: 0xff,
+				wday: 0xff,
+			})
+		})
+
+		test('should decode partial wildcard date to ZERO_DATE and preserve raw', () => {
+			const result = baAsn1.decodeDate(
+				Buffer.from([0xff, 0xff, 17, 0xff]),
+				0,
+			)
+			assert.equal(result.len, 4)
+			assert.equal(result.value.getTime(), baAsn1.ZERO_DATE.getTime())
+			assert.deepStrictEqual(result.raw, {
+				year: 0xff,
+				month: 0xff,
+				day: 17,
+				wday: 0xff,
+			})
+		})
+
+		test('should decode invalid concrete date to ZERO_DATE and preserve raw', () => {
+			const result = baAsn1.decodeDate(Buffer.from([124, 0, 32, 2]), 0)
+			assert.equal(result.len, 4)
+			assert.equal(result.value.getTime(), baAsn1.ZERO_DATE.getTime())
+			assert.deepStrictEqual(result.raw, {
+				year: 124,
+				month: 0,
+				day: 32,
+				wday: 2,
+			})
+		})
+
+		test('should decode non-normalized concrete date to ZERO_DATE', () => {
+			const result = baAsn1.decodeDate(Buffer.from([124, 2, 31, 5]), 0)
+			assert.equal(result.len, 4)
+			assert.equal(result.value.getTime(), baAsn1.ZERO_DATE.getTime())
+			assert.deepStrictEqual(result.raw, {
+				year: 124,
+				month: 2,
+				day: 31,
+				wday: 5,
+			})
+		})
+
+		test('should decode valid concrete date and preserve raw', () => {
+			const result = baAsn1.decodeDate(Buffer.from([124, 12, 31, 2]), 0)
+			assert.equal(result.len, 4)
+			assert.equal(result.value.getFullYear(), 2024)
+			assert.equal(result.value.getMonth(), 11)
+			assert.equal(result.value.getDate(), 31)
+			assert.deepStrictEqual(result.raw, {
+				year: 124,
+				month: 12,
+				day: 31,
+				wday: 2,
+			})
+		})
+	})
+
 	test.describe('decodeWeekNDay', () => {
 		test('should decode valid WEEKNDAY payload', () => {
 			const buffer = { buffer: Buffer.alloc(8), offset: 0 }

test/unit/service-read-property.spec.ts

@@ -18,6 +18,16 @@ const encodeRawDate = (buffer: any, value: Date) => {
 	buffer.buffer[buffer.offset++] = value.getDay() || 7
 }
 
+const encodeRawDateParts = (
+	buffer: any,
+	value: { year: number; month: number; day: number; wday: number },
+) => {
+	buffer.buffer[buffer.offset++] = value.year
+	buffer.buffer[buffer.offset++] = value.month
+	buffer.buffer[buffer.offset++] = value.day
+	buffer.buffer[buffer.offset++] = value.wday
+}
+
 const encodeReadPropertyAckHeader = (
 	buffer: any,
 	objectType: number,
@@ -185,6 +195,115 @@ test.describe('ReadPropertyAcknowledge schedule/calendar compatibility', () => {
 		assert.equal(weekdayEntry.date.value.wday, 1)
 	})
 
+	test('should preserve raw date for partial wildcard single date in exception schedule', () => {
+		const buffer = utils.getBuffer()
+		encodeReadPropertyAckHeader(
+			buffer,
+			ObjectType.SCHEDULE,
+			17,
+			PropertyIdentifier.EXCEPTION_SCHEDULE,
+		)
+
+		baAsn1.encodeOpeningTag(buffer, 0)
+		baAsn1.encodeTag(buffer, 0, true, 4)
+		encodeRawDateParts(buffer, {
+			year: 0xff,
+			month: 0xff,
+			day: 17,
+			wday: 0xff,
+		})
+		baAsn1.encodeClosingTag(buffer, 0)
+		baAsn1.encodeOpeningTag(buffer, 2)
+		baAsn1.bacappEncodeApplicationData(buffer, {
+			type: ApplicationTag.TIME,
+			value: new Date(2024, 0, 2, 6, 30, 0, 0),
+		})
+		baAsn1.bacappEncodeApplicationData(buffer, {
+			type: ApplicationTag.ENUMERATED,
+			value: 1,
+		})
+		baAsn1.encodeClosingTag(buffer, 2)
+		baAsn1.bacappEncodeApplicationData(buffer, {
+			type: ApplicationTag.UNSIGNED_INTEGER,
+			value: 8,
+		})
+		baAsn1.encodeClosingTag(buffer, 3)
+
+		const result = ReadProperty.decodeAcknowledge(
+			buffer.buffer,
+			0,
+			buffer.offset,
+		)
+		assert.ok(result)
+		const specialEvent = result.values[0]
+		const values = specialEvent.value as any[]
+		assert.equal(values.length, 1)
+		const date = values[0].date
+		assert.equal(date.type, ApplicationTag.DATE)
+		// Partial wildcard raw dates normalize to ZERO_DATE in value while raw preserves source bytes.
+		assert.equal(date.value.getTime(), baAsn1.ZERO_DATE.getTime())
+		assert.deepStrictEqual(date.raw, {
+			year: 0xff,
+			month: 0xff,
+			day: 17,
+			wday: 0xff,
+		})
+	})
+
+	test('should fall back to ZERO_DATE for invalid concrete raw date in exception schedule', () => {
+		const buffer = utils.getBuffer()
+		encodeReadPropertyAckHeader(
+			buffer,
+			ObjectType.SCHEDULE,
+			17,
+			PropertyIdentifier.EXCEPTION_SCHEDULE,
+		)
+
+		baAsn1.encodeOpeningTag(buffer, 0)
+		baAsn1.encodeTag(buffer, 0, true, 4)
+		encodeRawDateParts(buffer, {
+			year: 124,
+			month: 0,
+			day: 32,
+			wday: 2,
+		})
+		baAsn1.encodeClosingTag(buffer, 0)
+		baAsn1.encodeOpeningTag(buffer, 2)
+		baAsn1.bacappEncodeApplicationData(buffer, {
+			type: ApplicationTag.TIME,
+			value: new Date(2024, 0, 2, 6, 30, 0, 0),
+		})
+		baAsn1.bacappEncodeApplicationData(buffer, {
+			type: ApplicationTag.ENUMERATED,
+			value: 1,
+		})
+		baAsn1.encodeClosingTag(buffer, 2)
+		baAsn1.bacappEncodeApplicationData(buffer, {
+			type: ApplicationTag.UNSIGNED_INTEGER,
+			value: 8,
+		})
+		baAsn1.encodeClosingTag(buffer, 3)
+
+		const result = ReadProperty.decodeAcknowledge(
+			buffer.buffer,
+			0,
+			buffer.offset,
+		)
+		assert.ok(result)
+		const specialEvent = result.values[0]
+		const values = specialEvent.value as any[]
+		assert.equal(values.length, 1)
+		const date = values[0].date
+		assert.equal(date.type, ApplicationTag.DATE)
+		assert.equal(date.value.getTime(), baAsn1.ZERO_DATE.getTime())
+		assert.deepStrictEqual(date.raw, {
+			year: 124,
+			month: 0,
+			day: 32,
+			wday: 2,
+		})
+	})
+
 	test('should decode schedule effective period payload', () => {
 		const buffer = utils.getBuffer()
 		encodeReadPropertyAckHeader(
@@ -218,6 +337,59 @@ test.describe('ReadPropertyAcknowledge schedule/calendar compatibility', () => {
 		assert.ok(values[1].value instanceof Date)
 	})
 
+	test('should preserve raw date range with partial wildcards in effective period', () => {
+		const buffer = utils.getBuffer()
+		encodeReadPropertyAckHeader(
+			buffer,
+			ObjectType.SCHEDULE,
+			17,
+			PropertyIdentifier.EFFECTIVE_PERIOD,
+		)
+
+		baAsn1.encodeTag(buffer, ApplicationTag.DATE, true, 4)
+		encodeRawDateParts(buffer, {
+			year: 121, // 2021
+			month: 0xff,
+			day: 28,
+			wday: 0xff,
+		})
+		baAsn1.encodeTag(buffer, ApplicationTag.DATE, true, 4)
+		encodeRawDateParts(buffer, {
+			year: 132, // 2032
+			month: 0xff,
+			day: 30,
+			wday: 0xff,
+		})
+		baAsn1.encodeClosingTag(buffer, 3)
+
+		const result = ReadProperty.decodeAcknowledge(
+			buffer.buffer,
+			0,
+			buffer.offset,
+		)
+		assert.ok(result)
+		const dateRange = result.values[0]
+		assert.equal(dateRange.type, ApplicationTag.DATERANGE)
+		const values = dateRange.value as any[]
+		assert.equal(values.length, 2)
+		// Partial wildcard raw dates (e.g. month=0xff) cannot be represented as concrete JS Date values.
+		// The decoder therefore normalizes value to ZERO_DATE while preserving original raw bytes.
+		assert.equal(values[0].value.getTime(), baAsn1.ZERO_DATE.getTime())
+		assert.equal(values[1].value.getTime(), baAsn1.ZERO_DATE.getTime())
+		assert.deepStrictEqual(values[0].raw, {
+			year: 121,
+			month: 0xff,
+			day: 28,
+			wday: 0xff,
+		})
+		assert.deepStrictEqual(values[1].raw, {
+			year: 132,
+			month: 0xff,
+			day: 30,
+			wday: 0xff,
+		})
+	})
+
 	test('should decode calendar date list payload', () => {
 		const buffer = utils.getBuffer()
 		encodeReadPropertyAckHeader(