temporal-polyfill - npm Package Compare versions

Comparing version 0.1.1 to 0.2.0

global.d.ts

@@ -1,1 +0,1 @@
-export * from './dist/global'
+export * from 'temporal-spec/global'

impl.d.ts

@@ -1,1 +0,1 @@
-export * from './dist/impl'
+export * from 'temporal-spec'

package.json

 {
   "name": "temporal-polyfill",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "title": "Temporal Polyfill",
-  "description": "A spec-compliant Temporal JavaScript polyfill in 16kb",
+  "description": "A lightweight polyfill for Temporal, successor to the JavaScript Date object",
   "author": {
@@ -21,51 +21,31 @@ "name": "Adam Shaw",
     "type": "git",
-    "url": "https://github.com/fullcalendar/temporal.git",
+    "url": "https://github.com/fullcalendar/temporal-polyfill.git",
     "directory": "packages/temporal-polyfill"
   },
   "type": "module",
-  "types": "./dist/index.d.ts",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.mjs",
+  "dependencies": {
+    "temporal-spec": "^0.2.0"
+  },
+  "types": "./index.d.ts",
+  "main": "./index.cjs",
+  "module": "./index.esm.js",
+  "jsdelivr": "./global.min.js",
+  "unpkg": "./global.min.js",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "require": "./dist/index.cjs",
-      "import": "./dist/index.mjs"
+      "types": "./index.d.ts",
+      "require": "./index.cjs",
+      "import": "./index.esm.js"
     },
     "./impl": {
-      "types": "./dist/impl.d.ts",
-      "require": "./dist/impl.cjs",
-      "import": "./dist/impl.mjs"
+      "types": "./impl.d.ts",
+      "require": "./impl.cjs",
+      "import": "./impl.esm.js"
     },
-    "./shim": {
-      "types": "./dist/shim.d.ts",
-      "require": "./dist/shim.cjs",
-      "import": "./dist/shim.mjs"
-    },
     "./global": {
-      "types": "./dist/global.d.ts",
-      "require": "./dist/global.cjs",
-      "import": "./dist/global.mjs"
+      "types": "./global.d.ts",
+      "require": "./global.cjs",
+      "import": "./global.esm.js"
     }
-  },
-  "sideEffects": [
-    "./dist/global.*"
-  ],
-  "files": [
-    "/src",
-    "/dist",
-    "/*.d.ts"
-  ],
-  "dependencies": {
-    "temporal-spec": "~0.1.0"
-  },
-  "devDependencies": {
-    "@types/chai": "^4.2.22",
-    "@types/jest": "^26.0.24",
-    "@types/node": "^16.9.1",
-    "chai": "^4.3.4",
-    "jest": "^27.0.6",
-    "jest-date-mock": "^1.0.8",
-    "typescript": "^4.3.5"
   }
 }

README.md

 
 # temporal-polyfill
 
