From e40bb354373ee50d1c19a082f6ab2aac48843a24 Mon Sep 17 00:00:00 2001 From: Adam Jeniski Date: Tue, 20 Jan 2026 23:07:17 -0500 Subject: [PATCH] init --- jquery-4.0.0-documentation.md | 870 ++++++++++++++++++++++++++++++++++ 1 file changed, 870 insertions(+) create mode 100644 jquery-4.0.0-documentation.md diff --git a/jquery-4.0.0-documentation.md b/jquery-4.0.0-documentation.md new file mode 100644 index 0000000..6df716d --- /dev/null +++ b/jquery-4.0.0-documentation.md @@ -0,0 +1,870 @@ +# jQuery 4.0.0 Documentation + +**Release Date:** January 17, 2026 +**License:** MIT +**20th Anniversary Release** + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [Installation](#installation) +3. [Browser Support](#browser-support) +4. [Breaking Changes](#breaking-changes) +5. [New Features](#new-features) +6. [Migration Guide](#migration-guide) +7. [API Reference](#api-reference) + +--- + +## Overview + +jQuery 4.0.0 marks a significant milestone—celebrating jQuery's 20th anniversary and the first major version release in nearly 10 years. This release modernizes the library by removing legacy browser support, adopting ES modules, and improving security features. + +### Key Highlights + +- **Modernized codebase** migrated from AMD to ES modules +- **Smaller bundle size** with improved slim build +- **Enhanced security** with Trusted Types and CSP support +- **Removed deprecated APIs** in favor of native JavaScript equivalents +- **Updated browser support** dropping legacy browsers + +--- + +## Installation + +### CDN + +```html + + + + + +``` + +### npm + +```bash +npm install jquery@4.0.0 +``` + +### ES Module Import + +```javascript +// Full import +import $ from 'jquery'; + +// Named import +import { jQuery } from 'jquery'; +``` + +### CommonJS + +```javascript +const $ = require('jquery'); +``` + +--- + +## Browser Support + +### Supported Browsers + +| Browser | Minimum Version | +|---------|-----------------| +| Chrome | Last 3 versions | +| Firefox | Last 2 versions + ESR | +| Safari | Last 3 versions | +| Edge (Chromium) | Last 3 versions | +| iOS Safari | Last 3 versions | +| Android Chrome | Last 3 versions | + +### Removed Support + +The following browsers are **no longer supported**: + +- Internet Explorer 10 and earlier (IE 11 support planned for removal in jQuery 5.0) +- Edge Legacy (non-Chromium) +- iOS versions older than the last 3 +- Firefox versions older than the last 2 (except ESR) +- Android Browser (AOSP) + +--- + +## Breaking Changes + +### 1. Removed Deprecated Utility Functions + +Several utility functions deprecated in previous versions have been removed. Use native JavaScript equivalents instead. + +| Removed Function | Native Replacement | +|------------------|-------------------| +| `jQuery.isArray()` | `Array.isArray()` | +| `jQuery.parseJSON()` | `JSON.parse()` | +| `jQuery.trim()` | `String.prototype.trim()` | +| `jQuery.type()` | `typeof` / `instanceof` | +| `jQuery.now()` | `Date.now()` | +| `jQuery.isNumeric()` | `!isNaN(parseFloat(n)) && isFinite(n)` | +| `jQuery.isFunction()` | `typeof fn === 'function'` | +| `jQuery.isWindow()` | `obj != null && obj === obj.window` | + +#### Example Migration + +```javascript +// jQuery 3.x (deprecated) +if ($.isArray(myVar)) { /* ... */ } +if ($.isFunction(callback)) { /* ... */ } +var trimmed = $.trim(userInput); +var data = $.parseJSON(jsonString); +var timestamp = $.now(); + +// jQuery 4.0 (use native) +if (Array.isArray(myVar)) { /* ... */ } +if (typeof callback === 'function') { /* ... */ } +var trimmed = userInput.trim(); +var data = JSON.parse(jsonString); +var timestamp = Date.now(); +``` + +### 2. Focus Event Order Change + +The focus-related event order now follows the W3C specification. + +```javascript +// jQuery 3.x order: +// focusout → blur → focusin → focus + +// jQuery 4.0 order (W3C compliant): +// blur → focusout → focus → focusin +``` + +#### Example: Observing Event Order + +```javascript +const $input = $('#myInput'); + +$input.on('blur', () => console.log('1. blur')); +$input.on('focusout', () => console.log('2. focusout')); +$input.on('focus', () => console.log('3. focus')); +$input.on('focusin', () => console.log('4. focusin')); + +// When focus moves from #myInput to another element: +// Output in jQuery 4.0: +// 1. blur +// 2. focusout +// Then when new element receives focus: +// 3. focus +// 4. focusin +``` + +### 3. Removed Array Methods from jQuery Prototype + +The `push`, `sort`, and `splice` methods have been removed from the jQuery prototype. + +```javascript +// jQuery 3.x +$elements.push(newElement); +$elements.sort(compareFn); +$elements.splice(0, 1); + +// jQuery 4.0 +[].push.call($elements, newElement); +[].sort.call($elements, compareFn); +[].splice.call($elements, 0, 1); + +// Or convert to array first +const elemArray = $elements.toArray(); +elemArray.push(newElement); +``` + +--- + +## New Features + +### 1. ES Module Support + +jQuery 4.0 source has been migrated from AMD to ES modules, enabling better integration with modern build tools. + +#### Using with Modern Bundlers + +```javascript +// Rollup, Webpack, Vite, etc. +import $ from 'jquery'; + +$(document).ready(() => { + console.log('jQuery 4.0 with ES modules!'); +}); +``` + +#### Dynamic Import + +```javascript +// Lazy load jQuery when needed +async function initializeUI() { + const { default: $ } = await import('jquery'); + + $('.dynamic-content').fadeIn(); +} +``` + +### 2. Trusted Types Support + +jQuery 4.0 adds support for Trusted Types, enhancing security in environments with strict Content Security Policies. + +```javascript +// jQuery now accepts TrustedHTML objects +const policy = trustedTypes.createPolicy('myPolicy', { + createHTML: (string) => DOMPurify.sanitize(string) +}); + +const trustedContent = policy.createHTML('

