@gobrand/tiempo 2.3.3 → 2.3.5

package/README.md

@@ -4,7 +4,7 @@
 [![CI](https://github.com/go-brand/tiempo/actions/workflows/ci.yml/badge.svg)](https://github.com/go-brand/tiempo/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Comprehensive datetime utilities for the [Temporal API](https://tc39.es/proposal-temporal/docs/). Full timezone support, nanosecond precision, and 54+ utility functions with a familiar API.
+Comprehensive datetime utilities for the [Temporal API](https://tc39.es/proposal-temporal/docs/). Full timezone support, nanosecond precision, and a familiar API.
 
 ## Installation
 
@@ -18,31 +18,39 @@ yarn add @gobrand/tiempo
 
 ## Why tiempo?
 
-The Temporal API is powerful but requires understanding its various methods and objects. **tiempo** (`@gobrand/tiempo`) provides 54+ intuitive utilities for every datetime task:
-
-- **🌍 Timezone conversions** - Convert between UTC and any timezone effortlessly
-- **➕ Complete arithmetic** - Add/subtract any time unit from nanoseconds to years
-- **📅 Calendar operations** - Start/end of day, week, month, year with DST handling
-- **🔍 Comparisons** - Check if dates are before, after, same day, future, or past
-- **📊 Differences** - Calculate precise differences in any time unit
-- **🎨 Formatting** - Format dates with date-fns-style tokens or Intl
-- **⚡️ Type-safe** - Full TypeScript support with proper Temporal types
-- **🎯 Zero config** - Simple, direct function signatures
-
-**Key features:**
-- ✅ Native timezone support with Temporal API
-- ✅ DST transitions handled automatically
-- ✅ Nanosecond precision (beyond milliseconds)
-- ✅ Calendar-aware arithmetic (leap years, month-end dates)
-- ✅ Familiar date-fns-style API, built for the future
-
-**Perfect for:**
-- Social media scheduling apps
-- Calendar applications
-- Booking systems
-- Time tracking tools
-- Analytics dashboards
-- Any app that needs to handle user timezones
+JavaScript's `Date` object was modeled after a Java class that was deprecated over 25 years ago. It conflates timestamps with calendar dates, only works in UTC or device-local time, and its mutating methods cause countless bugs. The [Temporal API](https://tc39.es/proposal-temporal/docs/) is the modern replacement, designed from the ground up to fix these problems.
+
+**tiempo** makes Temporal accessible with an intuitive, date-fns-style API:
+
+### The Temporal Advantage
+
+| Problem with `Date` | Temporal Solution | tiempo API |
+|---------------------|-------------------|------------|
+| Only UTC or local time | Any IANA timezone | `toZonedTime(date, "America/New_York")` |
+| Millisecond precision | Nanosecond precision | `addNanoseconds()`, `differenceInNanoseconds()` |
+| Mutating methods | Immutable operations | All functions return new values |
+| Ambiguous representations | Distinct types for each use case | `Instant`, `ZonedDateTime`, `PlainDate` |
+| DST bugs everywhere | DST-aware arithmetic | `addDays()` respects timezone rules |
+| Gregorian calendar only | Multi-calendar support | Works with Hebrew, Chinese, Japanese, and more |
+
+### Features
+
+- **First-class timezone support** - Convert, compare, and calculate across any of 400+ IANA timezones with confidence
+- **Nanosecond precision** - Beyond milliseconds for scientific computing, financial systems, and high-frequency operations
+- **DST-safe arithmetic** - Adding days means calendar days, not 24-hour periods that break at clock changes
+- **Immutable by design** - No mutations, no side effects, no surprises
+- **Type-safe** - Full TypeScript support catches datetime errors at compile time
+- **Familiar API** - date-fns-style functions built on modern foundations
+- **Zero dependencies** - Only the Temporal polyfill for browser compatibility
+
+### Perfect for
+
+- **Scheduling apps** - Social media, meetings, reminders with proper timezone handling
+- **Booking systems** - Hotels, flights, events across global timezones
+- **Calendar applications** - Date math that respects DST and leap years
+- **Time tracking** - Precise duration calculations with nanosecond accuracy
+- **Analytics dashboards** - Aggregate by day/week/month in user timezones
+- **Global applications** - Any app serving users across multiple timezones
 
 ## Quick Start
 
@@ -355,6 +363,54 @@ const todayFormatted = formatPlainDate(today(), "EEEE, MMMM do");
 // "Thursday, January 23rd"
 ```
 
+#### `simpleFormat(input, options?)`
+
+Format a Temporal date in a human-friendly way: "Dec 23" or "Dec 23, 2020". By default, shows the year only if the date is not in the current year. Optionally includes time in 12-hour or 24-hour format.
+
+**Parameters:**
+- `input` (Temporal.PlainDate | Temporal.ZonedDateTime | Temporal.Instant): The date to format
+- `options` (object, optional): Formatting options
+  - `locale` (string): BCP 47 language tag (default: "en-US")
+  - `year` ('auto' | 'always' | 'never'): Control year display (default: 'auto')
+  - `time` ('12h' | '24h'): Include time in output (not available for PlainDate)
+  - `timeZone` (string): IANA timezone identifier (required for Instant, optional for ZonedDateTime)
+
+**Returns:** `string` - Human-friendly formatted date string
+
+**Example:**
+```typescript
+import { simpleFormat, today, now } from '@gobrand/tiempo';
+
+// Assuming current year is 2026
+const date2026 = Temporal.ZonedDateTime.from("2026-12-23T15:30:00[America/New_York]");
+const date2020 = Temporal.ZonedDateTime.from("2020-12-23T15:30:00[America/New_York]");
+
+// Basic usage - year shown only for past years
+simpleFormat(date2026); // "Dec 23"
+simpleFormat(date2020); // "Dec 23, 2020"
+
+// With time
+simpleFormat(date2026, { time: '12h' }); // "Dec 23, 3:30 PM"
+simpleFormat(date2026, { time: '24h' }); // "Dec 23, 15:30"
+
+// Control year display
+simpleFormat(date2026, { year: 'always' }); // "Dec 23, 2026"
+simpleFormat(date2020, { year: 'never' }); // "Dec 23"
+
+// With Instant (timeZone required)
+const instant = Temporal.Instant.from("2026-12-23T20:30:00Z");
+simpleFormat(instant, { timeZone: 'America/New_York' }); // "Dec 23"
+simpleFormat(instant, { timeZone: 'America/New_York', time: '12h' }); // "Dec 23, 3:30 PM"
+
+// With PlainDate (no time option available)
+const plain = Temporal.PlainDate.from("2020-12-23");
+simpleFormat(plain); // "Dec 23, 2020"
+
+// Different locales
+simpleFormat(date2020, { locale: 'es-ES' }); // "23 dic 2020"
+simpleFormat(date2020, { locale: 'de-DE' }); // "23. Dez. 2020"
+```
+
 ### Start/End Utilities
 
 #### `today(timezone?)`

package/dist/chunk-GQBO2UXH.js

@@ -0,0 +1,46 @@
+// src/simpleFormat.ts
+import { Temporal } from "@js-temporal/polyfill";
+function simpleFormat(input, options = {}) {
+  const locale = options.locale ?? "en-US";
+  const time = "time" in options ? options.time : void 0;
+  const timeZone = "timeZone" in options ? options.timeZone : void 0;
+  const yearOption = "year" in options ? options.year : void 0;
+  let year;
+  let dateTimeForFormat;
+  if (input instanceof Temporal.Instant) {
+    const tz = timeZone ?? "UTC";
+    const zoned = input.toZonedDateTimeISO(tz);
+    year = zoned.year;
+    dateTimeForFormat = zoned;
+  } else if (input instanceof Temporal.ZonedDateTime) {
+    if (timeZone) {
+      const zoned = input.toInstant().toZonedDateTimeISO(timeZone);
+      year = zoned.year;
+      dateTimeForFormat = zoned;
+    } else {
+      year = input.year;
+      dateTimeForFormat = input;
+    }
+  } else {
+    year = input.year;
+    dateTimeForFormat = input;
+  }
+  const currentYear = Temporal.Now.plainDateISO().year;
+  const showYear = yearOption === "always" ? true : yearOption === "never" ? false : year !== currentYear;
+  const dateOptions = {
+    day: "numeric",
+    month: "short",
+    year: showYear ? "numeric" : void 0
+  };
+  if (time && !(input instanceof Temporal.PlainDate)) {
+    dateOptions.hour = "numeric";
+    dateOptions.minute = "2-digit";
+    dateOptions.hour12 = time === "12h";
+  }
+  return dateTimeForFormat.toLocaleString(locale, dateOptions);
+}
+
+export {
+  simpleFormat
+};
+//# sourceMappingURL=chunk-GQBO2UXH.js.map

package/dist/chunk-GQBO2UXH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/simpleFormat.ts"],"sourcesContent":["import { Temporal } from '@js-temporal/polyfill';\n\n// simpleFormat options - discriminated by input type\ninterface PlainDateOptions {\n  locale?: string;\n  year?: 'auto' | 'always' | 'never';\n}\n\ninterface ZonedDateTimeOptions {\n  locale?: string;\n  time?: '12h' | '24h';\n  timeZone?: string;\n  year?: 'auto' | 'always' | 'never';\n}\n\ninterface InstantOptions {\n  locale?: string;\n  time?: '12h' | '24h';\n  timeZone: string; // required for Instant\n  year?: 'auto' | 'always' | 'never';\n}\n\n/**\n * Format a Temporal date in a human-friendly way: \"Dec 23\" or \"Dec 23, 2020\"\n *\n * By default (year: 'auto'), shows the year only if the date is not in the current year.\n * Use year: 'always' to always show the year, or year: 'never' to always hide it.\n * Optionally includes time in 12-hour or 24-hour format.\n *\n * @example\n * ```typescript\n * // Assuming current year is 2026\n * const date2026 = Temporal.ZonedDateTime.from(\"2026-12-23T15:30:00[America/New_York]\");\n * const date2020 = Temporal.ZonedDateTime.from(\"2020-12-23T15:30:00[America/New_York]\");\n *\n * simpleFormat(date2026); // \"Dec 23\"\n * simpleFormat(date2020); // \"Dec 23, 2020\"\n * simpleFormat(date2026, { time: '12h' }); // \"Dec 23, 3:30 PM\"\n * simpleFormat(date2026, { time: '24h' }); // \"Dec 23, 15:30\"\n *\n * // Control year display\n * simpleFormat(date2026, { year: 'always' }); // \"Dec 23, 2026\"\n * simpleFormat(date2020, { year: 'never' }); // \"Dec 23\"\n * simpleFormat(date2020, { year: 'auto' }); // \"Dec 23, 2020\" (default behavior)\n *\n * // With Instant (timeZone required)\n * const instant = Temporal.Instant.from(\"2026-12-23T20:30:00Z\");\n * simpleFormat(instant, { timeZone: 'America/New_York' }); // \"Dec 23\"\n * simpleFormat(instant, { timeZone: 'America/New_York', time: '12h' }); // \"Dec 23, 3:30 PM\"\n *\n * // With PlainDate (no time option)\n * const plain = Temporal.PlainDate.from(\"2020-12-23\");\n * simpleFormat(plain); // \"Dec 23, 2020\"\n * ```\n */\nexport function simpleFormat(input: Temporal.PlainDate, options?: PlainDateOptions): string;\nexport function simpleFormat(input: Temporal.ZonedDateTime, options?: ZonedDateTimeOptions): string;\nexport function simpleFormat(input: Temporal.Instant, options: InstantOptions): string;\nexport function simpleFormat(\n  input: Temporal.PlainDate | Temporal.ZonedDateTime | Temporal.Instant,\n  options: PlainDateOptions | ZonedDateTimeOptions | InstantOptions = {}\n): string {\n  const locale = options.locale ?? 'en-US';\n  const time = 'time' in options ? options.time : undefined;\n  const timeZone = 'timeZone' in options ? options.timeZone : undefined;\n  const yearOption = 'year' in options ? options.year : undefined;\n\n  // Get year from the input (converting Instant to ZonedDateTime if needed)\n  let year: number;\n  let dateTimeForFormat: Temporal.PlainDate | Temporal.ZonedDateTime;\n\n  if (input instanceof Temporal.Instant) {\n    const tz = timeZone ?? 'UTC';\n    const zoned = input.toZonedDateTimeISO(tz);\n    year = zoned.year;\n    dateTimeForFormat = zoned;\n  } else if (input instanceof Temporal.ZonedDateTime) {\n    if (timeZone) {\n      const zoned = input.toInstant().toZonedDateTimeISO(timeZone);\n      year = zoned.year;\n      dateTimeForFormat = zoned;\n    } else {\n      year = input.year;\n      dateTimeForFormat = input;\n    }\n  } else {\n    year = input.year;\n    dateTimeForFormat = input;\n  }\n\n  // Determine if year should be shown\n  const currentYear = Temporal.Now.plainDateISO().year;\n  const showYear =\n    yearOption === 'always' ? true : yearOption === 'never' ? false : year !== currentYear;\n\n  const dateOptions: Intl.DateTimeFormatOptions = {\n    day: 'numeric',\n    month: 'short',\n    year: showYear ? 'numeric' : undefined,\n  };\n\n  // Add time options if requested and input supports it\n  if (time && !(input instanceof Temporal.PlainDate)) {\n    dateOptions.hour = 'numeric';\n    dateOptions.minute = '2-digit';\n    dateOptions.hour12 = time === '12h';\n  }\n\n  return dateTimeForFormat.toLocaleString(locale, dateOptions);\n}\n"],"mappings":";AAAA,SAAS,gBAAgB;AA0DlB,SAAS,aACd,OACA,UAAoE,CAAC,GAC7D;AACR,QAAM,SAAS,QAAQ,UAAU;AACjC,QAAM,OAAO,UAAU,UAAU,QAAQ,OAAO;AAChD,QAAM,WAAW,cAAc,UAAU,QAAQ,WAAW;AAC5D,QAAM,aAAa,UAAU,UAAU,QAAQ,OAAO;AAGtD,MAAI;AACJ,MAAI;AAEJ,MAAI,iBAAiB,SAAS,SAAS;AACrC,UAAM,KAAK,YAAY;AACvB,UAAM,QAAQ,MAAM,mBAAmB,EAAE;AACzC,WAAO,MAAM;AACb,wBAAoB;AAAA,EACtB,WAAW,iBAAiB,SAAS,eAAe;AAClD,QAAI,UAAU;AACZ,YAAM,QAAQ,MAAM,UAAU,EAAE,mBAAmB,QAAQ;AAC3D,aAAO,MAAM;AACb,0BAAoB;AAAA,IACtB,OAAO;AACL,aAAO,MAAM;AACb,0BAAoB;AAAA,IACtB;AAAA,EACF,OAAO;AACL,WAAO,MAAM;AACb,wBAAoB;AAAA,EACtB;AAGA,QAAM,cAAc,SAAS,IAAI,aAAa,EAAE;AAChD,QAAM,WACJ,eAAe,WAAW,OAAO,eAAe,UAAU,QAAQ,SAAS;AAE7E,QAAM,cAA0C;AAAA,IAC9C,KAAK;AAAA,IACL,OAAO;AAAA,IACP,MAAM,WAAW,YAAY;AAAA,EAC/B;AAGA,MAAI,QAAQ,EAAE,iBAAiB,SAAS,YAAY;AAClD,gBAAY,OAAO;AACnB,gBAAY,SAAS;AACrB,gBAAY,SAAS,SAAS;AAAA,EAChC;AAEA,SAAO,kBAAkB,eAAe,QAAQ,WAAW;AAC7D;","names":[]}

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { toUtcString } from './toUtcString';
 export { toDate } from './toDate';
 export { format, type FormatOptions } from './format';
 export { formatPlainDate, type FormatPlainDateOptions } from './formatPlainDate';
+export { simpleFormat } from './simpleFormat';
 export { today } from './today';
 export { now } from './now';
 export { startOfDay } from './startOfDay';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,9 +1,15 @@
+import {
+  toUtcString
+} from "./chunk-DMKGJY4N.js";
 import {
   toZonedTime
 } from "./chunk-2MP3ESL7.js";
 import {
   today
 } from "./chunk-67QHALIG.js";
+import {
+  subMonths
+} from "./chunk-52NEOY34.js";
 import {
   subNanoseconds
 } from "./chunk-WVHAYLBW.js";
@@ -23,8 +29,8 @@ import {
   toUtc
 } from "./chunk-BW5SFCKS.js";
 import {
-  toUtcString
-} from "./chunk-DMKGJY4N.js";
+  startOfMonth
+} from "./chunk-TU2UNOOW.js";
 import {
   startOfWeek
 } from "./chunk-2WMXB7QL.js";
@@ -46,9 +52,6 @@ import {
 import {
   subMinutes
 } from "./chunk-J6G2I2TU.js";
-import {
-  subMonths
-} from "./chunk-52NEOY34.js";
 import {
   isSameMonth
 } from "./chunk-ADQTZVMH.js";
@@ -67,12 +70,12 @@ import {
 import {
   now
 } from "./chunk-3YGPHHB6.js";
+import {
+  simpleFormat
+} from "./chunk-GQBO2UXH.js";
 import {
   startOfDay
 } from "./chunk-TW5EV3DH.js";
-import {
-  startOfMonth
-} from "./chunk-TU2UNOOW.js";
 import {
   isPlainDateAfter
 } from "./chunk-BPZ7BRJW.js";
@@ -238,6 +241,7 @@ export {
   isSameWeek,
   isSameYear,
   now,
+  simpleFormat,
   startOfDay,
   startOfMonth,
   startOfWeek,

package/dist/simpleFormat.d.ts

@@ -0,0 +1,55 @@
+import { Temporal } from '@js-temporal/polyfill';
+interface PlainDateOptions {
+    locale?: string;
+    year?: 'auto' | 'always' | 'never';
+}
+interface ZonedDateTimeOptions {
+    locale?: string;
+    time?: '12h' | '24h';
+    timeZone?: string;
+    year?: 'auto' | 'always' | 'never';
+}
+interface InstantOptions {
+    locale?: string;
+    time?: '12h' | '24h';
+    timeZone: string;
+    year?: 'auto' | 'always' | 'never';
+}
+/**
+ * Format a Temporal date in a human-friendly way: "Dec 23" or "Dec 23, 2020"
+ *
+ * By default (year: 'auto'), shows the year only if the date is not in the current year.
+ * Use year: 'always' to always show the year, or year: 'never' to always hide it.
+ * Optionally includes time in 12-hour or 24-hour format.
+ *
+ * @example
+ * ```typescript
+ * // Assuming current year is 2026
+ * const date2026 = Temporal.ZonedDateTime.from("2026-12-23T15:30:00[America/New_York]");
+ * const date2020 = Temporal.ZonedDateTime.from("2020-12-23T15:30:00[America/New_York]");
+ *
+ * simpleFormat(date2026); // "Dec 23"
+ * simpleFormat(date2020); // "Dec 23, 2020"
+ * simpleFormat(date2026, { time: '12h' }); // "Dec 23, 3:30 PM"
+ * simpleFormat(date2026, { time: '24h' }); // "Dec 23, 15:30"
+ *
+ * // Control year display
+ * simpleFormat(date2026, { year: 'always' }); // "Dec 23, 2026"
+ * simpleFormat(date2020, { year: 'never' }); // "Dec 23"
+ * simpleFormat(date2020, { year: 'auto' }); // "Dec 23, 2020" (default behavior)
+ *
+ * // With Instant (timeZone required)
+ * const instant = Temporal.Instant.from("2026-12-23T20:30:00Z");
+ * simpleFormat(instant, { timeZone: 'America/New_York' }); // "Dec 23"
+ * simpleFormat(instant, { timeZone: 'America/New_York', time: '12h' }); // "Dec 23, 3:30 PM"
+ *
+ * // With PlainDate (no time option)
+ * const plain = Temporal.PlainDate.from("2020-12-23");
+ * simpleFormat(plain); // "Dec 23, 2020"
+ * ```
+ */
+export declare function simpleFormat(input: Temporal.PlainDate, options?: PlainDateOptions): string;
+export declare function simpleFormat(input: Temporal.ZonedDateTime, options?: ZonedDateTimeOptions): string;
+export declare function simpleFormat(input: Temporal.Instant, options: InstantOptions): string;
+export {};
+//# sourceMappingURL=simpleFormat.d.ts.map

package/dist/simpleFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simpleFormat.d.ts","sourceRoot":"","sources":["../src/simpleFormat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGjD,UAAU,gBAAgB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;CACpC;AAED,UAAU,oBAAoB;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;CACpC;AAED,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAAC;AAC5F,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAAC;AACpG,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,CAAC"}

package/dist/simpleFormat.js

@@ -0,0 +1,7 @@
+import {
+  simpleFormat
+} from "./chunk-GQBO2UXH.js";
+export {
+  simpleFormat
+};
+//# sourceMappingURL=simpleFormat.js.map

package/dist/simpleFormat.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/simpleFormat.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=simpleFormat.test.d.ts.map

package/dist/simpleFormat.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simpleFormat.test.d.ts","sourceRoot":"","sources":["../src/simpleFormat.test.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gobrand/tiempo",
-  "version": "2.3.3",
+  "version": "2.3.5",
   "description": "Lightweight utility functions for converting between UTC and timezone-aware datetimes using the Temporal API",
   "private": false,
   "publishConfig": {
@@ -28,7 +28,7 @@
   "bugs": {
     "url": "https://github.com/go-brand/tiempo/issues"
   },
-  "homepage": "https://github.com/go-brand/tiempo#readme",
+  "homepage": "https://eng.gobrand.app/tiempo",
   "scripts": {
     "build": "tsup && tsc --emitDeclarationOnly",
     "clean": "git clean -xdf .cache .turbo dist node_modules tsconfig.tsbuildinfo",