-A spec-compliant [Temporal] JavaScript polyfill in 16kb.
+A lightweight polyfill for [Temporal](https://tc39.es/proposal-temporal/docs/), successor to the JavaScript `Date` object.
 
-[Codepen](https://codepen.io/arshaw/pen/VwrMQPJ?editors=1111)
+Only 20.0 kB, with near-perfect [spec compliance](#spec-compliance).
 
-[CDN link](https://cdn.jsdelivr.net/npm/temporal-polyfill@0.0.8/dist/global.js)
-<!-- NOTE: when updating this link, update the codepen too -->
 
+## Table of Contents
 
-## Browser Support
+- [Installation](#installation)
+- [Comparison with `@js-temporal/polyfill`](#comparison-with-js-temporalpolyfill)
+- [Spec Compliance](#spec-compliance)
+- [Browser Support](#browser-support)
+- [BigInt Considerations](#bigint-considerations)
+- [Tree-shakeable API](#tree-shakeable-api) (coming soon)
 
-| Minimum required version if... | Chrome | Edge | Safari | Safari iOS | Firefox | Node |
-| --- | --- | --- | --- | --- | --- | --- |
-| ...transpiling to target environment | 36 (Jul 2014) | 14 (Aug 2016) | 10 (Sep 2016) | 10 (Sep 2016) | 52 (Mar 2017) | 12 (Apr 2019) |
-| ...leaving untranspiled | 60 (Jul 2017) | 79 (Jan 2020) | 11.1 (Mar 2018) | 11.3 (Mar 2018) | 55 (Aug 2017) | 12 (Apr 2019) |
-| ...using BigInt features | 67 (May 2018) | 79 (Jan 2020) | 14 (Sep 2020) | 14 (Sep 2020) | 68 (July 2019) | 12 (Apr 2019) |
 
-
-## BigInt Considerations
-
-This polyfill works fine in environments without [BigInt]. However, without BigInt, the following will throw errors:
-
-| ❌ Avoid microseconds/nanoseconds | ✅ Use milliseconds instead |
-| -------------------------------- | --------------------------- |
-| `instant.epochMicroseconds` | `instant.epochMilliseconds` |
-| `instant.epochNanoseconds` | `instant.epochMilliseconds` |
-| `Temporal.Instant.fromEpochMicroseconds(micro)` | `Temporal.Instant.fromEpochMilliseconds(milli)` |
-| `Temporal.Instant.fromEpochNanoseconds(nano)` | `Temporal.Instant.fromEpochMilliseconds(milli)` |
-| `new Temporal.Instant(nano)` | `Temporal.Instant.fromEpochMilliseconds(milli)` |
-| `zonedDateTime.epochMicroseconds` | `zonedDateTime.epochMilliseconds` |
-| `zonedDateTime.epochNanoseconds` | `zonedDateTime.epochMilliseconds` |
-| `new Temporal.ZonedDateTime(nano, tz, cal)` | `Temporal.Instant.fromEpochMilliseconds(milli).toZonedDateTimeISO()` |
-|                                             | `Temporal.Instant.fromEpochMilliseconds(milli).toZonedDateTime(cal)` |
-
-FYI, it is not possible to properly polyfill BigInt. [More Information][JSBI-why]
-
-
 ## Installation
@@ -46,6 +25,6 @@
 
-**A) Import globally:**
+Import as an ES module without side effects:
 
 ```js
-import 'temporal-polyfill/global'
+import { Temporal } from 'temporal-polyfill'
 
@@ -55,6 +34,6 @@ console.log(Temporal.Now.zonedDateTimeISO().toString())
 
-**B) Import as an ES module** without side effects:
+Or, import globally:
 
 ```js
-import { Temporal } from 'temporal-polyfill'
+import 'temporal-polyfill/global'
 
@@ -64,14 +43,235 @@ console.log(Temporal.Now.zonedDateTimeISO().toString())
 
-**C)** The above techniques try using the built-in `Temporal` object and fall back to the polyfill.
-To guarantee using the polyfill, do this:
+Use a `<script>` tags with a CDN link:
 
+```html
+<script src='https://cdn.jsdelivr.net/npm/temporal-polyfill@0.2.0/global.min.js'></script>
+<script>
+  console.log(Temporal.Now.zonedDateTimeISO().toString())
+</script>
+```
+
+
+## Comparison with `@js-temporal/polyfill`
+
+<table>
+  <tr>
+    <td>Package</td>
+    <td>
+      <code>temporal-polyfill</code>
+    </td>
+    <td>
+      <code>@js-temporal/polyfill</code>
+    </td>
+  </tr>
+  <tr>
+    <td>Repo</td>
+    <td>
+      <a href='https://github.com/fullcalendar/temporal-polyfill'>
+        fullcalendar/temporal-polyfill
+      </a>
+    </td>
+    <td>
+      <a href='https://github.com/js-temporal/temporal-polyfill'>
+        js-temporal/temporal-polyfill
+      </a>
+    </td>
+  </tr>
+  <tr>
+    <td>Creators</td>
+    <td><a href='https://fullcalendar.io/'>FullCalendar</a> lead dev <a href='https://github.com/arshaw'>arshaw</a></td>
+    <td>Champions of the <a href='https://github.com/tc39/proposal-temporal'>Temporal proposal</a></td>
+  </tr>
+  <tr>
+    <td>Minified+gzip size &#10013;</td>
+    <td>20.0 kB</td>
+    <td>43.2 kB (+116%)</td>
+  </tr>
+  <tr>
+    <td>Minified-only size &#10013;</td>
+    <td>58.7 kB</td>
+    <td>206.0 kB (+251%)</td>
+  </tr>
+  <tr>
+    <td>Spec compliance</td>
+    <td>
+      Strict compliance for common API.<br />
+      Relaxed compliance for subclassing<br />built-in types.
+    </td>
+    <td>
+      Strict compliance for entire API.
+    </td>
+  </tr>
+  <tr>
+    <td>Spec date</td>
+    <td>
+      Nov 2023 (latest)
+    </td>
+    <td>
+      May 2023
+    </td>
+  </tr>
+  <tr>
+    <td>BigInt Approach</td>
+    <td>Internally avoids BigInt operations altogether</td>
+    <td>Internally relies on <a href='https://github.com/GoogleChromeLabs/jsbi'>JSBI</a></td>
+  </tr>
+  <tr>
+    <td>Global usage in ESM</td>
+    <td>
+      <code>import 'temporal-polyfill/global'</code>
+    </td>
+    <td>Not currently possible</td>
+  </tr>
+</table>
+
+&#10013; Compares [global.min.js](https://cdn.jsdelivr.net/npm/temporal-polyfill@0.2.0/global.min.js) with [index.esm.js](https://cdn.jsdelivr.net/npm/@js-temporal/polyfill@0.4.4/dist/index.esm.js), which are similarly transpiled.
+
+
+## Spec Compliance
+
+All calendar systems (ex: `chinese`, `persian`) and time zones are supported.
+
+Compliance with the latest version of the Temporal spec (Nov 2023) is near-perfect with the following intentional deviations:
+
+- `Duration::toString` does not display units greater than `Number.MAX_SAFE_INTEGER` according to spec. Precision is chosen differently.
+- *Custom implementations* of Calendars and TimeZones are queried differently. Only affects those subclassing built-in classes, which is extremely rare. See the CALLING entries in the [test-ignore file](https://github.com/fullcalendar/temporal/blob/main/packages/temporal-polyfill/scripts/test-config/expected-failures.txt).
+- There are believed to be 3 bugs in the Temporal spec itself, one of which [has been filed](https://github.com/tc39/proposal-temporal/issues/2742). See SPEC-BUG entries in the [test-ignore file](https://github.com/fullcalendar/temporal/blob/main/packages/temporal-polyfill/scripts/test-config/expected-failures.txt).
+- Canonicalization of time zone IDs is simplified, leveraging the built-in `Intl` API.
+- `Intl.DateTimeFormat` has not been polyfilled to accept number-offset values for the `timeZone` option.
+- Method descriptors and `Function::length` are not strictly compliant due to ES-related space-saving techniques.
+
+The [Official ECMAScript Conformance Test Suite](https://github.com/tc39/test262) has:
+
+- 6811 *total* Temporal-related test files
+- 6138 *passed* by `temporal-polyfill`
+- 495 *ignored* due to superficial method descriptor compliance
+- 178 *ignored* due to other aforementioned intentional deviations
+
+
+## Browser Support
+
+<table>
+  <tr>
+    <td colspan='6'>
+      <strong>Minimum required browsers:</strong>
+    </td>
+  </tr>
+  <tr>
+    <!-- Computed from Libraries+Syntax in worksheet below  -->
+    <td>Chrome 60<br />(Jul 2017)</td>
+    <td>Firefox 55<br />(Aug 2017)</td>
+    <td>Safari 11.1<br />(Mar 2018)</td>
+    <td>Safari iOS 11.3<br />(Mar 2018)</td>
+    <td>Edge 79<br />(Jan 2020)</td>
+    <td>Node.js 14<br />(Apr 2020)</td>
+  </tr>
+  <tr>
+    <td colspan='6'>
+      <br />
+      <strong>If you transpile, you can support older browsers down to:</strong>
+    </td>
+  </tr>
+  <tr>
+    <!-- Computed from Libraries in worksheet below  -->
+    <td>Chrome 57<br />(Mar 2017)</td>
+    <td>Firefox 52<br />(Mar 2017)</td>
+    <td>Safari 10<br />(Sep 2016)</td>
+    <td>Safari iOS 10<br />(Sep 2016)</td>
+    <td>Edge 15<br />(Apr 2017)</td>
+    <td>Node.js 14<br />(Apr 2020)</td>
+  </tr>
+</table>
+
+<!--
+## Browser Support Worksheet
+
+Use caniuse's star feature to find intersection of features.
+
+Libraries:
+- [Intl.DateTimeFormat IANA time zone names](https://caniuse.com/mdn-javascript_builtins_intl_datetimeformat_datetimeformat_options_parameter_options_timezone_parameter_iana_time_zones)
+- [Number.isInteger](https://caniuse.com/mdn-javascript_builtins_number_isinteger)
+- [String::padStart](https://caniuse.com/mdn-javascript_builtins_string_padstart)
+- [WeakMap](https://caniuse.com/mdn-javascript_builtins_weakmap)
+
+Syntax:
+- [Classes](https://caniuse.com/es6-class)
+- [Exponentiation](https://caniuse.com/mdn-javascript_operators_exponentiation)
+- [Spread in array literals](https://caniuse.com/mdn-javascript_operators_spread_spread_in_arrays)
+- [Spread in function calls](https://caniuse.com/mdn-javascript_operators_spread_spread_in_function_calls)
+- [Spread in object literals](https://caniuse.com/mdn-javascript_operators_spread_spread_in_object_literals)
+
+BigInt (https://caniuse.com/bigint):
+- Chrome 67 (May 2018)
+- Firefox 68 (Jul 2019)
+- Safari 14 (Sep 2020)
+- Safari iOS 14 (Sep 2020)
+- Edge 79 (Jan 2020)
+
+Node.js is always 14 because the test-runner doesn't work with lower
+-->
+
+
+## BigInt Considerations
+
+This polyfill works fine in environments that do not support [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt).
+
+However, to use methods that accept/emit them, your browser [must support BigInt](https://caniuse.com/bigint).
+
+Here's how to sidestep this browser compatibility issue:
+
+<table>
+  <tr>
+    <th>❌ Avoid microseconds/nanoseconds</th>
+    <th>✅ Use milliseconds instead</th>
+  </tr>
+  <tr>
+    <td><code>instant.epochMicroseconds</code></td>
+    <td><code>instant.epochMilliseconds</code></td>
+  </tr>
+  <tr>
+    <td><code>instant.epochNanoseconds</code></td>
+    <td><code>instant.epochMilliseconds</code></td>
+  </tr>
+  <tr>
+    <td><code>Temporal.Instant.fromEpochMicroseconds(micro)</code></td>
+    <td><code>Temporal.Instant.fromEpochMilliseconds(milli)</code></td>
+  </tr>
+  <tr>
+    <td><code>Temporal.Instant.fromEpochNanoseconds(nano)</code></td>
+    <td><code>Temporal.Instant.fromEpochMilliseconds(milli)</code></td>
+  </tr>
+  <tr>
+    <td><code>new Temporal.Instant(nano)</code></td>
+    <td><code>Temporal.Instant.fromEpochMilliseconds(milli)</code></td>
+  </tr>
+  <tr>
+    <td><code>zonedDateTime.epochMicroseconds</code></td>
+    <td><code>zonedDateTime.epochMilliseconds</code></td>
+  </tr>
+  <tr>
+    <td><code>zonedDateTime.epochNanoseconds</code></td>
+    <td><code>zonedDateTime.epochMilliseconds</code></td>
+  </tr>
+  <tr>
+    <td>
+      <code>new Temporal.ZonedDateTime(nano, tz, cal)</code>
+    </td>
+    <td>
+      <code>Temporal.Instant.fromEpochMilliseconds(milli)</code><br />
+      <code>&nbsp;&nbsp;.toZonedDateTimeISO() // or toZonedDateTime</code>
+    </td>
+</table>
+
+
+## Tree-shakeable API
+
+🚧 Coming Soon
+
+For library authors and other devs who are hyper-concerned about bundle size, `temporal-polyfill` will be providing an alternate API designed for tree-shaking.
+
 ```js
-import { Temporal } from 'temporal-polyfill/impl'
+import * as ZonedDateTime from 'temporal-polyfill/fns/zoneddatetime'
 
-console.log(Temporal.Now.zonedDateTimeISO().toString())
+const zdt = ZonedDateTime.from({ year: 2024, month: 1, day: 1 })
+const s = ZonedDateTime.toString(zdt) // not how you normally call a method!
 ```
-
-
-[Temporal]: https://github.com/tc39/proposal-temporal
-[BigInt]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt
-[JSBI-why]: https://github.com/GoogleChromeLabs/jsbi#why

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Dev dependency count

0

decreased by-100%

Lines of code

10876

increased by37.44%

Number of lines in readme file

275

increased by266.67%

Worsened metrics

Total package byte prevSize

556185

decreased by-23.39%

Number of package files

15

decreased by-87.5%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Addedtemporal-spec@0.2.4(transitive)

• - Removedtemporal-spec@0.1.0(transitive)

• Updatedtemporal-spec@^0.2.0