Safe content

'); +$('#container').html(trustedContent); +``` + +### 3. Improved CSP Compatibility + +Async script requests now use ` + + + +``` + +**Slim build excludes:** +- Ajax module +- Effects/animation module +- Deferreds +- Callbacks + +--- + +## Migration Guide + +### Using jQuery Migrate Plugin + +For gradual migration, use the jQuery Migrate plugin to identify deprecated features: + +```html + + +``` + +The Migrate plugin will log warnings to the console for deprecated usage. + +### Step-by-Step Migration + +#### Step 1: Update Utility Function Calls + +```javascript +// Before (jQuery 3.x) +function processData(data) { + if ($.isArray(data)) { + return data.map(item => $.trim(item)); + } + return $.trim(data); +} + +// After (jQuery 4.0) +function processData(data) { + if (Array.isArray(data)) { + return data.map(item => item.trim()); + } + return data.trim(); +} +``` + +#### Step 2: Update Type Checking + +```javascript +// Before (jQuery 3.x) +function handleCallback(callback) { + if ($.isFunction(callback)) { + callback(); + } +} + +function getType(value) { + return $.type(value); // "array", "date", "regexp", etc. +} + +// After (jQuery 4.0) +function handleCallback(callback) { + if (typeof callback === 'function') { + callback(); + } +} + +function getType(value) { + if (Array.isArray(value)) return 'array'; + if (value instanceof Date) return 'date'; + if (value instanceof RegExp) return 'regexp'; + return typeof value; +} +``` + +#### Step 3: Handle Focus Event Order Changes + +```javascript +// If your code depends on specific event order, update accordingly +$('#form-field').on('focusout', function() { + // In jQuery 4.0, blur fires BEFORE focusout + // Adjust validation logic if needed + validateField(this); +}); +``` + +#### Step 4: Update Array Method Usage + +```javascript +// Before (jQuery 3.x) +const $items = $('.item'); +$items.push(document.createElement('div')); + +// After (jQuery 4.0) - Option 1: Use native call +const $items = $('.item'); +[].push.call($items, document.createElement('div')); + +// After (jQuery 4.0) - Option 2: Use .add() +const $items = $('.item').add(document.createElement('div')); +``` + +--- + +## API Reference + +### Core Functions + +#### `jQuery(selector [, context])` + +Select elements from the DOM. + +```javascript +// Select by ID +const $header = $('#header'); + +// Select by class +const $buttons = $('.btn'); + +// Select by tag +const $paragraphs = $('p'); + +// Select with context +const $items = $('.item', '#container'); + +// Create elements +const $newDiv = $('
Content
'); +``` + +#### `jQuery.noConflict([removeAll])` + +Relinquish jQuery's control of the `$` variable. + +```javascript +const jq = $.noConflict(); +jq('#element').addClass('active'); + +// With removeAll=true, also removes 'jQuery' global +const jq = jQuery.noConflict(true); +``` + +### Utilities + +#### `jQuery.extend([deep], target, object1 [, objectN])` + +Merge objects into the target object. + +```javascript +// Shallow merge +const defaults = { color: 'blue', size: 'medium' }; +const options = { color: 'red' }; +const settings = $.extend({}, defaults, options); +// Result: { color: 'red', size: 'medium' } + +// Deep merge +const obj1 = { a: { b: 1, c: 2 } }; +const obj2 = { a: { b: 3 } }; +const result = $.extend(true, {}, obj1, obj2); +// Result: { a: { b: 3, c: 2 } } +``` + +#### `jQuery.each(collection, callback)` + +Iterate over arrays or objects. + +```javascript +// Array iteration +$.each(['a', 'b', 'c'], function(index, value) { + console.log(`${index}: ${value}`); +}); + +// Object iteration +$.each({ name: 'John', age: 30 }, function(key, value) { + console.log(`${key}: ${value}`); +}); + +// Return false to break the loop +$.each([1, 2, 3, 4, 5], function(i, num) { + if (num > 3) return false; + console.log(num); +}); +// Output: 1, 2, 3 +``` + +#### `jQuery.map(array, callback)` + +Transform array elements. + +```javascript +const numbers = [1, 2, 3, 4]; +const doubled = $.map(numbers, n => n * 2); +// Result: [2, 4, 6, 8] + +// Can return multiple values +const expanded = $.map([1, 2], n => [n, n * 2]); +// Result: [1, 2, 2, 4] + +// Return null to remove item +const filtered = $.map([1, 2, 3, 4], n => n > 2 ? n : null); +// Result: [3, 4] +``` + +#### `jQuery.grep(array, function [, invert])` + +Filter array elements. + +```javascript +const numbers = [1, 2, 3, 4, 5, 6]; + +// Keep elements where callback returns true +const evens = $.grep(numbers, n => n % 2 === 0); +// Result: [2, 4, 6] + +// With invert=true, keep elements where callback returns false +const odds = $.grep(numbers, n => n % 2 === 0, true); +// Result: [1, 3, 5] +``` + +#### `jQuery.merge(first, second)` + +Merge two arrays. + +```javascript +const arr1 = [1, 2]; +const arr2 = [3, 4]; +$.merge(arr1, arr2); +// arr1 is now [1, 2, 3, 4] + +// Works with array-like objects +const $divs = $('div'); +const $spans = $('span'); +$.merge($divs, $spans); +``` + +#### `jQuery.inArray(value, array [, fromIndex])` + +Find value index in array. + +```javascript +const arr = ['a', 'b', 'c', 'd']; + +$.inArray('b', arr); // Returns: 1 +$.inArray('x', arr); // Returns: -1 +$.inArray('b', arr, 2); // Returns: -1 (starts search at index 2) +``` + +#### `jQuery.isPlainObject(obj)` + +Check if value is a plain object. + +```javascript +$.isPlainObject({}); // true +$.isPlainObject({ a: 1 }); // true +$.isPlainObject(new Object()); // true + +$.isPlainObject([]); // false +$.isPlainObject(document.body); // false +$.isPlainObject(new Date()); // false +``` + +#### `jQuery.isEmptyObject(obj)` + +Check if object has no properties. + +```javascript +$.isEmptyObject({}); // true +$.isEmptyObject({ a: 1 }); // false +$.isEmptyObject([]); // true (arrays are objects) +``` + +### Callbacks Object + +#### `jQuery.Callbacks(flags)` + +Create a callback list with optional flags. + +**Flags:** +- `once`: Callbacks fire only once +- `memory`: Remember previous values and call new callbacks immediately +- `unique`: Prevent duplicate callbacks +- `stopOnFalse`: Stop firing when a callback returns false + +```javascript +// Basic usage +const callbacks = $.Callbacks(); + +function fn1(value) { + console.log('fn1:', value); +} + +function fn2(value) { + console.log('fn2:', value); +} + +callbacks.add(fn1); +callbacks.add(fn2); +callbacks.fire('hello'); +// Output: +// fn1: hello +// fn2: hello + +// With flags +const onceCallbacks = $.Callbacks('once'); +onceCallbacks.add(fn1); +onceCallbacks.fire('first'); // fn1: first +onceCallbacks.fire('second'); // (nothing - already fired) + +// Memory flag - useful for ready-like patterns +const memoryCallbacks = $.Callbacks('memory'); +memoryCallbacks.fire('done'); +memoryCallbacks.add(fn1); // Immediately called with 'done' +``` + +### Deferred Object + +#### `jQuery.Deferred([beforeStart])` + +Create a Deferred object for async operations. + +```javascript +function asyncOperation() { + const deferred = $.Deferred(); + + setTimeout(() => { + const success = Math.random() > 0.5; + + if (success) { + deferred.resolve('Operation succeeded'); + } else { + deferred.reject('Operation failed'); + } + }, 1000); + + return deferred.promise(); +} + +asyncOperation() + .done(result => console.log(result)) + .fail(error => console.error(error)) + .always(() => console.log('Complete')); +``` + +#### `jQuery.when(deferreds)` + +Execute callback when all Deferreds resolve. + +```javascript +function fetchUser() { + return $.ajax('/api/user'); +} + +function fetchPosts() { + return $.ajax('/api/posts'); +} + +$.when(fetchUser(), fetchPosts()) + .done((userData, postsData) => { + console.log('User:', userData[0]); + console.log('Posts:', postsData[0]); + }) + .fail(() => { + console.error('One or more requests failed'); + }); +``` + +### DOM Ready + +#### `jQuery(callback)` / `jQuery.ready` + +Execute code when DOM is ready. + +```javascript +// Shorthand (recommended) +$(function() { + console.log('DOM ready'); +}); + +// Explicit ready +$(document).ready(function() { + console.log('DOM ready'); +}); + +// Arrow function +$(() => { + console.log('DOM ready'); +}); + +// Multiple ready handlers are executed in order +$(() => console.log('First')); +$(() => console.log('Second')); +``` + +### Data Storage + +#### `.data(key, value)` / `.data(key)` / `.data()` + +Store and retrieve data associated with elements. + +```javascript +// Set data +$('#element').data('userId', 123); +$('#element').data('config', { theme: 'dark', lang: 'en' }); + +// Get data +const userId = $('#element').data('userId'); // 123 +const config = $('#element').data('config'); // { theme: 'dark', lang: 'en' } + +// Get all data +const allData = $('#element').data(); +// { userId: 123, config: { theme: 'dark', lang: 'en' } } + +// HTML5 data attributes are auto-loaded +//
+$('#user').data('userId'); // 456 +$('#user').data('role'); // 'admin' +``` + +#### `.removeData(key)` + +Remove stored data. + +```javascript +$('#element').data('temp', 'value'); +$('#element').removeData('temp'); + +// Remove all data +$('#element').removeData(); +``` + +### Traversal + +#### `.find(selector)` + +Find descendant elements. + +```javascript +// Find all paragraphs inside #content +$('#content').find('p').addClass('styled'); + +// Chained traversal +$('#nav') + .find('li') + .find('a') + .addClass('nav-link'); +``` + +#### `.filter(selector)` / `.filter(function)` + +Reduce matched elements. + +```javascript +// Filter by selector +$('li').filter('.active').css('font-weight', 'bold'); + +// Filter by function +$('input').filter(function() { + return $(this).val().length > 0; +}).addClass('has-value'); + +// Filter with index +$('tr').filter(':even').addClass('striped'); +``` + +#### `.closest(selector)` + +Find closest ancestor matching selector. + +```javascript +// Find parent form +$('input').on('blur', function() { + const $form = $(this).closest('form'); + validateForm($form); +}); + +// With context +$('.item').closest('.container', '#wrapper'); +``` + +#### `.has(selector)` + +Filter elements that have matching descendants. + +```javascript +// Only select divs that contain a span +$('div').has('span').addClass('has-span'); + +// Select list items with links +$('li').has('a').css('background', '#f0f0f0'); +``` + +#### `.index([selector | element])` + +Get element index. + +```javascript +// Index among siblings +$('li.active').index(); // Position among siblings + +// Index in jQuery collection +const $items = $('li'); +$items.index($('.active')); // Position in collection + +// With selector +$('li').index('li.active'); // Find index of .active among all li +``` + +#### `.add(selector)` + +Add elements to the matched set. + +```javascript +// Combine selections +$('p') + .add('span') + .add('div.highlight') + .addClass('styled'); + +// Add newly created element +$('.existing').add('

