Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/js-temporal/temporal-polyfill
Polyfill for Temporal (under construction)
https://github.com/js-temporal/temporal-polyfill
Last synced: 14 days ago
JSON representation
Polyfill for Temporal (under construction)
- Host: GitHub
- URL: https://github.com/js-temporal/temporal-polyfill
- Owner: js-temporal
- License: isc
- Created: 2021-05-06T20:56:01.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-05-08T08:30:20.000Z (6 months ago)
- Last Synced: 2024-05-17T11:02:10.255Z (6 months ago)
- Language: TypeScript
- Homepage:
- Size: 3.69 MB
- Stars: 489
- Watchers: 16
- Forks: 27
- Open Issues: 44
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Temporal Polyfill
## Polyfill for [TC39 Proposal: Temporal](https://github.com/tc39/proposal-temporal)
This polyfill was kicked off by some of the champions of the [Temporal proposal](https://github.com/tc39/proposal-temporal).
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.
We're eagerly welcoming to contributors who want to help build and maintain this polyfill.
PRs are always welcome!
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/#polyfills).
This polyfill is compatible with Node.js 14 or later.
## Roadmap
- [x] Fork non-production polyfill from [tc39/proposal-temporal repo](https://github.com/tc39/proposal-temporal/tree/main/polyfill)
- [x] Release initial pre-alpha to NPM at [@js-temporal/polyfill](https://www.npmjs.com/package/@js-temporal/polyfill)
- [x] 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
- [x] Release alpha version to NPM
- [x] Deprecate all other earlier Temporal polyfills
- [x] Optimize slow operations by reducing calls to Intl.DateTimeFormat constructor (see [#7](https://github.com/js-temporal/temporal-polyfill/issues/7), [#8](https://github.com/js-temporal/temporal-polyfill/pull/8), [#10](https://github.com/js-temporal/temporal-polyfill/pull/10), [#12](https://github.com/js-temporal/temporal-polyfill/pull/12))
- [x] Convert to TypeScript for better maintainability
- [x] Improve typing of sources for better maintainability
- [x] Migrate to JSBI for improved compile-time safety around BigInt operations.
- [ ] Optimize performance of other slow operations
- [ ] Release production version to NPM
## Bug Reports and Feedback
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.
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).
## Documentation
Reference documentation and examples for the Temporal API can be found [here](https://tc39.es/proposal-temporal/docs/index.html).
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)
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.
Note that the Temporal documentation is in the process of being migrated to [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript).
You can track the progress of the MDN migration [here](https://github.com/tc39/proposal-temporal/issues/1449).
## Usage
To install:
```bash
$ npm install @js-temporal/polyfill
```
CJS Usage:
```javascript
const { Temporal, Intl, toTemporalInstant } = require('@js-temporal/polyfill');
Date.prototype.toTemporalInstant = toTemporalInstant;
```
Import the polyfill as an ES6 module:
```javascript
import { Temporal, Intl, toTemporalInstant } from '@js-temporal/polyfill';
Date.prototype.toTemporalInstant = toTemporalInstant;
```
Note that this polyfill currently does not install a global `Temporal` object like a real implementation will.
This behavior avoids hiding the global Temporal object in environments where a real Temporal implementation is present.
See [this issue](https://github.com/tc39/proposal-temporal/issues/778) for more background on this decision.
Once JS engines start shipping with Temporal, we may decide to change this behavior to match built-in behavior more closely.
See [#2](https://github.com/js-temporal/temporal-polyfill/issues/2) to provide feedback or track this issue.
This polyfill ships ES2020 code for both CJS and ESM bundles - if your
environment does not support ES2020, then please make sure to transpile the
content of this package along with the rest of your code.
This polyfill uses [JSBI](https://github.com/GoogleChromeLabs/jsbi) to enable backwards-compatibility for environments that don't support native bigints. If your project only ever runs in environments that do support native bigints (see [caniuse data](https://caniuse.com/bigint)), we highly recommend configuring the [JSBI Babel plugin](https://github.com/GoogleChromeLabs/babel-plugin-transform-jsbi-to-bigint) that translates JSBI calls to their native bigint equivalent, improving code-size and performance. We are exploring ways to provide separate builds for these use-cases in [#155](https://github.com/js-temporal/temporal-polyfill/issues/155).
## Contributing / Help Wanted
We're eagerly welcoming to contributors who want to help build and maintain this polyfill.
PRs are always welcome!