@nhtio/encoder 1.20260611.0 → 1.20260624.1

package/index.d.ts

@@ -36,6 +36,17 @@ declare type CountryOrUnknown = Country | 'XX';
  */
 declare type CountryTimezone = 'Europe/Andorra' | 'Asia/Dubai' | 'Asia/Kabul' | 'America/Antigua' | 'America/Anguilla' | 'Europe/Tirane' | 'Asia/Yerevan' | 'Africa/Luanda' | 'Antarctica/Casey' | 'America/Argentina/Buenos_Aires' | 'Pacific/Pago_Pago' | 'Europe/Vienna' | 'Australia/Sydney' | 'America/Aruba' | 'Europe/Mariehamn' | 'Asia/Baku' | 'Europe/Sarajevo' | 'America/Barbados' | 'Asia/Dhaka' | 'Europe/Brussels' | 'Africa/Ouagadougou' | 'Europe/Sofia' | 'Asia/Bahrain' | 'Africa/Bujumbura' | 'Africa/Porto-Novo' | 'America/St_Barthelemy' | 'Atlantic/Bermuda' | 'Asia/Brunei' | 'America/La_Paz' | 'America/Kralendijk' | 'America/Sao_Paulo' | 'America/Nassau' | 'Asia/Thimphu' | 'Africa/Gaborone' | 'Europe/Minsk' | 'America/Belize' | 'America/Toronto' | 'Indian/Cocos' | 'Africa/Kinshasa' | 'Africa/Bangui' | 'Africa/Brazzaville' | 'Europe/Zurich' | 'Africa/Abidjan' | 'Pacific/Rarotonga' | 'America/Santiago' | 'Africa/Douala' | 'Asia/Shanghai' | 'America/Bogota' | 'America/Costa_Rica' | 'America/Havana' | 'Atlantic/Cape_Verde' | 'America/Curacao' | 'Indian/Christmas' | 'Asia/Nicosia' | 'Europe/Prague' | 'Europe/Berlin' | 'Africa/Djibouti' | 'Europe/Copenhagen' | 'America/Dominica' | 'America/Santo_Domingo' | 'Africa/Algiers' | 'America/Guayaquil' | 'Europe/Tallinn' | 'Africa/Cairo' | 'Africa/El_Aaiun' | 'Africa/Asmara' | 'Europe/Madrid' | 'Africa/Addis_Ababa' | 'Europe/Helsinki' | 'Pacific/Fiji' | 'Atlantic/Stanley' | 'Pacific/Pohnpei' | 'Atlantic/Faroe' | 'Europe/Paris' | 'Africa/Libreville' | 'Europe/London' | 'America/Grenada' | 'Asia/Tbilisi' | 'America/Cayenne' | 'Europe/Guernsey' | 'Africa/Accra' | 'Europe/Gibraltar' | 'America/Godthab' | 'Africa/Banjul' | 'Africa/Conakry' | 'America/Guadeloupe' | 'Africa/Malabo' | 'Europe/Athens' | 'Atlantic/South_Georgia' | 'America/Guatemala' | 'Pacific/Guam' | 'Africa/Bissau' | 'America/Guyana' | 'Asia/Hong_Kong' | 'America/Tegucigalpa' | 'Europe/Zagreb' | 'America/Port-au-Prince' | 'Europe/Budapest' | 'Asia/Jakarta' | 'Europe/Dublin' | 'Asia/Jerusalem' | 'Europe/Isle_of_Man' | 'Asia/Kolkata' | 'Indian/Chagos' | 'Asia/Baghdad' | 'Asia/Tehran' | 'Atlantic/Reykjavik' | 'Europe/Rome' | 'Europe/Jersey' | 'America/Jamaica' | 'Asia/Amman' | 'Asia/Tokyo' | 'Africa/Nairobi' | 'Asia/Bishkek' | 'Asia/Phnom_Penh' | 'Pacific/Tarawa' | 'Indian/Comoro' | 'America/St_Kitts' | 'Asia/Pyongyang' | 'Asia/Seoul' | 'Asia/Kuwait' | 'America/Cayman' | 'Asia/Almaty' | 'Asia/Vientiane' | 'Asia/Beirut' | 'America/St_Lucia' | 'Europe/Vaduz' | 'Asia/Colombo' | 'Africa/Monrovia' | 'Africa/Maseru' | 'Europe/Vilnius' | 'Europe/Luxembourg' | 'Europe/Riga' | 'Africa/Tripoli' | 'Africa/Casablanca' | 'Europe/Monaco' | 'Europe/Chisinau' | 'Europe/Podgorica' | 'America/Marigot' | 'Indian/Antananarivo' | 'Pacific/Majuro' | 'Europe/Skopje' | 'Africa/Bamako' | 'Asia/Yangon' | 'Asia/Ulaanbaatar' | 'Asia/Macau' | 'Pacific/Saipan' | 'America/Martinique' | 'Africa/Nouakchott' | 'America/Montserrat' | 'Europe/Malta' | 'Indian/Mauritius' | 'Indian/Maldives' | 'Africa/Blantyre' | 'America/Mexico_City' | 'Asia/Kuala_Lumpur' | 'Africa/Maputo' | 'Africa/Windhoek' | 'Pacific/Noumea' | 'Africa/Niamey' | 'Pacific/Norfolk' | 'Africa/Lagos' | 'America/Managua' | 'Europe/Amsterdam' | 'Europe/Oslo' | 'Asia/Kathmandu' | 'Pacific/Nauru' | 'Pacific/Niue' | 'Pacific/Auckland' | 'Asia/Muscat' | 'America/Panama' | 'America/Lima' | 'Pacific/Tahiti' | 'Pacific/Port_Moresby' | 'Asia/Manila' | 'Asia/Karachi' | 'Europe/Warsaw' | 'America/Miquelon' | 'Pacific/Pitcairn' | 'America/Puerto_Rico' | 'Asia/Gaza' | 'Europe/Lisbon' | 'Pacific/Palau' | 'America/Asuncion' | 'Asia/Qatar' | 'Indian/Reunion' | 'Europe/Bucharest' | 'Europe/Belgrade' | 'Europe/Moscow' | 'Africa/Kigali' | 'Asia/Riyadh' | 'Pacific/Guadalcanal' | 'Indian/Mahe' | 'Africa/Khartoum' | 'Europe/Stockholm' | 'Asia/Singapore' | 'Atlantic/St_Helena' | 'Europe/Ljubljana' | 'Arctic/Longyearbyen' | 'Europe/Bratislava' | 'Africa/Freetown' | 'Europe/San_Marino' | 'Africa/Dakar' | 'Africa/Mogadishu' | 'America/Paramaribo' | 'Africa/Juba' | 'Africa/Sao_Tome' | 'America/El_Salvador' | 'America/Lower_Princes' | 'Asia/Damascus' | 'Africa/Mbabane' | 'America/Grand_Turk' | 'Africa/Ndjamena' | 'Indian/Kerguelen' | 'Africa/Lome' | 'Asia/Bangkok' | 'Asia/Dushanbe' | 'Pacific/Fakaofo' | 'Asia/Dili' | 'Asia/Ashgabat' | 'Africa/Tunis' | 'Pacific/Tongatapu' | 'Europe/Istanbul' | 'America/Port_of_Spain' | 'Pacific/Funafuti' | 'Asia/Taipei' | 'Africa/Dar_es_Salaam' | 'Europe/Kiev' | 'Africa/Kampala' | 'Pacific/Wake' | 'America/New_York' | 'America/Montevideo' | 'Asia/Tashkent' | 'Europe/Vatican' | 'America/St_Vincent' | 'America/Caracas' | 'America/Tortola' | 'America/St_Thomas' | 'Asia/Ho_Chi_Minh' | 'Pacific/Efate' | 'Pacific/Wallis' | 'Pacific/Apia' | 'Asia/Aden' | 'Indian/Mayotte' | 'Africa/Johannesburg' | 'Africa/Lusaka' | 'Africa/Harare';
 
