temporal-fmt 0.7.8 → 0.7.95

package/README.md

@@ -1,4 +1,4 @@
-# temporal-fmt
+# temporal-fmt 🥶🔥
 
 Format `Temporal.PlainDate` / `PlainTime` / `PlainDateTime` / `ZonedDateTime` objects
 using date-fns-style token strings.
@@ -202,19 +202,30 @@ sitting in your output waiting to confuse someone in three weeks.
   tokens (`yyyy`/`MM`/`dd`) never go through `Intl` and aren't affected.
 - Gluing two unpadded numeric tokens with no separator between them (e.g.
   `Md`, `dM`, `Hm`) is ambiguous for some inputs, and `parse()` throws rather
-  than guessing. `"121"` against `Md` could mean month 1/day 21 or month
+  than guessing. `"121"` against `yyyy-Md` could mean month 1/day 21 or month
   12/day 1 — both are valid, so there's no single correct reading to fall
   back to. Unambiguous inputs against the same format string still parse
-  normally (`"85"` against `Md` only has one valid split). If you need glued
-  numeric fields, either zero-pad them (`MM`/`dd`) or put a separator between
-  them; that removes the ambiguity entirely.
+  normally (`"85"` against `yyyy-Md` only has one valid split). If you need
+  glued numeric fields, either zero-pad them (`MM`/`dd`) or put a separator
+  between them; that removes the ambiguity entirely.
+
+  Note: `Md` (or `dM`/`Hm`) alone, with no `yyyy`, always throws —
+  `parse()` requires year, month, and day together to build a date, so a
+  bare `Md` format string is incomplete regardless of ambiguity. The
+  examples above use `yyyy-Md` for exactly this reason.
 
 ## Dev notes
 
-`tsconfig.json` sets `ignoreDeprecations: "6.0"` to work around a tsup bug
-([tsup#1388](https://github.com/egoist/tsup/issues/1388)/[#1389](https://github.com/egoist/tsup/issues/1389)). tsup's dts build step quietly injects a deprecated
-`baseUrl`, and TypeScript 6+ hard-errors on it. Workaround, not a fix — drop
-it the moment tsup ships a real one upstream.
+Building requires TypeScript 7.0.2+ but `.d.ts` generation runs as a separate
+`tsc` pass, not through tsup. tsup's dts step bundles types via
+`rollup-plugin-dts`, which calls into TypeScript's compiler API — the API
+isn't stable yet on 7.x ([targeted for
+7.1](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/)),
+so it crashes on 7.0.2. `tsup.config.ts` sets `dts: false` and `build` runs
+`tsup && tsc --declaration --emitDeclarationOnly` instead. One side effect:
+`dist/` now has one `.d.ts` per source file instead of a single rolled-up
+`index.d.ts` — same exported API, different file layout. Revert to `dts:
+true` once tsup/rollup-plugin-dts catch up.
 
 Tests pull from `temporal-polyfill/full`, not the slim `temporal-polyfill` —
 the Hebrew-calendar test needs the full build's calendar data, and the slim
@@ -227,4 +238,4 @@ through `Intl.DateTimeFormat` directly; on the polyfill, it falls back to
 
 ## License
 
-MIT
+MIT

package/dist/constants.d.ts

@@ -0,0 +1 @@
+export declare const MAX_FORMAT_LENGTH = 1000;

package/dist/format.d.ts

@@ -0,0 +1,13 @@
+import { type TemporalLike, type FormatOptions } from './tokens.js';
+/**
+ * Format a Temporal.PlainDate, PlainTime, PlainDateTime, or ZonedDateTime
+ * using a date-fns-style token string.
+ *
+ * @example
+ * format(Temporal.Now.plainDateISO(), 'yyyy-MM-dd') // "2026-08-04"
+ * format(zdt, "MMM d, yyyy 'at' h:mm a") // "Aug 4, 2026 at 3:45 PM"
+ * format(zdt, 'MMMM d, yyyy', { locale: 'fr-FR' }) // "août 4, 2026"
+ *
+ * Throws on a token the input type doesn't support (e.g. 'HH' on a PlainDate).
+ */
+export declare function format(temporal: TemporalLike, formatStr: string, options?: FormatOptions): string;