New paragraph

').appendTo('#container'); +``` + +#### `.addBack([selector])` + +Add previous set to current set. + +```javascript +// Select all children and the parent +$('#parent') + .find('> *') + .addBack() + .addClass('highlighted'); + +// With filter +$('ul') + .find('li') + .addBack('ul.main') + .css('border', '1px solid'); +``` + +### DOM Evaluation + +#### `jQuery.DOMEval(code, options)` + +Safely execute script code with nonce support (internal use, enhanced in 4.0). + +```javascript +// jQuery internally uses this for script execution +// Preserves nonce attributes for CSP compliance +// Handles type, src, nonce, and noModule attributes +``` + +--- + +## Security Features + +### Prototype Pollution Prevention + +jQuery 4.0 includes protection against prototype pollution attacks in `$.extend()`: + +```javascript +// These attempts are blocked +$.extend(true, {}, JSON.parse('{"__proto__": {"polluted": true}}')); +$.extend(true, {}, { constructor: { prototype: { polluted: true } } }); + +// Object.prototype remains unpolluted +console.log({}.polluted); // undefined +``` + +### XSS Mitigation + +The selector engine escapes special characters to prevent XSS: + +```javascript +// Safe selector escaping +const userInput = 'div">'; +const escaped = $.escapeSelector(userInput); +// Safely escaped for use in selectors +``` + +### CSP Compliance + +Script loading now complies with Content Security Policy: + +```javascript +// Scripts are loaded via