@formatjs/temporal 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE.md ADDED
@@ -0,0 +1,63 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2023 FormatJS
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
6
+
7
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8
+
9
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
10
+
11
+ ICU4X 2.3.0 lunisolar approximation
12
+ Source: https://github.com/unicode-org/icu4x/blob/a14f2dad852be26bad277ae704abf27a15cbfed1/components/calendar/src/cal/east_asian_traditional/simple.rs
13
+
14
+ CLDR 49 Before Hijrah era labels
15
+ Copyright © 2001–2026 Unicode, Inc.
16
+ Source: https://github.com/unicode-org/cldr-json/tree/49.0.0/cldr-json/cldr-cal-islamic-full
17
+
18
+ UNICODE LICENSE V3
19
+
20
+ COPYRIGHT AND PERMISSION NOTICE
21
+
22
+ Copyright © 2020-2024 Unicode, Inc.
23
+
24
+ NOTICE TO USER: Carefully read the following legal agreement. BY
25
+ DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
26
+ SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE
27
+ TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT
28
+ DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
29
+
30
+ Permission is hereby granted, free of charge, to any person obtaining a
31
+ copy of data files and any associated documentation (the "Data Files") or
32
+ software and any associated documentation (the "Software") to deal in the
33
+ Data Files or Software without restriction, including without limitation
34
+ the rights to use, copy, modify, merge, publish, distribute, and/or sell
35
+ copies of the Data Files or Software, and to permit persons to whom the
36
+ Data Files or Software are furnished to do so, provided that either (a)
37
+ this copyright and permission notice appear with all copies of the Data
38
+ Files or Software, or (b) this copyright and permission notice appear in
39
+ associated Documentation.
40
+
41
+ THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
42
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
43
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
44
+ THIRD PARTY RIGHTS.
45
+
46
+ IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE
47
+ BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES,
48
+ OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
49
+ WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
50
+ ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA
51
+ FILES OR SOFTWARE.
52
+
53
+ Except as contained in this notice, the name of a copyright holder shall
54
+ not be used in advertising or otherwise to promote the sale, use or other
55
+ dealings in these Data Files or Software without prior written
56
+ authorization of the copyright holder.
57
+
58
+ SPDX-License-Identifier: Unicode-3.0
59
+
60
+ —
61
+
62
+ Portions of ICU4X may have been adapted from ICU4C and/or ICU4J.
63
+ ICU 1.8.1 to ICU 57.1 © 1995-2016 International Business Machines Corporation and others.
package/README.md CHANGED
@@ -1,3 +1,232 @@
1
- # Temporary Holding Version
1
+ # @formatjs/temporal
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Temporal implementation in TypeScript with a Rust core. Importing the namespace changes no globals; runtime
4
+ arithmetic never delegates to native Temporal or another Temporal polyfill.
5
+
6
+ ```ts
7
+ import {Temporal} from '@formatjs/temporal'
8
+
9
+ const value = Temporal.ZonedDateTime.from(
10
+ '2020-03-07T12:00-05:00[America/New_York]'
11
+ )
12
+ value.add({days: 1}).toString()
13
+ // 2020-03-08T12:00:00-04:00[America/New_York]
14
+ value.add({hours: 24}).toString()
15
+ // 2020-03-08T13:00:00-04:00[America/New_York]
16
+ ```
17
+
18
+ Exports `Temporal`, its eight constructors, `Now` and `toTemporalInstant`.
19
+ Calendar arithmetic supports 16 calendar IDs. Chinese/Dangi use compact ICU4X
20
+ historical data and an arithmetic approximation outside 1900–2102. Umm al-Qura
21
+ uses captured host Intl data for AH 1300–1600, then the civil fallback. Named
22
+ timezones use captured installed `Intl.DateTimeFormat`, including its timezone
23
+ data version. UTC and numeric offsets work without Intl. Timezone aliases retain
24
+ their spelling separately from primary identity. Update host or installed
25
+ polyfill data when timezone laws change.
26
+
27
+ ## Installation
28
+
29
+ ```ts
30
+ import '@formatjs/temporal/polyfill.js'
31
+ ```
32
+
33
+ This preserves an existing Temporal implementation and supplies
34
+ `Date.prototype.toTemporalInstant`. Use `polyfill-force.js` to install this
35
+ namespace unconditionally. Install needed Intl polyfills and their locale,
36
+ calendar and timezone data before Temporal.
37
+
38
+ Installation registers owned brands with FormatJS DateTimeFormat and native
39
+ Hermes Intl bridges. When only legacy DateTimeFormat exists, its constructor and
40
+ four formatting methods are adapted. Native prototype identity, subclassing,
41
+ legacy constructor chaining, captured option values and ordinary Date/Number
42
+ formatting remain supported. Importing the namespace alone does not install this
43
+ adapter.
44
+ Construct formatters after installation; pre-existing instances retain native behavior.
45
+
46
+ For calendar and named-timezone operations without host Intl data, use the
47
+ full-table namespace:
48
+
49
+ ```ts
50
+ import {Temporal} from '@formatjs/temporal/standalone.js'
51
+ ```
52
+
53
+ `standalone.js` includes compact owned IANA timezone histories with exact finite
54
+ transitions and recurring future rules, without a 2100 cutoff. Default ships
55
+ identifiers and transition-search intervals, not offset histories. Entries expose separate namespaces;
56
+ installation entries install the default namespace. Chinese/Dangi arithmetic is
57
+ adapted from ICU4X under Unicode-3.0; see LICENSE.md.
58
+
59
+ Default accepts native Intl or installed FormatJS polyfills; no formatter package
60
+ is imported, so no circular runtime dependency. Install Intl before importing
61
+ Temporal, which captures its intrinsics. ICU oracles verify offsets, gap/fold
62
+ resolution and transitions on Hermes. Node also compares host-data results with
63
+ `temporal-polyfill`. Intl exposes no transition enumeration: default searches
64
+ offset changes from 1800 through three years beyond the later of now and input.
65
+ Previous-transition searches probe nearby future years before historical data.
66
+ Generated intervals account for closely spaced IANA transitions and recurring
67
+ rules, capped at seven days because host tzdata may differ. Two host transitions
68
+ within one probe interval can still be missed; Intl provides no exhaustive search.
69
+ Use standalone when owned timezone history/rules must determine results.
70
+
71
+ ## Locale formatting
72
+
73
+ All eight classes expose `toLocaleString(locales?, options?)`. Date/time classes
74
+ use captured DateTimeFormat operations; Duration uses DurationFormat. Without the
75
+ corresponding Intl formatter, locale methods return their ISO representation.
76
+
77
+ The owned DateTimeFormat path accepts exact nanoseconds, including plain dates
78
+ outside Date's TimeClip range. Load the needed FormatJS Intl polyfills and data
79
+ before installing Temporal. An isolated namespace can register explicitly with
80
+ `DateTimeFormat.__addTemporalNamespace(Temporal)`.
81
+
82
+ Legacy DateTimeFormat projects each Temporal kind onto the permitted fields.
83
+ Plain values ignore the formatter's timezone; YearMonth/MonthDay styles omit
84
+ reference fields. Ranges require matching Temporal types. Native style components
85
+ are inferred through captured `formatToParts` operations before host matching.
86
+ Chinese/Dangi date fields use the same calendar arithmetic as Temporal, including
87
+ numeric Date inputs when host ICU data differs. Captured host formatters supply
88
+ localized labels. Corrected ranges use full endpoint patterns when native field
89
+ collapse no longer applies.
90
+ All supported non-Gregorian plain values also format beyond Date TimeClip.
91
+ Safe Gregorian-cycle surrogates preserve weekday/clock; Temporal restores calendar
92
+ fields and eras. Host Intl supplies month and era labels, with compact CLDR
93
+ Before Hijrah labels for older hosts. Japanese era names and first-year forms
94
+ remain localized. Numeric Date inputs retain TimeClip.
95
+ Numeric Date and Instant formatting, plus ZonedDateTime locale methods, restore
96
+ non-Gregorian calendar fields and eras using the target timezone's local ISO date.
97
+ Captured host formatters retain weekday, clock and timezone labels. Gregorian era
98
+ probes handle BCE dates even when the host falls back to a non-English locale.
99
+ Chinese/Dangi numeric inputs also recover when host ICU fails at valid Date
100
+ bounds. Safe-year labels retain the original local date, clock and timezone;
101
+ ranges restore both endpoints. Boundary checks verify field consistency, not
102
+ independent astronomical accuracy outside the documented oracle ranges.
103
+
104
+ Rust exposes typed values and 62 normalized operations through ABI 9. JS retains
105
+ ECMAScript coercion, brands, slots and object allocation. Backend metadata keeps
106
+ `completeTemporalBackend: false` because this ABI is not an ECMAScript object
107
+ runtime. The [completion audit](../../knowledge-base/015a-temporal-completion-audit.md)
108
+ records Rust routes, independent controls and exact conformance scope.
109
+
110
+ Full Intl compatibility gates cover 4,078 executions with Node host Intl and
111
+ 4,076 with native SDK Intl. Pinned IANA alias and CLDR zero-offset assumptions
112
+ account for the documented exclusions; manifests retain reasons and sources.
113
+ Manual unfiltered diagnostics keep all 4,080 executions.
114
+
115
+ Legacy host formatting supports extended plain Gregorian dates, times and
116
+ year-months through both single-value and range APIs. It uses captured
117
+ NumberFormat for localized year digits. Ordinary Date/Number inputs retain
118
+ their clipping rules.
119
+
120
+ DurationFormat supports late Temporal installation, branded durations and ISO
121
+ duration strings. Installation registers captured getters and parsers with
122
+ FormatJS/native Hermes formatters and adapts legacy host formatters. Isolated
123
+ namespaces can use `DurationFormat.__addTemporalNamespace(Temporal)` explicitly.
124
+
125
+ ## WASM with native data
126
+
127
+ ```ts
128
+ import {
129
+ configureTemporalWasm,
130
+ installTemporalWasm,
131
+ } from '@formatjs/temporal/wasm-native.js'
132
+
133
+ const {instance} = await WebAssembly.instantiateStreaming(
134
+ fetch('/temporal-backend.wasm')
135
+ )
136
+ const Temporal = configureTemporalWasm(instance)
137
+ // Optional global installation:
138
+ installTemporalWasm(instance, true)
139
+ ```
140
+
141
+ This entry owns its namespace/backend state and omits duplicate TS calendar and
142
+ IANA tables. Invalid modules reject before installation. Native errors propagate
143
+ without a TS data retry. Keep this namespace separate from the default TS entry.
144
+ The existing `index.js` plus `wasm.js` pair shares brands and retains TS data;
145
+ `configureWasmBackend(instance)` switches that pair to Rust operations.
146
+
147
+ WASM is optional. TS remains the default. See [benchmarks](../../benchmarks/temporal/README.md)
148
+ for versioned performance, consumer payload and package graph measurements.
149
+ Runtime payload and whole npm archive size are different scopes.
150
+
151
+ ## Hermes
152
+
153
+ Import and installation accept absent or partial Intl namespaces, including
154
+ an Intl object without DateTimeFormat. ISO math and Date conversion remain usable.
155
+ Locale formatting still needs the corresponding formatter.
156
+
157
+ The TS implementation runs on Hermes source and optimized bytecode. Pinned Hermes
158
+ has no WebAssembly runtime. Use the [native SDK](../../native/hermes/package/README.md)
159
+ for Rust-backed Temporal and Intl, or the TS path with needed Intl polyfills.
160
+ The [standalone C++ example](../../examples/hermes-intl/README.md) consumes the SDK
161
+ without a Rust toolchain.
162
+
163
+ `Now` captures host clock/zone operations. Native Hermes supplies a system clock
164
+ and IANA zone through the SDK. Bare TS without Intl uses Date's current system
165
+ offset; it does not infer an IANA location from that offset.
166
+
167
+ The [Rust crate](../../crates/temporal/README.md) supplies eight value types,
168
+ `Now`, calendar providers, caller-owned IANA registries and optional compiled data.
169
+ Typed Rust partial updates cover all seven types with `with()` methods;
170
+ calendar updates preserve month codes and era relationships. Zoned updates prefer
171
+ the source offset by default and support explicit gap/fold and offset policies.
172
+ Rust `PlainDate::to_zoned_date_time(zone, None)` selects the first instant of the
173
+ civil day; supplying `Some(time)` uses compatible resolution.
174
+ JS adapters delegate normalized operations through ABI 9. Rust builds, generated
175
+ data and release artifacts use Bazel.
176
+
177
+ ## Validation
178
+
179
+ ```sh
180
+ bazel test -c opt //packages/temporal:package_test
181
+ bazel test -c opt //packages/temporal:wasm_package_test //packages/temporal:wasm_native_package_test
182
+ bazel test -c opt //packages/temporal:compact_calendar_datetimeformat_test262
183
+ bazel test -c opt //crates/temporal:temporal_test //crates/temporal:ffi_test
184
+ ```
185
+
186
+ Full class gates cover 9,090 executions per SDK source/HBC and WASM profile.
187
+ Calendar, Now, installation and Intl selections run separately. The
188
+ `intl402/Temporal` corpus has 4,080 executions; it does not include the separate
189
+ 65 DateTimeFormat files with the Temporal feature.
190
+
191
+ Count-checked formatter gates require all 130 executions and zero failures on
192
+ owned TS/Node, WASM, Hermes TS source/HBC and native SDK source/HBC. Their locale
193
+ prelude includes Arabic data for non-Latin numeral bounds. Native-host and adapted
194
+ non-Temporal DateTimeFormat diagnostics compare all 362 executions.
195
+
196
+ Independent ICU oracles verify calendar fields and arithmetic, timezone identity,
197
+ offsets, transitions, parsing, rounding and locale output. Authority datasets also
198
+ check table calendars. Unfiltered diagnostics retain implementation and pinned
199
+ IANA/CLDR differences. See the [implementation record](../../knowledge-base/015-temporal.md)
200
+ for commands, corpus counts, data policies and remaining work.
201
+
202
+ Compact-calendar validation includes every year and month in the existing full
203
+ ICU4X packs: 1,204,680 years and 14,899,816 months. This verifies the arithmetic
204
+ port across internal rounding bounds; it is not an independent calendar oracle.
205
+ Separate ICU/HKO/KASI fixtures cover 30,620 rows, including Hermes source/bytecode.
206
+ The pinned full Temporal-feature corpus passes with only the documented
207
+ IANA/CLDR data exclusions; coverage details follow below.
208
+
209
+ Matched bundled namespace consumers measure 38,639 bytes gzip for default TS,
210
+ 339,338 for standalone and 23,083 for forced full `temporal-polyfill`.
211
+ Default dropped 44.5% from 69,657 by using installed Intl timezone data.
212
+ Native-data WASM glue plus binary measures 479,583 bytes; hybrid 484,339.
213
+ Nine-process Node startup medians: TS 20.84 ms; full reference 22.58 ms.
214
+ Previous owned-data TS snapshot was 12.11 ms: smaller payload costs more startup
215
+ in this sample. See `benchmarks/temporal/host-intl-default-startup-results.json`
216
+ for methods, raw samples and memory. Earlier hot-operation measurements describe
217
+ previous data policies; they are not refreshed throughput claims.
218
+
219
+ Final coverage includes every Temporal-feature file in pinned Test262, including
220
+ DateTimeFormat, DurationFormat and staging. Six coherent profiles cover default
221
+ TS and native-data WASM on Node, plus TS/native SDK on Hermes source/HBC.
222
+ Each Node profile passes 13,474 unique scenarios; each Hermes profile passes
223
+ 13,472. Only documented IANA/CLDR data-version cases are excluded. The coherent
224
+ matrix has 98,716 overlapping suite executions; report unions verify exact
225
+ coverage separately. No Realm exclusion applies to this pin; unsupported Hermes
226
+ Realm hooks and oracle authority limits remain documented.
227
+ For standalone and Rust namespaces, legacy host formatting compares host and
228
+ owned offsets. Stale or missing host rules use owned local fields with a localized
229
+ numeric offset label. Default TS follows installed Intl timezone data. Matching
230
+ host output stays native.
231
+ Reversed Date and Temporal formatter ranges remain valid; endpoint source fields
232
+ retain their input order.