+/**
+ * A class that opts in to custom encoding/decoding.
+ *
+ * Implement `[ENCODE_METHOD]()` on instances to produce an Encodable snapshot,
+ * and `static [DECODE_METHOD](data)` to reconstruct the instance.
+ * Pass the class to `registerClass()` so the decoder can find it.
+ */
+export declare interface CustomEncodable {
+    [ENCODE_METHOD](): Encodable;
+}
+
 declare type DateInput = DateTime | DateObjectUnits | Date;
 
 /**
@@ -1485,6 +1496,11 @@ declare type DayNumbers =
 | 30
 | 31;
 
+declare interface DecodableConstructor {
+    readonly name: string;
+    [DECODE_METHOD](data: Encodable): any;
+}
+
 /**
  * Decodes a compressed base64 string back into a value
  * @param base64 The compressed base64 string representing an encoded value
@@ -1496,6 +1512,9 @@ declare type DayNumbers =
  */
 export declare const decode: <T extends Encodable = Encodable>(base64: string) => T;
 
+/** Static method: reconstruct an instance from an Encodable snapshot */
+export declare const DECODE_METHOD: unique symbol;
+
 declare type DefaultValidity = CanBeInvalid extends true ? boolean : true;
 
 declare interface DiffOptions {
@@ -1996,7 +2015,7 @@ declare type DurationUnits = DurationUnit | DurationUnit[];
  */
 export declare type Encodable = EncodablePrimitive | Date | RegExp | ArrayBuffer | DataView | DateTime | Duration | Interval | EncodableTypedArray | Encodable[] | {
     [key: string]: Encodable;
-} | Map<Encodable, Encodable> | Set<Encodable> | Error | EvalError | RangeError | ReferenceError | SyntaxError | TypeError | URIError | PhoneModel | Function | ((...args: any[]) => any);
+} | Map<Encodable, Encodable> | Set<Encodable> | Error | EvalError | RangeError | ReferenceError | SyntaxError | TypeError | URIError | PhoneModel | Function | ((...args: any[]) => any) | CustomEncodable;
 
 /**
  * Defines the union of all encodable primitive types.
@@ -2018,6 +2037,9 @@ export declare type EncodableTypedArray = Int8Array | Uint8Array | Uint8ClampedA
  */
 export declare const encode: <T extends Encodable = Encodable>(what: T) => string;
 
