@formatjs/temporal 0.0.0-stage → 1.1.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 +63 -0
- package/README.md +231 -2
- package/WASM_NOTICES.html +6885 -0
- package/index.d.ts +258 -0
- package/index.js +7905 -0
- package/index.js.map +1 -0
- package/native.d.ts +137 -0
- package/native.js +422 -0
- package/native.js.map +1 -0
- package/package.json +27 -3
- package/polyfill-force.d.ts +1 -0
- package/polyfill-force.js +4213 -0
- package/polyfill-force.js.map +1 -0
- package/polyfill.d.ts +1 -0
- package/polyfill.js +4213 -0
- package/polyfill.js.map +1 -0
- package/should-polyfill.d.ts +1 -0
- package/should-polyfill.js +35 -0
- package/should-polyfill.js.map +1 -0
- package/standalone.d.ts +258 -0
- package/standalone.js +71440 -0
- package/standalone.js.map +1 -0
- package/temporal-backend.wasm +0 -0
- package/wasm-native.d.ts +249 -0
- package/wasm-native.js +7961 -0
- package/wasm-native.js.map +1 -0
- package/wasm.d.ts +7 -0
- package/wasm.js +61 -0
- package/wasm.js.map +1 -0
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
|
-
#
|
|
1
|
+
# @formatjs/temporal
|
|
2
2
|
|
|
3
|
-
|
|
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.
|