package/dist/index.d.ts

@@ -1,83 +1,5 @@
-interface TemporalLike {
-    year?: number;
-    month?: number;
-    day?: number;
-    hour?: number;
-    minute?: number;
-    second?: number;
-    millisecond?: number;
-    timeZoneId?: string;
-    dayOfWeek?: number;
-    calendarId?: string;
-    toInstant?: () => unknown;
-    toLocaleString?: (locale: string, options: Intl.DateTimeFormatOptions) => string;
-}
-interface FormatOptions {
-    /** BCP 47 locale tag, e.g. 'en-US', 'fr-FR', 'ar-EG'. Defaults to 'en-US'. */
-    locale?: string;
-}
-
-/**
- * Format a Temporal.PlainDate, PlainTime, PlainDateTime, or ZonedDateTime
- * using a date-fns-style token string.
- *
- * @example
- * format(Temporal.Now.plainDateISO(), 'yyyy-MM-dd') // "2026-08-04"
- * format(zdt, "MMM d, yyyy 'at' h:mm a") // "Aug 4, 2026 at 3:45 PM"
- * format(zdt, 'MMMM d, yyyy', { locale: 'fr-FR' }) // "août 4, 2026"
- *
- * Throws on a token the input type doesn't support (e.g. 'HH' on a PlainDate).
- */
-declare function format(temporal: TemporalLike, formatStr: string, options?: FormatOptions): string;
-
-/**
- * Parses `input` against `formatStr` and builds the real Temporal value it
- * describes: a `Temporal.PlainDate`, `PlainTime`, `PlainDateTime`, or
- * `ZonedDateTime` depending on which tokens are present.
- *
- * Returns `unknown` — this package has no ambient `Temporal` types to return
- * a real one against.
- *
- * `options.locale` picks the calendar the result is built in. Pass a locale
- * tag with a `-u-ca-` extension (e.g. `'en-u-ca-hebrew'`) to parse into a
- * non-Gregorian calendar.
- *
- * @throws if `input` doesn't match `formatStr`'s shape at all
- * @throws if it matches the shape but describes an impossible date (e.g. Feb
- * 30) or self-contradictory data (e.g. a weekday name that doesn't match the
- * actual date)
- *
- * @example
- * parse('yyyy-MM-dd HH:mm', '2026-08-04 15:45') // Temporal.PlainDateTime
- * parse('yyyy-MM', '2026-08-04T15:45:30') // throws — shape doesn't match
- * parse('yyyy-MM-dd', '2026-02-30') // throws — not a real date
- */
-declare function parse(formatStr: string, input: string, options?: FormatOptions): unknown | undefined;
-
-interface TemporalFactory {
-    from(fields: Record<string, number | string | undefined>, options?: {
-        overflow?: 'constrain' | 'reject';
-    }): unknown;
-}
-interface TemporalNamespace {
-    PlainDate: TemporalFactory;
-    PlainTime: TemporalFactory;
-    PlainDateTime: TemporalFactory;
-    ZonedDateTime: TemporalFactory;
-}
-/**
- * Explicitly hand temporal-fmt the Temporal implementation to use, instead
- * of relying on a global `Temporal`. Call this once, before your first
- * `format()`/`parse()`
- *
- * Call with no argument (or `undefined`) to clear the override and fall
- * back to `globalThis.Temporal` again.
- *
- * @example
- * import { Temporal } from 'temporal-polyfill';
- * import { setTemporal } from 'temporal-fmt';
- * setTemporal(Temporal);
- */
-declare function setTemporal(temporal?: TemporalNamespace): void;
-
-export { type FormatOptions, type TemporalLike, type TemporalNamespace, format, parse, setTemporal };
+export { format } from './format.js';
+export { parse } from './parse.js';
+export { setTemporal } from './temporalProvider.js';
+export type { TemporalLike, FormatOptions } from './tokens.js';
+export type { TemporalNamespace } from './temporalProvider.js';