+/** Instance method: serialize the object into an Encodable snapshot */
+export declare const ENCODE_METHOD: unique symbol;
+
 declare type EndOfOptions = _UseLocaleWeekOption;
 
 declare interface ExplainedFormat {
@@ -2638,6 +2660,15 @@ declare type PossibleWeeksInYear = 52 | 53;
 
 declare type QuarterNumbers = 1 | 2 | 3 | 4;
 
+/**
+ * Register a class so the decoder can reconstruct it from a snapshot.
+ * The class must have a static `[DECODE_METHOD]` that accepts an Encodable
+ * snapshot and returns an instance of the class.
+ *
+ * @param ctor - The class constructor to register
+ */
+export declare const registerClass: (ctor: DecodableConstructor) => void;
+
 declare type ResolvedLocaleOptions = Required<LocaleOptions>;
 
 declare type SecondNumbers =

package/index.mjs

@@ -1,6 +1,6 @@
-import { i as isObject, a as isArray, b as isSet, c as isMap, d as isLuxonSystemZone, e as isLuxonInterval, f as isLuxonDuration, g as isLuxonDateTime, h as isPhoneObject, j as isTypedArray, k as isBigIntTypedArray, l as isPrimitive, m as isUniterableObject, n as isError, o as isBigInt, p as isUnsafeInteger, q as isNegativeInfinity, r as isPositiveInfinity, s as isNegativeZero, I as Info, t as Interval, D as DateTime, u as Duration, P as Phone } from "./type_guards-UkDoe__i.mjs";
+import { i as isObject, a as isCustomEncodable, E as ENCODE_METHOD, b as isArray, c as isSet, d as isMap, e as isLuxonSystemZone, f as isLuxonInterval, I as Interval, D as DateTime, g as isLuxonDuration, h as Duration, j as isLuxonDateTime, k as isPhoneObject, l as isTypedArray, m as isBigIntTypedArray, n as isPrimitive, o as isUniterableObject, p as isError, q as isBigInt, r as isUnsafeInteger, s as isNegativeInfinity, t as isPositiveInfinity, u as isNegativeZero, v as DECODE_METHOD, w as Info, P as Phone } from "./type_guards-DMqlMT2e.mjs";
 import { FunctionSerializer } from "./function_serializer.mjs";
-import { E as E_UNENCODABLE_VALUE, a as E_CIRCULAR_REFERENCE, b as E_ENCODING_FAILED, B as BaseException, c as E_UNDECODABLE_VALUE, d as E_NOT_AN_ENCODED_VALUE, e as E_INVALID_VERSION, f as E_INCOMPATIBLE_VERSION } from "./exceptions-WJOP87c3.mjs";
+import { E as E_UNENCODABLE_VALUE, a as E_CIRCULAR_REFERENCE, b as E_ENCODING_FAILED, B as BaseException, c as E_UNDECODABLE_VALUE, d as E_NOT_AN_ENCODED_VALUE, e as E_INVALID_VERSION, f as E_INCOMPATIBLE_VERSION } from "./exceptions-CqtGXEDJ.mjs";
 var re = { exports: {} };
 var constants;
 var hasRequiredConstants;
@@ -2728,6 +2728,16 @@ const atou = (base64) => {
   }
   return decodeURIComponent(escape(binary));
 };
