-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathindex.html
More file actions
151 lines (149 loc) · 13.7 KB
/
index.html
File metadata and controls
151 lines (149 loc) · 13.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@WebReflection">
<meta name="twitter:creator" content="@WebReflection">
<meta property="og:url" content="https://ungap.github.io">
<meta property="og:title" content="ungap">
<meta property="og:description" content="Modern Web Development One Jump At The Time">
<meta property="og:image" content="https://ungap.github.io/img/denny-luan-crop.jpg">
<meta property="og:image:alt" content="even a lizard can jump a gap">
<title>ungap</title>
<!--[if lt IE 9]>
<script src="https://unpkg.com/ie8"></script>
<script defer src="https://unpkg.com/dom4"></script>
<![endif]-->
<script defer src="js/index.js"></script>
<link rel="styleSheet" href="css/index.css">
<link rel="stylesheet"
href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.13.1/styles/default.min.css">
</head>
<body>
<h1 id="ungap">ungap</h1>
<p>Modern Web development one jump at the time</p>
<p><img src="img/denny-luan-crop.jpg" alt="jumping the gap" />
<sup><strong>Photo by <a href="https://unsplash.com/photos/ovm_b91yEgY?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Denny Luan</a> on <a href="https://unsplash.com/search/photos/gap-landscape?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a></strong></sup></p>
<h2 id="about">About</h2>
<p>The <a href="https://github.com/ungap">ungap project</a> was born after <a href="https://github.com/WebReflection/es6-collections">years</a> of <a href="https://github.com/WebReflection/poorlyfills">attempts</a> to always fix <a href="https://www.npmjs.com/search?q=weakmap">the</a> <a href="https://www.npmjs.com/search?q=weakset">same</a> <a href="https://www.npmjs.com/search?q=ES%20Map">issue</a>, but never in a modular way and, most importantly, never in a single, 100% code covered, <strong>organization</strong>.</p>
<h3 id="focusedonsizecompatibilityandquality">Focused on size, compatibility, and quality</h3>
<p>Each module is written in ES5 compatible syntax to avoid both unnecessary transpilers bloat and potentially unexpected behaviors.
Each module is also 100% code-covered through tests able to verify the whole API both as native and polyfilled version.
The constrains per module are the following:</p>
<ul>
<li>CommonJS, ESM, Worker, and Web compatibility.</li>
<li>easy to read and maintain ES5 syntax, keeping the code size in mind.</li>
<li>mandatory 100% code coverage through all possible NodeJS hacks to ensure every part of the code that has a meaning works as expected (some meaningless part can be skipped but functionalities must be ensured).</li>
<li>every module is stand-alone, allowing incremental patch or polyfilling.</li>
<li>modules should be bundlers and transpilers resistant to avoid any possible, production code, surprise <sup><sub>[1]</sub></sup>.</li>
</ul>
<p><sup><sub>[1]</sub></sup> <sup><sub>as example: <a href="https://twitter.com/WebReflection/status/1065665486233448449">stripped out features detections</a></sub></sup></p>
<h4 id="pragmaticisbetterthansubsupimsupsubperfect"><strong>⚠</strong> Pragmatic is better than <sub><sup>(im)</sup></sub>perfect</h4>
<p>There are parts of the specifications that are very hard, if not impossible, to polyfill.
The main purpose of this project is to help developers move forward, and possibly without unnecessary bloat.
This basically means that polyfills are written to support 99% of the use cases, without granting 100% spec compliance.</p>
<p>If you need that, which again is basically impossible in most of the cases, feel free to keep using whatever monolithic polyfill or approach you were using before.</p>
<h2 id="howtouseamodule">How to use a module</h2>
<p>Every single module is made available as ESM, through the <code>package.json</code>'s <code>module</code> field, CJS via <code>package.json</code>'s <code>main</code> field, and browser script polyfill / patch via <code>package.json</code>'s <code>unpkg</code> field so that you can use directly the <a href="https://unpkg.com/#/">unpkg CDN</a>.</p>
<pre><code class="js language-js">// as ECMAScript module
import WeakSet from '@ungap/weakset';
// as CommonJS module
const WeakSet = require('@ungap/weakset');
// as Browser global patch
<script src="https://unpkg.com/@ungap/weakset"></script>
</code></pre>
<h2 id="essentialpolyfills">Essential polyfills</h2>
<p>Essentials modules covers most common use cases without going full bloated API.
As example, the <a href="https://unpkg.com/@ungap/essential-map">essential-map</a> exposes only <code>get</code>, <code>set</code>, <code>delete</code>, and <code>has</code> which is most of the time everything one needs, as opposite of going full <a href="https://unpkg.com/@ungap/map">map</a>.
The main benefit of the essential modules is their size, simplicity, or even performance.</p>
<ul>
<li><a href="https://github.com/ungap/essential-map">@ungap/essential-map</a> with only common method.</li>
<li><a href="https://github.com/ungap/essential-set">@ungap/essential-set</a> with only common method.</li>
<li><a href="https://github.com/ungap/essential-symbol">@ungap/essential-symbol</a> providing just its uniqueness.</li>
<li><a href="https://github.com/ungap/essential-weakset">@ungap/essential-weakset</a> with simpler logic but widely compatible.</li>
</ul>
<h2 id="regularpolyfills">Regular polyfills</h2>
<ul>
<li><a href="https://github.com/ungap/assign">@ungap/assign</a> compatible with all JS engines</li>
<li><a href="https://github.com/ungap/array-iterator">@ungap/array-iterator</a> compatible with all engines that have a global <code>Symbol</code>.</li>
<li><a href="https://github.com/ungap/bytes">@ungap/bytes</a> compatible with engines that provide <code>Blob</code>, <code>Request</code> and <code>Response</code> classes.</li>
<li><a href="https://github.com/ungap/compression-stream">@ungap/compression-stream</a> compatible with modern engines only and mostly targeting <em>Bun</em>.</li>
<li><a href="https://github.com/ungap/custom-elements">@ungap/custom-elements</a> compatible with IE 11 and many other browsers.</li>
<li><a href="https://github.com/ungap/custom-event">@ungap/custom-event</a> compatible with all browsers.</li>
<li><a href="https://github.com/ungap/dom-iterable">@ungap/dom-iterable</a> compatible with all engines that have a global <code>Symbol</code>.</li>
<li><a href="https://github.com/ungap/element-matches">@ungap/element-matches</a> compatible with all JS engines with a DOM env.</li>
<li><a href="https://github.com/ungap/event">@ungap/event</a> with double fallback through <code>CustomEvent</code>.</li>
<li><a href="https://github.com/ungap/event-target">@ungap/event-target</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/from-entries">@ungap/from-entries</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/get-own-property-descriptors">@ungap/get-own-property-descriptors</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/global-this">@ungap/global-this</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/has-own">@ungap/has-own</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/import-node">@ungap/import-node</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/insert-after">@ungap/insert-after</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/is-array">@ungap/is-array</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/is-connected">@ungap/is-connected</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/item">@ungap/item</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/json">@ungap/json</a> fixes <code>\u2028|9</code> in all JS engines with a <code>JSON</code> global.</li>
<li><a href="https://github.com/ungap/map">@ungap/map</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/new">@ungap/new</a> an extension to allow <code>Class.new(...args)</code> instead of <code>new Class(...args)</code></li>
<li><a href="https://github.com/ungap/node-contains">@ungap/node-contains</a> <code>Element.contains</code> compatible with all JS engines with a DOM env.</li>
<li><a href="https://github.com/ungap/once">@ungap/once</a> <code>Function.prototype.once</code> compatible with modern JS engines.</li>
<li><a href="https://github.com/ungap/own-keys">@ungap/own-keys</a> <code>Reflect.ownKeys</code> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/promise-any">@ungap/promise-any</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/promise-all-settled">@ungap/promise-all-settled</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/queue-microtask">@ungap/queue-microtask</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/random-uuid">@ungap/random-uuid</a> compatible with IE11+ and NodeJS.</li>
<li><a href="https://github.com/ungap/raw-json">@ungap/raw-json</a> compatible with modern engines only.</li>
<li><a href="https://github.com/ungap/remove">@ungap/remove</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/set">@ungap/set</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/set-methods">@ungap/set-methods</a> compatible with ES2015 engines.</li>
<li><a href="https://github.com/ungap/structured-clone">@ungap/structured-clone</a> compatible with ES2015+ engines only.</li>
<li><a href="https://github.com/ungap/template-literal">@ungap/template-literal</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/template-tag-arguments">@ungap/template-tag-arguments</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/trim">@ungap/trim</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/trim-start">@ungap/trim-start</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/trim-end">@ungap/trim-end</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/url-search-params">@ungap/url-search-params</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/weakmap">@ungap/weakmap</a> compatible with all JS engines.</li>
<li><a href="https://github.com/ungap/weakrefs">@ungap/weakrefs</a> <code>WeakRef</code> and <code>FinalizationGroup</code> compatible with any engine that already has a <code>WeakMap</code> (i.e. <em>IE11+</em>).</li>
<li><a href="https://github.com/ungap/weakset">@ungap/weakset</a> compatible with any engine that already has a <code>WeakMap</code> (i.e. <em>IE11+</em>).</li>
<li><a href="https://github.com/ungap/with-resolvers">@ungap/with-resolvers</a> compatible with all JS engines.</li>
</ul>
<h2 id="polyfilledutilities">Polyfilled utilities</h2>
<p>Ungap utilities are meant to simplify cross browser development without the bloat of a whole polyfill.</p>
<ul>
<li><a href="https://github.com/ungap/create-content">@ungap/create-content</a> compatible with all JS engines <sup><sub>(backend via basichtml or others)</sub></sup>.</li>
<li><a href="https://github.com/ungap/custom-elements-new#readme">@ungap/custom-elements-new</a> to use <code>CustomElement.new()</code> instead of <code>new CustomElement()</code> due WebKit/Safari built-in extends caveat.</li>
</ul>
<h2 id="pluginstoremoveunnecessarybloat">Plugins to remove unnecessary bloat</h2>
<p>If you are targeting modern browsers only, you might want to exclude some unnecessary code from various ungapped APIs.</p>
<p>Following a list of plugins which aim is to address those cases:</p>
<ul>
<li><a href="https://github.com/cfware/babel-plugin-remove-ungap">babel-plugin-remove-ungap</a> provides the ability to arbitrarily exclude polyfills through tree-shaking, an awesome tool from <a href="https://github.com/coreyfarrell">coreyfarrell</a> ♥</li>
<li><a href="https://github.com/ungap/degap#ungapdegap">@ungap/degap</a> to make any module either a no-op, just the native version, or the simplified utility (as in element-matches case).</li>
</ul>
<h2 id="license">License</h2>
<p>Each module is under the <a href="https://www.npmjs.com">npm</a> default <a href="https://opensource.org/licenses/ISC">ISC</a> license.</p>
<h2 id="howtocontribute">How to contribute</h2>
<p>You are welcome to join the organization after your first module is published.</p>
<p>In order to do so, please take any already available module as example of how to create and test any code you need.</p>
<p>The main guideline though, can be summarized as such:</p>
<ul>
<li>the entry point is the root <code>./index.js</code>.</li>
<li>the ESM module is generated in <code>./esm/index.js</code>.</li>
<li>the CJS module is generated in <code>./cjs/index.js</code>.</li>
<li>you cannot use any transpiler.</li>
<li>you might use some bundler as long as the tested code is the one generated by such bundler.</li>
</ul>
<p>I have personally no interest in enforcing any specific linting rule or code style, as long as common sense and good practices are part of the code.</p>
<p>If these basic constrains are good enough for you, please do help this project grow, allowing the community to leave all monolithic polyfills part of the past.</p>
<p>If you have further questions, you can DM me <a href="https://twitter.com/WebReflection">@webreflection</a> <sup><sub>[1]</sub></sup></p>
<p><sup><sub>[1]</sub></sup> <sup><sub>my DMs are open</sub></sup></p>
<hr />
<script onload="hljs.initHighlightingOnLoad()"
src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.13.1/highlight.min.js"></script>
</body>
</html>