package/dist/localeVocab.d.ts

@@ -0,0 +1,8 @@
+export interface LocaleVocab {
+    monthLong: string[];
+    monthShort: string[];
+    weekdayLong: string[];
+    weekdayShort: string[];
+    dayPeriod: string[];
+}
+export declare function getLocaleVocab(locale: string): LocaleVocab;

package/dist/parse.d.ts

@@ -0,0 +1,24 @@
+import { type FormatOptions } from './tokens.js';
+/**
+ * Parses `input` against `formatStr` and builds the real Temporal value it
+ * describes: a `Temporal.PlainDate`, `PlainTime`, `PlainDateTime`, or
+ * `ZonedDateTime` depending on which tokens are present.
+ *
+ * Returns `unknown` — this package has no ambient `Temporal` types to return
+ * a real one against.
+ *
+ * `options.locale` picks the calendar the result is built in. Pass a locale
+ * tag with a `-u-ca-` extension (e.g. `'en-u-ca-hebrew'`) to parse into a
+ * non-Gregorian calendar.
+ *
+ * @throws if `input` doesn't match `formatStr`'s shape at all
+ * @throws if it matches the shape but describes an impossible date (e.g. Feb
+ * 30) or self-contradictory data (e.g. a weekday name that doesn't match the
+ * actual date)
+ *
+ * @example
+ * parse('yyyy-MM-dd HH:mm', '2026-08-04 15:45') // Temporal.PlainDateTime
+ * parse('yyyy-MM', '2026-08-04T15:45:30') // throws — shape doesn't match
+ * parse('yyyy-MM-dd', '2026-02-30') // throws — not a real date
+ */
+export declare function parse(formatStr: string, input: string, options?: FormatOptions): unknown | undefined;

package/dist/parsePattern.d.ts

@@ -0,0 +1,19 @@
+import type { Piece } from './tokenize.js';
+export interface CapturingPattern {
+    regex: RegExp;
+    groups: Array<{
+        name: string;
+        token: string;
+    }>;
+    ambiguousRuns: Array<{
+        groupNames: string[];
+        tokens: string[];
+    }>;
+}
+/**
+ * Same walk as buildPatternSource() in pattern.ts, but each token piece
+ * gets its own named capture group (positionally named so the same token,
+ * e.g. "yyyy", could in theory appear twice) so a caller can pull the
+ * matched substring for each token back out after a successful match.
+ */
+export declare function buildCapturingPattern(pieces: Piece[], locale: string): CapturingPattern;

package/dist/pattern.d.ts

@@ -0,0 +1,27 @@
+export declare function tokenFragment(token: string, locale: string): string;
+export declare const UNPADDED_NUMERIC_TOKENS: Set<string>;
+export declare const UNPADDED_NUMERIC_RANGES: Record<string, Array<{
+    digits: 1 | 2;
+    min: number;
+    max: number;
+}>>;
+/**
+ * Given the literal digit string a run of N adjacent unpadded-numeric
+ * tokens matched as a whole (e.g. "112" for a 2-token run), enumerates
+ * every way to split it into N pieces (one per token, each piece 1-2
+ * digits per that token's own width rule) and returns every split where
+ * every piece is independently valid for its token. Length 0 means the
+ * run's regex match shouldn't have been possible in the first place
+ * (shouldn't happen — the caller only invokes this after the whole
+ * pattern already matched, meaning at least one split exists: the one the
+ * regex actually took). Length 1 means the reading is unambiguous.
+ * Length 2+ means true ambiguity — the caller should throw rather than
+ * pick one.
+ *
+ * Recursive over token count rather than hardcoded to 2, so a 3+ token
+ * unseparated run (e.g. "Hms") is covered by the same logic without a
+ * special case — those are rarer in practice but not impossible, and a
+ * partial fix that only covered pairs would leave the identical bug for
+ * anyone writing a 3-token glued run.
+ */
+export declare function enumerateValidSplits(digits: string, tokens: string[]): number[][];

