|
1 | 1 | # Temporal Polyfill
|
| 2 | + |
| 3 | +## Polyfill for [TC39 Proposal: Temporal](https://github.com/tc39/proposal-temporal) |
| 4 | + |
| 5 | +This polyfill was kicked off by some of the champions of the [Temporal proposal](https://github.com/tc39/proposal-temporal). |
| 6 | +The goal is to be ready for production use when the Temporal proposal reaches Stage 4, although like with all OSS work progress is dependent on contributors. |
| 7 | +We're eagerly welcoming to contributors who want to help build and maintain this polyfill. |
| 8 | +PRs are always welcome! |
| 9 | + |
| 10 | +Note that this polyfill is not affiliated with TC39. Links to other polyfills can be found [here](https://github.com/tc39/proposal-temporal/tree/main/#polyfill). |
| 11 | + |
| 12 | +This polyfill is compatible with Node.js 14 or later. |
| 13 | + |
| 14 | +## Roadmap |
| 15 | + |
| 16 | +* [x] Fork non-production polyfill from [tc39/proposal-temporal repo](https://github.com/tc39/proposal-temporal/tree/main/polyfill) |
| 17 | +* [x] Release initial pre-alpha to NPM at [@js-temporal/polyfill](https://www.npmjs.com/package/@js-temporal/polyfill) |
| 18 | +* [ ] Sync the code in this repo with the handful of polyfill changes that have recently been made in the [tc39/proposal-temporal](https://github.com/tc39/proposal-temporal) repo |
| 19 | +* [ ] Release alpha version to NPM |
| 20 | +* [ ] Deprecate all other earlier Temporal polyfills |
| 21 | +* [ ] Convert to TypeScript for better maintainability |
| 22 | +* [ ] (Maybe) Optimize performance of slow operations, notably non-ISO calendar calculations |
| 23 | +* [ ] Release production version to NPM |
| 24 | + |
| 25 | +## Bug Reports and Feedback |
| 26 | + |
| 27 | +If you think you've found a bug in the Temporal API itself (not the implementation in this polyfill), please file an issue in the [tc39/proposal-temporal issue tracker](https://github.com/tc39/proposal-temporal/issues) issue tracker. |
| 28 | + |
| 29 | +If you've found a bug in this polyfill—meaning that the implementation here doesn't match the [Temporal spec](https://tc39.es/proposal-temporal/)—please file an issue in this repo's [issue tracker](https://github.com/js-temporal/temporal-polyfill/issues). |
| 30 | + |
| 31 | +## Documentation |
| 32 | + |
| 33 | +Reference documentation and examples for the Temporal API can be found [here](https://tc39.es/proposal-temporal/docs/index.html). |
| 34 | + |
| 35 | +A cookbook to help you get started and learn the ins and outs of Temporal is available [here](https://tc39.es/proposal-temporal/docs/index.html) |
| 36 | + |
| 37 | +If you find a bug in the documentation, please file a bug over in the [tc39/proposal-temporal issue tracker](https://github.com/tc39/proposal-temporal/issues) issue tracker. |
| 38 | + |
| 39 | +Note that the Temporal documentation is in the process of being migrated to [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript). |
| 40 | +You can track the progress of the MDN migration [here](https://github.com/tc39/proposal-temporal/issues/1449). |
| 41 | + |
| 42 | +## Usage |
| 43 | + |
| 44 | +To install: |
| 45 | + |
| 46 | +```bash |
| 47 | +$ npm install @js-temporal/polyfill |
| 48 | +``` |
| 49 | + |
| 50 | +CJS Usage: |
| 51 | + |
| 52 | +```javascript |
| 53 | +const { Temporal, Intl, toTemporalInstant } = require('@js-temporal/polyfill'); |
| 54 | +Date.prototype.toTemporalInstant = toTemporalInstant; |
| 55 | +``` |
| 56 | + |
| 57 | +Import the polyfill as an ES6 module: |
| 58 | + |
| 59 | +```javascript |
| 60 | +import { Temporal, Intl, toTemporalInstant } from '@js-temporal/polyfill/lib/index.mjs'; |
| 61 | +Date.prototype.toTemporalInstant = toTemporalInstant; |
| 62 | +``` |
| 63 | + |
| 64 | +Note that this polyfill currently does not install a global `Temporal` object like a real implementation will. |
| 65 | +This behavior avoids hiding the global Temporal object in environments where a real Temporal implementation is present. |
| 66 | +See [this issue](https://github.com/tc39/proposal-temporal/issues/778) for more background on this decision. |
| 67 | +Once JS engines start shipping with Temporal, we may decide to change this behavior to match built-in behavior more closely. |
| 68 | +See [#2](https://github.com/js-temporal/temporal-polyfill/issues/2) to provide feedback or track this issue. |
| 69 | + |
| 70 | +## Contributing / Help Wanted |
| 71 | + |
| 72 | +We're eagerly welcoming to contributors who want to help build and maintain this polyfill. |
| 73 | +PRs are always welcome! |
0 commit comments