Skip to content

Commit 5c50221

Browse files
authored
Draft of README content of new polyfill repo (#1)
* Draft of README content of new repo * Updates from @ptomato review feedback
1 parent fb6a5a6 commit 5c50221

File tree

1 file changed

+72
-0
lines changed

1 file changed

+72
-0
lines changed

README.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,73 @@
11
# 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

Comments
 (0)