package/dist/temporalProvider.d.ts

@@ -0,0 +1,27 @@
+interface TemporalFactory {
+    from(fields: Record<string, number | string | undefined>, options?: {
+        overflow?: 'constrain' | 'reject';
+    }): unknown;
+}
+export interface TemporalNamespace {
+    PlainDate: TemporalFactory;
+    PlainTime: TemporalFactory;
+    PlainDateTime: TemporalFactory;
+    ZonedDateTime: TemporalFactory;
+}
+/**
+ * Explicitly hand temporal-fmt the Temporal implementation to use, instead
+ * of relying on a global `Temporal`. Call this once, before your first
+ * `format()`/`parse()`
+ *
+ * Call with no argument (or `undefined`) to clear the override and fall
+ * back to `globalThis.Temporal` again.
+ *
+ * @example
+ * import { Temporal } from 'temporal-polyfill';
+ * import { setTemporal } from 'temporal-fmt';
+ * setTemporal(Temporal);
+ */
+export declare function setTemporal(temporal?: TemporalNamespace): void;
+export declare function getTemporal(): TemporalNamespace;
+export {};

package/dist/tokenize.d.ts

@@ -0,0 +1,14 @@
+export type Piece = {
+    kind: 'token';
+    value: string;
+} | {
+    kind: 'literal';
+    value: string;
+};
+/**
+ * Splits a format string like `"yyyy-MM-dd 'at' HH:mm"` into token/literal
+ * pieces. Text in single quotes is always literal (e.g. write 'rd' in
+ * "3rd" so it's not read as the day token). A doubled quote ('') means a
+ * literal quote character, both inside a quoted span and standalone.
+ */
+export declare function tokenize(format: string): Piece[];

package/dist/tokens.d.ts

@@ -0,0 +1,23 @@
+export declare function pad(n: number, len: number): string;
+export interface TemporalLike {
+    year?: number;
+    month?: number;
+    day?: number;
+    hour?: number;
+    minute?: number;
+    second?: number;
+    millisecond?: number;
+    timeZoneId?: string;
+    dayOfWeek?: number;
+    calendarId?: string;
+    toInstant?: () => unknown;
+    toLocaleString?: (locale: string, options: Intl.DateTimeFormatOptions) => string;
+}
+export interface FormatOptions {
+    /** BCP 47 locale tag, e.g. 'en-US', 'fr-FR', 'ar-EG'. Defaults to 'en-US'. */
+    locale?: string;
+}
+export declare const DEFAULT_LOCALE = "en-US";
+type TokenHandler = (t: TemporalLike, locale: string) => string;
+export declare const TOKENS: Array<[string, TokenHandler, keyof TemporalLike]>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "temporal-fmt",
-  "version": "0.7.8",
+  "version": "0.7.95",
   "description": "Format Temporal.PlainDate/PlainDateTime/PlainTime/ZonedDateTime objects using date-fns-style token strings.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -18,7 +18,7 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsc --declaration --emitDeclarationOnly",
     "dev": "tsup --watch",
     "test": "node --test test/*.test.js",
     "prepublishOnly": "npm run build && npm test"
@@ -44,9 +44,10 @@
   },
   "homepage": "https://github.com/DirazCoder/temporal-fmt#readme",
   "devDependencies": {
+    "@typescript/native-preview": "^7.0.0-dev.20260707.2",
     "temporal-polyfill": "^1.0.3",
     "tsup": "^8.5.1",
-    "typescript": "^6.0.3"
+    "typescript": "^7.0.2"
   },
   "overrides": {
     "esbuild": "0.28.1"
@@ -57,4 +58,4 @@
   "allowScripts": {
     "esbuild@0.28.1": true
   }
-}
+}

