temporal-fmt 0.8.1 → 0.8.2

package/dist/constants.d.cts

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

package/dist/format.d.cts

@@ -0,0 +1,13 @@
+import { type TemporalLike, type FormatOptions } from './tokens.cjs';
+/**
+ * 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.cts

@@ -0,0 +1,5 @@
+export { format } from './format.cjs';
+export { parse } from './parse.cjs';
+export { setTemporal } from './temporalProvider.cjs';
+export type { TemporalLike, FormatOptions } from './tokens.cjs';
+export type { TemporalNamespace } from './temporalProvider.cjs';

package/dist/localeVocab.d.cts

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

package/dist/parse.d.cts

@@ -0,0 +1,24 @@
+import { type FormatOptions } from './tokens.cjs';
+/**
+ * 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.cts

@@ -0,0 +1,19 @@
+import type { Piece } from './tokenize.cjs';
+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.cts

@@ -0,0 +1,28 @@
+export declare function isValidTimeZone(raw: string): boolean;
+export declare function tokenFragment(token: string, locale: string, nextToken?: 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.cts

@@ -0,0 +1,28 @@
+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;
+}
+export declare function subscribeToTemporalChanges(listener: () => void): void;
+/**
+ * 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.cts

@@ -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.cts

@@ -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.8.1",
+  "version": "0.8.2",
   "description": "Format Temporal.PlainDate/PlainDateTime/PlainTime/ZonedDateTime objects using date-fns-style token strings.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -8,9 +8,14 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     }
   },
   "files": [
@@ -18,13 +23,14 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "build": "tsup && tsc --declaration --emitDeclarationOnly",
+    "build": "tsup && tsc --declaration --emitDeclarationOnly && node scripts/emit-cjs-types.mjs",
     "dev": "tsup --watch",
-    "test": "node --test test/*.test.js",
+    "test": "node --test test/*.test.js test/*.test.cjs",
     "test:unit": "vitest run",
     "test:unit:watch": "vitest",
     "test:types": "vitest run --typecheck",
-    "test:all": "npm run build && npm test && npm run test:unit && npm run test:types",
+    "test:pack": "attw --pack .",
+    "test:all": "npm run build && npm test && npm run test:unit && npm run test:types && npm run test:pack",
     "prepublishOnly": "npm run build && npm test"
   },
   "keywords": [
@@ -48,6 +54,7 @@
   },
   "homepage": "https://github.com/DirazCoder/temporal-fmt#readme",
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
     "temporal-polyfill": "^1.0.4",
     "tsup": "^8.5.1",
     "typescript": "^7.0.2",