+const registry = /* @__PURE__ */ new Map();
+const registerClass = (ctor) => {
+  if (typeof ctor.name !== "string" || ctor.name === "") {
+    throw new TypeError("Cannot register an anonymous class — give it an explicit name.");
+  }
+  registry.set(ctor.name, ctor);
+};
+const getRegisteredClass = (name) => {
+  return registry.get(name);
+};
 const VOID = -1;
 const PRIMITIVE = 0;
 const ARRAY = 1;
@@ -2936,6 +2946,13 @@ const serialize = (value, { json, lossy } = {}) => {
 const stripUndefinedValuesFromObject = (obj) => {
   return Object.fromEntries(Object.entries(obj).filter(([_, value]) => value !== void 0));
 };
+const fixedOffsetToZoneName = (fixed) => {
+  const sign = fixed >= 0 ? "+" : "-";
+  const abs = Math.abs(fixed);
+  const hours = Math.floor(abs / 60);
+  const minutes = abs % 60;
+  return minutes === 0 ? `UTC${sign}${hours}` : `UTC${sign}${hours}:${String(minutes).padStart(2, "0")}`;
+};
 const toStructuredData = (value, seen = /* @__PURE__ */ new WeakSet()) => {
   switch (true) {
     case isNegativeZero(value): {
@@ -3025,7 +3042,19 @@ const toStructuredData = (value, seen = /* @__PURE__ */ new WeakSet()) => {
         throw new E_CIRCULAR_REFERENCE();
       }
       seen.add(value);
-      const dto = value;
+      const dto = value instanceof DateTime ? value : typeof value.toMillis === "function" ? value : (() => {
+        const raw = value;
+        const zone = raw._zone && typeof raw._zone.zoneName === "string" ? raw._zone.zoneName : raw._zone && typeof raw._zone.fixed === "number" ? fixedOffsetToZoneName(raw._zone.fixed) : void 0;
+        const locale = raw.loc && typeof raw.loc.locale === "string" ? raw.loc.locale : void 0;
+        const outputCalendar = raw.loc && typeof raw.loc.outputCalendar === "string" ? raw.loc.outputCalendar : void 0;
+        const numberingSystem = raw.loc && typeof raw.loc.numberingSystem === "string" ? raw.loc.numberingSystem : void 0;
+        return DateTime.fromMillis(typeof raw.ts === "number" ? raw.ts : 0, {
+          zone,
+          locale,
+          outputCalendar,
+          numberingSystem
+        });
+      })();
       return {
         _t: "luxon:DateTime",
         _s: toStructuredData(
@@ -3045,16 +3074,27 @@ const toStructuredData = (value, seen = /* @__PURE__ */ new WeakSet()) => {
         throw new E_CIRCULAR_REFERENCE();
       }
       seen.add(value);
+      const dur = value instanceof Duration ? value : typeof value.get === "function" ? value : (() => {
+        const raw = value;
+        const locale = raw.loc && typeof raw.loc.locale === "string" ? raw.loc.locale : void 0;
+        const rawValues = raw.values && typeof raw.values === "object" ? raw.values : {};
+        const values = Object.fromEntries(
+          Object.entries(rawValues).filter(
+            ([, val]) => typeof val === "number" && Number.isFinite(val)
+          )
+        );
+        return Duration.fromObject(values, { locale });
+      })();
       const dto = {
-        years: value.years,
-        quarters: value.quarters,
-        months: value.months,
-        weeks: value.weeks,
-        days: value.days,
-        hours: value.hours,
-        minutes: value.minutes,
-        seconds: value.seconds,
-        milliseconds: value.milliseconds
+        years: dur.years,
+        quarters: dur.quarters,
+        months: dur.months,
+        weeks: dur.weeks,
+        days: dur.days,
+        hours: dur.hours,
+        minutes: dur.minutes,
+        seconds: dur.seconds,
+        milliseconds: dur.milliseconds
       };
       Object.entries(dto).forEach(([key, val]) => {
         if (Number.isNaN(val) || val === 0) {
@@ -3071,8 +3111,17 @@ const toStructuredData = (value, seen = /* @__PURE__ */ new WeakSet()) => {
         throw new E_CIRCULAR_REFERENCE();
       }
       seen.add(value);
-      const start = value.start ? value.start.toISO({ extendedZone: true }) : null;
-      const end = value.end ? value.end.toISO({ extendedZone: true }) : null;
+      const iv = value instanceof Interval ? value : typeof value.toISO === "function" ? value : (() => {
+        const raw = value;
+        const startMs = raw.s && typeof raw.s.ts === "number" ? raw.s.ts : null;
+        const endMs = raw.e && typeof raw.e.ts === "number" ? raw.e.ts : null;
+        return Interval.fromDateTimes(
+          startMs !== null ? DateTime.fromMillis(startMs) : DateTime.invalid("missing start"),
+          endMs !== null ? DateTime.fromMillis(endMs) : DateTime.invalid("missing end")
+        );
+      })();
+      const start = iv.start ? iv.start.toISO({ extendedZone: true }) : null;
+      const end = iv.end ? iv.end.toISO({ extendedZone: true }) : null;
       if (!start || !end) {
         throw new E_UNENCODABLE_VALUE(value);
       }
@@ -3134,6 +3183,25 @@ const toStructuredData = (value, seen = /* @__PURE__ */ new WeakSet()) => {
         _s: utoa(JSON.stringify(value.map((item) => toStructuredData(item, seen))))
       };
     }
+    case isCustomEncodable(value): {
+      if (seen.has(value)) {
+        throw new E_CIRCULAR_REFERENCE();
+      }
+      seen.add(value);
+      const className = value.constructor.name;
+      try {
+        const snapshot = value[ENCODE_METHOD]();
+        return {
+          _t: `custom:${className}`,
+          _s: toStructuredData(snapshot, seen)
+        };
+      } catch (e) {
+        if (e instanceof BaseException) {
+          throw e;
+        }
+        throw new E_ENCODING_FAILED(value, e);
+      }
+    }
     case isObject(value): {
       if (seen.has(value)) {
         throw new E_CIRCULAR_REFERENCE();
@@ -3260,19 +3328,44 @@ const fromStructuredData = (data) => {
         throw err2;
       }
     }
-    default:
+    default: {
+      if (data._t.startsWith("custom:")) {
+        const className = data._t.slice("custom:".length);
+        const ctor = getRegisteredClass(className);
+        if (!ctor) {
+          const err2 = new E_UNDECODABLE_VALUE(data._t);
+          err2.cause = new Error(
+            `No class registered for "${className}". Call registerClass(${className}) before decoding.`
+          );
+          throw err2;
+        }
+        try {
+          const snapshot = fromStructuredData(data._s);
+          return ctor[DECODE_METHOD](snapshot);
+        } catch (e) {
+          if (e instanceof BaseException) {
+            throw e;
+          }
+          const err2 = new E_UNDECODABLE_VALUE(data._t);
+          if (e instanceof Error) {
+            err2.cause = e;
+          }
+          throw err2;
+        }
+      }
       throw new E_UNDECODABLE_VALUE(data._t);
+    }
   }
 };
 const { parse: $parse, stringify: $stringify } = JSON;
 const options = { json: true, lossy: true };
 const parse = (str) => deserialize($parse(str));
 const stringify = (any) => $stringify(serialize(any, options));
-const version = "1.20260611.0";
+const version = "1.20260624.1";
 const encode = (what) => {
   const structured = toStructuredData(what);
   const serialized = serialize(structured, { lossy: true, json: true });
-  const json = stringify({ version: "1.20260611.0", serialized });
+  const json = stringify({ version: "1.20260624.1", serialized });
   return utoa(json);
 };
 const decode = (base64) => {
@@ -3283,11 +3376,11 @@ const decode = (base64) => {
       throw new E_NOT_AN_ENCODED_VALUE(base64);
     }
     const { version: payloadVersion, serialized } = parsed;
-    if (semverExports.valid("1.20260611.0")) {
+    if (semverExports.valid("1.20260624.1")) {
       if (!semverExports.valid(semverExports.coerce(payloadVersion))) {
         throw new E_INVALID_VERSION(payloadVersion);
       }
-      if (semverExports.gt(semverExports.coerce(payloadVersion), "1.20260611.0")) {
+      if (semverExports.gt(semverExports.coerce(payloadVersion), "1.20260624.1")) {
         throw new E_INCOMPATIBLE_VERSION(payloadVersion);
       }
     }
@@ -3303,8 +3396,11 @@ const decode = (base64) => {
   }
 };
 export {
+  DECODE_METHOD,
+  ENCODE_METHOD,
   decode,
   encode,
+  registerClass,
   version
 };
 //# sourceMappingURL=index.mjs.map