@dereekb/date 13.6.11 → 13.6.13

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dereekb/date",
-  "version": "13.6.11",
+  "version": "13.6.13",
   "peerDependencies": {
-    "@dereekb/model": "13.6.11",
-    "@dereekb/rxjs": "13.6.11",
-    "@dereekb/util": "13.6.11",
+    "@dereekb/model": "13.6.13",
+    "@dereekb/rxjs": "13.6.13",
+    "@dereekb/util": "13.6.13",
     "@vvo/tzdb": "^6.0.0",
     "arktype": "^2.2.0",
     "date-fns": "^4.0.0",
@@ -14,7 +14,7 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@dereekb/rxjs": "13.6.11"
+    "@dereekb/rxjs": "13.6.13"
   },
   "exports": {
     "./package.json": "./package.json",

package/src/lib/date/date.duration.data.d.ts

@@ -0,0 +1,140 @@
+import { type Milliseconds, type TimeUnit } from '@dereekb/util';
+/**
+ * Represents a time duration decomposed into individual unit fields.
+ *
+ * Each field is optional and defaults to 0 if not provided.
+ * Used for parsing, formatting, and popover picker state.
+ */
+export interface TimeDurationData {
+    readonly weeks?: number;
+    readonly days?: number;
+    readonly hours?: number;
+    readonly minutes?: number;
+    readonly seconds?: number;
+    readonly milliseconds?: number;
+}
+/**
+ * Returns true if the input TimeDurationData has no meaningful values (all zero or undefined).
+ *
+ * @param data - The duration data to check
+ * @returns True if empty
+ *
+ * @example
+ * ```typescript
+ * timeDurationDataIsEmpty({}); // true
+ * timeDurationDataIsEmpty({ hours: 0, minutes: 0 }); // true
+ * timeDurationDataIsEmpty({ hours: 1 }); // false
+ * ```
+ */
+export declare function timeDurationDataIsEmpty(data: TimeDurationData): boolean;
+/**
+ * Converts a TimeDurationData to total milliseconds by summing all fields.
+ *
+ * @param data - The duration data to convert
+ * @returns Total milliseconds
+ *
+ * @example
+ * ```typescript
+ * durationDataToMilliseconds({ hours: 1, minutes: 30 }); // 5400000
+ * durationDataToMilliseconds({ days: 1, hours: 2 }); // 93600000
+ * ```
+ */
+export declare function durationDataToMilliseconds(data: TimeDurationData): Milliseconds;
+/**
+ * Decomposes milliseconds into a TimeDurationData object using the specified units.
+ *
+ * Breaks down from largest to smallest unit, only using units in the provided list.
+ *
+ * @param ms - The total milliseconds to decompose
+ * @param units - Which units to decompose into (defaults to days, hours, minutes, seconds)
+ * @returns A TimeDurationData with the decomposed values
+ *
+ * @example
+ * ```typescript
+ * millisecondsToDurationData(5400000); // { days: 0, hours: 1, minutes: 30, seconds: 0 }
+ * millisecondsToDurationData(90000, ['min', 's']); // { minutes: 1, seconds: 30 }
+ * ```
+ */
+export declare function millisecondsToDurationData(ms: Milliseconds, units?: readonly TimeUnit[]): TimeDurationData;
+/**
+ * Reads a specific time unit value from a TimeDurationData object.
+ *
+ * @param data - The duration data
+ * @param unit - The time unit to read
+ * @returns The value for that unit, or 0 if not set
+ */
+export declare function getDurationDataValue(data: TimeDurationData, unit: TimeUnit): number;
+/**
+ * Returns a new TimeDurationData with the specified unit set to the given value.
+ *
+ * @param data - The original duration data
+ * @param unit - The time unit to set
+ * @param value - The new value
+ * @returns A new TimeDurationData with the updated value
+ */
+export declare function setDurationDataValue(data: TimeDurationData, unit: TimeUnit, value: number): TimeDurationData;
+/**
+ * Parses a human-readable duration string into a TimeDurationData object.
+ *
+ * Supports compact formats ("3d10h5m8s"), spaced formats ("3d 10h 5m 8s"),
+ * and long formats ("3 days 10 hours 5 minutes 8 seconds"). Mixed formats
+ * are also supported. If the same unit appears multiple times, values are summed.
+ *
+ * If the string contains only a number with no unit, it is treated as the
+ * smallest unit that would make sense (milliseconds by default).
+ *
+ * @param input - The duration string to parse
+ * @returns A TimeDurationData object with the parsed values
+ *
+ * @example
+ * ```typescript
+ * parseDurationString('3d10h5m8s'); // { days: 3, hours: 10, minutes: 5, seconds: 8 }
+ * parseDurationString('2 hours 30 minutes'); // { hours: 2, minutes: 30 }
+ * parseDurationString('1w 2d'); // { weeks: 1, days: 2 }
+ * parseDurationString('500ms'); // { milliseconds: 500 }
+ * ```
+ */
+export declare function parseDurationString(input: string): TimeDurationData;
+/**
+ * Parses a duration string directly to milliseconds.
+ *
+ * @param input - The duration string to parse
+ * @returns Total milliseconds
+ *
+ * @example
+ * ```typescript
+ * parseDurationStringToMilliseconds('1h30m'); // 5400000
+ * ```
+ */
+export declare function parseDurationStringToMilliseconds(input: string): Milliseconds;
+/**
+ * Formats a TimeDurationData to a compact string like "3d10h5m8s".
+ *
+ * Omits zero-value units. Returns "0s" if all fields are zero or empty.
+ *
+ * @param data - The duration data to format
+ * @returns A compact duration string
+ *
+ * @example
+ * ```typescript
+ * formatDurationString({ days: 3, hours: 10, minutes: 5, seconds: 8 }); // "3d10h5m8s"
+ * formatDurationString({ hours: 2, minutes: 30 }); // "2h30m"
+ * formatDurationString({}); // "0s"
+ * ```
+ */
+export declare function formatDurationString(data: TimeDurationData): string;
+/**
+ * Formats a TimeDurationData to a long human-readable string.
+ *
+ * Omits zero-value units. Returns "0 seconds" if all fields are zero or empty.
+ *
+ * @param data - The duration data to format
+ * @returns A human-readable duration string
+ *
+ * @example
+ * ```typescript
+ * formatDurationStringLong({ days: 3, hours: 10 }); // "3 days 10 hours"
+ * formatDurationStringLong({ hours: 1, minutes: 1 }); // "1 hour 1 minute"
+ * ```
+ */
+export declare function formatDurationStringLong(data: TimeDurationData): string;

package/src/lib/date/date.model.d.ts

@@ -45,7 +45,7 @@ export declare const dateRangeType: import("arktype/internal/variants/object.ts"
 export declare const dateRangeParamsType: import("arktype/internal/variants/object.ts").ObjectType<{
     type: DateRangeType;
     date: Date | ((In: string) => import("arktype/internal/attributes.ts").To<Date>);
-    distance?: number | undefined;
+    distance?: number | null | undefined;
 }, {}>;
 /**
  * ArkType DTO schema for {@link DateCell}.
@@ -66,7 +66,7 @@ export declare const dateCellType: import("arktype/internal/variants/object.ts")
  */
 export declare const dateCellRangeType: import("arktype/internal/variants/object.ts").ObjectType<{
     i: number;
-    to?: number | undefined;
+    to?: number | null | undefined;
 }, {}>;
 /**
  * ArkType DTO schema for {@link DateCellTiming}.
@@ -102,8 +102,8 @@ export declare const calendarDateType: import("arktype/internal/variants/object.
  */
 export declare const dateCellScheduleType: import("arktype/internal/variants/object.ts").ObjectType<{
     w: string;
-    d?: number[] | undefined;
-    ex?: number[] | undefined;
+    d?: number[] | null | undefined;
+    ex?: number[] | null | undefined;
 }, {}>;
 /**
  * ArkType DTO schema for {@link ModelRecurrenceInfo}.
@@ -116,8 +116,8 @@ export declare const modelRecurrenceInfoType: import("arktype/internal/variants/
     rrule: string;
     start: Date | ((In: string) => import("arktype/internal/attributes.ts").To<Date>);
     end: Date | ((In: string) => import("arktype/internal/attributes.ts").To<Date>);
-    timezone?: string | undefined;
-    forever?: boolean | undefined;
+    timezone?: string | null | undefined;
+    forever?: boolean | null | undefined;
 }, {}>;
 /**
  * ArkType DTO schema that validates a value is a valid {@link DateCellTiming}.
@@ -138,7 +138,7 @@ export declare const validDateCellTimingType: import("arktype/internal/variants/
  */
 export declare const validDateCellRangeType: import("arktype/internal/variants/object.ts").ObjectType<{
     i: number;
-    to?: number | undefined;
+    to?: number | null | undefined;
 }, {}>;
 /**
  * ArkType DTO schema that validates a value is a sorted array of non-overlapping {@link DateCellRange} values.
@@ -147,5 +147,5 @@ export declare const validDateCellRangeType: import("arktype/internal/variants/o
  */
 export declare const validDateCellRangeSeriesType: import("arktype/internal/variants/array.ts").ArrayType<{
     i: number;
-    to?: number | undefined;
+    to?: number | null | undefined;
 }[], {}>;

package/src/lib/date/index.d.ts

@@ -7,6 +7,7 @@ export * from './date.cell';
 export * from './date.cell.week';
 export * from './date.calendar';
 export * from './date.duration';
+export * from './date.duration.data';
 export * from './date.format';
 export * from './date.model';
 export * from './date.hashset';