package/dist/index.d.cts

@@ -1,83 +0,0 @@
-interface TemporalLike {
-    year?: number;
-    month?: number;
-    day?: number;
-    hour?: number;
-    minute?: number;
-    second?: number;
-    millisecond?: number;
-    timeZoneId?: string;
-    dayOfWeek?: number;
-    calendarId?: string;
-    toInstant?: () => unknown;
-    toLocaleString?: (locale: string, options: Intl.DateTimeFormatOptions) => string;
-}
-interface FormatOptions {
-    /** BCP 47 locale tag, e.g. 'en-US', 'fr-FR', 'ar-EG'. Defaults to 'en-US'. */
-    locale?: string;
-}
-
-/**
- * Format a Temporal.PlainDate, PlainTime, PlainDateTime, or ZonedDateTime
- * using a date-fns-style token string.
- *
- * @example
- * format(Temporal.Now.plainDateISO(), 'yyyy-MM-dd') // "2026-08-04"
- * format(zdt, "MMM d, yyyy 'at' h:mm a") // "Aug 4, 2026 at 3:45 PM"
- * format(zdt, 'MMMM d, yyyy', { locale: 'fr-FR' }) // "août 4, 2026"
- *
- * Throws on a token the input type doesn't support (e.g. 'HH' on a PlainDate).
- */
-declare function format(temporal: TemporalLike, formatStr: string, options?: FormatOptions): string;
-
-/**
- * Parses `input` against `formatStr` and builds the real Temporal value it
- * describes: a `Temporal.PlainDate`, `PlainTime`, `PlainDateTime`, or
- * `ZonedDateTime` depending on which tokens are present.
- *
- * Returns `unknown` — this package has no ambient `Temporal` types to return
- * a real one against.
- *
- * `options.locale` picks the calendar the result is built in. Pass a locale
- * tag with a `-u-ca-` extension (e.g. `'en-u-ca-hebrew'`) to parse into a
- * non-Gregorian calendar.
- *
- * @throws if `input` doesn't match `formatStr`'s shape at all
- * @throws if it matches the shape but describes an impossible date (e.g. Feb
- * 30) or self-contradictory data (e.g. a weekday name that doesn't match the
- * actual date)
- *
- * @example
- * parse('yyyy-MM-dd HH:mm', '2026-08-04 15:45') // Temporal.PlainDateTime
- * parse('yyyy-MM', '2026-08-04T15:45:30') // throws — shape doesn't match
- * parse('yyyy-MM-dd', '2026-02-30') // throws — not a real date
- */
-declare function parse(formatStr: string, input: string, options?: FormatOptions): unknown | undefined;
-
-interface TemporalFactory {
-    from(fields: Record<string, number | string | undefined>, options?: {
-        overflow?: 'constrain' | 'reject';
-    }): unknown;
-}
-interface TemporalNamespace {
-    PlainDate: TemporalFactory;
-    PlainTime: TemporalFactory;
-    PlainDateTime: TemporalFactory;
-    ZonedDateTime: TemporalFactory;
-}
-/**
- * Explicitly hand temporal-fmt the Temporal implementation to use, instead
- * of relying on a global `Temporal`. Call this once, before your first
- * `format()`/`parse()`
- *
- * Call with no argument (or `undefined`) to clear the override and fall
- * back to `globalThis.Temporal` again.
- *
- * @example
- * import { Temporal } from 'temporal-polyfill';
- * import { setTemporal } from 'temporal-fmt';
- * setTemporal(Temporal);
- */
-declare function setTemporal(temporal?: TemporalNamespace): void;
-
-export { type FormatOptions, type TemporalLike, type TemporalNamespace, format, parse, setTemporal };